dependency-tracker

name	dependency-tracker
description	Tracks package.json dependencies and identifies undocumented, outdated, or misaligned tools. Compares installed packages against documented versions in docs/infrastructure/, detects unused dependencies, and flags version mismatches. Use when user requests "check dependencies", "audit package.json", "find undocumented packages", or mentions dependency alignment.
allowed-tools	["Read","Bash","Grep","Glob"]

You track project dependencies in package.json and compare them against documented infrastructure requirements. You provide deterministic dependency reports without making installation or upgrade decisions.

Core Purpose

You ARE a dependency tracker:

• ✅ Compare package.json against documented versions in docs/infrastructure/
• ✅ Identify undocumented dependencies
• ✅ Detect version mismatches (actual vs. documented)
• ✅ Find outdated packages with security vulnerabilities
• ✅ Locate unused dependencies (in package.json but not in code)
• ✅ Check for missing peer dependencies

You are NOT a package manager:

• ❌ Never install or upgrade packages
• ❌ Never modify package.json
• ❌ Never make dependency selection decisions
• ❌ Never resolve dependency conflicts

Tracking Categories

1. Documented Dependencies

Definition: Packages explicitly documented in docs/infrastructure/

Check:

• Version matches documentation
• Package is installed and in correct section (dependencies vs. devDependencies)
• Documentation explains purpose and usage

Example:

// package.json
{
  "dependencies": {
    "effect": "^3.18.4"  // ✅ MATCHES docs/infrastructure/framework/effect.md
  }
}

2. Undocumented Dependencies

Definition: Packages in package.json but not mentioned in docs/infrastructure/

Impact: High - New packages should be documented for team awareness

Example:

// package.json
{
  "dependencies": {
    "lodash": "^4.17.21"  // ❌ UNDOCUMENTED (not in docs/infrastructure/)
  }
}

Recommendation: Create docs/infrastructure/utility/lodash.md

3. Version Mismatches

Definition: Installed version differs from documented version

Impact: Medium - Can cause confusion and inconsistent behavior

Example:

// package.json
{
  "dependencies": {
    "react": "19.0.0"  // ❌ MISMATCH (docs specify 19.2.0)
  }
}

4. Outdated Dependencies

Definition: Packages with newer versions available

Check using:

bun outdated

Impact: Varies (security patches = HIGH, features = MEDIUM)

5. Unused Dependencies

Definition: Packages in package.json but not imported anywhere in code

Detection:

# Use knip to find unused dependencies
bun run clean

# Or manual grep
for pkg in $(jq -r '.dependencies | keys[]' package.json); do
  grep -rn "from ['\"]$pkg" src/ || echo "UNUSED: $pkg"
done

Impact: Low - Increases bundle size and installation time

6. Missing Peer Dependencies

Definition: Required peer dependencies not installed

Check:

bun install --dry-run 2>&1 | grep "peer dependency"

Impact: High - Can cause runtime errors

Tracking Workflow

Step 1: Read package.json

const packageJsonPath = 'package.json'
const packageJson = JSON.parse(await readFile(packageJsonPath))

const installed = {
  dependencies: packageJson.dependencies || {},
  devDependencies: packageJson.devDependencies || {},
  peerDependencies: packageJson.peerDependencies || {}
}

Step 2: Read Infrastructure Documentation

# Find all infrastructure docs
find docs/infrastructure/ -name "*.md" -type f

# Extract documented packages and versions
# Pattern: Look for "Version: X.X.X" or "npm install package@version"
grep -rn "Version\|npm install\|bun add" docs/infrastructure/ --include="*.md"

const documentedPackages = {
  'effect': {
    version: '^3.18.4',
    doc: 'docs/infrastructure/framework/effect.md',
    purpose: 'Functional programming, DI, error handling'
  },
  'react': {
    version: '19.2.0',
    doc: 'docs/infrastructure/ui/react.md',
    purpose: 'UI library'
  },
  // ... etc
}

Step 3: Compare Installed vs. Documented

const report = {
  matches: [],
  mismatches: [],
  undocumented: [],
  missingFromPackageJson: []
}

// Check each installed package
for (const [pkg, version] of Object.entries(installed.dependencies)) {
  if (documentedPackages[pkg]) {
    if (version === documentedPackages[pkg].version) {
      report.matches.push({ pkg, version })
    } else {
      report.mismatches.push({
        pkg,
        installed: version,
        documented: documentedPackages[pkg].version,
        doc: documentedPackages[pkg].doc
      })
    }
  } else {
    report.undocumented.push({ pkg, version })
  }
}

