crapkit 0.4.1__tar.gz → 0.4.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.1
+Version: 0.4.2
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -28,6 +28,7 @@ Requires-Dist: lizard>=1.24.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: pytest-xdist>=3; extra == "dev"
 Dynamic: license-file
 
 # crapkit
@@ -115,7 +116,7 @@ changing crapkit.
 
 ```
 $ crapkit --version
-crapkit 0.4.1
+crapkit 0.4.2
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -165,10 +166,16 @@ lane. Nothing about it is provisional: the ceiling still binds and the gate stil
 a function over it. Add a coverage lane the day a parser exists and the same scope starts
 joining coverage.
 
+`crapkit init` writes that key itself, on every scope whose languages all lack a parser,
+and leaves it off any scope a lane could still measure. So the 60-second start above runs
+unchanged on a Go, Rust or shell repo: `crapkit coverage` scores it with no lane at all,
+and that run is the baseline `worklist`, `next-item`, `ratchet seed` and `verify` read.
+
 Three readers are crapkit's own. lizard ships none for shell or PowerShell, so crapkit
 counts their functions itself. Its Rust reader scores a 7-arm `match` as ccn 2 (filed as
 lizard #494), so crapkit counts each non-wildcard arm like a C `case` and retires the
-override the day upstream fixes it.
+override the day upstream fixes it. The cognitive column charges that same block once,
+the way Sonar charges a `switch`.
 
 ## The gate
 
@@ -178,8 +185,8 @@ different powers:
 | Surface | Fires | Power |
 |---|---|---|
 | `crapkit claude-hook` | after an agent's edit lands | **advisory.** Names the breach on stderr. Blocks nothing, because PostToolUse runs after the write |
-| `crapkit rescore FILE --gate` | when you ask | **preview.** The commit gate's verdict on demand, sub-second, before you stage |
-| `crapkit hook-precommit` | `git commit` | **blocks.** Exit 6. Staged blobs only, so it costs the size of the commit and needs no coverage |
+| `crapkit rescore FILE --gate` | when you ask, after the first coverage run | **preview.** The commit gate's verdict on demand, sub-second, before you stage. With no run behind it, exit 1 and `no snapshot` |
+| `crapkit hook-precommit` | `git commit` | **blocks.** The hook exits 6; git reports 1. Staged blobs only, so it costs the size of the commit and needs no coverage |
 | `crapkit verify` | before you push, and in CI | **the verdict.** Gate, ratchet, new test failures, diff coverage, against the trusted baseline |
 
 Both hooks exempt a function the committed ratchet already carries a mark for, so touching
@@ -239,7 +246,8 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 ```yaml
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
-    rev: v0.4.0
+    # crapkit's release step rewrites this line to the tag it just cut
+    rev: v0.4.2
     hooks:
       - id: crapkit-gate
 ```
@@ -275,7 +283,9 @@ crapkit gate: 1 staged function(s) exceed the complexity ceiling of 6:
 decompose before committing (coverage cannot save a function above the target).
 ```
 
-Run directly, `crapkit hook-precommit` exits 6 on a violation and 0 otherwise.
+That commit exited **1**, not 6. Git collapses any failed hook to 1, so 6 is a code you
+only ever see by running the hook yourself: `crapkit hook-precommit` exits 6 on a
+violation and 0 otherwise. The stderr block above is the same either way.
 
 `CRAPKIT_OVERRIDE_REASON` is not a bypass. Setting it routes the commit through the full
 three-record audit: an alert line through `alert_command`, a ratchet entry staged into the
@@ -316,7 +326,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `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. |
-| `explain FILE NAME [--history] [--tests] [--json]` | A function's score across runs plus its mark. `--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. |
+| `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). |
 | `runs [list \| prune [--keep N]] [--json]` | Run history, and retention. `list` marks the run `verify` compares against today `baseline`, and prints `verdict=-` for a run that produces no verdict rather than one that failed. See [The trusted baseline](#the-trusted-baseline). `--keep` (default 5) is a floor on the newest trusted runs, not a cap: the digest pair, every passing verify baseline, every run an override names, and the newest non-hook run are kept too. `prune` VACUUMs afterwards. |
@@ -536,6 +546,11 @@ makes it step 4 of the burn-down loop. Every key is in
 
 ```
 $ crapkit doctor
+ok   config keys all recognized
+ok   scope 'calc': 1 files
+ok   every tracked source file belongs to a scope
+ok   1 lane(s) declared
+ok   lizard 1.24.0
 doctor: no problems found
 ```
 
@@ -567,11 +582,12 @@ worklist has none.
 
 ```
 $ crapkit next-item
-{"commit": "fae4db93108b4841a00959f9117430679e7250ca", "empty": false, "item": {"authors": 1, "ccn": 14, "ccn_std": 14, "cognitive": 13, "commits": 1, "cov": 0.5, "crap": 38.5, "end": 28, "est_splits": 3, "est_uncovered_paths": 7, "flag": "measured", "function": "classify( score , attempts , late , bonus )", "nesting": 8, "nloc": 22, "path": "calc/grade.py", "remedy": "decompose", "scope": "calc", "start": 7, "target": 6, "uncovered_lines": [9, 11, 15, 17, 19, 24, 25, 26, 27, 28]}, "run_id": 1, "schema": 1, "skipped_no_lane": 0}
+{"commit": "fae4db93108b4841a00959f9117430679e7250ca", "empty": false, "item": {"authors": 1, "ccn": 14, "ccn_std": 14, "cognitive": 13, "commits": 1, "cov": 0.5, "crap": 38.5, "end": 28, "est_splits": 3, "est_uncovered_paths": 7, "flag": "measured", "function": "classify( score , attempts , late , bonus )", "handle": "classify", "nesting": 8, "nloc": 22, "path": "calc/grade.py", "remedy": "decompose", "scope": "calc", "start": 7, "target": 6, "uncovered_lines": [9, 11, 15, 17, 19, 24, 25, 26, 27, 28]}, "run_id": 1, "schema": 1, "skipped_no_lane": 0, "stale": false}
 ```
 
 `remedy: "decompose"`, `est_splits: 3` (this needs roughly three pieces to fit under 6),
-and `uncovered_lines` naming the ten lines no test walks. Every field is in
+and `uncovered_lines` naming the ten lines no test walks. `handle` is the name form to
+pass back, and `stale: false` says the run still describes HEAD. Every field is in
 [docs/agent-json.md](docs/agent-json.md).
 
 ### 5. Seed the ratchet
@@ -648,17 +664,21 @@ crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/cov
 crapkit: every lane failed: ...
 ```
 
