ratch 0.1.0__py3-none-any.whl

ratch/__init__.py

@@ -0,0 +1,27 @@
+"""ratch — a ratchet for repository invariants.
+
+Decision: code is the single source of truth (SSOT); docs are pointers,
+generated, or signed. Rejected: a docs/ tree. Because: a copied fact rots.
+"""
+
+from ratch.result import (
+    EXIT,
+    PRECEDENCE,
+    Finding,
+    MeasuredValue,
+    MState,
+    Result,
+    State,
+    run_exit_code,
+)
+
+__all__ = [
+    "EXIT",
+    "PRECEDENCE",
+    "Finding",
+    "MeasuredValue",
+    "MState",
+    "Result",
+    "State",
+    "run_exit_code",
+]

ratch/__main__.py

@@ -0,0 +1,6 @@
+"""Enable 'python -m ratch'."""
+import sys
+
+from ratch.cli import main
+
+sys.exit(main())

ratch/check.py

@@ -0,0 +1,46 @@
+"""The Check contract: the shape every rule instance must present.
+
+A check is configured by instantiation — constructor arguments on the
+instance, never a config file. The runtime-checkable Protocol lets the
+runner accept any object that exposes this shape, keeping rules and the
+engine decoupled.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from ratch.result import Result
+
+if TYPE_CHECKING:
+    # TYPE_CHECKING-only: resolves the Workspace forward reference for
+    # static type checkers; not imported at runtime (no ratch code calls
+    # get_type_hints on these annotations, and this avoids a runtime
+    # import).
+    from ratch.workspace import Workspace
+
+
+@dataclass(frozen=True)
+class Plant:
+    label: str
+    planted_ws: object
+    expected: tuple[str, str, str]
+
+
+@runtime_checkable
+class Check(Protocol):
+    id: str
+    tier: str
+    kind: str
+    scope: str
+    proven_in: tuple[str, ...]
+    confidence: str
+    tolerates_unparseable: bool
+
+    def check(self, ws) -> Result: ...
+
+    def plants(self, ws) -> Iterable[Plant]: ...
+
+    def fixture(self, kit) -> Workspace: ...

ratch/checks/__init__.py

@@ -0,0 +1,7 @@
+"""Shipped check plugins. Discovery is via entry points, not this module."""
+
+
+def is_test_py(path):
+    return path.endswith(".py") and (
+        path.startswith("tests/") or "/tests/" in path
+    )

ratch/checks/ai_signatures.py

@@ -0,0 +1,125 @@
+"""No-AI-signatures check."""
+from __future__ import annotations
+
+import re
+from subprocess import CompletedProcess
+
+from ratch.check import Plant
+from ratch.result import Finding, Result, State
+from ratch.testing import FakeWorkspace
+
+
+def _log_text(commits):
+    """Render commits exactly as ws.git_log(fmt=...) would: each commit is
+    ``sha\\0an\\0ae\\0cn\\0ce\\0body\\0`` and git joins records with ``\\n``."""
+    recs = ["\x00".join(c) + "\x00" for c in commits]
+    return "\n".join(recs) + "\n"
+
+
+class NoAiSignatures:
+    """Forbid AI-attribution shapes anywhere in the full commit history.
+
+    Rule:
+        No commit message or committer/author identity, across the entire
+        reachable history, may match any configured attribution shape.
+
+    Why:
+        An AI attribution trailer or bot identity is a provenance leak that
+        survives squash and rebase; only a scan of the whole history proves
+        its absence, and a shallow clone that hides history must not read as
+        clean.
+
+    Proven in:
+        agent-runner/tests/invariants/test_no_ai_signatures.py
+
+    Not this:
+        Not a judgment on who or what wrote the code. Only fixed attribution
+        SHAPES are rejected; authorship, naming, and content are untouched.
+    """
+
+    id = "no-ai-signatures"
+    tier = "A"
+    kind = "gate"
+    scope = "global"
+    proven_in = ("agent-runner/tests/invariants/test_no_ai_signatures.py",)
+    confidence = "breadth"
+    tolerates_unparseable = False
+
+    def __init__(self, patterns=(
+        r"Co-Authored-By:",
+        r"Generated with",
+        r"Assisted by",
+        "\N{ROBOT FACE}",
+        r"[\w.+-]+@users\.noreply\.[\w.]+",
+    ), min_surface=1):
+        if min_surface < 1:
+            raise ValueError("min_surface must be >= 1")
+        self.patterns = tuple(patterns)
+        self.min_surface = min_surface
+
+    def _state(self, findings, examined_n):
+        if findings:
+            return State.FAIL
+        if examined_n < self.min_surface:
+            return State.VACUOUS
+        return State.PASS
+
+    def _is_shallow(self, ws):
+        proc = ws.run(["git", "rev-parse", "--is-shallow-repository"])
+        return proc.stdout.strip() == "true"
+
+    def check(self, ws):
+        findings = []
+        examined_n = 0
+        if not self._is_shallow(ws):
+            raw = ws.git_log(
+                rng=None,
+                fmt="%H%x00%an%x00%ae%x00%cn%x00%ce%x00%B%x00",
+            )
+            fields = raw.split("\x00")
+            for i in range(0, len(fields) - 5, 6):
+                sha = fields[i].strip()
+                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}")
+                        )
+        return Result(
+            self.id, self._state(findings, examined_n),
+            examined_n=examined_n, skipped_n=ws.skipped_n,
+            unparseable_n=0, findings=findings,
+        )
+
+    def plants(self, ws):
+        sha = "0f1e2d3c4b5a6978"
+        bot = "".join(["c", "l", "a", "u", "d", "e"])  # vendor token, never typed whole
+        body = f"feat: thing\n\nCo-Authored-By: {bot} <{bot}-bot@example.test>\n"
+        planted = FakeWorkspace(
+            files={"ok.py": "x = 1\n"},
+            run_table={("git", "rev-parse", "--is-shallow-repository"):
+                       CompletedProcess([], 0, stdout="false\n")},
+            git_log_text=_log_text([(sha, "Dev", "dev@example.test",
+                                     "Dev", "dev@example.test", body)]),
+        )
+        yield Plant(
+            label="commit:co-authored-by",
+            planted_ws=planted,  # type: ignore[arg-type]
+            expected=(self.id, "<commit>", f"{sha[:9]}:Co-Authored-By:"),
+        )
+
+    def fixture(self, kit):
+        return FakeWorkspace(
+            files={"clean.py": "x = 1\n"},
+            run_table={("git", "rev-parse", "--is-shallow-repository"):
+                       CompletedProcess([], 0, stdout="false\n")},
+            git_log_text=_log_text([("feedface12345678", "Dev", "dev@example.test",
+                                     "Dev", "dev@example.test", "feat: initial\n")]),
+        )

ratch/checks/bdd_conventions.py

@@ -0,0 +1,108 @@
+"""BDD test-naming check."""
+from __future__ import annotations
+
+import ast
+
+from ratch.check import Plant
+from ratch.checks import is_test_py
+from ratch.result import Finding, Result, State
+from ratch.testing import FakeWorkspace
+
+
+def _is_bdd_name(name):
+    if name.startswith("test_"):
+        return False
+    if "_should_" not in name or "_when_" not in name:
+        return False
+    return "or" not in name.split("_")
+
+
+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.
+
+    Why:
+        A test name that reads as a sentence is the readable spec; a
+        machine can prove the shape so pytest collection and review
+        share one convention.
+
+    Proven in:
+        internal/pillar-1-teeth.md
+
+    Not this:
+        Not a requirement on private helpers. Not a ban on tokens that
+        merely contain the letters o-r (error, format). Not a change to
+        pytest python_functions.
+    """
+
+    id = "bdd-test-conventions"
+    tier = "A"
+    kind = "gate"
+    scope = "global"
+    proven_in = ("internal/pillar-1-teeth.md",)
+    confidence = "inferred"
+    tolerates_unparseable = False
+
+    def __init__(self, min_surface=1):
+        if min_surface < 1:
+            raise ValueError("min_surface must be >= 1")
+        self.min_surface = min_surface
+
+    def _state(self, findings, examined_n):
+        if findings:
+            return State.FAIL
+        if examined_n < self.min_surface:
+            return State.VACUOUS
+        return State.PASS
+
+    def check(self, ws):
+        findings = []
+        examined_n = 0
+        for path in ws.tracked_files():
+            if not is_test_py(path):
+                continue
+            examined_n += 1
+            tree = ws.ast(path)
+            if tree is None:
+                continue
+            for node in tree.body:
+                if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    continue
+                name = node.name
+                if name.startswith("_"):
+                    continue
+                if not _is_bdd_name(name):
+                    findings.append(
+                        Finding(self.id, path, name,
+                                message=f"bdd name: {name}")
+                    )
+        return Result(
+            self.id, self._state(findings, examined_n),
+            examined_n=examined_n, skipped_n=ws.skipped_n,
+            unparseable_n=ws.unparseable_n, findings=findings,
+        )
+
+    def plants(self, ws):
+        yield Plant(
+            label="test-prefix",
+            planted_ws=FakeWorkspace(
+                files={"tests/t.py": "def test_foo():\n    pass\n"}
+            ),
+            expected=(self.id, "tests/t.py", "test_foo"),
+        )
+        yield Plant(
+            label="or-segment",
+            planted_ws=FakeWorkspace(
+                files={"tests/t.py": "def foo_should_pass_or_fail_when_x():\n    pass\n"}
+            ),
+            expected=(self.id, "tests/t.py", "foo_should_pass_or_fail_when_x"),
+        )
+
+    def fixture(self, kit):
+        return FakeWorkspace(
+            files={"tests/t.py": "def foo_should_bar_when_baz():\n    pass\n"}
+        )

