ratch 0.1.0__tar.gz → 0.1.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ratch
-Version: 0.1.0
+Version: 0.1.2
 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/README.md

@@ -0,0 +1,72 @@
+> **[中文](README.zh.md)** · English
+
+# ratch
+
+[![ci](https://github.com/wan9yu/ratch/actions/workflows/ci.yml/badge.svg)](https://github.com/wan9yu/ratch/actions/workflows/ci.yml)
+
+<!-- ratch:authored -->
+A written team agreement works when people keep it. An agent does not
+share that embarrassment. Prompts and policy files are not deterministic.
+ratch is the extreme-programming form of the agreement: a good practice
+pushed until git can re-prove it on every commit. Git author metadata no
+longer names which agent made the commit.
+
+Install with `pip install ratch`. Put a `ratch_checks.py` at the
+repository root (see `examples/ratch_checks.py`). Run
+`python -m ratch check`. Gates that fail exit non-zero. Eyes print and
+never change the exit code. `ratch list` and `ratch describe no-forbidden-literal` show the
+catalog; they do not run checks.
+
+This repository is gated by its own root `ratch_checks.py`. `./build.sh`
+and CI install, run pytest, then `ratch check`.
+
+**Provenance** — commit identity is no longer a person:
+
+- `no-forbidden-literal` — author-tool tokens in content, paths, or the tip commit
+- `no-first-person` — record prose without first-person voice
+- `no-ai-signatures` — attribution trailers that survive rebase
+
+**Debris agents leave in the tree:**
+
+- `no-conflict-markers` — unfinished merge markers
+- `no-vacuous-assert` — `assert True` / `assert False` placeholders
+- `no-pytest-skip` — skipped tests that read green
+- `no-hash-named-test` — test files named with a forgotten hex suffix
+- `todo-has-issue-ref` — debt markers without an issue citation
+- `bdd-test-conventions` — test names that read as a sentence; two blank lines split the body into three blocks
+- `no-circular-import` — a package that only imports in one order
+- `no-reassurance-words` — prose that tells the reader to stop checking
+- `loc-cap` — Python modules over 1000 lines
+- `no-external-font-cdn` — shipped HTML/CSS/JS fetching remote webfonts
+
+**The agreement must apply to the agreement:**
+
+- `plugin-registry` — every plugin has plants, fixture, and headings
+- `manifest-purity` — `ratch_checks.py` is importable and repeatable
+- `no-internal-refs` — no pointers into a gitignored notes tree
+- `doc-counts-match-ssot` — README `catalog_n` equals `discover()`
+- `docs-equal-fresh-render` — the generated region matches a live render
+- `tests-repo-root-ssot` — tests import one ROOT helper, not Path(__file__) walks
+- `injected-clock` — raw time.time only if a Clock type exists
+- `doc-cli-examples-valid` — documented ratch commands parse
+- `no-autoclose-keywords-in-commits` — commit messages that would auto-close issues
+
+**Eyes** — evidence, never a failed run:
+
+- `catalog-size` — how many plugins are installed
+- `commit-heatmap` — directory-grouped file × time touches and numstat growth
+
+ratch will never gate on judgment. It does not score, grade, or block on:
+
+- naming quality
+- abstraction quality
+- prose quality (including commit-message quality)
+- test meaningfulness
+
+Those calls belong to review by people. ratch gates only what a machine
+can prove.
+<!-- ratch:authored:end -->
+
+<!-- ratch:generated:checks -->
+catalog_n=24
+<!-- ratch:generated:checks:end -->

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ratch"
-version = "0.1.0"
+version = "0.1.2"
 description = "The ratchet only turns one way: code is the single source of truth."
 license = {text = "Apache-2.0"}
 requires-python = ">=3.11"
@@ -36,6 +36,13 @@ doc-counts-match-ssot = "ratch.checks.doc_counts:DocCountsMatchSSot"
 docs-equal-fresh-render = "ratch.checks.docs_render:DocsEqualFreshRender"
 catalog-size = "ratch.checks.catalog_size:CatalogSize"
 commit-heatmap = "ratch.checks.commit_heatmap:CommitHeatmap"
+no-internal-refs = "ratch.checks.internal_refs:NoInternalRefs"
+no-reassurance-words = "ratch.checks.reassurance:NoReassuranceWords"
+tests-repo-root-ssot = "ratch.checks.repo_root_ssot:RepoRootSSot"
+loc-cap = "ratch.checks.loc_cap:LocCap"
+injected-clock = "ratch.checks.injected_clock:InjectedClock"
+doc-cli-examples-valid = "ratch.checks.doc_cli:DocCliExamplesValid"
+no-autoclose-keywords-in-commits = "ratch.checks.autoclose:NoAutocloseKeywords"
 
 [tool.setuptools.packages.find]
 include = ["ratch*"]

ratch-0.1.2/ratch/checks/__init__.py

@@ -0,0 +1,32 @@
+"""Shipped check plugins. Discovery is via entry points, not this module."""
+import fnmatch
+
+
+def is_test_py(path):
+    return path.endswith(".py") and (
+        path.startswith("tests/") or "/tests/" in path
+    )
+
+
+def match_globs(path, globs):
+    """True if globs is None or path matches any glob (``**`` = any dirs)."""
+    if globs is None:
+        return True
+    return any(_match_one(path, pattern) for pattern in globs)
+
+
+def _match_one(path, pattern):
+    if fnmatch.fnmatch(path, pattern):
+        return True
+    if "**" not in pattern:
+        return False
+    head, tail = pattern.split("**", 1)
+    prefix = head.rstrip("/")
+    suffix = tail.lstrip("/")
+    if prefix and path != prefix and not path.startswith(prefix + "/"):
+        return False
+    rest = path[len(prefix):].lstrip("/") if prefix else path
+    if not suffix:
+        return True
+    base = rest.rsplit("/", 1)[-1]
+    return fnmatch.fnmatch(rest, suffix) or fnmatch.fnmatch(base, suffix)

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

@@ -30,7 +30,9 @@ class NoAiSignatures:
         clean.
 
     Proven in:
-        agent-runner/tests/invariants/test_no_ai_signatures.py
+        A full-history scan of attribution trailers (Co-Authored-By,
+        Generated with, Assisted by, robot glyph, noreply addresses);
+        a shallow clone must not read as clean.
 
     Not this:
         Not a judgment on who or what wrote the code. Only fixed attribution
@@ -41,7 +43,7 @@ class NoAiSignatures:
     tier = "A"
     kind = "gate"
     scope = "global"
-    proven_in = ("agent-runner/tests/invariants/test_no_ai_signatures.py",)
+    proven_in = ()
     confidence = "breadth"
     tolerates_unparseable = False
 

ratch-0.1.2/ratch/checks/autoclose.py

@@ -0,0 +1,83 @@
+"""no-autoclose-keywords-in-commits check."""
+import re
+
+from ratch.check import Plant
+from ratch.result import Finding, Result, State
+from ratch.testing import FakeWorkspace
+
+_RX = re.compile(
+    r"\b(?:fix(?:es|ed)?|close(?:s|d)?|resolve(?:s|d)?)\s+#\d+",
+    re.IGNORECASE,
+)
+
+
+class NoAutocloseKeywords:
+    """Forbid GitHub auto-close phrases in commit messages.
+
+    Rule:
+        git log subjects and bodies must not match fix/close/resolve
+        plus a hash-number issue citation.
+
+    Why:
+        Agent-written trailers close issues by accident; the message
+        is the SSOT that GitHub will act on.
+
+    Proven in:
+        git log format subject+body scanned with one regex.
+
+    Not this:
+        Not a ban on citing issues in code comments.
+    """
+
+    id = "no-autoclose-keywords-in-commits"
+    tier = "A"
+    kind = "gate"
+    scope = "global"
+    proven_in = ()
+    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):
+        text = ws.git_log(fmt="%s%n%b%n%x1e")
+        records = [block.strip() for block in text.split("\x1e") if block.strip()]
+        findings = []
+        examined_n = len(records)
+        for block in records:
+            hit = _RX.search(block)
+            if hit:
+                findings.append(
+                    Finding(self.id, "<commit>", hit.group(0),
+                            message=f"autoclose: {hit.group(0)}")
+                )
+        return Result(
+            self.id, self._state(findings, examined_n),
+            examined_n=examined_n, skipped_n=ws.skipped_n, findings=findings,
+        )
+
+    def plants(self, ws):
+        yield Plant(
+            label="fixes",
+            planted_ws=FakeWorkspace(
+                files={"a.py": "x = 1\n"},
+                git_log_text="Fixes #12\n\x1e",
+            ),
+            expected=(self.id, "<commit>", "Fixes #12"),
+        )
+
+    def fixture(self, kit):
+        return FakeWorkspace(
+            files={"a.py": "x = 1\n"},
+            git_log_text="tighten the parser\n\x1e",
+        )

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

@@ -17,6 +17,22 @@ def _is_bdd_name(name):
     return "or" not in name.split("_")
 
 
+def _paragraph_n(node, lines):
+    start = node.lineno
+    end = node.end_lineno or node.lineno
+    body = lines[start:end]
+    groups = 0
+    in_group = False
+    for line in body:
+        if line.strip():
+            if not in_group:
+                groups += 1
+                in_group = True
+        else:
+            in_group = False
+    return groups
+
+
 class BddTestConventions:
     """Require BDD test names in tracked test modules.
 
@@ -24,6 +40,8 @@ class BddTestConventions:
         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.
 
     Why:
         A test name that reads as a sentence is the readable spec; a
@@ -31,7 +49,9 @@ class BddTestConventions:
         share one convention.
 
     Proven in:
-        internal/pillar-1-teeth.md
+        A test name reads as subject_should_outcome_when_condition,
+        with no test_ prefix and no or segment. Two blank lines in the
+        body mark three blocks; no given/when/then labels.
 
     Not this:
         Not a requirement on private helpers. Not a ban on tokens that
@@ -43,7 +63,7 @@ class BddTestConventions:
     tier = "A"
     kind = "gate"
     scope = "global"
-    proven_in = ("internal/pillar-1-teeth.md",)
+    proven_in = ()
     confidence = "inferred"
     tolerates_unparseable = False
 
@@ -69,6 +89,7 @@ class BddTestConventions:
             tree = ws.ast(path)
             if tree is None:
                 continue
+            lines = ws.read(path).splitlines()
             for node in tree.body:
                 if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                     continue
@@ -80,6 +101,12 @@ class BddTestConventions:
                         Finding(self.id, path, name,
                                 message=f"bdd name: {name}")
                     )
+                    continue
+                if _paragraph_n(node, lines) < 3:
+                    findings.append(
+                        Finding(self.id, path, name,
+                                message=f"bdd blank: {name}")
+                    )
         return Result(
             self.id, self._state(findings, examined_n),
             examined_n=examined_n, skipped_n=ws.skipped_n,
@@ -101,8 +128,21 @@ class BddTestConventions:
             ),
             expected=(self.id, "tests/t.py", "foo_should_pass_or_fail_when_x"),
         )
+        body = "\n".join(f"    a{i} = {i}" for i in range(6))
+        yield Plant(
+            label="dense-body",
+            planted_ws=FakeWorkspace(
+                files={"tests/t.py": f"def foo_should_bar_when_baz():\n{body}\n"}
+            ),
+            expected=(self.id, "tests/t.py", "foo_should_bar_when_baz"),
+        )
 
     def fixture(self, kit):
         return FakeWorkspace(
-            files={"tests/t.py": "def foo_should_bar_when_baz():\n    pass\n"}
+            files={"tests/t.py": (
+                "def foo_should_bar_when_baz():\n"
+                "    x = 1\n\n"
+                "    y = 2\n\n"
+                "    assert x\n"
+            )}
         )

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

@@ -17,7 +17,8 @@ class CatalogSize:
         measures.
 
     Proven in:
-        internal/specs/2026-09-17-ratchet-v1-spine-design.md
+        This repository: an eye that reports how many checks are
+        installed, without failing the run.
 
     Not this:
         Not a gate. VACUOUS on an empty catalog does not fail the run.
@@ -27,7 +28,7 @@ class CatalogSize:
     tier = "A"
     kind = "eye"
     scope = "global"
-    proven_in = ("internal/specs/2026-09-17-ratchet-v1-spine-design.md",)
+    proven_in = ()
     confidence = "inferred"
     tolerates_unparseable = False
 

{ratch-0.1.0 → ratch-0.1.2}/ratch/checks/circular_import.py

@@ -55,7 +55,8 @@ class NoCircularImport:
         in-process import would be masked by an already-populated sys.modules.
 
     Proven in:
-        argus-gateway/tests/test_invariant_no_circular_import.py
+        A fresh-interpreter import of the package: CPython cycle
+        strings FAIL; any other import error is ERROR, never FAIL.
 
     Not this:
         Not a static import-graph analysis and not a style rule. Only an
@@ -69,7 +70,7 @@ class NoCircularImport:
     tier = "A"
     kind = "gate"
     scope = "global"
-    proven_in = ("argus-gateway/tests/test_invariant_no_circular_import.py",)
+    proven_in = ()
     confidence = "portable-with-config"
     tolerates_unparseable = False
     min_surface = 1

ratch-0.1.2/ratch/checks/commit_heatmap.py

@@ -0,0 +1,301 @@
+"""commit-heatmap eye: directory groups, file rows, time columns."""
+from collections import Counter, defaultdict
+from datetime import datetime, timedelta
+
+from ratch.check import Plant
+from ratch.result import MeasuredValue, MState, Result, State
+from ratch.testing import FakeWorkspace
+
+_MAX_COMMITS = 500
+_MAX_DIRS = 8
+_MAX_FILES = 24
+_MAX_COLS = 14
+_DENSITY = (
+    (0, " "),
+    (1, "."),
+    (3, ":"),
+    (6, "*"),
+    (11, "+"),
+    (21, "#"),
+)
+# log-ish |net| cutoffs: 10^0, 10^1, ~10^1.5, 10^2, ~10^2.5
+_GROWTH_STEPS = (
+    (1, ".", "o"),
+    (10, ":", "~"),
+    (32, "*", "-"),
+    (100, "+", "="),
+    (316, "#", "@"),
+)
+_GROWTH_CAPTION = (
+    "growth (per-column ins-del, log ladder, not file size; full history)"
+)
+
+
+def _top_dir(path):
+    if "/" not in path:
+        return "(root)"
+    return path.split("/", 1)[0]
+
+
+def _normalize_path(path):
+    if " => " not in path:
+        return path
+    left, right = path.split(" => ", 1)
+    if "{" in left and right.endswith("}"):
+        prefix, _old = left.split("{", 1)
+        return prefix + right[:-1]
+    return right
+
+
+def _parse_stat_line(line):
+    parts = line.split("\t", 2)
+    if len(parts) != 3:
+        return None
+    ins_s, del_s, raw_path = parts
+    path = _normalize_path(raw_path)
+    if ins_s == "-" and del_s == "-":
+        return path, None, None
+    try:
+        return path, int(ins_s), int(del_s)
+    except ValueError:
+        return None
+
+
+def _parse_log(text):
+    commits = []
+    for rec in text.split("\x1e"):
+        lines = [line.strip() for line in rec.splitlines() if line.strip()]
+        if not lines:
+            continue
+        try:
+            ts = int(lines[0])
+        except ValueError:
+            continue
+        files = []
+        for line in lines[1:]:
+            parsed = _parse_stat_line(line)
+            if parsed is not None:
+                files.append(parsed)
+        commits.append((ts, files))
+        if len(commits) >= _MAX_COMMITS:
+            break
+    return commits
+
+
+def _grain(span_hours):
+    if span_hours <= 48:
+        return "hour"
+    if span_hours <= 14 * 24:
+        return "day"
+    return "week"
+
+
+def _bucket_key(ts, grain):
+    dt = datetime.fromtimestamp(ts)
+    if grain == "hour":
+        return dt.strftime("%m-%d %H")
+    if grain == "day":
+        return dt.strftime("%m-%d")
+    year, week, _ = dt.isocalendar()
+    return f"{year}-W{week:02d}"
+
+
+def _bucket_keys(start_ts, end_ts, grain, max_cols=_MAX_COLS):
+    start = datetime.fromtimestamp(start_ts)
+    end = datetime.fromtimestamp(end_ts)
+    if grain == "hour":
+        cursor = start.replace(minute=0, second=0, microsecond=0)
+        step = timedelta(hours=1)
+    elif grain == "day":
+        cursor = start.replace(hour=0, minute=0, second=0, microsecond=0)
+        step = timedelta(days=1)
+    else:
+        cursor = (start - timedelta(days=start.weekday())).replace(
+            hour=0, minute=0, second=0, microsecond=0,
+        )
+        step = timedelta(days=7)
+    keys = []
+    while cursor <= end:
+        keys.append(_bucket_key(cursor.timestamp(), grain))
+        cursor += step
+    return keys[-max_cols:]
+
+
+def _cell_char(n):
+    ch = " "
+    for threshold, glyph in _DENSITY:
+        if n >= threshold:
+            ch = glyph
+    return ch
+
+
+def _growth_char(n):
+    if n == 0:
+        return " "
+    glyph = " "
+    for threshold, pos, neg in _GROWTH_STEPS:
+        if abs(n) >= threshold:
+            if n > 0:
+                glyph = pos
+            else:
+                glyph = neg
+    return glyph
+
+
+def _row(label, key, cols, cell, width, char_fn):
+    cells = "".join(f"{char_fn(cell.get((key, col), 0)):>3}" for col in cols)
+    return f"{label:<{width}} {cells}"
+
+
+def _header(cols, width):
+    return " " * width + " " + "".join(f"{col[-3:]:>3}" for col in cols)
+
+
+def _short(path, width):
+    if len(path) <= width:
+        return path
+    return "..." + path[-(width - 3):]
+
+
+def _render_panel(title, dir_cell, file_cell, dirs, files_by_dir, cols, char_fn):
+    width = 28
+    lines = [title, "dirs", _header(cols, width)]
+    for name in dirs:
+        lines.append(_row(name, name, cols, dir_cell, width, char_fn))
+    lines.append("files")
+    for name in dirs:
+        grouped = files_by_dir.get(name, [])
+        if not grouped:
+            continue
+        lines.append(f"{name}/")
+        for path in grouped:
+            lines.append(
+                _row(_short(path, width), path, cols, file_cell, width, char_fn)
+            )
+    return lines
+
+
+def _group(dirs, ranked_files):
+    files_by_dir = defaultdict(list)
+    allowed = set(dirs)
+    for path in ranked_files:
+        top = _top_dir(path)
+        if top in allowed:
+            files_by_dir[top].append(path)
+    return files_by_dir
+
+
+class CommitHeatmap:
+    """Report a directory-grouped file x time commit heatmap.
+
+    Rule:
+        Recent commits are shown as two panels on the same axes:
+        touch counts, then per-column insert-minus-delete net.
+
+    Why:
+        How often a path moved and how much mass it gained are different
+        facts. Both are git-recomputable; neither is a quality score.
+
+    Proven in:
+        git log --numstat timestamps and paths, folded into a density
+        grid. Directories first, files second, time across. Growth is
+        per-column net, not file size.
+
+    Not this:
+        Not a gate. Not a cumulative stock. Not role inference.
+    """
+
+    id = "commit-heatmap"
+    tier = "A"
+    kind = "eye"
+    scope = "global"
+    proven_in = ()
+    confidence = "depth-once"
+    tolerates_unparseable = False
+
+    def __init__(self, min_surface=1, max_dirs=_MAX_DIRS, max_files=_MAX_FILES):
+        if min_surface < 1:
+            raise ValueError("min_surface must be >= 1")
+        self.min_surface = min_surface
+        self.max_dirs = max_dirs
+        self.max_files = max_files
+
+    def check(self, ws):
+        commits = _parse_log(
+            ws.git_log(
+                fmt="%x1e%at",
+                extra=("--numstat", "-n", str(_MAX_COMMITS)),
+            )
+        )
+        n = len(commits)
+        if n < self.min_surface:
+            return Result(self.id, State.VACUOUS, examined_n=n, findings=[])
+        timestamps = [ts for ts, _files in commits]
+        span = max((max(timestamps) - min(timestamps)) / 3600, 0)
+        grain = _grain(span)
+        cols = _bucket_keys(min(timestamps), max(timestamps), grain)
+        retained = set(cols)
+        touch_dir = defaultdict(int)
+        touch_file = defaultdict(int)
+        grow_dir = defaultdict(int)
+        grow_file = defaultdict(int)
+        touch_dir_n = Counter()
+        touch_file_n = Counter()
+        grow_file_n = Counter()
+        for ts, files in commits:
+            col = _bucket_key(ts, grain)
+            if col not in retained:
+                continue
+            for path, ins, dele in files:
+                top = _top_dir(path)
+                touch_dir[(top, col)] += 1
+                touch_dir_n[top] += 1
+                touch_file[(path, col)] += 1
+                touch_file_n[path] += 1
+                if ins is None:
+                    continue
+                net = ins - dele
+                grow_dir[(top, col)] += net
+                grow_file[(path, col)] += net
+                grow_file_n[path] += net
+        if not touch_dir_n:
+            return Result(self.id, State.VACUOUS, examined_n=n, findings=[])
+        dirs = [name for name, _ in touch_dir_n.most_common(self.max_dirs)]
+        touch_files = [p for p, _ in touch_file_n.most_common(self.max_files)]
+        grow_files = sorted(
+            grow_file_n, key=lambda path: grow_file_n[path], reverse=True,
+        )[: self.max_files]
+        lines = _render_panel(
+            "touches", touch_dir, touch_file, dirs,
+            _group(dirs, touch_files), cols, _cell_char,
+        )
+        lines.extend(_render_panel(
+            _GROWTH_CAPTION, grow_dir, grow_file, dirs,
+            _group(dirs, grow_files), cols, _growth_char,
+        ))
+        measured = MeasuredValue(
+            value="\n".join(lines),
+            state=MState.MEASURED,
+            source="git_log:numstat",
+            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=(
+                "\x1e1700000000\n"
+                "12\t0\tratch/checks/a.py\n"
+                "3\t1\ttests/t.py\n"
+            ),
+        )

{ratch-0.1.0 → ratch-0.1.2}/ratch/checks/conflict_markers.py

@@ -22,7 +22,8 @@ class NoConflictMarkers:
         on every commit.
 
     Proven in:
-        internal/pillar-1-teeth.md
+        Leftover-merge scan: git conflict start and end markers,
+        never Markdown setext underlines.
 
     Not this:
         Not a Markdown rule. A setext underline of equals signs is
@@ -33,7 +34,7 @@ class NoConflictMarkers:
     tier = "A"
     kind = "gate"
     scope = "global"
-    proven_in = ("internal/pillar-1-teeth.md",)
+    proven_in = ()
     confidence = "inferred"
     tolerates_unparseable = False