Source Command Tech Audit Codebase

source-command-tech-audit-codebase

Use this skill when the user asks to run the migrated source command tech-audit-codebase.

Command Template

Codebase Audit — StarMapper

Performs a scored health audit across 7 categories. Output: tier assessment, weighted global score, and prioritized action plan.

Usage

/tech:audit-codebase              # Full audit
/tech:audit-codebase --category secrets   # Single category
/tech:audit-codebase --fix        # Audit + auto-fix safe issues
/tech:audit-codebase --json       # JSON output for CI

Scoring System

Each category scored 0–10. Weighted global score:

Global score = sum(score × weight) / sum(weights)

Tier System

Phase 1: Secrets & Tokens (weight 2x)

# Search for hardcoded secrets
grep -r "ghp_\|github_pat_\|token.*=.*['\"][a-zA-Z0-9]\{20,\}" src/ --include="*.ts" --include="*.tsx"
grep -r "jawgmap\|geoapify\|neon\.tech" src/ --include="*.ts" --include="*.tsx" | grep -v "process.env"
grep -r "GITHUB_TOKEN\|JAWGMAP\|GEOAPIFY" src/ --include="*.ts" --include="*.tsx" | grep -v "process.env"

Check: All secrets accessed via process.env.*, never hardcoded. .env.local not committed.

Score: 10 if zero hardcoded secrets. -3 per finding.

Phase 2: Security (weight 2x)

Check:

• CSP headers present in next.config.ts
• No dangerouslySetInnerHTML without sanitization
• No eval() or dynamic require() in API routes
• No raw SQL injection vectors (Prisma parameterizes, check raw queries)
• XSS vectors in popup innerHTML (MapLibre popups use innerHTML — verify escaping)

Score: 10 if clean. -2 per finding.

Phase 3: Dependencies (weight 1x)

rtk pnpm outdated

Check major outdated deps (Next.js, MapLibre, Prisma). Flag known CVEs if any.

Score: 10 if up-to-date. -1 per major outdated, -3 per CVE.

Phase 4: Structure (weight 1.5x)

# Check for function keyword (should be arrow functions only)
grep -rn "^export function\|^  function " src/ --include="*.ts" --include="*.tsx"
# Check for interface (should be type)
grep -rn "^export interface\|^interface " src/ --include="*.ts" --include="*.tsx"
# Check for console.log left in code
grep -rn "console\.log" src/ --include="*.ts" --include="*.tsx"
# Check file naming (should be kebab-case)
find src/ -name "*.tsx" -o -name "*.ts" | grep -E "[A-Z]" | grep -v "\.d\.ts"

Score: 10 if clean. -1 per function keyword, -0.5 per interface, -0.5 per console.log.

Phase 5: Rate Limit Safety (weight 2x) — StarMapper-specific

# Nominatim calls must have delay
grep -rn "callNominatim\|nominatim\|openstreetmap" src/ --include="*.ts"
# Check for Promise.all on geocoding (forbidden)
grep -rn "Promise.all.*geocod\|geocod.*Promise.all" src/ --include="*.ts"
# GitHub rate limit check
grep -rn "X-RateLimit-Remaining\|rateLimit" src/ --include="*.ts"

Check:

• Nominatim calls have 1100ms delay between them (sequential, not parallel)
• Circuit breaker present for Jawg/Geoapify (3 errors → 1h cooldown)
• GitHub GraphQL checks X-RateLimit-Remaining before each call
• No Promise.all() on Nominatim calls

Score: 10 if all guards present. -3 per missing critical guard.

Phase 6: Cache Integrity (weight 1.5x) — StarMapper-specific

# Geocache key normalization
grep -rn "toLowerCase.*trim\|trim.*toLowerCase" src/lib/geocoder.ts
# DB health guard on writes
grep -rn "checkDbHealth\|dbHealth" src/lib/user-cache.ts
# Compression before large cache writes
grep -rn "pointsGz\|CompressionStream\|gzip" src/app/\[owner\]/\[repo\]/page.tsx 2>/dev/null || grep -rn "pointsGz\|CompressionStream\|gzip" src/app/ --include="*.tsx"

Check:

• GeoCache key always location.toLowerCase().trim()
• checkDbHealth() called before user-level cache writes
• StargazerCache write uses compressed format (pointsGz, unmappedGz)

Score: 10 if all patterns correct. -3 per missing guard.

Phase 7: Code Quality (weight 1x)

rtk tsc
pnpm lint

Score: 10 if zero errors. -1 per TypeScript error, -0.5 per ESLint error.

Output Format

## StarMapper Codebase Audit

**Date**: {date}
**Global Score**: {score}/10 — {Tier 🔴/🟡/🟢}

| Category | Score | Weight | Notes |
|----------|-------|--------|-------|
| Secrets & Tokens | X/10 | 2x | ... |
| Security | X/10 | 2x | ... |
| Dependencies | X/10 | 1x | ... |
| Structure | X/10 | 1.5x | ... |
| Rate Limit Safety | X/10 | 2x | ... |
| Cache Integrity | X/10 | 1.5x | ... |
| Code Quality | X/10 | 1x | ... |

## Critical Issues (block release)
[List of Tier 1 findings]

## Action Plan
### Quick Wins (< 1h)
1. ...

### This Sprint (2-4h)
2. ...

### Backlog
3. ...