subhajitlucky/codebase-doctor

**Models build. Codebase Doctor verifies.**
> It finds the thing, and it never guesses.
Most repository scanners fail in one of two ways: they flood you with false positives, or they silently skip the hard case and report "clean." Codebase Doctor does neither. Every finding carries evidence, every audit reports what it *couldn't* analyze, and a clean run means the scope was actually checked.
That last line is the point. Most tools print findings and stop. This one tells you what it *didn't* check, every single run.
---
Why this exists
Coding agents ship code faster than review can keep up. The failure isn't that agents can't write code — it's that nothing **verifies** what they wrote before it merges.
Codebase Doctor is that verification step. It builds a source graph, scans for committed secrets, dependency drift, unsafe Dockerfiles, workflow injection, RLS mistakes, and accessibility regressions — then tells you exactly what it could not verify.
**Benchmarked, not vibes**: 17 seeded single-defect fixtures score **100% rule recall and zero medium+ false positives** (results, reproducible with npm run benchmark).
**Red-teamed**: an adversarial mutation corpus tries to hide each defect in a different shape — **11/11 mutants caught, 7/7 controls clean**, gated in CI (corpus, reproducible with npm run red-team).
**Cross-checked**: two independently written offline analyzers (this repo's sql-rls and rls-doctor) run over the same SQL corpus — **10 findings matched, 0 severity mismatches, 1 documented coverage difference**, safe schema clean under both (scoreboard, npm run differential).
**Field study**: of 100 agent-configured public repositories, **23% ship at least one high-severity finding** — 10% have broken imports, 4% committed key material, 11% risky agent configuration (report, anonymized and reproducible).
Install
Quick start
demo needs no configuration and no repository: it builds a disposable git
fixture with a tracked secret and a broken import, audits the simulated agent
edit with the real pipeline, prints the blast radius, and exits 1 to show the
CI gate. Nothing outside a temp directory is touched.
Options
Code review
review is the pull-request command. It always audits changed scope, narrows
findings to added diff lines, and prints a verdict — APPROVE, COMMENT, or
REQUEST_CHANGES — so unrelated old issues never fail a PR:
- --format markdown renders a PR-comment-ready body with the verdict,
findings, source impact, and coverage limitations.
- --format github emits ::error / ::warning / ::notice workflow
commands that annotate pull-request diffs inline from Actions logs, with no
network access.
- A finding on an unchanged line is out of scope for the verdict and counted
as omitted; the full audit still reports it. --all-findings disables
narrowing, and --output writes the report to a file as well as
stdout.
- With --baseline, only *new* findings in the diff gate the verdict.
- Exit 1 means the review requests changes; exit 2 is an operational
failure, never a clean result. Inspect coverage before calling the reviewed
diff verified or clean.
GitHub Action
Findings appear in the Security tab. See docs/github-action.md.
---
What it checks
Secrets — working tree and history
Precision-first and not exhaustive: it detects private-key material, provider-token shapes, paired AWS credentials, credential-bearing URLs, and high-confidence sensitive assignments. A Git-ignored .env is normal storage and is **not** a finding; a tracked one containing a real credential is.
security/secrets-history catches the case that matters most: a secret committed and later deleted from the working tree, so a rotated-looking repo doesn't hide an exposure. It inspects the most recent 200 commits across all branches without ever checking out, rewriting, or executing repository content. Changed audits scope the history log to changed paths, so deleting a leaked file cannot review clean.