# Source Command Tech Audit Codebase

> 7-category codebase health audit for StarMapper with weighted scoring and tier system. Run before major releases or architectural changes.

- Skill: `florianbruniaux/source-command-tech-audit-codebase` (Agent Skill)
- Install (CLI): `npx skillmds@latest add florianbruniaux/source-command-tech-audit-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/florianbruniaux/source-command-tech-audit-codebase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: FlorianBruniaux (https://skillmd.com/u/florianbruniaux)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/florianbruniaux/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:

| Category | Weight | Focus |
|----------|--------|-------|
| Secrets & Tokens | 2x | Env vars, GitHub tokens, API keys in code |
| Security | 2x | XSS, injection, CSP headers |
| Dependencies | 1x | Outdated packages, known CVEs |
| Structure | 1.5x | File naming, import order, conventions |
| Rate Limit Safety | 2x | Nominatim delay, circuit breakers, GitHub limit checks |
| Cache Integrity | 1.5x | GeoCache keys, StargazerCache compression, DB health guards |
| Code Quality | 1x | TypeScript errors, ESLint violations, no-any, no console.log |

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

## Tier System

| Tier | Score | Status |
|------|-------|--------|
| 🔴 Tier 1 | 0–4 | Critical — block release |
| 🟡 Tier 2 | 5–7 | Improvement required — address within sprint |
| 🟢 Tier 3 | 8–10 | Production ready |

## Phase 1: Secrets & Tokens (weight 2x)

```bash
# 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)

```bash
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)

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
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. ...
```