ratch 0.1.0__py3-none-any.whl

ratch/checks/doc_counts.py

@@ -0,0 +1,111 @@
+"""doc-counts-match-ssot check."""
+import re
+
+from ratch.check import Plant
+from ratch.registry import discover
+from ratch.result import Finding, Result, State
+from ratch.testing import FakeWorkspace
+
+
+def render_checks_region():
+    return f"catalog_n={len(discover())}\n"
+
+
+class Pin:
+    def __init__(self, path, pattern, ssot_key):
+        self.path = path
+        self.pattern = re.compile(pattern)
+        self.ssot_key = ssot_key
+
+
+_DEFAULT_PINS = (
+    Pin("README.md", r"^catalog_n=(\d+)$", "discover_n"),
+)
+
+
+class DocCountsMatchSSot:
+    """Pin a README capture to a runtime catalog count.
+
+    Rule:
+        README.md must contain a catalog_n=N line whose N equals
+        len(discover()).
+
+    Why:
+        A hand-typed catalog size in prose rots the moment a plugin is
+        added; the entry-point catalog is the SSOT.
+
+    Proven in:
+        internal/specs/2026-09-17-ratchet-v1-spine-design.md
+
+    Not this:
+        Not a full README renderer. Not an enabled-set count (that
+        needs a Workspace-aware manifest reader). Not a match scoped
+        only to the generated HTML region.
+    """
+
+    id = "doc-counts-match-ssot"
+    tier = "A"
+    kind = "gate"
+    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, pins=None):
+        if min_surface < 1:
+            raise ValueError("min_surface must be >= 1")
+        self.min_surface = min_surface
+        self.pins = _DEFAULT_PINS if pins is None else pins
+
+    def _state(self, findings, examined_n):
+        if findings:
+            return State.FAIL
+        if examined_n < self.min_surface:
+            return State.VACUOUS
+        return State.PASS
+
+    def _ssot(self, key):
+        if key == "discover_n":
+            return str(len(discover()))
+        raise ValueError(f"unknown ssot_key {key}")
+
+    def check(self, ws):
+        tracked = set(ws.tracked_files())
+        findings = []
+        texts = {}
+        for pin in self.pins:
+            if pin.path not in tracked:
+                continue
+            if pin.path not in texts:
+                texts[pin.path] = ws.read(pin.path)
+            matched = False
+            for line in texts[pin.path].splitlines():
+                hit = pin.pattern.search(line)
+                if hit is None:
+                    continue
+                matched = True
+                if hit.group(1) != self._ssot(pin.ssot_key):
+                    findings.append(
+                        Finding(self.id, pin.path, "catalog_n",
+                                message="catalog_n disagrees with discover()")
+                    )
+            if not matched:
+                findings.append(
+                    Finding(self.id, pin.path, "catalog_n",
+                            message="catalog_n line missing")
+                )
+        return Result(
+            self.id, self._state(findings, len(texts)),
+            examined_n=len(texts), skipped_n=ws.skipped_n, findings=findings,
+        )
+
+    def plants(self, ws):
+        wrong = f"catalog_n={len(discover()) + 1}\n"
+        yield Plant(
+            label="wrong-catalog-n",
+            planted_ws=FakeWorkspace(files={"README.md": wrong}),
+            expected=(self.id, "README.md", "catalog_n"),
+        )
+
+    def fixture(self, kit):
+        return FakeWorkspace(files={"README.md": render_checks_region()})

ratch/checks/docs_render.py

