📦 Upgrade Impact Analyzer

Intelligent dependency upgrade risk analysis with AI-powered insights

Unlike traditional dependency checkers that just report version changes, Upgrade Impact Analyzer measures risk based on your actual code usage. It combines static code analysis, changelog intelligence, and semantic versioning to give you actionable insights.

🎯 Key Features

Feature	Description
Usage-Centric Scoring	Risk scored by actual code usage, not just version numbers
AI-Powered Analysis	LLM changelog summarization (OpenAI/Anthropic)
Conflict Detection	Detect incompatible upgrades before they break your code
Security Scanning	CVE detection via pip-audit and OSV.dev
Health Scoring	A-F grades based on maintenance, popularity, quality
SBOM Generation	CycloneDX 1.5 and SPDX 2.3 formats
License Auditing	Compliance checking with deny lists
Monorepo Support	Analyze multiple projects with shared deps
Custom Policies	Define risk thresholds per package
Multi-Format Output	Terminal, JSON, SARIF, JUnit XML, Markdown
CI/CD Integration	GitHub Actions, pre-commit hooks

📥 Installation

# Basic installation
pip install upgrade-impact-analyzer

# With security scanning support
pip install upgrade-impact-analyzer[security]

# With all optional features
pip install upgrade-impact-analyzer[all]

Available on PyPI

🚀 Quick Start

# Analyze your project (auto-detects files)
upgrade-analyzer analyze

# Check for conflicts before upgrading
upgrade-analyzer conflicts

# With security scanning
upgrade-analyzer analyze --security

# Generate SBOM
upgrade-analyzer sbom --output sbom.json

# Health scoring
upgrade-analyzer health

# AI-powered analysis (requires OPENAI_API_KEY)
upgrade-analyzer ai-analyze --package requests --from 2.28.0 --to 2.31.0

💡 Advanced Usage

🔍 Conflict Detection

Detect incompatible dependencies before upgrading (Forward, Reverse, and Cross-upgrade conflicts).

upgrade-analyzer conflicts                    # Check all upgrades
upgrade-analyzer conflicts --output conflicts.md  # Save report

🤖 AI-Powered Analysis

Get human-readable summaries of breaking changes using LLMs.

# Requires OPENAI_API_KEY or ANTHROPIC_API_KEY
export OPENAI_API_KEY="sk-..."

upgrade-analyzer ai-analyze \
  --package requests \
  --from 2.28.0 \
  --to 2.31.0

📊 Health Scoring & Licensing

# Show A-F grades for your dependencies
upgrade-analyzer health

# Audit licenses (pass --deny AGPL-3.0 to fail on specific licenses)
upgrade-analyzer licenses

🏢 Monorepo & Policies

# Analyze monorepo
upgrade-analyzer monorepo --root /path/to/monorepo

# Initialize custom policies
upgrade-analyzer init-policies

📊 Example Output

Terminal Output

📦 Dependency Upgrade Analysis
┏━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┓
┃ Package    ┃ Current ┃ Target ┃ Risk Score ┃ Severity ┃ Issues ┃
┡━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━┩
│ requests   │ 2.28.0  │ 3.0.0  │       85.0 │ 🔴 high  │      3 │
│ flask      │ 2.0.0   │ 3.0.0  │       45.0 │ 🟡 medium│      1 │
│ pytest     │ 7.0.0   │ 8.0.0  │       12.0 │ 🟢 low   │      0 │
└────────────┴─────────┴────────┴────────────┴──────────┴────────┘

Risk Breakdown

📦 requests: 2.28.0 → 3.0.0

┌─ Risk Assessment ────────────────────────────┐
│ 🔴 HIGH                                      │
│ Risk Score: 85.0/100                         │
└──────────────────────────────────────────────┘

Risk Factors:
  • SemVer Distance: [████████████████░░░░] 80.0 (weight: 30%)
  • Usage Impact: [████████████████████] 100.0 (weight: 50%)
    3 API changes affecting 5 usage points
  • Changelog Severity: [████████░░░░░░░░░░░░] 40.0 (weight: 20%)

⚠️  Breaking Changes:
  • requests.get
    Function 'requests.get' signature changed
    Affects 2 usage(s) across 1 file(s)

🔧 CI/CD Integration

GitHub Actions

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install analyzer
        run: pip install upgrade-impact-analyzer
      - name: Run analysis
        run: upgrade-analyzer analyze --format sarif --output results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

🏗️ Architecture

upgrade_analyzer/
├── analyzer.py          # Main orchestrator
├── cli.py               # Typer CLI commands
├── conflict_detector.py # Dependency conflict detection
├── health.py            # Health scoring (A-F)
├── sbom.py              # SBOM & license auditing
├── intelligence/        # Risk analysis
│   ├── api_differ.py   # API diffing (griffe)
│   ├── risk_scorer.py  # Risk calculation
│   ├── security.py     # CVE detection
│   └── llm_analyzer.py # AI analysis
└── scanner/             # Code analysis
    └── ast_analyzer.py  # AST-based usage detection

📄 License

MIT License - see LICENSE for details.