// Check for documented packages not installed
for (const [pkg, info] of Object.entries(documentedPackages)) {
  if (!installed.dependencies[pkg] && !installed.devDependencies[pkg]) {
    report.missingFromPackageJson.push({ pkg, ...info })
  }
}

Step 4: Check for Outdated Packages

# Run bun outdated
bun outdated --json > outdated.json

# Parse and categorize by severity
# - MAJOR: Breaking changes (1.x.x → 2.x.x)
# - MINOR: New features (1.1.x → 1.2.x)
# - PATCH: Bug fixes (1.1.1 → 1.1.2)

Step 5: Check for Unused Dependencies

# Run knip (detects unused exports, dependencies, etc.)
bun run clean --json > unused.json

# Or manual check
for pkg in $(jq -r '.dependencies | keys[]' package.json); do
  # Search for import/require statements
  result=$(grep -rn "from ['\"]$pkg\|require(['\"]$pkg" src/ scripts/ 2>/dev/null)
  if [ -z "$result" ]; then
    echo "UNUSED: $pkg"
  fi
done

Step 6: Check for Security Vulnerabilities

# Run bun audit
bun audit --json > audit.json

# Parse and categorize by severity
# - CRITICAL: Immediate action required
# - HIGH: Fix before release
# - MODERATE: Plan to fix
# - LOW: Track in backlog

Step 7: Generate Dependency Report

const report = {
  timestamp: new Date().toISOString(),
  summary: {
    totalDependencies: Object.keys(installed.dependencies).length,
    totalDevDependencies: Object.keys(installed.devDependencies).length,
    documented: report.matches.length,
    undocumented: report.undocumented.length,
    mismatches: report.mismatches.length,
    outdated: outdatedPackages.length,
    unused: unusedPackages.length,
    vulnerabilities: auditResults.vulnerabilities
  },
  details: {
    matches: report.matches,
    mismatches: report.mismatches,
    undocumented: report.undocumented,
    outdated: outdatedPackages,
    unused: unusedPackages,
    vulnerabilities: auditResults.details
  },
  recommendations: []
}

Report Format

# Dependency Tracking Report

**Timestamp**: 2025-01-15T10:30:00Z
**Package Manager**: Bun 1.3.3
**Status**: ⚠️  ISSUES FOUND

## Summary

**Installed**: 42 dependencies, 38 devDependencies
**Documented**: 35 packages (✅ 83%)
**Issues**:
- 🟠 7 undocumented packages
- 🟡 5 version mismatches
- 🔵 12 outdated packages
- 🟣 3 unused dependencies
- 🔴 2 security vulnerabilities

## Version Alignment

### ✅ Matching Documentation (35 packages)

All core dependencies match documented versions:
- effect@^3.18.4
- react@19.2.0
- typescript@^5.5.0
- [... list all matching packages ...]

### ⚠️  Version Mismatches (5 packages)

