countersign-cli 0.2.0__py3-none-any.whl

countersign/__init__.py

@@ -0,0 +1,8 @@
+# audited on 20260903
+"""Countersign: deterministic verification of agent completion claims.
+
+The agent signs (claims the work is done). Countersign only countersigns
+after the claim survived deterministic checks it can re-run later.
+"""
+
+__version__ = "0.2.0"

countersign/__main__.py

@@ -0,0 +1,4 @@
+# audited on 20260903
+from .cli import main
+
+raise SystemExit(main())

countersign/claims.py

@@ -0,0 +1,245 @@
+# audited on 20260903
+"""The claims protocol: every completion claim must be falsifiable.
+
+An agent (or a human) declares what is true about the work in claims.toml.
+Each claim carries the command that would fail if the claim were false.
+Countersign runs those commands and records the verdict. Nothing here
+interprets prose or trusts a summary: a claim either survived its command
+or it did not.
+
+The three expectations a claim can declare:
+
+  expect = "exit 0"          the command must succeed (default)
+  expect = "nonzero exit"    the command must fail (negative tests)
+  expect = "output contains" the needle must appear in combined output
+
+This is the protocol that makes "done" a testable statement: if nobody can
+say what command would disprove the claim, the claim was not a claim.
+
+Commands run through the shell in the repository root, in their own process
+group. A claim that times out is killed together with everything it
+spawned, so a hung test runner cannot outlive the verdict that recorded it.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import time
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+PASS = "pass"
+FAIL = "fail"
+TIMEOUT = "timeout"
+# A claim the repository's config requires but the claims file does not
+# declare. It fails the gate: a required claim that nobody wrote is the
+# quietest way to weaken a repository's own standard.
+MISSING = "missing"
+NOT_PASSED = frozenset({FAIL, TIMEOUT, MISSING})
+
+VALID_EXPECTATIONS = frozenset({"exit 0", "nonzero exit", "output contains"})
+
+# How long to wait for a killed command's pipes to drain before giving up
+# on collecting its output. A grandchild that escaped its process group can
+# hold the pipe open; the verdict must not hang on it.
+_DRAIN_AFTER_KILL_S = 5
+
+
+@dataclass(frozen=True)
+class Claim:
+    claim_id: str
+    statement: str
+    command: str
+    expect: str = "exit 0"
+    needle: str | None = None
+    timeout_s: int | None = None
+
+
+@dataclass
+class ClaimResult:
+    claim_id: str
+    statement: str
+    command: str
+    expect: str
+    status: str
+    exit_code: int | None = None
+    duration_ms: int = 0
+    output_excerpt: str = ""
+
+
+class ClaimsError(ValueError):
+    """The claims file exists but cannot be honoured as written."""
+
+
+def load_claims(path: Path | None) -> list[Claim] | None:
+    """Parse claims.toml. None means no file (a reported skip, not silence)."""
+    if path is None:
+        return None
+    with Path(path).open("rb") as handle:
+        data = handle.read()
+    return parse_claims(data, Path(path).name)
+
+
+def parse_claims(data: bytes | str, source_name: str = "claims.toml") -> list[Claim]:
+    """Parse the text of a claims file. Raises ClaimsError for anything that
+    cannot be honoured as written."""
+    if isinstance(data, bytes):
+        try:
+            # TOML is UTF-8 by definition; a byte order mark is tolerated,
+            # anything undecodable is refused rather than silently repaired,
+            # because a repaired byte inside a command would change what runs.
+            data = data.decode("utf-8-sig")
+        except UnicodeDecodeError as exc:
+            raise ClaimsError(f"{source_name} is not valid UTF-8: {exc}") from None
+    try:
+        raw = tomllib.loads(data)
+    except tomllib.TOMLDecodeError as exc:
+        raise ClaimsError(f"{source_name} is not valid TOML: {exc}") from None
+    declared: Any = raw.get("claim", [])
+    if not isinstance(declared, list) or not all(isinstance(entry, dict) for entry in declared):
+        raise ClaimsError("claims must be declared as an array of tables: one [[claim]] block per claim")
+    claims: list[Claim] = []
+    seen: set[str] = set()
+    for index, entry in enumerate(declared, start=1):
+        claim_id = str(entry.get("id", "")).strip()
+        if not claim_id:
+            raise ClaimsError(f"claim {index} has no id")
+        if claim_id in seen:
+            raise ClaimsError(f"claim id '{claim_id}' is declared twice")
+        seen.add(claim_id)
+        statement = str(entry.get("statement", "")).strip()
+        if not statement:
+            raise ClaimsError(f"claim '{claim_id}' has no statement")
+        command = str(entry.get("command", "")).strip()
+        if not command:
+            raise ClaimsError(f"claim '{claim_id}' declares no command; a claim without a disproof command is not falsifiable")
+        expect = str(entry.get("expect", "exit 0"))
+        if expect not in VALID_EXPECTATIONS:
+            raise ClaimsError(
+                f"claim '{claim_id}' uses expect = '{expect}', which is not one of {sorted(VALID_EXPECTATIONS)}"
+            )
+        needle = entry.get("needle")
+        if expect == "output contains" and not needle:
+            raise ClaimsError(f"claim '{claim_id}' expects 'output contains' but declares no needle")
+        timeout_s: int | None = None
+        if "timeout_s" in entry:
+            raw_timeout = entry["timeout_s"]
+            if isinstance(raw_timeout, bool) or not isinstance(raw_timeout, int) or raw_timeout < 1:
+                raise ClaimsError(f"claim '{claim_id}' has timeout_s = {raw_timeout!r}; it must be a whole number of seconds, at least 1")
+            timeout_s = raw_timeout
+        claims.append(
+            Claim(
+                claim_id=claim_id,
+                statement=statement,
+                command=command,
+                expect=expect,
+                needle=str(needle) if needle is not None else None,
+                timeout_s=timeout_s,
+            )
+        )
+    return claims
+
+
+def missing_claim(claim_id: str) -> ClaimResult:
+    """The verdict for a required claim that was never declared."""
+    return ClaimResult(
+        claim_id=claim_id,
+        statement="required by countersign.toml but not declared in the claims file",
+        command="",
+        expect="exit 0",
+        status=MISSING,
+    )
+
+
+def _truncate(text: str, limit: int) -> str:
+    if len(text) <= limit:
+        return text
+    half = limit // 2
+    return text[:half] + f"\n... [{len(text) - limit} characters truncated] ...\n" + text[-half:]
+
+
+def _decode(data: bytes | None) -> str:
+    """Command output as text, whatever bytes the command produced."""
+    if not data:
+        return ""
+    return data.decode("utf-8", errors="replace")
+
+
+def _kill_tree(process: subprocess.Popen) -> None:
+    """Kill the command and everything it started."""
+    try:
+        if os.name == "nt":
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(process.pid)],
+                capture_output=True, check=False, timeout=15,
+            )
+        else:
+            os.killpg(process.pid, signal.SIGKILL)
+    except (OSError, subprocess.SubprocessError):
+        pass
+    try:
+        process.kill()
+    except OSError:
+        pass
+
+
+def run_claim(claim: Claim, cwd: Path, default_timeout_s: int, max_output_bytes: int) -> ClaimResult:
+    """Run one claim's command and judge it exactly as declared."""
+    timeout_s = claim.timeout_s if claim.timeout_s is not None else default_timeout_s
+    started = time.monotonic()
+    isolation: dict[str, Any] = (
+        {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP}
+        if os.name == "nt"
+        else {"start_new_session": True}
+    )
+    process = subprocess.Popen(
+        claim.command,
+        shell=True,
+        cwd=str(cwd),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        **isolation,
+    )
+    try:
+        stdout, stderr = process.communicate(timeout=timeout_s)
+    except subprocess.TimeoutExpired:
+        _kill_tree(process)
+        try:
+            stdout, stderr = process.communicate(timeout=_DRAIN_AFTER_KILL_S)
+        except subprocess.TimeoutExpired:
+            stdout, stderr = b"", b""
+        return ClaimResult(
+            claim_id=claim.claim_id,
+            statement=claim.statement,
+            command=claim.command,
+            expect=claim.expect,
+            status=TIMEOUT,
+            duration_ms=int((time.monotonic() - started) * 1000),
+            output_excerpt=_truncate(_decode(stdout) + _decode(stderr), max_output_bytes),
+        )
+
+    duration_ms = int((time.monotonic() - started) * 1000)
+    combined = _decode(stdout) + _decode(stderr)
+    excerpt = _truncate(combined, max_output_bytes)
+
+    if claim.expect == "exit 0":
+        status = PASS if process.returncode == 0 else FAIL
+    elif claim.expect == "nonzero exit":
+        status = PASS if process.returncode != 0 else FAIL
+    else:
+        status = PASS if (claim.needle or "") in combined else FAIL
+
+    return ClaimResult(
+        claim_id=claim.claim_id,
+        statement=claim.statement,
+        command=claim.command,
+        expect=claim.expect,
+        status=status,
+        exit_code=process.returncode,
+        duration_ms=duration_ms,
+        output_excerpt=excerpt,
+    )

