crapkit 0.4.6__tar.gz → 0.4.8__tar.gz

{crapkit-0.4.6 → crapkit-0.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.6
+Version: 0.4.8
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -44,6 +44,8 @@ Dynamic: license-file
 [![Python](https://img.shields.io/pypi/pyversions/crapkit)](https://pypi.org/project/crapkit/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
+![crapkit init, coverage and worklist --top 5 on a small Python repo, then a shell heredoc adding a function at ccn 7: the per-edit advisory reports it and exits 2, and the commit gate refuses the staged file with exit 6](https://raw.githubusercontent.com/JeanFrancoisGagne/crapkit/main/docs/demo.gif)
+
 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
 Python, TypeScript, TSX, JavaScript, Swift, Go, Rust, shell, PowerShell, C and C++,
@@ -145,7 +147,7 @@ changing crapkit.
 
 ```
 $ crapkit --version
-crapkit 0.4.6
+crapkit 0.4.8
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -227,6 +229,33 @@ ceiling. It adds no files to your repo, and it needs the crapkit CLI on PATH.
 A repo with no `crapkit.toml` costs a silent sub-50 ms no-op per edit. Other agent
 runtimes have no marketplace: copy `plugin/skills/*` into their skills directory instead.
 
+The hook registers on `Edit|Write`, which is every write that names a file. An agent that
+writes its source through a shell heredoc names none, so a `Bash` event is judged off the
+working tree instead. That half is yours to register, because it costs two
+git spawns per shell call. Add a second PostToolUse entry to your own settings, same
+command, matcher `Bash`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "crapkit claude-hook --protocol 1", "timeout": 20 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The cost is one `git rev-parse --show-toplevel` and one `git status --porcelain -z -uall`
+per shell call in any git repo, whether or not crapkit measures it: about 30 ms together
+on crapkit's own checkout, and more on a bigger tree. What comes back is the dirty or
+untracked `*.py` files written in the last 12 seconds, 25 at most, each judged the way an
+edit is. Python only, so a TypeScript or Go repo pays the two spawns and hears nothing.
+
 ## Languages
 
 14 languages, two coverage parsers. Coverage joins where a parser exists; everything else
@@ -346,7 +375,7 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
     # crapkit's release step rewrites this line to the tag it just cut
-    rev: v0.4.6
+    rev: v0.4.8
     hooks:
       - id: crapkit-gate
 ```
@@ -442,6 +471,122 @@ commit, and a row in the override log. All three land or nothing does, and an un
 `alert_command` refuses the override outright. See
 [docs/ratchet.md](docs/ratchet.md#overrides-and-the-audit-trail).
 
+## The GitHub Action
+
+[action.yml](action.yml) at this repository's root is a composite action, so a reviewer
+sees crapkit's numbers on the pull request without installing anything. Four lines add it
+to a workflow, and every input has a default:
+
+```yaml
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: JeanFrancoisGagne/crapkit@v0.4.8
+```
+
+The whole job those four lines sit in:
+
+```yaml
+on: pull_request
+jobs:
+  crapkit:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write             # the comment, and nothing else
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0               # the diff, and verify's baseline commit
+      - run: pip install -e ".[dev]"   # whatever your lanes need to run
+      - uses: JeanFrancoisGagne/crapkit@v0.4.8
+        with:
+          gate: "false"
+```
+
+That `pip install` step is the one people leave out, and it is the same one Route 4 above
+names: the action installs crapkit and nothing else, so your lanes still need whatever
+your test command needs. Without it the lane writes no artifact and the comment says so.
+
+`fetch-depth: 0` is the other one. `actions/checkout` clones a single commit; the action
+reads the pull request's changed files out of git and `verify` reads the diff against the
+baseline's commit. With a shallow clone the file list comes back empty and the comment
+ranks the whole repository instead of the diff.
+
+The action installs crapkit from `$GITHUB_ACTION_PATH`, which is its own checkout of the
+ref you pinned in `uses:`. So `@v0.4.8` scores your tree with 0.4.8's crapkit rather than
+with whatever released last, and pinning a tag is the whole version policy.
+
+### What the comment looks like
+
+One comment per pull request, edited in place on every push. A hidden
+`<!-- crapkit-action -->` line is how the next run finds it, so a fifteen-push branch
+carries one comment and not fifteen. On a `push` event there is no pull request to carry
+it, and the same text goes to the job log instead.
+
+Rendered against this repository's own store, with a base commit fifteen back standing in
+for a pull request:
+
+```markdown
+<!-- crapkit-action -->
+
+## crapkit
+
+1333 functions in 61 files, 0 over target, CRAP load 3713.89, grade A+.
+
+**verify passed.** Run 2 against baseline 1, 7 changed files.
+
+### Worklist: 39 changed files
+
+| File | Function | ccn | risk | remedy |
+|---|---|---:|---:|---|
+| `src/crapkit/cli/admin.py:1026` | `_recorded_roots( recorded )` | 6 | 10.9908 | ok |
+| `src/crapkit/lanes.py:646` | `build_retest_command( template : str , tests : set [ str ] )` | 6 | 10.8234 | ok |
+| `src/crapkit/cli/admin.py:80` | `_next_step( scopes : dict , lanes : tuple )` | 5 | 9.159 | ok |
+| `src/crapkit/cli/admin.py:239` | `_pytest_cov_probe( command : str )` | 5 | 9.159 | ok |
+| `src/crapkit/cli/admin.py:505` | `_segment_problems( name : str , cwd : Path , tokens : list [ str ] )` | 5 | 9.159 | ok |
+```
+
+The rows are the ranked worklist for the files the pull request changed, worst first,
+`top` of them. `risk` is ccn times churn weight, the number `crapkit worklist` ranks on,
+and `remedy` is the run's own verdict for that function: `decompose`, `add-tests` or `ok`.
+A pull request that touches no ranked function gets the heading and no table.
+
+The two file counts describe two different diffs, and both are wanted. `39 changed files`
+is the pull request's own list, `git diff --name-only` against the base commit, and it is
+what the table is filtered to. `7 changed files` on the verdict line is what `verify`
+measured against its baseline run, which is the section below.
+
+### The inputs
+
+| Input | Default | What it does |
+|---|---|---|
+| `gate` | `"false"` | `"true"` exits with `crapkit verify`'s own code, so a finding fails the check. Anything else exits 0 and the comment is the whole output |
+| `top` | `"5"` | worklist rows rendered in the table |
+| `python-version` | `"3.12"` | the interpreter `actions/setup-python` installs crapkit into |
+
+`gate: "false"` is the default on purpose. A team adopts the action before it has decided
+which findings should stop a merge, and a check that fails on day one gets turned off on
+day two.
+
+### What the verdict line covers
+
+The action runs `crapkit coverage --json` and then `crapkit verify --json
+--reuse-artifacts`, so the baseline is the run written a step earlier, at this same
+commit. On a clean checkout that diff is empty: the verdict line reports the tree's own
+health and the exit code verify returned, not the pull request's delta. The gate that
+judges the delta is the portable baseline in [Route 4](#route-4-ci): commit
+`crapkit-baseline.tsv` on the default branch and run `crapkit verify --baseline-tsv
+crapkit-baseline.tsv` in a step of your own beside this one.
+
+`--reuse-artifacts` is what keeps the job to one test run. `coverage` ran the lanes
+moments earlier on this same tree, and verify parses those artifacts rather than running
+your whole suite a second time for the same numbers.
+
+The comment is posted with `gh api` and the job's own `GITHUB_TOKEN`, which needs
+`pull-requests: write`. Two things it cannot do: a pull request from a fork gets a
+read-only token, so the POST is a 403 there, and a self-hosted runner without the `gh` CLI
+on PATH fails that step. Both leave the rendered text in the job log.
+
 ## Subcommands
 
 Every subcommand takes `--repo PATH` (default `.`), and the flag goes **after** the
@@ -488,7 +633,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `mutate [--files F ...] [--max-mutants N] [--drop-pool] [--json]` | Diff-scoped mutation testing: flips comparisons, boundary shifts, boolean connectives and boolean literals on changed lines, runs `mutation_command` per mutant, lists survivors. `--files` replaces diff scope with the whole file. `--max-mutants` (default 100) caps the run and the cap warning goes to stderr only, so `mutants` in `--json` is the capped count. Shell and PowerShell files are refused by name on stderr rather than mutated: `<` and `>` are redirections there, not comparisons. With `mutation_workers > 1` the worker worktrees are kept at `.crapkit/mutate-pool/` and re-prepared per run (30.6 s to build four on a 31,459-file repo, 0.46 s to re-prepare them); `--drop-pool` removes them and exits. |
 | `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, 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 all exit 0 in silence. Takes no `--repo`, because 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 and writes nothing. |
+| `claude-hook [--protocol N]` | Reads one Claude Code PostToolUse payload from stdin and judges the file it edited: ccn against the scope ceiling, on functions the edit changed, minus functions a ratchet mark already covers. Advisory only: the edit has landed, and `hook-precommit` stays the enforcement point. Exit 2 and an advisory on stderr is the only thing it ever says, one block per judged file (a head line, one line per breaching function, a closing line): no `crapkit.toml` above the edited file, an unscoped file, mid-rebase or mid-merge, a `--protocol` other than 1, source that parses to no functions, or any internal failure all exit 0 in silence. The root is the first `crapkit.toml` above the edited file; the walk stops at a `.git` entry, so a worktree never borrows its parent's config. A `Bash` event names no file, so it judges the working tree instead: the dirty or untracked `*.py` files touched in the last 12 seconds, 25 at most, each through the same ladder, and silence for a clean tree or a cwd outside any repo. That half fires only where you register a `Bash` matcher ([The Claude Code plugin](#the-claude-code-plugin)). It opens no snapshot and writes nothing. |
 | `watch [--interval SECONDS] [--cycles N]` | Rescores tracked files as they change (mtime polling, default 2s, subprocess-isolated so a half-saved syntax error never kills the watcher). `--cycles N` polls exactly N times and exits 0; without it the loop runs until ctrl-c. |
 | `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing nine read-only tools. Every tool shells to the CLI's own `--json` surface, so the MCP view cannot drift from what the CLI reports. Answering from a kept in-process store was benchmarked and rejected: a packet's `source` would go stale behind the edit it describes. See [docs/agent-json.md](docs/agent-json.md#mcp-server). |
 
@@ -616,7 +761,7 @@ crapkit: run 3 is an inventory run (no coverage was measured) and cannot serve a
 | 2 | Usage error from argparse: unknown flag, missing positional. Raised before crapkit's own error handling. |
 | 3 | Config error: `crapkit.toml` missing or unparseable, an unknown language or parser, a lane command the shell that runs it reads as a narrowed suite, a ratchet metric-stamp mismatch ([Upgrading from 0.4.4](#upgrading-from-044)), a `test-scoped` file under no scope or under a scope with no template. |
 | 4 | Git error: not a repository, a baseline commit rewritten out of the history. |
-| 5 | Tool error: lizard not importable, a lane produced no artifact or one that measured a different tree, a lane timed out past its retries, an override alert command failed. A `timeout_seconds` kills the whole process tree, so no orphan suite keeps running behind the failure. |
+| 5 | Tool error: lizard not importable, a lane that produced no artifact, one that measured a different tree, one that measured this tree and reported it in absolute paths (the join is root-relative, so those match nothing either; the refusal names the runner's own switch, `relative_files = true` under `[tool.coverage.run]` for a coveragepy lane, the reporter's `cwd`/`root` option for an istanbul one), a lane that timed out past its retries, an override alert command that failed. A `timeout_seconds` kills the whole process tree, so no orphan suite keeps running behind the failure. |
 | 6 | Gate violation. A function the diff touched is over its ceiling and past any ratchet mark it carries: an edit that leaves a marked function at or under its mark is the debt the repo signed for and is exempt. Also `rescore --gate`, which applies the same rule, and `hook-precommit`, which exempts on the mark's existence instead. |
 | 7 | Ratchet regression the diff never touched. A marked function scores worse than its recorded high-water mark; a touched one past its mark reports 6. |
 | 8 | New test failures against the baseline run. Failures the baseline already had do not count. |
@@ -671,7 +816,8 @@ coverage lane from what the repo already has: a pytest marker file (`pyproject.t
 the matching `run` for the rest), because a bare `python` binds to whichever venv the shell
 has active rather than the one the repo pins — see
 [The interpreter a lane binds to](docs/lanes.md#the-interpreter-a-lane-binds-to). Whatever
-it detects, it also leaves commented templates for the runners it did not find. Every lane
+it detects, it also leaves commented templates for the runners it did not find, and those
+carry the same launcher, so uncommenting one cannot hand the bare `python` back. Every lane
 it writes reports into `.crapkit/cov/`, which is why the `.gitignore` list is so short: see
 [Where artifacts live](docs/lanes.md#where-artifacts-live).