PyPI - sourcebound - Versions diffs - 1.2.1__py3-none-any.whl - Mend

sourcebound 1.2.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (71) hide show

clean_docs/__init__.py +26 -0
clean_docs/__main__.py +3 -0
clean_docs/accessibility.py +182 -0
clean_docs/adapters/__init__.py +1 -0
clean_docs/adapters/event_capture.py +56 -0
clean_docs/adapters/mdx_dependencies.json +714 -0
clean_docs/adapters/mdx_parser.mjs +29992 -0
clean_docs/applicability.py +330 -0
clean_docs/audit.py +1120 -0
clean_docs/bootstrap.py +507 -0
clean_docs/capabilities.py +200 -0
clean_docs/changed.py +452 -0
clean_docs/claims.py +840 -0
clean_docs/cli.py +1612 -0
clean_docs/context.py +307 -0
clean_docs/corpus.py +377 -0
clean_docs/demo.py +369 -0
clean_docs/doctor.py +184 -0
clean_docs/emit/__init__.py +4 -0
clean_docs/emit/llms_txt.py +102 -0
clean_docs/emit/stepwise.py +168 -0
clean_docs/engine.py +324 -0
clean_docs/errors.py +20 -0
clean_docs/evaluation.py +867 -0
clean_docs/execution.py +138 -0
clean_docs/explain.py +123 -0
clean_docs/extractors/__init__.py +19 -0
clean_docs/extractors/command.py +51 -0
clean_docs/extractors/inventory.py +176 -0
clean_docs/extractors/json_pointer.py +84 -0
clean_docs/extractors/python_literal.py +104 -0
clean_docs/extractors/static.py +111 -0
clean_docs/feedback.py +1390 -0
clean_docs/impact.py +1624 -0
clean_docs/improvements.py +1178 -0
clean_docs/inventory.py +474 -0
clean_docs/isolation.py +157 -0
clean_docs/manifest.py +898 -0
clean_docs/mdx.py +272 -0
clean_docs/migration.py +121 -0
clean_docs/models.py +194 -0
clean_docs/outcomes.py +296 -0
clean_docs/performance.py +123 -0
clean_docs/phrasing.py +448 -0
clean_docs/plugins.py +249 -0
clean_docs/policy.py +536 -0
clean_docs/projections.py +255 -0
clean_docs/regions.py +75 -0
clean_docs/release.py +232 -0
clean_docs/renderers.py +57 -0
clean_docs/residue.py +311 -0
clean_docs/review_contracts.py +862 -0
clean_docs/review_ledger.py +297 -0
clean_docs/review_limits.py +9 -0
clean_docs/sensitivity.py +602 -0
clean_docs/snapshot.py +212 -0
clean_docs/standard.py +281 -0
clean_docs/standards/default.json +309 -0
clean_docs/standards/exemplars.md +87 -0
clean_docs/standards/v0-migrations.json +26 -0
clean_docs/symbols.py +47 -0
clean_docs/templates.py +96 -0
clean_docs/verdict.py +1397 -0
clean_docs/visuals.py +346 -0
clean_docs/write_gate.py +170 -0
sourcebound-1.2.1.dist-info/LICENSE +21 -0
sourcebound-1.2.1.dist-info/METADATA +109 -0
sourcebound-1.2.1.dist-info/RECORD +71 -0
sourcebound-1.2.1.dist-info/WHEEL +5 -0
sourcebound-1.2.1.dist-info/entry_points.txt +2 -0
sourcebound-1.2.1.dist-info/top_level.txt +1 -0

clean_docs/mdx.py ADDED Viewed

