crapkit 0.4.11__tar.gz → 0.4.12__tar.gz

{crapkit-0.4.11/src/crapkit.egg-info → crapkit-0.4.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.11
+Version: 0.4.12
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -117,7 +117,9 @@ command when `pytest_cov` is missing; `pip install "crapkit[py]"` pulls the plug
 alongside crapkit when the two share a venv. On a Windows PATH holding only the `py`
 launcher it writes `py`, not a `python3` the lane could never run, and when cmd.exe cannot
 start the interpreter at all (exit 9009, the Store alias) it names that instead of guessing
-at pytest-cov. The two quickstarts below walk a real repo end to end.
+at pytest-cov. A repo that pins no lockfile and carries its own `.venv` gets that venv's
+interpreter in the lane, when that interpreter can import pytest, rather than whichever
+python the shell answers with. The two quickstarts below walk a real repo end to end.
 
 **On Windows a lane command is read by cmd.exe**, the shell that will run it, not by sh.
 Double quotes are the portable quoting. A single-quoted value is refused at config load
@@ -129,7 +131,7 @@ artifact:
 command = "python -m pytest -m 'not live and not perf' --cov=calc --cov-branch --cov-report=json:.crapkit/cov/py.json"
 
 $ crapkit doctor
-crapkit: lane 'py': positional argument 'live' narrows a full-suite coverage run; drop it, attach it to the flag it belongs to (-n8, --numprocesses=8), or set full_suite = false deliberately (cmd.exe does not treat ' as a quote: write the value in double quotes)
+crapkit: lane 'py': positional argument 'live' narrows a full-suite coverage run; drop it, attach it to the flag it belongs to (-n8, --numprocesses=8), or set full_suite = false deliberately (cmd.exe does not treat ' as a quote: write the value in double quotes); a suite whose testpaths cannot be collected in one process needs one lane per testpath, each with full_suite = false and its own artifact
 ```
 
 Write it `-m "not live and not perf"`. Carets, `&&` and `|` segments, redirections and
@@ -163,7 +165,7 @@ leaves the box
 
 ```
 $ crapkit --version
-crapkit 0.4.11
+crapkit 0.4.12
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -393,7 +395,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.11
+    rev: v0.4.12
     hooks:
       - id: crapkit-gate
 ```
@@ -499,7 +501,7 @@ to a workflow, and every input has a default:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: JeanFrancoisGagne/crapkit@v0.4.11
+      - uses: JeanFrancoisGagne/crapkit@v0.4.12
 ```
 
 The whole job those four lines sit in:
@@ -519,7 +521,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.11
+      - uses: JeanFrancoisGagne/crapkit@v0.4.12
         with:
           gate: "false"
 ```
@@ -663,7 +665,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | Command | What it does |
 |---|---|
 | `init` | Sniffs tracked source into per-directory scopes, writes a self-validated starter `crapkit.toml` whose lanes report into `.crapkit/cov/`, and appends `.crapkit/` plus each runner's own droppings to `.gitignore`. Writes a live `[[lane]]` when it can detect the test runner, otherwise a commented template. Refuses to clobber an existing config. |
-| `doctor [--show-files] [--json] [--tune] [--plugin-root [PATH]]` | Checks the config still describes the repo: unknown keys (with the accepted spellings), zero-file scopes, tracked source no scope claims, scopes no lane covers, lane cwds and commands that no longer resolve, lizard importable, oversized files. It reads each lane command with the shell that will run it, so a quoted interpreter path is one word and a runner after `&&` is checked too, and it FAILs a lane whose runner does not resolve on PATH or that the shell cannot start, naming the word to change; each distinct runner is probed once, not once per lane. It WARNs on a lane writing its artifact at the repo root, a `coveragepy` or `istanbul` lane with no `results_artifact` (the crashed-worker and no-new-failures checks are off for it, whichever runner the lane spells), a committed hook under `core.hooksPath` that is not executable in the index, a directory whose functions are all `untested` while its tests exist, and a scope a lane measures with no `[crapkit.scoped_tests]` template behind it, which is the loop's step 4 with nothing to run. `--tune` prints suggested parallelism knobs and writes nothing. `--plugin-root PATH` reads no repo at all: it checks an installed [plugin](https://github.com/JeanFrancoisGagne/crapkit/tree/main/plugin) against this CLI on both version and hook `--protocol`, one line per disagreement and silence when they agree; PATH is the plugin root or any directory above it, `~/.claude` included (only manifests named `crapkit` count, and the newest install wins), and with no PATH it looks in Claude Code's plugin cache. A root it found rather than one you typed is named first, as `crapkit doctor: checking PATH`. See [docs/agent-json.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#doctor---json). |
+| `doctor [--show-files] [--json] [--tune] [--plugin-root [PATH]]` | Checks the config still describes the repo: unknown keys (with the accepted spellings), zero-file scopes, tracked source no scope claims, scopes no lane covers, lane cwds and commands that no longer resolve, lizard importable, oversized files. It reads each lane command with the shell that will run it, so a quoted interpreter path is one word and a runner after `&&` is checked too, and it FAILs a lane whose runner does not resolve or that the shell cannot start, naming the word to change; a bare name is looked for on PATH and a runner spelled as a path is looked for under the directory the lane runs in, so `.venv/bin/python` answers the same from any directory you run `doctor` in; each distinct runner is probed once, not once per lane. It WARNs on a lane writing its artifact at the repo root, a `coveragepy` or `istanbul` lane with no `results_artifact` (the crashed-worker and no-new-failures checks are off for it, whichever runner the lane spells), a committed hook under `core.hooksPath` that is not executable in the index, a directory whose functions are all `untested` while its tests exist, and a scope a lane measures with no `[crapkit.scoped_tests]` template behind it, which is the loop's step 4 with nothing to run. `--tune` prints suggested parallelism knobs and writes nothing. `--plugin-root PATH` reads no repo at all: it checks an installed [plugin](https://github.com/JeanFrancoisGagne/crapkit/tree/main/plugin) against the `crapkit` on PATH (the bare name its hooks and MCP server spawn) on both version and hook `--protocol`, and FAILs when PATH carries no `crapkit` at all, one line per disagreement and silence when they agree; PATH is the plugin root or any directory above it, `~/.claude` included (only manifests named `crapkit` count, and the newest install wins), and with no PATH it looks in Claude Code's plugin cache. A root it found rather than one you typed is named first, as `crapkit doctor: checking PATH`. See [docs/agent-json.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#doctor---json). |
 | `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. |
@@ -678,7 +680,7 @@ 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), 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. 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. |
 | `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. |
@@ -686,6 +688,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `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). |
 
 ## Reading the output
@@ -882,11 +885,11 @@ paths = ["calc"]
 languages = ["python"]
 
 [exclude]
-globs = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/vendor/**", "**/*.test.*", "**/*.spec.*", "**/test_*.py", "**/*_test.py", "**/conftest.py", "**/*_test.go", "*.config.ts", "*.config.js", "*.config.mts", "**/*.config.ts", "**/*.config.js", "**/*.config.mts"]
+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"]
 
 [[lane]]
 name = "py"
-command = "python -m pytest --cov --cov-branch --cov-report=json:.crapkit/cov/py.json --junitxml=.crapkit/cov/junit-py.xml"
+command = "python -m pytest --cov --cov-branch --cov-report=json:.crapkit/cov/py.json --junitxml=.crapkit/cov/junit-py.xml --continue-on-collection-errors"
 artifact = ".crapkit/cov/py.json"
 results_artifact = ".crapkit/cov/junit-py.xml"
 parser = "coveragepy"
@@ -895,7 +898,7 @@ scopes = ["calc"]
 # Declare one [[lane]] per coverage command, then run `crapkit coverage`.
 # [[lane]]
 # name = "js"
-# command = "npx vitest run --coverage --coverage.reportsDirectory=.crapkit/cov/js --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml"
+# command = "npx vitest run --coverage --coverage.reportsDirectory=.crapkit/cov/js --coverage.reportOnFailure --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml"
 # artifact = ".crapkit/cov/js/coverage-final.json"
 # results_artifact = ".crapkit/cov/js/junit.xml"
 # parser = "istanbul"
@@ -1010,7 +1013,7 @@ added to .gitignore: .crapkit/
 ```
 
 The lane `init` wrote is
-`npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml`.
+`npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --coverage.reportOnFailure --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml`.
 It reads vitest's `json` reporter from `.crapkit/cov/js/coverage-final.json`; the
 `reportsDirectory` flag is what keeps that report out of your root. The junit half is the
 lane's `results_artifact`, which the crashed-worker and no-new-failures checks read; both
@@ -1029,7 +1032,7 @@ exit 5:
 
 ```
 $ crapkit coverage
-crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/coverage-final.json (command exit 1); full log: /repo/.crapkit/lane-js.log; last output: $ npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml
+crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/coverage-final.json (command exit 1); full log: /repo/.crapkit/lane-js.log; last output: $ npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --coverage.reportOnFailure --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml
 
  MISSING DEPENDENCY  Cannot find dependency '@vitest/coverage-v8'
 
@@ -1057,9 +1060,11 @@ The artifact crapkit wants is `coverage-final.json`, written by vitest's `json`
 reporter, which is on by default. If your vitest config sets `coverage.reporter`
 explicitly, keep `"json"` in the list.
 
-One more vitest default worth flipping now: it writes **no coverage report at all when the
-run fails**, so a single red test becomes a missing artifact and a lane failure. Set
-`coverage.reportOnFailure = true`. The full config block is in
+vitest writes **no coverage report at all when the run fails**. The lane `init` wrote
+already carries `--coverage.reportOnFailure`, so a red test still produces the artifact.
+If you write the lane by hand, or you would rather keep the switch beside your other
+coverage settings, `coverage.reportOnFailure = true` in the vitest config does the same
+job; either one is enough. The full block is in
 [docs/lanes.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/lanes.md#reportonfailure).
 
 ### 3. Score the repo

{crapkit-0.4.11 → crapkit-0.4.12}/README.md

@@ -78,7 +78,9 @@ command when `pytest_cov` is missing; `pip install "crapkit[py]"` pulls the plug
 alongside crapkit when the two share a venv. On a Windows PATH holding only the `py`
 launcher it writes `py`, not a `python3` the lane could never run, and when cmd.exe cannot
 start the interpreter at all (exit 9009, the Store alias) it names that instead of guessing
-at pytest-cov. The two quickstarts below walk a real repo end to end.
+at pytest-cov. A repo that pins no lockfile and carries its own `.venv` gets that venv's
+interpreter in the lane, when that interpreter can import pytest, rather than whichever
+python the shell answers with. The two quickstarts below walk a real repo end to end.
 
 **On Windows a lane command is read by cmd.exe**, the shell that will run it, not by sh.
 Double quotes are the portable quoting. A single-quoted value is refused at config load
@@ -90,7 +92,7 @@ artifact:
 command = "python -m pytest -m 'not live and not perf' --cov=calc --cov-branch --cov-report=json:.crapkit/cov/py.json"
 
 $ crapkit doctor
-crapkit: lane 'py': positional argument 'live' narrows a full-suite coverage run; drop it, attach it to the flag it belongs to (-n8, --numprocesses=8), or set full_suite = false deliberately (cmd.exe does not treat ' as a quote: write the value in double quotes)
+crapkit: lane 'py': positional argument 'live' narrows a full-suite coverage run; drop it, attach it to the flag it belongs to (-n8, --numprocesses=8), or set full_suite = false deliberately (cmd.exe does not treat ' as a quote: write the value in double quotes); a suite whose testpaths cannot be collected in one process needs one lane per testpath, each with full_suite = false and its own artifact
 ```
 
 Write it `-m "not live and not perf"`. Carets, `&&` and `|` segments, redirections and
@@ -124,7 +126,7 @@ leaves the box
 
 ```
 $ crapkit --version
-crapkit 0.4.11
+crapkit 0.4.12
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -354,7 +356,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.11
+    rev: v0.4.12
     hooks:
       - id: crapkit-gate
 ```
@@ -460,7 +462,7 @@ to a workflow, and every input has a default:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: JeanFrancoisGagne/crapkit@v0.4.11
+      - uses: JeanFrancoisGagne/crapkit@v0.4.12
 ```
 
 The whole job those four lines sit in:
@@ -480,7 +482,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.11
+      - uses: JeanFrancoisGagne/crapkit@v0.4.12
         with:
           gate: "false"
 ```
@@ -624,7 +626,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | Command | What it does |
 |---|---|
 | `init` | Sniffs tracked source into per-directory scopes, writes a self-validated starter `crapkit.toml` whose lanes report into `.crapkit/cov/`, and appends `.crapkit/` plus each runner's own droppings to `.gitignore`. Writes a live `[[lane]]` when it can detect the test runner, otherwise a commented template. Refuses to clobber an existing config. |
-| `doctor [--show-files] [--json] [--tune] [--plugin-root [PATH]]` | Checks the config still describes the repo: unknown keys (with the accepted spellings), zero-file scopes, tracked source no scope claims, scopes no lane covers, lane cwds and commands that no longer resolve, lizard importable, oversized files. It reads each lane command with the shell that will run it, so a quoted interpreter path is one word and a runner after `&&` is checked too, and it FAILs a lane whose runner does not resolve on PATH or that the shell cannot start, naming the word to change; each distinct runner is probed once, not once per lane. It WARNs on a lane writing its artifact at the repo root, a `coveragepy` or `istanbul` lane with no `results_artifact` (the crashed-worker and no-new-failures checks are off for it, whichever runner the lane spells), a committed hook under `core.hooksPath` that is not executable in the index, a directory whose functions are all `untested` while its tests exist, and a scope a lane measures with no `[crapkit.scoped_tests]` template behind it, which is the loop's step 4 with nothing to run. `--tune` prints suggested parallelism knobs and writes nothing. `--plugin-root PATH` reads no repo at all: it checks an installed [plugin](https://github.com/JeanFrancoisGagne/crapkit/tree/main/plugin) against this CLI on both version and hook `--protocol`, one line per disagreement and silence when they agree; PATH is the plugin root or any directory above it, `~/.claude` included (only manifests named `crapkit` count, and the newest install wins), and with no PATH it looks in Claude Code's plugin cache. A root it found rather than one you typed is named first, as `crapkit doctor: checking PATH`. See [docs/agent-json.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#doctor---json). |
+| `doctor [--show-files] [--json] [--tune] [--plugin-root [PATH]]` | Checks the config still describes the repo: unknown keys (with the accepted spellings), zero-file scopes, tracked source no scope claims, scopes no lane covers, lane cwds and commands that no longer resolve, lizard importable, oversized files. It reads each lane command with the shell that will run it, so a quoted interpreter path is one word and a runner after `&&` is checked too, and it FAILs a lane whose runner does not resolve or that the shell cannot start, naming the word to change; a bare name is looked for on PATH and a runner spelled as a path is looked for under the directory the lane runs in, so `.venv/bin/python` answers the same from any directory you run `doctor` in; each distinct runner is probed once, not once per lane. It WARNs on a lane writing its artifact at the repo root, a `coveragepy` or `istanbul` lane with no `results_artifact` (the crashed-worker and no-new-failures checks are off for it, whichever runner the lane spells), a committed hook under `core.hooksPath` that is not executable in the index, a directory whose functions are all `untested` while its tests exist, and a scope a lane measures with no `[crapkit.scoped_tests]` template behind it, which is the loop's step 4 with nothing to run. `--tune` prints suggested parallelism knobs and writes nothing. `--plugin-root PATH` reads no repo at all: it checks an installed [plugin](https://github.com/JeanFrancoisGagne/crapkit/tree/main/plugin) against the `crapkit` on PATH (the bare name its hooks and MCP server spawn) on both version and hook `--protocol`, and FAILs when PATH carries no `crapkit` at all, one line per disagreement and silence when they agree; PATH is the plugin root or any directory above it, `~/.claude` included (only manifests named `crapkit` count, and the newest install wins), and with no PATH it looks in Claude Code's plugin cache. A root it found rather than one you typed is named first, as `crapkit doctor: checking PATH`. See [docs/agent-json.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#doctor---json). |
 | `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. |
@@ -639,7 +641,7 @@ 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), 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. 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. |
 | `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. |
@@ -647,6 +649,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `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). |
 
 ## Reading the output
@@ -843,11 +846,11 @@ paths = ["calc"]
 languages = ["python"]
 
 [exclude]
-globs = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/vendor/**", "**/*.test.*", "**/*.spec.*", "**/test_*.py", "**/*_test.py", "**/conftest.py", "**/*_test.go", "*.config.ts", "*.config.js", "*.config.mts", "**/*.config.ts", "**/*.config.js", "**/*.config.mts"]
+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"]
 
 [[lane]]
 name = "py"
-command = "python -m pytest --cov --cov-branch --cov-report=json:.crapkit/cov/py.json --junitxml=.crapkit/cov/junit-py.xml"
+command = "python -m pytest --cov --cov-branch --cov-report=json:.crapkit/cov/py.json --junitxml=.crapkit/cov/junit-py.xml --continue-on-collection-errors"
 artifact = ".crapkit/cov/py.json"
 results_artifact = ".crapkit/cov/junit-py.xml"
 parser = "coveragepy"
@@ -856,7 +859,7 @@ scopes = ["calc"]
 # Declare one [[lane]] per coverage command, then run `crapkit coverage`.
 # [[lane]]
 # name = "js"
-# command = "npx vitest run --coverage --coverage.reportsDirectory=.crapkit/cov/js --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml"
+# command = "npx vitest run --coverage --coverage.reportsDirectory=.crapkit/cov/js --coverage.reportOnFailure --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml"
 # artifact = ".crapkit/cov/js/coverage-final.json"
 # results_artifact = ".crapkit/cov/js/junit.xml"
 # parser = "istanbul"
@@ -971,7 +974,7 @@ added to .gitignore: .crapkit/
 ```
 
 The lane `init` wrote is
-`npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml`.
+`npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --coverage.reportOnFailure --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml`.
 It reads vitest's `json` reporter from `.crapkit/cov/js/coverage-final.json`; the
 `reportsDirectory` flag is what keeps that report out of your root. The junit half is the
 lane's `results_artifact`, which the crashed-worker and no-new-failures checks read; both
@@ -990,7 +993,7 @@ exit 5:
 
 ```
 $ crapkit coverage
-crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/coverage-final.json (command exit 1); full log: /repo/.crapkit/lane-js.log; last output: $ npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml
+crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/coverage-final.json (command exit 1); full log: /repo/.crapkit/lane-js.log; last output: $ npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --coverage.reportOnFailure --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml
 
  MISSING DEPENDENCY  Cannot find dependency '@vitest/coverage-v8'
 
@@ -1018,9 +1021,11 @@ The artifact crapkit wants is `coverage-final.json`, written by vitest's `json`
 reporter, which is on by default. If your vitest config sets `coverage.reporter`
 explicitly, keep `"json"` in the list.
 
-One more vitest default worth flipping now: it writes **no coverage report at all when the
-run fails**, so a single red test becomes a missing artifact and a lane failure. Set
-`coverage.reportOnFailure = true`. The full config block is in
+vitest writes **no coverage report at all when the run fails**. The lane `init` wrote
+already carries `--coverage.reportOnFailure`, so a red test still produces the artifact.
+If you write the lane by hand, or you would rather keep the switch beside your other
+coverage settings, `coverage.reportOnFailure = true` in the vitest config does the same
+job; either one is enough. The full block is in
 [docs/lanes.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/lanes.md#reportonfailure).
 
 ### 3. Score the repo

{crapkit-0.4.11 → crapkit-0.4.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crapkit"
-version = "0.4.11"
+version = "0.4.12"
 description = "Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "MIT" }

{crapkit-0.4.11 → crapkit-0.4.12}/src/crapkit/__init__.py

@@ -1,2 +1,2 @@
 """crapkit: deterministic CRAP-score framework."""
-__version__ = "0.4.11"
+__version__ = "0.4.12"

{crapkit-0.4.11 → crapkit-0.4.12}/src/crapkit/cli/__init__.py

@@ -59,8 +59,10 @@ _OWNER = {
     "_claimable": "queue",
     "_claims_summary": "queue",
     "_claims_to_release": "queue",
+    "_clearing_spellings": "verifying",
     "_collect_lanes": "scoring",
     "_collect_mutants": "analyses",
+    "_committed_launcher": "admin",
     "_config": "claude_hook",
     "_contexts_for_span": "reports",
     "_coupling_pairs": "analyses",
@@ -118,16 +120,21 @@ _OWNER = {
     "_guard_ratchet_stamp": "verifying",
     "_handle": "queue",
     "_held_marks": "verifying",
+    "_help_topic": "parser",
+    "_help_topics": "parser",
     "_hook_handlers": "admin",
     "_hook_modes": "admin",
     "_hook_protocols": "admin",
+    "_imports_pytest": "admin",
     "_installed_crapkit_roots": "admin",
     "_interpreter": "admin",
+    "_is_rooted": "_shared",
     "_is_test_path": "verifying",
     "_judge": "claude_hook",
     "_junit_seconds": "admin",
     "_lane_command_problems": "admin",
     "_lane_durations": "admin",
+    "_lane_path": "admin",
     "_lane_problem": "admin",
     "_lane_problems": "admin",
     "_lane_report": "admin",
@@ -142,18 +149,22 @@ _OWNER = {
     "_load_ratchet_or_die": "_shared",
     "_load_repo_config": "_shared",
     "_load_sources": "_shared",
+    "_looks_like_a_path": "parser",
     "_manifest_field": "admin",
     "_manifest_roots": "admin",
     "_manifest_version": "admin",
     "_mark_text": "queue",
+    "_marker_texts": "admin",
     "_matching_rows": "queue",
     "_maybe_claim": "queue",
     "_marks_for": "claude_hook",
     "_maybe_flake_retry": "verifying",
     "_merge_stamp": "ratchet_cmds",
     "_missing_named_script": "admin",
+    "_missing_runner": "admin",
     "_more_skips_line": "verifying",
     "_mutation_targets": "analyses",
+    "_name_found_root": "admin",
     "_name_matches": "queue",
     "_name_prefix": "queue",
     "_named_baseline": "verifying",
@@ -168,6 +179,7 @@ _OWNER = {
     "_next_reasons": "queue",
     "_next_step": "admin",
     "_no_baseline": "verifying",
+    "_no_crapkit_on_path": "admin",
     "_no_handle_message": "queue",
     "_no_lane_debt": "queue",
     "_no_lane_gap": "queue",
@@ -185,12 +197,14 @@ _OWNER = {
     "_packet_context": "queue",
     "_packet_gate": "queue",
     "_packet_scope": "queue",
+    "_path_first_arg": "parser",
     "_payload": "claude_hook",
     "_pick_baseline": "verifying",
     "_pick_function": "queue",
     "_plugin_json": "admin",
     "_plugins_dir": "admin",
     "_policy_findings": "ratchet_cmds",
+    "_positive_top": "_shared",
     "_present_lockfiles": "admin",
     "_present_markers": "admin",
     "_present_on_disk": "scoring",
@@ -200,6 +214,7 @@ _OWNER = {
     "_print_brief_context": "queue",
     "_print_brief_neighbours": "queue",
     "_print_claims": "queue",
+    "_print_clear_the_reason": "verifying",
     "_print_coverage": "scoring",
     "_print_duplication": "analyses",
     "_print_finding_split": "verifying",
@@ -215,6 +230,7 @@ _OWNER = {
     "_print_trend": "reports",
     "_print_uncovered": "reports",
     "_print_verify_findings": "verifying",
+    "_probed_cli_version": "admin",
     "_progress": "scoring",
     "_prune_renames": "ratchet_cmds",
     "_pruned": "ratchet_cmds",
@@ -227,6 +243,7 @@ _OWNER = {
     "_ratchet_mark": "reports",
     "_ratchet_merge": "ratchet_cmds",
     "_ratchet_move": "ratchet_cmds",
+    "_ratchet_or_die": "_shared",
     "_ratchet_report": "ratchet_cmds",
     "_ratchet_sha256": "verifying",
     "_reconfigure_streams": "parser",
@@ -235,8 +252,12 @@ _OWNER = {
     "_records_by_scope": "scoring",
     "_refuse_empty_lane_run": "scoring",
     "_refuse_lane_less_verify": "verifying",
+    "_refuse_path_argument": "parser",
     "_release_claims": "verifying",
     "_release_target": "queue",
+    "_repo_out_path": "_shared",
+    "_repo_relative": "_shared",
+    "_repo_venv_python": "admin",
     "_report": "claude_hook",
     "_report_lanes": "reports",
     "_report_payload": "reports",
@@ -274,6 +295,7 @@ _OWNER = {
     "_sequencing": "claude_hook",
     "_settle_verify": "verifying",
     "_skip_reason": "queue",
+    "_spawned_cli": "admin",
     "_split_marked": "verifying",
     "_split_worklist": "queue",
     "_stale_warning": "queue",
@@ -292,12 +314,15 @@ _OWNER = {
     "_uncovered_fields": "queue",
     "_uncovered_scopes": "admin",
     "_uncovered_text": "reports",
+    "_under_root": "_shared",
     "_under_scope_path": "verifying",
     "_unknown_key_text": "admin",
     "_unmarked_breaches": "scoring",
     "_unknown_claude_command": "parser",
     "_untracked_of": "scoring",
     "_untrusted_reason": "verifying",
+    "_venv_dirs": "admin",
+    "_venv_launcher": "admin",
     "_verdict": "claude_hook",
     "_verify_attribution": "verifying",
     "_verify_baseline": "verifying",
@@ -335,6 +360,7 @@ _OWNER = {
     "cmd_doctor": "admin",
     "cmd_duplication": "analyses",
     "cmd_explain": "reports",
+    "cmd_help": "parser",
     "cmd_hook_precommit": "verifying",
     "cmd_init": "admin",
     "cmd_inventory": "scoring",