abildtoft/kramme:deps:audit

Dependency Audit

Audit project dependencies for outdated packages, security vulnerabilities, and staleness. Groups related packages, assesses risk per update, and generates a prioritized upgrade plan.

Parse $ARGUMENTS for --auto before Step 1.

• If present, set AUTO_MODE=true and remove the flag from the remaining input.
• --auto means: audit all detected ecosystems, write DEPENDENCY_AUDIT.md, and stop in review-only mode without applying updates or creating SIW issues.

---

Step 1: Detect Package Manager

Read the detection details from references/package-manager-commands.md and use it as the source of truth for lock-file mappings, manifest patterns, and monorepo markers.

If multiple ecosystems are detected:

• If AUTO_MODE=true, set PACKAGE_MANAGER to the list of all detected ecosystems and continue.
• Otherwise, ask the user which to audit. Present the detected ecosystems plus an "Audit all" option, then store the selection as PACKAGE_MANAGER.

---

Step 2: Gather Dependency Data

For each ecosystem in PACKAGE_MANAGER, run the outdated and audit commands from references/package-manager-commands.md. Examples:

npm/yarn/pnpm:

npm outdated --json
npm audit --json

pip:

pip list --outdated --format=json
pip-audit --json  # if installed

cargo:

cargo outdated  # if installed
cargo audit     # if installed

go:

go list -m -u all
govulncheck ./...  # if installed

dotnet:

dotnet list package --outdated
dotnet list package --vulnerable

Error capture: Do not suppress stderr. Capture both stdout and stderr so failures are visible. Distinguish three outcomes per command:

1. Success — exit 0, parse output.
2. Tool missing — command not found. Warn, skip that command, suggest the install command from the reference file.
3. Command failed — non-zero exit with output. Retry once. If the second attempt also fails, record the ecosystem as partial and surface the stderr verbatim in the Step 7 report so the user can diagnose network, registry, or auth issues.

Capture per package:

• From the outdated command: name, current version, latest version, update type (major/minor/patch), staleness (versions behind, last release date when available).
• From the audit command: vulnerabilities (severity, CVE ID, fixed-in version).

---

Step 3: Group and Classify

1. Group related packages by org or scope:

   • @angular/core, @angular/cli, @angular/common → Angular group
   • eslint, eslint-plugin-*, @typescript-eslint/* → ESLint group
   • @ngrx/store, @ngrx/effects → NgRx group

2. Classify each update:

   • Security — has a known CVE (Critical/High/Medium/Low)
   • Major — major version bump (likely breaking changes)
   • Minor — minor version bump (new features, should be safe)
   • Patch — patch version bump (bug fixes)

3. Calculate staleness: how many versions behind, time since current version.

---

Step 4: Risk Assessment

Read the scoring rubric from references/risk-assessment-matrix.md.

For each package group, assess:

1. Breaking change likelihood: Major = High, Minor = Low, Patch = Minimal.
2. Codebase impact: count files that import the package. Scope the search to source directories — exclude node_modules/, dist/, build/, out/, vendor/, target/, .venv/, and bin/obj/ so file counts reflect first-party usage.
3. Test coverage: check if affected areas have existing tests.
4. Assign risk level: Low / Medium / High / Critical.

---

Step 5: Generate Upgrade Plan

Priority ordering:

1. Phase 1 — Immediate: Security vulnerabilities (Critical and High severity)
2. Phase 2 — Quick Wins: Patch updates + low-risk minor updates
3. Phase 3 — Planned: Remaining minor updates (grouped by related packages)
4. Phase 4 — Major Upgrades: Major version bumps (one campaign per group)

Each entry includes: packages, current → target versions, risk level, recommended testing.

---

Step 6: User Review

Auto mode

If AUTO_MODE=true:

• Skip the prompt below.
• Default to Review only — no changes.
• Always write DEPENDENCY_AUDIT.md using the template at assets/audit-report.md (see "Writing the report" below).
• Continue to Step 7.

Interactive mode

Otherwise, ask the user one combined question:

How should I present the results, and what should I do next?

Present these options:

1. Terminal summary only, no changes
2. Write DEPENDENCY_AUDIT.md, no changes
3. Write DEPENDENCY_AUDIT.md, then apply Phase 2 (low-risk patches + minors) and run /kramme:verify:run
4. Write DEPENDENCY_AUDIT.md, then create a SIW workflow with one issue per Phase 4 campaign (via /kramme:siw:init)
5. Generate a visual HTML report via /kramme:visual:diagram, no changes

Writing the report

When the chosen action writes the report:

• Read the template from assets/audit-report.md.
• Populate one report file at <project-root>/DEPENDENCY_AUDIT.md.
• Overwrite any existing DEPENDENCY_AUDIT.md without prompting (the report is a snapshot, not append-only). Note the overwrite in the Step 7 summary.
• For multi-ecosystem audits, render one populated copy of every top-level template section per ecosystem under a ## Ecosystem: <name> heading, in the order ecosystems are listed in PACKAGE_MANAGER. Keep the top-of-file Summary section as a single combined view across ecosystems.

Applying Phase 2 (option 3)

Before running update commands:

1. List the exact packages and target versions to be updated in the chat.
2. Verify the working tree is clean (git status --porcelain). If it is dirty, stop and ask the user to commit or stash first.
3. Run the ecosystem update commands.
4. Run /kramme:verify:run. If verification fails, stop, report which packages were updated, and leave the lockfile changes in place for the user to inspect or revert.

---

Step 7: Report

Dependency Audit Complete

Package Manager: {PACKAGE_MANAGER}
Total Dependencies: {N} ({direct} direct, {transitive} transitive)

Security Vulnerabilities:
  Critical: {N}
  High:     {N}
  Medium:   {N}
  Low:      {N}

Outdated Packages:
  Major: {N} packages ({groups} groups)
  Minor: {N} packages
  Patch: {N} packages

Upgrade Plan:
  Phase 1 (Immediate):  {N} security fixes
  Phase 2 (Quick Wins): {N} patch + minor updates
  Phase 3 (Planned):    {N} grouped minor updates
  Phase 4 (Major):      {N} major upgrades ({campaigns} campaigns)

{if report_written}
Report: DEPENDENCY_AUDIT.md{if overwritten} (overwrote previous report){/if}
{/if}

{if partial_results}
Partial results — the following commands failed and were excluded:
  - {ecosystem}: {command} → {stderr first line}
{/if}

STOP — Do not continue beyond this point.

---

Error Handling

| Scenario | Action | | --- | --- | | No package manager detected | Abort: No supported package manager found in this directory. | | Audit tool not installed | Warn, skip vulnerability check, suggest install command from the reference file | | Command failed (non-zero exit) | Retry once; if still failing, mark ecosystem as partial and surface stderr in Step 7 | | No outdated packages | Report clean: All dependencies are up to date. | | Monorepo with many workspaces | Audit root-level first, suggest per-workspace audit | | Working tree dirty when applying Phase 2 | Stop and ask user to commit or stash before proceeding | | /kramme:verify:run fails after applying Phase 2 | Stop, report which packages were updated, leave lockfile changes for the user |