@@ -0,0 +1,87 @@
+"""docs-equal-fresh-render check."""
+from ratch.check import Plant
+from ratch.checks.doc_counts import render_checks_region
+from ratch.result import Finding, Result, State
+from ratch.testing import FakeWorkspace
+
+_START = "<!-- ratch:generated:checks -->"
+_END = "<!-- ratch:generated:checks:end -->"
+_README = "README.md"
+
+
+def _region(text):
+    if _START not in text or _END not in text:
+        return None
+    return text.split(_START, 1)[1].split(_END, 1)[0]
+
+
+class DocsEqualFreshRender:
+    """Require the README generated region to match a fresh render.
+
+    Rule:
+        README.md must contain the generated-checks markers whose inner
+        body equals render_checks_region().
+
+    Why:
+        A catalog_n line that a human typed can still be the wrong
+        shape (extra lines, missing newline). Byte-equal to the live
+        renderer is the SSOT.
+
+    Proven in:
+        internal/specs/2026-09-17-ratchet-v1-spine-design.md
+
+    Not this:
+        Not a rewrite of the authored fence. Not a full README
+        generator. Not an enabled-set count.
+    """
+
+    id = "docs-equal-fresh-render"
+    tier = "A"
+    kind = "gate"
+    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 _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):
+        if _README not in ws.tracked_files():
+            return Result(
+                self.id, self._state([], 0),
+                examined_n=0, skipped_n=ws.skipped_n, findings=[],
+            )
+        body = _region(ws.read(_README))
+        expected = "\n" + render_checks_region()
+        findings = []
+        if body is None or body != expected:
+            findings.append(
+                Finding(self.id, _README, "generated:checks",
+                        message="generated region stale")
+            )
+        return Result(
+            self.id, self._state(findings, 1),
+            examined_n=1, skipped_n=ws.skipped_n, findings=findings,
+        )
+
+    def plants(self, ws):
+        stale = f"{_START}\ncatalog_n=0\n{_END}\n"
+        yield Plant(
+            label="stale-region",
+            planted_ws=FakeWorkspace(files={_README: stale}),
+            expected=(self.id, _README, "generated:checks"),
+        )
+
+    def fixture(self, kit):
+        text = f"{_START}\n{render_checks_region()}{_END}\n"
+        return FakeWorkspace(files={_README: text})

ratch/checks/first_person.py

