acquit 0.0.1__py3-none-any.whl

acquit/__init__.py

@@ -0,0 +1,3 @@
+"""Acquit: provably skip unaffected pytest tests, with evidence for every skip."""
+
+__version__ = "0.0.1"

acquit/__main__.py

@@ -0,0 +1,6 @@
+"""Make `python -m acquit` work; the study runner invokes acquit this way."""
+
+from acquit.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

acquit/cli.py

@@ -0,0 +1,239 @@
+"""Command line entry point.
+
+Every failure path converges on a run-all report. The tool may only be wrong
+in the safe direction.
+"""
+
+import argparse
+import json
+import stat
+import sys
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from acquit import __version__
+from acquit.constants import (
+    DEFAULT_REPORT_FILE,
+    DEFAULT_SELECTION_FILE,
+    DEFAULT_WITNESSES_FILE,
+)
+from acquit.errors import AcquitError, ExitCode
+from acquit.explain import explain_lines
+from acquit.gh.comment import run_comment
+from acquit.gh.outputs import run_ci_outputs
+from acquit.graph.model import NodeKind
+from acquit.pipeline import SelectResult, run_select, snapshot_working_tree
+from acquit.policy.model import Finding, RuleId, Scope, ScopeKind
+from acquit.replay import run_replay
+from acquit.report import (
+    RunInfo,
+    SelectionMode,
+    build_report,
+    build_run_all_report,
+    build_run_all_selection,
+    build_selection_doc,
+    build_witnesses_doc,
+    to_canonical_json,
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="acquit")
+    parser.add_argument("--version", action="version", version=f"acquit {__version__}")
+    subcommands = parser.add_subparsers(dest="command", required=True)
+
+    select = subcommands.add_parser("select", help="decide which tests must run for a diff")
+    select.add_argument("--base", required=True, help="base git ref")
+    select.add_argument("--head", help="head git ref, defaults to the working tree")
+    select.add_argument("--report", default=DEFAULT_REPORT_FILE, help="report output path")
+    select.add_argument("--selection", default=DEFAULT_SELECTION_FILE, help="selection output path")
+    select.add_argument("--witnesses", default=DEFAULT_WITNESSES_FILE, help="witnesses output path")
+    select.add_argument("--durations", help="json file mapping test paths to seconds")
+
+    subcommands.add_parser("analyze", help="build the dependency graph and print its health")
+
+    explain = subcommands.add_parser("explain", help="explain the decision for one test file")
+    explain.add_argument("test", help="repo-relative test file path")
+    explain.add_argument("--base", required=True, help="base git ref")
+    explain.add_argument("--head", help="head git ref, defaults to the working tree")
+
+    replay = subcommands.add_parser("replay", help="re-verify the witnesses behind a report")
+    replay.add_argument("report", help="path to an acquit report file")
+    replay.add_argument("--witnesses", default=DEFAULT_WITNESSES_FILE, help="witnesses file path")
+    replay.add_argument("--selection", help="selection file to cross-check against the report")
+
+    comment = subcommands.add_parser(
+        "comment", help="post or update the sticky PR comment for a report; never fails CI"
+    )
+    comment.add_argument("report", help="path to an acquit report file")
+    comment.add_argument("--pr", type=int, help="pull request number; otherwise from GITHUB_REF")
+
+    # A separate subcommand rather than a comment flag: the action calls it on
+    # every run, comment or not, and its contract (runner files) is different.
+    ci_outputs = subcommands.add_parser(
+        "ci-outputs", help="write GitHub action outputs and a step summary; never fails CI"
+    )
+    ci_outputs.add_argument("report", help="path to an acquit report file")
+    ci_outputs.add_argument("selection", help="path to the selection file pytest will obey")
+    return parser
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds")
+
+
+def _load_durations(path_arg: str | None) -> dict[str, float] | None:
+    if path_arg is None:
+        return None
+    data = json.loads(Path(path_arg).read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise AcquitError(f"{path_arg}: durations must be a json object")
+    durations: dict[str, float] = {}
+    for key, value in data.items():
+        if (
+            not isinstance(key, str)
+            or isinstance(value, bool)
+            or not isinstance(value, int | float)
+        ):
+            raise AcquitError(f"{path_arg}: durations must map test paths to seconds")
+        durations[key] = float(value)
+    return durations
+
+
+def _summary(result: SelectResult) -> str:
+    decision = result.decision
+    total = sum(1 for node in result.head.graph.nodes.values() if node.kind is NodeKind.TEST)
+    if decision.mode is SelectionMode.SELECTIVE:
+        return (
+            f"acquit: selective: {len(decision.selected)} selected, "
+            f"{len(decision.always_run)} always-run, "
+            f"{len(decision.skipped)} skipped of {total} tests"
+        )
+    findings = result.outcome.findings
+    if findings:
+        top = "; ".join(f"{finding.rule}:{finding.subject}" for finding in findings[:3])
+        if len(findings) > 3:
+            top += f" and {len(findings) - 3} more"
+    else:
+        top = "no test could be proven unaffected"
+    return f"acquit: run-all: {top} ({total} tests)"
+
+
+def _write_document(path: Path, document: dict[str, Any]) -> None:
+    """Write one document atomically: temp file in place, then replace."""
+    tmp = path.with_name(f"{path.name}.{uuid.uuid4().hex}.tmp")
+    try:
+        tmp.write_text(to_canonical_json(document), encoding="utf-8")
+        try:
+            tmp.replace(path)
+        except PermissionError:
+            # Windows refuses to replace a read-only target; clear the bit.
+            path.chmod(stat.S_IWRITE)
+            tmp.replace(path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def _run_select(args: argparse.Namespace) -> int:
+    created_at = _now()
+    durations = _load_durations(args.durations)
+    result = run_select(args.base, args.head, Path.cwd())
+    graph_hash = result.head.graph.graph_hash
+    report = build_report(result, created_at=created_at, durations=durations)
+    selection = build_selection_doc(
+        result.decision, graph_hash, result.head_sha, result.tree_fingerprint
+    )
+    witnesses = build_witnesses_doc(result.decision, graph_hash)
+    _write_document(Path(args.report), report)
+    _write_document(Path(args.selection), selection)
+    _write_document(Path(args.witnesses), witnesses)
+    print(_summary(result))
+    return ExitCode.OK
+
+
+def _run_analyze() -> int:
+    snapshot = snapshot_working_tree(Path.cwd())
+    graph = snapshot.graph
+    health = {
+        "files": len(snapshot.files),
+        "nodes": graph.digraph.num_nodes(),
+        "edges": graph.digraph.num_edges(),
+        "tests": sum(1 for node in graph.nodes.values() if node.kind is NodeKind.TEST),
+        "tainted": sum(1 for node in graph.nodes.values() if node.tainted),
+        "roots": list(snapshot.index.roots),
+        "graph_hash": graph.graph_hash,
+    }
+    print(to_canonical_json(health), end="")
+    return ExitCode.OK
+
+
+def _run_explain(args: argparse.Namespace) -> int:
+    result = run_select(args.base, args.head, Path.cwd())
+    lines, code = explain_lines(args.test, result)
+    stream = sys.stdout if code is ExitCode.OK else sys.stderr
+    for line in lines:
+        print(line, file=stream)
+    return code
+
+
+def _run_replay(args: argparse.Namespace) -> int:
+    selection = None if args.selection is None else Path(args.selection)
+    lines, code = run_replay(Path(args.report), Path(args.witnesses), selection, Path.cwd())
+    stream = sys.stdout if code is ExitCode.OK else sys.stderr
+    for line in lines:
+        print(line, file=stream)
+    return code
+
+
+def _write_failure_docs(args: argparse.Namespace, error: Exception) -> None:
+    finding = Finding(
+        rule=RuleId.INTERNAL_ERROR,
+        scope=Scope(kind=ScopeKind.GLOBAL),
+        subject="acquit",
+        reason=str(error) or type(error).__name__,
+    )
+    run = RunInfo(base_sha=args.base, head_sha=args.head, created_at=_now())
+    report = build_run_all_report(run, findings=[finding])
+    # The selection is what pytest obeys, so it must convert to run-all first,
+    # and a failure to convert it must be loud, never suppressed.
+    for path, document in ((args.selection, build_run_all_selection()), (args.report, report)):
+        try:
+            _write_document(Path(path), document)
+        except Exception as write_error:
+            print(
+                f"acquit: FAILED to write fail-closed document {path}: {write_error}",
+                file=sys.stderr,
+            )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "select":
+            return _run_select(args)
+        if args.command == "analyze":
+            return _run_analyze()
+        if args.command == "explain":
+            return _run_explain(args)
+        if args.command == "comment":
+            return run_comment(Path(args.report), args.pr)
+        if args.command == "ci-outputs":
+            return run_ci_outputs(Path(args.report), Path(args.selection))
+        return _run_replay(args)
+    except Exception as error:  # fail closed on anything unexpected
+        if args.command in ("comment", "ci-outputs"):
+            # Delivery must never fail CI, even if its own guard rails break.
+            print(f"acquit: warning: {args.command} skipped: {error}", file=sys.stderr)
+            return ExitCode.OK
+        print(f"acquit: internal error, run all tests: {error}", file=sys.stderr)
+        if args.command == "select":
+            _write_failure_docs(args, error)
+        return ExitCode.INTERNAL
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

acquit/config.py

@@ -0,0 +1,105 @@
+"""Acquit's own configuration.
+
+Sources, first hit wins: .acquit.toml at the repo root (top-level keys), then
+[tool.acquit] in pyproject.toml. Missing files mean defaults. Unknown keys are
+rejected: a typo in a soundness-sensitive config must not be silently ignored.
+"""
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from acquit.errors import PolicyError
+
+_KNOWN_KEYS = frozenset({"roots", "assume_inert", "waive"})
+_WAIVER_KEYS = ("rule", "glob", "justification")
+
+
+@dataclass(frozen=True, slots=True)
+class Waiver:
+    rule: str
+    glob: str
+    # Mandatory: a waiver nobody can justify is not reviewable.
+    justification: str
+
+
+@dataclass(frozen=True, slots=True)
+class AcquitConfig:
+    roots: tuple[str, ...] = ()
+    # Globs of resource files the user vouches never affect tests.
+    assume_inert: tuple[str, ...] = ()
+    waivers: tuple[Waiver, ...] = ()
+
+
+def load_config(repo_root: Path) -> AcquitConfig:
+    """Load configuration from repo_root, falling back to defaults.
+
+    Raises PolicyError on unreadable TOML, unknown keys, or malformed waivers.
+    """
+    acquit_toml = repo_root / ".acquit.toml"
+    if acquit_toml.is_file():
+        return _parse(_read_toml(acquit_toml), source=".acquit.toml")
+    pyproject = repo_root / "pyproject.toml"
+    if pyproject.is_file():
+        tool = _read_toml(pyproject).get("tool")
+        section = tool.get("acquit") if isinstance(tool, dict) else None
+        if section is not None:
+            if not isinstance(section, dict):
+                raise PolicyError("pyproject.toml: [tool.acquit] must be a table")
+            return _parse(section, source="pyproject.toml [tool.acquit]")
+    return AcquitConfig()
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("rb") as handle:
+            return tomllib.load(handle)
+    except OSError as error:
+        raise PolicyError(f"{path.name}: cannot read: {error}") from error
+    except tomllib.TOMLDecodeError as error:
+        raise PolicyError(f"{path.name}: invalid TOML: {error}") from error
+
+
+def _parse(data: dict[str, Any], source: str) -> AcquitConfig:
+    unknown = sorted(set(data) - _KNOWN_KEYS)
+    if unknown:
+        raise PolicyError(f"{source}: unknown key(s): {', '.join(unknown)}")
+    return AcquitConfig(
+        roots=_string_tuple(data.get("roots", []), key="roots", source=source),
+        assume_inert=_string_tuple(data.get("assume_inert", []), key="assume_inert", source=source),
+        waivers=_parse_waivers(data.get("waive", []), source=source),
+    )
+
+
+def _string_tuple(value: Any, key: str, source: str) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise PolicyError(f"{source}: {key!r} must be an array of strings")
+    return tuple(value)
+
+
+def _parse_waivers(value: Any, source: str) -> tuple[Waiver, ...]:
+    if not isinstance(value, list):
+        raise PolicyError(f"{source}: 'waive' must be an array of tables")
+    waivers: list[Waiver] = []
+    for position, entry in enumerate(value, start=1):
+        label = f"{source}: waive entry {position}"
+        if not isinstance(entry, dict):
+            raise PolicyError(f"{label} must be a table")
+        if isinstance(entry.get("rule"), str):
+            label = f"{label} (rule {entry['rule']})"
+        unknown = sorted(set(entry) - set(_WAIVER_KEYS))
+        if unknown:
+            raise PolicyError(f"{label}: unknown key(s): {', '.join(unknown)}")
+        missing = [key for key in _WAIVER_KEYS if key not in entry]
+        if missing:
+            raise PolicyError(f"{label}: missing key(s): {', '.join(missing)}")
+        for key in _WAIVER_KEYS:
+            if not isinstance(entry[key], str):
+                raise PolicyError(f"{label}: {key!r} must be a string")
+        if not entry["justification"].strip():
+            raise PolicyError(f"{label}: justification must not be empty")
+        waivers.append(
+            Waiver(rule=entry["rule"], glob=entry["glob"], justification=entry["justification"])
+        )
+    return tuple(waivers)

acquit/constants.py

@@ -0,0 +1,19 @@
+"""Shared constants. Values that appear in more than one module live here."""
+
+from typing import Final
+
+REPORT_SCHEMA: Final = "acquit/report-v1"
+SELECTION_SCHEMA: Final = "acquit/selection-v2"
+WITNESSES_SCHEMA: Final = "acquit/witnesses-v1"
+
+ENV_SELECTION_FILE: Final = "ACQUIT_SELECTION_FILE"
+ENV_CACHE_DIR: Final = "ACQUIT_CACHE_DIR"
+
+DEFAULT_REPORT_FILE: Final = "acquit-report.json"
+DEFAULT_SELECTION_FILE: Final = "acquit-selection.json"
+DEFAULT_WITNESSES_FILE: Final = "acquit-witnesses.json"
+
+COMMENT_MARKER: Final = "<!-- acquit-report -->"
+
+# Refuse selection documents larger than this before reading them.
+SELECTION_SIZE_CAP: Final = 5 * 1024 * 1024

acquit/errors.py

@@ -0,0 +1,38 @@
+"""Error taxonomy and process exit codes.
+
+User-facing failures must degrade to a fail-closed report, never a bare traceback.
+The CLI catches AcquitError (and everything else) and converts it to a run-all decision.
+"""
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    OK = 0
+    USAGE = 2
+    INTERNAL = 3
+    REPLAY_MISMATCH = 4
+
+
+class AcquitError(Exception):
+    """Base for all errors raised by acquit."""
+
+
+class GraphError(AcquitError):
+    """The dependency graph could not be built."""
+
+
+class ResolutionError(AcquitError):
+    """An import statement could not be resolved."""
+
+
+class PolicyError(AcquitError):
+    """The policy engine could not evaluate its rules."""
+
+
+class VcsError(AcquitError):
+    """Git information (refs, diffs, blobs) could not be obtained."""
+
+
+class ParseFailure(GraphError):
+    """A source file could not be parsed into an AST."""

acquit/explain.py

@@ -0,0 +1,104 @@
+"""Explanations for individual test decisions.
+
+Pure rendering over a completed SelectResult: no git, no filesystem. The CLI
+runs the pipeline and hands the outcome here.
+"""
+
+from acquit.errors import ExitCode
+from acquit.graph.model import BuiltGraph, NodeKind
+from acquit.pipeline import SelectResult
+from acquit.policy.model import ScopeKind
+
+_REACHABLE_PREFIX = "reachable-from:"
+
+
+def _dependency_path(graph: BuiltGraph, src: str, dst: str) -> tuple[str, ...] | None:
+    start = graph.index_of.get(src)
+    goal = graph.index_of.get(dst)
+    if start is None or goal is None:
+        return None
+    if start == goal:
+        return (src,)
+    parent: dict[int, int] = {}
+    seen = {start}
+    frontier = [start]
+    while frontier:
+        upcoming: list[int] = []
+        for node in frontier:
+            # Neighbors sorted by path make the BFS tie-break deterministic.
+            neighbors = sorted(
+                graph.digraph.successor_indices(node), key=lambda index: graph.digraph[index].path
+            )
+            for neighbor in neighbors:
+                if neighbor in seen:
+                    continue
+                seen.add(neighbor)
+                parent[neighbor] = node
+                if neighbor == goal:
+                    return _reconstruct(graph, parent, start, goal)
+                upcoming.append(neighbor)
+        frontier = upcoming
+    return None
+
+
+def _reconstruct(
+    graph: BuiltGraph, parent: dict[int, int], start: int, goal: int
+) -> tuple[str, ...]:
+    chain = [goal]
+    while chain[-1] != start:
+        chain.append(parent[chain[-1]])
+    return tuple(graph.digraph[index].path for index in reversed(chain))
+
+
+def _explain_skipped(path: str, witness_id: str, result: SelectResult) -> tuple[str, ...]:
+    witness = next(w for w in result.decision.witnesses if w.id == witness_id)
+    closure = result.decision.closures[witness.closure_hash]
+    changed = ", ".join(witness.changed) if witness.changed else "(empty)"
+    return (
+        f"{path}: skipped",
+        f"  witness: {witness.id}",
+        f"  claim: {witness.claim}",
+        f"  closure: {len(closure)} files, hash {witness.closure_hash}",
+        f"  changed: {changed}",
+    )
+
+
+def _explain_selected(path: str, reasons: tuple[str, ...], graph: BuiltGraph) -> tuple[str, ...]:
+    lines = [f"{path}: selected"]
+    for reason in reasons:
+        lines.append(f"  reason: {reason}")
+        if not reason.startswith(_REACHABLE_PREFIX):
+            continue
+        target = reason.removeprefix(_REACHABLE_PREFIX)
+        chain = _dependency_path(graph, path, target)
+        if chain is None:
+            lines.append("    (reachable only in the base graph)")
+        else:
+            lines.append("    " + " imports ".join(chain))
+    return tuple(lines)
+
+
+def explain_lines(test: str, result: SelectResult) -> tuple[tuple[str, ...], ExitCode]:
+    """Explain why one test was selected, skipped, or forced to run."""
+    path = test.replace("\\", "/").removeprefix("./")
+    node = result.head.graph.nodes.get(path)
+    if node is None or node.kind is not NodeKind.TEST:
+        return ((f"acquit: {path!r} is not a known test file at head",), ExitCode.USAGE)
+
+    global_findings = [f for f in result.outcome.findings if f.scope.kind is ScopeKind.GLOBAL]
+    if global_findings:
+        lines = [f"{path}: runs; global findings force the full suite:"]
+        lines.extend(f"  {f.rule} {f.subject}: {f.reason}" for f in global_findings)
+        return (tuple(lines), ExitCode.OK)
+
+    for skipped in result.decision.skipped:
+        if skipped.path == path:
+            return (_explain_skipped(path, skipped.witness_id, result), ExitCode.OK)
+    for always in result.decision.always_run:
+        if always.path == path:
+            return ((f"{path}: always runs", f"  finding: {always.finding}"), ExitCode.OK)
+    for selected in result.decision.selected:
+        if selected.path == path:
+            return (_explain_selected(path, selected.reasons, result.head.graph), ExitCode.OK)
+    # Unreachable when the decision covers every head test; answer safely anyway.
+    return ((f"{path}: runs (not covered by the decision, run-all default)",), ExitCode.OK)

acquit/gh/__init__.py

@@ -0,0 +1,6 @@
+"""GitHub delivery: the sticky PR comment and the action's runner-file outputs.
+
+Everything in this package is best-effort by design. A delivery failure is a
+warning on stderr and a zero exit, because reporting must never fail CI; the
+fail-closed guarantees all live upstream in selection and replay.
+"""