Codebase Doctor

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.

npx -y codebase-doctor audit . --changed --format brief

codebase-doctor brief

scope=full findings=1 shown=1 coverage=incomplete score=80 [high] security/secrets/provider-token src/config.ts:12 — Have an authorized human or external coding agent remove the value and rotate it, then rerun the audit. coverage-limitations: validation: skipped, database: skipped, security: partial

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

npx -y codebase-doctor audit .          # no install

npm install -g codebase-doctor # global

Quick start

codebase-doctor demo                             # disposable fixture: secret, broken import, blast radius

codebase-doctor bisect security/secrets/provider-token . # when did this enter history? codebase-doctor audit . --json # full audit codebase-doctor audit . --changed --json # just my diff codebase-doctor audit . --changed --base main --json # PR review codebase-doctor audit . --format sarif # GitHub code scanning codebase-doctor audit . --format html > report.html # shareable standalone report codebase-doctor verify . --baseline before.json # confirm fixes landed

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

--run-checks          Permit configured validation commands

--changed Audit Git changes and their affected scope (implied by review) --base Compare changed scope from the merge base with this ref --json Emit schema-versioned JSON --format Output format: text, json, sarif, brief, or html (review adds markdown, github) --all-findings Review only: include findings outside the changed lines --output Review only: write the report to a file as well as stdout --exclude Exclude a repository-relative path glob; repeatable --baseline Compare with a prior Codebase Doctor JSON report --timeout Per-command timeout (default: 120000) --fail-on info|low|medium|high|critical|none (default: high) --require-complete Exit 2 when audit coverage is incomplete --max-findings Cap brief output (default: 100) --score Print only the Repo Health score --badge Print a shields.io badge URL for the Repo Health score --receipt Write a portable coverage receipt (digest-verified) --receipt-key Sign the receipt with an Ed25519 private key (PEM) --pheromone Write a privacy-bounded signal (rules and counts only) --with-database Permit live PostgreSQL catalog access --with-advisories Opt-in OSV advisory lookup over lockfile packages --database-schema Schema to inspect; repeatable (default: public) --database-timeout Catalog statement timeout in ms (default: 10000)

Code review

review is the pull-request command. It always audits changed scope, narrows findings to added diff lines, and prints a verdict — NO_CHANGES, APPROVE, COMMENT, or REQUEST_CHANGES — so unrelated old issues never fail a PR and an empty checkout is never represented as an approval:

codebase-doctor review . --base origin/main --format markdown > review.md

codebase-doctor review . --base origin/main --format github codebase-doctor review . --format json # includes a machine-readable review envelope codebase-doctor review . --base origin/main --receipt review.json codebase-doctor review . --base origin/main --receipt review.json --receipt-key key.pem

• --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.
• An empty diff reports NO_CHANGES, not APPROVE. Use --require-base in CI to fail closed when the base ref was not supplied.
• --receipt writes a portable review receipt with the verdict, diff-scope counts, coverage limitations, and finding fingerprints. Add --receipt-key to sign it with Ed25519; verify-receipt checks integrity and prints the review 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

permissions:

contents: read security-events: write

steps:

• uses: actions/checkout@v4
• uses: subhajitlucky/codebase-doctor@v0.5.0 with: format: sarif upload: "true" fail-on: high

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.

Matched values are withheld from every finding, fingerprint, error, and report. Codebase Doctor never prints your secrets — including in its own SARIF. An external authorized human or agent must remediate the shareable content and rotate or revoke the credential, then rerun the same audit.

Dependencies

security/dependencies is read-only and offline. Lockfile-aware for npm lockfile versions 2 and 3, pnpm (v5+), Yarn (classic and Berry), Bun, and Python poetry and uv locks. Remaining ecosystems stay explicitly unsupported rather than receiving guessed findings.

Rule families: security/dependencies/missing-lockfile, security/dependencies/manifest-lock-drift, security/dependencies/insecure-source, security/dependencies/mutable-git-source, security/dependencies/missing-integrity, security/dependencies/workspace-registry-resolution, security/dependencies/competing-npm-lockfiles, and security/dependencies/competing-lockfiles.

A normal semver range such as ^5.0.0 is not a finding when the lock agrees. Raw dependency specifications and resolved URLs are withheld from reports and never enter a fingerprint. An external authorized human or agent must correct the metadata and rerun the same scope. Inspect coverage before calling the dependency graph clean or verified.

It never invokes npm, another package manager, a shell, an installer, or a lifecycle script, and makes no network request. It makes no CVE or advisory claim on its own. Python coverage parses poetry.lock and uv.lock package blocks and pyproject.toml Poetry and PEP 621 declarations with a bounded line scanner (no TOML dependency): insecure transports, unpinned git references, missing hash evidence, missing lockfiles, competing lockfiles, and decidable manifest-lock drift are reported, while undecidable specifiers, markers, direct-URL drift, transitive-only entries, and requirements-only layouts stay visible as partial coverage.

--with-advisories performs one bounded OSV lookup against resolved packages. Only names, versions, and ecosystems leave the machine.

Source impact — what breaks if I change this file

repository/source-graph uses a real syntax parser (never executes your code) to build a static import graph across JS/TS, Python, Go, Java, and Rust. In changed mode it walks reverse edges and reports a deterministic shortest impact path from each changed file.

Changed mode is mixed-scope per doctor, not a universal file filter: Project Doctor structural rules run with the full repository snapshot and may report findings outside changed paths for manifests, lockfiles, workspaces, and test visibility. File-local doctors (backend, frontend, infrastructure, agent surface, performance) examine only changed files present in the inventory, so changed audits stay proportional to the change. Configured validation check plans are built from full project topology and then filtered to affectedProjectIds. Static SQL selects affected migration streams and replays full current history for every selected stream. Live database remains a full observed schema-set audit only with separately requested --with-database. Zero changed findings is not a full clean result.

repository/source-graph recognizes static import, re-export, type-only import, literal require, and literal dynamic import edges across JavaScript and TypeScript (plus Python, Go, Java, and Rust) with a real syntax parser that never executes repository code. Cycles are valid topology, not f