sourcebound 1.2.1__py3-none-any.whl

clean_docs/emit/stepwise.py

@@ -0,0 +1,168 @@
+"""Project a Sourcebound manifest into a docs-only stepwise skill package."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from clean_docs.errors import ConfigurationError
+from clean_docs.models import Manifest
+from clean_docs.regions import atomic_write
+
+
+PREAMBLE = (
+    "**Read ONLY this file.** Do not read any other reference file until this one tells you to."
+)
+
+
+def _bound_docs(manifest: Manifest) -> list[str]:
+    return sorted({binding.doc.as_posix() for binding in manifest.bindings})
+
+
+def _config(
+    *,
+    display_name: str,
+    role: str,
+    parent_command: str | None,
+    command: str | None,
+) -> dict[str, object]:
+    cli: dict[str, object] = {"role": role}
+    if role == "command":
+        if not command:
+            raise ConfigurationError("a command name is required when role is command")
+        cli["command"] = command
+        if parent_command:
+            cli["parentCommand"] = parent_command
+    elif parent_command or command:
+        raise ConfigurationError("command options require role command")
+    return {
+        "type": "skill",
+        "template": "description.md",
+        "description": "Keep repository documentation true to its source with Sourcebound",
+        "tags": ["documentation", "sourcebound"],
+        "cli": cli,
+        "references": {"preamble": PREAMBLE},
+        "variants": [
+            {
+                "id": "all",
+                "display_name": display_name,
+                "tags": ["documentation"],
+                "docs_urls": [],
+            }
+        ],
+    }
+
+
+def _description(bound_docs: list[str]) -> str:
+    listed = "\n".join(f"- `{doc}`" for doc in bound_docs) or "- No bound documents yet."
+    return (
+        "# Keep documentation true\n\n"
+        "<!-- sourcebound:purpose -->\n"
+        "Use this package when repository documentation may have drifted from its sources. "
+        "It gives maintainers an ordered audit, bounded repair, and verification path with an "
+        "explicit condition for each transition.\n"
+        "<!-- sourcebound:end purpose -->\n\n"
+        "Bound documents in this repository:\n\n"
+        f"{listed}\n"
+    )
+
+
+def _step_audit() -> str:
+    return (
+        "---\nnext_step: 2-repair.md\n---\n\n"
+        "# Step 1: audit the corpus\n\n"
+        "<!-- sourcebound:purpose -->\n"
+        "Use this step before changing docs when the active corpus may contain structural "
+        "findings. It gives maintainers a read-only list of repairs that must precede binding "
+        "work.\n"
+        "<!-- sourcebound:end purpose -->\n\n"
+        "## Status\n\n"
+        "Emit: `sourcebound: auditing documentation`.\n\n"
+        "## Action\n\n"
+        "Run the manifest-free corpus audit:\n\n"
+        "```bash\nsourcebound audit\n```\n\n"
+        "## Decision\n\n"
+        "Exit `0`: proceed. Exit `1`: apply each finding's named repair, then rerun this step. "
+        "Exit `2` or `3`: repair the configuration or extractor before continuing.\n\n"
+        "## Navigation\n\n"
+        "When the audit exits `0`, read `2-repair.md`.\n"
+    )
+
+
+def _step_repair() -> str:
+    return (
+        "---\nnext_step: 3-verify.md\n---\n\n"
+        "# Step 2: repair bound regions\n\n"
+        "<!-- sourcebound:purpose -->\n"
+        "Use this step after the corpus audit passes and source-bound regions may be stale. "
+        "It repairs declared regions while preserving prose outside their markers.\n"
+        "<!-- sourcebound:end purpose -->\n\n"
+        "## Status\n\n"
+        "Emit: `sourcebound: repairing bound regions`.\n\n"
+        "## Action\n\n"
+        "Derive the declared regions from source and enforce the packaged standard:\n\n"
+        "```bash\nsourcebound drive\n```\n\n"
+        "This writes only the regions declared in the manifest. It preserves prose outside the "
+        "markers "
+        "and refuses a write when policy fails.\n\n"
+        "## Decision\n\n"
+        "Exit `0`: proceed. A policy finding requires an author to repair the flagged prose and "
+        "rerun this step.\n\n"
+        "## Navigation\n\n"
+        "When `drive` exits `0`, read `3-verify.md`.\n"
+    )
+
+
+def _step_verify() -> str:
+    return (
+        "---\nnext_step: null\n---\n\n"
+        "# Step 3: verify before publishing\n\n"
+        "<!-- sourcebound:purpose -->\n"
+        "Use this step after repair when you need evidence that the corpus and every binding "
+        "are current. It gives maintainers the read-only release gate and the exact stop "
+        "condition.\n"
+        "<!-- sourcebound:end purpose -->\n\n"
+        "## Status\n\n"
+        "Emit: `sourcebound: verifying`.\n\n"
+        "## Action\n\n"
+        "Run the read-only gates:\n\n"
+        "```bash\nsourcebound audit\nsourcebound check\n```\n\n"
+        "## Decision\n\n"
+        "Both commands exit `0`: publishing is allowed. Either exits nonzero: return to the step "
+        "that owns the finding and do not publish.\n\n"
+        "## Navigation\n\n"
+        "This is the final step. It writes nothing.\n"
+    )
+
+
+def emit_stepwise_skill(
+    manifest: Manifest,
+    out_dir: Path,
+    *,
+    display_name: str = "Keep documentation true",
+    role: str = "skill",
+    parent_command: str | None = None,
+    command: str | None = None,
+) -> tuple[Path, ...]:
+    """Write a manifest-derived stepwise skill package and return its files."""
+    bound_docs = _bound_docs(manifest)
+    files = {
+        out_dir / "config.yaml": yaml.safe_dump(
+            _config(
+                display_name=display_name,
+                role=role,
+                parent_command=parent_command,
+                command=command,
+            ),
+            sort_keys=False,
+            allow_unicode=True,
+        ),
+        out_dir / "description.md": _description(bound_docs),
+        out_dir / "references/1-audit.md": _step_audit(),
+        out_dir / "references/2-repair.md": _step_repair(),
+        out_dir / "references/3-verify.md": _step_verify(),
+    }
+    for path, text in files.items():
+        atomic_write(path, text)
+    return tuple(sorted(files))

clean_docs/engine.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import difflib
+import hashlib
+import json
+import re
+from pathlib import Path
+
+from clean_docs.errors import ConfigurationError, ExtractionError
+from clean_docs.execution import ExecutionPolicy
+from clean_docs.extractors import (
+    extract_command,
+    extract_file,
+    extract_json_pointer,
+    extract_paths,
+    extract_python_literal,
+    extract_repository_inventory,
+    extract_repository_overview,
+    extract_structured,
+)
+from clean_docs.extractors.inventory import _extract_repository_overview_legacy
+from clean_docs.manifest import load_manifest
+from clean_docs.inventory import InventoryItem
+from clean_docs.models import (
+    Binding,
+    BindingResult,
+    ClaimBinding,
+    Manifest,
+    Provenance,
+    RegionBinding,
+    SymbolBinding,
+)
+from clean_docs.policy import PolicyFinding, check_documents
+from clean_docs.plugins import check_plugin_policies, extract_plugin, render_plugin
+from clean_docs.regions import atomic_write, replace_region
+from clean_docs.renderers import render
+from clean_docs.snapshot import RepositorySnapshot
+from clean_docs.standard import load_default_pack
+from clean_docs.symbols import resolve_symbol
+
+
+def _select(bindings: tuple[Binding, ...], binding_id: str | None) -> list[Binding]:
+    if binding_id is None:
+        return list(bindings)
+    selected = [binding for binding in bindings if binding.id == binding_id]
+    if not selected:
+        raise ConfigurationError(f"unknown binding id: {binding_id}")
+    return selected
+
+
+def _document(root: Path, binding: Binding) -> str:
+    try:
+        return (root / binding.doc).read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigurationError(f"cannot read bound document {binding.doc}: {exc}") from exc
+
+
+def _has_anchor(document: str, anchor: str) -> bool:
+    return _anchored_section(document, anchor) is not None
+
+
+def _anchored_section(document: str, anchor: str) -> str | None:
+    lines = document.splitlines(keepends=True)
+    start: int | None = None
+    level = 0
+    for index, line in enumerate(lines):
+        match = re.match(r"^#{1,6}\s+(.+?)\s*$", line)
+        if match:
+            heading_level = len(line) - len(line.lstrip("#"))
+            if start is not None and heading_level <= level:
+                return "".join(lines[start:index])
+            slug = re.sub(r"[^a-z0-9 -]", "", match.group(1).lower()).replace(" ", "-")
+            if slug == anchor:
+                start = index + 1
+                level = heading_level
+    return None if start is None else "".join(lines[start:])
+
+
+def _claim_result(root: Path, snapshot: RepositorySnapshot, manifest: Manifest, binding: ClaimBinding) -> BindingResult:
+    document = _document(root, binding)
+    section = _anchored_section(document, binding.anchor)
+    if section is None:
+        raise ConfigurationError(f"document anchor not found: {binding.doc}#{binding.anchor}")
+    command = next(item for item in manifest.commands if item.id == binding.command)
+    evidence = extract_command(snapshot, command, binding.assertion.path)
+    prose_current = (
+        binding.assertion.prose is None
+        or binding.assertion.prose in section
+    )
+    changed = evidence.value != binding.assertion.expected or not prose_current
+    expected = json.dumps(binding.assertion.expected, sort_keys=True)
+    observed = json.dumps(evidence.value, sort_keys=True)
+    diff_lines = []
+    if evidence.value != binding.assertion.expected:
+        diff_lines.append(
+            f"command pin {binding.doc}#{binding.anchor}: "
+            f"expected {expected}, observed {observed}"
+        )
+    if binding.assertion.prose is not None and not prose_current:
+        diff_lines.append(
+            f"command pin {binding.doc}#{binding.anchor}: "
+            f"anchored prose is missing {binding.assertion.prose!r}"
+        )
+    diff = "" if not diff_lines else "\n".join(diff_lines) + "\n"
+    return BindingResult(
+        binding.id, binding.doc.as_posix(), changed, expected, observed, diff,
+        evidence.provenance, "command-pin", prose_checked=binding.assertion.prose is not None,
+    )
+
+
+def _symbol_result(root: Path, snapshot: RepositorySnapshot, binding: SymbolBinding) -> BindingResult:
+    document = _document(root, binding)
+    if not _has_anchor(document, binding.anchor):
+        raise ConfigurationError(f"document anchor not found: {binding.doc}#{binding.anchor}")
+    try:
+        evidence = resolve_symbol(snapshot, binding)
+        changed = False
+        observed = "exists"
+        provenance = evidence.provenance
+        diff = ""
+    except ExtractionError as exc:
+        if "not found" not in str(exc) and "cannot read source" not in str(exc):
+            raise
+        changed = True
+        observed = "missing"
+        locator = binding.source.symbol or binding.source.path.as_posix()
+        provenance = Provenance(
+            snapshot.label,
+            binding.source.path.as_posix(),
+            locator,
+            "symbol@1",
+            hashlib.sha256(locator.encode()).hexdigest(),
+        )
+        diff = f"symbol {locator} referenced by {binding.doc}#{binding.anchor} is missing\n"
+    return BindingResult(
+        binding.id, binding.doc.as_posix(), changed, "exists", observed, diff,
+        provenance, "symbol",
+    )
+
+
+def evaluate(
+    root: Path,
+    manifest_path: Path,
+    *,
+    ref: str | None = None,
+    binding_id: str | None = None,
+    execution_policy: ExecutionPolicy = ExecutionPolicy.TRUSTED,
+    inventory_items: tuple[InventoryItem, ...] | None = None,
+) -> list[BindingResult]:
+    manifest = load_manifest(manifest_path)
+    snapshot = RepositorySnapshot(root=root, ref=ref)
+    results: list[BindingResult] = []
+    documents: dict[str, str] = {}
+    for binding in _select(manifest.bindings, binding_id):
+        uses_plugin = (
+            isinstance(binding, RegionBinding)
+            and (
+                binding.extractor.startswith("plugin:")
+                or binding.renderer.startswith("plugin:")
+            )
+        )
+        if execution_policy is ExecutionPolicy.STATIC_ONLY and (
+            isinstance(binding, ClaimBinding) or uses_plugin
+        ):
+            locator = (
+                binding.command
+                if isinstance(binding, ClaimBinding)
+                else binding.id
+            )
+            mechanism = (
+                "command-pin" if isinstance(binding, ClaimBinding) else "plugin"
+            )
+            provenance = Provenance(
+                snapshot.label,
+                binding.doc.as_posix(),
+                locator,
+                f"{mechanism}@skipped",
+                hashlib.sha256(locator.encode()).hexdigest(),
+            )
+            results.append(
+                BindingResult(
+                    binding_id=binding.id,
+                    doc=binding.doc.as_posix(),
+                    changed=True,
+                    expected="trusted declared execution",
+                    observed="skipped by static-only execution policy",
+                    diff=(
+                        f"{mechanism} {binding.id} was not evaluated because "
+                        "repository-declared execution is disabled\n"
+                    ),
+                    provenance=provenance,
+                    binding_type=mechanism,
+                    state="skipped-untrusted-execution",
+                )
+            )
+            continue
+        if isinstance(binding, ClaimBinding):
+            results.append(_claim_result(root, snapshot, manifest, binding))
+            continue
+        if isinstance(binding, SymbolBinding):
+            results.append(_symbol_result(root, snapshot, binding))
+            continue
+        assert isinstance(binding, RegionBinding)
+        if binding.extractor.startswith("plugin:"):
+            plugin_id = binding.extractor.removeprefix("plugin:")
+            plugin = next(item for item in manifest.plugins if item.id == plugin_id)
+            evidence = extract_plugin(snapshot, binding, plugin)
+        else:
+            extractors = {
+                "file": extract_file,
+                "json": extract_json_pointer,
+                "path": extract_paths,
+                "python-literal": extract_python_literal,
+                "repository-inventory": extract_repository_inventory,
+                "repository-overview": extract_repository_overview,
+                "structured-data": extract_structured,
+            }
+            if binding.extractor == "repository-overview":
+                evidence = extract_repository_overview(
+                    snapshot,
+                    binding,
+                    inventory_items=inventory_items,
+                )
+            else:
+                evidence = extractors[binding.extractor](snapshot, binding)
+        if binding.renderer.startswith("plugin:"):
+            renderer_id = binding.renderer.removeprefix("plugin:")
+            renderer_plugin = next(
+                item for item in manifest.plugins if item.id == renderer_id
+            )
+            rendered = render_plugin(snapshot, binding, renderer_plugin, evidence)
+        else:
+            rendered = render(evidence, binding)
+        doc_path = root / binding.doc
+        doc_key = binding.doc.as_posix()
+        if doc_key not in documents:
+            try:
+                documents[doc_key] = doc_path.read_text(encoding="utf-8")
+            except OSError as exc:
+                raise ConfigurationError(
+                    f"cannot read bound document {binding.doc}: {exc}"
+                ) from exc
+        observed = documents[doc_key]
+        expected = replace_region(observed, binding.region, rendered)
+        if observed != expected and binding.extractor == "repository-overview":
+            legacy_evidence = _extract_repository_overview_legacy(
+                snapshot,
+                binding,
+                inventory_items=inventory_items,
+            )
+            legacy_rendered = render(legacy_evidence, binding)
+            legacy_expected = replace_region(
+                observed, binding.region, legacy_rendered
+            )
+            if observed == legacy_expected:
+                evidence = legacy_evidence
+                expected = observed
+        documents[doc_key] = expected
+        diff = "".join(difflib.unified_diff(
+            observed.splitlines(keepends=True),
+            expected.splitlines(keepends=True),
+            fromfile=binding.doc.as_posix(),
+            tofile=f"{binding.doc.as_posix()} (derived)",
+        ))
+        results.append(BindingResult(
+            binding_id=binding.id,
+            doc=binding.doc.as_posix(),
+            changed=observed != expected,
+            expected=expected,
+            observed=observed,
+            diff=diff,
+            provenance=evidence.provenance,
+        ))
+    return results
+
+
+def write_results(root: Path, results: list[BindingResult]) -> None:
+    by_doc: dict[str, str] = {}
+    for result in results:
+        if result.binding_type != "region":
+            continue
+        current = by_doc.get(result.doc)
+        if current is not None and current != result.observed:
+            raise ConfigurationError(
+                f"multiple bindings for {result.doc} require a combined document update"
+            )
+        by_doc[result.doc] = result.expected
+    for doc, content in by_doc.items():
+        atomic_write(root / doc, content)
+
+
+def planned_documents(results: list[BindingResult]) -> dict[str, str]:
+    documents: dict[str, str] = {}
+    for result in results:
+        if result.binding_type != "region":
+            continue
+        current = documents.get(result.doc)
+        if current is not None and current != result.observed:
+            raise ConfigurationError(f"binding plan for {result.doc} is not sequential")
+        documents[result.doc] = result.expected
+    return documents
+
+
+def drive(
+    root: Path,
+    manifest_path: Path,
+    *,
+    ref: str | None = None,
+    binding_id: str | None = None,
+) -> tuple[list[BindingResult], list[PolicyFinding]]:
+    results = evaluate(root, manifest_path, ref=ref, binding_id=binding_id)
+    planned = planned_documents(results)
+    manifest = load_manifest(manifest_path)
+    findings = check_documents(planned, load_default_pack())
+    findings.extend(
+        check_plugin_policies(RepositorySnapshot(root, ref), manifest.plugins, planned)
+    )
+    if findings:
+        return results, findings
+    write_results(root, results)
+    remaining = evaluate(root, manifest_path, ref=ref, binding_id=binding_id)
+    if any(result.changed for result in remaining if result.binding_type == "region"):
+        raise ConfigurationError("drive wrote documentation but drift remains")
+    return results, []

clean_docs/errors.py

@@ -0,0 +1,20 @@
+class CleanDocsError(Exception):
+    """Base error with a stable process exit code."""
+
+    exit_code = 3
+
+
+class ConfigurationError(CleanDocsError):
+    exit_code = 2
+
+
+class ExtractionError(CleanDocsError):
+    exit_code = 3
+
+
+class RegionError(CleanDocsError):
+    exit_code = 3
+
+
+class PolicyError(CleanDocsError):
+    exit_code = 1