-Install the provider, pinned to your vitest major or npm refuses the peer dependency:
+That failure **writes no run**. Every lane failed, so `coverage` exits before it opens a
+store: there is no `.crapkit/crap.sqlite` yet and the run ids below still start at 1.
+
+Install the provider, and pin the major yourself. Unpinned, npm resolves the newest
+provider against your older vitest and refuses the tree:
 
 ```
-npm i -D @vitest/coverage-v8
+npm i -D "@vitest/coverage-v8@<your vitest major>"
 ```
 
 | Question | Answer |
 |---|---|
 | Which provider? | Either works. `@vitest/coverage-v8` is vitest's default and needs no config. `@vitest/coverage-istanbul` also works and needs `coverage.provider = "istanbul"` in your vitest config. |
 | Which crapkit parser? | Both feed `parser = "istanbul"`. The provider name and the parser name are unrelated: v8 output is remapped to the istanbul JSON schema before it is written. |
-| Which version? | It must match your vitest major. npm refuses the install otherwise (`peer vitest@"4.x" from @vitest/coverage-v8@4.x`). On vitest 2, `npm i -D "@vitest/coverage-v8@2"`. |
+| Which version? | The provider's major has to match vitest's. On vitest 2 that is `npm i -D "@vitest/coverage-v8@2"`, on vitest 3 `npm i -D "@vitest/coverage-v8@3"`. Drop the pin and npm answers `ERESOLVE unable to resolve dependency tree`, naming the peer it could not satisfy. |
 
 The artifact crapkit wants is `coverage-final.json`, written by vitest's `json` coverage
 reporter, which is on by default. If your vitest config sets `coverage.reporter`

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

@@ -83,7 +83,7 @@ changing crapkit.
 
 ```
 $ crapkit --version
-crapkit 0.4.1
+crapkit 0.4.2
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -133,10 +133,16 @@ lane. Nothing about it is provisional: the ceiling still binds and the gate stil
 a function over it. Add a coverage lane the day a parser exists and the same scope starts
 joining coverage.
 
+`crapkit init` writes that key itself, on every scope whose languages all lack a parser,
+and leaves it off any scope a lane could still measure. So the 60-second start above runs
+unchanged on a Go, Rust or shell repo: `crapkit coverage` scores it with no lane at all,
+and that run is the baseline `worklist`, `next-item`, `ratchet seed` and `verify` read.
+
 Three readers are crapkit's own. lizard ships none for shell or PowerShell, so crapkit
 counts their functions itself. Its Rust reader scores a 7-arm `match` as ccn 2 (filed as
 lizard #494), so crapkit counts each non-wildcard arm like a C `case` and retires the
-override the day upstream fixes it.
+override the day upstream fixes it. The cognitive column charges that same block once,
+the way Sonar charges a `switch`.
 
 ## The gate
 
@@ -146,8 +152,8 @@ different powers:
 | Surface | Fires | Power |
 |---|---|---|
 | `crapkit claude-hook` | after an agent's edit lands | **advisory.** Names the breach on stderr. Blocks nothing, because PostToolUse runs after the write |
-| `crapkit rescore FILE --gate` | when you ask | **preview.** The commit gate's verdict on demand, sub-second, before you stage |
-| `crapkit hook-precommit` | `git commit` | **blocks.** Exit 6. Staged blobs only, so it costs the size of the commit and needs no coverage |
+| `crapkit rescore FILE --gate` | when you ask, after the first coverage run | **preview.** The commit gate's verdict on demand, sub-second, before you stage. With no run behind it, exit 1 and `no snapshot` |
+| `crapkit hook-precommit` | `git commit` | **blocks.** The hook exits 6; git reports 1. Staged blobs only, so it costs the size of the commit and needs no coverage |
 | `crapkit verify` | before you push, and in CI | **the verdict.** Gate, ratchet, new test failures, diff coverage, against the trusted baseline |
 
 Both hooks exempt a function the committed ratchet already carries a mark for, so touching
@@ -207,7 +213,8 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 ```yaml
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
-    rev: v0.4.0
+    # crapkit's release step rewrites this line to the tag it just cut
+    rev: v0.4.2
     hooks:
       - id: crapkit-gate
 ```
@@ -243,7 +250,9 @@ crapkit gate: 1 staged function(s) exceed the complexity ceiling of 6:
 decompose before committing (coverage cannot save a function above the target).
 ```
 
-Run directly, `crapkit hook-precommit` exits 6 on a violation and 0 otherwise.
+That commit exited **1**, not 6. Git collapses any failed hook to 1, so 6 is a code you
+only ever see by running the hook yourself: `crapkit hook-precommit` exits 6 on a
+violation and 0 otherwise. The stderr block above is the same either way.
 
 `CRAPKIT_OVERRIDE_REASON` is not a bypass. Setting it routes the commit through the full
 three-record audit: an alert line through `alert_command`, a ratchet entry staged into the
@@ -284,7 +293,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `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. |
-| `explain FILE NAME [--history] [--tests] [--json]` | A function's score across runs plus its mark. `--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. |
+| `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). |
 | `runs [list \| prune [--keep N]] [--json]` | Run history, and retention. `list` marks the run `verify` compares against today `baseline`, and prints `verdict=-` for a run that produces no verdict rather than one that failed. See [The trusted baseline](#the-trusted-baseline). `--keep` (default 5) is a floor on the newest trusted runs, not a cap: the digest pair, every passing verify baseline, every run an override names, and the newest non-hook run are kept too. `prune` VACUUMs afterwards. |
@@ -504,6 +513,11 @@ makes it step 4 of the burn-down loop. Every key is in
 
 ```
 $ crapkit doctor
+ok   config keys all recognized
+ok   scope 'calc': 1 files
+ok   every tracked source file belongs to a scope
+ok   1 lane(s) declared
+ok   lizard 1.24.0
 doctor: no problems found
 ```
 
@@ -535,11 +549,12 @@ worklist has none.
 
 ```
 $ crapkit next-item
