crapkit 0.4.2__tar.gz → 0.4.4__tar.gz

{crapkit-0.4.2/src/crapkit.egg-info → crapkit-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.2
+Version: 0.4.4
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -29,6 +29,8 @@ Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
 Requires-Dist: pytest-xdist>=3; extra == "dev"
+Provides-Extra: py
+Requires-Dist: pytest-cov>=5; extra == "py"
 Dynamic: license-file
 
 # crapkit
@@ -93,7 +95,10 @@ the repo can get better and never worse while you burn it down.
 out to your own test runner, and the runner needs its coverage package installed:
 `pytest-cov` for pytest, `@vitest/coverage-v8` (pinned to your vitest major) for vitest.
 Without it the lane produces no artifact and `coverage` exits 5 quoting the runner's own
-error. The two quickstarts below walk a real repo end to end.
+error. For pytest, `init` probes the python its lane will run and prints the install
+command when `pytest_cov` is missing; `pip install 'crapkit[py]'` pulls the plugin
+alongside crapkit when the two share a venv. The two quickstarts below walk a real repo
+end to end.
 
 ## Install
 
@@ -116,7 +121,7 @@ changing crapkit.
 
 ```
 $ crapkit --version
-crapkit 0.4.2
+crapkit 0.4.4
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -124,6 +129,22 @@ source checkout. Every subcommand accepts `--repo PATH` (default: the current di
 so you never have to `cd` into the repo you are scoring. The flag goes after the
 subcommand; [Subcommands](#subcommands) shows both orders.
 
+### Upgrading on Windows
+
+`uv tool upgrade crapkit`, and `pip install -U` into a tool venv, fail with `os error 32`
+("The process cannot access the file because it is being used by another process") while a
+crapkit MCP server is live: an agent session spawns `crapkit.exe mcp`, which holds the
+launcher, and Windows will not overwrite a running executable. The venv upgrades before
+that copy fails, so `crapkit --version` already reports the new version and the launcher is
+the only stale piece. Quit the agent session and rerun the upgrade, or rename the locked
+exe aside (Windows allows renaming a running one) and copy the new one in; the `.old` file
+goes at the next reboot.
+
+```
+mv ~/.local/bin/crapkit.exe ~/.local/bin/crapkit.exe.old
+cp %APPDATA%/uv/tools/crapkit/Scripts/crapkit.exe ~/.local/bin/crapkit.exe
+```
+
 ## The Claude Code plugin
 
 ```
@@ -247,7 +268,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.2
+    rev: v0.4.4
     hooks:
       - id: crapkit-gate
 ```
@@ -321,11 +342,11 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `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 WARNs on a lane writing its artifact at the repo root, 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](plugin/) against this CLI on both version and hook `--protocol`, one line per disagreement and silence when they agree. See [docs/agent-json.md](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](docs/lanes.md). |
-| `verify [--baseline ID \| --base REF \| --baseline-tsv PATH] [--emit-baseline PATH] [--override REASON] [--reuse-artifacts] [--reuse-unchanged] [--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. Findings a dirty tree produced are tagged `dirty` and counted apart. |
+| `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. |
 | `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; 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. |
 | `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, or `(anonymous)#N` for a function printed `(anonymous)`, counting the file's anonymous functions from the top. `--batch N` drops the positionals and emits `packets[]` instead: the top N of the queue, built from one read of the store. |
+| `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. |
 | `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. `--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](docs/lanes.md#test-attribution-for-explain---tests)). `--json` emits the same content as one `schema` 1 object. |
 | `rescore FILE ... [--gate] [--json]` | Fresh complexity for named files over the latest run's stale coverage, joined by name. Advisory: it writes no run. `--gate` applies the pre-commit hook's policy to the same selection the hook uses (functions the tree changed since HEAD), minus functions a ratchet mark already covers, and exits 6. |
 | `ratchet seed \| prune \| merge \| move \| report [--enforce] [--json]` | The mark lifecycle: seed new debt, prune gone code (a mark whose file git renamed follows it), merge as a git driver, move re-paths marks, report reads burn-down from the file's own git history. See [docs/ratchet.md](docs/ratchet.md). |
@@ -334,7 +355,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `trend [--json]` | Totals per trusted run: functions, over-target count, CRAP load, average, per-scope rollup. |
 | `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. |
