deps-audit

/deps-audit — Dependency Health Audit

Audit the project's dependency tree for security vulnerabilities, outdated packages, unused dependencies, and license compliance. Produce a structured report and optionally auto-fix safe updates.

Arguments

• $ARGUMENTS may contain --fix to auto-apply safe updates (patch/minor only)

Phase 0 — Pre-flight

1. Confirm we're in the codegraph repo root (check for package.json and package-lock.json)
2. Run node --version — must be >= 20
3. Run npm --version to capture toolchain info
4. Parse $ARGUMENTS — set AUTO_FIX=true if --fix is present
5. If AUTO_FIX is set: Save the original manifests now, before any npm commands run, so pre-existing unstaged changes are preserved:

   git stash push -m "deps-audit-backup" -- package.json package-lock.json
   STASH_REF=$(git stash list --format='%gd %s' | grep 'deps-audit-backup' | head -1 | awk '{print $1}')
   

   STASH_REF is non-empty if and only if a stash entry was actually created. Do not use $? — modern git (2.16+) returns 0 even when nothing was stashed. Use [ -n "$STASH_REF" ] (stash created) / [ -z "$STASH_REF" ] (nothing stashed) for all branching. Use $STASH_REF (not stash@{0}) in all later stash drop/pop commands to avoid targeting the wrong entry.

Phase 1 — Security Vulnerabilities

Run npm audit --json and parse the output:

1. Count vulnerabilities by severity: critical, high, moderate, low, info
2. For each critical or high vulnerability:
   • Record: package name, severity, CVE/GHSA ID, vulnerable version range, patched version, dependency path (direct vs transitive)
   • Check if a fix is available (npm audit fix --dry-run --json)
3. Summarize: total vulns, fixable count, breaking-fix count

If AUTO_FIX is set: Run npm audit fix (non-breaking fixes only). Record what changed. Do NOT run npm audit fix --force — breaking changes require manual review.

Phase 2 — Outdated Dependencies