ratch/checks/catalog_size.py

@@ -0,0 +1,64 @@
+"""catalog-size eye."""
+from ratch.check import Plant
+from ratch.result import MeasuredValue, MState, Result, State
+from ratch.testing import FakeWorkspace
+
+
+class CatalogSize:
+    """Report how many checks are installed, without gating.
+
+    Rule:
+        The installed ratch.checks catalog size is reported as a
+        measured value.
+
+    Why:
+        A gate that failed the run because the catalog was empty would
+        confuse absence of plugins with a rule break; an eye only
+        measures.
+
+    Proven in:
+        internal/specs/2026-09-17-ratchet-v1-spine-design.md
+
+    Not this:
+        Not a gate. VACUOUS on an empty catalog does not fail the run.
+    """
+
+    id = "catalog-size"
+    tier = "A"
+    kind = "eye"
+    scope = "global"
+    proven_in = ("internal/specs/2026-09-17-ratchet-v1-spine-design.md",)
+    confidence = "inferred"
+    tolerates_unparseable = False
+
+    def __init__(self, min_surface=1):
+        if min_surface < 1:
+            raise ValueError("min_surface must be >= 1")
+        self.min_surface = min_surface
+
+    def check(self, ws):
+        n = len(ws.plugin_classes())
+        measured = MeasuredValue(
+            value=n, state=MState.MEASURED,
+            source="plugin_classes", measured_at=ws.now(),
+        )
+        if n < self.min_surface:
+            state = State.VACUOUS
+        else:
+            state = State.PASS
+        return Result(
+            self.id, state, examined_n=n, findings=[], measured=measured,
+        )
+
+    def plants(self, ws):
+        yield Plant(
+            label="empty-catalog",
+            planted_ws=FakeWorkspace(files={"a.py": "x = 1\n"}, plugin_classes={}),
+            expected=(self.id, "catalog", "0"),
+        )
+
+    def fixture(self, kit):
+        return FakeWorkspace(
+            files={"a.py": "x = 1\n"},
+            plugin_classes={"no-forbidden-literal": object},
+        )

