Code Health Auditor

Purpose: Run a comprehensive codebase health check in one command. Orchestrates four analysis passes — dependency audit, security scan, complexity analysis, and test coverage — and produces a unified, graded health report with prioritized action items. The "annual physical" for your codebase.

Invocation

code

/health [path]

Examples:

/health — audit the entire current directory
/health src/ — audit a specific subdirectory
/health --quick — skip complexity analysis, just deps + security

Analysis Passes

Pass 1: Dependency Audit

Run the package manager's built-in audit tool:

bash

# Node.js
npm audit --json 2>/dev/null || yarn audit --json 2>/dev/null

# Python
pip-audit --format json 2>/dev/null || safety check --json 2>/dev/null

# Go
govulncheck ./... 2>/dev/null

# Ruby
bundle audit 2>/dev/null

Check for:

CVEs with CVSS score ≥ 7.0 (High/Critical) → CRITICAL
CVEs with CVSS score 4.0–6.9 (Medium) → HIGH
Packages more than 2 major versions behind → MEDIUM
Packages more than 1 minor version behind → LOW
Packages with 0 downloads in 6 months (zombie deps) → LOW
License violations (GPL in commercial project, etc.) → HIGH

Pass 2: Security Scan

Pattern-based scan across all source files:

Hardcoded secrets:

code

patterns: /(?:api_key|secret|password|token|auth)\s*=\s*['"][^'"]{8,}['"]/i

SQL injection:

code

patterns: string interpolation inside SQL strings, format strings with user input

Command injection:

code

patterns: os.system/exec.Command/shell=True with non-constant arguments

OWASP Top 10 patterns:

A01 Broken Access Control — missing auth checks on routes
A02 Cryptographic Failures — MD5/SHA1 for password hashing
A03 Injection — SQL, command, LDAP, XPath
A05 Security Misconfiguration — debug mode on, verbose errors in prod
A07 Auth Failures — hardcoded credentials, weak token generation

Pass 3: Complexity Hotspots

Scan source files for complexity indicators:

Metric	Warning Threshold	Critical Threshold
Function length	> 50 lines	> 100 lines
File length	> 300 lines	> 500 lines
Nesting depth	> 3 levels	> 5 levels
Function arguments	> 5 params	> 8 params
Duplicate blocks	> 10 lines identical	> 20 lines identical

Report top 10 most complex files ranked by violation count.

Pass 4: Test Coverage Assessment

Identify coverage gaps without running the full suite:

bash

# Check for test files
find . -name "*.test.*" -o -name "*.spec.*" -o -name "*_test.*" | head -50

Cross-reference against source files to find:

Source files with no corresponding test file → flagged
Recently modified files with no recent test changes → flagged
Critical paths with no tests: auth, payments, data mutations → HIGH

Output Format

markdown

# Code Health Report — [date]
**Path:** [audited path]
**Languages:** [detected]

---

## Overall Grade: [A / B / C / D / F]

| Category | Score | Issues |
|----------|-------|--------|
| Dependencies | 90/100 | 1 outdated |
| Security | 75/100 | 1 HIGH, 2 MEDIUM |
| Complexity | 85/100 | 3 complex files |
| Test Coverage | 60/100 | 8 untested modules |
| **Overall** | **77/100** | **B** |

---

## 🔴 Critical — Fix Immediately

[List of CRITICAL findings with file:line and fix command]

---

## 🟡 High — Fix This Sprint

[List of HIGH findings]

---

## 🔵 Medium — Track in Backlog

[List of MEDIUM findings]

---

## 💚 Low — Nice to Have

[List of LOW findings]

---

## Quick Wins

Commands you can run right now to fix the easiest issues:

```bash
npm audit fix          # Auto-fix compatible CVEs
npm update --save      # Update to latest compatible versions

Trend

[If run previously: show improvement/regression since last run]

code


---

## Grading Scale

| Score | Grade | Meaning |
|-------|-------|---------|
| 90-100 | A | Excellent — production-ready |
| 80-89 | B | Good — minor improvements needed |
| 70-79 | C | Fair — some attention required |
| 60-69 | D | Poor — significant issues |
| < 60 | F | Critical — immediate action needed |

---

## Rules

- Run all passes even if one fails — partial results are better than no results
- Critical/High findings always surfaced first regardless of category
- Quick Wins section must include actual runnable commands, not vague suggestions
- If no test files found at all: automatically rate Test Coverage as 0/100 (F)
- Never fail silently — if a tool is missing, note it and skip that check with a warning
- Security findings always overrule the grade — one CRITICAL finding caps at D

Code Health Auditor

Code Health Auditor

Invocation

Analysis Passes

Pass 1: Dependency Audit

Pass 2: Security Scan

Pass 3: Complexity Hotspots

Pass 4: Test Coverage Assessment

Output Format

Trend

Created by

Info

Embed

Export