-| `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. |
+| `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. |
 | `mutate [--files F ...] [--max-mutants N] [--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. |
 | `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. |
@@ -412,7 +433,9 @@ baseline**. `crapkit runs list` marks which one that is today.
 never qualifies, and neither does a `partial` run (a lane failed, so some scope fell back
 to `no-lane`) nor a `hook` override record, which carries no scored rows at all. In `runs
 list`, `verdict=-` marks a run that produces no verdict rather than one that failed: only
-`verify` renders a verdict.
+`verify` renders a verdict. Three readers ask this one question and get this one answer:
+the baseline pick here, `ratchet seed` and `prune`, and the tighten damping that compares a
+mark against the same commit's previous run.
 
 **What advances it.** Any qualifying run. `coverage` writes one wherever HEAD is, so a
 dashboard cron advances the baseline exactly as CI does. A passing `verify` advances it
@@ -487,6 +510,10 @@ writes runs `pytest --cov` and those flags come from `pytest-cov`:
 pip install pytest-cov
 ```
 
+(or `pip install 'crapkit[py]'` to pull both at once, when crapkit lives in the same venv
+as the suite — skip it and `init` prints this same fix when its probe finds the plugin
+missing).
+
 ### 1. Scaffold the config
 
 ```

{crapkit-0.4.2 → crapkit-0.4.4}/README.md

@@ -60,7 +60,10 @@ the repo can get better and never worse while you burn it down.
 out to your own test runner, and the runner needs its coverage package installed:
 `pytest-cov` for pytest, `@vitest/coverage-v8` (pinned to your vitest major) for vitest.
 Without it the lane produces no artifact and `coverage` exits 5 quoting the runner's own
-error. The two quickstarts below walk a real repo end to end.
+error. For pytest, `init` probes the python its lane will run and prints the install
+command when `pytest_cov` is missing; `pip install 'crapkit[py]'` pulls the plugin
+alongside crapkit when the two share a venv. The two quickstarts below walk a real repo
+end to end.
 
 ## Install
 
@@ -83,7 +86,7 @@ changing crapkit.
 
 ```
 $ crapkit --version
-crapkit 0.4.2
+crapkit 0.4.4
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -91,6 +94,22 @@ source checkout. Every subcommand accepts `--repo PATH` (default: the current di
 so you never have to `cd` into the repo you are scoring. The flag goes after the
 subcommand; [Subcommands](#subcommands) shows both orders.
 
+### Upgrading on Windows
+
+`uv tool upgrade crapkit`, and `pip install -U` into a tool venv, fail with `os error 32`
+("The process cannot access the file because it is being used by another process") while a
+crapkit MCP server is live: an agent session spawns `crapkit.exe mcp`, which holds the
+launcher, and Windows will not overwrite a running executable. The venv upgrades before
+that copy fails, so `crapkit --version` already reports the new version and the launcher is
+the only stale piece. Quit the agent session and rerun the upgrade, or rename the locked
+exe aside (Windows allows renaming a running one) and copy the new one in; the `.old` file
+goes at the next reboot.
+
+```
+mv ~/.local/bin/crapkit.exe ~/.local/bin/crapkit.exe.old
+cp %APPDATA%/uv/tools/crapkit/Scripts/crapkit.exe ~/.local/bin/crapkit.exe
+```
+
 ## The Claude Code plugin
 
 ```
