countersign-cli 0.2.0__py3-none-any.whl

countersign/plain.py

@@ -0,0 +1,111 @@
+# audited on 20260905
+"""The receipt in plain words.
+
+The terminal summary and the pack tables are written for engineers. The
+person who most needs a receipt is often the one who cannot read a stack
+trace: they asked an agent for a feature and were told it is done. This
+module renders the same facts as short sentences, one idea each, with no
+jargon the reader has to look up. Every sentence is derived from the run's
+recorded facts; nothing is softened, nothing is inferred.
+"""
+
+from __future__ import annotations
+
+from .claims import FAIL, MISSING, PASS, TIMEOUT
+from .engine import FAIL_VERDICT, GateResult
+from .stubscan import RULES
+
+# What each finding kind means to someone who did not write the rule. The
+# marker rules carry their own words; the structural kinds are named here.
+KIND_IN_WORDS = {rule.rule_id: rule.plain for rule in RULES}
+KIND_IN_WORDS["empty-body"] = "a function that does nothing"
+KIND_IN_WORDS["unparseable"] = "a Python file that does not even parse"
+
+FINDINGS_SHOWN = 5
+CLAIMS_SHOWN = 3
+
+
+def _count(n: int, singular: str, plural: str | None = None) -> str:
+    return f"{n} {singular if n == 1 else (plural or singular + 's')}"
+
+
+def _last_line(text: str) -> str:
+    lines = [line.strip() for line in (text or "").strip().splitlines() if line.strip()]
+    return lines[-1][:120] if lines else ""
+
+
+def plain_sentences(result: GateResult) -> list[str]:
+    """Short sentences, each ending with a full stop, telling a non-engineer
+    what was checked, what held, and what did not."""
+    sentences: list[str] = []
+    results = result.claim_results or []
+    failed = [c for c in results if c.status == FAIL]
+    timed_out = [c for c in results if c.status == TIMEOUT]
+    missing = [c for c in results if c.status == MISSING]
+    held = [c for c in results if c.status == PASS]
+    weakened = result.weakened_claims
+
+    if result.verdict == FAIL_VERDICT:
+        reasons: list[str] = []
+        if result.findings:
+            reasons.append(f"{_count(len(result.findings), 'place')} in the code look unfinished")
+        if failed or timed_out:
+            reasons.append(f"{_count(len(failed) + len(timed_out), 'claim')} out of {len(results)} did not hold")
+        if missing:
+            reasons.append(f"{_count(len(missing), 'required claim')} {'was' if len(missing) == 1 else 'were'} never declared")
+        if weakened:
+            reasons.append(f"the claims file was weakened compared with {result.claims_base}")
+        sentences.append("Not countersigned: " + "; ".join(reasons) + ".")
+    else:
+        scanned = f"{_count(result.files_scanned, 'file')} {'was' if result.files_scanned == 1 else 'were'} scanned and none carries unfinished work"
+        if result.claim_results is None:
+            sentences.append(f"Countersigned on the scan alone: {scanned}.")
+        elif held:
+            shown = "; ".join(f"'{c.statement}'" for c in held[:CLAIMS_SHOWN])
+            more = f" and {len(held) - CLAIMS_SHOWN} more" if len(held) > CLAIMS_SHOWN else ""
+            sentences.append(f"Countersigned: {scanned}, and {_count(len(held), 'claim')} held: {shown}{more}.")
+        else:
+            sentences.append(f"Countersigned: {scanned}, and no claim was declared.")
+
+    for finding in result.findings[:FINDINGS_SHOWN]:
+        kind = KIND_IN_WORDS.get(finding.rule_id, finding.why)
+        sentences.append(f"{finding.path} line {finding.line}: {kind}.")
+    if len(result.findings) > FINDINGS_SHOWN:
+        sentences.append(f"{len(result.findings) - FINDINGS_SHOWN} more such places are listed in the findings table.")
+
+    for claim in failed:
+        tail = _last_line(claim.output_excerpt)
+        ending = f"; its last line of output was '{tail}'" if tail else "; it printed nothing"
+        code = f"exit code {claim.exit_code}" if claim.exit_code is not None else "no exit code"
+        sentences.append(f"The claim '{claim.statement}' did not hold: the command '{claim.command}' ended with {code}{ending}.")
+    for claim in timed_out:
+        sentences.append(f"The claim '{claim.statement}' was stopped after {max(1, round(claim.duration_ms / 1000))} seconds without finishing.")
+    for claim in missing:
+        sentences.append(f"The claim '{claim.claim_id}' is required by your configuration but was never declared.")
+    if result.verdict == FAIL_VERDICT and held:
+        sentences.append(f"{_count(len(held), 'other claim')} held.")
+
+    if result.claim_results is None:
+        sentences.append("No claims were checked: no claims file was found, and a skipped check is not a pass.")
+
+    if weakened:
+        parts: list[str] = []
+        for change in weakened:
+            if change.kind == "removed":
+                parts.append(f"'{change.claim_id}' was removed")
+            elif "expect" in change.fields:
+                parts.append(f"'{change.claim_id}' now expects the opposite outcome")
+            elif "needle" in change.fields:
+                parts.append(f"'{change.claim_id}' now looks for a different phrase in the output")
+            else:
+                parts.append(f"'{change.claim_id}' was changed")
+        sentences.append(f"The claims file was weakened compared with {result.claims_base}: " + "; ".join(parts) + ".")
+
+    if result.git_dirty:
+        sentences.append(
+            f"The files checked include uncommitted changes, so this receipt describes the working tree, "
+            f"not commit {result.git_commit[:8]} exactly."
+        )
+
+    sentences.append("No AI judged anything here; every sentence comes from a command's exit code or a text match you can re-run yourself.")
+    return sentences

