warrant-cli 0.1.0__py3-none-any.whl

warrant/gate.py

@@ -0,0 +1,151 @@
+"""The gatekeeper: deterministic rules that turn evidence into warrants or denials."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from warrant import __version__
+from warrant.config import STRENGTHS
+from warrant.errors import WarrantError
+from warrant.hashing import short
+
+RANK = {strength: rank for rank, strength in enumerate(STRENGTHS)}
+GATEKEEPER = f"gatekeeper:warrant-cli/{__version__}"
+
+
+@dataclass
+class Decision:
+    action: str
+    workspace: str
+    baseline: str
+    approval: dict | None
+    granted: bool = False
+    qualifier: str | None = None
+    reasons: list[str] = field(default_factory=list)
+    builder_reasons: list[str] = field(default_factory=list)  # the same, naming hidden checks only by promise
+    rebuttals: list[str] = field(default_factory=list)
+    grounds: list[str] = field(default_factory=list)  # evidence digests
+    passed: list[str] = field(default_factory=list)  # the checks that evidence came from
+    checks: list[str] = field(default_factory=list)
+
+    def deny(self, reason: str, builder_reason: str | None = None) -> None:
+        if reason not in self.reasons:
+            self.reasons.append(reason)
+        builder_reason = builder_reason or reason
+        if builder_reason not in self.builder_reasons:
+            self.builder_reasons.append(builder_reason)
+
+
+def latest_results(project, workspace: str) -> dict[str, dict]:
+    """The most recent result for each current check on exactly this workspace."""
+    current = {check.id: check.digest for check in project.checks}
+    results = {}
+    for entry in project.ledger.entries():
+        if entry["type"] != "verify" or entry["data"]["workspace"] != workspace:
+            continue
+        for result in entry["data"]["results"]:
+            if current.get(result["check"]) == result["digest"]:
+                results[result["check"]] = result
+    return results
+
+
+def evaluate(project, action: str, workspace: str) -> Decision:
+    gate = project.config.gates.get(action)
+    if gate is None:
+        raise WarrantError(f"no gate named {action!r}; warrant.toml defines {', '.join(project.config.gates)}")
+    state, approval = project.approval_state()
+    decision = Decision(action, workspace, project.baseline_digest(), approval)
+
+    if state == "missing":
+        decision.deny("nobody has approved the intent and checks yet")
+    elif state == "stale":
+        decision.deny("changed since approval: " + "; ".join(project.changes_since(approval)))
+
+    for prerequisite in gate.after:
+        if not evaluate(project, prerequisite, workspace).granted:
+            decision.deny(f"needs a {prerequisite} warrant first")
+
+    results = latest_results(project, workspace)
+    selected = [check for check in project.checks if any(check.matches(s) for s in gate.checks)]
+    decision.checks = [check.id for check in selected]
+    if not selected:
+        decision.deny("this gate selects no checks")
+    for check in selected:
+        _require_pass(decision, check, results.get(check.id))
+        if RANK[check.strength] < RANK[gate.min_strength]:
+            needs = f"is only {check.strength}; {action} needs {gate.min_strength} evidence"
+            decision.deny(f"{check.id} {needs}", f"{_named(check)} {needs}")
+
+    covered = {clause for check in selected for clause in check.covers}
+    uncovered = [clause for clause in project.intent.ids if clause not in covered]
+    if uncovered and gate.cover_all_intent:
+        decision.deny("no check covers " + ", ".join(uncovered))
+    elif uncovered:
+        decision.rebuttals.append(f"the {action} gate does not check " + ", ".join(uncovered))
+
+    if gate.require_regressions:
+        for incident in project.incidents():
+            regressions = [check for check in project.checks if incident["id"] in check.regression_for]
+            if not regressions:
+                decision.deny(f"incident {incident['id']} has no regression check")
+            for check in regressions:
+                _require_pass(decision, check, results.get(check.id))
+
+    def only(predicate) -> list[str]:
+        return [
+            clause for clause in project.intent.ids
+            if clause in covered and all(predicate(check) for check in selected if clause in check.covers)
+        ]
+
+    visible_only = only(lambda check: check.visibility == "public")
+    if visible_only:
+        decision.rebuttals.append("only checks the builder could see cover " + ", ".join(visible_only))
+    judged_only = only(lambda check: check.strength == "judged")
+    if judged_only:
+        decision.rebuttals.append("only judged, non-reproducible evidence covers " + ", ".join(judged_only))
+
+    if selected:
+        decision.qualifier = min((check.strength for check in selected), key=RANK.__getitem__)
+    decision.granted = not decision.reasons
+    return decision
+
+
+def record(project, decision: Decision, label: str) -> dict:
+    """Write the decision to the ledger, structured the way Toulmin structures an argument."""
+    approval = decision.approval
+    verb = "keeps" if decision.granted else "has not shown that it keeps"
+    data = {
+        "action": decision.action,
+        "granted": decision.granted,
+        "claim": f"Workspace {short(decision.workspace)} ({label}) {verb} every promise the {decision.action} gate requires.",
+        "workspace": decision.workspace,
+        "label": label,
+        "grounds": decision.grounds,
+        "rule": {"gate": decision.action, **project.config.gates[decision.action].policy()},
+        "backing": {
+            "baseline": decision.baseline,
+            "approvedBy": approval["data"]["by"] if approval else None,
+            "approvalEntry": approval["seq"] if approval else None,
+            "gatekeeper": f"warrant-cli/{__version__}",
+        },
+        "qualifier": decision.qualifier if decision.granted else None,
+        "rebuttals": decision.rebuttals,
+        "reasons": decision.reasons,
+    }
+    return project.ledger.append("warrant" if decision.granted else "denial", GATEKEEPER, data)
+
+
+def _require_pass(decision: Decision, check, result: dict | None) -> None:
+    if result is None:
+        decision.deny(f"{check.id} has not been run on this workspace", f"{_named(check)} has not been run on this workspace")
+    elif result["result"] != "pass":
+        verb = "failed" if result["result"] == "fail" else "could not run"
+        decision.deny(f"{check.id} {verb}", f"{_named(check)} {verb}")
+    elif result["evidence"] not in decision.grounds:
+        decision.grounds.append(result["evidence"])
+        decision.passed.append(check.id)
+
+
+def _named(check) -> str:
+    """How a builder hears about a check: hidden ones only by the promises they cover."""
+    return check.id if check.visibility == "public" else "a hidden check on " + ", ".join(check.covers)

warrant/hashing.py

@@ -0,0 +1,85 @@
+"""Content addressing: digests of JSON values and of directory trees."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import stat
+from pathlib import Path
+
+from warrant.errors import WarrantError
+
+# Never part of a snapshot: version control, caches, local environments and Warrant's own state.
+EXCLUDED_NAMES = frozenset({
+    ".git", ".hg", ".svn", ".warrant", "__pycache__", ".pytest_cache", ".mypy_cache",
+    ".ruff_cache", ".venv", "venv", "node_modules", ".DS_Store",
+})
+
+
+def canonical_json(value) -> bytes:
+    """The single byte encoding of a JSON value that every digest is computed over."""
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def digest_bytes(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def digest_json(value) -> str:
+    return digest_bytes(canonical_json(value))
+
+
+def hex_part(digest: str) -> str:
+    return digest.partition(":")[2]
+
+
+def short(digest: str | None) -> str:
+    return f"sha256:{hex_part(digest)[:12]}" if digest else "none"
+
+
+def tree_digest(root: Path) -> str:
+    """Digest of every file's path, content and executable bit under root."""
+    if not root.is_dir():
+        raise WarrantError(f"{root} is not a directory")
+    listing = "".join(f"{kind} {relative}\n" for relative, kind in sorted(_entries(root)))
+    return digest_bytes(listing.encode("utf-8"))
+
+
+def copy_tree(source: Path, destination: Path) -> None:
+    shutil.copytree(source, destination, symlinks=True, ignore=shutil.ignore_patterns(*EXCLUDED_NAMES))
+
+
+def _entries(root: Path):
+    for current, dirs, files in os.walk(root):
+        base = Path(current)
+        descend = []
+        for name in sorted(dirs):
+            if name in EXCLUDED_NAMES:
+                continue
+            path = base / name
+            if path.is_symlink():
+                yield _relative(root, path), _link(path)
+            else:
+                descend.append(name)
+        dirs[:] = descend
+        for name in files:
+            if name in EXCLUDED_NAMES:
+                continue
+            path = base / name
+            if path.is_symlink():
+                yield _relative(root, path), _link(path)
+                continue
+            kind = "exec" if path.stat().st_mode & stat.S_IXUSR else "file"
+            with path.open("rb") as handle:
+                content = hashlib.file_digest(handle, "sha256").hexdigest()
+            yield _relative(root, path), f"{kind} {content}"
+
+
+def _relative(root: Path, path: Path) -> str:
+    return path.relative_to(root).as_posix()
+
+
+def _link(path: Path) -> str:
+    return "link " + hashlib.sha256(os.readlink(path).encode("utf-8")).hexdigest()

warrant/intent.py

@@ -0,0 +1,104 @@
+"""Intent documents: Markdown in which every promise is a list item that starts with an ID."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from warrant.errors import WarrantError
+from warrant.hashing import digest_bytes
+
+CLAUSE = re.compile(r"^[-*] +([A-Z]{1,3}[0-9]{1,4}): +(\S.*)$")
+INFORMATIONAL_SECTIONS = ("out of scope", "non-goals", "non goals")
+
+
+@dataclass
+class Clause:
+    id: str
+    text: str
+    section: str
+    line: int
+
+
+@dataclass
+class Intent:
+    path: Path
+    title: str
+    meta: dict[str, str]
+    clauses: list[Clause]
+    digest: str
+
+    @property
+    def ids(self) -> list[str]:
+        return [clause.id for clause in self.clauses]
+
+    def clause(self, clause_id: str) -> Clause | None:
+        return next((clause for clause in self.clauses if clause.id == clause_id), None)
+
+
+def parse_intent(path: Path) -> Intent:
+    try:
+        raw = path.read_bytes()
+    except FileNotFoundError:
+        raise WarrantError(f"intent file not found: {path}") from None
+    lines = raw.decode("utf-8").split("\n")
+    meta, start = _front_matter(lines, path)
+    title = meta.get("title", "")
+    section = ""
+    clauses: list[Clause] = []
+    defined_on: dict[str, int] = {}
+    current: Clause | None = None
+    fenced = False
+    for number, line in enumerate(lines[start:], start=start + 1):
+        line = line.rstrip("\r")
+        if line.lstrip().startswith(("```", "~~~")):
+            fenced, current = not fenced, None
+            continue
+        if fenced:
+            continue
+        if line.startswith("#"):
+            current = None
+            level = len(line) - len(line.lstrip("#"))
+            heading = line[level:].strip()
+            if level == 1 and not title:
+                title = heading
+            elif level == 2:
+                section = heading
+            continue
+        match = CLAUSE.match(line)
+        if match:
+            current = None
+            if section.lower().startswith(INFORMATIONAL_SECTIONS):
+                continue
+            clause_id, text = match.groups()
+            if clause_id in defined_on:
+                raise WarrantError(
+                    f"{path.name}:{number}: clause {clause_id} is already defined on line {defined_on[clause_id]}"
+                )
+            defined_on[clause_id] = number
+            current = Clause(clause_id, text.strip(), section, number)
+            clauses.append(current)
+        elif current is not None and line[:1] in (" ", "\t") and line.strip():
+            current.text += " " + line.strip()
+        else:
+            current = None
+    if not clauses:
+        raise WarrantError(
+            f"{path.name} has no promises. Write each one as a list item that starts with an ID, like '- G1: ...'"
+        )
+    return Intent(path, title or path.stem, meta, clauses, digest_bytes(raw))
+
+
+def _front_matter(lines: list[str], path: Path) -> tuple[dict[str, str], int]:
+    if not lines or lines[0].strip() != "---":
+        return {}, 0
+    for index in range(1, len(lines)):
+        if lines[index].strip() == "---":
+            meta = {}
+            for entry in lines[1:index]:
+                key, separator, value = entry.partition(":")
+                if separator and key.strip():
+                    meta[key.strip()] = value.strip()
+            return meta, index + 1
+    raise WarrantError(f"{path.name}: front matter opens with '---' but never closes")

warrant/ledger.py

@@ -0,0 +1,106 @@
+"""The ledger: an append-only, hash-chained record that principals read instead of code."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from warrant.errors import WarrantError
+from warrant.hashing import canonical_json, digest_bytes, digest_json, hex_part, short
+
+GENESIS = "sha256:" + "0" * 64
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class Ledger:
+    def __init__(self, directory: Path):
+        self.directory = directory
+        self.path = directory / "ledger.jsonl"
+        self.evidence_dir = directory / "evidence"
+
+    def entries(self) -> list[dict]:
+        entries = []
+        for number, line in enumerate(self._lines(), start=1):
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError as error:
+                raise WarrantError(f"{self.path}: entry {number} is not valid JSON ({error.msg})") from None
+        return entries
+
+    def head(self) -> str:
+        lines = self._lines()
+        return digest_bytes(lines[-1].encode("utf-8")) if lines else GENESIS
+
+    def append(self, kind: str, actor: str, data: dict) -> dict:
+        lines = self._lines()
+        entry = {
+            "seq": len(lines) + 1,
+            "time": utc_now(),
+            "type": kind,
+            "actor": actor,
+            "prev": digest_bytes(lines[-1].encode("utf-8")) if lines else GENESIS,
+            "data": data,
+        }
+        self.directory.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(canonical_json(entry).decode("utf-8") + "\n")
+        return entry
+
+    def put_evidence(self, statement: dict) -> str:
+        digest = digest_json(statement)
+        path = self._evidence_path(digest)
+        if not path.exists():
+            self.evidence_dir.mkdir(parents=True, exist_ok=True)
+            text = json.dumps(statement, indent=2, sort_keys=True, ensure_ascii=False)
+            path.write_text(text + "\n", encoding="utf-8")
+        return digest
+
+    def get_evidence(self, digest: str) -> dict:
+        try:
+            statement = json.loads(self._evidence_path(digest).read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            raise WarrantError(f"evidence {short(digest)} is missing") from None
+        except json.JSONDecodeError:
+            raise WarrantError(f"evidence {short(digest)} is not valid JSON") from None
+        if digest_json(statement) != digest:
+            raise WarrantError(f"evidence {short(digest)} no longer matches its digest, so it was changed")
+        return statement
+
+    def problems(self) -> list[str]:
+        """Everything that shows the ledger or its evidence was altered outside Warrant."""
+        problems = []
+        previous = GENESIS
+        for number, line in enumerate(self._lines(), start=1):
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                problems.append(f"entry {number} is not valid JSON")
+                previous = digest_bytes(line.encode("utf-8"))
+                continue
+            if entry.get("seq") != number:
+                problems.append(f"entry {number} carries sequence number {entry.get('seq')}")
+            if entry.get("prev") != previous:
+                problems.append(f"entry {number} does not chain to the entry before it")
+            if canonical_json(entry).decode("utf-8") != line:
+                problems.append(f"entry {number} is not in canonical form, so it was edited outside Warrant")
+            previous = digest_bytes(line.encode("utf-8"))
+            if entry.get("type") == "verify":
+                for result in entry.get("data", {}).get("results", []):
+                    try:
+                        self.get_evidence(result.get("evidence", ""))
+                    except WarrantError as error:
+                        problems.append(f"entry {number}: {error}")
+        return problems
+
+    def _lines(self) -> list[str]:
+        if not self.path.exists():
+            return []
+        # Split on "\n" only: str.splitlines() also breaks on characters that canonical JSON leaves unescaped.
+        return [line for line in self.path.read_text(encoding="utf-8").split("\n") if line]
+
+    def _evidence_path(self, digest: str) -> Path:
+        return self.evidence_dir / f"{hex_part(digest)}.json"

warrant/project.py

@@ -0,0 +1,81 @@
+"""A loaded project: configuration, intent, checks and ledger, and the baseline they form."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from warrant.checks import Check, load_checks
+from warrant.config import CONFIG_NAME, Config, load_config
+from warrant.errors import WarrantError
+from warrant.hashing import digest_json
+from warrant.intent import Intent, parse_intent
+from warrant.ledger import Ledger
+
+
+@dataclass
+class Project:
+    config: Config
+    intent: Intent
+    checks: list[Check]
+    ledger: Ledger
+
+    def baseline(self) -> dict:
+        """Everything the principal approves: the intent, each check, and the gate policy."""
+        return {
+            "intent": self.intent.digest,
+            "checks": {check.id: check.digest for check in self.checks},
+            "policy": self.config.policy_digest(),
+        }
+
+    def baseline_digest(self) -> str:
+        return digest_json(self.baseline())
+
+    def approval_state(self) -> tuple[str, dict | None]:
+        """("missing" | "stale" | "current", the latest approval entry). Only the latest approval counts."""
+        approval = next((e for e in reversed(self.ledger.entries()) if e["type"] == "approve"), None)
+        if approval is None:
+            return "missing", None
+        if approval["data"]["baseline"] != self.baseline_digest():
+            return "stale", approval
+        return "current", approval
+
+    def changes_since(self, approval: dict) -> list[str]:
+        approved, current = approval["data"], self.baseline()
+        changes = []
+        if approved["intent"] != current["intent"]:
+            changes.append(f"{self.intent.path.name} changed")
+        for check_id in sorted(set(approved["checks"]) | set(current["checks"])):
+            before, after = approved["checks"].get(check_id), current["checks"].get(check_id)
+            if before is None:
+                changes.append(f"check {check_id} was added")
+            elif after is None:
+                changes.append(f"check {check_id} was removed")
+            elif before != after:
+                changes.append(f"check {check_id} changed")
+        if approved["policy"] != current["policy"]:
+            changes.append("the gate policy changed")
+        return changes
+
+    def coverage(self) -> dict[str, list[Check]]:
+        return {clause.id: [c for c in self.checks if clause.id in c.covers] for clause in self.intent.clauses}
+
+    def incidents(self) -> list[dict]:
+        return [
+            {**entry["data"], "time": entry["time"], "seq": entry["seq"]}
+            for entry in self.ledger.entries()
+            if entry["type"] == "incident"
+        ]
+
+
+def find_root(start: Path) -> Path:
+    for candidate in (start, *start.parents):
+        if (candidate / CONFIG_NAME).is_file():
+            return candidate
+    raise WarrantError(f"no {CONFIG_NAME} in {start} or any directory above it; run 'warrant init' first")
+
+
+def load_project(root: Path) -> Project:
+    config = load_config(root)
+    intent = parse_intent(config.intent_path)
+    return Project(config, intent, load_checks(config, intent), Ledger(config.ledger_dir))