-{"commit": "fae4db93108b4841a00959f9117430679e7250ca", "empty": false, "item": {"authors": 1, "ccn": 14, "ccn_std": 14, "cognitive": 13, "commits": 1, "cov": 0.5, "crap": 38.5, "end": 28, "est_splits": 3, "est_uncovered_paths": 7, "flag": "measured", "function": "classify( score , attempts , late , bonus )", "nesting": 8, "nloc": 22, "path": "calc/grade.py", "remedy": "decompose", "scope": "calc", "start": 7, "target": 6, "uncovered_lines": [9, 11, 15, 17, 19, 24, 25, 26, 27, 28]}, "run_id": 1, "schema": 1, "skipped_no_lane": 0}
+{"commit": "fae4db93108b4841a00959f9117430679e7250ca", "empty": false, "item": {"authors": 1, "ccn": 14, "ccn_std": 14, "cognitive": 13, "commits": 1, "cov": 0.5, "crap": 38.5, "end": 28, "est_splits": 3, "est_uncovered_paths": 7, "flag": "measured", "function": "classify( score , attempts , late , bonus )", "handle": "classify", "nesting": 8, "nloc": 22, "path": "calc/grade.py", "remedy": "decompose", "scope": "calc", "start": 7, "target": 6, "uncovered_lines": [9, 11, 15, 17, 19, 24, 25, 26, 27, 28]}, "run_id": 1, "schema": 1, "skipped_no_lane": 0, "stale": false}
 ```
 
 `remedy: "decompose"`, `est_splits: 3` (this needs roughly three pieces to fit under 6),
-and `uncovered_lines` naming the ten lines no test walks. Every field is in
+and `uncovered_lines` naming the ten lines no test walks. `handle` is the name form to
+pass back, and `stale: false` says the run still describes HEAD. Every field is in
 [docs/agent-json.md](docs/agent-json.md).
 
 ### 5. Seed the ratchet
@@ -616,17 +631,21 @@ crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/cov
 crapkit: every lane failed: ...
 ```
 
-Install the provider, pinned to your vitest major or npm refuses the peer dependency:
+That failure **writes no run**. Every lane failed, so `coverage` exits before it opens a
+store: there is no `.crapkit/crap.sqlite` yet and the run ids below still start at 1.
+
+Install the provider, and pin the major yourself. Unpinned, npm resolves the newest
+provider against your older vitest and refuses the tree:
 
 ```
-npm i -D @vitest/coverage-v8
+npm i -D "@vitest/coverage-v8@<your vitest major>"
 ```
 
 | Question | Answer |
 |---|---|
 | Which provider? | Either works. `@vitest/coverage-v8` is vitest's default and needs no config. `@vitest/coverage-istanbul` also works and needs `coverage.provider = "istanbul"` in your vitest config. |
 | Which crapkit parser? | Both feed `parser = "istanbul"`. The provider name and the parser name are unrelated: v8 output is remapped to the istanbul JSON schema before it is written. |
-| Which version? | It must match your vitest major. npm refuses the install otherwise (`peer vitest@"4.x" from @vitest/coverage-v8@4.x`). On vitest 2, `npm i -D "@vitest/coverage-v8@2"`. |
+| Which version? | The provider's major has to match vitest's. On vitest 2 that is `npm i -D "@vitest/coverage-v8@2"`, on vitest 3 `npm i -D "@vitest/coverage-v8@3"`. Drop the pin and npm answers `ERESOLVE unable to resolve dependency tree`, naming the peer it could not satisfy. |
 
 The artifact crapkit wants is `coverage-final.json`, written by vitest's `json` coverage
 reporter, which is on by default. If your vitest config sets `coverage.reporter`

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crapkit"
-version = "0.4.1"
+version = "0.4.2"
 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" }
@@ -48,7 +48,11 @@ Issues = "https://github.com/JeanFrancoisGagne/crapkit/issues"
 Source = "https://github.com/JeanFrancoisGagne/crapkit"
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "pytest-cov>=5"]
+# pytest-xdist is not a convenience: tests/fixtures/mini_repo declares a lane
+# that shells out to `pytest pylib -n 2 ...`, and pytest rejects `-n` outright
+# 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"]
 
 [project.scripts]
 crapkit = "crapkit.cli:main"

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

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

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

@@ -49,7 +49,12 @@ _POOL_THRESHOLD = 16
 # Bump whenever analysis semantics change (merge rules, extension set, record
 # extraction): the fingerprint must invalidate cached records produced by older
 # logic even when file content and tool versions are identical.
-ANALYSIS_VERSION = 6  # 6: five more C-family extension sets and .ps1/.psm1 are
+ANALYSIS_VERSION = 7  # 7: a Rust `match` is a cognitive condition (+1 and the
+#                          nesting it sits in), so every cached .rs record
+#                          carries a cognitive score measured without it. Rust
+#                          is the only language whose stored values move; ccn is
+#                          untouched in every language, Rust included.
+#                       6: five more C-family extension sets and .ps1/.psm1 are
 #                          admitted, a C++ rvalue reference is no longer a
 #                          cognitive condition, and source bytes decode utf-8
 #                          then cp1252 instead of by machine locale

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

