Dependency Doctor

Comprehensive dependency health analysis and upgrade planning.

Core Workflow Scan manifests: Analyze package.json, requirements.txt, Cargo.toml, go.mod, etc. Check versions: Identify outdated packages against latest stable versions Detect issues: Find duplicates, security vulnerabilities, deprecated packages, heavy bundles Assess risk: Evaluate breaking changes and version compatibility Prioritize: Rank issues by severity (security > performance > maintenance) Generate upgrade path: Create safe, incremental update plan Recommend pins: Suggest version constraints to avoid future issues Analysis Categories Security Issues (Critical) Known CVEs in dependencies Unmaintained packages (no updates >2 years) Packages with security advisories Transitive dependency vulnerabilities Outdated Packages (High) Major versions behind (breaking changes) Minor versions behind (new features) Patch versions behind (bug fixes) Duplicate Dependencies (Medium) Multiple versions of same package Overlapping functionality (lodash + underscore) Can be deduplicated Heavy Dependencies (Medium) Large bundle sizes (>500KB) Unnecessary peer dependencies Better alternatives available Risky Combinations (Medium) Known incompatible version pairs Conflicting peer dependencies Framework version mismatches Report Structure

Dependency Audit Report

🔴 Critical Security Issues (2)

• axios@0.21.0 → CVE-2021-3749 → Upgrade to 1.6.0+
• lodash@4.17.15 → Prototype pollution → Upgrade to 4.17.21+

🟡 High Priority Updates (5)

• react@17.0.2 → 18.2.0 (major, breaking changes)
• next@12.0.0 → 14.1.0 (major, new features)

🟢 Maintenance Updates (8)

• typescript@4.9.0 → 5.3.3 (patch improvements)

📦 Duplicates Found (3)

• moment: 2.29.1, 2.30.0 → Deduplicate to 2.30.0
• @types/node: 18.0.0, 20.0.0 → Align to 20.0.0

🏋️ Heavy Dependencies (2)

• moment (232KB) → Consider date-fns (12KB)
• lodash (full) → Consider lodash-es or specific imports

Upgrade Path

Phase 1: Security (Do First)

npm update axios lodash
npm audit fix

Phase 2: Major Frameworks (Test Thoroughly) npm install react@18 react-dom@18 npm install next@14

Run full test suite

Phase 3: Minor Updates (Low Risk) npm update

Safe Pin Recommendations { "axios": "^1.6.0", "react": "^18.2.0", "typescript": "~5.3.0" }

Package Manager Commands

npm

• Audit: npm audit
• Outdated: npm outdated
• Dedupe: npm dedupe
• Update: npm update [package]

yarn

• Audit: yarn audit
• Outdated: yarn outdated
• Dedupe: yarn dedupe
• Upgrade: yarn upgrade [package]

pnpm

• Audit: pnpm audit
• Outdated: pnpm outdated
• Dedupe: pnpm dedupe
• Update: pnpm update [package]

pip

• Outdated: pip list --outdated
• Update: pip install --upgrade [package]
• Security: pip-audit or safety check

Upgrade Best Practices

1. Backup first: Commit current state or create branch
2. Read changelogs: Check for breaking changes
3. Update incrementally: One major version at a time
4. Test thoroughly: Run full test suite after each update
5. Check peer deps: Ensure compatibility
6. Lock files: Commit updated lock files
7. Monitor: Watch for runtime issues after deployment

Version Pinning Strategy

• Exact: 1.2.3 - Only for problematic packages
• Patch: ~1.2.3 - Safe updates (1.2.x)
• Minor: ^1.2.3 - Most common (1.x.x)
• Range: >=1.2.3 <2.0.0 - Explicit bounds

References

See references/common-issues.md for known problematic package combinations and migration guides.