crapkit 0.2.0__tar.gz → 0.4.0__tar.gz

{crapkit-0.2.0/src/crapkit.egg-info → crapkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.2.0
+Version: 0.4.0
 Summary: Deterministic CRAP-score framework: per-function complexity x coverage risk, worklists, ratchets, refactor verification
 Author: Jean-Francois Gagne
 License: MIT
@@ -28,10 +28,14 @@ Dynamic: license-file
 
 crapkit scores every function in your repo on complexity times uncovered risk, ranks the
 worst ones by how often the file changes, and blocks commits that add more. It reads
-TypeScript, TSX, JavaScript and Python through [lizard](https://github.com/terryyin/lizard),
+TypeScript, TSX, JavaScript, Python, Swift, Go, Rust, shell, PowerShell, C and C++,
+Objective-C, Vue, Java and Zig through [lizard](https://github.com/terryyin/lizard),
 and joins per-function branch coverage from istanbul or coverage.py artifacts your own test
-command already produces. Every read-side command speaks JSON with a pinned schema, because
-half the callers are coding agents.
+command already produces. Those two parsers are the whole list, so Swift, Go, Rust, shell,
+PowerShell, C and C++, Objective-C, Java and Zig have no coverage to join: declare those
+scopes `coverage_optional` and they score on complexity alone. Vue joins istanbul coverage
+when your own vitest run reports on `.vue` files. Every read-side command speaks JSON with a
+pinned schema, because half the callers are coding agents.
 
 ```
 CRAP = ccn^2 * (1 - cov)^3 + ccn
@@ -76,7 +80,7 @@ Check the install:
 
 ```
 $ crapkit --version
-crapkit 0.2.0
+crapkit 0.4.0
 ```
 
 `python -m crapkit` works identically to the `crapkit` console script, and is what to use
@@ -130,7 +134,7 @@ paths = ["calc"]
 languages = ["python"]
 
 [exclude]
-globs = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/vendor/**", "**/*.test.*", "**/*.spec.*", "**/test_*.py", "**/*_test.py", "**/conftest.py", "*.config.ts", "*.config.js", "*.config.mts", "**/*.config.ts", "**/*.config.js", "**/*.config.mts"]
+globs = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/vendor/**", "**/*.test.*", "**/*.spec.*", "**/test_*.py", "**/*_test.py", "**/conftest.py", "**/*_test.go", "*.config.ts", "*.config.js", "*.config.mts", "**/*.config.ts", "**/*.config.js", "**/*.config.mts"]
 
 [[lane]]
 name = "py"
@@ -472,11 +476,15 @@ without touching the repo-wide cache, and refuses the commit when a staged funct
 its scope ceiling. It needs no coverage data and no snapshot, so it costs the size of the
 commit, not the size of the repo.
 
-Two limits to know. The gate judges files a `[[scope]]` claims; a staged source file no
+Three limits to know. The gate judges files a `[[scope]]` claims; a staged source file no
 scope claims is not gated, and the hook says so on stderr (`N staged file(s) belong to no
 scope and were not gated`) so the hole is visible the moment a new top-level directory
-appears. And git runs hooks outside your shell's activated venv: bare `python` must resolve
-to an interpreter that has crapkit installed, or use the absolute form
+appears. A function the committed ratchet already carries a mark for is not gated either,
+so touching signed debt does not refuse the commit; the hook reports the count on stderr
+(`N staged function(s) carry a ratchet mark and were not gated`) and `crapkit verify` is
+what fails a mark that rose. And git runs hooks outside your shell's activated venv: bare
+`python` must resolve to an interpreter that has crapkit installed, or use the absolute
+form
 (`exec /path/to/venv/Scripts/python -m crapkit hook-precommit`).
 
 ### Route 1: `.git/hooks/pre-commit` (local, not committed)
@@ -725,7 +733,8 @@ advances the baseline nor tightens the ratchet, exit 9 included.
 ## Subcommands
 
 Every subcommand takes `--repo PATH` (default `.`), and the flag goes **after** the
-subcommand:
+subcommand. `claude-hook` is the one exception: it has no `--repo`, because it takes its
+root from the file named in the hook payload it reads.
 
 ```
 $ crapkit worklist --repo /path/to/repo --scope util --top 1
@@ -746,7 +755,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | Command | What it does |
 |---|---|
 | `init` | Sniffs tracked source into per-directory scopes, writes a self-validated starter `crapkit.toml` whose lanes report into `.crapkit/cov/`, and appends `.crapkit/` plus each runner's own droppings to `.gitignore`. Writes a live `[[lane]]` when it can detect the test runner, otherwise a commented template. Refuses to clobber an existing config. |
-| `doctor [--show-files] [--json] [--tune]` | 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, lanes writing their artifacts at the repo root instead of under `.crapkit/` (WARN), committed hooks under `core.hooksPath` that are not executable in the index (WARN), directories whose functions are all `untested` while their tests exist (WARN), and scopes a lane measures with no `[crapkit.scoped_tests]` template behind them (WARN), which is the loop's step 4 with nothing to run. `--tune` prints suggested parallelism knobs and writes nothing. See [docs/agent-json.md](docs/agent-json.md#doctor---json). |
+| `doctor [--show-files] [--json] [--tune] [--plugin-root PATH]` | Checks the config still describes the repo: unknown keys (with the accepted spellings), zero-file scopes, tracked source no scope claims, scopes no lane covers, lane cwds and commands that no longer resolve, lizard importable, oversized files, lanes writing their artifacts at the repo root instead of under `.crapkit/` (WARN), committed hooks under `core.hooksPath` that are not executable in the index (WARN), directories whose functions are all `untested` while their tests exist (WARN), and scopes a lane measures with no `[crapkit.scoped_tests]` template behind them (WARN), 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, comparing `.claude-plugin/plugin.json`'s version against the running crapkit and every `--protocol` in `hooks/hooks.json` against the protocol `claude-hook` answers, 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]` | Two lizard passes 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. |
@@ -761,11 +770,13 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `overrides [--json]` | The override audit trail: who granted what, when, and why. |
 | `trend [--json]` | Totals per trusted run: functions, over-target count, CRAP load, average, per-scope rollup. |
 | `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, opens no network connection, and carries no per-function CRAP or coverage, because no repo-wide payload has 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. |
 | `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. |
+| `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. |
 | `hook-precommit` | The cc-only gate on staged blobs. No coverage, no snapshot, no repo-wide cache. Exit 6 on a violation. |
+| `claude-hook [--protocol N]` | Reads one Claude Code PostToolUse payload from stdin and judges the file it edited: ccn against the scope ceiling, on functions the edit changed, minus functions a ratchet mark already covers. Advisory only: the edit has landed and nothing is blocked, and `hook-precommit` stays the enforcement point. Exit 2 with three lines on stderr is the only thing it ever says. No `crapkit.toml` above the edited file, an unscoped file, mid-rebase or mid-merge, a `--protocol` other than 1, source that parses to no functions, or any internal failure: exit 0, silence, empty stderr. Takes no `--repo` — the root is the first `crapkit.toml` above the edited file and the upward walk stops at a `.git` entry, so a worktree never borrows its parent's config. It opens no snapshot, writes nothing, and leaves stdout empty. |
 | `watch [--interval SECONDS] [--cycles N]` | Rescores tracked files as they change (mtime polling, default 2s, subprocess-isolated so a half-saved syntax error never kills the watcher). `--cycles N` polls exactly N times and exits 0; without it the loop runs until ctrl-c. |
 | `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing nine read-only tools. See [docs/agent-json.md](docs/agent-json.md#mcp-server). |
 
@@ -779,7 +790,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | [docs/ratchet.md](docs/ratchet.md) | Seeding, pruning, the git merge driver, metric stamps, debt policy, overrides. |
 | [docs/agent-json.md](docs/agent-json.md) | The machine surface: `schema`, every payload field, real captured examples. |
 | [docs/adoption.md](docs/adoption.md) | The judgment layer over the quickstarts: scope granularity, exclude vs lane, scoped_tests wiring, the first-verify taint hazard. |
-| [skills/](skills/) | Agent skills shipped with the repo (`crapkit`, `crapkit-recover`, `crapkit-onboard`) — install by copying to your agent runtime's skills directory. |
+| [plugin/](plugin/) | The Claude Code plugin: three skills (`crapkit`, `crapkit-recover`, `crapkit-onboard`), the read-side MCP server, and the advisory PostToolUse hook. Install with `claude plugin marketplace add JeanFrancoisGagne/crapkit` then `claude plugin install crapkit@crapkit`; other runtimes copy `plugin/skills/*` into their skills directory. |
 
 [crapkit.schema.json](crapkit.schema.json) is the authority on the config file shape.
 

{crapkit-0.2.0 → crapkit-0.4.0}/README.md

@@ -2,10 +2,14 @@
 
 crapkit scores every function in your repo on complexity times uncovered risk, ranks the
 worst ones by how often the file changes, and blocks commits that add more. It reads
-TypeScript, TSX, JavaScript and Python through [lizard](https://github.com/terryyin/lizard),
+TypeScript, TSX, JavaScript, Python, Swift, Go, Rust, shell, PowerShell, C and C++,
+Objective-C, Vue, Java and Zig through [lizard](https://github.com/terryyin/lizard),
 and joins per-function branch coverage from istanbul or coverage.py artifacts your own test
-command already produces. Every read-side command speaks JSON with a pinned schema, because
-half the callers are coding agents.
+command already produces. Those two parsers are the whole list, so Swift, Go, Rust, shell,
+PowerShell, C and C++, Objective-C, Java and Zig have no coverage to join: declare those
+scopes `coverage_optional` and they score on complexity alone. Vue joins istanbul coverage
+when your own vitest run reports on `.vue` files. Every read-side command speaks JSON with a
+pinned schema, because half the callers are coding agents.
 
 ```
 CRAP = ccn^2 * (1 - cov)^3 + ccn
@@ -50,7 +54,7 @@ Check the install:
 
 ```
 $ crapkit --version
-crapkit 0.2.0
+crapkit 0.4.0
 ```
 
 `python -m crapkit` works identically to the `crapkit` console script, and is what to use
@@ -104,7 +108,7 @@ paths = ["calc"]
 languages = ["python"]
 
 [exclude]
-globs = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/vendor/**", "**/*.test.*", "**/*.spec.*", "**/test_*.py", "**/*_test.py", "**/conftest.py", "*.config.ts", "*.config.js", "*.config.mts", "**/*.config.ts", "**/*.config.js", "**/*.config.mts"]
+globs = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/vendor/**", "**/*.test.*", "**/*.spec.*", "**/test_*.py", "**/*_test.py", "**/conftest.py", "**/*_test.go", "*.config.ts", "*.config.js", "*.config.mts", "**/*.config.ts", "**/*.config.js", "**/*.config.mts"]
 
 [[lane]]
 name = "py"
@@ -446,11 +450,15 @@ without touching the repo-wide cache, and refuses the commit when a staged funct
 its scope ceiling. It needs no coverage data and no snapshot, so it costs the size of the
 commit, not the size of the repo.
 
-Two limits to know. The gate judges files a `[[scope]]` claims; a staged source file no
+Three limits to know. The gate judges files a `[[scope]]` claims; a staged source file no
 scope claims is not gated, and the hook says so on stderr (`N staged file(s) belong to no
 scope and were not gated`) so the hole is visible the moment a new top-level directory
-appears. And git runs hooks outside your shell's activated venv: bare `python` must resolve
-to an interpreter that has crapkit installed, or use the absolute form
+appears. A function the committed ratchet already carries a mark for is not gated either,
+so touching signed debt does not refuse the commit; the hook reports the count on stderr
+(`N staged function(s) carry a ratchet mark and were not gated`) and `crapkit verify` is
+what fails a mark that rose. And git runs hooks outside your shell's activated venv: bare
+`python` must resolve to an interpreter that has crapkit installed, or use the absolute
+form
 (`exec /path/to/venv/Scripts/python -m crapkit hook-precommit`).
 
 ### Route 1: `.git/hooks/pre-commit` (local, not committed)
@@ -699,7 +707,8 @@ advances the baseline nor tightens the ratchet, exit 9 included.
 ## Subcommands
 
 Every subcommand takes `--repo PATH` (default `.`), and the flag goes **after** the
-subcommand:
+subcommand. `claude-hook` is the one exception: it has no `--repo`, because it takes its
+root from the file named in the hook payload it reads.
 
 ```
 $ crapkit worklist --repo /path/to/repo --scope util --top 1
@@ -720,7 +729,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | Command | What it does |
 |---|---|
 | `init` | Sniffs tracked source into per-directory scopes, writes a self-validated starter `crapkit.toml` whose lanes report into `.crapkit/cov/`, and appends `.crapkit/` plus each runner's own droppings to `.gitignore`. Writes a live `[[lane]]` when it can detect the test runner, otherwise a commented template. Refuses to clobber an existing config. |
-| `doctor [--show-files] [--json] [--tune]` | 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, lanes writing their artifacts at the repo root instead of under `.crapkit/` (WARN), committed hooks under `core.hooksPath` that are not executable in the index (WARN), directories whose functions are all `untested` while their tests exist (WARN), and scopes a lane measures with no `[crapkit.scoped_tests]` template behind them (WARN), which is the loop's step 4 with nothing to run. `--tune` prints suggested parallelism knobs and writes nothing. See [docs/agent-json.md](docs/agent-json.md#doctor---json). |
+| `doctor [--show-files] [--json] [--tune] [--plugin-root PATH]` | Checks the config still describes the repo: unknown keys (with the accepted spellings), zero-file scopes, tracked source no scope claims, scopes no lane covers, lane cwds and commands that no longer resolve, lizard importable, oversized files, lanes writing their artifacts at the repo root instead of under `.crapkit/` (WARN), committed hooks under `core.hooksPath` that are not executable in the index (WARN), directories whose functions are all `untested` while their tests exist (WARN), and scopes a lane measures with no `[crapkit.scoped_tests]` template behind them (WARN), 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, comparing `.claude-plugin/plugin.json`'s version against the running crapkit and every `--protocol` in `hooks/hooks.json` against the protocol `claude-hook` answers, 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]` | Two lizard passes 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. |
@@ -735,11 +744,13 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `overrides [--json]` | The override audit trail: who granted what, when, and why. |
 | `trend [--json]` | Totals per trusted run: functions, over-target count, CRAP load, average, per-scope rollup. |
 | `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, opens no network connection, and carries no per-function CRAP or coverage, because no repo-wide payload has 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. |
 | `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. |
+| `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. |
 | `hook-precommit` | The cc-only gate on staged blobs. No coverage, no snapshot, no repo-wide cache. Exit 6 on a violation. |
+| `claude-hook [--protocol N]` | Reads one Claude Code PostToolUse payload from stdin and judges the file it edited: ccn against the scope ceiling, on functions the edit changed, minus functions a ratchet mark already covers. Advisory only: the edit has landed and nothing is blocked, and `hook-precommit` stays the enforcement point. Exit 2 with three lines on stderr is the only thing it ever says. No `crapkit.toml` above the edited file, an unscoped file, mid-rebase or mid-merge, a `--protocol` other than 1, source that parses to no functions, or any internal failure: exit 0, silence, empty stderr. Takes no `--repo` — the root is the first `crapkit.toml` above the edited file and the upward walk stops at a `.git` entry, so a worktree never borrows its parent's config. It opens no snapshot, writes nothing, and leaves stdout empty. |
 | `watch [--interval SECONDS] [--cycles N]` | Rescores tracked files as they change (mtime polling, default 2s, subprocess-isolated so a half-saved syntax error never kills the watcher). `--cycles N` polls exactly N times and exits 0; without it the loop runs until ctrl-c. |
 | `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing nine read-only tools. See [docs/agent-json.md](docs/agent-json.md#mcp-server). |
 
@@ -753,7 +764,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | [docs/ratchet.md](docs/ratchet.md) | Seeding, pruning, the git merge driver, metric stamps, debt policy, overrides. |
 | [docs/agent-json.md](docs/agent-json.md) | The machine surface: `schema`, every payload field, real captured examples. |
 | [docs/adoption.md](docs/adoption.md) | The judgment layer over the quickstarts: scope granularity, exclude vs lane, scoped_tests wiring, the first-verify taint hazard. |
-| [skills/](skills/) | Agent skills shipped with the repo (`crapkit`, `crapkit-recover`, `crapkit-onboard`) — install by copying to your agent runtime's skills directory. |
+| [plugin/](plugin/) | The Claude Code plugin: three skills (`crapkit`, `crapkit-recover`, `crapkit-onboard`), the read-side MCP server, and the advisory PostToolUse hook. Install with `claude plugin marketplace add JeanFrancoisGagne/crapkit` then `claude plugin install crapkit@crapkit`; other runtimes copy `plugin/skills/*` into their skills directory. |
 
 [crapkit.schema.json](crapkit.schema.json) is the authority on the config file shape.
 

{crapkit-0.2.0 → crapkit-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crapkit"
-version = "0.2.0"
+version = "0.4.0"
 description = "Deterministic CRAP-score framework: per-function complexity x coverage risk, worklists, ratchets, refactor verification"
 readme = "README.md"
 license = { text = "MIT" }

{crapkit-0.2.0 → crapkit-0.4.0}/src/crapkit/__init__.py

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

{crapkit-0.2.0 → crapkit-0.4.0}/src/crapkit/_pygdefer.py

@@ -6,9 +6,12 @@ importlib.metadata, email, zipfile and socket. Measured on this box: 42ms with
 pygments, 16ms without, paid by every process that touches the analysis stack,
 the pre-commit hook included.
 
-crapkit analyzes five languages (typescript, tsx, javascript, python, swift).
-Erlang is not one of them and no scope can name it. The readers that need
-pygments are still SHIPPED, not removed: `deferred_pygments()` puts proxies in
+crapkit analyzes fourteen languages (typescript, tsx, javascript, python, swift,
+go, rust, shell, powershell, cpp, objectivec, vue, java, zig). Erlang is not one
+of them and no scope can name it, which is the whole argument for stubbing its
+reader, so a test pins this list to `config.SUPPORTED_LANGUAGES`. The readers
+that need pygments are still SHIPPED, not removed: `deferred_pygments()` puts
+proxies in
 sys.modules for the duration of the lizard import, so the readers bind stand-ins
 and the real package loads the first time anything reads or calls one. An .erl
 file analyzed through lizard directly gets the same answer; it just pays the

{crapkit-0.2.0 → crapkit-0.4.0}/src/crapkit/analyze.py

@@ -5,9 +5,11 @@ nested node_modules (measured hang on the first consumer repo).
 """
 from __future__ import annotations
 
+import codecs
 import hashlib
 import json
 import os
+import sys
 import time
 from concurrent.futures import ProcessPoolExecutor
 from pathlib import Path
@@ -17,17 +19,40 @@ from ._pygdefer import deferred_pygments
 with deferred_pygments():  # lizard's Erlang reader would load pygments here
     import lizard
 
+    from .lizardpowershell import register as _register_powershell
+    from .lizardrust import register as _register_rust
+    from .lizardshell import register as _register_shell
+
 from .cache import partition_by_cache, updated_cache
 from .errors import ToolError
 from .lizardcognitive import LizardExtension as _Cognitive
 from .merge import FunctionRecord
+from .packet import bare_name
+
+# lizard picks a reader by extension off a hardcoded list, and none of these is
+# on it: `.rs` resolves to a reader that counts no `match` arm (lizard #494),
+# and `.sh` and `.ps1` resolve to nothing at all, which lizard answers with
+# CLikeReader rather than a failure. All three belong HERE, at the module scope
+# of the module a ProcessPoolExecutor child imports, or spawned workers measure
+# with the readers lizard shipped and report plausible wrong numbers.
+#
+# lizardshell and lizardpowershell already register themselves on import and
+# lizardrust deliberately does not (rebinding a name in another package's
+# namespace is not something an import should do quietly). Calling all three
+# keeps the wiring readable in one place and costs nothing: each is idempotent.
+_register_rust()
+_register_shell()
+_register_powershell()
 
 _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 = 3  # 3: cognitive complexity column joined the standard pass
+ANALYSIS_VERSION = 6  # 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
 
 # The three tokens lizard's modified rule reacts to. Membership is checked before
 # anything else runs, so the common token pays one frozenset lookup.
@@ -69,12 +94,39 @@ class _ModifiedDelta:
             yield token
 
 
-# Built once per process, not once per file: 14k files paid 14k chain builds.
-# Every extension in it keeps its state in the generator frame __call__ opens,
-# so one chain serves every file. Cognitive comes FIRST because lizard's own
-# preprocessors strip the whitespace tokens its python rules read; the delta
-# comes last, where the modified pass used to sit.
-_EXTENSIONS = [_Cognitive()] + lizard.get_extensions(["ND"]) + [_ModifiedDelta()]
+def _chain(cognitive_index: int) -> list:
+    """lizard's standard extensions with cognitive spliced in at one index.
+
+    Index 0 puts cognitive ahead of lizard's own `preprocessing`, which is where
+    it has to sit for Python: `preprocessing` strips the whitespace tokens the
+    python indent rules read, and behind it a 6-branch function scores 6 instead
+    of 10. The delta comes last either way, where the modified pass used to sit.
+    """
+    extensions = lizard.get_extensions(["ND"])
+    extensions.insert(cognitive_index, _Cognitive())
+    return extensions + [_ModifiedDelta()]
+
+
+# Two chains, built once per process each, not once per file: 14k files paid 14k
+# chain builds. Every extension keeps its state in the generator frame __call__
+# opens, so one chain serves every file of its kind.
+_EXTENSIONS = _chain(0)
+_PREPROCESSED_EXTENSIONS = _chain(1)
+
+# lizard's SwiftReplaceLabel.preprocess RETURNS a list where the other seven
+# preprocessors YIELD: it runs list() over its input, so every extension AHEAD of
+# `preprocessing` is drained to exhaustion before lizard has split the file into
+# functions. An extension at index 0 counts the whole file against one
+# placeholder FunctionInfo, and every real function comes out at 0. SwiftReader
+# and KotlinReader are the only two of lizard's 27 readers that inherit that
+# preprocessor, so only these suffixes take the second chain.
+_DRAINED_READER_SUFFIXES = (".swift", ".kt", ".kts")
+
+
+def _extensions_for(rel_path: str) -> list:
+    if rel_path.lower().endswith(_DRAINED_READER_SUFFIXES):
+        return _PREPROCESSED_EXTENSIONS
+    return _EXTENSIONS
 
 
 def _record(rel_path: str, fn) -> FunctionRecord:
@@ -95,11 +147,145 @@ def _record(rel_path: str, fn) -> FunctionRecord:
     )
 
 
+# How many colliding names one warning prints before it stops. A generated file
+# can hold hundreds; the point is that the file needs looking at, not the list.
+_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)`, 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.
+    """
+    seen: set[str] = set()
+    colliding: dict[str, None] = {}
+    for record in records:
+        if bare_name(record.long_name) and record.long_name in seen:
+            colliding[record.long_name] = None
+        seen.add(record.long_name)
+    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.
+
+    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.
+    """
+    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)
+
+
+def _listed(names: list[str]) -> str:
+    if len(names) <= _NAMES_SHOWN:
+        return ", ".join(names)
+    return f"{', '.join(names[:_NAMES_SHOWN])} and {len(names) - _NAMES_SHOWN} more name(s)"
+
+
+def _file_records(rel_path: str, functions) -> list[FunctionRecord]:
+    records = [_record(rel_path, fn) for fn in functions]
+    _warn_on_collisions(rel_path, records)
+    return records
+
+
+# --- how a source file's bytes become text -------------------------------------
+#
+# lizard opens a source file with `io.open(path, 'r')` and no encoding, so the
+# MACHINE'S LOCALE decides what a repo scores. Measured on one function,
+# `function Write-Café`, written once as UTF-8 and once as cp1252, read on a
+# cp1252 interpreter and on a UTF-8 one:
+#
+#     source     cp1252 reader        utf-8 reader
+#     utf-8      no function at all   Write-Café
+#     cp1252     Write-Café           Write-Caf
+#
+# The empty cell is not a rounding error: `é` arrives as `Ã` plus `©`, the `©`
+# is no word character, and the declaration stops being one. The ratchet keys on
+# path::long_name, so those are three different rows for one commit, and a
+# Windows developer and a Linux CI cannot see each other's baseline.
+#
+# utf-8 first, cp1252 second, replacement for the five bytes cp1252 leaves
+# undefined. That is the whole rule and it is fixed rather than environmental:
+# all four cells above read `Write-Café`. The fallback is cp1252 rather than
+# latin-1 because Windows PowerShell 5.1 writes cp1252, and because latin-1
+# decodes every byte and so can never say it was wrong.
+#
+# UTF-16 is NOT handled. `Out-File` and the ISE write it, and such a file
+# decodes here as NUL-separated cp1252 text that reports no function; it
+# reported none before this change either, so nothing regressed and the narrow
+# rule stays narrow.
+
+
+def _characters(raw: bytes) -> str:
+    if raw.startswith(codecs.BOM_UTF8):
+        raw = raw[len(codecs.BOM_UTF8):]
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return raw.decode("cp1252", "replace")
+
+
+def decode_source(raw: bytes) -> str:
+    """Source bytes as text, decoded by content rather than by machine locale.
+
+    The single rule for every path into lizard: a file on disk, and a staged
+    blob the pre-commit gate never writes down. Those two must agree or the
+    gate judges different content than the inventory scores.
+
+    Line endings are normalized the way `io.open(path, 'r')` normalized them,
+    because that is what lizard did and every recorded line number and NLOC in
+    every cache depends on it: a lone `\\r` left in the stream is one more
+    whitespace token, not one more line.
+    """
+    return _characters(raw).replace("\r\n", "\n").replace("\r", "\n")
+
+
+def read_source(path: str) -> str:
+    return decode_source(Path(path).read_bytes())
+
+
+def _install_decoder() -> None:
+    """Point lizard's own file read at `read_source`. Idempotent.
+
+    A rebind rather than a replacement for `FileAnalyzer.__call__`, so lizard
+    keeps the IOError branch that answers a file deleted mid-run with an empty
+    result instead of a traceback, and keeps reading each file exactly once.
+    `lizard.py` binds `auto_read` into its own module namespace at import, and
+    `FileAnalyzer.__call__` resolves it there on every call.
+
+    Raises when that name is gone, which is what a lizard release that reads
+    source some other way would look like. Loud beats an attribute nobody
+    reads and a decode that silently went back to the locale's.
+    """
+    if not hasattr(lizard, "auto_read"):
+        raise RuntimeError(
+            f"crapkit.analyze._install_decoder() found no lizard.auto_read to "
+            f"rebind: lizard {lizard.version} reads source some other way. "
+            f"Rewrite this against the new mechanism; leaving it undone makes "
+            f"every non-ASCII file score by the machine's locale.")
+    lizard.auto_read = read_source
+
+
+_install_decoder()
+
+
 def analyze_one(args: tuple[str, str]) -> tuple[str, list[FunctionRecord]]:
     abs_path, rel_path = args
     try:
-        analysis = lizard.FileAnalyzer(_EXTENSIONS)(abs_path)
-        return rel_path, [_record(rel_path, fn) for fn in analysis.function_list]
+        analysis = lizard.FileAnalyzer(_extensions_for(rel_path))(abs_path)
+        return rel_path, _file_records(rel_path, analysis.function_list)
     except Exception as exc:  # loud, with the file named
         raise ToolError(f"lizard failed on {rel_path}: {exc}") from exc
 
@@ -110,11 +296,12 @@ def analyze_source(rel_path: str, code: str) -> list[FunctionRecord]:
     analyze_source_code is what FileAnalyzer.__call__ runs once it has read the
     file, so nothing about the analysis depends on whether the source arrived
     from the disk or from a git blob the caller already holds; rel_path picks
-    the language exactly as the path on disk did.
+    the language, and with it the extension chain, exactly as the path on disk did.
     """
     try:
-        analysis = lizard.FileAnalyzer(_EXTENSIONS).analyze_source_code(rel_path, code)
-        return [_record(rel_path, fn) for fn in analysis.function_list]
+        analyzer = lizard.FileAnalyzer(_extensions_for(rel_path))
+        analysis = analyzer.analyze_source_code(rel_path, code)
+        return _file_records(rel_path, analysis.function_list)
     except Exception as exc:  # loud, with the file named
         raise ToolError(f"lizard failed on {rel_path}: {exc}") from exc