ratch/checks/circular_import.py

@@ -0,0 +1,120 @@
+"""No-circular-import check."""
+from __future__ import annotations
+
+import pathlib
+import sys
+import tempfile
+
+from ratch.check import Plant
+from ratch.result import Finding, Result, State
+from ratch.workspace import Workspace
+
+_CYCLE_SIGNATURES = ("partially initialized module", "circular import")
+
+
+def _strip_trailing_path(line):
+    """Drop CPython's trailing ``(/abs/path/mod.py)`` from an ImportError line.
+
+    That path varies by machine and tmp dir; removing it makes the anchor
+    deterministic so a planted cycle yields a stable finding identity.
+    """
+    if line.endswith(")"):
+        open_at = line.rfind(" (")
+        if open_at != -1 and "/" in line[open_at:]:
+            return line[:open_at].rstrip()
+    return line
+
+
+def _cycle_line(stderr):
+    lines = [ln.strip() for ln in stderr.splitlines() if ln.strip()]
+    for line in reversed(lines):
+        if any(sig in line for sig in _CYCLE_SIGNATURES):
+            return _strip_trailing_path(line)
+    return lines[-1] if lines else ""
+
+
+def _write_package(root, name, modules):
+    pkg = pathlib.Path(root) / name
+    pkg.mkdir(parents=True, exist_ok=True)
+    for mod_name, text in modules.items():
+        (pkg / mod_name).write_text(text)
+    return pkg
+
+
+class NoCircularImport:
+    """Forbid a package that cannot be imported because of an import cycle.
+
+    Rule:
+        Importing the configured top-level package in a fresh interpreter
+        must not raise a CPython circular-import error.
+
+    Why:
+        A cycle imports clean in one entry order and explodes in another, so
+        it hides until a production import path hits the bad order; a
+        subprocess import proves the package loads on every commit, where an
+        in-process import would be masked by an already-populated sys.modules.
+
+    Proven in:
+        argus-gateway/tests/test_invariant_no_circular_import.py
+
+    Not this:
+        Not a static import-graph analysis and not a style rule. Only an
+        actual interpreter cycle FAILs; a missing dependency or any other
+        import error is reported as ERROR (could-not-measure), never FAIL.
+        The subprocess import runs against the checked-out worktree, not
+        the index, because Workspace.run always uses repo_root as cwd.
+    """
+
+    id = "no-circular-import"
+    tier = "A"
+    kind = "gate"
+    scope = "global"
+    proven_in = ("argus-gateway/tests/test_invariant_no_circular_import.py",)
+    confidence = "portable-with-config"
+    tolerates_unparseable = False
+    min_surface = 1
+
+    def __init__(self, package, interpreter=None):
+        self.package = package
+        self.interpreter = interpreter
+
+    def check(self, ws):
+        interp = self.interpreter or sys.executable
+        proc = ws.run([interp, "-c", f"import {self.package}"])
+        if proc.returncode == 0:
+            return Result(self.id, State.PASS, examined_n=1)
+        stderr = proc.stderr or ""
+        if any(sig in stderr for sig in _CYCLE_SIGNATURES):
+            anchor = _cycle_line(stderr)
+            return Result(
+                self.id, State.FAIL, examined_n=1,
+                findings=[Finding(self.id, self.package, anchor,
+                                  message=f"circular import: {anchor}")],
+            )
+        return Result(self.id, State.ERROR, examined_n=0)
+
+    def plants(self, ws):
+        root = pathlib.Path(tempfile.mkdtemp(prefix="ratch-circ-"))
+        _write_package(root, self.package, {
+            "__init__.py": f"from {self.package} import a\n",
+            "a.py": f"from {self.package}.b import beta\n\nalpha = 1\n",
+            "b.py": f"from {self.package}.a import alpha\n\nbeta = 2\n",
+        })
+        planted = Workspace(root)
+        probe = NoCircularImport(self.package, interpreter=self.interpreter)
+        probed = probe.check(planted)
+        if probed.state is not State.FAIL or not probed.findings:
+            raise AssertionError(
+                f"{self.id}: probe could not reproduce the planted cycle "
+                f"(got {probed.state})")
+        finding = probed.findings[0]
+        yield Plant(
+            label=f"circular:{self.package}",
+            planted_ws=planted,
+            expected=(self.id, self.package, finding.anchor),
+        )
+
+    def fixture(self, kit):
+        root = pathlib.Path(tempfile.mkdtemp(prefix="ratch-circ-clean-"))
+        _write_package(root, self.package, {"__init__.py": "value = 42\n"})
+        return Workspace(root)