@@ -152,6 +152,7 @@ _OWNER = {
     "_next_item_payload": "queue",
     "_next_ranked": "queue",
     "_next_reasons": "queue",
+    "_next_step": "admin",
     "_no_baseline": "verifying",
     "_no_handle_message": "queue",
     "_no_lane_debt": "queue",
@@ -210,6 +211,8 @@ _OWNER = {
     "_reconfigure_streams": "parser",
     "_records": "claude_hook",
     "_records_by_scope": "scoring",
+    "_refuse_empty_lane_run": "scoring",
+    "_refuse_lane_less_verify": "verifying",
     "_release_claims": "verifying",
     "_release_target": "queue",
     "_report": "claude_hook",

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

@@ -39,14 +39,30 @@ def _package_json(root: Path) -> str:
     return path.read_text(encoding="utf-8") if path.is_file() else ""
 
 
+def _next_step(scopes: dict, lanes: tuple) -> str:
+    """What to run next, which is not the same sentence in all three cases.
+
+    A repo whose every language is cc-only was told to declare a lane per
+    coverage command. There is no lane to declare: neither parser reads Go,
+    Rust, shell or the six others, `init` just wrote `coverage_optional` for
+    each scope, and `crapkit coverage` scores them from complexity alone.
+    """
+    from ..scaffold import cc_only_scope
+
+    if lanes:
+        return (f"detected {len(lanes)} lane(s) from this repo's own files: "
+                f"{', '.join(lane.name for lane in lanes)} — next: run `crapkit coverage`")
+    if all(cc_only_scope(languages) for languages in scopes.values()):
+        return ("no coverage parser reads this repo's languages, so every scope is "
+                "cc-only (coverage_optional = true) and needs no lane — next: run "
+                "`crapkit coverage`")
+    return ("next: declare a [[lane]] per coverage command (see the commented template), "
+            "then run `crapkit coverage`")
+
+
 def _print_init_summary(scopes: dict, lanes: tuple) -> None:
     print(f"wrote crapkit.toml with {len(scopes)} scope(s): {', '.join(scopes)}")
-    if lanes:
-        print(f"detected {len(lanes)} lane(s) from this repo's own files: "
-              f"{', '.join(lane.name for lane in lanes)} — next: run `crapkit coverage`")
-        return
-    print("next: declare a [[lane]] per coverage command (see the commented template), "
-          "then run `crapkit coverage`")
+    print(_next_step(scopes, lanes))
 
 
 def _no_scopes_reason(root: Path) -> str:
@@ -214,9 +230,13 @@ def _lane_command_problems(root: Path, lane) -> list[str]:
 
 
 def _doctor_lane_summary(cfg) -> Finding:
+    """No lanes is a gap in most repos and the finished state in a cc-only one,
+    where every scope declares coverage_optional and `coverage` runs anyway."""
     if cfg.lanes:
         return Finding("ok", f"{len(cfg.lanes)} lane(s) declared")
-    return Finding("note", "no [[lane]] declared — inventory works; coverage needs one")
+    if cfg.lane_less_scopes:
+        return Finding("note", "no [[lane]] declared — inventory works; coverage needs one")
+    return Finding("ok", "no [[lane]] declared: every scope is cc-only, so none is needed")
 
 
 def _lane_problems(root: Path, cfg) -> list[str]:

{crapkit-0.4.1 → crapkit-0.4.2}/src/crapkit/cli/queue.py

@@ -359,8 +359,13 @@ def cmd_claims(args: argparse.Namespace) -> int:
 
 
 def _name_prefix(long_name: str) -> str:
-    """The identifier a long_name opens with, before its parameter list."""
-    return long_name.split("(")[0].strip()
+    """The identifier a long_name opens with, before its parameter list.
+
+    packet.bare_name is the definition. This was a second copy of the cut, and
+    it is what kept `brief` rejecting a Rust or Go bare name after the packet
+    that published it had already been fixed.
+    """
+    return packet.bare_name(long_name)
 
 
 def _name_matches(long_name: str, name: str) -> bool:
@@ -375,7 +380,13 @@ def _name_matches(long_name: str, name: str) -> bool:
 
 
 def _matching_rows(rows: list, name: str) -> list:
-    return [r for r in rows if _name_matches(r.long_name, name)]
+    """The rows NAME resolves to, by the rule `explain` runs on the same string.
+
+    Both commands go through `packet.matching_names`, so a name that picks one
+    function in a packet cannot pick three in a trajectory.
+    """
+    wanted = set(packet.matching_names([r.long_name for r in rows], name))
+    return [r for r in rows if r.long_name in wanted]
 
 
 def _no_match_message(path: str, name: str, rows: list, candidates: list) -> str:

{crapkit-0.4.1 → crapkit-0.4.2}/src/crapkit/cli/scoring.py

@@ -194,7 +194,9 @@ def _collect_lanes(root: Path, lanes, outcomes: dict):
         stamps[lane.artifact] = outcome.stamp
         succeeded.append(lane)
     write_stamps(root, stamps)
-    if not succeeded:
+    # `lane_errors` and not `lanes`: a cc-only repo declares no lanes, so nothing
+    # succeeded and nothing failed either, and that run is still a scored run.
+    if lane_errors and not succeeded:
         raise ToolError(f"every lane failed: {'; '.join(lane_errors.values())}")
     return coverage_by_path, provenance, lane_errors, succeeded
 
@@ -254,11 +256,30 @@ def _run_kind(lanes, cfg, failures) -> str:
     return "coverage" if full else "partial"
 
 
+def _refuse_empty_lane_run(cfg, requested) -> None:
+    """Refuse a run that selected no lane, unless running with none is right.
+
+    Right for a repo whose every scope declares `coverage_optional`: nine of the
+    fourteen languages have no coverage parser at all, such a repo is scored
+    from complexity alone, and demanding a lane refused exactly the repos that
+    can never supply one. Wrong the moment one scope has neither, which is what
+    the message names — the scopes, not the empty list, because the list is a
+    symptom and the scopes are the gap.
+    """
+    if requested is not None:
+        raise ConfigError(f"no lane named {requested!r}")
+    if cfg.lane_less_scopes:
+        raise ConfigError(
+            f"no [[lane]] to run for scope(s) {', '.join(cfg.lane_less_scopes)} — declare a "
+            "[[lane]] measuring them in crapkit.toml, or set coverage_optional = true on a "
+            "scope no coverage parser can read")
+
+
 def _select_lanes(cfg, requested):
+    """The lanes this run executes; an empty list is a legitimate answer."""
     lanes = [l for l in cfg.lanes if requested is None or l.name == requested]
     if not lanes:
-        raise ConfigError("no [[lane]] to run — declare lanes in crapkit.toml" if not cfg.lanes
-                          else f"no lane named {requested!r}")
+        _refuse_empty_lane_run(cfg, requested)
     return lanes
 
 

{crapkit-0.4.1 → crapkit-0.4.2}/src/crapkit/cli/verifying.py

@@ -320,6 +320,23 @@ def _report_verify(as_json: bool, out: dict, verdict, overridden) -> None:
     _print_finding_split(verdict)
 
 
+def _refuse_lane_less_verify(cfg) -> None:
+    """Refuse a verdict on a scope nothing measures and no key excuses.
+
+    Stricter than `coverage`, on purpose. `coverage` scores such a scope and
+    flags every row `no-lane`, because scoring is its whole job; `verify` calls
+    coverage half the verdict, so an unmeasured scope leaves it with half an
+    answer and it says so instead. The test that a cc-only repo passes is that
+    `lane_less_scopes` is empty, not that lanes exist: such a repo has none and
+    never will, and its verdict is the gate and the ratchet, neither of which
+    needs a coverage number.
+    """
+    if cfg.lane_less_scopes:
+        raise ConfigError(f"verify needs a [[lane]] for scope(s) {', '.join(cfg.lane_less_scopes)}"
+                          " — coverage is half the verdict; a scope no coverage parser can read "
+                          "declares coverage_optional = true instead")
+
+
 def cmd_verify(args: argparse.Namespace) -> int:
     from ..diffparse import changed_ranges
     from ..gitio import GitFacts, diff_since
@@ -328,8 +345,7 @@ def cmd_verify(args: argparse.Namespace) -> int:
 
     root = Path(args.repo).resolve()
     cfg = _load_repo_config(root)
-    if not cfg.lanes:
-        raise ConfigError("verify needs [[lane]] declarations — coverage is half the verdict")
+    _refuse_lane_less_verify(cfg)
     store = _verify_store(root, args.baseline_tsv)
     _guard_ratchet_stamp(root / cfg.ratchet_file, cfg.ratchet_file)
     # One context for the whole command: the ancestry checks, the lane runner and

{crapkit-0.4.1 → crapkit-0.4.2}/src/crapkit/config.py

@@ -110,6 +110,23 @@ class Config(NamedTuple):
         """The scopes scored cc-only: no coverage join, and no lane required."""
         return frozenset(s.name for s in self.scopes if s.coverage_optional)
 
+    @property
+    def lane_less_scopes(self) -> tuple[str, ...]:
+        """Scopes no lane measures and no `coverage_optional` excuses.
+
+        Empty is the licence to run with no lanes at all: every scope is either
+        measured by one or scored cc-only, so there is nothing left for a lane
+        to say.
+
+        The two readers weigh a non-empty answer differently, and the difference
+        is deliberate. `verify` refuses outright and names the list. `coverage`
+        refuses only when it also selected no lane, and otherwise scores the
+        scope and flags every row `no-lane` — a flag it could not print at all
+        if owing a lane refused the run. `doctor` is what says so out of band.
+        """
+        covered = {s for lane in self.lanes for s in lane.scopes} | self.coverage_optional_scopes
+        return tuple(s.name for s in self.scopes if s.name not in covered)
+
     @property
     def scope_paths(self) -> dict[str, tuple[str, ...]]:
         """Every scope's declared paths, by name — what a lane's scopes resolve to."""

{crapkit-0.4.1 → crapkit-0.4.2}/src/crapkit/lizardcognitive.py

@@ -10,9 +10,14 @@ same rules with no second parse and no new dependency:
   try / finally / case labels / with are free; nesting rises inside the
   block structures listed above.
 
-One language-specific rule: in C/C++ and Objective-C/C++ a `&&` before the
-function's opening brace declares an rvalue reference rather than deciding
-anything, and costs nothing. See `_declarator_and`.
+Two language-specific rules:
+  * in C/C++ and Objective-C/C++ a `&&` before the function's opening brace
+    declares an rvalue reference rather than deciding anything, and costs
+    nothing. See `_declarator_and`.
+  * in Rust a `match` is a switch and is charged as one, +1 and +nesting with
+    the arms free. It is read only for the Rust readers because `match` is a
+    soft keyword in Python, where the same spelling is an ordinary identifier.
+    See `_counting_match`.
 
 Attribution follows lizard's function splitting (a nested arrow's tokens are
 the arrow's), exactly as ccn is attributed today. Ternary branches do not
@@ -53,14 +58,22 @@ _RUN_RESETS = frozenset({";", ",", "{", "}"})
 # lose a real one.
 _DECLARATOR_READERS = frozenset({"CLikeReader", "ObjCReader"})
 
+# The readers whose `match` is Rust's switch: lizard's own, and crapkit's
+# subclass of it. Exact names for the same reason `_DECLARATOR_READERS` uses
+# them — the discriminator is the language, and an issubclass test would also
+# catch anything a later lizard derives from RustReader for another one.
+_MATCH_READERS = frozenset({"RustReader", "CorrectedRustReader"})
+
 
 class _FnState:
     __slots__ = ("total", "stack", "brace_depth", "line_indent", "at_line_start",
                  "pending", "else_pending", "question_pending", "bool_op", "name",
-                 "recursed", "body_started", "prev", "label_check", "c_family")
+                 "recursed", "body_started", "prev", "label_check", "c_family",
+                 "match_kw")
 
-    def __init__(self, name: str, c_family: bool = False):
+    def __init__(self, name: str, c_family: bool = False, match_kw: bool = False):
         self.c_family = c_family
+        self.match_kw = match_kw
         self.total = 0
         self.stack = []          # (entry_brace_depth) or python header indents
         self.brace_depth = 0
@@ -91,11 +104,13 @@ class LizardExtension:
         reader_name = type(reader).__name__
         is_python = reader_name.lower().startswith("python")
         c_family = reader_name in _DECLARATOR_READERS
+        match_kw = reader_name in _MATCH_READERS
         for token in tokens:
             fn = reader.context.current_function
             state = states.get(fn)
             if state is None:
-                state = states[fn] = _FnState(getattr(fn, "name", ""), c_family)
+                state = states[fn] = _FnState(getattr(fn, "name", ""), c_family,
+                                              match_kw)
             _step(state, token, is_python)
             fn.cognitive_complexity = state.total
             yield token
@@ -235,12 +250,27 @@ def _keywords(state: _FnState, token: str, is_python: bool) -> None:
         _if_token(state, is_python)
     elif token in _ELSE_KEYWORDS:
         _else_token(state, token, is_python)
-    elif token in _COUNTING:
+    elif token in _COUNTING or _counting_match(state, token):
         _structure_token(state, token, is_python)
     else:
         _jumps_and_recursion(state, token, is_python)
 
 
+def _counting_match(state: _FnState, token: str) -> bool:
+    """True for a Rust `match`, which is a switch and is charged as one.
+
+    Not in `_COUNTING`, because that set is read by every language and `match`
+    is a soft keyword in Python: `match = re.match(...)` would cost a point and
+    open a block that never closes. The reader decides, the way it decides
+    whether a `&&` is a declarator.
+
+    The block itself pays +1 and the nesting it sits in; the arms pay nothing,
+    exactly as a C `case` pays nothing. Rust's cyclomatic column counts the arms
+    instead, so the two columns say different things about one block on purpose.
+    """
+    return token == "match" and state.match_kw
+
+
 def _structure_token(state: _FnState, token: str, is_python: bool) -> None:
     if token == "while" and state.prev == "}":
         return  # the closing half of do-while; the do already paid

{crapkit-0.4.1 → crapkit-0.4.2}/src/crapkit/mcp_server.py

@@ -15,6 +15,14 @@ PROTOCOL_VERSION = "2024-11-05"
 
 _REPO = {"repo": {"type": "string", "description": "repo root (default: the server's)"}}
 
+# brief and explain resolve NAME by one rule, so they describe it with one
+# string. The bare identifier is the long name's leading token, which is all
+# there is before the parameters in Rust and Go.
+_NAME_DESCRIPTION = ("the bare identifier (classify, or route for a Rust "
+                     "`route cmd : & Cmd`) or the whole long_name next_item "
+                     "printed (classify( score , late )); both resolve, exact "
+                     "match first")
+
 TOOLS: tuple[dict, ...] = (
     {"name": "next_item", "argv": ["next-item"], "json_flag": False, "positional": (),
      "flags": {"top": "--top", "exclude": "--exclude"},
@@ -31,14 +39,12 @@ TOOLS: tuple[dict, ...] = (
      "description": "One function's whole context: scored row, ratchet mark, uncovered lines, "
                     "duplication twins, churn and change-coupling partners",
      "properties": {"path": {"type": "string", "description": "repo-relative source file"},
-                    "name": {"type": "string",
-                             "description": "the bare identifier (classify) or the whole "
-                                            "long_name next_item printed "
-                                            "(classify( score , late )); both resolve"}}},
+                    "name": {"type": "string", "description": _NAME_DESCRIPTION}}},
     {"name": "explain", "argv": ["explain"], "json_flag": False, "positional": ("path", "name"),
      "flags": {},
      "description": "One function's score trajectory across runs plus its ratchet mark",
-     "properties": {"path": {"type": "string"}, "name": {"type": "string"}}},
+     "properties": {"path": {"type": "string"},
+                    "name": {"type": "string", "description": _NAME_DESCRIPTION}}},
     {"name": "doctor", "argv": ["doctor"], "json_flag": False, "positional": (), "flags": {},
      "description": "Config/repo agreement check: typo keys, empty scopes, missing lane cwds",
      "properties": {}},