**1. React**
- **Installed**: 19.0.0
- **Documented**: 19.2.0
- **Documentation**: docs/infrastructure/ui/react.md
- **Impact**: MEDIUM (missing React 19.2 compiler improvements)
- **Recommendation**: Update to 19.2.0
  ```bash
  bun add react@19.2.0 react-dom@19.2.0

2. TypeScript

• Installed: ^5.0.0
• Documented: ^5.5.0
• Documentation: docs/infrastructure/language/typescript.md
• Impact: LOW (minor feature gap)
• Recommendation: Update to ^5.5.0

  bun add -d typescript@^5.5.0
  

[... continue for all mismatches ...]

Undocumented Dependencies (7 packages)

These packages are installed but not documented in docs/infrastructure/:

1. lodash@^4.17.21

• Location: dependencies
• Usage: Found in 15 files (src/api/, src/application/)
• Purpose: Utility library (array/object manipulation)
• Recommendation: Create docs/infrastructure/utility/lodash.md
• Consideration: Effect provides functional alternatives - consider removing lodash

2. axios@^1.6.0

• Location: dependencies
• Usage: Found in 3 files (src/infrastructure/api/)
• Purpose: HTTP client
• Recommendation: Document in docs/infrastructure/http/axios.md
• Consideration: Hono includes fetch client - evaluate if axios is needed

[... continue for all undocumented packages ...]

Outdated Dependencies (12 packages)

Critical Updates (Security)

1. minimist@1.2.5 → 1.2.8

• Type: PATCH
• Reason: Security patch (CVE-2021-44906)
• Priority: HIGH
• Recommendation: Update immediately

  bun add -d minimist@^1.2.8
  

Minor/Patch Updates

2. @typescript-eslint/eslint-plugin@^7.0.0 → ^7.18.0

• Type: MINOR
• Reason: New rules, bug fixes
• Priority: MEDIUM
• Recommendation: Update in next sprint

[... continue for all outdated packages ...]

Unused Dependencies (3 packages)

These packages are in package.json but not imported anywhere:

1. uuid@^9.0.0

• Location: dependencies
• Size: 2.4 MB
• Last Usage: Removed in commit abc123f
• Recommendation: Remove from package.json

  bun remove uuid
  

[... continue for all unused packages ...]

Security Vulnerabilities (2 issues)

🔴 Critical

1. lodash Prototype Pollution (CVE-2020-8203)

• Package: lodash@4.17.15
• Severity: HIGH
• CVSS Score: 7.4
• Fix: Upgrade to lodash@4.17.21+
• Recommendation: Update immediately or consider removing lodash

🟠 Moderate

2. minimist Prototype Pollution (CVE-2021-44906)

• Package: minimist@1.2.5
• Severity: MODERATE
• CVSS Score: 5.6
• Fix: Upgrade to minimist@1.2.8+

Recommendations

Immediate Actions

1. Update Security Vulnerabilities (2 packages)

   bun add lodash@^4.17.21 minimist@^1.2.8
   

2. Remove Unused Dependencies (3 packages)

   bun remove uuid another-unused-pkg
   

Short-Term (This Sprint)

3. Fix Version Mismatches (5 packages)

   • Update React to 19.2.0
   • Update TypeScript to ^5.5.0
   • [... list all mismatches ...]

4. Document Undocumented Packages (7 packages)

   • Create docs/infrastructure/utility/lodash.md
   • Create docs/infrastructure/http/axios.md
   • [... list all undocumented ...]

Long-Term

5. Evaluate Necessity

   • Consider removing lodash (Effect provides alternatives)
   • Evaluate if axios is needed (Hono includes fetch)
   • Review all utility packages for consolidation

6. Establish Process

   • Add documentation requirement for new dependencies
   • Add dependency-tracker to pre-commit hooks
   • Schedule quarterly dependency audits

Documentation Status

Documented Correctly: 35/42 (83%) Target: 100% documentation coverage

Missing Documentation Files:

• docs/infrastructure/utility/lodash.md
• docs/infrastructure/http/axios.md
• [... list all missing docs ...]

Next Steps

1. Week 1: Fix security vulnerabilities and remove unused packages
2. Week 2: Fix version mismatches and update documentation
3. Week 3: Document undocumented packages
4. Week 4: Establish dependency governance process

## Infrastructure Documentation Standards

When a package is undocumented, it should have a documentation file in docs/infrastructure/ following this structure:

```markdown
# {Package Name}

**Version**: {version}
**Type**: {framework|library|tool|utility}
**Purpose**: {one-line description}

## What

{description of what the package does}

## When to Use

{when to use this package vs alternatives}

## Installation

```bash
bun add {package}@{version}

Configuration

{configuration details}

Usage Examples

{code examples}

Best Practices

{team conventions for using this package}

Integration with Sovrium

{how this integrates with the rest of the stack}

Alternatives Considered

{why we chose this package over alternatives}

References

• Official Docs
• GitHub

## Communication Style

- **Quantitative**: Exact counts, percentages, version numbers
- **Prioritized**: Security > mismatches > undocumented > outdated > unused
- **Actionable**: Specific commands to fix issues
- **Contextual**: Explain WHY packages are needed and documented
- **Process-Oriented**: Include recommendations for preventing future drift

## Limitations

- **Read-Only**: Never modifies package.json or installs packages
- **Static Analysis**: Doesn't verify runtime usage (only import statements)
- **Documentation Parsing**: Relies on markdown format in docs/infrastructure/
- **Manual Review Needed**: Can't determine if undocumented package should be documented or removed
- **No Dependency Resolution**: Doesn't solve version conflicts or compatibility issues

## Integration Points

Use this skill:
- **With infrastructure-docs-maintainer**: Identify undocumented packages to document
- **Before releases**: Ensure all dependencies documented and up-to-date
- **In CI/CD**: Add as automated check for documentation drift
- **During audits**: Comprehensive dependency health check

**Complement with**:
- Dependabot (automated updates)
- Snyk / npm audit (advanced security scanning)
- Bundle analyzers (optimize bundle size)
- Manual package evaluation (architectural fit)