/health - Project Health Score

Generate a comprehensive health score for your project or a specific module.

Scope: $ARGUMENTS (default: full project)

Scoring Categories

Category	Weight	What it measures
Architecture	25%	ARCHITECTURE.md conformance
Tests	20%	Coverage, test presence
Security	20%	OWASP compliance, secrets
Performance	15%	Bundle size, caching
Maintainability	20%	Code complexity, docs

Workflow

Step 1: Gather Metrics

# File counts
find src -name "*.ts" -o -name "*.tsx" | wc -l
find src -name "*.test.ts" -o -name "*.spec.ts" | wc -l

# TypeScript check
npx tsc --noEmit 2>&1 | grep -c "error"

# Test coverage (if available)
npm test -- --coverage --json 2>/dev/null

# Bundle analysis
npm run build 2>&1 | grep -E "size|chunk"

# Security checks
grep -rn "dangerouslySetInnerHTML\|v-html\|eval(" src/ 2>/dev/null | wc -l
grep -rn "password\|secret\|token" src/ --include="*.ts" 2>/dev/null | wc -l

Step 2: Calculate Scores

Architecture Score (25 points)

+5  ARCHITECTURE.md exists
+5  Module structure follows patterns
+5  No cross-module imports
+5  Correct layer usage (service→adapter→hook→component)
+5  Naming conventions followed

Test Score (20 points)

+5  Test files exist
+5  Coverage > 50%
+5  Coverage > 70%
+5  Coverage > 80%
+5  All tests passing
-2  Each failing test

Security Score (20 points)

+5  No hardcoded secrets
+5  No dangerous HTML methods
+5  Input validation present
+5  Auth implementation exists
+5  Secure headers configured
-5  Each critical vulnerability

Performance Score (15 points)

+5  Lazy loading implemented
+5  Query caching present (staleTime)
+5  Bundle < 500KB
+5  No N+1 queries detected
-3  Each performance warning

Maintainability Score (20 points)

+5  README.md exists
+5  Files < 200 lines (average)
+5  Low cyclomatic complexity
+5  TypeScript strict mode
+5  No 'any' types
-2  Each 'any' type found

Step 3: Generate Report

Output Format

═══════════════════════════════════════════════════════════════
                    PROJECT HEALTH REPORT
═══════════════════════════════════════════════════════════════

   ██████████████████████████████████████░░░░░░░░  78/100

═══════════════════════════════════════════════════════════════

CATEGORY BREAKDOWN
───────────────────────────────────────────────────────────────

Architecture    ████████████████████░░░░░  20/25
  ✓ ARCHITECTURE.md exists
  ✓ Module structure correct
  ✗ Cross-module imports found (3 violations)
  ✓ Layer usage correct
  ✓ Naming conventions followed

Tests           ████████████████░░░░░░░░░  16/20
  ✓ Test files exist (42 specs)
  ✓ Coverage: 72%
  ✗ Coverage < 80% target
  ✓ All tests passing

Security        █████████████████████████  20/20
  ✓ No hardcoded secrets
  ✓ No dangerous HTML methods
  ✓ Input validation present
  ✓ Auth implementation exists
  ✓ Secure headers configured

Performance     █████████████░░░░░░░░░░░░  10/15
  ✓ Lazy loading implemented
  ✗ Missing staleTime in 5 queries
  ✓ Bundle: 320KB
  ✗ Potential N+1 in user.service.ts

Maintainability ████████████░░░░░░░░░░░░░  12/20
  ✓ README.md exists
  ✗ 3 files > 200 lines
  ✓ Low complexity
  ✓ TypeScript strict mode
  ✗ 12 'any' types found

═══════════════════════════════════════════════════════════════

TOP ISSUES TO FIX (by impact)
───────────────────────────────────────────────────────────────

1. 🔴 [Architecture] Cross-module imports
   Files: src/modules/orders/components/UserCard.tsx
   Fix: Move shared components to src/shared/

2. 🟡 [Performance] Missing staleTime in queries
   Files: src/modules/*/hooks/use*.ts (5 files)
   Fix: Add staleTime to all useQuery calls

3. 🟡 [Maintainability] Files exceeding 200 lines
   Files: src/modules/auth/components/LoginForm.tsx (284 lines)
   Fix: Split into smaller components

4. 🟡 [Tests] Coverage below 80%
   Current: 72%
   Fix: Add tests for uncovered modules

═══════════════════════════════════════════════════════════════

TREND (if previous scans exist)
───────────────────────────────────────────────────────────────

  Previous: 71/100 (2024-01-10)
  Current:  78/100 (2024-01-20)
  Change:   +7 points ↑

═══════════════════════════════════════════════════════════════

RECOMMENDATIONS
───────────────────────────────────────────────────────────────

  @reviewer  - Run /review-fix-violations to auto-fix
  @tester    - Add tests for auth module
  @builder   - Refactor LoginForm.tsx

═══════════════════════════════════════════════════════════════
  Generated: 2024-01-20 14:30 | Scan time: 12s
═══════════════════════════════════════════════════════════════

Score Interpretation

Score	Grade	Status
90-100	A	Excellent
80-89	B	Good
70-79	C	Acceptable
60-69	D	Needs Work
0-59	F	Critical

Save History

Save scan to .claude/health-history.json:

{
  "scans": [
    {
      "date": "2024-01-20T14:30:00Z",
      "score": 78,
      "categories": {
        "architecture": 20,
        "tests": 16,
        "security": 20,
        "performance": 10,
        "maintainability": 12
      }
    }
  ]
}

Quick Mode

For fast feedback (< 5 seconds):

/health quick

Only checks:

TypeScript errors
Test status
File count

Anti-Rationalization

Excuse	Reality
"The score doesn't matter, the app works"	Working today doesn't mean maintainable tomorrow. The score measures long-term health.
"We'll improve the score after the deadline"	After the deadline there's another deadline. Measure now, fix incrementally.
"80% coverage is overkill"	80% is the baseline. Below that, regressions hide in untested code.
"Security checks are paranoid"	One vulnerability costs more than 100 health scans. Paranoia is appropriate.

Rules

Be objective - Numbers, not opinions
Prioritize issues - Most impactful first
Show trends - Compare to previous scans
Actionable - Suggest specific fixes
Save history - Track progress over time

health