deps-audit

name	deps-audit
description	Dependency health analysis to detect outdated packages and unused dependencies.

Purpose

Analyze dependency health in your project to ensure:

• Dependencies are up-to-date (minor versions)
• No unused dependencies bloating node_modules
• Clean and maintainable package.json
• Reduced security vulnerabilities

Dependency Checks

1. Outdated Dependencies Check

Rule: Keep dependencies up-to-date to get security patches, bug fixes, and improvements.

Detects:

• Packages with available minor version updates
• Both production and dev dependencies
• Percentage of outdated packages

How it works:

• Uses npm-check-updates to check for available updates
• Targets minor versions (e.g., 1.2.0 → 1.3.0, not 1.x → 2.x)
• Safe updates that shouldn't break compatibility

Example Output:

Outdated Packages
--------------------------------------------------------------------------------

⚠️  Found 5 outdated package(s) (12% of total)

  Production Dependencies (2):
    react: ^18.2.0 → ^18.3.0
    axios: ^1.4.0 → ^1.7.0

  Dev Dependencies (3):
    vitest: ^1.0.0 → ^1.5.0
    typescript: ^5.2.0 → ^5.4.0
    eslint: ^8.50.0 → ^8.57.0

Benefits of updating:

• Security vulnerability patches
• Bug fixes
• Performance improvements
• New features
• Reduced technical debt

Recommendations:

1. Review release notes before updating
2. Update dev dependencies first (lower risk)
3. Run tests after updating
4. Consider using deps-minor skill for safe automated updates

Threshold: Fails if more than 20% of packages are outdated

Check: check_outdated_deps.mjs

2. Unused Dependencies Check

Rule: Remove unused dependencies to keep node_modules clean and secure.

Detects:

• Dependencies not found in import statements
• Both production and dev dependencies
• Heuristic-based detection

How it works:

• Scans all source files for import statements
• Extracts imported package names
• Compares with package.json dependencies
• Excludes known build tools and CLI packages

Example Output:

Potentially Unused Dependencies
--------------------------------------------------------------------------------

⚠️  Found 3 potentially unused dependencies (8%)

  Production Dependencies (1):
    lodash

  Dev Dependencies (2):
    jest
    webpack

Important Warnings:

• HEURISTIC CHECK - may have false positives
• Verify before removing any package
• May miss:
  • Packages used only in config files
  • Transitive dependencies
  • Type-only packages (@types/*)
  • Build script dependencies

Verification Steps:

1. Search codebase: grep -r "package-name" src/
2. Check config files (vite.config.ts, tsconfig.json, etc.)
3. Check if it's a peer dependency
4. If truly unused: npm uninstall package-name

Benefits of removal:

• Smaller node_modules (faster installs)
• Reduced security surface area
• Cleaner package.json
• Lower maintenance burden

Threshold: Fails if more than 10% of dependencies appear unused

Check: check_unused_deps.mjs

Running Checks

Run All Checks

node ./.claude/skills/deps-audit/scripts/run_all_checks.mjs

Run Individual Checks

# Outdated dependencies check
node ./.claude/skills/deps-audit/scripts/check_outdated_deps.mjs

# Unused dependencies check
node ./.claude/skills/deps-audit/scripts/check_unused_deps.mjs

Generating Reports (Optional)

To save a comprehensive markdown report of all checks:

node ./.claude/skills/deps-audit/scripts/generate_report.mjs

Output: reports/{YYYY-MM-DD_HH-MM}/deps-audit-report.md

Report includes:

• Executive summary with pass/fail counts
• Results table for all checks
• Detailed lists of outdated and unused packages
• Summary of passed checks
• Dependency management principles
• Prioritized recommendations

Environment variable:

# Custom report directory
export REPORT_DIR="reports/my-custom-timestamp"
node ./.claude/skills/deps-audit/scripts/generate_report.mjs

Usage patterns:

# Option 1: Console output only (default)
node ./.claude/skills/deps-audit/scripts/run_all_checks.mjs

# Option 2: Console output + Save report
node ./.claude/skills/deps-audit/scripts/generate_report.mjs

# Option 3: Specific check only
node ./.claude/skills/deps-audit/scripts/check_outdated_deps.mjs

Report structure:

reports/
└── 2025-11-01_14-30/               # Includes hours and minutes for multiple runs per day
    ├── deps-audit-report.md        # This skill's report
    ├── security-audit-report.md    # Security audit (separate)
    ├── test-audit-report.md        # Test audit (separate)
    ├── code-audit-report.md        # Code quality audit (separate)
    ├── arch-audit-report.md        # Architecture audit (separate)
    └── ...                         # Other reports

Output Format

Each check produces:

• Clear package lists with current and available versions
• Percentage of affected packages
• Actionable recommendations
• Update commands
• Summary with metrics
• Exit code 0 (success) or 1 (failures)

Example output:

Outdated Dependencies Check
================================================================================

Total packages: 42

Running npm-check-updates (this may take a moment)...

Outdated Packages
--------------------------------------------------------------------------------

⚠️  Found 5 outdated package(s) (12% of total)

  Production Dependencies (2):
    react: ^18.2.0 → ^18.3.0
    axios: ^1.4.0 → ^1.7.0

Update commands:
  # Update specific package
  npm install package-name@latest

  # Update all minor versions (use with caution)
  npx npm-check-updates -u --target minor && npm install

================================================================================
Summary: 5 outdated package(s) (12%)

Dependency Management Benefits

Security

• Outdated packages may have known vulnerabilities
• Regular updates reduce security risks
• Proactive security posture

Maintainability

• Smaller, cleaner dependency tree
• Easier to understand project dependencies
• Less technical debt

Performance

• Bug fixes and optimizations in newer versions
• Faster installs with fewer packages
• Smaller bundle sizes

Developer Experience

• Access to latest features
• Better documentation
• Active community support

Integration with Other Skills

deps-minor Skill

• Automated safe minor version updates
• Validates with lint/test/build
• Automatic rollback on failure
• Use after identifying outdated packages

security-audit Skill

• Checks for hardcoded secrets
• Complements dependency security
• Together provide comprehensive security analysis

Combined Analysis

Run all audit skills for complete health check:

# Security vulnerabilities
node ./.claude/skills/security-audit/scripts/run_all_checks.mjs

# Test coverage
node ./.claude/skills/test-audit/scripts/run_all_checks.mjs

# Dependency health
node ./.claude/skills/deps-audit/scripts/run_all_checks.mjs

# Code quality
node ./.claude/skills/code-audit/scripts/run_all_checks.mjs

# Architecture patterns
node ./.claude/skills/arch-audit/scripts/run_all_checks.mjs

Limitations

Outdated Check

• Only checks minor versions (not major)
• Requires npm-check-updates (auto-installed with npx)
• Requires network access
• Release notes review still needed

Unused Check

• Heuristic-based (may have false positives)
• Doesn't analyze config files thoroughly
• Doesn't track transitive dependencies
• May miss indirect usage patterns

Recommendations

• Always verify before removing packages
• Read release notes before updating
• Run tests after dependency changes
• Use version control to track changes

Tools

• Bash: Run Node.js check scripts and npm-check-updates
• Read: Read package.json and source files
• Write: reports/{timestamp}/deps-audit-report.md (only when generating reports)

Safety

• Read-only operations (unless generating reports)
• No automatic package installations or removals
• No package.json modifications
• Network call only for npm-check-updates
• Comprehensive dependency analysis
• Each check is isolated and focused
• Reports are saved to isolated reports/ directory