git-agent-ratchet 1.1.0__py3-none-any.whl

git_agent_ratchet/__init__.py

@@ -0,0 +1,5 @@
+"""git-agent-ratchet: deterministic git ratchets for guarding against agent drift."""
+
+from git_agent_ratchet._version import __version__
+
+__all__ = ["__version__"]

git_agent_ratchet/__main__.py

@@ -0,0 +1,3 @@
+from git_agent_ratchet.cli import main
+
+raise SystemExit(main())

git_agent_ratchet/_version.py

@@ -0,0 +1 @@
+__version__ = "1.1.0"

git_agent_ratchet/baseline.py

@@ -0,0 +1,82 @@
+"""Baseline registry: load, validate, and persist the ratchet JSON state."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+SCHEMA_URL = "https://git-agent-ratchet.org/schemas/v1.json"
+DEFAULT_AUTHOR = "git-agent-ratchet-core"
+
+
+@dataclass
+class Baseline:
+    """In-memory view of a ratchet baseline registry file."""
+
+    path: Path
+    ratchet_meta: dict[str, Any] = field(default_factory=dict)
+    baselines: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, path: Path) -> Baseline:
+        """Load a baseline from disk; return an empty baseline if missing."""
+        if not path.exists():
+            return cls(path=path, ratchet_meta=_empty_meta(), baselines={})
+        with path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+        return cls(
+            path=path,
+            ratchet_meta=data.get("ratchet_meta", _empty_meta()),
+            baselines=data.get("baselines", {}),
+        )
+
+    def get_metric(self, name: str) -> int | None:
+        """Return the stored metric_value for a ratchet, or None if absent."""
+        entry = self.baselines.get(name)
+        if entry is None:
+            return None
+        value = entry.get("metric_value")
+        return int(value) if value is not None else None
+
+    def set_entry(
+        self,
+        name: str,
+        metric_value: int,
+        items: list[dict[str, Any]],
+    ) -> None:
+        """Replace the stored entry for a ratchet with a fresh metric and item list."""
+        self.baselines[name] = {
+            "metric_value": int(metric_value),
+            "items": items,
+        }
+
+    def save(self, repo_signature: str | None = None) -> None:
+        """Persist the baseline to disk with stable, deterministic JSON formatting."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        meta = dict(self.ratchet_meta)
+        meta["last_updated_by"] = DEFAULT_AUTHOR
+        if repo_signature is not None:
+            meta["repo_signature"] = repo_signature
+        elif "repo_signature" not in meta:
+            meta["repo_signature"] = _signature_from_baselines(self.baselines)
+        payload = {
+            "$schema": SCHEMA_URL,
+            "ratchet_meta": meta,
+            "baselines": self.baselines,
+        }
+        text = json.dumps(payload, indent=2, sort_keys=False) + "\n"
+        self.path.write_text(text, encoding="utf-8")
+        self.ratchet_meta = meta
+
+
+def _empty_meta() -> dict[str, Any]:
+    return {"repo_signature": "", "last_updated_by": DEFAULT_AUTHOR}
+
+
+def _signature_from_baselines(baselines: dict[str, dict[str, Any]]) -> str:
+    """Derive a deterministic content signature for change detection."""
+    canonical = json.dumps(baselines, sort_keys=True).encode("utf-8")
+    return "sha256:" + hashlib.sha256(canonical).hexdigest()

git_agent_ratchet/cli.py