ratch/checks/commit_heatmap.py

@@ -0,0 +1,89 @@
+"""commit-heatmap eye, lifted from argus-gateway commit_heatmap hour buckets."""
+from datetime import datetime
+
+from ratch.check import Plant
+from ratch.result import MeasuredValue, MState, Result, State
+from ratch.testing import FakeWorkspace
+
+_MAX_COMMITS = 500
+
+
+def _hour_counts(text):
+    hours = [0] * 24
+    n = 0
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            ts = int(line)
+        except ValueError:
+            continue
+        hours[datetime.fromtimestamp(ts).hour] += 1
+        n += 1
+        if n >= _MAX_COMMITS:
+            break
+    return hours, n
+
+
+class CommitHeatmap:
+    """Report the busiest hour-of-day in recent git history.
+
+    Rule:
+        Recent commit timestamps are bucketed by local hour of day and
+        the peak bucket is reported as a measured value.
+
+    Why:
+        A commit heatmap is a lens on when the repo actually moves;
+        failing the run because Tuesday was quiet would turn a dashboard
+        into a gate. argus-gateway's commit_heatmap is the structure x
+        time tool; this eye keeps only the hour histogram.
+
+    Proven in:
+        argus-gateway/tools/commit_heatmap.py
+
+    Not this:
+        Not the ASCII directory heatmap. Not role filters, --exclude, or
+        depth. Not a gate.
+    """
+
+    id = "commit-heatmap"
+    tier = "A"
+    kind = "eye"
+    scope = "global"
+    proven_in = ("argus-gateway/tools/commit_heatmap.py",)
+    confidence = "depth-once"
+    tolerates_unparseable = False
+
+    def __init__(self, min_surface=1):
+        if min_surface < 1:
+            raise ValueError("min_surface must be >= 1")
+        self.min_surface = min_surface
+
+    def check(self, ws):
+        hours, n = _hour_counts(ws.git_log(fmt="%at"))
+        if n < self.min_surface:
+            return Result(self.id, State.VACUOUS, examined_n=n, findings=[])
+        peak_hour = max(range(24), key=lambda hour: hours[hour])
+        measured = MeasuredValue(
+            value=f"{peak_hour}h:{hours[peak_hour]}/{n}",
+            state=MState.MEASURED,
+            source="git_log:%at",
+            measured_at=ws.now(),
+        )
+        return Result(
+            self.id, State.PASS, examined_n=n, findings=[], measured=measured,
+        )
+
+    def plants(self, ws):
+        yield Plant(
+            label="empty-log",
+            planted_ws=FakeWorkspace(files={"a.py": "x = 1\n"}, git_log_text=""),
+            expected=(self.id, "git_log", "0"),
+        )
+
+    def fixture(self, kit):
+        return FakeWorkspace(
+            files={"a.py": "x = 1\n"},
+            git_log_text="1700000000\n1700003600\n",
+        )

