sourcebound 1.2.1__py3-none-any.whl

clean_docs/outcomes.py

@@ -0,0 +1,296 @@
+"""Build one local outcome receipt from deterministic repository checks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from clean_docs import __version__
+from clean_docs.audit import AuditReport, audit
+from clean_docs.changed import ChangedReport, check_changed
+from clean_docs.claims import SourceClaimReport, scan_source_claims
+from clean_docs.engine import evaluate
+from clean_docs.errors import ConfigurationError
+from clean_docs.execution import ExecutionPolicy
+from clean_docs.manifest import load_manifest
+from clean_docs.inventory import InventoryReport, scan_inventory
+from clean_docs.models import BindingResult, Manifest
+from clean_docs.projections import evaluate_projections
+from clean_docs.snapshot import RepositorySnapshot
+
+
+@dataclass(frozen=True)
+class RepositoryEvidence:
+    manifest: Manifest
+    audit: AuditReport
+    inventory: InventoryReport
+    bindings: tuple[BindingResult, ...]
+    projections: tuple[BindingResult, ...]
+    source_claims: SourceClaimReport | None
+    changed: ChangedReport | None
+
+
+@dataclass(frozen=True)
+class OutcomeReceipt:
+    ref: str
+    documents: int
+    archived_documents: int
+    hygiene_findings: int
+    baselined_hygiene_findings: int
+    bindings: int
+    current_bindings: int
+    drifted_bindings: int
+    skipped_bindings: int
+    regions: int
+    command_pins: int
+    command_pins_with_prose: int
+    symbols: int
+    projections: int
+    current_projections: int
+    stale_projections: int
+    inventory_items: int
+    covered_inventory_items: int
+    cataloged_inventory_items: int
+    ignored_inventory_items: int
+    standard_gaps: int
+    source_claims: int
+    current_source_claims: int
+    drifted_source_claims: int
+    missing_source_claims: int
+    execution_mode: str = ExecutionPolicy.TRUSTED.value
+    manifest_deprecations: tuple[str, ...] = ()
+    changed: ChangedReport | None = None
+
+    @property
+    def ok(self) -> bool:
+        return (
+            self.hygiene_findings == 0
+            and self.drifted_bindings == 0
+            and self.skipped_bindings == 0
+            and self.stale_projections == 0
+            and self.drifted_source_claims == 0
+            and self.missing_source_claims == 0
+            and (self.changed is None or self.changed.ok)
+        )
+
+    def as_dict(self) -> dict[str, object]:
+        changed = None
+        if self.changed is not None:
+            changed = {
+                "base": self.changed.base,
+                "head": self.changed.head,
+                "required": len(self.changed.required),
+                "coverage_gaps": len(self.changed.gaps),
+                "reasoned_ignores": len(self.changed.ignored),
+                "ok": self.changed.ok,
+            }
+        return {
+            "schema": "sourcebound.outcome.v2",
+            "version": __version__,
+            "ref": self.ref,
+            "ok": self.ok,
+            "assurance": {
+                "scope": "configured-contract",
+                "region_bytes_checked": self.regions > 0,
+                "command_pin_output_checked": self.command_pins > 0,
+                "command_pin_prose_checked": (
+                    self.command_pins > 0
+                    and self.command_pins == self.command_pins_with_prose
+                ),
+                "symbol_existence_checked": self.symbols > 0,
+                "accepted_source_claim_prose_checked": self.source_claims > 0,
+                "cataloged_surfaces_check_prose": False,
+                "judgment_prose_certified": False,
+            },
+            "outcomes": {
+                "protected_baseline_current": (
+                    self.ok and self.changed is None and self.standard_gaps == 0
+                ),
+                "coverage_complete": self.standard_gaps == 0,
+                "direct_coverage_complete": (
+                    self.standard_gaps == 0 and self.cataloged_inventory_items == 0
+                ),
+                "drift_caught_before_merge": (
+                    0
+                    if self.changed is None
+                    else len(self.changed.required) + len(self.changed.gaps)
+                ),
+            },
+            "documentation": {
+                "active": self.documents,
+                "archived": self.archived_documents,
+                "hygiene_findings": self.hygiene_findings,
+                "baselined_hygiene_findings": self.baselined_hygiene_findings,
+            },
+            "coverage": {
+                "total": self.inventory_items,
+                "bound": self.covered_inventory_items,
+                "cataloged": self.cataloged_inventory_items,
+                "ignored": self.ignored_inventory_items,
+                "standard_gaps": self.standard_gaps,
+            },
+            "bindings": {
+                "total": self.bindings,
+                "current": self.current_bindings,
+                "drifted": self.drifted_bindings,
+                "skipped": self.skipped_bindings,
+                "regions": self.regions,
+                "command_pins": self.command_pins,
+                "symbols": self.symbols,
+            },
+            "projections": {
+                "total": self.projections,
+                "current": self.current_projections,
+                "stale": self.stale_projections,
+            },
+            "source_claims": {
+                "total": self.source_claims,
+                "current": self.current_source_claims,
+                "drifted": self.drifted_source_claims,
+                "missing": self.missing_source_claims,
+            },
+            "changed": changed,
+            "execution": {
+                "mode": self.execution_mode,
+                "declared_processes": (
+                    "skipped"
+                    if self.execution_mode == ExecutionPolicy.STATIC_ONLY.value
+                    else "permitted-by-manifest"
+                ),
+                "network_isolation": "not-provided",
+                "network_observation": "not-instrumented",
+            },
+            "deprecations": list(self.manifest_deprecations),
+        }
+
+
+def build_outcome_receipt(
+    root: Path,
+    manifest_path: Path,
+    *,
+    base: str | None = None,
+    head: str | None = None,
+    project: Path = Path("."),
+    execution_policy: ExecutionPolicy = ExecutionPolicy.TRUSTED,
+    use_cache: bool = True,
+) -> OutcomeReceipt:
+    evidence = collect_repository_evidence(
+        root,
+        manifest_path,
+        base=base,
+        head=head,
+        project=project,
+        execution_policy=execution_policy,
+        use_cache=use_cache,
+    )
+    root = root.resolve()
+    inventory = evidence.inventory
+    audit_report = evidence.audit
+    bindings = evidence.bindings
+    projections = evidence.projections
+    source_claim_report = evidence.source_claims
+    changed = evidence.changed
+    manifest = evidence.manifest
+    covered_items = sum(item.coverage == "bound" for item in inventory.items)
+    cataloged_items = sum(item.coverage == "cataloged" for item in inventory.items)
+    ignored_items = sum(item.coverage == "ignored" for item in inventory.items)
+    standard_gaps = sum(item.coverage == "standard-gap" for item in inventory.items)
+    return OutcomeReceipt(
+        RepositorySnapshot(root).label,
+        len(audit_report.documents),
+        len(audit_report.ignored_documents),
+        len(audit_report.findings) + len(audit_report.stale_baseline),
+        len(audit_report.baselined_findings),
+        len(bindings),
+        sum(not item.changed for item in bindings),
+        sum(
+            item.changed and item.state != "skipped-untrusted-execution"
+            for item in bindings
+        ),
+        sum(item.state == "skipped-untrusted-execution" for item in bindings),
+        sum(item.binding_type == "region" for item in bindings),
+        sum(
+            item.binding_type == "command-pin"
+            and item.state != "skipped-untrusted-execution"
+            for item in bindings
+        ),
+        sum(
+            item.binding_type == "command-pin"
+            and item.state != "skipped-untrusted-execution"
+            and item.prose_checked
+            for item in bindings
+        ),
+        sum(item.binding_type == "symbol" for item in bindings),
+        len(projections),
+        sum(not item.changed for item in projections),
+        sum(item.changed for item in projections),
+        len(inventory.items),
+        covered_items,
+        cataloged_items,
+        ignored_items,
+        standard_gaps,
+        0 if source_claim_report is None else len(source_claim_report.results),
+        0
+        if source_claim_report is None
+        else sum(item.status == "current" for item in source_claim_report.results),
+        0
+        if source_claim_report is None
+        else sum(item.status == "drift" for item in source_claim_report.results),
+        0 if source_claim_report is None else len(source_claim_report.missing),
+        execution_policy.value,
+        manifest.deprecations,
+        changed,
+    )
+
+
+def collect_repository_evidence(
+    root: Path,
+    manifest_path: Path,
+    *,
+    base: str | None = None,
+    head: str | None = None,
+    project: Path = Path("."),
+    execution_policy: ExecutionPolicy = ExecutionPolicy.TRUSTED,
+    use_cache: bool = True,
+) -> RepositoryEvidence:
+    if (base is None) != (head is None):
+        raise ConfigurationError("verify requires both --base and --head")
+    root = root.resolve()
+    manifest = load_manifest(manifest_path)
+    audit_report = audit(root)
+    inventory = scan_inventory(root)
+    bindings = tuple(evaluate(root, manifest_path, execution_policy=execution_policy))
+    projections = (
+        tuple(evaluate_projections(root, manifest))
+        if manifest.projections is not None
+        else ()
+    )
+    source_claim_report = (
+        scan_source_claims(
+            root,
+            manifest.source_claim_checks,
+            discover=False,
+        )
+        if manifest.source_claim_checks
+        else None
+    )
+    changed = None
+    if base is not None and head is not None:
+        changed = check_changed(
+            root,
+            manifest_path,
+            base=base,
+            head=head,
+            project=project,
+            execution_policy=execution_policy,
+            use_cache=use_cache,
+        )
+    return RepositoryEvidence(
+        manifest,
+        audit_report,
+        inventory,
+        bindings,
+        projections,
+        source_claim_report,
+        changed,
+    )

clean_docs/performance.py

@@ -0,0 +1,123 @@
+"""Measure changed-check latency and peak process memory against published budgets."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import resource
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from clean_docs.changed import CHANGED_CHECK_BUDGET_SECONDS, ChangedReport, check_changed
+from clean_docs.errors import ConfigurationError
+
+
+CHANGED_CHECK_MEMORY_BUDGET_MB = 256.0
+
+
+@dataclass(frozen=True)
+class PerformanceReceipt:
+    base: str
+    head: str
+    project: str
+    iterations: int
+    p95_seconds: float
+    peak_memory_mb: float
+    time_budget_seconds: float
+    memory_budget_mb: float
+    result_sha256: str
+    required: int
+    gaps: int
+
+    @property
+    def ok(self) -> bool:
+        return (
+            self.p95_seconds <= self.time_budget_seconds
+            and self.peak_memory_mb <= self.memory_budget_mb
+        )
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "schema": "sourcebound.performance.v2",
+            "ok": self.ok,
+            "base": self.base,
+            "head": self.head,
+            "project": self.project,
+            "iterations": self.iterations,
+            "p95_seconds": self.p95_seconds,
+            "peak_memory_mb": self.peak_memory_mb,
+            "budgets": {
+                "p95_seconds": self.time_budget_seconds,
+                "peak_memory_mb": self.memory_budget_mb,
+            },
+            "normalized_result_sha256": self.result_sha256,
+            "required": self.required,
+            "coverage_gaps": self.gaps,
+            "execution": {
+                "declared_processes": "may-run-when-required-by-changed-scope",
+                "network_isolation": "not-provided",
+                "network_observation": "not-instrumented",
+            },
+        }
+
+
+def _digest(report: ChangedReport) -> str:
+    payload = json.dumps(report.as_dict(), sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(payload.encode()).hexdigest()
+
+
+def benchmark_changed_check(
+    root: Path,
+    manifest_path: Path,
+    *,
+    base: str,
+    head: str,
+    project: Path = Path("."),
+    iterations: int = 7,
+    time_budget_seconds: float = CHANGED_CHECK_BUDGET_SECONDS,
+    memory_budget_mb: float = CHANGED_CHECK_MEMORY_BUDGET_MB,
+) -> PerformanceReceipt:
+    if not 3 <= iterations <= 50:
+        raise ConfigurationError("benchmark iterations must be 3..50")
+    if time_budget_seconds <= 0 or memory_budget_mb <= 0:
+        raise ConfigurationError("benchmark budgets must be positive")
+    durations: list[float] = []
+    reports: list[ChangedReport] = []
+    for _index in range(iterations):
+        started = time.perf_counter()
+        report = check_changed(
+            root,
+            manifest_path,
+            base=base,
+            head=head,
+            use_cache=False,
+            project=project,
+        )
+        durations.append(time.perf_counter() - started)
+        reports.append(report)
+    digests = {_digest(report) for report in reports}
+    if len(digests) != 1:
+        raise ConfigurationError("benchmark changed-check results varied across iterations")
+    ordered = sorted(durations)
+    p95 = ordered[max(0, math.ceil(len(ordered) * 0.95) - 1)]
+    peak_rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    peak_memory_mb = (
+        peak_rss / (1024 * 1024) if sys.platform == "darwin" else peak_rss / 1024
+    )
+    last = reports[-1]
+    return PerformanceReceipt(
+        last.base,
+        last.head,
+        project.as_posix(),
+        iterations,
+        round(p95, 6),
+        round(peak_memory_mb, 3),
+        time_budget_seconds,
+        memory_budget_mb,
+        next(iter(digests)),
+        len(last.required),
+        len(last.gaps),
+    )