@@ -214,7 +233,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.2
+    rev: v0.4.4
     hooks:
       - id: crapkit-gate
 ```
@@ -288,11 +307,11 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `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 WARNs on a lane writing its artifact at the repo root, 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](plugin/) against this CLI on both version and hook `--protocol`, one line per disagreement and silence when they agree. See [docs/agent-json.md](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](docs/lanes.md). |
-| `verify [--baseline ID \| --base REF \| --baseline-tsv PATH] [--emit-baseline PATH] [--override REASON] [--reuse-artifacts] [--reuse-unchanged] [--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. Findings a dirty tree produced are tagged `dirty` and counted apart. |
+| `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. |
 | `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; 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. |
 | `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, or `(anonymous)#N` for a function printed `(anonymous)`, counting the file's anonymous functions from the top. `--batch N` drops the positionals and emits `packets[]` instead: the top N of the queue, built from one read of the store. |
+| `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. |
 | `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. `--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](docs/lanes.md#test-attribution-for-explain---tests)). `--json` emits the same content as one `schema` 1 object. |
 | `rescore FILE ... [--gate] [--json]` | Fresh complexity for named files over the latest run's stale coverage, joined by name. Advisory: it writes no run. `--gate` applies the pre-commit hook's policy to the same selection the hook uses (functions the tree changed since HEAD), minus functions a ratchet mark already covers, and exits 6. |
 | `ratchet seed \| prune \| merge \| move \| report [--enforce] [--json]` | The mark lifecycle: seed new debt, prune gone code (a mark whose file git renamed follows it), merge as a git driver, move re-paths marks, report reads burn-down from the file's own git history. See [docs/ratchet.md](docs/ratchet.md). |
@@ -301,7 +320,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `trend [--json]` | Totals per trusted run: functions, over-target count, CRAP load, average, per-scope rollup. |
 | `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. |
-| `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. |
+| `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. |
 | `mutate [--files F ...] [--max-mutants N] [--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. |
 | `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. |
@@ -379,7 +398,9 @@ baseline**. `crapkit runs list` marks which one that is today.
 never qualifies, and neither does a `partial` run (a lane failed, so some scope fell back
 to `no-lane`) nor a `hook` override record, which carries no scored rows at all. In `runs
 list`, `verdict=-` marks a run that produces no verdict rather than one that failed: only
-`verify` renders a verdict.
+`verify` renders a verdict. Three readers ask this one question and get this one answer:
+the baseline pick here, `ratchet seed` and `prune`, and the tighten damping that compares a
+mark against the same commit's previous run.
 
 **What advances it.** Any qualifying run. `coverage` writes one wherever HEAD is, so a
 dashboard cron advances the baseline exactly as CI does. A passing `verify` advances it
@@ -454,6 +475,10 @@ writes runs `pytest --cov` and those flags come from `pytest-cov`:
 pip install pytest-cov
 ```
 
+(or `pip install 'crapkit[py]'` to pull both at once, when crapkit lives in the same venv
+as the suite — skip it and `init` prints this same fix when its probe finds the plugin
+missing).
+
 ### 1. Scaffold the config
 
 ```