@@ -0,0 +1,272 @@
+from __future__ import annotations
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+MDX_PARSE_SCHEMA = "sourcebound.mdx-parse.v1"
+MDX_PARSE_BATCH_SCHEMA = "sourcebound.mdx-parse-batch.v1"
+MDX_PARSE_REQUEST_SCHEMA = "sourcebound.mdx-parse-request.v1"
+MDX_PARSER_ID = "@mdx-js/mdx@3.1.1"
+MDX_CONTROL = re.compile(
+    r"^(?P<indent>\s*)\{/\*\s*(?P<body>sourcebound:.*?)\s*\*/\}\s*$"
+)
+class MdxParserError(RuntimeError):
+    """The first-party MDX parser could not establish a structural result."""
+@dataclass(frozen=True)
+class MdxLink:
+    line: int
+    column: int
+    url: str
+@dataclass(frozen=True)
+class MdxNode:
+    type: str
+    start_line: int
+    start_column: int
+    start_byte: int
+    end_line: int
+    end_column: int
+    end_byte: int
+    name: str | None = None
+    url: str | None = None
+    depth: int | None = None
+    text: str | None = None
+    language: str | None = None
+    meta: str | None = None
+    alt: str | None = None
+@dataclass(frozen=True)
+class MdxDocument:
+    digest: str
+    masked_text: str
+    links: tuple[MdxLink, ...]
+    nodes: tuple[MdxNode, ...]
+    parser: str = MDX_PARSER_ID
+    def policy_text(self, source: str) -> str:
+        source_lines = source.splitlines(keepends=True)
+        masked_lines = self.masked_text.splitlines(keepends=True)
+        if len(source_lines) != len(masked_lines):
+            raise MdxParserError("MDX parser changed the document line structure")
+        for index, line in enumerate(source_lines):
+            content = line.rstrip("\r\n")
+            ending = line[len(content):]
+            match = MDX_CONTROL.match(content)
+            if match:
+                masked_lines[index] = (
+                    f"{match.group('indent')}<!-- {match.group('body').strip()} -->"
+                    f"{ending}"
+                )
+        return "".join(masked_lines)
+def parser_path() -> Path:
+    return Path(str(files("clean_docs.adapters").joinpath("mdx_parser.mjs")))
+def parser_availability() -> tuple[bool, str]:
+    node = shutil.which("node")
+    if node is None:
+        return False, "Node.js executable not found"
+    try:
+        version_process = subprocess.run(
+            [node, "--version"],
+            text=True,
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return False, f"cannot inspect Node.js runtime: {exc}"
+    match = re.fullmatch(r"v(\d+)\.\d+\.\d+\s*", version_process.stdout)
+    if version_process.returncode != 0 or match is None:
+        return False, "Node.js runtime did not report a semantic version"
+    if int(match.group(1)) < 20:
+        return False, f"Node.js 20 or newer is required; found {version_process.stdout.strip()}"
+    bundled = parser_path()
+    if not bundled.is_file():
+        return False, "bundled MDX parser not found"
+    return True, f"{MDX_PARSER_ID} via {node}"
+def _integer(value: Any, field: str, *, minimum: int = 0) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
+        raise MdxParserError(f"MDX parser returned invalid {field}")
+    return value
+def _string(value: Any, field: str) -> str:
+    if not isinstance(value, str):
+        raise MdxParserError(f"MDX parser returned invalid {field}")
+    return value
+def _node(raw: Any) -> MdxNode:
+    if not isinstance(raw, dict):
+        raise MdxParserError("MDX parser returned an invalid node")
+    start = raw.get("start")
+    end = raw.get("end")
+    if not isinstance(start, dict) or not isinstance(end, dict):
+        raise MdxParserError("MDX parser returned a node without positions")
+    name = raw.get("name")
+    url = raw.get("url")
+    text = raw.get("text")
+    language = raw.get("language")
+    meta = raw.get("meta")
+    alt = raw.get("alt")
+    depth = raw.get("depth")
+    if name is not None and not isinstance(name, str):
+        raise MdxParserError("MDX parser returned an invalid node name")
+    if url is not None and not isinstance(url, str):
+        raise MdxParserError("MDX parser returned an invalid node URL")
+    if text is not None and not isinstance(text, str):
+        raise MdxParserError("MDX parser returned invalid heading text")
+    if language is not None and not isinstance(language, str):
+        raise MdxParserError("MDX parser returned invalid code language")
+    if meta is not None and not isinstance(meta, str):
+        raise MdxParserError("MDX parser returned invalid code metadata")
+    if alt is not None and not isinstance(alt, str):
+        raise MdxParserError("MDX parser returned invalid image alternative text")
+    if depth is not None:
+        depth = _integer(depth, "heading depth", minimum=1)
+    return MdxNode(
+        type=_string(raw.get("type"), "node type"),
+        start_line=_integer(start.get("line"), "start line", minimum=1),
+        start_column=_integer(start.get("column"), "start column", minimum=1),
+        start_byte=_integer(start.get("byte"), "start byte"),
+        end_line=_integer(end.get("line"), "end line", minimum=1),
+        end_column=_integer(end.get("column"), "end column", minimum=1),
+        end_byte=_integer(end.get("byte"), "end byte"),
+        name=name,
+        url=url,
+        depth=depth,
+        text=text,
+        language=language,
+        meta=meta,
+        alt=alt,
+    )
+def _parse_payload(payload: Any, text: str) -> MdxDocument:
+    if not isinstance(payload, dict) or payload.get("schema") != MDX_PARSE_SCHEMA:
+        raise MdxParserError("MDX parser returned an unsupported document schema")
+    if payload.get("parser") != MDX_PARSER_ID:
+        raise MdxParserError("MDX parser identity does not match the packaged adapter")
+    digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
+    if payload.get("digest") != digest:
+        raise MdxParserError("MDX parser input digest does not match")
+    masked = _string(payload.get("masked"), "masked document")
+    if masked.count("\n") != text.count("\n"):
+        raise MdxParserError("MDX parser changed the document line structure")
+    raw_links = payload.get("links")
+    raw_nodes = payload.get("nodes")
+    if not isinstance(raw_links, list) or not isinstance(raw_nodes, list):
+        raise MdxParserError("MDX parser omitted semantic results")
+    links: list[MdxLink] = []
+    for raw in raw_links:
+        if not isinstance(raw, dict):
+            raise MdxParserError("MDX parser returned an invalid link")
+        links.append(
+            MdxLink(
+                line=_integer(raw.get("line"), "link line", minimum=1),
+                column=_integer(raw.get("column"), "link column", minimum=1),
+                url=_string(raw.get("url"), "link URL"),
+            )
+        )
+    return MdxDocument(
+        digest=digest,
+        masked_text=masked,
+        links=tuple(links),
+        nodes=tuple(_node(raw) for raw in raw_nodes),
+    )
+def parse_mdx_documents(
+    documents: Mapping[str, str],
+) -> tuple[dict[str, MdxDocument], dict[str, str]]:
+    available, detail = parser_availability()
+    if not available:
+        raise MdxParserError(detail)
+    environment = {
+        "LC_ALL": "C",
+        "PATH": os.environ.get("PATH", ""),
+        "TZ": "UTC",
+    }
+    with tempfile.TemporaryDirectory(prefix="sourcebound-mdx-") as working:
+        try:
+            process = subprocess.run(
+                ["node", "--no-warnings", str(parser_path())],
+                input=json.dumps(
+                    {
+                        "schema": MDX_PARSE_REQUEST_SCHEMA,
+                        "documents": [
+                            {"id": identifier, "text": text}
+                            for identifier, text in sorted(documents.items())
+                        ],
+                    },
+                    separators=(",", ":"),
+                ),
+                text=True,
+                capture_output=True,
+                cwd=working,
+                env=environment,
+                timeout=20,
+                check=False,
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            raise MdxParserError(f"MDX parser failed: {exc}") from exc
+    if process.returncode != 0:
+        detail = process.stderr.strip() or "parser exited without a diagnostic"
+        raise MdxParserError(f"MDX parser failed: {detail}")
+    try:
+        payload = json.loads(process.stdout)
+    except json.JSONDecodeError as exc:
+        raise MdxParserError("MDX parser returned invalid JSON") from exc
+    if not isinstance(payload, dict) or payload.get("schema") != MDX_PARSE_BATCH_SCHEMA:
+        raise MdxParserError("MDX parser returned an unsupported batch schema")
+    raw_results = payload.get("documents")
+    if not isinstance(raw_results, list):
+        raise MdxParserError("MDX parser omitted batch results")
+    parsed: dict[str, MdxDocument] = {}
+    errors: dict[str, str] = {}
+    for raw in raw_results:
+        if not isinstance(raw, dict) or not isinstance(raw.get("id"), str):
+            raise MdxParserError("MDX parser returned an invalid batch item")
+        identifier = raw["id"]
+        if identifier not in documents or identifier in parsed or identifier in errors:
+            raise MdxParserError("MDX parser returned an unexpected batch item")
+        if raw.get("ok") is True:
+            parsed[identifier] = _parse_payload(raw.get("result"), documents[identifier])
+        elif raw.get("ok") is False and isinstance(raw.get("error"), str):
+            errors[identifier] = raw["error"]
+        else:
+            raise MdxParserError("MDX parser returned an invalid batch state")
+    if set(parsed) | set(errors) != set(documents):
+        raise MdxParserError("MDX parser did not account for every document")
+    return parsed, errors
+def parse_mdx(text: str) -> MdxDocument:
+    parsed, errors = parse_mdx_documents({"document.mdx": text})
+    if errors:
+        raise MdxParserError(
+            f"MDX syntax is not structurally valid: {errors['document.mdx']}"
+        )
+    return parsed["document.mdx"]

clean_docs/migration.py ADDED Viewed

@@ -0,0 +1,121 @@
+"""Migrate prior manifests with an exact backup and rollback path."""
+from __future__ import annotations
+import difflib
+import hashlib
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+import yaml
+from clean_docs.errors import ConfigurationError
+from clean_docs.regions import atomic_write
+@dataclass(frozen=True)
+class MigrationPlan:
+    source_version: int
+    target_version: int
+    original_sha256: str
+    migrated_sha256: str
+    original: str
+    migrated: str
+    diff: str
+    def as_dict(self) -> dict[str, object]:
+        payload = asdict(self)
+        payload["schema"] = "sourcebound.manifest-migration.v1"
+        payload["backup"] = ".sourcebound.yml.v0.bak"
+        return payload
+def _mapping(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ConfigurationError("manifest migration source must be a mapping")
+    return value
+def build_migration_plan(path: Path) -> MigrationPlan:
+    try:
+        original = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigurationError(f"cannot read manifest {path}: {exc}") from exc
+    try:
+        raw = _mapping(yaml.safe_load(original))
+    except yaml.YAMLError as exc:
+        raise ConfigurationError(f"invalid YAML in {path}: {exc}") from exc
+    source_version = raw.get("version")
+    if source_version not in {0, 1}:
+        raise ConfigurationError("manifest migration requires source version 0 or 1")
+    migrated_data = dict(raw)
+    target_version = source_version + 1
+    migrated_data["version"] = target_version
+    if source_version == 1:
+        execution = migrated_data.get("execution")
+        if isinstance(execution, dict):
+            allowed = execution.get("allowed_commands")
+            if isinstance(allowed, dict):
+                for command in allowed.values():
+                    if isinstance(command, dict):
+                        command.pop("network", None)
+    migrated = yaml.safe_dump(migrated_data, sort_keys=False, allow_unicode=True)
+    diff = "".join(
+        difflib.unified_diff(
+            original.splitlines(keepends=True),
+            migrated.splitlines(keepends=True),
+            fromfile=path.name,
+            tofile=f"{path.name} (version {target_version})",
+        )
+    )
+    return MigrationPlan(
+        source_version,
+        target_version,
+        hashlib.sha256(original.encode()).hexdigest(),
+        hashlib.sha256(migrated.encode()).hexdigest(),
+        original,
+        migrated,
+        diff,
+    )
+def backup_path(path: Path, source_version: int = 0) -> Path:
+    return path.with_name(path.name + f".v{source_version}.bak")
+def apply_migration(path: Path, plan: MigrationPlan) -> Path:
+    backup = backup_path(path, plan.source_version)
+    if backup.exists():
+        raise ConfigurationError(f"migration backup already exists: {backup}")
+    try:
+        current = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigurationError(f"cannot read manifest {path}: {exc}") from exc
+    if hashlib.sha256(current.encode()).hexdigest() != plan.original_sha256:
+        raise ConfigurationError("manifest changed after migration planning")
+    atomic_write(backup, plan.original)
+    try:
+        atomic_write(path, plan.migrated)
+    except OSError:
+        atomic_write(path, plan.original)
+        raise
+    return backup
+def rollback_migration(path: Path) -> None:
+    backups = sorted(path.parent.glob(path.name + ".v*.bak"))
+    if len(backups) != 1:
+        raise ConfigurationError(
+            f"manifest rollback requires one backup, found {len(backups)}"
+        )
+    backup = backups[0]
+    try:
+        original = backup.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigurationError(f"cannot read migration backup {backup}: {exc}") from exc
+    atomic_write(path, original)
+    try:
+        backup.unlink()
+    except OSError as exc:
+        raise ConfigurationError(f"cannot remove migration backup {backup}: {exc}") from exc

clean_docs/models.py ADDED Viewed

@@ -0,0 +1,194 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+PLUGIN_API_VERSION = 1
+PLUGIN_INTERFACES = frozenset({"discoverer", "extractor", "policy", "renderer"})
+@dataclass(frozen=True)
+class Source:
+    path: Path
+    symbol: str | None = None
+    pointer: str | None = None
+    glob: str | None = None
+@dataclass(frozen=True)
+class RegionBinding:
+    id: str
+    doc: Path
+    region: str
+    extractor: str
+    source: Source
+    renderer: str
+    columns: tuple[str, ...]
+    language: str | None = None
+@dataclass(frozen=True)
+class Assertion:
+    path: str
+    operator: str
+    expected: Any
+    prose: str | None = None
+@dataclass(frozen=True)
+class ClaimBinding:
+    id: str
+    doc: Path
+    anchor: str
+    extractor: str
+    command: str
+    assertion: Assertion
+@dataclass(frozen=True)
+class SymbolBinding:
+    id: str
+    doc: Path
+    anchor: str
+    source: Source
+Binding = RegionBinding | ClaimBinding | SymbolBinding
+@dataclass(frozen=True)
+class SourceClaimCheck:
+    id: str
+    kind: str
+    doc: Path
+    anchor: str
+    subject: str
+    source: Path
+    locator: str
+@dataclass(frozen=True)
+class CommandSpec:
+    id: str
+    argv: tuple[str, ...]
+    timeout_seconds: int
+@dataclass(frozen=True)
+class PluginSpec:
+    id: str
+    api_version: int
+    interfaces: tuple[str, ...]
+    argv: tuple[str, ...]
+    timeout_seconds: int
+@dataclass(frozen=True)
+class LlmsTxtProjection:
+    output: Path
+    title: str | None = None
+    summary: str | None = None
+    include: tuple[Path, ...] = ()
+@dataclass(frozen=True)
+class ContextBundleProjection:
+    id: str
+    output: Path
+    include: tuple[Path, ...]
+@dataclass(frozen=True)
+class StaticDemoProjection:
+    output: Path
+    evidence: Path
+@dataclass(frozen=True)
+class VisualProjection:
+    id: str
+    source: Path
+    human_output: Path
+    agent_output: Path
+@dataclass(frozen=True)
+class ReviewLocator:
+    id: str
+    path: Path
+    extractor: str
+    locator: str
+@dataclass(frozen=True)
+class ReviewContract:
+    id: str
+    mode: str
+    sources: tuple[ReviewLocator, ...]
+    targets: tuple[ReviewLocator, ...]
+@dataclass(frozen=True)
+class PublicDisposition:
+    """A narrowly scoped, documented disposition for one historical finding."""
+    base: str
+    kind: str
+    subject: str
+    documentation: Path
+    replacement: str
+    reason: str
+@dataclass(frozen=True)
+class ProjectionConfig:
+    llms_txt: LlmsTxtProjection | None = None
+    bundles: tuple[ContextBundleProjection, ...] = ()
+    demo: StaticDemoProjection | None = None
+    visuals: tuple[VisualProjection, ...] = ()
+@dataclass(frozen=True)
+class Manifest:
+    path: Path
+    version: int
+    bindings: tuple[Binding, ...]
+    commands: tuple[CommandSpec, ...] = ()
+    plugins: tuple[PluginSpec, ...] = ()
+    projections: ProjectionConfig | None = None
+    source_claim_checks: tuple[SourceClaimCheck, ...] = ()
+    review_contracts: tuple[ReviewContract, ...] = ()
+    public_dispositions: tuple[PublicDisposition, ...] = ()
+    deprecations: tuple[str, ...] = ()
+@dataclass(frozen=True)
+class Provenance:
+    ref: str
+    path: str
+    locator: str
+    extractor: str
+    digest: str
+@dataclass(frozen=True)
+class EvidenceValue:
+    kind: str
+    value: Any
+    provenance: Provenance
+@dataclass(frozen=True)
+class BindingResult:
+    binding_id: str
+    doc: str
+    changed: bool
+    expected: str
+    observed: str
+    diff: str
+    provenance: Provenance
+    binding_type: str = "region"
+    state: str | None = None
+    prose_checked: bool = False