countersign/claimsdiff.py

@@ -0,0 +1,134 @@
+# audited on 20260903
+"""What changed in the claims file, judged against a base revision.
+
+The agent that wrote the code can also write the claims. The quiet way to
+pass a gate is not to fix the code but to soften the claim: drop the test
+claim, change ``exit 0`` to ``nonzero exit``, point the needle at a string
+that is always there. This module makes that visible where a reviewer
+looks: as a diff of claims between a base revision (the branch a pull
+request targets) and the working tree, with every weakening named.
+
+What counts as weakened, deterministically:
+
+  removed              the claim is gone
+  expect changed       the judgement rule changed
+  needle changed       what the output must contain changed
+
+A changed command is reported as changed and left to the reviewer: the
+engine cannot know whether ``npm test`` became stricter or looser. A
+changed statement or timeout is reported as wording.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .claims import Claim, ClaimsError, parse_claims
+
+ADDED = "added"
+REMOVED = "removed"
+CHANGED = "changed"
+
+WEAKENING_FIELDS = ("expect", "needle")
+
+
+@dataclass(frozen=True)
+class ClaimChange:
+    claim_id: str
+    kind: str
+    fields: tuple[str, ...]
+    weakened: bool
+    detail: str
+
+
+def claims_text_at(root: Path, ref: str, claims_file: str) -> bytes | None:
+    """The claims file as it was at ``ref``; None when it did not exist there.
+
+    Raises ClaimsError when git cannot answer at all (no repository, no such
+    ref, git missing): a base that cannot be read must not pass as "no
+    claims at base".
+    """
+    try:
+        top = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"], cwd=str(root),
+            capture_output=True, text=True, timeout=15,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise ClaimsError(f"cannot read claims at {ref}: git is not available ({exc})") from None
+    if top.returncode != 0:
+        raise ClaimsError(f"cannot read claims at {ref}: {root} is not inside a git repository")
+    toplevel = Path(top.stdout.strip()).resolve()
+    target = (Path(root).resolve() / claims_file).resolve()
+    if not target.is_relative_to(toplevel):
+        raise ClaimsError(f"cannot read claims at {ref}: {target} is outside the repository {toplevel}")
+    relative = target.relative_to(toplevel).as_posix()
+    # ls-tree answers "does this path exist at that revision" with its exit
+    # code and output alone, so no error message has to be parsed (git
+    # localises its messages).
+    listed = _git_bytes(toplevel, ref, "ls-tree", ref, "--", relative)
+    if listed.returncode != 0:
+        raise ClaimsError(f"cannot read claims at {ref}: {listed.stderr.decode('utf-8', errors='replace').strip() or 'not a valid revision'}")
+    if not listed.stdout.strip():
+        return None
+    shown = _git_bytes(toplevel, ref, "show", f"{ref}:{relative}")
+    if shown.returncode != 0:
+        raise ClaimsError(f"cannot read claims at {ref}: {shown.stderr.decode('utf-8', errors='replace').strip() or 'git show failed'}")
+    return shown.stdout
+
+
+def _git_bytes(cwd: Path, ref: str, *args: str) -> subprocess.CompletedProcess[bytes]:
+    try:
+        return subprocess.run(["git", *args], cwd=str(cwd), capture_output=True, timeout=30)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise ClaimsError(f"cannot read claims at {ref}: {exc}") from None
+
+
+def diff_claims(base: list[Claim] | None, head: list[Claim] | None) -> list[ClaimChange]:
+    """Changes from ``base`` to ``head``, ordered by claim id. None means the
+    file did not exist on that side."""
+    base_by_id = {c.claim_id: c for c in (base or [])}
+    head_by_id = {c.claim_id: c for c in (head or [])}
+    changes: list[ClaimChange] = []
+    for claim_id in sorted(set(base_by_id) | set(head_by_id)):
+        before = base_by_id.get(claim_id)
+        after = head_by_id.get(claim_id)
+        if before is None and after is not None:
+            changes.append(ClaimChange(claim_id, ADDED, (), False, f"added: {after.statement}"))
+            continue
+        if before is not None and after is None:
+            changes.append(ClaimChange(claim_id, REMOVED, (), True, f"removed: {before.statement}"))
+            continue
+        if before is None or after is None:
+            continue  # unreachable: the id came from one of the two sides
+        fields = tuple(
+            name for name in ("statement", "command", "expect", "needle", "timeout_s")
+            if getattr(before, name) != getattr(after, name)
+        )
+        if not fields:
+            continue
+        weakened = any(name in WEAKENING_FIELDS for name in fields)
+        parts = []
+        for name in fields:
+            parts.append(f"{name}: {getattr(before, name)!r} to {getattr(after, name)!r}")
+        changes.append(ClaimChange(claim_id, CHANGED, fields, weakened, "; ".join(parts)))
+    return changes
+
+
+def diff_against_ref(root: Path, ref: str, claims_file: str, head: list[Claim] | None) -> tuple[list[ClaimChange], str | None]:
+    """Diff the working tree's claims against those at ``ref``.
+
+    Returns (changes, base_problem). ``base_problem`` names a base claims
+    file that exists but cannot be parsed; the diff then treats the base
+    as empty so that every head claim shows as added, and the problem is
+    reported next to it rather than hidden.
+    """
+    text = claims_text_at(root, ref, claims_file)
+    if text is None:
+        return diff_claims(None, head), None
+    try:
+        base = parse_claims(text, f"{claims_file} at {ref}")
+    except ClaimsError as exc:
+        return diff_claims(None, head), str(exc)
+    return diff_claims(base, head), None