Dark Code Audit

Scan a repository and produce a tiered report of where human comprehension has gone missing. "Dark code" is code that works correctly but that no human understood at any point in its lifecycle -- it was generated, merged, and deployed without anyone building a mental model of what it does or why.

Dark code is not bad code. It passes linters, tests, and style checks. The danger is that when it breaks, nobody knows how to fix it because nobody ever understood it.

Phase 1: Intake

Ask the user for ONE of:

• A repository path to scan (local)
• A GitHub repo URL (will clone or use gh CLI)
• A specific subdirectory to scope the audit

If no input is provided, scan the current working directory.

Scoping options (ask if repo is large):

• Full repo scan (default)
• Specific directories only
• Files changed in the last N days
• Files with fewer than N commits

Phase 2: Module Discovery

Identify the natural module boundaries in the codebase:

1. Language detection: Identify primary language(s) from file extensions
2. Module mapping: Group files into logical modules based on:
   • Directory structure (each top-level src directory = module)
   • Package/module declarations (Python packages, Go packages, JS modules)
   • Service boundaries (Dockerfiles, serverless configs, API route groups)
3. Size filtering: Skip vendored code, node_modules, generated files, lock files, and build artifacts

Output a module inventory before proceeding to scoring.

Phase 3: Darkness Scoring

Score each module on four dimensions (25% weight each). Each dimension scores 0-100 where 100 = maximum darkness (worst).

Dimension 1: Authorship Signal (25%)

Measures whether the code has traceable human authorship or appears to be AI-generated without human review.

How to measure:

• git log --format='%an' -- <module_path> | sort | uniq -c | sort -rn for author diversity
• git log --oneline -- <module_path> and classify commit message quality
• Grep for AI-generation markers in source files and commit messages

Dimension 2: Decision Trail (25%)

Measures whether the why behind architectural choices is documented anywhere.

How to measure:

• Search for ADR files (docs/adr/, docs/decisions/, ADR-*.md)
• Grep CLAUDE.md files for references to the module name or key functions
• git log --format='%s%n%b' -- <module_path> and classify messages as "what" vs "why"
• Sample 5-10 non-trivial functions and check for explanatory comments

Dimension 3: Behavioral Contracts (25%)

Measures whether the module's expected behavior is specified anywhere outside the implementation itself.

How to measure:

• Check for test files corresponding to module files
• Read test files: do they test behavior ("when X happens, Y should result") or implementation ("mock A, assert B was called")?
• Check public function/class signatures for type annotations and docstrings
• Look for contract/schema validation (JSON Schema, Pydantic models, Zod schemas)

Dimension 4: Dependency Awareness (25%)

Measures whether the module's role in the larger system is understood and documented.

How to measure:

• Grep the codebase for imports of this module
• Count dependents (modules that import from this one)
• Check for CODEOWNERS or equivalent ownership files
• Search architecture docs, README files, and system diagrams for references

Score Calculation

module_darkness = (authorship_score * 0.25) + (decision_trail_score * 0.25) + 
                  (behavioral_contracts_score * 0.25) + (dependency_awareness_score * 0.25)

Clamp each dimension to 0-100 before averaging. Final score is 0-100.

Darkness Tiers

Phase 4: Output

Produce a tiered report with two sections:

Section 1: Summary Heat Map

## Dark Code Heat Map: [Repo Name]

Scanned [N] modules, [M] files, [L] lines of code
Scan date: [date]

### Overall Darkness Distribution
- DARK (80-100):      [N] modules ([X]% of codebase by LOC)
- DIM (50-79):        [N] modules ([X]% of codebase by LOC)
- UNDERSTOOD (0-49):  [N] modules ([X]% of codebase by LOC)

### Aggregate Score: [weighted average by LOC] / 100

### Module Scores
| Module | Darkness | Authorship | Decision Trail | Contracts | Dependencies | LOC |
|--------|----------|------------|----------------|-----------|--------------|-----|
| [path] | [score]  | [score]    | [score]        | [score]   | [score]      | [N] |
| ...    | ...      | ...        | ...            | ...       | ...          | ... |

(Sorted by darkness score descending)

Section 2: Drill-Down TODO List

For each module scoring above the darkness threshold (default: 80):

### [Module Path] -- Darkness Score: [N]/100

**Why it's dark:**
- [Specific gaps from each dimension that contributed to the high score]

**Highest-impact actions to reduce darkness:**
1. [Most impactful action] -- reduces score by ~[N] points
   - Example: "Add behavioral tests for the 3 public functions in this module"
2. [Second action] -- reduces score by ~[N] points
3. [Third action] -- reduces score by ~[N] points

**Estimated effort:** [Quick fix / Half-day / Multi-day]

Section 3: Trend Data (if prior scan exists)

If a previous scan report exists in the repo (.dark-code-audit/ directory), compare:

### Trend Since Last Scan ([date])
- Modules that got DARKER: [list with delta]
- Modules that got LIGHTER: [list with delta]  
- New modules (unscored): [list]
- Removed modules: [list]
- Overall darkness delta: [+/- N points]

Phase 5: Persistence

After producing the report:

1. Save the raw scores as JSON to .dark-code-audit/latest.json for trend comparison
2. Offer to save the full report as .dark-code-audit/report-[date].md
3. If a prior scan exists, include trend data automatically

JSON schema for latest.json:

{
  "scan_date": "2026-04-13",
  "repo": "repo-name",
  "modules": [
    {
      "path": "src/module",
      "darkness_score": 85,
      "authorship": 90,
      "decision_trail": 80,
      "behavioral_contracts": 85,
      "dependency_awareness": 85,
      "loc": 1200
    }
  ],
  "aggregate_score": 72,
  "threshold": 80
}

Configuration

Verification

Before producing the final report:

• Every discovered module must have a score (nothing skipped without explanation)
• Scores must be mathematically consistent with dimension inputs
• TODO actions must be specific to the module, not generic advice
• Trend data (if present) must reference the actual prior scan, not estimates

Adoption Path

Source

Inspired by Nate Jones' "Dark Code" framework (2026-04-13): code generated by AI that no human ever understood at any point in its lifecycle. The audit maps where comprehension has gone missing so teams can systematically reattach understanding to their codebase.