{crapkit-0.4.1 → crapkit-0.4.2}/src/crapkit/packet.py

@@ -132,11 +132,46 @@ def commands(path: str, scoped: str | None, note: str = "") -> dict:
 def bare_name(long_name: str) -> str:
     """The identifier a long_name opens with, before its parameter list.
 
+    Two cuts, because lizard's readers spell a parameter list two ways. Python
+    and shell close the name with `(` — `classify( score , limit = 1 )`,
+    `classify()` — and Rust and Go print the parameters after a space with no
+    parenthesis at all: `route cmd : & Cmd`, `Classify n int`. Cutting only at
+    the `(` handed those back whole, so the handle a packet published was a
+    signature no command would accept back.
+
+    The leading token settles both. It moves no parenthesised language, because
+    none of those puts a space before the `(`: `n::K::m( int a)` keeps its
+    namespace and an Objective-C `doThing:( int )` keeps its selector colon.
+
     Empty for a function lizard could not name: both `(anonymous)` and
     `(anonymous) ( z )` open with the parenthesis, so an empty prefix IS the
     test for anonymity, with no second string to keep in step.
     """
-    return long_name.split("(")[0].strip()
+    head = long_name.split("(")[0].strip()
+    return head.split()[0] if head else ""
+
+
+def exact_names(names, name: str) -> list[str]:
+    """The long names `name` names outright: the whole string, or the bare one."""
+    return [n for n in names if name in (n, bare_name(n))]
+
+
+def matching_names(names, name: str) -> list[str]:
+    """The long names one NAME resolves to, in the order `names` arrived.
+
+    Exact first, the fragment second. `brief` matched only exactly and `explain`
+    only loosely, so `route` picked one function in one command and three —
+    `route`, `route_chain`, `route_num` — in the other, off the same string in
+    the same payload. Nesting names is the ordinary case, so the loose command
+    was wrong far more often than the strict one was unhelpful.
+
+    The fragment survives as the fallback because a name nobody owns is usually
+    a typo, and listing everything holding it is what tells a session which name
+    it meant. An empty NAME resolves to nothing rather than to everything.
+    """
+    if not name:
+        return []
+    return exact_names(names, name) or [n for n in names if name in n]
 
 
 def anonymous_starts(rows) -> list[int]:

{crapkit-0.4.1 → crapkit-0.4.2}/src/crapkit/scaffold.py

@@ -8,6 +8,23 @@ from .universe import LANGUAGE_EXTENSIONS, exclude_matcher, excluded
 
 _EXT_LANGUAGE = {ext: lang for lang, exts in LANGUAGE_EXTENSIONS.items() for ext in exts}
 
+# The languages a coverage parser can read: coverage.py reads python, istanbul
+# reads the JavaScript family and the .vue files a vitest run reports on. Every
+# other supported language scores on complexity alone, which is what
+# `coverage_optional = true` declares — so init writes the key for a scope built
+# entirely from the rest, rather than leaving it to score `no-lane` forever
+# against a lane nobody can write.
+COVERABLE_LANGUAGES = frozenset({"python", "javascript", "typescript", "tsx", "vue"})
+
+
+def cc_only_scope(languages: tuple[str, ...]) -> bool:
+    """True when no coverage parser reads any of this scope's languages.
+
+    One coverable language is enough to keep the key off: a lane can still
+    measure that part, and `coverage_optional` would forgive the whole scope.
+    """
+    return not any(lang in COVERABLE_LANGUAGES for lang in languages)
+
 DEFAULT_EXCLUDES = (
     "**/node_modules/**", "**/dist/**", "**/build/**", "**/vendor/**",
     "**/*.test.*", "**/*.spec.*", "**/test_*.py", "**/*_test.py", "**/conftest.py",
@@ -174,8 +191,9 @@ def _quoted(names) -> str:
 
 
 def _scope_stanza(name: str, languages: tuple[str, ...]) -> list[str]:
+    optional = ["coverage_optional = true"] if cc_only_scope(languages) else []
     return ["[[scope]]", f'name = "{name}"', f'paths = ["{name}"]',
-            f"languages = [{_quoted(languages)}]", ""]
+            f"languages = [{_quoted(languages)}]", *optional, ""]
 
 
 def _exclude_stanza() -> list[str]:
@@ -297,10 +315,17 @@ def _commented_block(rest: dict[str, tuple[str, ...]], has_live: bool) -> list[s
     return header + _scoped_entry_lines(rest, False)
 
 
-def _template_lines(covered: set[str], scope_list: str) -> list[str]:
+def _template_lines(covered: set[str], scopes: dict[str, tuple[str, ...]]) -> list[str]:
+    """Commented lane templates for the parsers no live lane covers.
+
+    None at all when every scope is cc-only. Neither parser reads any language
+    in the repo, so both templates would be a step the reader cannot take, under
+    a heading telling them to take it before running `crapkit coverage`.
+    """
+    if all(cc_only_scope(languages) for languages in scopes.values()):
+        return []
     # the template's scope is a placeholder on purpose: writing a real scope
     # name pointed a TS lane template at a python project's sources
-    del scope_list
     lines: list[str] = []
     for parser in sorted(_TEMPLATES):
         if parser not in covered:
@@ -316,7 +341,7 @@ def starter_toml(scopes: dict[str, tuple[str, ...]], lanes: tuple[LaneSpec, ...]
         lines += _scope_stanza(name, languages)
     lines += _exclude_stanza()
     live, covered = _live_lanes(lanes, scopes)
-    return "\n".join(lines + live + _template_lines(covered, _quoted(scopes))
+    return "\n".join(lines + live + _template_lines(covered, scopes)
                      + _scoped_tests_stub(scopes, _confirmed_languages(lanes)))
 
 

{crapkit-0.4.1 → crapkit-0.4.2}/src/crapkit/store.py

@@ -25,7 +25,7 @@ from itertools import takewhile
 from pathlib import Path
 from typing import NamedTuple
 
-from .packet import bare_name, handle_ordinal
+from .packet import bare_name, handle_ordinal, matching_names
 from .snapshot import InventoryRow
 
 # {table} so the migration can build the same shape under a temp name and swap
@@ -850,23 +850,34 @@ class SnapshotStore:
         return list(cur.fetchall())
 
     def find_functions(self, path: str, name_fragment: str) -> list[str]:
-        """Distinct long_names in a path containing the fragment, across all runs.
+        """The long_names in a path that one NAME resolves to, across all runs.
 
-        Joined to functions rather than read off identities alone: a prune drops
-        the rows of a run and leaves its identities behind, and a name no
-        surviving run scored is a name `brief` cannot resolve.
+        `packet.matching_names` is the rule, shared with `brief`: exact first,
+        the fragment only when nothing matches exactly. This used to be a SQL
+        `LIKE '%name%'` and nothing else, so `explain src/lib.rs route` printed
+        the trajectories of `route`, `route_chain` and `route_num` for a
+        question about one function. Matching in Python also makes `_` and `%`
+        the characters they are rather than LIKE's wildcards.
 
         `(anonymous)#N` is resolved by position instead: an anonymous function
-        carries no text for a LIKE to match, and the fragment would otherwise
-        hunt for a `#` no long_name has.
+        carries no text to match, and the fragment would otherwise hunt for a
+        `#` no long_name has.
         """
         ordinal = handle_ordinal(name_fragment)
         if ordinal is not None:
             return self._nth_anonymous(path, ordinal)
+        return matching_names(self._long_names(path), name_fragment)
+
+    def _long_names(self, path: str) -> list[str]:
+        """Every distinct long_name a surviving run scored in this path.
+
+        Joined to functions rather than read off identities alone: a prune drops
+        the rows of a run and leaves its identities behind, and a name no
+        surviving run scored is a name `brief` cannot resolve.
+        """
         cur = self._conn.execute(
-            f"SELECT DISTINCT i.long_name {_BY_PATH} "
-            "WHERE i.path = ? AND i.long_name LIKE ? ORDER BY i.long_name",
-            (path, f"%{name_fragment}%"))
+            f"SELECT DISTINCT i.long_name {_BY_PATH} WHERE i.path = ? "
+            "ORDER BY i.long_name", (path,))
         return [n for (n,) in cur]
 
     def _nth_anonymous(self, path: str, ordinal: int) -> list[str]:
@@ -1014,11 +1025,24 @@ def pick_baseline(runs: list[dict]) -> BaselinePick:
 
 
 def is_trusted(r: dict) -> bool:
-    """Trusted = a coverage run, or a verify run whose verdict passed."""
-    if not r["lanes"] or r["kind"] == "hook":
+    """Trusted = a full coverage run, or a verify run whose verdict passed.
+
+    `kind` decides it, not lane provenance. A repo whose every scope declares
+    `coverage_optional` scores with no lanes at all, and reading the empty
+    provenance as "nothing was measured" left it with a coverage run no
+    baseline reader would accept — worklist, next-item, rescore, ratchet seed
+    and verify all reported there was no scored run right after one.
+
+    `legacy` is the exception that keeps the old test: those rows were migrated
+    from before the column existed, so one label covers their inventory runs and
+    their coverage runs alike and only provenance tells the two apart.
+    """
+    if r["kind"] == "hook":
         return False
-    if r["kind"] in ("coverage", "legacy", None):
+    if r["kind"] == "coverage":
         return True
+    if r["kind"] in ("legacy", None):
+        return bool(r["lanes"])
     return r["kind"] == "verify" and r["verdict_ok"] is True
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.1
+Version: 0.4.2
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -28,6 +28,7 @@ Requires-Dist: lizard>=1.24.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: pytest-xdist>=3; extra == "dev"
 Dynamic: license-file
 
 # crapkit
@@ -115,7 +116,7 @@ changing crapkit.
 
 ```
 $ crapkit --version
-crapkit 0.4.1
+crapkit 0.4.2
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -165,10 +166,16 @@ lane. Nothing about it is provisional: the ceiling still binds and the gate stil
 a function over it. Add a coverage lane the day a parser exists and the same scope starts
 joining coverage.
 
+`crapkit init` writes that key itself, on every scope whose languages all lack a parser,
+and leaves it off any scope a lane could still measure. So the 60-second start above runs
+unchanged on a Go, Rust or shell repo: `crapkit coverage` scores it with no lane at all,
+and that run is the baseline `worklist`, `next-item`, `ratchet seed` and `verify` read.
+
 Three readers are crapkit's own. lizard ships none for shell or PowerShell, so crapkit
 counts their functions itself. Its Rust reader scores a 7-arm `match` as ccn 2 (filed as
 lizard #494), so crapkit counts each non-wildcard arm like a C `case` and retires the
-override the day upstream fixes it.
+override the day upstream fixes it. The cognitive column charges that same block once,
+the way Sonar charges a `switch`.
 
 ## The gate
 
@@ -178,8 +185,8 @@ different powers:
 | Surface | Fires | Power |
 |---|---|---|
 | `crapkit claude-hook` | after an agent's edit lands | **advisory.** Names the breach on stderr. Blocks nothing, because PostToolUse runs after the write |
-| `crapkit rescore FILE --gate` | when you ask | **preview.** The commit gate's verdict on demand, sub-second, before you stage |
-| `crapkit hook-precommit` | `git commit` | **blocks.** Exit 6. Staged blobs only, so it costs the size of the commit and needs no coverage |
+| `crapkit rescore FILE --gate` | when you ask, after the first coverage run | **preview.** The commit gate's verdict on demand, sub-second, before you stage. With no run behind it, exit 1 and `no snapshot` |
+| `crapkit hook-precommit` | `git commit` | **blocks.** The hook exits 6; git reports 1. Staged blobs only, so it costs the size of the commit and needs no coverage |
 | `crapkit verify` | before you push, and in CI | **the verdict.** Gate, ratchet, new test failures, diff coverage, against the trusted baseline |
 
 Both hooks exempt a function the committed ratchet already carries a mark for, so touching
@@ -239,7 +246,8 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 ```yaml
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
-    rev: v0.4.0
+    # crapkit's release step rewrites this line to the tag it just cut
+    rev: v0.4.2
     hooks:
       - id: crapkit-gate
 ```
@@ -275,7 +283,9 @@ crapkit gate: 1 staged function(s) exceed the complexity ceiling of 6:
 decompose before committing (coverage cannot save a function above the target).
 ```
 
-Run directly, `crapkit hook-precommit` exits 6 on a violation and 0 otherwise.
+That commit exited **1**, not 6. Git collapses any failed hook to 1, so 6 is a code you
+only ever see by running the hook yourself: `crapkit hook-precommit` exits 6 on a
+violation and 0 otherwise. The stderr block above is the same either way.
 
 `CRAPKIT_OVERRIDE_REASON` is not a bypass. Setting it routes the commit through the full
 three-record audit: an alert line through `alert_command`, a ratchet entry staged into the
@@ -316,7 +326,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `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. |
-| `explain FILE NAME [--history] [--tests] [--json]` | A function's score across runs plus its mark. `--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. |
+| `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). |
 | `runs [list \| prune [--keep N]] [--json]` | Run history, and retention. `list` marks the run `verify` compares against today `baseline`, and prints `verdict=-` for a run that produces no verdict rather than one that failed. See [The trusted baseline](#the-trusted-baseline). `--keep` (default 5) is a floor on the newest trusted runs, not a cap: the digest pair, every passing verify baseline, every run an override names, and the newest non-hook run are kept too. `prune` VACUUMs afterwards. |
@@ -536,6 +546,11 @@ makes it step 4 of the burn-down loop. Every key is in
 
 ```
 $ crapkit doctor
+ok   config keys all recognized
+ok   scope 'calc': 1 files
+ok   every tracked source file belongs to a scope
+ok   1 lane(s) declared
+ok   lizard 1.24.0
 doctor: no problems found
 ```
 
@@ -567,11 +582,12 @@ worklist has none.
 
 ```
 $ crapkit next-item
-{"commit": "fae4db93108b4841a00959f9117430679e7250ca", "empty": false, "item": {"authors": 1, "ccn": 14, "ccn_std": 14, "cognitive": 13, "commits": 1, "cov": 0.5, "crap": 38.5, "end": 28, "est_splits": 3, "est_uncovered_paths": 7, "flag": "measured", "function": "classify( score , attempts , late , bonus )", "nesting": 8, "nloc": 22, "path": "calc/grade.py", "remedy": "decompose", "scope": "calc", "start": 7, "target": 6, "uncovered_lines": [9, 11, 15, 17, 19, 24, 25, 26, 27, 28]}, "run_id": 1, "schema": 1, "skipped_no_lane": 0}
+{"commit": "fae4db93108b4841a00959f9117430679e7250ca", "empty": false, "item": {"authors": 1, "ccn": 14, "ccn_std": 14, "cognitive": 13, "commits": 1, "cov": 0.5, "crap": 38.5, "end": 28, "est_splits": 3, "est_uncovered_paths": 7, "flag": "measured", "function": "classify( score , attempts , late , bonus )", "handle": "classify", "nesting": 8, "nloc": 22, "path": "calc/grade.py", "remedy": "decompose", "scope": "calc", "start": 7, "target": 6, "uncovered_lines": [9, 11, 15, 17, 19, 24, 25, 26, 27, 28]}, "run_id": 1, "schema": 1, "skipped_no_lane": 0, "stale": false}
 ```
 
 `remedy: "decompose"`, `est_splits: 3` (this needs roughly three pieces to fit under 6),
-and `uncovered_lines` naming the ten lines no test walks. Every field is in
+and `uncovered_lines` naming the ten lines no test walks. `handle` is the name form to
+pass back, and `stale: false` says the run still describes HEAD. Every field is in
 [docs/agent-json.md](docs/agent-json.md).
 
 ### 5. Seed the ratchet
@@ -648,17 +664,21 @@ crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/cov
 crapkit: every lane failed: ...
 ```
 
-Install the provider, pinned to your vitest major or npm refuses the peer dependency:
+That failure **writes no run**. Every lane failed, so `coverage` exits before it opens a
+store: there is no `.crapkit/crap.sqlite` yet and the run ids below still start at 1.
+
+Install the provider, and pin the major yourself. Unpinned, npm resolves the newest
+provider against your older vitest and refuses the tree:
 
 ```
-npm i -D @vitest/coverage-v8
+npm i -D "@vitest/coverage-v8@<your vitest major>"
 ```
 
 | Question | Answer |
 |---|---|
 | Which provider? | Either works. `@vitest/coverage-v8` is vitest's default and needs no config. `@vitest/coverage-istanbul` also works and needs `coverage.provider = "istanbul"` in your vitest config. |
 | Which crapkit parser? | Both feed `parser = "istanbul"`. The provider name and the parser name are unrelated: v8 output is remapped to the istanbul JSON schema before it is written. |
-| Which version? | It must match your vitest major. npm refuses the install otherwise (`peer vitest@"4.x" from @vitest/coverage-v8@4.x`). On vitest 2, `npm i -D "@vitest/coverage-v8@2"`. |
+| Which version? | The provider's major has to match vitest's. On vitest 2 that is `npm i -D "@vitest/coverage-v8@2"`, on vitest 3 `npm i -D "@vitest/coverage-v8@3"`. Drop the pin and npm answers `ERESOLVE unable to resolve dependency tree`, naming the peer it could not satisfy. |
 
 The artifact crapkit wants is `coverage-final.json`, written by vitest's `json` coverage
 reporter, which is on by default. If your vitest config sets `coverage.reporter`

{crapkit-0.4.1 → crapkit-0.4.2}/src/crapkit.egg-info/requires.txt

@@ -3,3 +3,4 @@ lizard>=1.24.0
 [dev]
 pytest>=8
 pytest-cov>=5
+pytest-xdist>=3