{crapkit-0.4.2 → crapkit-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crapkit"
-version = "0.4.2"
+version = "0.4.4"
 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" }
@@ -53,6 +53,11 @@ Source = "https://github.com/JeanFrancoisGagne/crapkit"
 # without it. Left out of this list it took down 31 e2e tests on every one of
 # the six CI test jobs (run 33225190806), ubuntu and windows alike.
 dev = ["pytest>=8", "pytest-cov>=5", "pytest-xdist>=3"]
+# The py lane's runtime half, for installs that share the suite's venv: the
+# lane init writes runs `pytest --cov`, and those flags come from pytest-cov.
+# An install elsewhere (pipx, uv tool) still needs pytest-cov beside the SUITE;
+# init probes for that and prints the fix.
+py = ["pytest-cov>=5"]
 
 [project.scripts]
 crapkit = "crapkit.cli:main"

{crapkit-0.4.2 → crapkit-0.4.4}/src/crapkit/__init__.py

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

{crapkit-0.4.2 → crapkit-0.4.4}/src/crapkit/analyze.py

@@ -160,10 +160,11 @@ _NAMES_SHOWN = 5
 def _colliding_names(records: list[FunctionRecord]) -> list[str]:
     """Names this file gives to more than one function, in first-seen order.
 
-    Anonymous functions are exempt. lizard calls every one of them
+    Anonymous functions are exempt from the line. lizard calls every one of them
     `(anonymous)`, so a file with two arrow callbacks collides by construction
-    and a warning would name nothing anyone could act on; `packet.handles`
-    answers that collision with the `(anonymous)#N` ordinal instead.
+    and the line would name nothing anyone could act on. They take the same
+    ordinal keys as any other twin; `packet.handles` already addresses them as
+    `(anonymous)#N`.
     """
     seen: set[str] = set()
     colliding: dict[str, None] = {}
@@ -174,23 +175,26 @@ def _colliding_names(records: list[FunctionRecord]) -> list[str]:
     return list(colliding)
 
 
-def _warn_on_collisions(rel_path: str, records: list[FunctionRecord]) -> None:
-    """One stderr line for a file whose records cannot all reach the ratchet.
+def _note_twin_keys(rel_path: str, records: list[FunctionRecord]) -> None:
+    """One stderr line for a file that gives one name to more than one function.
 
-    A mark is keyed on (path, long_name), and so is the row a run writes, so the
-    last function under a colliding name is the only one marked and the only one
-    gated. C makes this ordinary: both arms of an `#ifdef` fork are textually
-    present, so a platform shim defines the same function twice in one file.
-    Python makes it ordinary too, because a method's long_name carries no class.
-    Neither is fixable here — the ratchet cannot key on a span, which drifts with
-    every edit — so the loss is announced rather than silent.
+    Information, not a warning. Until 0.4.2 it was the second: a mark keyed on
+    (path, long_name) meant one twin owned the key and the rest were neither
+    marked nor gated, which is the loss this announced. `keys` ends that by
+    giving each twin its own ordinal, so the line now says what a reader will
+    see in `crapkit-ratchet.tsv` and nothing is lost.
+
+    Still printed, because a `#2` appearing in a committed marks file is
+    otherwise unexplained. C makes the shape ordinary — both arms of an `#ifdef`
+    fork are textually present — and so does Python, whose method long_names
+    carry no class.
     """
     names = _colliding_names(records)
     if not names:
         return
-    print(f"crapkit: {rel_path} defines {_listed(names)} more than once; the ratchet keys "
-          f"on (path, long_name) and keeps the last, so the earlier ones are neither "
-          f"marked nor gated", file=sys.stderr)
+    print(f"crapkit: {rel_path} defines {_listed(names)} more than once; each one takes "
+          f"its own ratchet key — the first as written, later ones suffixed #2, #3 in "
+          f"file order", file=sys.stderr)
 
 
 def _listed(names: list[str]) -> str:
@@ -201,7 +205,7 @@ def _listed(names: list[str]) -> str:
 
 def _file_records(rel_path: str, functions) -> list[FunctionRecord]:
     records = [_record(rel_path, fn) for fn in functions]
-    _warn_on_collisions(rel_path, records)
+    _note_twin_keys(rel_path, records)
     return records
 
 

{crapkit-0.4.2 → crapkit-0.4.4}/src/crapkit/churn_cache.py

@@ -5,10 +5,12 @@ git diffing every commit's tree, and worklist, next-item and coupling each paid
 it in full on every invocation, at an unmoved HEAD. Every one of them reaches
 git through this module, so `.crapkit/churn-cache.json` has exactly one writer.
 
-The key is (HEAD sha, window months, UTC date). The sha pins the history; the
-window pins the command; the date is there because `--since=N months ago` is
-evaluated against the wall clock, so yesterday's cache describes a window one
-day wider than today's. Anything else is a miss, and a miss rebuilds.
+The key is (HEAD sha, window months, UTC date, path format). The sha pins the
+history; the window pins the command; the date is there because `--since=N
+months ago` is evaluated against the wall clock, so yesterday's cache describes
+a window one day wider than today's; the format marker retires maps whose
+paths predate `git log --relative`. Anything else is a miss, and a miss
+rebuilds.
 
 A cache is disposable: unreadable, corrupt or unkeyable content reads as cold,
 never as a crash. Uncommitted work is invisible to churn either way. The one
@@ -23,7 +25,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from .churn import FileChurn, parse_git_log_lines
-from .churn_log import has_cache, log_lines
+from .churn_log import RELATIVE_PATHS, has_cache, log_lines
 from .errors import GitError
 from .gitio import churn_log_lines, head_commit
 
@@ -64,7 +66,10 @@ def _cache_key(root: Path, months: int) -> dict | None:
         head = head_commit(root)
     except GitError:
         return None
-    return {"head": head, "months": months, "date": _utc_date()}
+    # `paths` marks the format, not a question: maps built before --relative
+    # hold top-relative paths in a subdirectory root, and must read as cold.
+    return {"head": head, "months": months, "date": _utc_date(),
+            "paths": RELATIVE_PATHS}
 
 
 def _read_cache(path: Path, key: dict | None) -> dict[str, FileChurn] | None:

{crapkit-0.4.2 → crapkit-0.4.4}/src/crapkit/churn_log.py

@@ -42,6 +42,11 @@ from .gitio import _git_lines, head_commit, is_ancestor
 LOG_NAME = "churn-log.z"
 LOG_FORMAT = "--format=%x01%an%x02%at%x02%ct"
 CHUNK = 1 << 20
+# The key's format marker: these logs hold root-relative paths (--relative),
+# the only kind that joins against ls-files rows when the root sits below the
+# repo top. A key without it names a top-relative log, and that one is cold —
+# served OR refreshed, it would feed every consumer paths that match nothing.
+RELATIVE_PATHS = "root-relative"
 
 
 def log_lines(root: Path, months: int) -> Iterator[str]:
@@ -103,7 +108,8 @@ def _cache_key(root: Path, months: int) -> dict | None:
         head = head_commit(root)
     except GitError:
         return None
-    return {"head": head, "months": months, "date": _utc_date()}
+    return {"head": head, "months": months, "date": _utc_date(),
+            "paths": RELATIVE_PATHS}
 
 
 def _key_path(path: Path) -> Path:
@@ -119,7 +125,7 @@ def _read_key(path: Path) -> dict | None:
 
 
 def _key_fields(doc: dict) -> dict:
-    return {field: doc.get(field) for field in ("head", "months", "date")}
+    return {field: doc.get(field) for field in ("head", "months", "date", "paths")}
 
 
 def _cached(path: Path, key: dict | None) -> Iterator[str] | None:
@@ -173,9 +179,12 @@ def _refreshed(root: Path, months: int, path: Path, key: dict | None) -> Iterato
 
 
 def _refreshable(root: Path, stored: dict | None, key: dict) -> bool:
-    """True only for a cached log this HEAD grew from: same window, and behind us."""
+    """True only for a cached log this HEAD grew from: same window, same path
+    format, and behind us."""
     if stored is None or stored.get("months") != key["months"]:
         return False
+    if stored.get("paths") != key["paths"]:
+        return False  # a top-relative log: prepending would stack fresh commits on wrong paths
     if stored.get("head") == key["head"]:
         return True
     return is_ancestor(root, str(stored.get("head")), key["head"])
@@ -262,13 +271,16 @@ def _keep(part: BinaryIO, path: Path, key: dict | None) -> None:
 
 
 def _window_log(root: Path, months: int) -> Iterator[str]:
-    """The whole window, from git. The expensive one."""
-    return _git_lines(root, "log", f"--since={months} months ago", LOG_FORMAT, "--name-only")
+    """The whole window, from git. The expensive one. --relative for the same
+    reason gitio.churn_log_lines carries it: consumers join these paths against
+    root-relative rows, and a root below the repo top matched nothing without it."""
+    return _git_lines(root, "log", "--relative", f"--since={months} months ago",
+                      LOG_FORMAT, "--name-only")
 
 
 def _range_log(root: Path, base: str, head: str) -> Iterator[str]:
     """Only what HEAD added on top of the cached log."""
-    return _git_lines(root, "log", f"{base}..{head}", LOG_FORMAT, "--name-only")
+    return _git_lines(root, "log", "--relative", f"{base}..{head}", LOG_FORMAT, "--name-only")
 
 
 def _window_cutoff(root: Path, months: int) -> int | None:

{crapkit-0.4.2 → crapkit-0.4.4}/src/crapkit/cli/__init__.py

@@ -109,6 +109,7 @@ _OWNER = {
     "_group_files_by_scope": "verifying",
     "_guard_ratchet_stamp": "verifying",
     "_handle": "queue",
+    "_held_marks": "verifying",
     "_hook_handlers": "admin",
     "_hook_modes": "admin",
     "_hook_protocols": "admin",
@@ -160,6 +161,8 @@ _OWNER = {
     "_no_line_message": "queue",
     "_no_match_message": "queue",
     "_no_scopes_reason": "admin",
+    "_no_tighten_line": "verifying",
+    "_no_twin_message": "queue",
     "_note_marked_staged": "verifying",
     "_note_stale_staged": "verifying",
     "_open_store": "_shared",
@@ -176,6 +179,7 @@ _OWNER = {
     "_policy_findings": "ratchet_cmds",
     "_present_markers": "admin",
     "_present_on_disk": "scoring",
+    "_prior_crap": "verifying",
     "_print_batches": "queue",
     "_print_brief": "queue",
     "_print_brief_context": "queue",
@@ -200,6 +204,7 @@ _OWNER = {
     "_prune_renames": "ratchet_cmds",
     "_pruned": "ratchet_cmds",
     "_pushdown_floor": "queue",
+    "_pytest_cov_probe": "admin",
     "_range_lines": "analyses",
     "_rankable": "queue",
     "_ratchet_entries": "_shared",
@@ -283,6 +288,7 @@ _OWNER = {
     "_version_line": "parser",
     "_version_report": "admin",
     "_warn_diff_uncovered": "verifying",
+    "_warn_missing_pytest_cov": "admin",
     "_warn_suite_shrink": "verifying",
     "_warn_untracked": "scoring",
     "_watch_banner": "admin",

{crapkit-0.4.2 → crapkit-0.4.4}/src/crapkit/cli/admin.py

@@ -6,12 +6,13 @@ what moved)."""
 from __future__ import annotations
 
 import argparse
+import os
 import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 
 from .. import __version__
-from ..config import load_config_text
+from ..config import load_config_text, shell_words
 from ..doctor import Finding
 from ..errors import ConfigError, ToolError
 from ..gitio import ls_files
@@ -82,6 +83,51 @@ def _no_scopes_reason(root: Path) -> str:
             f"run `git add` first ({len(untracked)} untracked source file(s) found)")
 
 
