crapkit 0.4.14__tar.gz → 0.5.0__tar.gz

{crapkit-0.4.14/src/crapkit.egg-info → crapkit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.14
+Version: 0.5.0
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -39,7 +39,7 @@ Dynamic: license-file
 
 # crapkit
 
-<!-- mcp-name: io.github.jeanfrancoisgagne/crapkit -->
+<!-- mcp-name: io.github.JeanFrancoisGagne/crapkit -->
 
 [![ci](https://github.com/JeanFrancoisGagne/crapkit/actions/workflows/ci.yml/badge.svg)](https://github.com/JeanFrancoisGagne/crapkit/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/crapkit)](https://pypi.org/project/crapkit/)
@@ -98,15 +98,18 @@ crapkit ratchet seed && git add crapkit.toml crapkit-ratchet.tsv .gitignore
 
 ```
 $ crapkit coverage
-run 1 @ fae4db93108: 2 functions scored — 2 measured / 0 untested / 0 no-lane / 0 cc-only, 1 over target 6, CRAP load 41.0, grade F
+run 1 @ fae4db93108: 2 functions scored: 2 measured, 1 over ceiling 6, CRAP load 41.0, grade F
+-> next: crapkit worklist
 
 $ crapkit worklist
-worklist @ fae4db93108 (run 1, floor ccn>=5, churn 12mo) — 1 active, 0 dormant
-  risk      0.0  ccn  14 ( 14 std)    1c/1a w   0.00  calc/grade.py:7  classify( score , attempts , late , bonus )
+worklist @ fae4db93108 (run 1, floor ccn>=5, churn 12mo) - 1 of 1 active (worklist_top 50), 0 dormant
+  risk     14.0  ccn  14  crap    38.5  cov  50%    1c/1a  calc/grade.py:7  classify( score , attempts , late , bonus )
 ```
 
-`risk 0.0` is what a one-commit repo scores, because churn needs a spread of commits to
-rank and ccn order stands in until then ([Risk](#risk-what-ranks-the-worklist)).
+`risk 14.0` is ccn times a churn weight of one: a one-commit repo has no spread of commits
+to weight, so each commit counts once and the ranking is complexity order until the
+history grows ([Risk](#risk-what-ranks-the-worklist)). `crap 38.5` and `cov 50%` are the
+score and the coverage behind it.
 
 `ratchet seed` signs today's debt at today's score. From then on marks only ever fall, so
 the repo can get better and never worse while you burn it down.
@@ -168,12 +171,13 @@ leaves the box
 
 ```
 $ crapkit --version
-crapkit 0.4.14
+crapkit 0.5.0
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
-source checkout. Every subcommand accepts `--repo PATH` (default: the current directory),
-so you never have to `cd` into the repo you are scoring; [Subcommands](#subcommands) shows
+source checkout. Every subcommand accepts `--repo PATH` (default: the nearest `crapkit.toml`
+at or above the current directory, so a monorepo workspace finds the root's), and with it
+you never have to `cd` into the repo you are scoring; [Subcommands](#subcommands) shows
 where the flag goes.
 
 ## Upgrading from 0.4.4
@@ -360,6 +364,19 @@ EOF
 chmod +x .git/hooks/pre-commit
 ```
 
+The same file from PowerShell. `Out-File` and `>` write a byte-order mark (UTF-16 on
+5.1) in front of the shebang, and git then answers every commit with `cannot spawn
+.git/hooks/pre-commit` and lets it through; `Set-Content -Encoding ascii` does not. Git
+runs the hook with its own `sh`, so the interpreter is spelled with forward slashes and
+quoted, and no `chmod` is needed on Windows:
+
+```powershell
+$python = (Get-Command python).Source -replace '\\', '/'
+Set-Content -Path .git/hooks/pre-commit -Encoding ascii -NoNewline -Value "#!/bin/sh`nexec '$python' -m crapkit hook-precommit`n"
+```
+
+`crapkit doctor` warns when the hook file git would spawn starts with a byte-order mark.
+
 ### Route 2: a committed hooks directory
 
 The whole route, from a repo that has no `githooks/` yet:
@@ -398,7 +415,7 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
     # crapkit's release step rewrites this line to the tag it just cut
-    rev: v0.4.14
+    rev: v0.5.0
     hooks:
       - id: crapkit-gate
 ```
@@ -444,10 +461,12 @@ git, and a shallow clone does not have that commit:
 
 ```
 $ crapkit verify --baseline-tsv crapkit-baseline.tsv
-crapkit: baseline commit a74260f321f is not an ancestor of HEAD (rebase or amend rewrote history) — run `crapkit coverage` for a fresh baseline
+crapkit: baseline commit a74260f321f is not an ancestor of HEAD in this shallow clone, which does not hold it; set fetch-depth: 0 on the checkout or run git fetch --unshallow
 ```
 
 That is exit 4 on a `git clone --depth 1` of a repo whose baseline verifies at full depth.
+On a full clone the same exit blames what it used to, a rebase or an amend that rewrote
+history, and asks for a fresh baseline instead.
 Set `fetch-depth: 0` on the checkout step, which is what crapkit's own
 [.github/workflows/ci.yml](https://github.com/JeanFrancoisGagne/crapkit/blob/main/.github/workflows/ci.yml) does.
 
@@ -504,7 +523,7 @@ to a workflow, and every input has a default:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: JeanFrancoisGagne/crapkit@v0.4.14
+      - uses: JeanFrancoisGagne/crapkit@v0.5.0
 ```
 
 The whole job those four lines sit in:
@@ -524,7 +543,7 @@ jobs:
         with:
           python-version: "3.12"       # the interpreter the install below lands in
       - run: pip install -e ".[dev]"   # whatever your lanes need to run
-      - uses: JeanFrancoisGagne/crapkit@v0.4.14
+      - uses: JeanFrancoisGagne/crapkit@v0.5.0
         with:
           gate: "false"
 ```
@@ -550,33 +569,55 @@ One comment per pull request, edited in place on every push. A hidden
 carries one comment and not fifteen. On a `push` event there is no pull request to carry
 it, and the same text goes to the job log instead.
 
-Rendered against this repository's own store, with a base commit fifteen back standing in
-for a pull request:
+Rendered from three saved payloads: a pull request that adds an untested `route()` (ccn 8)
+beside a ratchet-marked `legacy_router()`, in a repository whose `diff_uncovered_max` is 3.
+The payloads are under `tests/fixtures/action_comment/`, and the unit suite pins this block
+to their render:
 
 ```markdown
 <!-- crapkit-action -->
 
 ## crapkit
 
-1333 functions in 61 files, 0 over target, CRAP load 3713.89, grade A+.
+4 functions in 2 files, 2 over ceiling 6, CRAP load 149.59, grade F.
 
-**verify passed.** Run 2 against baseline 1, 7 changed files.
+**verify failed, exit 6: complexity gate.**
 
-### Worklist: 39 changed files
+- gate: `app/calc.py:34` `route( a , b , c , d )` ccn 8, cov 0%, crap 72.0 -> decompose
+- uncovered lines in `app/calc.py`: 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45
+
+Run 3 against baseline 1, 1 changed file: 1 gate violation, 0 ratchet regressions, 0 new test failures, 11 uncovered changed lines.
+
+### Worklist: 1 changed file
 
 | File | Function | ccn | risk | remedy |
 |---|---|---:|---:|---|
-| `src/crapkit/cli/admin.py:1026` | `_recorded_roots( recorded )` | 6 | 10.9908 | ok |
-| `src/crapkit/lanes.py:646` | `build_retest_command( template : str , tests : set [ str ] )` | 6 | 10.8234 | ok |
-| `src/crapkit/cli/admin.py:80` | `_next_step( scopes : dict , lanes : tuple )` | 5 | 9.159 | ok |
-| `src/crapkit/cli/admin.py:239` | `_pytest_cov_probe( command : str )` | 5 | 9.159 | ok |
-| `src/crapkit/cli/admin.py:505` | `_segment_problems( name : str , cwd : Path , tokens : list [ str ] )` | 5 | 9.159 | ok |
+| `app/calc.py:34` | `route( a , b , c , d )` | 8 | 4.0 | decompose |
+| `app/calc.py:19` | `legacy_router( a , b , c , d , e )` | 8 | 4.0 | decompose (accepted debt) |
 ```
 
+The first line is the run `crapkit coverage` wrote: functions and files, how many sit over
+the ceiling (`over ceiling 6`, or `over their ceilings (6; reports 12, util 4)` when scopes
+set their own), CRAP load and grade, with a failed lane's first error line appended as
+`; lane 'js' failed: ...`. When `coverage --json` died before a summary, the line quotes the
+error object it printed instead: `` `crapkit coverage` exited 5: lane 'py' cannot import
+pytest-cov; pip install pytest-cov. ``
+
+The verdict opens with the exit code and the rule it stands for (`complexity gate`,
+`ratchet regressions`, `new test failures`, `diff-coverage ceiling N`), then one bullet per
+finding: each gate violation with its function, ccn, coverage, CRAP and remedy; each
+ratchet regression as recorded -> fresh; each new test failure by id; and the first twenty
+uncovered changed lines, one bullet per file, with a count of the rest. The counts line
+closes it. A verify that passed is one line: `**verify passed.** Run 2 against baseline 1,
+7 changed files.`
+
 The rows are the ranked worklist for the files the pull request changed, worst first,
-`top` of them. `risk` is ccn times churn weight, the number `crapkit worklist` ranks on,
-and `remedy` is the run's own verdict for that function: `decompose`, `add-tests` or `ok`.
-A pull request that touches no ranked function gets the heading and no table.
+`top` of them, with the rows a finding names listed first. `risk` is ccn times churn
+weight, the number `crapkit worklist` ranks on, and `remedy` is the run's own verdict for
+that function: `decompose`, `add-tests` or `ok`. `(accepted debt)` marks a function the
+committed ratchet carries a mark for, so an untouched `legacy_router` does not read like
+the pull request's own new function. A pull request that touches no ranked function gets
+the heading and no table.
 
 The two file counts describe the same diff, counted twice. `39 changed files` is
 `git diff --name-only base.sha...HEAD`, the branch's own commits, and it is what the
@@ -588,8 +629,8 @@ behind the checkout to measure from.
 
 | Input | Default | What it does |
 |---|---|---|
-| `gate` | `"false"` | `"true"` exits with `crapkit verify`'s own code, so a finding fails the check. Anything else exits 0 and the comment is the whole output |
-| `delta` | `"true"` | scores the pull request's base commit first, so the verdict covers the commits the pull request adds. Costs a second lane run; `"false"` scores the checkout alone |
+| `gate` | `"false"` | `"true"` exits with `crapkit verify`'s own code, so a finding fails the check. On a pull request with `delta` on it also exits 1 when the base run was not made, because a verdict with no base run judged no changed function. Anything else exits 0 and the comment is the whole output |
+| `delta` | `"true"` | scores the pull request's base commit first, so the verdict covers the commits the pull request adds. Costs a second lane run; `"false"` scores the checkout alone, and the verdict then judges no changed function |
 | `top` | `"5"` | worklist rows rendered in the table |
 | `python-version` | `"3.12"` | the interpreter `actions/setup-python` installs crapkit into. Match it to the version your own setup-python step named, or the lanes run on an interpreter your dependencies never reached |
 
@@ -614,13 +655,26 @@ The base run happens in a detached worktree under `RUNNER_TEMP`, and its store i
 over the checkout's so both runs sit in one place. The cost is **two lane runs on a pull
 request**: your suite runs once at the fork point and once on the checkout. Set `delta:
 "false"` to skip the base run, and the verdict falls back to the checkout against its own
-run, which reports the tree's own health and judges no changed function.
+run, which reports the tree's own health and judges no changed function. The comment says
+so in place of `verify passed`:
 
-Three things leave the base run unmade, and none of them fails the job: a shallow clone
-that does not hold the fork point, a fork point older than your `crapkit.toml`, and a
-lane that will not run against that tree. The step logs `crapkit base scoring exited N`
-and the verdict falls back the same way `delta: "false"` does. A `push` event never makes
-one, because there is no base commit and no pull request to comment on.
+```markdown
+**verify judged no changed function:** the base run was not made (no base commit). Run 2 against baseline 2, 0 changed files.
+```
+
+Three things leave the base run unmade: a shallow clone that does not hold the fork
+point, a fork point older than your `crapkit.toml`, and a lane that will not run against
+that tree. The step logs `crapkit base scoring exited N` and writes the reason to
+`crapkit-base.reason` in the words the comment then quotes, `shallow clone does not hold
+the fork point of <sha>; set fetch-depth: 0 on the checkout`, `no usable crapkit.toml at
+the fork point <sha>: ...`, or `lane failed at the fork point <sha>: ...` with the lane's
+first error line. The verdict falls back the same way `delta: "false"` does, and the
+ratchet still runs, so exit 7 there is a finding. What differs is the job's status. With
+`gate: "true"` on a pull request whose base run was attempted and not made, the exit step
+exits 1 and prints the reason, because `actions/checkout`'s default depth-1 clone would
+otherwise turn every pull request into a green check that judged nothing. A `push` event
+and `delta: "false"` never attempt the base run, so they keep verify's own code; a `push`
+has no base commit and no pull request to comment on.
 
 One requirement the base run adds: the lane has to measure the tree it runs in. A lane
 that reaches an installed copy of your package instead of the checkout will measure the
@@ -633,6 +687,21 @@ worktree is the quiet one. Point the lane at the tree, or set `delta: "false"`.
 ran the lanes moments earlier on that tree, and verify parses those artifacts rather than
 running the whole suite a second time for the same numbers.
 
+Which is why `crapkit coverage` has to exit 0 for there to be a verdict. When it exits
+anything else (a lane that failed, an artifact it refused), the action does not run
+`verify`: on a runner that keeps its workspace between jobs (`clean: false`), a
+`verify --reuse-artifacts` over a failed measurement read the artifact the dead lane had
+left from an earlier run, passed over it, and made that run the trusted baseline. The
+comment then carries coverage's failure in place of the verdict:
+
+```markdown
+**no verdict: `crapkit coverage` exited 5 (lane 'py' failed: lane 'py' wrote no artifact on its last attempt; the .crapkit/cov/py.json on disk predates it); verify did not run.**
+```
+
+The parenthesis is the first line of the lane failure the summary carries. When every
+lane failed, `coverage` prints no summary at all and the lane errors are only in the job
+log, and the line says so. With `gate: "true"` the job exits with coverage's code.
+
 The other gate that judges a delta is the portable baseline in [Route 4](#route-4-ci):
 commit `crapkit-baseline.tsv` on the default branch and run `crapkit verify --baseline-tsv
 crapkit-baseline.tsv` in a step of your own. It needs no second lane run, and it needs
@@ -645,14 +714,18 @@ on PATH fails that step. Both leave the rendered text in the job log.
 
 ## Subcommands
 
-Every subcommand takes `--repo PATH` (default `.`), and the flag goes **after** the
-subcommand. `claude-hook` is the one exception: it has no `--repo`, because it takes its
-root from the file named in the hook payload it reads.
+Every subcommand takes `--repo PATH`, and the flag goes **after** the subcommand. Without
+it the root is the nearest `crapkit.toml` at or above the current directory
+([ADR 0002](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/adr/0002-configuration-is-found-upward-nearest-wins.md)): from a
+monorepo workspace `crapkit worklist` reads the root configuration that claims the
+workspace, says `crapkit: using crapkit.toml at /repo` on stderr, and reads a relative path
+argument from where you stand. `claude-hook` is the one exception: it has no `--repo`,
+because it takes its root from the file named in the hook payload it reads.
 
 ```
 $ crapkit worklist --repo /path/to/repo --scope util --top 1
-worklist @ a7c5c85ac37 (run 1, floor ccn>=5, churn 12mo) — 1 active, 0 dormant
-  risk      5.4  ccn   5 (  5 std)    5c/1a w   1.08  util/stats.py:1  bucket( value , low , high )
+worklist @ a7c5c85ac37 (run 1, floor ccn>=5, churn 12mo) - 1 of 3 active (--top 1), 0 dormant
+  risk      5.4  ccn   5  crap    30.0  cov   0%    5c/1a  util/stats.py:1  bucket( value , low , high )
 ```
 
 Before it, argparse reads the path as the subcommand name and exits 2 without ever
@@ -672,8 +745,8 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `inventory [--db PATH] [--export PATH] [--json]` | One lizard pass over every in-scope file into a SQLite snapshot run, cached by content hash. `--db` is the only way to point crapkit at a store outside `.crapkit/`, and only this command accepts it. |
 | `coverage [--lane NAME] [--reuse-artifacts] [--reuse-unchanged] [--export PATH] [--sarif PATH] [--github] [--json]` | Runs the lanes, joins branch coverage onto a fresh inventory, writes a scored run. A failed lane is recorded, not fatal: its scopes fall back to `no-lane` and the run is typed `partial`, so it can never serve as a baseline. See [docs/lanes.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/lanes.md). |
 | `verify [--baseline ID \| --base REF \| --baseline-tsv PATH] [--emit-baseline PATH] [--override REASON] [--reuse-artifacts] [--reuse-unchanged] [--no-tighten] [--sarif PATH] [--github] [--json]` | The full verdict against the trusted baseline: gate on touched functions, ratchet, no new test failures, optional diff-coverage ceiling. The three baseline selectors are mutually exclusive; `--baseline ID` also bypasses the taint rule ([The trusted baseline](#the-trusted-baseline)), and `--baseline-tsv` reads a commit-stamped file so a fresh clone verifies with no store. `--no-tighten` passes the verdict without rewriting the ratchet. Findings a dirty tree produced are tagged `dirty` and counted apart. It reads each istanbul artifact once for coverage, dead lines and its digest, and skips the artifact walk on an empty diff; skipping the whole run on an unchanged tree was measured and rejected, because a key made of HEAD plus the dirty names cannot see a second edit to a file that was already dirty. |
-| `worklist [--top N] [--scope NAME] [--batches N] [--json]` | The risk map: every admitted function ranked by `ccn * churn weight`, floored by `worklist_floor`, with hot simple code and anything over its ceiling admitted past that floor. It ranks finished rows and `no-lane` rows too, marked `ok` and `no-lane`, so it never empties; `next-item` carries the stop condition. `--scope NAME` (repeatable) is exact, not a substring. `--batches N` **adds** a `batches[]` view cutting the active list into at most N file-disjoint batches with co-changing files kept together, off the same cached pairs `coupling` reads; the normal keys stay. |
-| `next-item [--top N] [--exclude FRAG] [--scope NAME] [--claim]` | The actionable queue as JSON, with churn, budget estimates and uncovered lines. Same run and same admission floor as `worklist`, a different view of it: `no-lane` rows are skipped and counted in `skipped_no_lane`, and what is left is ranked by `crap` descending rather than by risk, so the item it hands out is often not the worklist's first row. `--exclude FRAG` (repeatable) skips items whose path or function name contains FRAG; `--scope NAME` (repeatable) is exact, not a substring. `--claim` holds what it hands out so a second session skips it. `stale` is true when the ranked run's commit is not HEAD, the same field `worklist` carries. Every item carries a `handle`: the bare identifier, or `(anonymous)#N` for a function with no name, which is the name form that survives the edit the item asks for. |
+| `worklist [--top N] [--scope NAME] [--batches N] [--json]` | The risk map: every admitted function ranked by `ccn * churn weight`, floored by `worklist_floor`, with hot simple code and anything over its ceiling admitted past that floor. It ranks finished rows and `no-lane` rows too, marked `ok` and `no-lane`, so it never empties; `next-item` carries the stop condition. Every row carries the function's `crap` and `cov` off the ranked run and its `ratchet_mark` when the committed marks file signs for it, and the header counts the active rows the cap hid: `50 of 3980 active (worklist_top 50)`. `--scope NAME` (repeatable) is exact, not a substring; a name no `[[scope]]` declares is a configuration error, exit 3, naming the declared scopes. `--batches N` **adds** a `batches[]` view cutting the active list into at most N file-disjoint batches with co-changing files kept together, off the same cached pairs `coupling` reads; the normal keys stay. |
+| `next-item [--top N] [--exclude FRAG] [--scope NAME] [--claim]` | The actionable queue as JSON, with churn, budget estimates and uncovered lines. Same run and same admission floor as `worklist`, a different view of it: `no-lane` rows are skipped and counted in `skipped_no_lane`, and what is left is ranked by `crap` descending rather than by risk, so the item it hands out is often not the worklist's first row. `--exclude FRAG` (repeatable) skips items whose path or function name contains FRAG; `--scope NAME` (repeatable) is exact, not a substring, and a name no `[[scope]]` declares is a configuration error, exit 3, naming the declared scopes. `--claim` holds what it hands out so a second session skips it. `stale` is true when the ranked run's commit is not HEAD, the same field `worklist` carries. Every item carries a `handle`: the bare identifier, or `(anonymous)#N` for a function with no name, which is the name form that survives the edit the item asks for. |
 | `claims [list \| release PATH NAME \| release --all] [--json]` | The open claims, and the way to hand one back without waiting for a verify. `release` takes the bare identifier, the whole long name, or the `handle` the claim was taken under, which is the only one that picks out a single `(anonymous)` claim. |
 | `brief FILE NAME [--batch N] [--json]` | The start-editing packet for one function: its own `source` text, every function in the file, the scored row and the scope ceiling, the ratchet mark and what the gate will bind on, uncovered lines, duplication twins, file churn, coupling partners, the config's notes, and the literal commands for the rest of the loop. Plus `handle`, `remedy` and the same `est_splits` / `est_uncovered_paths` the queue prints, and a `commands.refresh` that writes a run (`refresh_writes_run`) rather than re-reading the stale one. `NAME` takes the bare identifier, the long name `next-item` printed, the function's start line, `(anonymous)#N` for a function printed `(anonymous)` counting the file's anonymous functions from the top, or `NAME#2` for the second of several functions a file gives one name to. `--batch N` drops the positionals and emits `packets[]` instead: the top N of the queue, built from one read of the store and one duplication pass over the snapshot for the whole batch (batch of 5: 11.8 s to 5.2 s, output byte-identical to five separate calls). |
 | `explain FILE NAME [--history] [--tests] [--json]` | A function's score across runs plus its mark. `NAME` resolves exact first: a function whose bare identifier or long name is exactly `NAME` wins, and only when nothing matches exactly does it fall back to a prefix match, so `route` explains `route` rather than every `route_*` beside it. It also takes the function's start line, the form `brief` takes, which is how you open one printed `(anonymous)`. `--history` adds the commits that touched it (`git log -L`), each carrying its message `body`, `--tests` the tests that covered it, which needs coverage.py contexts turned on ([recipe](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/lanes.md#test-attribution-for-explain---tests)). `--json` emits the same content as one `schema` 1 object. |
@@ -683,16 +756,16 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `overrides [--json]` | The override audit trail: who granted what, when, and why. |
 | `trend [--json]` | Totals per trusted run: functions, over-target count, CRAP load, average, per-scope rollup. It reads a per-run rollup table rather than rescanning every scored row, and fills that table for any run missing one, so it writes to the store (best effort: a read-only `.crapkit/` costs the speed, not the command). |
 | `digest [--alert]` | The delta between the two newest runs with identical lane sets. Silent when nothing changed. `--alert` pipes the body to `alert_command` on stdin. Plain lines, never JSON. |
-| `report [--out PATH]` | One self-contained HTML page written to `.crapkit/report.html` (or `--out PATH`, repo-relative, or an absolute path you name), with the path printed on stdout. It renders what `worklist --json` and `trend --json` already answer at their defaults: the ranked worklist capped at `worklist_top`, the per-scope grades off the newest run, the trend series, and a banner naming every stale lane. It measures nothing and opens no network connection. Per-function CRAP and coverage are absent because no repo-wide payload carries them; each row prints the `crapkit explain` call that does. It reads the same per-run rollups `trend` does, and writes them on the same terms. |
+| `report [--out PATH]` | One self-contained HTML page written to `.crapkit/report.html` (or `--out PATH`, repo-relative, or an absolute path you name), with the path printed on stdout. It renders what `worklist --json` and `trend --json` already answer at their defaults: the ranked worklist capped at `worklist_top`, the per-scope grades off the newest run, the trend series, and a banner naming every stale lane. It measures nothing and opens no network connection. Every row carries the function's CRAP and coverage, and prints the `crapkit explain` call for the rest: dark lines, history, the mark. It reads the same per-run rollups `trend` does, and writes them on the same terms. |
 | `duplication [--min-lines N] [--similarity F] [--top N] [--json]` | Near-duplicate functions by normalized line shingles with containment scoring. Defaults: `--min-lines 8`, `--similarity 0.8`, `--top 50`. `--top` truncates the list. A function and a function nested inside it never pair: their spans nest, they score 1.0 by construction, and nobody can deduplicate a factory from its own closure. |
 | `coupling [--min-support N] [--min-confidence F] [--top N] [--json]` | File pairs that keep landing in the same commits. Defaults: `--min-support 5` shared commits, `--min-confidence 0.5` max-direction ratio, `--top 50`. Bulk commits never couple pairs, and a young repo returns nothing at the default support. The ranked pairs are cached in `.crapkit/coupling-cache-v1.json`, keyed on HEAD, the churn window, today's UTC date, the path format and a digest of the tracked set, and shared with `brief` and `worklist --batches` (warm: 1.05 s to 0.11 s on a 72k-commit repo). The date is part of that key, so the first run after midnight UTC rebuilds the pairs on an unchanged HEAD. `--top` reads the cache, because it truncates that same order; `--min-support` or `--min-confidence` off their defaults ask a wider question than the file answers, so they bypass it and recompute. |
-| `mutate [--files F ...] [--max-mutants N] [--drop-pool] [--json]` | Diff-scoped mutation testing: flips comparisons, boundary shifts, boolean connectives and boolean literals on changed lines, runs `mutation_command` per mutant, lists survivors. `--files` replaces diff scope with the whole file. `--max-mutants` (default 100) caps the run and the cap warning goes to stderr only, so `mutants` in `--json` is the capped count. Shell and PowerShell files are refused by name on stderr rather than mutated: `<` and `>` are redirections there, not comparisons. With `mutation_workers > 1` the worker worktrees are kept at `.crapkit/mutate-pool/` and re-prepared per run (30.6 s to build four on a 31,459-file repo, 0.46 s to re-prepare them); `--drop-pool` removes them and exits. |
+| `mutate [--files F ...] [--max-mutants N] [--drop-pool] [--json]` | Diff-scoped mutation testing: flips comparisons, boundary shifts, boolean connectives and boolean literals on changed lines, runs `mutation_command` per mutant, lists survivors. `--files` replaces diff scope with the whole file. Both lists pass through the scored corpus first, the same predicate `coverage` uses (scopes, excludes, the test-file cut, `max_file_bytes`): a test file, an excluded path, a file over `max_file_bytes` or a file no scope claims is named on stderr and never mutated, `--json` lists it under `outside_corpus`, and when nothing is left stdout says `nothing to mutate` at exit 0 without starting the suite. `--max-mutants` (default 100) caps the run and the cap warning goes to stderr only, so `mutants` in `--json` is the capped count. Shell and PowerShell files are refused by name on stderr rather than mutated: `<` and `>` are redirections there, not comparisons. With `mutation_workers > 1` the worker worktrees are kept at `.crapkit/mutate-pool/` and re-prepared per run (30.6 s to build four on a 31,459-file repo, 0.46 s to re-prepare them); `--drop-pool` removes them and exits. |
 | `test-scoped FILE ...` | Runs each owning scope's `[crapkit.scoped_tests]` template on the files (quoted, longest-prefix scope wins). A template with no `{files}` runs as written, which is how a scope whose tests live outside its own paths runs its whole suite. Exit code only; a nonzero runner exits 1. |
 | `hook-precommit` | The cc-only gate on staged blobs. No coverage, no snapshot, no repo-wide cache. Exit 6 on a violation. |
 | `claude-hook [--protocol N]` | Reads one Claude Code PostToolUse payload from stdin and judges the file it edited: ccn against the scope ceiling, on functions the edit changed, minus functions a ratchet mark already covers. Advisory only: the edit has landed, and `hook-precommit` stays the enforcement point. Exit 2 and an advisory on stderr is the only thing it ever says, one block per judged file (a head line, one line per breaching function, a closing line): no `crapkit.toml` above the edited file, an unscoped file, mid-rebase or mid-merge, a `--protocol` other than 1, source that parses to no functions, or any internal failure all exit 0 in silence. The root is the first `crapkit.toml` above the edited file; the walk stops at a `.git` entry, so a worktree never borrows its parent's config. A `Bash` event names no file, so it judges the working tree instead: the dirty or untracked `*.py` files touched in the last 12 seconds, 25 at most, each through the same ladder, and silence for a clean tree or a cwd outside any repo. That half fires only where you register a `Bash` matcher ([The Claude Code plugin](#the-claude-code-plugin)). It opens no snapshot and writes nothing. |
 | `watch [--interval SECONDS] [--cycles N]` | Rescores tracked files as they change (mtime polling, default 2s, subprocess-isolated so a half-saved syntax error never kills the watcher). `--cycles N` polls exactly N times and exits 0; without it the loop runs until ctrl-c. |
 | `help [TOPIC]` | The help git, npm and docker answer to. With no TOPIC it prints the command list; with one it prints that subcommand's own help, the same page as `crapkit TOPIC --help`. A TOPIC that names no subcommand exits 3. |
-| `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing nine read-only tools. Every tool shells to the CLI's own `--json` surface, so the MCP view cannot drift from what the CLI reports. Answering from a kept in-process store was benchmarked and rejected: a packet's `source` would go stale behind the edit it describes. See [docs/agent-json.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#mcp-server). |
+| `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing ten read-only tools. Every tool shells to the CLI's own `--json` surface, so the MCP view cannot drift from what the CLI reports. Answering from a kept in-process store was benchmarked and rejected: a packet's `source` would go stale behind the edit it describes. See [docs/agent-json.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#mcp-server). |
 
 ## Reading the output
 
@@ -731,16 +804,17 @@ outrank fifty from two years ago. The window anchors on the newest commit, never
 wall clock, so a fixed tree ranks identically forever.
 
 Age is not the input, position in the log is. A log whose commits all share one timestamp
-reads 0.0 everywhere, which is why a one-commit repo shows `risk 0.0` on every row and
-falls back to ccn order. Commits minutes apart already rank. This repo was eight commits
-old, all made the same day:
+has no range to weight against, so each commit counts once: a one-commit repo weighs every
+file 1.0, ranks by ccn, and promotes nothing under the floor, because a top 10% of equal
+weights would be every file. Commits minutes apart already rank. This repo was eight
+commits old, all made the same day:
 
 ```
 $ crapkit worklist --scope util
-worklist @ a7c5c85ac37 (run 1, floor ccn>=5, churn 12mo) — 3 active, 0 dormant
-  risk      5.4  ccn   5 (  5 std)    5c/1a w   1.08  util/stats.py:1  bucket( value , low , high )
-  risk      4.5  ccn   9 (  9 std)    1c/1a w   0.50  util/curve.py:1  curve( scores , mode , floor , ceiling , skip_none )
-  risk      4.3  ccn   4 (  4 std)    5c/1a w   1.08  util/stats.py:13  spread( values , cap )  ok
+worklist @ a7c5c85ac37 (run 1, floor ccn>=5, churn 12mo) - 3 of 3 active (worklist_top 50), 0 dormant
+  risk      5.4  ccn   5  crap    30.0  cov   0%    5c/1a  util/stats.py:1  bucket( value , low , high )
+  risk      4.5  ccn   9  crap    90.0  cov   0%    1c/1a  util/curve.py:1  curve( scores , mode , floor , ceiling , skip_none )
+  risk      4.3  ccn   4  crap     4.2  cov  75%    5c/1a  util/stats.py:13  spread( values , cap )  ok
 ```
 
 `bucket` at ccn 5 outranks `curve` at ccn 9 because five commits touched it and one
@@ -861,7 +935,7 @@ warns. [docs/lanes.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/do
 ```
 $ crapkit init
 wrote crapkit.toml with 1 scope(s): calc
-detected 1 lane(s) from this repo's own files: py — next: run `crapkit coverage`
+detected 1 lane(s) from this repo's own files: py - next: run `crapkit coverage`
 added to .gitignore: .crapkit/, .coverage, __pycache__/
 ```
 
@@ -888,7 +962,26 @@ paths = ["calc"]
 languages = ["python"]
 
 [exclude]
-globs = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/vendor/**", "**/*.test.*", "**/*.spec.*", "**/test_*.py", "**/*_test.py", "**/conftest.py", "node_modules/**", "dist/**", "build/**", "vendor/**", "*.test.*", "*.spec.*", "test_*.py", "*_test.py", "conftest.py", "*_test.go", "**/*_test.go", "*.config.ts", "*.config.js", "*.config.mts", "**/*.config.ts", "**/*.config.js", "**/*.config.mts"]
+# A leading **/ matches zero or more directories, so each glob below reaches the
+# repo root and every nested copy. Test directories leave the corpus on their own.
+globs = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/vendor/**",
+  "**/generated/**",
+  "**/__generated__/**",
+  "**/*.generated.*",
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/test_*.py",
+  "**/*_test.py",
+  "**/conftest.py",
+  "**/*_test.go",
+  "**/*.config.ts",
+  "**/*.config.js",
+  "**/*.config.mts",
+]
 
 [[lane]]
 name = "py"
@@ -908,9 +1001,12 @@ scopes = ["calc"]
 # scopes = ["<your-scope>"]
 
 # `crapkit test-scoped FILES` runs one command per scope, with {files}
-# replaced by that scope's files, each quoted.
+# replaced by that scope's files, each quoted; a template with no {files}
+# runs as written, which is how a scope whose tests live elsewhere runs them.
 [crapkit.scoped_tests]
-calc = "python -m pytest {files} -q -p no:cacheprovider"
+# calc: no test file under calc/, so the whole suite runs, from tests/
+calc = "python -m pytest tests -q -p no:cacheprovider"
+
 ```
 
 The last block is the one an agent loop needs. `crapkit test-scoped` exits 3 for a file
@@ -926,6 +1022,7 @@ ok   config keys all recognized
 ok   scope 'calc': 1 file
 ok   every tracked source file belongs to a scope
 ok   1 lane(s) declared
+ok   lane 'py': python -> /home/you/ledger/.venv/bin/python (pytest 8.3.3, pytest-cov 7.1.0)
 ok   lizard 1.24.0
 doctor: no problems found
 ```
@@ -937,16 +1034,20 @@ and exit 0.
 
 ```
 $ crapkit coverage
-run 1 @ fae4db93108: 2 functions scored — 2 measured / 0 untested / 0 no-lane / 0 cc-only, 1 over target 6, CRAP load 41.0, grade F
+run 1 @ fae4db93108: 2 functions scored: 2 measured, 1 over ceiling 6, CRAP load 41.0, grade F
+-> next: crapkit worklist
 
 $ crapkit worklist
-worklist @ fae4db93108 (run 1, floor ccn>=5, churn 12mo) — 1 active, 0 dormant
-  risk      0.0  ccn  14 ( 14 std)    1c/1a w   0.00  calc/grade.py:7  classify( score , attempts , late , bonus )
+worklist @ fae4db93108 (run 1, floor ccn>=5, churn 12mo) - 1 of 1 active (worklist_top 50), 0 dormant
+  risk     14.0  ccn  14  crap    38.5  cov  50%    1c/1a  calc/grade.py:7  classify( score , attempts , late , bonus )
 ```
 
-Columns: `risk`, `ccn` with the standard-only ccn in parentheses,
-`<commits>c/<authors>a` in the churn window with `w<weight>`, `path:line`, the function's
-long name, then a marker on rows the burn-down queue will not hand out (`ok`, `no-lane`).
+Columns: `risk`, `ccn`, the function's `crap` and `cov` off the ranked run (`-` on an
+inventory-only run), `<commits>c/<authors>a` in the churn window, `path:line`, the
+function's long name, then a marker on rows the burn-down queue will not hand out (`ok`,
+`no-lane`). The header counts the active rows against their total, so `50 of 3980 active
+(worklist_top 50)` says what the cap hid, and reads `(--top N)` when the flag set the cap.
+`--json` also carries `ccn_std`, `weight` and `ratchet_mark`.
 
 **`worklist` is the risk map, not a to-do list.** It ranks finished rows too, so it does
 not empty when the burn-down does. `next-item` is the other view of that run: it drops the
@@ -956,7 +1057,7 @@ not empty when the burn-down does. `next-item` is the other view of that run: it
 
 ```
 $ crapkit next-item
-{"commit": "fae4db93108b4841a00959f9117430679e7250ca", "empty": false, "item": {"authors": 1, "ccn": 14, "ccn_std": 14, "cognitive": 13, "commits": 1, "cov": 0.5, "crap": 38.5, "end": 28, "est_splits": 3, "est_uncovered_paths": 7, "flag": "measured", "function": "classify( score , attempts , late , bonus )", "handle": "classify", "nesting": 8, "nloc": 22, "path": "calc/grade.py", "remedy": "decompose", "scope": "calc", "start": 7, "target": 6, "uncovered_lines": [9, 11, 15, 17, 19, 24, 25, 26, 27, 28]}, "run_id": 1, "schema": 1, "skipped_no_lane": 0, "stale": false}
+{"commit": "fae4db93108b4841a00959f9117430679e7250ca", "empty": false, "item": {"authors": 1, "ccn": 14, "ccn_std": 14, "cognitive": 13, "commits": 1, "cov": 0.5, "crap": 38.5, "end": 28, "est_splits": 3, "est_uncovered_paths": 7, "flag": "measured", "function": "classify( score , attempts , late , bonus )", "handle": "classify", "nesting": 3, "nloc": 22, "path": "calc/grade.py", "remedy": "decompose", "scope": "calc", "start": 7, "target": 6, "uncovered_lines": [9, 11, 15, 17, 19, 24, 25, 26, 27, 28]}, "run_id": 1, "schema": 1, "skipped_no_lane": 0, "stale": false}
 ```
 
 `remedy: "decompose"`, `est_splits: 3` (this needs roughly three pieces to fit under 6),
@@ -971,7 +1072,7 @@ function at its current score, and from then on nothing may get worse.
 
 ```
 $ crapkit ratchet seed
-crapkit-ratchet.tsv: added 1, tightened 0 — 1 mark(s) vs run 1 (fae4db93108)
+crapkit-ratchet.tsv: added 1, tightened 0 - 1 mark(s) vs run 1 (fae4db93108)
 
 $ git add crapkit.toml crapkit-ratchet.tsv .gitignore && git commit -m "adopt crapkit"
 ```
@@ -987,7 +1088,8 @@ $ crapkit verify
 verify OK @ 8d10c13303d vs baseline fae4db93108 (5 changed files)
 
 $ crapkit coverage
-run 3 @ 8d10c13303d: 5 functions scored — 5 measured / 0 untested / 0 no-lane / 0 cc-only, 0 over target 6, CRAP load 19.0, grade A+
+run 3 @ 8d10c13303d: 5 functions scored: 5 measured, 0 over ceiling 6, CRAP load 19.0, grade A+
+-> next: crapkit worklist
 ```
 
 CRAP load 41.0 to 19.0, grade F to A+. `verify` reruns the lanes and checks three things
@@ -1011,7 +1113,7 @@ A vitest repo with `src/grade.ts` and `test/grade.test.ts`.
 ```
 $ crapkit init
 wrote crapkit.toml with 1 scope(s): src
-detected 1 lane(s) from this repo's own files: js — next: run `crapkit coverage`
+detected 1 lane(s) from this repo's own files: js - next: run `crapkit coverage`
 added to .gitignore: .crapkit/
 ```
 
@@ -1074,11 +1176,12 @@ job; either one is enough. The full block is in
 
 ```
 $ crapkit coverage
-run 1 @ 8bfbe613fcd: 2 functions scored — 2 measured / 0 untested / 0 no-lane / 0 cc-only, 1 over target 6, CRAP load 56.68, grade F
+run 1 @ 8bfbe613fcd: 2 functions scored: 2 measured, 1 over ceiling 6, CRAP load 56.68, grade F
+-> next: crapkit worklist
 
 $ crapkit worklist
-worklist @ 8bfbe613fcd (run 1, floor ccn>=5, churn 12mo) — 1 active, 0 dormant
-  risk      0.0  ccn  15 ( 15 std)    1c/1a w   0.00  src/grade.ts:8  classify ( row Row )
+worklist @ 8bfbe613fcd (run 1, floor ccn>=5, churn 12mo) - 1 of 1 active (worklist_top 50), 0 dormant
+  risk     15.0  ccn  15  crap    52.4  cov  45%    1c/1a  src/grade.ts:8  classify ( row Row )
 ```
 
 `classify` is ccn 15 against a ceiling of 6: one function holding the late-and-retry
@@ -1091,7 +1194,7 @@ can get worse while you burn this one down.
 
 ```
 $ crapkit ratchet seed
-crapkit-ratchet.tsv: added 1, tightened 0 — 1 mark(s) vs run 1 (8bfbe613fcd)
+crapkit-ratchet.tsv: added 1, tightened 0 - 1 mark(s) vs run 1 (8bfbe613fcd)
 
 $ git add crapkit.toml crapkit-ratchet.tsv .gitignore && git commit -m "adopt crapkit"
 ```
@@ -1171,7 +1274,8 @@ $ crapkit verify
 verify OK @ 2af3433d979 vs baseline 8bfbe613fcd (3 changed files)
 
 $ crapkit coverage
-run 3 @ 2af3433d979: 5 functions scored — 5 measured / 0 untested / 0 no-lane / 0 cc-only, 0 over target 6, CRAP load 22.0, grade A+
+run 3 @ 2af3433d979: 5 functions scored: 5 measured, 0 over ceiling 6, CRAP load 22.0, grade A+
+-> next: crapkit worklist
 ```
 
 CRAP load 56.68 to 22.0, grade F to A+, and the mark seeded in step 4 is gone: `verify`