ratch 0.1.2__tar.gz → 0.1.3__tar.gz

{ratch-0.1.2/ratch.egg-info → ratch-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ratch
-Version: 0.1.2
+Version: 0.1.3
 Summary: The ratchet only turns one way: code is the single source of truth.
 License: Apache-2.0
 Requires-Python: >=3.11

{ratch-0.1.2 → ratch-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ratch"
-version = "0.1.2"
+version = "0.1.3"
 description = "The ratchet only turns one way: code is the single source of truth."
 license = {text = "Apache-2.0"}
 requires-python = ">=3.11"

{ratch-0.1.2 → ratch-0.1.3}/ratch/checks/ai_signatures.py

@@ -53,11 +53,13 @@ class NoAiSignatures:
         r"Assisted by",
         "\N{ROBOT FACE}",
         r"[\w.+-]+@users\.noreply\.[\w.]+",
-    ), min_surface=1):
+    ), min_surface=1, sources=("log",), files=()):
         if min_surface < 1:
             raise ValueError("min_surface must be >= 1")
         self.patterns = tuple(patterns)
         self.min_surface = min_surface
+        self.sources = tuple(sources)
+        self.files = tuple(files)
 
     def _state(self, findings, examined_n):
         if findings:
@@ -70,12 +72,29 @@ class NoAiSignatures:
         proc = ws.run(["git", "rev-parse", "--is-shallow-repository"])
         return proc.stdout.strip() == "true"
 
+    def _scan(self, haystack, path, prefix, findings):
+        for pattern in self.patterns:
+            if re.search(pattern, haystack, re.IGNORECASE):
+                anchor = f"{prefix}:{pattern}"
+                findings.append(
+                    Finding(self.id, path, anchor,
+                            message=f"provenance leak {anchor}")
+                )
+
     def check(self, ws):
         findings = []
         examined_n = 0
-        if not self._is_shallow(ws):
+        if self._is_shallow(ws):
+            findings.append(
+                Finding(self.id, "<git>", "shallow",
+                        message="shallow clone; history is incomplete")
+            )
+            return Result(
+                self.id, State.FAIL, examined_n=1,
+                skipped_n=ws.skipped_n, findings=findings,
+            )
+        if "log" in self.sources:
             raw = ws.git_log(
-                rng=None,
                 fmt="%H%x00%an%x00%ae%x00%cn%x00%ce%x00%B%x00",
             )
             fields = raw.split("\x00")
@@ -84,16 +103,23 @@ class NoAiSignatures:
                 an, ae, cn, ce, body = fields[i + 1:i + 6]
                 examined_n += 1
                 haystack = "\n".join([an, ae, cn, ce, body])
