axonscanner

Audit whether your codebase is as real as it claims.

AI writes code 5–7× faster than anyone can read it. Pull requests are up, review time is up, and "done" increasingly means a model said it was done — not that anyone verified it. The result has a name now: comprehension debt, and the sharp edge of it is code that claims to be finished but is a stub, a placeholder, or synthetic data dressed up as real computation.

axonscanner reads your codebase and places every module on a verification ladder, derived from the code itself — never from commit messages or docs. Each rung is a strictly stronger claim than the one below it:

• ◉ asserted — a test assertion actually checks this module's output (strongest)
• ● tested — a test directly exercises it
• ◐ reachable — a test's call path reaches it, but nothing asserts on it
• ○ claimed-only — commits say "complete"; no test path reaches it
• ◌ stub — placeholder, TODO, pass, NotImplementedError
• ▲ synthetic-risk — returns random-generated values where real computation is claimed

The ladder is computed by static analysis with one governing rule: it under-credits, never over-credits. If it marks a module verified, it is verified; its errors only ever hide real tests, never invent them — so the output is safe to trust. The method is written up in docs/measuring-comprehension-debt.md.

Then it gives you the structural intelligence to act on it: a dependency graph, risk hotspots (churn × unverified × complexity × coupling), an algorithmically-ranked improvement backlog, and a self-learning loop that measures whether acting on a recommendation actually helped and reweights itself over time.

Zero dependencies. Pure standard library. It reads your code; it never modifies it.

Install

pipx install axonscanner        # recommended
# or
pip install axonscanner

Or run from source:

git clone https://github.com/AI-Labs-Pvt-Ltd-Nepal/axonscanner
cd axonscanner && pip install -e .

Use

axonscanner scan            # scan the current directory, write reports to ./.axonscanner/
axonscanner scan ../my-repo # scan another codebase
axonscanner check           # CI gate: pass/fail against your .axonscanner.toml (exit code)
axonscanner dashboard       # the full visual dashboard (also shown after every scan)
axonscanner dream           # a living dashboard — watch, re-derive, and learn as you code
axonscanner report          # write a shareable, self-contained HTML report (print to PDF)
axonscanner status          # the verified capability register (per file)
axonscanner status -g package  # per-package rollup — the view for large codebases
axonscanner attention       # only the claimed-vs-verified gaps
axonscanner optimize        # the ranked improvement backlog
axonscanner intel           # hotspots, import cycles, orphans
axonscanner learn           # what the self-learning loop has learned
axonscanner brief           # a session briefing an AI coding agent reads at start

The dashboard

Run in a terminal, axonscanner scan ends with a single composed dashboard (and axonscanner dashboard re-renders it any time): a stacked verification bar, an at-a-glance panel, heat-mapped risk hotspots, and a per-package rollup — all 24-bit colour, pure standard library, no rich/textual dependency. Piped or in CI it falls back to plain text automatically.

A real, unmodified scan of Werkzeug — 45 modules, 21,177 LOC. Produced by axonscanner scan; nothing mocked.

◉ A X O N S C A N N E R                         codebase honesty · static analysis
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
werkzeug  ·  git b24c8ec  ·  45 modules / 21,177 LOC

╭─ VERIFICATION ─────────────────────────────────────────────────────────────────╮
│ ◉◉◉◉◉◉◉◉◉◉◉◉◉◉◉◉ ●●●●●●●● ◐ ○○○○○○○○○○○○○○○○○○○○                                   │
│ ◉ 16 asserted   ● 8 tested   ◐ 1 reachable   ○ 20 claimed-only                   │
╰─────────────────────────────────────────────────────────────────────────────────╯
╭─ AT A GLANCE ─────────╮  ╭─ RISK HOTSPOTS ──────────────────────────────────────╮
│ verified 56%          │  │ 0.47 ██████░░░░░░ ○ routing/matcher                   │
│ asserted 36%          │  │ 0.44 █████░░░░░░░ ○ routing/map                       │
│ hi-risk  11 modules   │  │ 0.42 █████░░░░░░░ ○ wrappers/response                 │
╰───────────────────────╯  ╰──────────────────────────────────────────────────────╯

Example — axonscanner scanning itself

It doesn't flatter its own author. Run on its own source, it reports that its core (scanner) is asserted — its tests actually check its output — while openly flagging that three modules (cli, history, briefing) still have no tests at all.

$ axonscanner scan
✓ 10 modules · 2,266 LOC · 45 test funcs · 0 endpoints  (git fff9c4a)
  verification: ◉ asserted=5 · ● tested=2 · ○ claimed-only=3
  intelligence: 9 import edges · 0 cycle(s) · 0 orphan(s) · 0 high-risk module(s)
  backlog: 1 recommendation(s); top priority 1.00
  slop tax: unmeasurable (no AI-authorship signal in git history)
→ register CAPABILITY_REGISTER.md · briefing SESSION_BRIEFING.md · backlog backlog.json

$ axonscanner status
| Status         | Module    | LOC | Tests | Risk | Note                   |
|----------------|-----------|-----|-------|------|------------------------|
| ○ claimed-only | cli       | 294 |     0 | 0.21 | real code but NO tests |
| ○ claimed-only | history   | 110 |     0 | 0.30 | real code but NO tests |
| ○ claimed-only | briefing  | 105 |     0 | 0.29 | real code but NO tests |
| ● tested       | callgraph | 396 |     5 | 0.24 | 5 test funcs           |
| ● tested       | slptax    | 158 |     2 | 0.21 | 2 test funcs           |
| ◉ asserted     | scanner   | 466 |    14 | 0.32 | 14 test funcs          |
| ◉ asserted     | metrics   | 361 |     7 | 0.24 | 7 test funcs           |
| ◉ asserted     | optimizer | 147 |     8 | 0.15 | 8 test funcs           |
| ◉ asserted     | learning  | 140 |     6 | 0.15 | 6 test funcs           |
| ◉ asserted     | trends    |  89 |     3 | 0.14 | 3 test funcs           |