@@ -0,0 +1,53 @@
+"""Unified CLI dispatcher: `git-agent-ratchet <subcommand>`."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from git_agent_ratchet._version import __version__
+from git_agent_ratchet.hooks import (
+    anti_bypass,
+    deny_agent_chatter,
+    max_file_lines,
+    no_duplicate_helpers,
+)
+
+SUBCOMMANDS = {
+    "no-duplicate-helpers": no_duplicate_helpers.main,
+    "deny-agent-chatter": deny_agent_chatter.main,
+    "anti-bypass": anti_bypass.main,
+    "max-file-lines": max_file_lines.main,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="git-agent-ratchet",
+        description=(
+            "git-agent-ratchet: deterministic git ratchets for guarding against agent drift."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "subcommand",
+        choices=sorted(SUBCOMMANDS),
+        help="The ratchet to invoke.",
+    )
+    parser.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="Arguments forwarded to the chosen subcommand.",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler = SUBCOMMANDS[args.subcommand]
+    return handler(args.args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

git_agent_ratchet/hooks/__init__.py

@@ -0,0 +1 @@
+"""Pre-commit hook entry points and the unified CLI dispatcher."""

git_agent_ratchet/hooks/anti_bypass.py

@@ -0,0 +1,66 @@
+"""Hook: ratchet-anti-bypass (Ratchet C)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from git_agent_ratchet.ratchets.anti_bypass import BYPASS_KEY_ENV, evaluate
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ratchet-anti-bypass",
+        description=(
+            "Fail when an automated process attempts to mutate protected ratchet "
+            "configuration files without the human bypass key."
+        ),
+    )
+    parser.add_argument(
+        "--enforce-files",
+        required=True,
+        help=(
+            "Comma-separated list of repo-relative file paths that may only be "
+            "mutated when HUMAN_RATCHET_BYPASS_KEY is set."
+        ),
+    )
+    parser.add_argument(
+        "filenames",
+        nargs="*",
+        help="Staged files supplied by pre-commit.",
+    )
+    return parser
+
+
+def _split_enforce_files(value: str) -> list[str]:
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    protected = _split_enforce_files(args.enforce_files)
+    decision = evaluate(staged_files=args.filenames, protected_files=protected)
+
+    if not decision.blocked:
+        return 0
+
+    print("[ratchet] anti_bypass: GATE TRIPPED.", file=sys.stderr)
+    print(f"  reason: {decision.reason}", file=sys.stderr)
+    print("  protected files in this commit:", file=sys.stderr)
+    for path in decision.touched_protected_files:
+        print(f"    - {path}", file=sys.stderr)
+    if decision.agent_signal:
+        print(f"  agent signal: {decision.agent_signal}", file=sys.stderr)
+    print(
+        f"  Fix: a human operator must export {BYPASS_KEY_ENV}=<value> in their "
+        f"shell and re-run the commit. Agents must not set this variable.",
+        file=sys.stderr,
+    )
+    return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

git_agent_ratchet/hooks/deny_agent_chatter.py