-                for pattern in self.patterns:
-                    # IGNORECASE so GitHub's canonical `Co-authored-by:` casing
-                    # (and `generated with` / `assisted by`) is caught too
-                    # (resolves Fable finding: default missed lowercase trailers).
-                    if re.search(pattern, haystack, re.IGNORECASE):
-                        anchor = f"{sha[:9]}:{pattern}"
-                        findings.append(
-                            Finding(self.id, "<commit>", anchor,
-                                    message=f"provenance leak {anchor}")
-                        )
+                self._scan(haystack, "<commit>", sha[:9], findings)
+        if "tags" in self.sources:
+            proc = ws.run([
+                "git", "for-each-ref", "refs/tags",
+                "--format=%(refname)%x00%(contents)",
+            ])
+            blob = proc.stdout or ""
+            if blob.strip():
+                examined_n += 1
+                self._scan(blob, "<tag>", "tag", findings)
+        if "files" in self.sources:
+            tracked = set(ws.tracked_files())
+            for path in self.files:
+                if path not in tracked:
+                    continue
+                examined_n += 1
+                self._scan(ws.read(path), path, path, findings)
         return Result(
             self.id, self._state(findings, examined_n),
             examined_n=examined_n, skipped_n=ws.skipped_n,

{ratch-0.1.2 → ratch-0.1.3}/ratch/checks/bdd_conventions.py

@@ -9,8 +9,10 @@ from ratch.result import Finding, Result, State
 from ratch.testing import FakeWorkspace
 
 
-def _is_bdd_name(name):
-    if name.startswith("test_"):
+def _is_bdd_name(name, prefix):
+    if prefix and not name.startswith(prefix):
+        return None
+    if not prefix and name.startswith("test_"):
         return False
     if "_should_" not in name or "_when_" not in name:
         return False
@@ -37,11 +39,12 @@ class BddTestConventions:
     """Require BDD test names in tracked test modules.
 
     Rule:
-        In tracked tests/*.py, every top-level def whose name does not
-        start with underscore must contain _should_ and _when_, must not
-        start with test_, and must not use or as a snake_case segment.
-        The body must be three blocks separated by two blank lines.
-        Labels such as given/when/then are allowed and ignored.
+        In tracked tests/*.py, selected top-level defs must contain
+        _should_ and _when_ and must not use or as a snake_case segment.
+        prefix="" (this repo) inspects every public def and forbids a
+        test_ prefix. prefix="test_" inspects only that prefix (helpers
+        are ignored). blank_blocks=3 requires two blank-line gaps;
+        blank_blocks=0 skips body shape. Labels are ignored.
 
     Why:
         A test name that reads as a sentence is the readable spec; a
@@ -67,10 +70,12 @@ class BddTestConventions:
     confidence = "inferred"
     tolerates_unparseable = False
 
-    def __init__(self, min_surface=1):
+    def __init__(self, min_surface=1, prefix="", blank_blocks=3):
         if min_surface < 1:
             raise ValueError("min_surface must be >= 1")
         self.min_surface = min_surface
+        self.prefix = prefix
+        self.blank_blocks = blank_blocks
 
     def _state(self, findings, examined_n):
         if findings:
@@ -96,13 +101,16 @@ class BddTestConventions:
                 name = node.name
                 if name.startswith("_"):
                     continue
-                if not _is_bdd_name(name):
+                verdict = _is_bdd_name(name, self.prefix)
+                if verdict is None:
+                    continue
+                if not verdict:
                     findings.append(
                         Finding(self.id, path, name,
                                 message=f"bdd name: {name}")
                     )
                     continue
-                if _paragraph_n(node, lines) < 3:
+                if self.blank_blocks and _paragraph_n(node, lines) < self.blank_blocks:
                     findings.append(
                         Finding(self.id, path, name,
                                 message=f"bdd blank: {name}")

{ratch-0.1.2 → ratch-0.1.3}/ratch/checks/catalog_size.py

@@ -8,8 +8,8 @@ class CatalogSize:
     """Report how many checks are installed, without gating.
 
     Rule:
-        The installed ratch.checks catalog size is reported as a
-        measured value.
+        Reports enabled_n (manifest CHECKS) and catalog_n (entry
+        points) as a measured value.
 
     Why:
         A gate that failed the run because the catalog was empty would
@@ -38,17 +38,24 @@ class CatalogSize:
         self.min_surface = min_surface
 
     def check(self, ws):
-        n = len(ws.plugin_classes())
+        catalog_n = len(ws.plugin_classes())
+        enabled_n = catalog_n
+        root = getattr(ws, "repo_root", None)
+        if root is not None:
+            from ratch.registry import load_manifest
+            enabled_n = len(load_manifest(root))
         measured = MeasuredValue(
-            value=n, state=MState.MEASURED,
+            value=f"enabled_n={enabled_n} catalog_n={catalog_n}",
+            state=MState.MEASURED,
             source="plugin_classes", measured_at=ws.now(),
         )
-        if n < self.min_surface:
+        if catalog_n < self.min_surface:
             state = State.VACUOUS
         else:
             state = State.PASS
         return Result(
-            self.id, state, examined_n=n, findings=[], measured=measured,
+            self.id, state, examined_n=catalog_n, findings=[],
+            measured=measured,
         )
 
     def plants(self, ws):

{ratch-0.1.2 → ratch-0.1.3}/ratch/checks/commit_heatmap.py

@@ -1,4 +1,5 @@
 """commit-heatmap eye: directory groups, file rows, time columns."""
+import os
 from collections import Counter, defaultdict
 from datetime import datetime, timedelta
 
@@ -27,10 +28,14 @@ _GROWTH_STEPS = (
     (316, "#", "@"),
 )
 _GROWTH_CAPTION = (
-    "growth (per-column ins-del, log ladder, not file size; full history)"
+    "growth (per-column ins-del, log ladder, not file size; tracked only)"
 )
 
 
+def _want_compact():
+    return bool(os.environ.get("RATCH_COMPACT"))
+
+
 def _top_dir(path):
     if "/" not in path:
         return "(root)"
@@ -242,11 +247,14 @@ class CommitHeatmap:
         touch_dir_n = Counter()
         touch_file_n = Counter()
         grow_file_n = Counter()
+        tracked = set(ws.tracked_files())
         for ts, files in commits:
             col = _bucket_key(ts, grain)
             if col not in retained:
                 continue
             for path, ins, dele in files:
+                if path not in tracked:
+                    continue
                 top = _top_dir(path)
                 touch_dir[(top, col)] += 1
                 touch_dir_n[top] += 1
@@ -273,8 +281,15 @@ class CommitHeatmap:
             _GROWTH_CAPTION, grow_dir, grow_file, dirs,
             _group(dirs, grow_files), cols, _growth_char,
         ))
