Metadata-Version: 2.4
Name: axonscanner
Version: 0.2.0
Summary: Audit whether your codebase is as real as it claims — code-derived verification status, risk hotspots, and a self-learning improvement backlog.
Project-URL: Homepage, https://ailabs.com.np
Project-URL: Repository, https://github.com/AI-Labs-Pvt-Ltd-Nepal/axonscanner
Author-email: "AI Labs Pvt. Ltd." <contact@ailabs.com.np>
License: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,ai-slop,code-audit,code-quality,comprehension-debt,static-analysis,technical-debt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# axonscanner

[![CI](https://github.com/AI-Labs-Pvt-Ltd-Nepal/axonscanner/actions/workflows/ci.yml/badge.svg)](https://github.com/AI-Labs-Pvt-Ltd-Nepal/axonscanner/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/axonscanner)](https://pypi.org/project/axonscanner/)
[![Python](https://img.shields.io/pypi/pyversions/axonscanner)](https://pypi.org/project/axonscanner/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

**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](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

```bash
pipx install axonscanner        # recommended
# or
pip install axonscanner
```

Or run from source:

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

## Use

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

<p align="center">
  <img src="https://raw.githubusercontent.com/AI-Labs-Pvt-Ltd-Nepal/axonscanner/main/docs/assets/example-werkzeug-dashboard.svg" alt="axonscanner dashboard — a real scan of Werkzeug" width="860">
</p>

<p align="center"><em>A real, unmodified scan of <a href="https://github.com/pallets/werkzeug">Werkzeug</a> — 45 modules, 21,177 LOC. Produced by <code>axonscanner scan</code>; nothing mocked.</em></p>

<details>
<summary>Plain-text fallback — what a pipe or CI log sees</summary>

```
◉ 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                 │
╰───────────────────────╯  ╰──────────────────────────────────────────────────────╯
```

</details>

## 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.

```console
$ 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.

```console
$ 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.

## 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:

```toml
# .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:

```console
$ 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](docs/benchmarks.md). Reproduce it yourself:

```bash
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.](https://ailabs.com.np) — the discipline
we use to keep our own platforms honest, released as a standalone tool.
Contact: contact@ailabs.com.np
