crapkit 0.5.0__tar.gz → 0.5.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.5.0
+Version: 0.5.1
 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.5.1
 ```
 
 `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.5.1
     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.5.1
 ```
 
 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.5.1
         with:
           gate: "false"
 ```
@@ -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.5.1}/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.5.1
 ```
 
 `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.5.1
     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.5.1
 ```
 
 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.5.1
         with:
           gate: "false"
 ```
@@ -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.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crapkit"
-version = "0.5.0"
+version = "0.5.1"
 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.5.1}/src/crapkit/__init__.py

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

{crapkit-0.5.0 → crapkit-0.5.1}/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)

{crapkit-0.5.0 → crapkit-0.5.1}/src/crapkit/verify.py

@@ -206,6 +206,23 @@ def _ratchet_regressions(fresh, ratchet, dirty) -> list[RatchetRegression]:
     return regressions
 
 
+def unmarked_over_ceiling(fresh: list[ScoredRow], ratchet: list[RatchetEntry], target: int,
+                          scope_targets: dict[str, int] | None = None) -> list[ScoredRow]:
+    """Standing debt nothing guards: the worst row per ratchet key that sits over
+    its ceiling with no mark under that key, worst first.
+
+    The gate judges touched functions only and the ratchet check compares marks
+    only, so a rise on one of these (coverage loss included) reaches no finding.
+    A marked function that rose is a regression already; this is the debt
+    `ratchet seed` was never run on.
+    """
+    marks = _marks_of(ratchet)
+    rows = [row for key, row in rows_by_key(fresh).items()
+            if row.crap > _ceiling(row, target, scope_targets) and key not in marks]
+    rows.sort(key=lambda r: (-r.crap, r.path, r.start))
+    return rows
+
+
 def evaluate(
     *,
     fresh: list[ScoredRow],

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.5.0
+Version: 0.5.1
 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.5.1
 ```
 
 `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.5.1
     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.5.1
 ```
 
 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.5.1
         with:
           gate: "false"
 ```
@@ -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