@@ -0,0 +1,57 @@
+"""Hook: ratchet-deny-agent-chatter (Ratchet B)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from git_agent_ratchet.ratchets.agent_chatter import scan_files
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ratchet-deny-agent-chatter",
+        description=(
+            "Fail when staged files contain conversational agent-chatter artifacts "
+            "(e.g. 'Sure, I can help with...', 'As an AI, ...')."  # ratchet-allow: agent_chatter
+        ),
+    )
+    parser.add_argument(
+        "filenames",
+        nargs="*",
+        help="Files supplied by pre-commit. Each file is scanned for chatter signatures.",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    paths = [Path(f) for f in args.filenames]
+    matches = scan_files(paths)
+
+    if not matches:
+        return 0
+
+    print("[ratchet] agent_chatter: GATE TRIPPED.", file=sys.stderr)
+    print(
+        "  Conversational agent artifacts detected in the following staged files:",
+        file=sys.stderr,
+    )
+    for match in matches:
+        print(
+            f"  {match.file}:{match.line_number}  [{match.signature}]  {match.line}",
+            file=sys.stderr,
+        )
+    print(
+        "  Fix: remove the conversational preamble/postscript and re-stage the file.",
+        file=sys.stderr,
+    )
+    return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

git_agent_ratchet/hooks/max_file_lines.py

@@ -0,0 +1,128 @@
+"""Hook: ratchet-max-file-lines (Ratchet D)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from git_agent_ratchet.baseline import Baseline
+from git_agent_ratchet.ratchets.max_file_lines import (
+    DEFAULT_MAX_LINES,
+    RATCHET_NAME,
+    OversizedFile,
+    metric_value,
+    scan_directory,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ratchet-max-file-lines",
+        description=(
+            "Fail when the total line overage across over-sized source files "
+            "exceeds the recorded baseline. Shrinks are recorded automatically "
+            "and staged back into the commit."
+        ),
+    )
+    parser.add_argument(
+        "--baseline",
+        type=Path,
+        default=Path("config/ratchets/file_lines.json"),
+        help="Path to the JSON baseline registry file.",
+    )
+    parser.add_argument(
+        "--dir",
+        dest="directory",
+        type=Path,
+        default=Path("src"),
+        help="Directory tree to scan for over-sized files.",
+    )
+    parser.add_argument(
+        "--max",
+        dest="max_lines",
+        type=int,
+        default=DEFAULT_MAX_LINES,
+        help=f"Per-file line-count limit (default: {DEFAULT_MAX_LINES}).",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=None,
+        help="Directory name to exclude (repeatable). Defaults to tests/test.",
+    )
+    parser.add_argument(
+        "filenames",
+        nargs="*",
+        help="Files supplied by pre-commit (ignored; full directory scan is used).",
+    )
+    return parser
+
+
+def _emit_oversized(oversized: list[OversizedFile], max_lines: int) -> str:
+    if not oversized:
+        return "  (none)"
+    lines = []
+    for f in oversized:
+        lines.append(f"  - {f.path}: {f.line_count} lines (+{f.overage} over {max_lines})")
+    return "\n".join(lines)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    exclude = tuple(args.exclude) if args.exclude else ("tests", "test")
+    oversized = scan_directory(args.directory, max_lines=args.max_lines, exclude_dirs=exclude)
+    current = metric_value(oversized)
+
+    baseline = Baseline.load(args.baseline)
+    recorded = baseline.get_metric(RATCHET_NAME)
+
+    if recorded is None:
+        baseline.set_entry(
+            name=RATCHET_NAME,
+            metric_value=current,
+            items=[f.to_dict() for f in oversized],
+        )
+        baseline.save()
+        print(
+            f"[ratchet] {RATCHET_NAME}: seeded baseline at {args.baseline} "
+            f"(metric_value={current})."
+        )
+        return 0
+
+    if current > recorded:
+        print(
+            f"[ratchet] {RATCHET_NAME}: GATE TRIPPED.\n"
+            f"  baseline overage = {recorded}\n"
+            f"  current  overage = {current}\n"
+            f"  delta            = +{current - recorded}\n"
+            f"  over-sized files (max={args.max_lines}):\n"
+            f"{_emit_oversized(oversized, args.max_lines)}\n"
+            f"  Rule: per-file line counts may not grow past their recorded baseline.\n"
+            f"  Fix: split the file into focused modules, or extract a helper into "
+            f"an existing module that already owns the concept.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if current < recorded:
+        baseline.set_entry(
+            name=RATCHET_NAME,
+            metric_value=current,
+            items=[f.to_dict() for f in oversized],
+        )
+        baseline.save()
+        print(
+            f"[ratchet] {RATCHET_NAME}: baseline ratcheted down "
+            f"({recorded} -> {current}); registry restaged."
+        )
+        return 0
+
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

git_agent_ratchet/hooks/no_duplicate_helpers.py

@@ -0,0 +1,135 @@
+"""Hook: ratchet-no-duplicate-helpers (Ratchet A)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from git_agent_ratchet.baseline import Baseline
+from git_agent_ratchet.ratchets.duplicate_helpers import (
+    RATCHET_NAME,
+    DuplicateHelper,
+    metric_value,
+    scan_directory,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ratchet-no-duplicate-helpers",
+        description=(
+            "Fail when the count of duplicate private helper functions across the "
+            "target directory exceeds the recorded baseline. Shrinks are recorded "
+            "automatically and staged back into the commit."
+        ),
+    )
+    parser.add_argument(
+        "--baseline",
+        type=Path,
+        default=Path("config/ratchets/duplicates.json"),
+        help="Path to the JSON baseline registry file.",
+    )
+    parser.add_argument(
+        "--dir",
+        dest="directory",
+        type=Path,
+        default=Path("src"),
+        help="Directory tree to scan for duplicate helpers.",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=None,
+        help="Directory name to exclude (repeatable). Defaults to tests/test.",
+    )
+    parser.add_argument(
+        "--lang",
+        dest="languages",
+        action="append",
+        default=None,
+        choices=["python", "typescript", "csharp"],
+        help=(
+            "Restrict scanning to one or more languages (repeatable). "
+            "Default: all registered extractors."
+        ),
+    )
+    parser.add_argument(
+        "filenames",
+        nargs="*",
+        help="Files supplied by pre-commit (ignored; full directory scan is used).",
+    )
+    return parser
+
+
+def _emit_duplicates(duplicates: list[DuplicateHelper]) -> str:
+    if not duplicates:
+        return "  (none)"
+    lines = []
+    for dup in duplicates:
+        occ = ", ".join(dup.occurrences)
+        lines.append(f"  - {dup.name} -> [{occ}]")
+    return "\n".join(lines)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    exclude = tuple(args.exclude) if args.exclude else ("tests", "test")
+    duplicates = scan_directory(
+        args.directory,
+        exclude_dirs=exclude,
+        languages=args.languages,
+    )
+    current = metric_value(duplicates)
+
+    baseline = Baseline.load(args.baseline)
+    recorded = baseline.get_metric(RATCHET_NAME)
+
+    if recorded is None:
+        baseline.set_entry(
+            name=RATCHET_NAME,
+            metric_value=current,
+            items=[d.to_dict() for d in duplicates],
+        )
+        baseline.save()
+        print(
+            f"[ratchet] {RATCHET_NAME}: seeded baseline at {args.baseline} "
+            f"(metric_value={current})."
+        )
+        return 0
+
+    if current > recorded:
+        print(
+            f"[ratchet] {RATCHET_NAME}: GATE TRIPPED.\n"
+            f"  baseline metric_value = {recorded}\n"
+            f"  current  metric_value = {current}\n"
+            f"  delta                 = +{current - recorded}\n"
+            f"  duplicates now present:\n{_emit_duplicates(duplicates)}\n"
+            f"  Rule: duplicate-helper occurrences are not permitted to grow.\n"
+            f"  Fix: reuse the existing helper instead of forking a new one, "
+            f"or rename the new function so it's not a private helper.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if current < recorded:
+        baseline.set_entry(
+            name=RATCHET_NAME,
+            metric_value=current,
+            items=[d.to_dict() for d in duplicates],
+        )
+        baseline.save()
+        print(
+            f"[ratchet] {RATCHET_NAME}: baseline ratcheted down "
+            f"({recorded} -> {current}); registry restaged."
+        )
+        return 0
+
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

git_agent_ratchet/paths.py

@@ -0,0 +1,18 @@
+"""Shared path utilities used by the ratchet scanners."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def relative_posix(path: Path, anchor: Path) -> str:
+    """Return ``path`` as a posix string, relative to ``anchor`` when possible.
+
+    Falls back to the raw path string if ``path`` does not sit under ``anchor``
+    (which happens when callers pass an unrelated working directory).
+    """
+    try:
+        rel = path.resolve().relative_to(anchor.resolve())
+    except ValueError:
+        rel = path
+    return rel.as_posix()

git_agent_ratchet/ratchets/__init__.py

@@ -0,0 +1 @@
+"""Ratchet modules: scanners that produce structural metrics for the registry."""

git_agent_ratchet/ratchets/agent_chatter.py

@@ -0,0 +1,79 @@
+"""Ratchet B: lexical detection of agent-chatter artifacts leaking into files."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+RATCHET_NAME = "agent_chatter"
+
+# A line containing this literal substring is skipped by the scanner.
+# Lets repos that legitimately quote chatter (this very codebase, security
+# regression tests, docs explaining the rule) opt out per-line, the same
+# way ruff lets you opt out with a noqa comment.
+ALLOW_MARKER = "ratchet-allow: agent_chatter"
+
+# Regex signatures sourced directly from the spec table. Each entry pairs a
+# compiled pattern with a human-readable label used in failure output.
+CHATTER_SIGNATURES: tuple[tuple[str, re.Pattern[str]], ...] = (
+    (
+        "sure-i-can-help-with",
+        re.compile(r"(?i)(sure,\s)?i\scan\shelp\swith"),
+    ),
+    (
+        "as-an-ai",
+        re.compile(r"(?i)as\san\sai,\s(i\s)?"),
+    ),
+    (
+        "i-have-successfully",
+        re.compile(r"(?i)i\shave\ssuccessfully\s(modified|updated)"),
+    ),
+    (
+        "now-let-me-check",
+        re.compile(r"(?i)now\slet\sme\scheck\sthe\s(docs|dir)"),
+    ),
+)
+
+
+@dataclass(frozen=True)
+class ChatterMatch:
+    """A single line that matched one of the chatter signatures."""
+
+    file: str
+    line_number: int
+    signature: str
+    line: str
+
+
+def scan_text(text: str, file_label: str) -> list[ChatterMatch]:
+    """Scan text and return every line that matches any chatter signature."""
+    matches: list[ChatterMatch] = []
+    for line_number, raw_line in enumerate(text.splitlines(), start=1):
+        if ALLOW_MARKER in raw_line:
+            continue
+        for signature, pattern in CHATTER_SIGNATURES:
+            if pattern.search(raw_line):
+                matches.append(
+                    ChatterMatch(
+                        file=file_label,
+                        line_number=line_number,
+                        signature=signature,
+                        line=raw_line.rstrip(),
+                    )
+                )
+                break
+    return matches
+
+
+def scan_files(paths: Iterable[Path]) -> list[ChatterMatch]:
+    """Scan each file in paths; silently skip unreadable or binary files."""
+    matches: list[ChatterMatch] = []
+    for path in paths:
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        matches.extend(scan_text(text, file_label=str(path)))
+    return matches