Analyze Dependencies

Overview

Audit the project's dependency tree across five risk dimensions: freshness, vulnerabilities, bundle impact, license compliance, and maintenance status. Produce a risk-scored report with actionable recommendations for each dependency.

Workflow

1. Read project context — Check .chalk/docs/engineering/ for:

   • Architecture docs (to understand which dependencies are critical path)
   • Previous dependency audits
   • Any documented dependency policies or license requirements

2. Locate dependency manifests — Scan the project for:

   • package.json / package-lock.json / yarn.lock / pnpm-lock.yaml (Node.js)
   • pyproject.toml / requirements.txt / Pipfile / poetry.lock (Python)
   • pubspec.yaml / pubspec.lock (Dart/Flutter)
   • Cargo.toml / Cargo.lock (Rust)
   • go.mod / go.sum (Go)
   • Gemfile / Gemfile.lock (Ruby)
   • pom.xml / build.gradle (Java/Kotlin)
   • If $ARGUMENTS specifies a file, focus on that manifest

3. Inventory dependencies — For each manifest, list:

   • Direct dependencies (production)
   • Direct dev dependencies
   • Note the declared version constraints (exact, range, caret, tilde)

4. Assess freshness — For each dependency:

   • Current installed version vs. latest available version
   • Run the appropriate command: npm outdated, pip list --outdated, pub outdated, etc.
   • Classify the gap:
     • Current: on latest or within one minor version
     • Stale: one or more minor versions behind
     • Outdated: one or more major versions behind
     • Abandoned: no release in 2+ years

5. Check for vulnerabilities — Run the appropriate audit command:

   • npm audit / yarn audit / pnpm audit
   • pip audit or safety check
   • cargo audit
   • bundle audit
   • Record: CVE ID, severity (critical/high/medium/low), affected version range, fix available (yes/no)
   • Check transitive dependencies, not just direct ones

6. Evaluate bundle impact — Where applicable:

   • For Node.js: check package size, number of transitive dependencies, tree-shakeability
   • For frontend projects: note if a large library is used for a small feature (e.g., lodash for one function)
   • Flag dependencies that pull in disproportionately large sub-dependency trees

7. Check license compliance — For each dependency:

   • Identify the license (MIT, Apache-2.0, GPL, LGPL, AGPL, BSD, ISC, etc.)
   • Flag copyleft licenses (GPL, AGPL, LGPL) that may have viral implications
   • Flag unlicensed or custom-licensed packages
   • Flag license changes between the installed version and latest version
   • Note: MIT, Apache-2.0, BSD, ISC are generally permissive and low risk

8. Assess maintenance status — For each dependency, check:

   • Last publish date
   • Open issues and PRs (especially security-related)
   • Number of maintainers (bus factor)
   • Whether the project is archived or deprecated
   • Classify: Active (regular releases, responsive maintainers), Maintained (occasional releases, issues addressed), Minimal (rare updates, issues pile up), Unmaintained (no activity in 12+ months)

9. Score each dependency — Assign a risk score based on all dimensions:

   • Low: Current, no vulnerabilities, permissive license, actively maintained
   • Medium: Stale or one minor concern (e.g., slightly outdated, minimal maintenance)
   • High: Outdated or multiple concerns (known vulnerability with fix available, copyleft license, large bundle impact)
   • Critical: Known exploitable vulnerability, abandoned with no alternative, or license violation

10. Generate recommendations — For each dependency with medium or higher risk:

    • Update: Newer version fixes the issue. Note any breaking changes.
    • Replace: Better-maintained alternative exists. Name the alternative.
    • Remove: Dependency is unused or its functionality can be inlined.
    • Monitor: Risk is acceptable for now but should be tracked.
    • Immediate Action: Critical vulnerability or license violation requiring urgent attention.

11. Determine the next file number — List files in .chalk/docs/engineering/ matching *_dependency_audit*. Find the highest number and increment by 1.

12. Write the report — Save to .chalk/docs/engineering/<n>_dependency_audit.md.

13. Confirm — Summarize: total dependencies analyzed, risk distribution, critical items requiring immediate attention.

Filename Convention

<number>_dependency_audit.md

Examples:

• 5_dependency_audit.md
• 9_dependency_audit.md

Dependency Audit Format

# Dependency Audit

Last updated: <YYYY-MM-DD>
Package manager: <npm / pip / pub / cargo / etc.>
Manifest: <path to manifest file>

## Summary