+def _pytest_cov_probe(command: str) -> bool:
+    """Can the interpreter this lane names import pytest_cov? The probe runs
+    through the same shell as the lane, so a bare `python` resolves to the one
+    the lane will get (a .bat shim included), not the one CreateProcess finds.
+    True too when the probe cannot run — only a clean "no" earns the warning,
+    and a missing interpreter is doctor's finding, not this one's."""
+    import shutil
+    import subprocess
+
+    words = shell_words(command)
+    if not words or shutil.which(words[0]) is None:
+        return True
+    probe = f'{_shell_quote(words[0])} -c "import pytest_cov"'
+    try:
+        return subprocess.run(probe, shell=True, capture_output=True,
+                              timeout=15).returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return True
+
+
+def _shell_quote(word: str) -> str:
+    """One word, quoted for the shell the lane runs under."""
+    import shlex
+
+    if os.name != "nt":
+        return shlex.quote(word)
+    return f'"{word}"' if " " in word else word
+
+
+def _warn_missing_pytest_cov(lanes: tuple) -> None:
+    """The first-run trap, caught where it starts. The py lane shells out to
+    `pytest --cov`, and the --cov flags come from pytest-cov — a package of the
+    REPO's interpreter, so a crapkit dependency could only ever cover installs
+    sharing the suite's venv. Probe the python the lane will actually run and
+    say the fix now, instead of `coverage` exiting 5 with a lane log the first
+    run has to decode."""
+    for lane in lanes:
+        if lane.parser == "coveragepy" and "--cov" in lane.command \
+                and not _pytest_cov_probe(lane.command):
+            print(f"note: lane {lane.name!r} runs `pytest --cov`, and this python cannot "
+                  "import pytest_cov — pip install pytest-cov where the suite runs "
+                  "(pip install 'crapkit[py]' when that is crapkit's own environment), "
+                  "then `crapkit coverage`", file=sys.stderr)
+
+
 def _extend_gitignore(root: Path, lanes: tuple) -> None:
     """Ignore what adopting crapkit will write: the store, and each lane's
     artifact. Without this the consumer's next `git status` is a wall of
@@ -115,6 +161,7 @@ def cmd_init(args: argparse.Namespace) -> int:
     load_config_text(text)  # self-check: never write a config crapkit cannot read back
     toml_path.write_text(text, encoding="utf-8", newline="\n")
     _print_init_summary(scopes, lanes)
+    _warn_missing_pytest_cov(live_lanes(lanes, scopes))
     _extend_gitignore(root, live_lanes(lanes, scopes))
     return 0
 

{crapkit-0.4.2 → crapkit-0.4.4}/src/crapkit/cli/claude_hook.py

@@ -154,7 +154,7 @@ def _judge(root: Path, rel: str) -> int:
     records = _records(root, rel)
     ranges = _changed(root, rel, diff.communicate()[0])
     breaches, ceiling = _verdict(cfg, in_scope, rel, records, ranges)
-    return _report(root, cfg, rel, breaches, ceiling)
+    return _report(root, cfg, rel, breaches, ceiling, _keys(records))
 
 
 def _config(root: Path):
@@ -260,11 +260,21 @@ def _answerable(over: list, ranges) -> list:
     return [rec for rec in over if _touches(rec, ranges)]
 
 
-def _report(root: Path, cfg, rel: str, breaches: list, ceiling: int) -> int:
+def _keys(records: list) -> dict:
+    """The file's ratchet keys, built from every record rather than the breaching
+    ones: the ordinal counts same-named functions in file order."""
+    from ..keys import key_names
+
+    return key_names(records)
+
+
+def _report(root: Path, cfg, rel: str, breaches: list, ceiling: int, keys: dict) -> int:
     """Rung 9. stdout stays empty whatever happens: protocol 1 reserves it for a
     future JSON channel, and Claude Code parses stdout JSON on exit 0."""
+    from ..keys import key_of
+
     marked = _marks_for(root / cfg.ratchet_file, rel)
-    unmarked = [rec for rec in breaches if rec.long_name not in marked]
+    unmarked = [rec for rec in breaches if key_of(keys, rec)[1] not in marked]
     if not unmarked:
         return 0
     for line in _advisory_lines(rel, unmarked, ceiling):
@@ -273,7 +283,7 @@ def _report(root: Path, cfg, rel: str, breaches: list, ceiling: int) -> int:
 
 
 def _marks_for(marks_path: Path, rel: str) -> set[str]:
-    """The function names one file carries ratchet marks for.
+    """The ratchet KEY names one file carries marks for, `#N` ordinals included.
 
     Existence, not the numeric high-water rule `verify` applies: crap needs
     coverage, coverage needs the store, and the store stays closed. A mark is a

{crapkit-0.4.2 → crapkit-0.4.4}/src/crapkit/cli/parser.py

@@ -286,6 +286,8 @@ def build_parser() -> argparse.ArgumentParser:
                      help="rerun only lanes whose scope files changed since their artifact; reuse the rest")
     ver.add_argument("--override", default=None, metavar="REASON",
                      help="audited exemption for gate violations: alert + ratchet debt + snapshot record")
+    ver.add_argument("--no-tighten", action="store_true",
+                     help="pass the verdict without rewriting the ratchet; marks stay where they are")
     ver.add_argument("--sarif", default=None, metavar="PATH",
                      help="write gate/ratchet findings as SARIF 2.1.0, relative to the repo")
     ver.add_argument("--github", action="store_true",