sourcebound 1.2.1__py3-none-any.whl

clean_docs/capabilities.py

@@ -0,0 +1,200 @@
+"""Public capability registry rendered into the sourcebound README."""
+
+PRODUCT_OVERVIEW = (
+    "A stale sentence does not fail loudly. It keeps a straight face after the code has moved on, "
+    "and reviewers have no mechanical way to identify the false claim. Sourcebound gives each "
+    "protected fact a source, then checks that relationship again in CI.\n\n"
+    "Declared sources own the protected facts. A packaged policy enforces the deterministic form "
+    "floor; authored judgment still owns motivation, pedagogy, and voice. Static adapters read "
+    "common code and schema formats, while declared commands run under explicit process controls. "
+    "The engine can repair bound regions, rank static count and column candidates, enforce accepted "
+    "source-claim relationships, and project canonical text and visual records into purpose-built "
+    "human and agent surfaces with local receipts."
+)
+
+ASSURANCE_BOUNDARIES = (
+    {
+        "surface": "Generated region",
+        "sourcebound proves": "Rendered region bytes match configured source evidence",
+        "sourcebound does not prove": "Authored prose outside the region is accurate or complete",
+    },
+    {
+        "surface": "Legacy command pin (`type: claim`)",
+        "sourcebound proves": "Allowlisted command output matches the configured expected value and the document anchor exists",
+        "sourcebound does not prove": "The prose under that anchor states the command result",
+    },
+    {
+        "surface": "Symbol reference",
+        "sourcebound proves": "The configured source path or Python symbol exists",
+        "sourcebound does not prove": "The surrounding prose describes that symbol accurately",
+    },
+    {
+        "surface": "Repository catalog",
+        "sourcebound proves": "Detected additions, removals, and replacements stay visible",
+        "sourcebound does not prove": "Every cataloged item needs or has a reader-facing explanation",
+    },
+    {
+        "surface": "Accepted static source claim",
+        "sourcebound proves": "The documented count or identifier set matches its accepted source locator",
+        "sourcebound does not prove": "A ranked candidate names the right semantic relationship",
+    },
+    {
+        "surface": "Binding sensitivity receipt",
+        "sourcebound proves": "One static check becomes stale after one independently frozen source fact changes",
+        "sourcebound does not prove": "The document and source describe the same concept or that the relationship should be accepted",
+    },
+    {
+        "surface": "Declared review contract",
+        "sourcebound proves": "At two immutable refs, repository-declared source locators changed without every declared target locator changing",
+        "sourcebound does not prove": "The target is stale, a co-change is semantically correct, or the locators describe the same concept",
+    },
+    {
+        "surface": "Pull-request verdict",
+        "sourcebound proves": "Static configured checks and changed-surface evidence produce the reported state at one pinned commit",
+        "sourcebound does not prove": "Unbound prose, skipped processes, semantic relationships, or authored judgment are correct",
+    },
+    {
+        "surface": "Packaged writing policy",
+        "sourcebound proves": "Implemented deterministic rules pass",
+        "sourcebound does not prove": "Motivation, pedagogy, personality, or usefulness pass judgment",
+    },
+    {
+        "surface": "Authored purpose and scope",
+        "sourcebound proves": "Declared markers and configured relationships remain intact",
+        "sourcebound does not prove": "The repository chose the right goals, audience, or priority",
+    },
+    {
+        "surface": "Opt-in feedback loop",
+        "sourcebound proves": "Validated operational envelopes and improvement-state receipts satisfy their closed schemas",
+        "sourcebound does not prove": "Observed behavior establishes causality, authorizes purpose, or makes a candidate change correct",
+    },
+)
+
+SUPPORTED_BINDINGS = {
+    "command-pin": {
+        "binding": "command pin (`type: claim`)",
+        "source": "Allowlisted JSON command",
+        "output": "Configured assertion, with optional declared prose at a document anchor",
+        "check": "Compare typed expected and observed values; verify declared anchored prose",
+    },
+    "region": {
+        "binding": "region",
+        "source": "Static Python, structured data, text, or paths",
+        "output": "Table, list, scalar, or fenced text",
+        "check": "Re-render and compare",
+    },
+    "symbol": {
+        "binding": "symbol",
+        "source": "Static path or Python symbol",
+        "output": "Reference at a document anchor",
+        "check": "Resolve the cited locator",
+    },
+}
+
+CLI_REFERENCE = (
+    {
+        "command": "audit",
+        "job": "Assess documentation and enforce adopted scopes",
+        "writes": "with --update-baseline",
+        "example": "sourcebound audit --format json",
+    },
+    {"command": "residue", "job": "Manage private cross-project residue matching", "writes": "with init-local", "example": "sourcebound residue status"},
+    {"command": "residue status", "job": "Report whether private residue matching is active", "writes": "no", "example": "sourcebound residue status"},
+    {"command": "residue init-local", "job": "Create a permission-restricted private residue template", "writes": "yes", "example": "sourcebound residue init-local"},
+    {"command": "inventory", "job": "List detected repository surfaces and coverage", "writes": "no", "example": "sourcebound inventory --format json"},
+    {"command": "claims", "job": "Rank and verify static count and column claims", "writes": "no", "example": "sourcebound claims --format json"},
+    {"command": "binding", "job": "Inspect one proposed source relationship", "writes": "no", "example": "sourcebound binding --help"},
+    {
+        "command": "binding sensitivity",
+        "job": "Test whether one static check depends on a frozen source fact",
+        "writes": "no",
+        "example": "sourcebound binding sensitivity --help",
+    },
+    {"command": "context", "job": "Compile provider-neutral evidence packets", "writes": "no", "example": "sourcebound context --help"},
+    {"command": "context compile", "job": "Compile a bounded source-addressed context bundle", "writes": "no", "example": "sourcebound context compile --request context-request.json"},
+    {"command": "review", "job": "Turn review observations into testable improvement candidates", "writes": "with --out", "example": "sourcebound review --help"},
+    {"command": "review candidates", "job": "Compile documentation and product test candidates from one review", "writes": "with --out", "example": "sourcebound review candidates --input review-observations.json"},
+    {"command": "review ledger", "job": "Initialize an append-only review denominator", "writes": "with init", "example": "sourcebound review ledger --help"},
+    {"command": "review ledger init", "job": "Initialize a review ledger before it reaches a protected branch", "writes": "yes", "example": "sourcebound review ledger init --input review.json --out events.json"},
+    {"command": "review lifecycle", "job": "Track assessment-only candidate status with typed evidence", "writes": "with init or transition", "example": "sourcebound review lifecycle --help"},
+    {"command": "review lifecycle init", "job": "Initialize a lifecycle record for one candidate set", "writes": "yes", "example": "sourcebound review lifecycle init --input review.json --out lifecycle.json"},
+    {"command": "review lifecycle transition", "job": "Apply one evidence-backed candidate transition", "writes": "yes", "example": "sourcebound review lifecycle transition --help"},
+    {"command": "review lifecycle check", "job": "Check a lifecycle record against its candidate set", "writes": "no", "example": "sourcebound review lifecycle check --input review.json --state lifecycle.json"},
+    {"command": "init", "job": "Write a source-bound documentation baseline", "writes": "yes", "example": "sourcebound init --no-model"},
+    {"command": "explain", "job": "Explain a finding or coverage state", "writes": "no", "example": "sourcebound explain purpose-contract --format json"},
+    {"command": "doctor", "job": "Check repository and integration readiness", "writes": "with --bundle", "example": "sourcebound doctor --bundle doctor.json"},
+    {"command": "verify", "job": "Write a local deterministic outcome receipt", "writes": "with --out", "example": "sourcebound verify --out outcome.json"},
+    {"command": "benchmark", "job": "Measure changed-check time and memory budgets", "writes": "with --out", "example": "sourcebound benchmark --base HEAD~1 --head HEAD"},
+    {"command": "derive", "job": "Preview or write generated region changes", "writes": "with --write", "example": "sourcebound derive --check"},
+    {"command": "drive", "job": "Repair bound regions after deterministic policy checks", "writes": "yes", "example": "sourcebound drive"},
+    {"command": "plan", "job": "Build an immutable read-only documentation impact plan", "writes": "no", "example": "sourcebound plan --base origin/main --head HEAD --format json"},
+    {
+        "command": "verdict",
+        "job": "Compose one coverage-stating static PR verdict",
+        "writes": "no",
+        "example": "sourcebound verdict --base origin/main --head HEAD --format json",
+    },
+    {"command": "check", "job": "Fail on binding drift or uncovered changed surface", "writes": "no", "example": "sourcebound check --changed --base origin/main --head HEAD"},
+    {"command": "project", "job": "Regenerate configured documentation projections", "writes": "unless --check", "example": "sourcebound project --check"},
+    {"command": "eval", "job": "Score human tasks and replayable agent round trips", "writes": "with --history or live recording", "example": "sourcebound eval --fixtures .sourcebound/eval.yml"},
+    {"command": "release", "job": "Render typed release facts between immutable refs", "writes": "no", "example": "sourcebound release --from v0.9.0 --to HEAD"},
+    {"command": "migrate", "job": "Upgrade a prior manifest with rollback backup", "writes": "with --write or --rollback", "example": "sourcebound migrate --write"},
+    {"command": "feedback", "job": "Manage opt-in operational feedback", "writes": "yes", "example": "sourcebound feedback status"},
+    {"command": "feedback enable", "job": "Consent to a named feedback sink", "writes": "yes", "example": "sourcebound feedback enable --sink local"},
+    {"command": "feedback status", "job": "Show feedback consent and pending counts", "writes": "no", "example": "sourcebound feedback status"},
+    {"command": "feedback preview", "job": "Print exact pending envelope bytes", "writes": "no", "example": "sourcebound feedback preview"},
+    {"command": "feedback flush", "job": "Deliver pending feedback envelopes", "writes": "yes", "example": "sourcebound feedback flush"},
+    {"command": "feedback disable", "job": "Remove feedback delivery authority", "writes": "yes", "example": "sourcebound feedback disable"},
+    {"command": "feedback rotate", "job": "Replace the feedback installation identifier", "writes": "yes", "example": "sourcebound feedback rotate"},
+    {"command": "feedback purge", "job": "Delete local feedback state", "writes": "yes", "example": "sourcebound feedback purge"},
+    {"command": "feedback signal", "job": "Validate or ingest aggregate behavior signals", "writes": "varies", "example": "sourcebound feedback signal validate --input signal.json"},
+    {"command": "feedback signal prepare", "job": "Add a canonical content-derived signal ID", "writes": "no", "example": "sourcebound feedback signal prepare --input signal-body.json"},
+    {"command": "feedback signal validate", "job": "Validate one aggregate behavior signal", "writes": "no", "example": "sourcebound feedback signal validate --input signal.json"},
+    {"command": "feedback signal ingest", "job": "Create an observed improvement case", "writes": "yes", "example": "sourcebound feedback signal ingest --input signal.json"},
+    {"command": "feedback case", "job": "Advance a verified improvement case", "writes": "yes", "example": "sourcebound feedback case transition --case ID --to reproduced --receipt receipt.json"},
+    {"command": "feedback case transition", "job": "Apply one adjacent evidence-backed state transition", "writes": "yes", "example": "sourcebound feedback case transition --case ID --to reproduced --receipt receipt.json"},
+    {"command": "emit", "job": "Project the manifest into another format", "writes": "yes", "example": "sourcebound emit --help"},
+    {
+        "command": "emit stepwise-skill",
+        "job": "Write a manifest-derived stepwise skill package",
+        "writes": "yes",
+        "example": "sourcebound emit stepwise-skill --out skill",
+    },
+    {
+        "command": "emit llms-txt",
+        "job": "Write an index of source-bound documents",
+        "writes": "yes",
+        "example": "sourcebound emit llms-txt --out llms.txt",
+    },
+    {"command": "standard", "job": "Build or verify the bundled policy pack", "writes": "varies", "example": "sourcebound standard --help"},
+    {"command": "standard build", "job": "Compile the canonical standard", "writes": "yes", "example": "sourcebound standard build"},
+    {"command": "standard check", "job": "Fail when the policy pack is stale", "writes": "no", "example": "sourcebound standard check"},
+)
+
+EVALUATION_SCORERS = (
+    {
+        "scorer": "command",
+        "input": "Allowlisted command and documented excerpt",
+        "passes when": "Exit code and required output match",
+    },
+    {
+        "scorer": "configuration",
+        "input": "Recorded manifest and fixture repository",
+        "passes when": "Schema validation and check pass",
+    },
+    {
+        "scorer": "structured-output",
+        "input": "Recorded JSON and expected value",
+        "passes when": "Parsed values match exactly",
+    },
+    {
+        "scorer": "cited-limit",
+        "input": "Recorded answer, canonical citation, and forbidden inferences",
+        "passes when": "The answer cites the declared limit without inferring support",
+    },
+    {
+        "scorer": "mutation-red",
+        "input": "Provider proposal, frozen fact, and disposable static repository",
+        "passes when": "The sensitivity state matches without authorizing the relationship",
+    },
+)

