crapkit 0.4.7__tar.gz → 0.4.9__tar.gz

{crapkit-0.4.7 → crapkit-0.4.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.7
+Version: 0.4.9
 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.7
+crapkit 0.4.9
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -373,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.7
+    rev: v0.4.9
     hooks:
       - id: crapkit-gate
 ```
@@ -469,6 +471,151 @@ 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 the same diff, counted twice. `39 changed files` is
+`git diff --name-only base.sha...HEAD`, the branch's own commits, and it is what the
+table is filtered to. The count on the verdict line is what `verify` measured from the
+same fork point. With `delta: "false"` the second one is 0, because there is nothing
+behind the checkout to measure from.
+
+### 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 |
+| `delta` | `"true"` | scores the pull request's base commit first, so the verdict covers the commits the pull request adds. Costs a second lane run; `"false"` scores the checkout alone |
+| `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
+
+On a pull request, the commits the pull request adds. The action scores the fork point
+first, then the checkout, then runs `crapkit verify --base <fork>`, which measures the
+diff from there and takes the fork point's run as its baseline. So the gate judges the
+functions in the diff a reviewer is reading, and a repository that was already over its
+ceiling before the branch started does not fail every pull request that touches it.
+
+The fork point is `git merge-base` of `base.sha` and HEAD, not `base.sha` itself.
+`base.sha` is the base branch's tip when the event fired, so a base branch that moved
+after the branch forked carries commits HEAD never saw, and a run there would be neither
+the baseline verify wants nor a diff anyone is reviewing.
+
+The base run happens in a detached worktree under `RUNNER_TEMP`, and its store is copied
+over the checkout's so both runs sit in one place. The cost is **two lane runs on a pull
+request**: your suite runs once at the fork point and once on the checkout. Set `delta:
+"false"` to skip the base run, and the verdict falls back to the checkout against its own
+run, which reports the tree's own health and judges no changed function.
+
+Three things leave the base run unmade, and none of them fails the job: a shallow clone
+that does not hold the fork point, a fork point older than your `crapkit.toml`, and a
+lane that will not run against that tree. The step logs `crapkit base scoring exited N`
+and the verdict falls back the same way `delta: "false"` does. A `push` event never makes
+one, because there is no base commit and no pull request to comment on.
+
+One requirement the base run adds: the lane has to measure the tree it runs in. A lane
+that reaches an installed copy of your package instead of the checkout will measure the
+pull request's code while standing on the base commit, and the two runs then describe the
+same tree. `crapkit verify` refuses a run whose artifact names files outside the tree
+(exit 5), which catches the loud version of this; a lane pinned to a path outside the
+worktree is the quiet one. Point the lane at the tree, or set `delta: "false"`.
+
+`--reuse-artifacts` is what keeps each of those runs to one pass of your suite. `coverage`
+ran the lanes moments earlier on that tree, and verify parses those artifacts rather than
+running the whole suite a second time for the same numbers.
+
+The other gate that judges a 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. It needs no second lane run, and it needs
+someone to keep that file current.
+
+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