On a large codebase, per-file output is precise but hard to navigate. status -g package rolls files up into packages, showing each package's tier distribution and its weakest non-trivial file — because a package is only as verified as its least-verified real file. It never collapses a package to a single status; that would re-introduce the very over-crediting the tool exists to prevent.

$ axonscanner status -g package        # (werkzeug)
Package              files    ◉   ●   ◐   ○    weakest
datastructures          10    0   0   0  10    ○ claimed-only   ← a real gap
middleware               6    1   5   0   0    ● tested         ← safe to build on

Prefer something you can share or print? axonscanner report writes a self-contained report.html — the same dashboard (in colour), the full capability register, and the slop tax, in one file with zero external dependencies. Open it in any browser, email it around, or use the browser's "Print → Save as PDF" for a portable copy.

The slop tax line is the honest "unmeasurable" — axonscanner's own history carries no AI-authorship trailers, so it refuses to fabricate a number. On a repo whose commits are tagged (Co-authored-by: Claude/Copilot/…), it reports what share of the unverified code is AI-authored, and how much more likely AI-authored code is to be unverified than human-written.

Why "from the code, not the claim"

Every other signal lies under AI-assisted development. Commit messages say "implement real X" over a function that returns a hardcoded value. Docs describe features that are 60% wired up. Test counts go up while test coverage of real behaviour goes down. axonscanner ignores all of it and derives status from what the code actually does: does this module have tests that exercise it? does it call into real work or return a placeholder? does it fabricate data with random? That's the honesty check — and it's the discipline that turns a pile of confident-looking code into something you can actually build on.

Dream mode — a living dashboard

axonscanner dream turns the one-shot scan into a loop. It watches the repo, re-derives the truth every time you save a file, runs its self-learning loop continuously instead of once, and redraws the dashboard in place. A drift panel shows what changed tier since your last save, and a sparkline tracks verification climbing across the session:

$ axonscanner dream
⠹ dreaming   cycle 3   watching 29 files   verified 100.0% ▁█   last change just now
  ...the dashboard, live...
╭─ DRIFT  since your last save ───────────────────────────────────────────────╮
│ ↑ auth/session          claimed-only → asserted                             │
╰──────────────────────────────────────────────────────────────────────────────╯

Add a test, save, and watch the module climb claimed-only → asserted in real time. It's the metaphor: while you work, it keeps consolidating, so the picture is always current. Pure standard library — Ctrl-C to wake.

Quality gate — you define the bar, CI enforces it

axonscanner measures verification honestly; it does not decide what's good enough for your repo. That line is yours. Write it in .axonscanner.toml, version-controlled and reviewable like any other code:

# .axonscanner.toml
min_verified_pct = 75          # (asserted + tested + reachable) share of modules
min_asserted_pct = 0           # the stronger bar: output actually checked by a test
max_claimed_only = 10          # cap on modules no test path reaches
fail_on = ["synthetic-risk", "stub"]   # never merge fabricated-data or stub code

Then gate on it — axonscanner check scans, evaluates, and exits non-zero when the bar isn't met, so it drops straight into CI:

$ axonscanner check
quality gate — .axonscanner.toml
  [PASS] verified >= 75%   (actual: 85.7%, limit: 75%)
  [PASS] no stub, synthetic-risk modules   (actual: 0, limit: 0)

GATE PASSED

The split is the point: the tool guarantees the number is true; your team owns the threshold. (Config also works as a [tool.axonscanner] table in pyproject.toml. With no config, check only fails on synthetic-risk — never ship fabricated data — and imposes no other bar.)

For AI coding agents

axonscanner brief emits a single briefing an agent should load at the start of a session: verified-real modules it can safely build on, the claimed-but-unproven ones it must not trust, the current risk hotspots, and the ranked next actions. An agent that starts from what's real wastes far fewer tokens than one rediscovering the codebase from scratch every session.

Benchmarks

A trust tool is only worth trusting if it never lies in the dangerous direction. axonscanner's core guarantee — it under-credits, never over-credits — is measured on 12 diverse real-world codebases (560 modules, ~390k LOC spanning pytest, unittest, hypothesis, and async suites; src/, flat, multi-package, and monolithic layouts; up to sqlalchemy at 234k LOC):

Over-credit invariant violations: 0 / 560 modules.

The asserted share ranged 10–50% — discriminating, never all-or-nothing. Full table (with per-repo commit SHAs) and interpretation: docs/benchmarks.md. Reproduce it yourself:

python benchmarks/validate.py

Roadmap

v0.1 is the free CLI, Python-first, with the full verification ladder (reachability + assertion dataflow) and the slop tax. Planned:

• More language front-ends (the analysis is language-agnostic; the parsers are the work)
• A hosted team dashboard with history and org-wide trends

Done since v0.1: the CI quality gate (axonscanner check + .axonscanner.toml).

License

Apache-2.0.

Built and maintained by AI Labs Pvt. Ltd. — the discipline we use to keep our own platforms honest, released as a standalone tool. Contact: contact@ailabs.com.np