clean_docs/changed.py

@@ -0,0 +1,452 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from contextlib import nullcontext
+from dataclasses import asdict, dataclass
+from fnmatch import fnmatch
+from pathlib import Path
+
+from clean_docs.engine import evaluate
+from clean_docs.errors import ConfigurationError, ExtractionError
+from clean_docs.execution import ExecutionPolicy
+from clean_docs.claims import scan_source_claims
+from clean_docs.inventory import (
+    PUBLIC_SURFACE_KINDS,
+    InventoryItem,
+    scan_inventory,
+)
+from clean_docs.manifest import load_manifest
+from clean_docs.models import Binding, ClaimBinding, RegionBinding
+from clean_docs.regions import atomic_write
+from clean_docs.plugins import discover_plugin_items, merge_plugin_inventory
+from clean_docs.snapshot import RepositorySnapshot
+
+
+CHANGED_CHECK_BUDGET_SECONDS = 5.0
+
+
+@dataclass(frozen=True)
+class ChangedFinding:
+    id: str
+    rule: str
+    doc: str
+    source: str
+    locator: str
+    message: str
+    repair: str
+
+
+@dataclass(frozen=True)
+class ChangedReport:
+    base: str
+    head: str
+    project: str
+    changed_files: tuple[str, ...]
+    required: tuple[ChangedFinding, ...]
+    gaps: tuple[ChangedFinding, ...]
+    ignored: tuple[ChangedFinding, ...]
+    dependencies: dict[str, tuple[str, ...]]
+    cache_hits: int = 0
+    cache_misses: int = 0
+
+    @property
+    def ok(self) -> bool:
+        return not self.required and not self.gaps
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "schema": "sourcebound.changed.v1",
+            "ok": self.ok,
+            "base": self.base,
+            "head": self.head,
+            "project": self.project,
+            "changed_files": list(self.changed_files),
+            "required": [asdict(item) for item in self.required],
+            "gaps": [asdict(item) for item in self.gaps],
+            "ignored": [asdict(item) for item in self.ignored],
+            "dependencies": {
+                binding: list(paths) for binding, paths in sorted(self.dependencies.items())
+            },
+        }
+
+
+def _finding_id(rule: str, doc: str, source: str, locator: str) -> str:
+    value = json.dumps([rule, doc, source, locator], separators=(",", ":"))
+    return hashlib.sha256(value.encode()).hexdigest()
+
+
+def _affected_paths(
+    binding: Binding,
+    changed: tuple[str, ...],
+    manifest_path: str,
+) -> tuple[str, ...]:
+    matched = {path for path in changed if path in {binding.doc.as_posix(), manifest_path}}
+    if isinstance(binding, ClaimBinding):
+        matched.update(changed)
+    else:
+        source = binding.source
+        if (
+            isinstance(binding, RegionBinding)
+            and binding.extractor in {"repository-inventory", "repository-overview"}
+        ):
+            matched.update(changed)
+        elif source.glob:
+            matched.update(path for path in changed if fnmatch(path, source.glob))
+        elif source.path.as_posix() in changed:
+            matched.add(source.path.as_posix())
+    return tuple(sorted(matched))
+
+
+def _git(root: Path, *args: str) -> str:
+    proc = subprocess.run(
+        ["git", "-C", str(root), *args],
+        text=True,
+        capture_output=True,
+        timeout=30,
+        check=False,
+    )
+    if proc.returncode != 0:
+        detail = proc.stderr.strip() or proc.stdout.strip() or "unknown git error"
+        raise ExtractionError(f"git {' '.join(args)} failed: {detail}")
+    return proc.stdout
+
+
+def _cache_root(root: Path) -> Path:
+    git_dir = _git(root, "rev-parse", "--git-dir").strip()
+    path = Path(git_dir)
+    if not path.is_absolute():
+        path = root / path
+    return path.resolve() / "sourcebound-cache"
+
+
+def _inventory(
+    root: Path,
+    ref: str,
+    project: Path,
+    *,
+    use_cache: bool,
+    materialized_root: Path | None = None,
+    execution_policy: ExecutionPolicy = ExecutionPolicy.TRUSTED,
+) -> tuple[tuple[InventoryItem, ...], bool]:
+    key_payload = json.dumps(
+        {
+            "extractor": "repository-inventory@1",
+            "parameters": {"project": project.as_posix()},
+            "source": ref,
+            "execution_policy": execution_policy.value,
+        },
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+    key = hashlib.sha256(key_payload.encode()).hexdigest()
+    cache_path = _cache_root(root) / f"inventory-{key}.json"
+    if use_cache and cache_path.is_file():
+        try:
+            raw = json.loads(cache_path.read_text(encoding="utf-8"))
+            if (
+                isinstance(raw, dict)
+                and raw.get("key") == key
+                and isinstance(raw.get("items"), list)
+            ):
+                return tuple(InventoryItem(**item) for item in raw["items"]), True
+        except (OSError, json.JSONDecodeError, TypeError):
+            pass
+    repository_snapshot = RepositorySnapshot(root, ref)
+    snapshot_context = (
+        nullcontext(materialized_root)
+        if materialized_root is not None
+        else repository_snapshot.materialized_root(
+            paths=(() if project == Path(".") else (project,))
+        )
+    )
+    with snapshot_context as snapshot:
+        project_root = snapshot / project
+        if not project_root.is_dir():
+            raise ConfigurationError(f"project does not exist at {ref}: {project}")
+        items = list(scan_inventory(project_root).items)
+        manifest_path = project_root / ".sourcebound.yml"
+        plugins = (
+            load_manifest(manifest_path).plugins
+            if manifest_path.is_file()
+            and execution_policy is ExecutionPolicy.TRUSTED
+            else ()
+        )
+    items = list(
+        merge_plugin_inventory(
+            tuple(items), discover_plugin_items(repository_snapshot, plugins)
+        )
+    )
+    if use_cache:
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write(cache_path, json.dumps({
+            "schema": "sourcebound.inventory-cache.v1",
+            "key": key,
+            "items": [asdict(item) for item in items],
+        }, sort_keys=True, separators=(",", ":")) + "\n")
+    return tuple(items), False
+
+
+def _check_changed_details(
+    root: Path,
+    manifest_path: Path,
+    *,
+    base: str,
+    head: str,
+    use_cache: bool = True,
+    project: Path = Path("."),
+    head_snapshot_root: Path | None = None,
+    execution_policy: ExecutionPolicy = ExecutionPolicy.TRUSTED,
+) -> tuple[ChangedReport, tuple[InventoryItem, ...], tuple[InventoryItem, ...]]:
+    root = root.resolve()
+    if not base or not head:
+        raise ConfigurationError("check --changed requires --base and --head")
+    if project.is_absolute() or ".." in project.parts:
+        raise ConfigurationError("check --changed project must stay inside the repository")
+    project = Path(project.as_posix().strip("/")) if project.as_posix() != "." else Path(".")
+    project_root = (root / project).resolve()
+    try:
+        manifest_relative = manifest_path.resolve().relative_to(project_root)
+    except ValueError as exc:
+        raise ConfigurationError("changed-check manifest must be inside the selected project") from exc
+    base_sha = RepositorySnapshot(root, base).label
+    head_sha = RepositorySnapshot(root, head).label
+    all_changed_files = tuple(sorted(
+        line for line in _git(
+            root, "diff", "--name-only", base_sha, head_sha
+        ).splitlines()
+        if line
+    ))
+    prefix = "" if project == Path(".") else project.as_posix().rstrip("/") + "/"
+    changed_files = tuple(
+        path for path in all_changed_files if not prefix or path.startswith(prefix)
+    )
+    project_changed_files = tuple(
+        path.removeprefix(prefix) if prefix else path for path in changed_files
+    )
+    base_inventory, base_hit = _inventory(
+        root,
+        base_sha,
+        project,
+        use_cache=use_cache,
+        execution_policy=execution_policy,
+    )
+    snapshot_context = (
+        nullcontext(head_snapshot_root)
+        if head_snapshot_root is not None
+        else RepositorySnapshot(root, head_sha).materialized_root()
+    )
+    with snapshot_context as snapshot:
+        head_inventory, head_hit = _inventory(
+            root,
+            head_sha,
+            project,
+            use_cache=use_cache,
+            materialized_root=snapshot,
+            execution_policy=execution_policy,
+        )
+        base_items = {item.id: item for item in base_inventory}
+        head_items = {item.id: item for item in head_inventory}
+        required: list[ChangedFinding] = []
+        dependencies: dict[str, tuple[str, ...]] = {}
+        head_project = snapshot / project
+        head_manifest = head_project / manifest_relative
+        loaded = load_manifest(head_manifest)
+        for binding in loaded.bindings:
+            paths = _affected_paths(
+                binding, project_changed_files, manifest_relative.as_posix()
+            )
+            if not paths:
+                continue
+            dependencies[binding.id] = paths
+            for result in evaluate(
+                head_project,
+                head_manifest,
+                binding_id=binding.id,
+                execution_policy=execution_policy,
+                inventory_items=head_inventory,
+            ):
+                if not result.changed:
+                    continue
+                rule = (
+                    "execution-skipped"
+                    if result.state == "skipped-untrusted-execution"
+                    else "binding-drift"
+                )
+                doc = prefix + result.doc
+                source = prefix + result.provenance.path
+                root_arg = (
+                    "" if project == Path(".") else f" --root {project.as_posix()}"
+                )
+                required.append(ChangedFinding(
+                    _finding_id(rule, doc, source, result.provenance.locator),
+                    rule,
+                    doc,
+                    source,
+                    result.provenance.locator,
+                    (
+                        f"binding {result.binding_id} is unknown because "
+                        "static-only mode skipped repository-declared execution"
+                        if result.state == "skipped-untrusted-execution"
+                        else f"binding {result.binding_id} changed behind {doc}"
+                    ),
+                    (
+                        "run the binding in a separately configured trusted environment"
+                        if result.state == "skipped-untrusted-execution"
+                        else f"sourcebound{root_arg} drive --binding {result.binding_id}"
+                    ),
+                ))
+        affected_claim_checks = []
+        for claim_check in loaded.source_claim_checks:
+            paths = tuple(
+                sorted(
+                    set(project_changed_files)
+                    & {
+                        claim_check.doc.as_posix(),
+                        claim_check.source.as_posix(),
+                        manifest_relative.as_posix(),
+                    }
+                )
+            )
+            if not paths:
+                continue
+            dependencies[f"source-claim:{claim_check.id}"] = paths
+            affected_claim_checks.append(claim_check)
+        if affected_claim_checks:
+            claim_report = scan_source_claims(
+                head_project,
+                tuple(affected_claim_checks),
+                discover=False,
+            )
+            for claim_result in claim_report.results:
+                if claim_result.status != "drift":
+                    continue
+                rule = "source-claim-drift"
+                doc = prefix + claim_result.doc
+                source = prefix + claim_result.source
+                required.append(
+                    ChangedFinding(
+                        _finding_id(rule, doc, source, claim_result.locator),
+                        rule,
+                        doc,
+                        source,
+                        claim_result.locator,
+                        claim_result.detail,
+                        "update the documented value or accepted relationship, "
+                        "then run sourcebound claims",
+                    )
+                )
+            for missing_claim in claim_report.missing:
+                rule = "source-claim-contract-missing"
+                doc = prefix + missing_claim.doc
+                source = prefix + missing_claim.source
+                required.append(
+                    ChangedFinding(
+                        _finding_id(rule, doc, source, missing_claim.locator),
+                        rule,
+                        doc,
+                        source,
+                        missing_claim.locator,
+                        f"accepted source claim {missing_claim.id} cannot be verified: "
+                        f"{missing_claim.detail}",
+                        "restore the documented claim and source locator or remove "
+                        "the obsolete relationship from .sourcebound.yml",
+                    )
+                )
+
+    gaps: list[ChangedFinding] = []
+    ignored: list[ChangedFinding] = []
+    for identifier in sorted(set(head_items) - set(base_items)):
+        inventory_item = head_items[identifier]
+        if inventory_item.kind not in PUBLIC_SURFACE_KINDS:
+            continue
+        rule = "new-public-surface"
+        source = prefix + inventory_item.source
+        finding = ChangedFinding(
+            _finding_id(rule, "", source, inventory_item.locator),
+            rule,
+            "",
+            source,
+            inventory_item.locator,
+            f"new {inventory_item.kind} {inventory_item.name!r} has coverage "
+            f"state {inventory_item.coverage}",
+            "add a source binding or a specific .sourcebound-ignore.yml record",
+        )
+        if inventory_item.coverage == "ignored":
+            ignored.append(finding)
+        elif inventory_item.coverage not in {"bound", "cataloged"}:
+            gaps.append(finding)
+    report = ChangedReport(
+        base_sha,
+        head_sha,
+        project.as_posix(),
+        changed_files,
+        tuple(sorted(required, key=lambda item: item.id)),
+        tuple(sorted(gaps, key=lambda item: item.id)),
+        tuple(sorted(ignored, key=lambda item: item.id)),
+        dependencies,
+        int(base_hit) + int(head_hit),
+        int(not base_hit) + int(not head_hit),
+    )
+    return report, base_inventory, head_inventory
+
+
+def check_changed(
+    root: Path,
+    manifest_path: Path,
+    *,
+    base: str,
+    head: str,
+    use_cache: bool = True,
+    project: Path = Path("."),
+    execution_policy: ExecutionPolicy = ExecutionPolicy.TRUSTED,
+) -> ChangedReport:
+    report, _, _ = _check_changed_details(
+        root,
+        manifest_path,
+        base=base,
+        head=head,
+        use_cache=use_cache,
+        project=project,
+        execution_policy=execution_policy,
+    )
+    return report
+
+
+def render_sarif(report: ChangedReport) -> str:
+    findings = [
+        (finding, "error") for finding in report.required
+    ] + [
+        (finding, "warning") for finding in report.gaps
+    ]
+    payload = {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [{
+            "tool": {
+                "driver": {
+                    "name": "sourcebound",
+                    "rules": [
+                        {"id": rule, "shortDescription": {"text": rule.replace("-", " ")}}
+                        for rule in sorted({finding.rule for finding, _level in findings})
+                    ],
+                }
+            },
+            "results": [
+                {
+                    "ruleId": finding.rule,
+                    "level": level,
+                    "message": {"text": f"{finding.message}. Repair: {finding.repair}"},
+                    "partialFingerprints": {"cleanDocsFindingId": finding.id},
+                    "locations": [{
+                        "physicalLocation": {
+                            "artifactLocation": {"uri": finding.doc or finding.source},
+                        }
+                    }],
+                }
+                for finding, level in findings
+            ],
+        }],
+    }
+    return json.dumps(payload, indent=2, sort_keys=True) + "\n"