| Risk Level | Count | Action Required |
|------------|-------|-----------------|
| Critical | <n> | Immediate action |
| High | <n> | Plan remediation this sprint |
| Medium | <n> | Schedule for next maintenance window |
| Low | <n> | No action needed |
| **Total** | **<n>** | |

## Vulnerability Summary

| CVE | Severity | Package | Installed | Fixed In | Transitive? |
|-----|----------|---------|-----------|----------|-------------|
| CVE-XXXX-XXXXX | Critical | <name> | <version> | <version> | No |

## Critical & High Risk Dependencies

### <package-name> — CRITICAL

| Dimension | Status | Detail |
|-----------|--------|--------|
| Freshness | Outdated | Installed: 2.1.0, Latest: 4.0.0 |
| Vulnerabilities | CVE-XXXX-XXXXX (High) | RCE via crafted input |
| Bundle Impact | 450KB | Pulls in 23 transitive deps |
| License | MIT | No issues |
| Maintenance | Unmaintained | Last release: 2022-01-15 |

**Risk**: <Why this is critical>
**Recommendation**: Replace with `<alternative>`. Migration guide: <link or steps>.

### <package-name> — HIGH

| Dimension | Status | Detail |
|-----------|--------|--------|
| ... | ... | ... |

**Risk**: <explanation>
**Recommendation**: <action>

## Medium Risk Dependencies

| Package | Version | Risk Factors | Recommendation |
|---------|---------|-------------|----------------|
| <name> | <ver> | Stale (3 minor behind), minimal maintenance | Update to <ver> |

## Low Risk Dependencies

| Package | Version | License | Last Updated |
|---------|---------|---------|-------------|
| <name> | <ver> | MIT | 2024-11-01 |

## License Compliance

| License | Count | Packages | Risk |
|---------|-------|----------|------|
| MIT | <n> | <list> | None |
| Apache-2.0 | <n> | <list> | None |
| GPL-3.0 | <n> | <list> | Copyleft — review required |
| Unlicensed | <n> | <list> | Unknown — investigate |

## Recommendations Summary

### Immediate Action
1. <package>: <action and reason>

### This Sprint
1. <package>: <action and reason>

### Next Maintenance Window
1. <package>: <action and reason>

### Monitor
1. <package>: <what to watch for>

Risk Scoring Matrix

Dimension	Low	Medium	High	Critical
Freshness	Current or 1 minor behind	2+ minor behind	1+ major behind	Abandoned (2+ years)
Vulnerabilities	None known	Low severity	High severity, fix available	Critical severity or no fix
Bundle Impact	< 50KB, few transitive	50-200KB	200KB-1MB	> 1MB or 50+ transitive deps
License	MIT, BSD, ISC, Apache-2.0	LGPL	GPL	AGPL or unlicensed
Maintenance	Active (monthly releases)	Maintained (quarterly)	Minimal (yearly)	Unmaintained or archived

The overall risk score for a dependency is the highest score across all dimensions.

Note: These risk levels assume distributed, proprietary software. Adjust based on your project's distribution model — for internal-only tools, even copyleft licenses may be low risk. For dynamically linked libraries, LGPL is often low risk.

Anti-patterns

• Only checking for vulnerabilities, ignoring staleness — A dependency with no CVEs but abandoned for 3 years is a ticking time bomb. When a vulnerability is discovered, there will be no one to patch it. Staleness is a leading indicator of future risk.
• Not checking transitive dependencies — Your project may have 20 direct dependencies but 200 transitive ones. A critical vulnerability in a transitive dependency is just as exploitable. Always audit the full tree.
• Ignoring license issues — Using a GPL library in a proprietary product can create legal exposure. License compliance is not optional, and "we will deal with it later" becomes expensive when a customer or investor asks.
• Only auditing production dependencies — Dev dependencies run in your CI/CD pipeline and developer machines. A compromised dev dependency can inject malicious code into your build artifacts. Audit everything.
• Treating the audit as a one-time activity — Dependencies change constantly. New vulnerabilities are disclosed daily. Schedule regular audits (at least monthly) and integrate npm audit / pip audit into CI.
• Recommending updates without checking breaking changes — "Just update to latest" is not actionable advice. Check the changelog for breaking changes, especially across major versions, and note migration effort in the recommendation.
• Ignoring bundle impact in frontend projects — A 2MB dependency for a single utility function destroys load time. Always consider whether the functionality can be achieved with a smaller package or inlined code.