@@ -0,0 +1,131 @@
+"""No-first-person check."""
+from __future__ import annotations
+
+import fnmatch
+import re
+
+from ratch.check import Plant
+from ratch.result import Finding, Result, State
+from ratch.testing import FakeWorkspace
+
+
+class NoFirstPerson:
+    """Forbid first-person voice in tracked prose.
+
+    Rule:
+        No tracked file matching the configured path globs may contain a
+        first-person pronoun: the English words I, we, our, us as whole
+        words, or the CJK self-reference 我.
+
+    Why:
+        First-person voice binds shipped prose to one author's standpoint
+        where the project must speak with a single impersonal voice; a
+        machine proves the pronoun's absence so no reviewer polices tone
+        by eye on every commit.
+
+    Proven in:
+        kairos/tests/test_invariant_no_self_reference.py
+
+    Not this:
+        Not a grammar, clarity, or readability rule. It never rewrites
+        prose and never judges style; it rejects only an exact pronoun
+        match, and deliberately exempts the "I/O" boundary term and, under
+        the allow-team-we polarity, the collective 我们.
+    """
+
+    id = "no-first-person"
+    tier = "A"
+    kind = "gate"
+    scope = "global"
+    proven_in = ("kairos/tests/test_invariant_no_self_reference.py",)
+    confidence = "breadth"
+    tolerates_unparseable = False
+
+    def __init__(self, polarity="forbid-all", tokens_en=("I", "we", "our", "us"),
+                 tokens_cjk=("我",), paths=("*.md",), min_surface=1):
+        if min_surface < 1:
+            raise ValueError("min_surface must be >= 1")
+        self.polarity = polarity
+        self.paths = tuple(paths)
+        self.min_surface = min_surface
+        # allow-team-we: drop the collective EN pronouns (keep only "I"),
+        # and let the CJK builder exempt 我们.
+        if polarity == "allow-team-we":
+            self.tokens_en = tuple(t for t in tokens_en if t == "I")
+        else:
+            self.tokens_en = tuple(tokens_en)
+        self.tokens_cjk = tuple(tokens_cjk)
+        self._en_rx = self._build_en_rx()
+        self._cjk_rx = self._build_cjk_rx()
+
+    def _build_en_rx(self):
+        if not self.tokens_en:
+            return None
+        # Self-host critical (blocking, non-weakenable gate): "I" never matches
+        # inside the I/O boundary term, and NO re.IGNORECASE — IGNORECASE would
+        # bite a lowercase loop variable `i`, `i.e.`, or the acronym `US`.
+        # Match only sentence-case forms: I, We/we, Our/our, Us/us.
+        parts = ["I(?!/O)" if t == "I"
+                 else f"[{t[0].upper()}{t[0]}]{re.escape(t[1:])}"
+                 for t in self.tokens_en]
+        return re.compile(r"\b(?:" + "|".join(parts) + r")\b")
+
+    def _build_cjk_rx(self):
+        if not self.tokens_cjk:
+            return None
+        parts = []
+        for t in self.tokens_cjk:
+            if t == "我" and self.polarity == "allow-team-we":
+                parts.append("我(?!们)")  # allow the collective 我们
+            else:
+                parts.append(re.escape(t))
+        return re.compile("|".join(parts))
+
+    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):
+        files = [p for p in ws.tracked_files()
+                 if any(fnmatch.fnmatch(p, g) for g in self.paths)]
+        findings = []
+        examined_n = 0
+        for path in files:
+            examined_n += 1
+            for lineno, line in enumerate(ws.read(path).splitlines(), start=1):
+                if (self._en_rx and self._en_rx.search(line)) or \
+                   (self._cjk_rx and self._cjk_rx.search(line)):
+                    anchor = " ".join(line.split())
+                    findings.append(
+                        Finding(self.id, path, anchor, line=lineno,
+                                message=f"first-person: {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):
+        for glob in self.paths:
+            fname = glob.replace("*", "note")   # e.g. "*.md" -> "note.md"
+            for token in self.tokens_en:
+                line = f"Line with {token} here."
+                yield Plant(
+                    label=f"en:{token}:{glob}",
+                    planted_ws=FakeWorkspace(files={fname: line + "\n"}),
+                    expected=(self.id, fname, line),
+                )
+            for token in self.tokens_cjk:
+                line = f"这一行有{token}字。"
+                yield Plant(
+                    label=f"cjk:{token}:{glob}",
+                    planted_ws=FakeWorkspace(files={fname: line + "\n"}),
+                    expected=(self.id, fname, line),
+                )
+
+    def fixture(self, kit):
+        return FakeWorkspace(files={"README.md": "The ratchet turns one way.\n"})

ratch/checks/font_cdn.py

@@ -0,0 +1,84 @@
+"""No-external-font-cdn check."""
+from __future__ import annotations
+
+from ratch.check import Plant
+from ratch.result import Finding, Result, State
+from ratch.testing import FakeWorkspace
+
+_CDNS = (
+    "fonts.googleapis.com",
+    "fonts.gstatic.com",
+    "typekit.net",
+)
+_WEB = (".html", ".css", ".js")
+
+
+class NoExternalFontCdn:
+    """Forbid hosted webfont CDNs in shipped HTML/CSS/JS.
+
+    Rule:
+        Tracked .html/.css/.js files must not contain known font-CDN
+        host substrings.
+
+    Why:
+        A remote font fetch is a privacy and availability leak; fonts
+        must be served from the same origin.
+
+    Proven in:
+        internal/pillar-1-teeth.md
+
+    Not this:
+        Not a ban on local @font-face. Not a scan of markdown prose.
+    """
+
+    id = "no-external-font-cdn"
+    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 path.endswith(_WEB):
+                continue
+            examined_n += 1
+            text = ws.read(path)
+            for cdn in _CDNS:
+                if cdn in text:
+                    findings.append(
+                        Finding(self.id, path, cdn,
+                                message=f"font cdn: {cdn}")
+                    )
+        return Result(
+            self.id, self._state(findings, examined_n),
+            examined_n=examined_n, skipped_n=ws.skipped_n, findings=findings,
+        )
+
+    def plants(self, ws):
+        host = "fonts.googleapis.com"
+        yield Plant(
+            label="google-fonts",
+            planted_ws=FakeWorkspace(
+                files={"static/x.css": f"@import url(https://{host}/css);\n"}
+            ),
+            expected=(self.id, "static/x.css", host),
+        )
+
+    def fixture(self, kit):
+        return FakeWorkspace(files={"static/x.css": "body { font-family: sans-serif; }\n"})

ratch/checks/forbidden_literal.py

@@ -0,0 +1,131 @@
+"""No-forbidden-literal check."""
+from __future__ import annotations
+
+import re
+
+from ratch.check import Plant
+from ratch.result import Finding, Result, State
+from ratch.testing import FakeWorkspace
+
+
+def _sample_for(pattern):
+    parts = []
+    i = 0
+    while i < len(pattern):
+        if pattern[i] == "[" and i + 2 < len(pattern) and pattern[i + 2] == "]":
+            parts.append(pattern[i + 1])
+            i += 3
+        else:
+            parts.append(pattern[i])
+            i += 1
+    return "".join(parts)
+
+
+class NoForbiddenLiteral:
+    """Forbid a fixed set of author-tool literals anywhere they can leak.
+
+    Rule:
+        No tracked file content, tracked filename, or committer identity may
+        match any configured forbidden pattern.
+
+    Why:
+        An author-tool literal in shipped content, a path, or a commit trailer
+        is a provenance leak that no reviewer reliably catches by eye; a
+        machine can prove its absence on every commit.
+
+    Proven in:
+        tremor/tests/lint_no_forbidden_literal.py
+
+    Not this:
+        Not a style or taste rule. Naming, wording, and intent are untouched;
+        only an exact pattern match across three mechanical vectors is rejected.
+    """
+
+    id = "no-forbidden-literal"
+    tier = "A"
+    kind = "gate"
+    scope = "global"
+    proven_in = ("tremor/tests/lint_no_forbidden_literal.py",)
+    confidence = "breadth"
+    tolerates_unparseable = False
+
+    def __init__(self, patterns=("cl[a]ude",), 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 check(self, ws):
+        tracked = ws.tracked_files()
+        cached = ws.view == "index"
+        head = ws.view == "HEAD"
+        findings = []
+        for pattern in self.patterns:
+            rx = re.compile(pattern)
+            for path, line, text in ws.git_grep(pattern, cached=cached, head=head):
+                anchor = " ".join(text.split())
+                findings.append(
+                    Finding(self.id, path, anchor, line=line,
+                            message=f"content: {anchor}")
+                )
+            for path in tracked:
+                if rx.search(path):
+                    findings.append(
+                        Finding(self.id, path, path, message=f"filename: {path}")
+                    )
+            for field, value in ws.commit_identity().items():
+                if rx.search(str(value)):
+                    anchor = f"{field}:{value}"
+                    findings.append(
+                        Finding(self.id, "<commit>", anchor,
+                                message=f"commit {anchor}")
+                    )
+        examined_n = len(tracked) + 1
+        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):
+        for pattern in self.patterns:
+            sample = _sample_for(pattern)
+
+            content_path = "planted/content.py"
+            yield Plant(
+                label=f"content:{pattern}",
+                planted_ws=FakeWorkspace(files={content_path: sample + "\n"}),
+                expected=(self.id, content_path, sample),
+            )
+
+            fname = f"planted/{sample}_helper.py"
+            yield Plant(
+                label=f"filename:{pattern}",
+                planted_ws=FakeWorkspace(files={fname: "x = 1\n"}),
+                expected=(self.id, fname, fname),
+            )
+
+            email = sample + "@example.test"
+            yield Plant(
+                label=f"commit:{pattern}",
+                planted_ws=FakeWorkspace(
+                    files={"ok.py": "x = 1\n"},
+                    identity={"name": "Dev", "email": email,
+                              "subject": "init", "body": ""},
+                ),
+                expected=(self.id, "<commit>", f"email:{email}"),
+            )
+
+    def fixture(self, kit):
+        return FakeWorkspace(
+            files={"clean.py": "x = 1\n"},
+            identity={"name": "Dev", "email": "dev@example.test",
+                      "subject": "init", "body": ""},
+        )

ratch/checks/hash_named_test.py

@@ -0,0 +1,83 @@
+"""No-hash-named-test check."""
+from __future__ import annotations
+
+import re
+
+from ratch.check import Plant
+from ratch.checks import is_test_py
+from ratch.result import Finding, Result, State
+from ratch.testing import FakeWorkspace
+
+_HEX_STEM = re.compile(r"_[a-f0-9]{6,8}$")
+
+
+def _stem(path):
+    return path.rsplit("/", 1)[-1].removesuffix(".py")
+
+
+class NoHashNamedTest:
+    """Forbid opaque hex suffixes on test filenames.
+
+    Rule:
+        No tracked tests/*.py stem may end in underscore plus 6 to 8
+        hex digits.
+
+    Why:
+        A truncated hash in a filename is opaque once the commit is
+        forgotten; a readable stem stays reviewable.
+
+    Proven in:
+        internal/pillar-1-teeth.md
+
+    Not this:
+        Not a ban on hex elsewhere in the path. Not a check on non-test
+        modules.
+    """
+
+    id = "no-hash-named-test"
+    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
+            if _HEX_STEM.search(_stem(path)):
+                findings.append(
+                    Finding(self.id, path, path,
+                            message=f"hash-named test: {path}")
+                )
+        return Result(
+            self.id, self._state(findings, examined_n),
+            examined_n=examined_n, skipped_n=ws.skipped_n, findings=findings,
+        )
+
+    def plants(self, ws):
+        path = "tests/test_foo_a1b2c3d4.py"
+        yield Plant(
+            label="hex-stem",
+            planted_ws=FakeWorkspace(files={path: "x = 1\n"}),
+            expected=(self.id, path, path),
+        )
+
+    def fixture(self, kit):
+        return FakeWorkspace(files={"tests/test_foo.py": "x = 1\n"})