countersign/receipt.py

@@ -0,0 +1,255 @@
+# audited on 20260903
+"""The receipt: what a countersignature actually is.
+
+Three renderings of one run:
+
+  JSON      the machine-readable receipt, digest-bound to the register
+  Markdown  for CI step summaries, pull request comments and status pages
+  Terminal  for the human who just ran the command
+
+The wording rule inherited from the evidence-pack tradition: the receipt
+never says "verified" without saying what was checked, and a skipped check
+is printed as a skip. A receipt that overstates is worse than no receipt.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from . import __version__
+from .claims import FAIL, MISSING, PASS, TIMEOUT
+from .engine import FAIL_VERDICT, GateResult
+from .plain import plain_sentences
+
+STATUS_MARK = {PASS: "PASS", FAIL: "FAIL", TIMEOUT: "TIMEOUT", MISSING: "MISSING"}
+
+DIRTY_SUFFIX = " (uncommitted changes in the working tree)"
+
+
+def commit_label(result: GateResult) -> str:
+    """The commit as it should be read: with the dirty flag attached when the
+    scanned files were not exactly that commit."""
+    return result.git_commit + (DIRTY_SUFFIX if result.git_dirty else "")
+
+
+def _code_span(text: str) -> str:
+    """A Markdown code span that survives backticks and newlines in ``text``.
+
+    Evidence lines carry template literals and reStructuredText ``code``;
+    commands can be multi-line TOML strings. The fence is one backtick
+    longer than the longest run inside, which is the CommonMark rule.
+    """
+    flat = " ".join(text.split())
+    longest_run = max((len(run) for run in re.findall(r"`+", flat)), default=0)
+    fence = "`" * (longest_run + 1)
+    return f"{fence} {flat} {fence}"
+
+
+def receipt_json(result: GateResult) -> dict:
+    return {
+        "run_id": result.run_id,
+        "recorded_at": result.recorded_at,
+        "countersign_version": __version__,
+        "verdict": result.verdict,
+        "config": {"path": result.config_path, "sha256": result.config_sha256},
+        "claims_file": (
+            {"sha256": result.claims_sha256} if result.claims_sha256 else None
+        ),
+        "git_commit": result.git_commit,
+        "git_dirty": result.git_dirty,
+        "scan": {
+            "files_scanned": result.files_scanned,
+            "findings": len(result.findings),
+            "exemptions": result.exemptions,
+            "tests_excluded": result.tests_excluded,
+        },
+        "findings": [
+            {
+                "path": f.path,
+                "line": f.line,
+                "rule_id": f.rule_id,
+                "why": f.why,
+                "evidence": f.evidence,
+            }
+            for f in result.findings
+        ],
+        "claims": (
+            None
+            if result.claim_results is None
+            else [
+                {
+                    "claim_id": c.claim_id,
+                    "statement": c.statement,
+                    "command": c.command,
+                    "expect": c.expect,
+                    "status": c.status,
+                    "exit_code": c.exit_code,
+                    "duration_ms": c.duration_ms,
+                    "output_excerpt": c.output_excerpt,
+                }
+                for c in result.claim_results
+            ]
+        ),
+        "claims_status": result.claims_status,
+        "plain": plain_sentences(result),
+        "claims_diff": (
+            None
+            if result.claims_diff is None
+            else {
+                "base": result.claims_base,
+                "base_problem": result.claims_base_problem,
+                "weakened": len(result.weakened_claims),
+                "changes": [
+                    {
+                        "claim_id": c.claim_id,
+                        "kind": c.kind,
+                        "fields": list(c.fields),
+                        "weakened": c.weakened,
+                        "detail": c.detail,
+                    }
+                    for c in result.claims_diff
+                ],
+            }
+        ),
+        "register": {"index": result.register_index, "hash": result.register_hash},
+        "duration_ms": result.duration_ms,
+        "notes": result.notes,
+    }
+
+
+def write_receipt(result: GateResult, path: Path) -> Path:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(receipt_json(result), indent=2, sort_keys=True), encoding="utf-8")
+    return path
+
+
+def load_receipt(path: Path) -> dict:
+    with Path(path).open(encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def find_receipt(receipts_root: Path, run_id: str) -> Path | None:
+    candidate = Path(receipts_root) / f"{run_id}.json"
+    return candidate if candidate.exists() else None
+
+
+def markdown_summary(result: GateResult) -> str:
+    lines: list[str] = []
+    verdict_word = "COUNTERSIGNED" if result.verdict != FAIL_VERDICT else "NOT COUNTERSIGNED"
+    lines.append(f"## Countersign: {verdict_word}")
+    lines.append("")
+    lines.append(" ".join(plain_sentences(result)))
+    lines.append("")
+    lines.append("| | |")
+    lines.append("|---|---|")
+    lines.append(f"| Run | `{result.run_id}` |")
+    lines.append(f"| Git commit | `{result.git_commit}`{DIRTY_SUFFIX if result.git_dirty else ''} |")
+    lines.append(f"| Files scanned | {result.files_scanned} |")
+    lines.append(f"| Marker findings | {len(result.findings)} |")
+    lines.append(f"| Line exemptions used | {result.exemptions} |")
+    claims_line = "skipped, not passed (see notes)" if result.claim_results is None else f"{len(result.claim_results)} declared"
+    lines.append(f"| Claims | {claims_line} |")
+    if result.claims_diff is not None:
+        lines.append(f"| Claims changed against `{result.claims_base}` | {len(result.claims_diff)}, {len(result.weakened_claims)} weakened |")
+    lines.append(f"| Register head | `{result.register_hash[:16]}...` at entry {result.register_index} |")
+    lines.append("")
+
+    if result.findings:
+        lines.append("### Findings")
+        lines.append("")
+        lines.append("| Location | Rule | Evidence |")
+        lines.append("|---|---|---|")
+        for f in result.findings[:25]:
+            evidence = f.evidence.replace("|", "\\|")[:120]
+            lines.append(f"| `{f.path}:{f.line}` | {f.rule_id} | {_code_span(evidence)} |")
+        if len(result.findings) > 25:
+            lines.append(f"| ... | ... | {len(result.findings) - 25} more in the receipt JSON |")
+        lines.append("")
+
+    if result.claim_results is not None:
+        lines.append("### Claims")
+        lines.append("")
+        lines.append("| Status | Claim | Command |")
+        lines.append("|---|---|---|")
+        for c in result.claim_results:
+            command = c.command.replace("|", "\\|")[:100]
+            statement = " ".join(c.statement.replace("|", "\\|").split())
+            lines.append(f"| {STATUS_MARK.get(c.status, c.status)} | {statement} | {_code_span(command) if command else 'none declared'} |")
+        lines.append("")
+
+    if result.claims_diff:
+        lines.append(f"### Claims changed against `{result.claims_base}`")
+        lines.append("")
+        lines.append("| Claim | Change | Weakened | Detail |")
+        lines.append("|---|---|---|---|")
+        for change in result.claims_diff:
+            detail = " ".join(change.detail.replace("|", "\\|").split())[:200]
+            lines.append(f"| `{change.claim_id}` | {change.kind} | {'YES' if change.weakened else 'no'} | {detail} |")
+        lines.append("")
+
+    for note in result.notes:
+        lines.append(f"> {note}")
+    if result.notes:
+        lines.append("")
+    return "\n".join(lines)
+
+
+def terminal_summary(result: GateResult, use_color: bool = True) -> str:
+    green, red, yellow, bold, reset = ("", "", "", "", "")
+    if use_color:
+        green, red, yellow, bold, reset = "\033[32m", "\033[31m", "\033[33m", "\033[1m", "\033[0m"
+
+    lines: list[str] = []
+    lines.append(f"{bold}Countersign{reset} run {result.run_id}")
+    lines.append(f"  commit {commit_label(result)} · {result.files_scanned} files scanned · {result.duration_ms} ms")
+    lines.append("")
+
+    if result.findings:
+        mark = f"{red}✗{reset}"
+        lines.append(f"{mark} marker scan: {len(result.findings)} finding(s)")
+        for f in result.findings[:15]:
+            lines.append(f"    {f.path}:{f.line}  [{f.rule_id}]  {f.evidence[:100]}")
+        if len(result.findings) > 15:
+            lines.append(f"    ... {len(result.findings) - 15} more")
+    else:
+        lines.append(f"{green}✓{reset} marker scan: clean ({result.files_scanned} files)")
+
+    if result.claim_results is None:
+        lines.append(f"{yellow}–{reset} claims: skipped, not passed (see note below)")
+    else:
+        for c in result.claim_results:
+            if c.status == PASS:
+                lines.append(f"{green}✓{reset} claim {c.claim_id}: {c.statement}")
+            elif c.status == TIMEOUT:
+                lines.append(f"{red}✗{reset} claim {c.claim_id}: TIMED OUT after {c.duration_ms} ms: {c.statement}")
+            elif c.status == MISSING:
+                lines.append(f"{red}✗{reset} claim {c.claim_id}: MISSING, {c.statement}")
+            else:
+                excerpt = (c.output_excerpt or "").strip().splitlines()
+                tail = excerpt[-1][:120] if excerpt else "no output"
+                lines.append(f"{red}✗{reset} claim {c.claim_id}: {c.statement}")
+                lines.append(f"    command: {c.command}")
+                lines.append(f"    output ends: {tail}")
+
+    if result.claims_diff is not None:
+        weakened = result.weakened_claims
+        mark = f"{red}✗{reset}" if weakened else f"{green}✓{reset}"
+        lines.append(f"{mark} claims against {result.claims_base}: {len(result.claims_diff)} change(s), {len(weakened)} weakened")
+        for change in result.claims_diff:
+            flag = "WEAKENED " if change.weakened else ""
+            lines.append(f"    {flag}{change.kind} {change.claim_id}: {change.detail[:140]}")
+
+    for note in result.notes:
+        lines.append(f"{yellow}–{reset} note: {note}")
+
+    lines.append("")
+    if result.verdict == FAIL_VERDICT:
+        weakened_part = f", {len(result.weakened_claims)} weakened claim(s)" if result.weakened_claims else ""
+        lines.append(f"{red}{bold}NOT COUNTERSIGNED{reset} · {len(result.findings)} finding(s), {len(result.failed_claims)} failed claim(s){weakened_part}")
+        lines.append("The work did not pass its own declared checks. Fix the code or the claims.")
+    else:
+        lines.append(f"{green}{bold}COUNTERSIGNED{reset} · register entry {result.register_index}, head {result.register_hash[:16]}...")
+    return "\n".join(lines)

countersign/register.py

@@ -0,0 +1,205 @@
+# audited on 20260903
+"""The evidence register: append only, hash chained, plain files.
+
+Every check Countersign runs, every finding it produces and every claim
+verdict is written here as one line of JSON. Each line carries the hash of
+the line before it, so any later edit to any earlier line breaks the chain
+and ``verify_chain`` says so. This is what makes a receipt tamper evident:
+not a claim on a website, but arithmetic anyone can redo.
+
+Adapted from Gaigentic Verify's register (2026), which ran this exact design
+through a file-by-file production review.
+
+Deliberately a file, not a database. It has to run inside any repository on
+any machine on day one, and a file is something an auditor can copy, diff
+and keep.
+
+Appends take an exclusive lock on a sibling ``.lock`` file for the read-head,
+write-entry pair. Without it, two runs started at the same moment (two CI
+jobs on one checkout, a human and a hook) could both chain onto the same
+head and leave a register that is broken forever, indistinguishable from
+tampering.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator
+
+try:
+    import fcntl
+except ImportError:  # Windows has no fcntl; msvcrt provides byte-range locks
+    fcntl = None
+    import msvcrt
+
+GENESIS = "0" * 64
+
+
+class RegisterDamaged(ValueError):
+    """The file cannot be extended without breaking the chain it carries."""
+
+
+def _canonical(payload: dict[str, Any]) -> str:
+    """Stable JSON so the same entry always hashes to the same value."""
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str)
+
+
+def entry_hash(previous_hash: str, body: dict[str, Any]) -> str:
+    return hashlib.sha256((previous_hash + _canonical(body)).encode("utf-8")).hexdigest()
+
+
+@contextlib.contextmanager
+def _exclusive(lock_path: Path) -> Iterator[None]:
+    """Hold an exclusive advisory lock on ``lock_path`` for the block."""
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lock_path.open("a+b") as handle:
+        if fcntl is not None:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        else:
+            handle.seek(0)
+            msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
+            try:
+                yield
+            finally:
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+
+
+@dataclass
+class Register:
+    """Append-only log of everything a verification run did."""
+
+    path: Path
+
+    def __post_init__(self) -> None:
+        self.path = Path(self.path)
+
+    @property
+    def lock_path(self) -> Path:
+        return self.path.parent / (self.path.name + ".lock")
+
+    # ---- writing ----
+
+    def append(self, kind: str, body: dict[str, Any], *, at: datetime | None = None) -> dict[str, Any]:
+        """Add one entry and return it, including its position and hash.
+
+        The entry is on the disk before this returns. Evidence that a caller
+        has been told was written, and that a power cut then removes, would
+        be worse than evidence never written at all: the register would be
+        short an entry and nobody would know which.
+        """
+        with _exclusive(self.lock_path):
+            previous = self.head()
+            previous_hash = previous["hash"] if previous else GENESIS
+            index = (previous["index"] + 1) if previous else 0
+            recorded_at = (at or datetime.now(timezone.utc)).isoformat()
+
+            core = {"index": index, "kind": kind, "recorded_at": recorded_at, "body": body}
+            entry = {**core, "previous_hash": previous_hash, "hash": entry_hash(previous_hash, core)}
+
+            with self.path.open("a", encoding="utf-8") as handle:
+                handle.write(json.dumps(entry, sort_keys=True, default=str) + "\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+        return entry
+
+    # ---- reading ----
+
+    def entries(self) -> Iterator[dict[str, Any]]:
+        """Every entry, in order, without verifying the chain. Use
+        ``verify_chain`` first when the file may have been touched."""
+        if not self.path.exists():
+            return
+        with self.path.open(encoding="utf-8", errors="replace") as handle:
+            for line in handle:
+                line = line.strip()
+                if line:
+                    yield json.loads(line)
+
+    def _last_line(self) -> str | None:
+        """The final line, read by seeking rather than by reading everything.
+
+        Appending needs only the entry before it. Reading the whole file to
+        find that entry makes each append cost more than the last, so a
+        register that runs for years gets slower every month it is used.
+        """
+        if not self.path.exists():
+            return None
+        with self.path.open("rb") as handle:
+            handle.seek(0, os.SEEK_END)
+            position = handle.tell()
+            collected = b""
+            while position > 0:
+                step = min(4096, position)
+                position -= step
+                handle.seek(position)
+                collected = handle.read(step) + collected
+                stripped = collected.rstrip(b"\n")
+                if b"\n" in stripped:
+                    return stripped.rsplit(b"\n", 1)[1].decode("utf-8", errors="replace")
+            final = collected.strip()
+            return final.decode("utf-8", errors="replace") if final else None
+
+    def head(self) -> dict[str, Any] | None:
+        line = self._last_line()
+        if line is None:
+            return None
+        try:
+            entry = json.loads(line)
+            if not isinstance(entry, dict) or not isinstance(entry.get("index"), int) or not isinstance(entry.get("hash"), str):
+                raise ValueError("the line is not a register entry")
+        except ValueError as exc:  # json.JSONDecodeError is a ValueError
+            raise RegisterDamaged(
+                f"the last line of {self.path.name} cannot be read as an entry, so nothing can "
+                "be added after it without breaking the chain. Keep the file and investigate "
+                f"what wrote it: {exc}"
+            ) from None
+        return entry
+
+    def verify_chain(self) -> tuple[bool, str]:
+        """Recompute every hash. Returns (intact, human readable reason).
+
+        A line that cannot even be parsed is itself a broken chain, not a
+        crash: the likeliest way a register gets corrupted is someone opening
+        the file in an editor, and the verdict has to survive whatever they
+        saved, including bytes that are not text.
+        """
+        previous_hash = GENESIS
+        expected_index = 0
+        if not self.path.exists():
+            return True, "0 entries, chain intact"
+        with self.path.open(encoding="utf-8", errors="replace") as handle:
+            for line_number, line in enumerate(handle, start=1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                    index = entry["index"]
+                    core = {k: entry[k] for k in ("index", "kind", "recorded_at", "body")}
+                    recorded_previous = entry["previous_hash"]
+                    recorded_hash = entry["hash"]
+                except (json.JSONDecodeError, KeyError, TypeError):
+                    return False, (
+                        f"line {line_number} cannot be read as an entry; the register has been "
+                        "altered since it was written"
+                    )
+                if index != expected_index:
+                    return False, f"entry {index} is out of order, expected {expected_index}"
+                if recorded_previous != previous_hash:
+                    return False, f"entry {index} does not follow the entry before it"
+                if entry_hash(previous_hash, core) != recorded_hash:
+                    return False, f"entry {index} has been altered since it was written"
+                previous_hash = recorded_hash
+                expected_index += 1
+        return True, f"{expected_index} entries, chain intact"