ratch/checks/conflict_markers.py

@@ -0,0 +1,79 @@
+"""No-conflict-markers check."""
+from __future__ import annotations
+
+from ratch.check import Plant
+from ratch.result import Finding, Result, State
+from ratch.testing import FakeWorkspace
+
+_START = "<" * 7
+_END = ">" * 7
+
+
+class NoConflictMarkers:
+    """Forbid leftover git conflict markers in tracked files.
+
+    Rule:
+        No tracked file may contain a line whose stripped prefix is the
+        seven-character git conflict start or end marker.
+
+    Why:
+        A leftover conflict marker is an unfinished merge that no
+        reviewer reliably catches by eye; a machine can prove absence
+        on every commit.
+
+    Proven in:
+        internal/pillar-1-teeth.md
+
+    Not this:
+        Not a Markdown rule. A setext underline of equals signs is
+        allowed; only the git start and end markers are rejected.
+    """
+
+    id = "no-conflict-markers"
+    tier = "A"
+    kind = "gate"
+    scope = "global"
+    proven_in = ("internal/pillar-1-teeth.md",)
+    confidence = "inferred"
+    tolerates_unparseable = False
+
+    def __init__(self, min_surface=1):
+        if min_surface < 1:
+            raise ValueError("min_surface must be >= 1")
+        self.min_surface = min_surface
+
+    def _state(self, findings, examined_n):
+        if findings:
+            return State.FAIL
+        if examined_n < self.min_surface:
+            return State.VACUOUS
+        return State.PASS
+
+    def check(self, ws):
+        findings = []
+        examined_n = 0
+        for path in ws.tracked_files():
+            examined_n += 1
+            for line in ws.read(path).splitlines():
+                stripped = line.lstrip()
+                if stripped.startswith((_START, _END)):
+                    anchor = " ".join(line.split())
+                    findings.append(
+                        Finding(self.id, path, anchor,
+                                message=f"conflict marker: {anchor}")
+                    )
+        return Result(
+            self.id, self._state(findings, examined_n),
+            examined_n=examined_n, skipped_n=ws.skipped_n, findings=findings,
+        )
+
+    def plants(self, ws):
+        line = _START + " HEAD"
+        yield Plant(
+            label="start-marker",
+            planted_ws=FakeWorkspace(files={"a.py": line + "\nx = 1\n"}),
+            expected=(self.id, "a.py", line),
+        )
+
+    def fixture(self, kit):
+        return FakeWorkspace(files={"a.py": "x = 1\n"})