crapkit 0.5.0__tar.gz → 0.6.0__tar.gz

{crapkit-0.5.0/src/crapkit.egg-info → crapkit-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.5.0
+Version: 0.6.0
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -73,6 +73,16 @@ half-executed straight-line function never reads as fully covered.
 function at ccn 7 with 100% coverage still scores 7 and still fails the gate. The only
 move that clears it is splitting the function.
 
+**Why 6 and not 30.** crap4j's conventional threshold of 30 is a CRAP score: it lets an
+untested `ccn 5` through (25 + 5 = 30) and a fully covered `ccn 30` too. crapkit's default
+is a complexity ceiling, because coverage can at best collapse CRAP to `ccn`, and a
+function you cannot cover past `ccn 6` is one you decompose. Set `target = 30` in
+`crapkit.toml` if you want the crap4j number. A repo with existing debt does not need to:
+`ratchet seed` marks today's over-ceiling functions at today's score, the gate then judges
+only the functions a change touches, and marks may only fall, so adoption never starts with
+a wall of red. Next to crap4py, radon, xenon, wily and SonarQube:
+[docs/comparison.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/comparison.md).
+
 crapkit scores **git-tracked files only**. Source you have not `git add`ed is invisible to
 it.
 
@@ -171,7 +181,7 @@ leaves the box
 
 ```
 $ crapkit --version
-crapkit 0.5.0
+crapkit 0.6.0
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -415,7 +425,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.5.0
+    rev: v0.6.0
     hooks:
       - id: crapkit-gate
 ```
@@ -523,7 +533,7 @@ to a workflow, and every input has a default:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: JeanFrancoisGagne/crapkit@v0.5.0
+      - uses: JeanFrancoisGagne/crapkit@v0.6.0
 ```
 
 The whole job those four lines sit in:
@@ -543,7 +553,7 @@ jobs:
         with:
           python-version: "3.12"       # the interpreter the install below lands in
       - run: pip install -e ".[dev]"   # whatever your lanes need to run
-      - uses: JeanFrancoisGagne/crapkit@v0.5.0
+      - uses: JeanFrancoisGagne/crapkit@v0.6.0
         with:
           gate: "false"
 ```
@@ -765,7 +775,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `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. |
 | `help [TOPIC]` | The help git, npm and docker answer to. With no TOPIC it prints the command list; with one it prints that subcommand's own help, the same page as `crapkit TOPIC --help`. A TOPIC that names no subcommand exits 3. |
-| `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing ten 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](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#mcp-server). |
+| `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing twelve read-only tools named `verb_noun`, each with a title and a documented output schema. 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](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#mcp-server). |
 
 ## Reading the output
 
@@ -1285,6 +1295,11 @@ dropped it once `classify` scored under the ceiling, rewriting the tracked
 A verify may also print `warning: N changed line(s) have no coverage` above its verdict;
 that block is advisory unless `diff_uncovered_max` is set
 ([docs/configuration.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/configuration.md)).
+It prints `warning: N function(s) over the ceiling carry no ratchet mark` when the tree
+holds debt `ratchet seed` never signed: the gate judges touched functions only and the
+ratchet check compares marks only, so coverage loss on such a function would pass unseen.
+The count is `unmarked_over_target` in `--json`, fires no exit code, and is zero on a repo
+with no debt.
 
 ## Documentation
 

{crapkit-0.5.0 → crapkit-0.6.0}/README.md

@@ -34,6 +34,16 @@ half-executed straight-line function never reads as fully covered.
 function at ccn 7 with 100% coverage still scores 7 and still fails the gate. The only
 move that clears it is splitting the function.
 
+**Why 6 and not 30.** crap4j's conventional threshold of 30 is a CRAP score: it lets an
+untested `ccn 5` through (25 + 5 = 30) and a fully covered `ccn 30` too. crapkit's default
+is a complexity ceiling, because coverage can at best collapse CRAP to `ccn`, and a
+function you cannot cover past `ccn 6` is one you decompose. Set `target = 30` in
+`crapkit.toml` if you want the crap4j number. A repo with existing debt does not need to:
+`ratchet seed` marks today's over-ceiling functions at today's score, the gate then judges
+only the functions a change touches, and marks may only fall, so adoption never starts with
+a wall of red. Next to crap4py, radon, xenon, wily and SonarQube:
+[docs/comparison.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/comparison.md).
+
 crapkit scores **git-tracked files only**. Source you have not `git add`ed is invisible to
 it.
 
@@ -132,7 +142,7 @@ leaves the box
 
 ```
 $ crapkit --version
-crapkit 0.5.0
+crapkit 0.6.0
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -376,7 +386,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.5.0
+    rev: v0.6.0
     hooks:
       - id: crapkit-gate
 ```
@@ -484,7 +494,7 @@ to a workflow, and every input has a default:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: JeanFrancoisGagne/crapkit@v0.5.0
+      - uses: JeanFrancoisGagne/crapkit@v0.6.0
 ```
 
 The whole job those four lines sit in:
@@ -504,7 +514,7 @@ jobs:
         with:
           python-version: "3.12"       # the interpreter the install below lands in
       - run: pip install -e ".[dev]"   # whatever your lanes need to run
-      - uses: JeanFrancoisGagne/crapkit@v0.5.0
+      - uses: JeanFrancoisGagne/crapkit@v0.6.0
         with:
           gate: "false"
 ```
@@ -726,7 +736,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `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. |
 | `help [TOPIC]` | The help git, npm and docker answer to. With no TOPIC it prints the command list; with one it prints that subcommand's own help, the same page as `crapkit TOPIC --help`. A TOPIC that names no subcommand exits 3. |
-| `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing ten 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](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#mcp-server). |
+| `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing twelve read-only tools named `verb_noun`, each with a title and a documented output schema. 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](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#mcp-server). |
 
 ## Reading the output
 
@@ -1246,6 +1256,11 @@ dropped it once `classify` scored under the ceiling, rewriting the tracked
 A verify may also print `warning: N changed line(s) have no coverage` above its verdict;
 that block is advisory unless `diff_uncovered_max` is set
 ([docs/configuration.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/configuration.md)).
+It prints `warning: N function(s) over the ceiling carry no ratchet mark` when the tree
+holds debt `ratchet seed` never signed: the gate judges touched functions only and the
+ratchet check compares marks only, so coverage loss on such a function would pass unseen.
+The count is `unmarked_over_target` in `--json`, fires no exit code, and is zero on a repo
+with no debt.
 
 ## Documentation
 

{crapkit-0.5.0 → crapkit-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crapkit"
-version = "0.5.0"
+version = "0.6.0"
 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" }

{crapkit-0.5.0 → crapkit-0.6.0}/src/crapkit/__init__.py

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

{crapkit-0.5.0 → crapkit-0.6.0}/src/crapkit/cli/verifying.py

@@ -483,9 +483,13 @@ def _verify_attribution(verdict) -> dict:
 
 
 def _verify_result(verdict, overridden, run_id: int, baseline: dict, commit: str, ranges,
-                   uncovered: list, diff_uncovered_max: int | None) -> dict:
+                   uncovered: list, diff_uncovered_max: int | None,
+                   unmarked_over_target: int) -> dict:
     """`diff_uncovered_max` travels with the count it judges: a reader of exit 9
-    (the Action's comment) can say which ceiling the lines went over."""
+    (the Action's comment) can say which ceiling the lines went over.
+    `unmarked_over_target` is the standing debt no mark covers (see
+    `_warn_standing_debt`); it fires no exit code and is the one number that
+    says how much of the tree the ratchet is not holding."""
     return {
         "ok": verdict.ok,
         "run_id": run_id,
@@ -500,10 +504,28 @@ def _verify_result(verdict, overridden, run_id: int, baseline: dict, commit: str
         "diff_uncovered_count": len(uncovered),
         "diff_uncovered": [{"path": p, "line": ln} for p, ln in uncovered[:50]],
         "diff_uncovered_max": diff_uncovered_max,
+        "unmarked_over_target": unmarked_over_target,
         **_verify_attribution(verdict),
     }
 
 
+def _warn_standing_debt(unmarked: list) -> None:
+    """One stderr line for the over-ceiling functions no mark covers.
+
+    The gate never looks at an untouched function and the ratchet check compares
+    marks only, so a rise on these (coverage loss included) reaches no finding;
+    docs/ratchet.md says "seed once, early" for exactly this, and a header-only
+    marks file cannot say whether seed ever ran. stderr, because
+    `--json` prints one object on stdout. Silent at zero, which is the state
+    of a repo with no debt and of one seeded in full.
+    """
+    if not unmarked:
+        return
+    print(f"warning: {len(unmarked)} function(s) over the ceiling carry no ratchet mark, so a "
+          f"rise on them (coverage loss included) passes unseen; record them with "
+          f"`{_self()} ratchet seed`", file=sys.stderr)
+
+
 def _warn_diff_uncovered(uncovered: list) -> None:
     if not uncovered:
         return
@@ -576,7 +598,7 @@ def cmd_verify(args: argparse.Namespace) -> int:
     from ..diffparse import changed_ranges
     from ..gitio import GitFacts, diff_since
     from ..uncovered import missing_by_path
-    from ..verify import diff_uncovered, evaluate
+    from ..verify import diff_uncovered, evaluate, unmarked_over_ceiling
 
     root = _command_root(args.repo)
     cfg = _load_repo_config(root)
@@ -616,6 +638,8 @@ def cmd_verify(args: argparse.Namespace) -> int:
     # the whole cost of the post-commit verify on an unchanged tree.
     uncovered = diff_uncovered(ranges, missing_by_path(root, cfg)) if ranges else []
     _warn_diff_uncovered(uncovered)
+    unmarked = unmarked_over_ceiling(scored, ratchet, cfg.target, cfg.scope_targets)
+    _warn_standing_debt(unmarked)
     breach = _diff_cover_breach(cfg, uncovered)
     if breach:
         verdict = verdict._replace(ok=False)  # a breached run never advances the baseline
@@ -629,7 +653,7 @@ def cmd_verify(args: argparse.Namespace) -> int:
 
     _report_verify(args.json,
                    {**_verify_result(verdict, overridden, run_id, baseline, commit, ranges,
-                                     uncovered, cfg.diff_uncovered_max),
+                                     uncovered, cfg.diff_uncovered_max, len(unmarked)),
                     **_receipt(tool_versions, ratchet_sha256, changes)},
                    verdict, overridden, cfg.ratchet_file)
     _refuse_override(verdict, args.override)