+        if _want_compact():
+            value = (
+                f"tracked-only commits={n} dirs={len(dirs)} "
+                f"files={len(touch_files)}"
+            )
+        else:
+            value = "\n".join(lines)
         measured = MeasuredValue(
-            value="\n".join(lines),
+            value=value,
             state=MState.MEASURED,
             source="git_log:numstat",
             measured_at=ws.now(),
@@ -292,7 +307,11 @@ class CommitHeatmap:
 
     def fixture(self, kit):
         return FakeWorkspace(
-            files={"a.py": "x = 1\n"},
+            files={
+                "a.py": "x = 1\n",
+                "ratch/checks/a.py": "x = 1\n",
+                "tests/t.py": "x = 1\n",
+            },
             git_log_text=(
                 "\x1e1700000000\n"
                 "12\t0\tratch/checks/a.py\n"

{ratch-0.1.2 → ratch-0.1.3}/ratch/checks/font_cdn.py

@@ -49,7 +49,7 @@ class NoExternalFontCdn:
         if findings:
             return State.FAIL
         if examined_n < self.min_surface:
-            return State.VACUOUS
+            return State.NOT_APPLICABLE
         return State.PASS
 
     def check(self, ws):

{ratch-0.1.2 → ratch-0.1.3}/ratch/cli.py

@@ -5,6 +5,7 @@ Only check builds a Workspace and a Runner (and may request nicing).
 """
 import argparse
 import inspect
+import os
 import pathlib
 import sys
 
@@ -21,6 +22,7 @@ def build_parser():
     sub = parser.add_subparsers(dest="command", required=True)
     check = sub.add_parser("check")
     check.add_argument("--staged", action="store_true")
+    check.add_argument("--compact", action="store_true")
     sub.add_parser("list")
     describe = sub.add_parser("describe")
     describe.add_argument("id")
@@ -57,6 +59,8 @@ def main(argv=None):
     if args.command == "describe":
         return cmd_describe(args.id)
 
+    if args.compact:
+        os.environ["RATCH_COMPACT"] = "1"
     view = "index" if args.staged else "worktree"
     ws = Workspace(cwd, view)
     checks = load_manifest(cwd)

{ratch-0.1.2 → ratch-0.1.3}/ratch/registry.py

@@ -9,8 +9,6 @@ import importlib.metadata
 import importlib.util
 import pathlib
 
-from ratch.checks.forbidden_literal import NoForbiddenLiteral
-
 __all__ = ["discover", "load_manifest"]
 
 
@@ -21,16 +19,18 @@ def discover():
 
 
 def load_manifest(repo_root):
-    """Return the check instances a repo declares, or the default gate.
+    """Return the check instances a repo declares, or an empty list.
 
-    A repo opts into a custom check set by exposing a CHECKS list from a
-    ratch_checks.py module at its root; absent that file, the default
-    surface is the single forbidden-literal gate.
+    A repo opts into checks by exposing CHECKS from ratch_checks.py at
+    its root. Absent that file, nothing runs: a silent default gate
+    would scan product names in consumer READMEs.
     """
     manifest = pathlib.Path(repo_root) / "ratch_checks.py"
-    if manifest.is_file():
-        spec = importlib.util.spec_from_file_location("ratch_checks", manifest)
-        module = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(module)
-        return list(module.CHECKS)
-    return [NoForbiddenLiteral()]
+    if not manifest.is_file():
+        return []
+    spec = importlib.util.spec_from_file_location("ratch_checks", manifest)
+    if spec is None or spec.loader is None:
+        return []
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return list(module.CHECKS)

{ratch-0.1.2 → ratch-0.1.3}/ratch/runner.py

@@ -39,6 +39,8 @@ def derive_state(raw, examined_n, unparseable_n, tolerates_unparseable,
     """
     if raw is State.ERROR:
         return State.ERROR
+    if raw is State.NOT_APPLICABLE:
+        return State.NOT_APPLICABLE
     if unparseable_n > 0 and not tolerates_unparseable:
         return State.FAIL
     if findings:

{ratch-0.1.2 → ratch-0.1.3/ratch.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ratch
-Version: 0.1.2
+Version: 0.1.3
 Summary: The ratchet only turns one way: code is the single source of truth.
 License: Apache-2.0
 Requires-Python: >=3.11

{ratch-0.1.2 → ratch-0.1.3}/tests/test_ai_signatures.py

@@ -68,7 +68,7 @@ def no_ai_signatures_should_pass_when_history_carries_no_attribution_shape():
     assert result.findings == []
 
 
-def no_ai_signatures_should_be_vacuous_when_the_repo_is_shallow():
+def no_ai_signatures_should_fail_when_the_repo_is_shallow():
     sha = "deadbeef0badf00d"
     trailer = "feat: x\n\nCo-Authored-By: Bot <bot@example.test>\n"
     ws = FakeWorkspace(
@@ -80,9 +80,8 @@ def no_ai_signatures_should_be_vacuous_when_the_repo_is_shallow():
 
     result = NoAiSignatures().check(ws)
 
-    assert result.state is State.VACUOUS
-    assert result.examined_n == 0
-    assert result.findings == []
+    assert result.state is State.FAIL
+    assert any(f.anchor == "shallow" for f in result.findings)
 
 
 def no_ai_signatures_should_fail_when_trailer_uses_github_lowercase_casing():

{ratch-0.1.2 → ratch-0.1.3}/tests/test_bdd_conventions.py

@@ -114,3 +114,25 @@ def bdd_test_conventions_should_be_discoverable_when_registered_as_an_entry_poin
     expected = BddTestConventions
 
     assert found is expected
+
+
+def bdd_test_conventions_should_ignore_helpers_when_prefix_is_test_():
+    src = (
+        "def make_toml():\n    return 1\n"
+        "def test_foo_should_bar_when_baz():\n"
+        "    x = 1\n\n    y = 2\n\n    assert x\n"
+    )
+    ws = FakeWorkspace(files={"tests/t.py": src})
+
+    result = BddTestConventions(prefix="test_").check(ws)
+
+    assert result.state is State.PASS
+
+
+def bdd_test_conventions_should_skip_body_shape_when_blank_blocks_is_zero():
+    src = "def foo_should_bar_when_baz():\n    x = 1\n    assert x\n"
+    ws = FakeWorkspace(files={"tests/t.py": src})
+
+    result = BddTestConventions(blank_blocks=0).check(ws)
+
+    assert result.state is State.PASS

{ratch-0.1.2 → ratch-0.1.3}/tests/test_catalog_size.py

@@ -18,7 +18,7 @@ def catalog_size_should_pass_when_the_workspace_has_plugins():
 
     assert result.state is State.PASS
     assert result.measured is not None
-    assert result.measured.value == 1
+    assert "catalog_n=1" in str(result.measured.value)
     assert result.measured.state is MState.MEASURED
 
 

{ratch-0.1.2 → ratch-0.1.3}/tests/test_cli.py

@@ -5,10 +5,18 @@ from ratch.cli import main
 from ratch.registry import discover
 from ratch.testing import make_tmp_repo
 
+_MANIFEST = (
+    "from ratch.checks.forbidden_literal import NoForbiddenLiteral\n"
+    "CHECKS = [NoForbiddenLiteral()]\n"
+)
+
 
 def main_should_return_one_when_the_repo_has_a_violation(tmp_path, monkeypatch):
     banned = "cl" + "aude"
-    repo = make_tmp_repo(tmp_path, {"pkg/mod.py": f'MARK = "{banned}"\n'})
+    repo = make_tmp_repo(tmp_path, {
+        "pkg/mod.py": f'MARK = "{banned}"\n',
+        "ratch_checks.py": _MANIFEST,
+    })
     monkeypatch.chdir(repo)
     monkeypatch.setattr(os, "nice", lambda n: None)
 
@@ -18,7 +26,10 @@ def main_should_return_one_when_the_repo_has_a_violation(tmp_path, monkeypatch):
 
 
 def main_should_return_zero_when_the_repo_is_clean(tmp_path, monkeypatch):
-    repo = make_tmp_repo(tmp_path, {"pkg/mod.py": "MARK = 'clean'\n"})
+    repo = make_tmp_repo(tmp_path, {
+        "pkg/mod.py": "MARK = 'clean'\n",
+        "ratch_checks.py": _MANIFEST,
+    })
     monkeypatch.chdir(repo)
     monkeypatch.setattr(os, "nice", lambda n: None)
 
@@ -51,7 +62,7 @@ def main_should_list_discovered_plugins_when_invoked_with_list(
         assert line == f"{name:<{width}}{label}"
         labels[name] = label
     assert set(labels.values()) <= {"enabled", "catalog"}
-    assert labels["no-forbidden-literal"] == "enabled"
+    assert labels["no-forbidden-literal"] == "catalog"
     assert labels["no-external-font-cdn"] == "catalog"
 
 

{ratch-0.1.2 → ratch-0.1.3}/tests/test_commit_heatmap.py

@@ -18,7 +18,14 @@ _LOG = (
 
 
 def _ws(log=_LOG):
-    return FakeWorkspace(files={"a.py": "x = 1\n"}, git_log_text=log)
+    return FakeWorkspace(
+        files={
+            "a.py": "x = 1\n",
+            "ratch/checks/a.py": "x = 1\n",
+            "tests/t.py": "x = 1\n",
+        },
+        git_log_text=log,
+    )
 
 
 def parse_log_should_read_insert_and_delete_counts_when_numstat_line_is_plain():

{ratch-0.1.2 → ratch-0.1.3}/tests/test_font_cdn.py

@@ -27,12 +27,12 @@ def no_external_font_cdn_should_pass_when_css_uses_local_fonts():
     assert result.state is State.PASS
 
 
-def no_external_font_cdn_should_be_vacuous_when_no_web_file_is_present():
+def no_external_font_cdn_should_be_not_applicable_when_no_web_file_is_present():
     ws = FakeWorkspace(files={"a.py": "x = 1\n"})
 
     result = NoExternalFontCdn().check(ws)
 
-    assert result.state is State.VACUOUS
+    assert result.state is State.NOT_APPLICABLE
 
 
 def no_external_font_cdn_should_bite_its_plants_when_checked_against_its_own_fixture(tmp_path):

{ratch-0.1.2 → ratch-0.1.3}/tests/test_registry.py

@@ -14,12 +14,12 @@ def discover_should_resolve_no_forbidden_literal_when_the_package_is_installed()
     assert found is expected
 
 
-def load_manifest_should_return_the_default_check_when_no_manifest_exists(tmp_path):
+def load_manifest_should_return_no_checks_when_no_manifest_exists(tmp_path):
     checks = load_manifest(tmp_path)
 
-    assert len(checks) == 1
+    found = len(checks)
 
-    assert isinstance(checks[0], NoForbiddenLiteral)
+    assert found == 0
 
 
 def no_forbidden_literal_should_raise_when_min_surface_is_zero():

{ratch-0.1.2 → ratch-0.1.3}/tests/test_self_host.py

@@ -1,8 +1,8 @@
 """The ratch repo dogfoods every tooth it ships.
 
 load_manifest read at this repo's own root must return the twenty-three ids in
-ratch_checks.py CHECKS, not the single-check default a fresh repo falls
-back to. no-external-font-cdn is shipped as an entry point only.
+ratch_checks.py CHECKS, not the empty default a fresh repo falls back to.
+no-external-font-cdn is shipped as an entry point only.
 """
 import importlib
 

{ratch-0.1.2 → ratch-0.1.3}/tests/test_self_host_blackbox.py

@@ -25,7 +25,13 @@ def _hand_rolled_repo():
         cwd=root, check=True,
     )
     (root / "seed.py").write_text("x = 1\n")
-    subprocess.run(["git", "add", "seed.py"], cwd=root, check=True)
+    (root / "ratch_checks.py").write_text(
+        "from ratch.checks.forbidden_literal import NoForbiddenLiteral\n"
+        "CHECKS = [NoForbiddenLiteral()]\n"
+    )
+    subprocess.run(
+        ["git", "add", "seed.py", "ratch_checks.py"], cwd=root, check=True,
+    )
     subprocess.run(["git", "commit", "-q", "-m", "seed"], cwd=root, check=True)
     return root