| name | dependency-audit |
| description | Dependency health and internal coupling audit for Node.js/TypeScript projects. 10 dimensions: supply chain vulnerabilities, freshness, dead dependencies, license compliance, bundle weight, circular dependencies, coupling metrics, architecture boundary violations, barrel file health, and change coupling. Tiered tooling with graceful degradation. Switches: zuvo:dependency-audit full | [path] | --supply-chain | --coupling | --dead | --bundle | --lock-in
|
| codesift_tools | {"always":["analyze_project","index_status","index_folder","index_file","plan_turn","get_file_tree","find_dead_code","find_unused_imports","find_circular_deps","fan_in_fan_out","check_boundaries","search_text","search_patterns","audit_scan","get_file_outline"],"by_stack":{"typescript":["get_type_info"],"javascript":[],"python":["python_audit","analyze_async_correctness","analyze_python_deps"],"php":["php_project_audit","php_security_scan","resolve_php_namespace"],"kotlin":["analyze_sealed_hierarchy","find_extension_functions","trace_flow_chain","trace_suspend_chain","trace_compose_tree","analyze_compose_recomposition","trace_hilt_graph","trace_room_schema","analyze_kmp_declarations","extract_kotlin_serialization_contract"],"nestjs":["nest_audit"],"nextjs":["framework_audit","nextjs_route_map"],"astro":["astro_audit","astro_actions_audit","astro_hydration_audit"],"hono":["analyze_hono_app","audit_hono_security"],"express":[],"fastify":[],"react":["react_quickstart","analyze_hooks","analyze_renders","audit_compiler_readiness"],"django":["analyze_django_settings","effective_django_view_security","taint_trace"],"fastapi":["trace_fastapi_depends","get_pydantic_models"],"flask":["find_framework_wiring"],"jest":[],"yii":["resolve_php_service"],"prisma":["analyze_prisma_schema"],"drizzle":[],"sql":["sql_audit"],"postgres":["migration_lint"]}} |
zuvo:dependency-audit
Audit external dependency health and internal module coupling. Scores 10
dimensions with tiered tooling -- gracefully degrades when specialized tools
are unavailable.
Scope: Node.js / TypeScript projects (npm, pnpm, yarn, bun).
When to use: Before releases, after adding many dependencies, periodic
health check, after monorepo restructuring, before lock-in reviews.
When NOT to use: Code quality (zuvo:review), DB-specific
(zuvo:db-audit), full-stack performance (zuvo:performance-audit), OWASP
(/security-audit).
Scanner exit codes: follow ../../shared/includes/scanner-invocation.md — npm/pip-audit/osv-scanner exit non-zero WHEN they find vulns (success); never treat non-zero as failure.
Known Limitations
- Node.js/TypeScript only. Python, Go, Rust, and Java are not supported.
npm query selectors are npm-specific. pnpm/yarn/bun fall back to lockfile
analysis.- D5 (bundle impact) uses Bundlephobia API for triage -- not precise without
actual build statistics.
- D7 (instability metrics) requires dependency-cruiser for Ca/Ce/I. Without it,
only fan-in/fan-out via grep.
- D10 (change coupling) requires 3+ months of git history.
- Monorepo workspace scoping is partial -- tools operate on workspace root
unless filtered.
Mandatory File Loading
Read every file below before starting. Print the checklist.
CORE FILES LOADED:
1. ../../shared/includes/codesift-setup.md -- [READ | MISSING -> STOP]
2. ../../shared/includes/env-compat.md -- [READ | MISSING -> STOP]
3. ../../rules/cq-patterns.md -- [READ | MISSING -> STOP]
4. ../../shared/includes/run-logger.md -- [READ | MISSING -> STOP]
5. ../../shared/includes/retrospective.md -- [READ | MISSING -> STOP]
If any file is MISSING, STOP. Do not proceed from memory.
Argument Parsing
| Token | Behavior |
|---|
(empty) or full | All 10 dimensions, scope = project root |
[path] | Scope to a package or directory (see scope rules below) |
--supply-chain | D1 only |
--coupling | D6, D7, D8, D9 only |
--dead | D3 only |
--bundle | D5 only |
--lock-in | D7 vendor lock-in focus |
--no-api | Skip Bundlephobia and OpenSSF API calls |
Path scope rules:
| Path points to | Manifest found? | D1-D5 (external) | D6-D10 (internal) |
|---|
Package root (own package.json) | Yes | Score for this package | Score within path |
| Subdirectory within a package | Inherited from parent | Mark INHERITED | Score within path |
No package.json above | No | Mark SKIPPED | Score within path |
Safety Gate
This audit is read-only. The only write target is zuvo/audits/. Do not
install, uninstall, or modify any dependency. Do not run npm audit fix or
equivalent automatically.
MANDATORY TOOL CALLS — Dependency Audit Validity Gate
This audit is INVALID if any tool below is skipped when its trigger condition holds. "DEFERRED", "N/A", "no fresh deps" are NOT valid reasons.
| Tool | Trigger | Reason | Skip allowed? |
|---|
find_dead_code | Always | KEY — unused exports = dead code = candidate dead deps | NO |
find_unused_imports | Always | KEY — barrel-file health, dead transitive deps | NO |
find_circular_deps | Always | KEY — circular module detection (D6) | NO |
fan_in_fan_out | Always | KEY — coupling metrics (D7) | NO |
check_boundaries | Always | D8 architecture boundary violations | NO |
audit_scan | Always | Compound CQ + dep pattern check | NO |
analyze_python_deps | Python detected | D1 supply-chain CVE check via PyPI | NO when Python |
| Stack-specific tools | Framework/language detected | Stack-specific dep gates | NO when matches |
Forbidden escape hatches: find_dead_code: skipped, find_circular_deps: N/A, codesift: unavailable (when deferred), retrospective: skipped — all REJECTED.
Required POSTAMBLE: report on disk → retro appended → ~/.zuvo/append-runlog exit 0. Every D-dim finding needs path/to/file.ext:LINE (verify-audit gate).
Mandatory acknowledgment (REQUIRED — print verbatim before Phase 0)
Mandatory-tools-acknowledgment: I will run find_dead_code + find_unused_imports + find_circular_deps + fan_in_fan_out + check_boundaries + audit_scan + analyze_python_deps (when Python) + stack-specific tools for this dependency audit. Every D-dim finding will cite a `path/to/file.ext:LINE` resolving in the current tree.
CodeSift preload
Use the deterministic preload helper FIRST. Run ~/.zuvo/compute-preload dependency-audit "$PWD" before any ToolSearch. Copy [CodeSift matching trace] verbatim, issue printed ToolSearch(query="select:..."). Math gate enforced.
Phase 0: Preflight
0.1 Manifest and Lockfile
Step 1: Find package.json at TARGET_ROOT, walk up to project root if needed.
If not found -> STOP: "No package.json. This skill requires Node.js."
Step 2: Find lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lockb).
Step 3: Validate package manager works: <pm> ls --json 2>&1
Decision matrix:
| Manifest | Lockfile | node_modules | Action |
|----------|----------|-------------|--------|
| Yes | Yes | Yes | Full audit D1-D10 |
| Yes | Yes | No | STOP: "Run <pm> install first." |
| Yes | No | Yes | D1 capped at 6/15. D1.5 = CRITICAL. |
| Yes | No | No | STOP: "No lockfile and no node_modules." |
| No | -- | -- | STOP: "No package.json found." |
0.2 Package Manager Detection
| Signal | PM |
|---|
package-lock.json | npm |
pnpm-lock.yaml | pnpm |
yarn.lock | Yarn (detect version: yarn --version, 1.x = Classic, 2+ = Berry) |
bun.lockb or bun.lock | Bun |
0.3 Framework Detection (for D8 layer rules)
| Signal | Framework | Layer Pattern |
|---|
next.config.* | Next.js App Router | app/ (server) -> lib/ -> components/ (client) |
nest-cli.json or @nestjs/core | NestJS | controllers -> services -> repositories |
vite.config.* + no SSR | Vite SPA | pages -> features -> shared |
express in deps | Express | routes -> middleware -> services |
0.4 Tool Availability
Run in parallel:
<pm> audit --json 2>/dev/null
<pm> ls --json 2>/dev/null
<pm> outdated --json 2>/dev/null
npx knip --reporter json 2>/dev/null
npx license-checker --json --production 2>/dev/null
npx depcruise --version 2>/dev/null
npx madge --version 2>/dev/null
Record which tools are available. Missing tools degrade specific dimensions
but do not block the audit.
Phase 1: Data Collection
1.1 External Dependency Data
PM audit output: Vulnerability report with severity levels.
PM outdated output: Current vs latest version for each dependency.
Lockfile analysis:
- Install scripts (
postinstall, preinstall)
- Git dependencies (
git+, github:)
- Lockfile integrity (uncommitted changes, drift from manifest)
Manifest analysis: Read package.json -- count prod/dev deps, version
specifier types (^, ~, exact), overrides, resolutions.
1.2 Internal Dependency Graph
With dependency-cruiser:
npx depcruise --no-config --output-type json --metrics TARGET_ROOT
With madge (fallback):
npx madge --json TARGET_ROOT
npx madge --circular --json --ts-config tsconfig.json TARGET_ROOT
npx madge --orphans --json TARGET_ROOT
Grep fallback (always available):
Search for import/export statements to build an approximate dependency graph.
Phase 2: Dimension Analysis (D1-D10)
Agent Dispatch
Refer to env-compat.md for the dispatch pattern.
When parallel dispatch is available:
| Agent | Dimensions | Input |
|---|
| Supply Chain Scanner | D1, D4 | PM audit, lockfile, license data |
| Coupling Analyzer | D6, D7, D8, D9 | dep-cruiser/madge output |
| Freshness Checker | D2, D3, D5 | PM outdated, knip output |
D10 (Change Coupling) runs in the lead agent (requires git log).
Without parallel dispatch: Execute all dimensions sequentially.
D1: Supply Chain and Vulnerabilities -- Weight 15, Max 15, Critical Gate
| Check | Good | Bad | Severity |
|---|
| Known CVEs | Zero critical/high CVEs in production deps | Unpatched critical CVE | CRITICAL |
| Install scripts | Only trusted packages run postinstall | Unknown package with postinstall | HIGH |
| Signature verification | Lockfile signatures verified | No signature verification | MEDIUM |
| Git dependencies | Zero git deps in production | git+ URLs bypass registry auditing | HIGH |
| Lockfile integrity | Committed, matches manifest, reproducible | Missing or diverged lockfile | HIGH |
Critical gate: D1=0 (known exploit-grade CVE in production) triggers FAIL.
D2: Freshness and Maintenance Health -- Weight 10, Max 10
| Check | Good | Bad | Severity |
|---|
| Major version lag | Within 1 major version of latest | 3+ major versions behind | HIGH |
| Maintenance status | Active maintainer, recent releases | Abandoned (no release > 2 years) | HIGH |
| Deprecated packages | Zero deprecated deps | Using packages with npm deprecate notice | MEDIUM |
D3: Dead Dependencies -- Weight 10, Max 10
| Check | Good | Bad | Severity |
|---|
| Unused production deps | Zero unused in dependencies | Package in manifest, never imported | HIGH |
| Phantom dependencies | All imports resolve to declared deps | Import works only because of hoisting | MEDIUM |
| Duplicate functionality | One library per task (date, HTTP, validation) | lodash + underscore + ramda all installed | MEDIUM |
Use knip output when available. Otherwise grep for import statements and
cross-reference against package.json dependencies.
D4: License Compliance -- Weight 8, Max 8, Critical Gate
| Check | Good | Bad | Severity |
|---|
| Copyleft in production | Zero GPL/AGPL in bundled code | GPL dependency in production app | CRITICAL |
| Unknown licenses | All deps have declared licenses | Missing license field | MEDIUM |
| License compatibility | All licenses compatible with project license | Conflicting license chain | HIGH |
Critical gate: D4=0 (GPL in production closed-source app) triggers FAIL.
D5: Bundle and Weight Impact -- Weight 8, Max 8
| Check | Good | Bad | Severity |
|---|
| Heavy dependencies | Alternatives exist for large deps (moment -> dayjs, lodash -> native) | 500 KB+ dep used for one function | HIGH |
| Tree-shaking support | sideEffects: false in dep, ESM exports | CommonJS-only dep in frontend bundle | MEDIUM |
| Duplicate versions | Single version in bundle | 3 versions of the same package | MEDIUM |
D6: Circular Dependencies -- Weight 12, Max 12, Critical Gate
| Check | Good | Bad | Severity |
|---|
| Runtime cycles | Zero circular dependency chains at runtime | Module A imports B, B imports A | CRITICAL |
| Type-only cycles | Type-only imports (import type) are acceptable | Type cycle causes runtime initialization bug | LOW |
| Cycle depth | N/A | 4+ module cycle chain | HIGH |
Critical gate: D6=0 (runtime circular dependency causing initialization bug)
triggers FAIL.
D7: Coupling Metrics -- Weight 10, Max 10
| Check | Good | Bad | Severity |
|---|
| Instability (I = Ce/(Ca+Ce)) | Balanced: stable foundations, unstable leaves | Core module with I > 0.8 (depends on everything) | HIGH |
| Fan-out | Module imports < 10 direct dependencies | Single file imports 30+ modules | HIGH |
| Fan-in | Shared module is aware of its consumers | Utility used by 50+ files, fragile to change | MEDIUM |
| Vendor lock-in | Adapter pattern around vendor SDKs | Vendor SDK calls spread across 20+ files | MEDIUM |
D8: Architecture Boundary Violations -- Weight 12, Max 12, Critical Gate
| Check | Good | Bad | Severity |
|---|
| Layer enforcement | UI -> Services -> Data, never backward | Component imports from data layer directly | HIGH |
| Secret in client | Server-only vars never imported in client code | Client bundle imports process.env.SECRET | CRITICAL |
| Domain boundaries | Features do not cross-import internal modules | Feature A reaches into Feature B internals | MEDIUM |
Critical gate: D8=0 (secret leaked to client bundle) triggers FAIL.
D9: Barrel File Health -- Weight 7, Max 7
| Check | Good | Bad | Severity |
|---|
| Re-export scope | Barrel re-exports < 5 symbols, public API only | export * pulling in 50+ symbols | HIGH |
| Circular risk | Barrel does not create import cycles | Barrel creates cycle between modules | HIGH |
| Tree-shake impact | sideEffects: false set, named exports | Barrel defeats tree-shaking | MEDIUM |
D10: Change Coupling -- Weight 8, Max 8
Analyze git history (last 6 months) for files that always change together:
git log --name-only --pretty=format:"---COMMIT---" --since="6 months ago" -- TARGET_ROOT
| Check | Good | Bad | Severity |
|---|
| Co-change clusters | Related files change together (test + impl) | Unrelated modules always change together | HIGH |
| Shotgun surgery | Feature change touches 1-3 files | Every feature touches 10+ files | HIGH |
| God module churn | Hot files are small and well-tested | Largest file is also most-changed | CRITICAL |
Phase 3: Verification and Scoring
False Positive Filters
| Pattern | Skip When |
|---|
| Install script flagged | Well-known build tool (esbuild, sharp, prisma, @swc/core) |
| Unused dep | Framework plugin loaded via config (knip handles 139+ but misses some) |
| Circular dep | Type-only cycle (import type) with isolatedModules |
Floating ^ version | Lockfile present and committed |
| Layer violation in Next.js | Server component IS the server layer |
| Barrel flagged | < 5 re-exports AND no circular deps caused |
export * | sideEffects: false is set in the package |
Scoring
Critical gates: D1=0, D4=0, D6=0, D8=0 -- any triggers FAIL.
N/A handling: Exclude dimensions with INSUFFICIENT DATA, SKIPPED, or
INHERITED from both numerator and denominator.
| Grade | Percentage |
|---|
| A | >= 85% |
| B | 70-84% |
| C | 50-69% |
| D | < 50% |
Phase 4: Report
Save to: zuvo/audits/dependency-audit-[YYYY-MM-DD].md — at the project root (zuvo/ resolves via git rev-parse --show-toplevel; override $ZUVO_OUTPUT_DIR. See ../../shared/includes/report-output-location.md).
REQUIRED: emit the Tool Availability Block (template in ../../shared/includes/codesift-setup.md) at the top of the report, after the title and before findings. Auditing degraded runs depends on this — do NOT skip it.
Report Structure
# Dependency & Coupling Audit Report
## Metadata
| Field | Value |
|-------|-------|
| Project | [name] |
| Date | [YYYY-MM-DD] |
| Package Manager | [npm/pnpm/yarn/bun] |
| Scope | [full / path] |
| Total prod deps | [N] |
| Total dev deps | [N] |
## Executive Summary
**Score: [N] / [MAX]** -- [A/B/C/D or FAIL]
| Metric | Count |
|--------|-------|
| CRITICAL findings | N |
| HIGH findings | N |
| MEDIUM findings | N |
[2-3 sentence summary]
## Dimension Scores
| # | Dimension | Score | Max | Tool Used | Notes |
|---|-----------|-------|-----|-----------|-------|
| D1 | Supply Chain | [N] | 15 | <pm> audit | |
| D2 | Freshness | [N] | 10 | <pm> outdated | |
| D3 | Dead Deps | [N] | 10 | knip / grep | |
| D4 | Licenses | [N] | 8 | license-checker | |
| D5 | Bundle Weight | [N] | 8 | Bundlephobia | |
| D6 | Circular Deps | [N] | 12 | dep-cruiser / madge | |
| D7 | Coupling Metrics | [N] | 10 | dep-cruiser / grep | |
| D8 | Architecture | [N] | 12 | dep-cruiser / grep | |
| D9 | Barrel Health | [N] | 7 | grep | |
| D10 | Change Coupling | [N] | 8 | git log | |
| **Total** | | **[N]** | **[M]** | | |
## Critical Gate Status
[D1, D4, D6, D8 -- PASS/FAIL per gate]
## Delete These Tomorrow
[Unused deps that can be removed with zero code changes]
## Findings (sorted by severity)
[Per finding: ID, severity, dimension, description, fix]
## Cross-Cutting Patterns
| Pattern | Dims | Impact |
|---------|------|--------|
| Barrel causing circular deps | D9+D6 | Fix barrel, cycles disappear |
| God module + high churn | D7+D10 | Max blast radius on hot code |
| Unused dep with known CVE | D3+D1 | Dead code + security risk |
## Remediation Roadmap
### Quick Wins (< 1 hour)
### Short-term (1 day)
### Medium-term (1 week)
Phase 5: Next-Step Routing
RECOMMENDED NEXT ACTION
------------------------------------
D1 CRITICAL (CVE) -> npm audit fix or manual upgrade
D4 GPL in production -> replace with MIT/Apache alternative
D6 runtime circular dep -> zuvo:refactor [module path]
D8 boundary violation -> zuvo:refactor [violating file]
D9 barrel causing cycles -> zuvo:refactor [barrel file]
D10 high change coupling -> zuvo:refactor [coupled files]
Score < 60% -> prioritize "Delete These Tomorrow" list first
Score >= 85% -> schedule next audit in 3 months
------------------------------------
Completion Gate Check
Before printing the final output block, verify every item. Unfinished items = pipeline incomplete.
COMPLETION GATE CHECK
[ ] Tool availability printed: PM audit, knip, dep-cruiser, license-checker
[ ] D1 supply chain: CRITICAL/HIGH CVEs checked for reachability
[ ] D4 license: GPL/AGPL in production flagged
[ ] D6 circular dependency detection ran
[ ] Critical gates printed: D1, D4, D6, D8
[ ] "Delete These Tomorrow" section present
[ ] Report saved to zuvo/audits/
[ ] Run: line printed and appended to log
DEPENDENCY-AUDIT COMPLETE
Score: [N] / [MAX] -- [grade]
Package Manager: [npm/pnpm/yarn/bun]
Dimensions: [N scored] | Critical gates: [PASS/FAIL]
Findings: [N critical] / [N total]
Validity Gate (REQUIRED — print BEFORE Run line, AFTER retro append + append-runlog)
VALIDITY GATE
triggers_held: language=<X> python=<yes|no>
required_tool_calls:
find_dead_code: [<N> unused exports | NOT_CALLED — VIOLATES_TRIGGER]
find_unused_imports: [<N> | NOT_CALLED — VIOLATES_TRIGGER]
find_circular_deps: [<N> cycles | NOT_CALLED — VIOLATES_TRIGGER]
fan_in_fan_out: [<max_in>/<max_out> | NOT_CALLED — VIOLATES_TRIGGER]
check_boundaries: [<N> violations | NOT_CALLED — VIOLATES_TRIGGER]
audit_scan: [<N> findings | NOT_CALLED — VIOLATES_TRIGGER]
analyze_python_deps: [<N> CVEs | not_required (no Python) | NOT_CALLED — VIOLATES_TRIGGER]
stack_specific: [<result> | not_required | NOT_CALLED — VIOLATES_TRIGGER]
postamble:
retros_log_appended: [yes(bytes_added=N) | NOT_APPENDED]
retros_md_appended: [yes(entry_count=N) | NOT_APPENDED]
verify_audit_pass: [yes(<verified>/<total>) | NOT_RUN | REJECTED]
gate_status: [PASS | FAIL — <which gates missing>]
If gate_status = FAIL → VERDICT = INCOMPLETE.
Append the Run line via the retro-gated wrapper (NOT direct >> runs.log):
printf '%b\n' "$RUN_LINE" | ~/.zuvo/append-runlog
Run: dependency-audit - -dimensions
Retrospective (REQUIRED)
Follow the retrospective protocol from retrospective.md.
Gate check → structured questions → TSV emit → markdown append.
If gate check skips: print "RETRO: skipped (trivial session)" and proceed.
After printing this block, append the Run: line value (without the Run: prefix) to the log file path resolved per run-logger.md.
VERDICT: PASS (0 critical findings), WARN (1-3 critical), FAIL (4+ critical).
Execution Notes
- All commands use the resolved
TARGET_ROOT from argument parsing
- CodeSift integration follows
codesift-setup.md
- Agent dispatch follows
env-compat.md
- Tool unavailability degrades individual dimensions, not the entire audit
- Yarn version detection is critical: Classic (1.x) and Berry (2+) have
different command syntax
npm query selectors are npm-only; pnpm/yarn/bun use lockfile grep as
fallback--no-api flag skips Bundlephobia and OpenSSF calls for air-gapped or
rate-limited environments
