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:

Review release notes before updating
Update dev dependencies first (lower risk)
Run tests after updating
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:

Search codebase: grep -r "package-name" src/
Check config files (vite.config.ts, tsconfig.json, etc.)
Check if it's a peer dependency
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

deps-audit

Install Skill

SKILL.md