tracecite 0.0.2__py3-none-any.whl

tracecite/docs/__init__.py

@@ -0,0 +1,56 @@
+"""Reusable documentation build and evidence-contract APIs."""
+
+from .build import (
+    BuildSelection,
+    BuildVariant,
+    DocsBuildResult,
+    Language,
+    build_docs,
+    changed_retained_markdown,
+    classify_render_inputs,
+    discover_render_inputs,
+    select_build_variant,
+    snapshot_retained_markdown,
+    stage_retained_markdown,
+)
+from .config import load_docs_contract
+from .contract import DocsEvidenceContract
+from .modes import DocsModeResult, author_docs, check_docs
+from .stage import DocsStageResult, stage_docs
+from .vectorize import (
+    DocsIndexProfile,
+    DocsIndexResult,
+    doctor_docs_index,
+    prepare_docs_index_input,
+    resolve_docs_index_profile,
+    search_docs_index,
+    sync_docs_index,
+)
+
+__all__ = [
+    "BuildSelection",
+    "BuildVariant",
+    "DocsBuildResult",
+    "DocsEvidenceContract",
+    "DocsIndexProfile",
+    "DocsIndexResult",
+    "DocsModeResult",
+    "DocsStageResult",
+    "Language",
+    "author_docs",
+    "build_docs",
+    "changed_retained_markdown",
+    "check_docs",
+    "classify_render_inputs",
+    "discover_render_inputs",
+    "doctor_docs_index",
+    "load_docs_contract",
+    "prepare_docs_index_input",
+    "resolve_docs_index_profile",
+    "search_docs_index",
+    "select_build_variant",
+    "snapshot_retained_markdown",
+    "stage_docs",
+    "stage_retained_markdown",
+    "sync_docs_index",
+]

tracecite/docs/build.py

@@ -0,0 +1,381 @@
+"""Reusable Quarto documentation-build orchestration."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+from ..tables import SiteExportResult, export_embedding_site
+
+Language = Literal["python", "julia"]
+BuildVariant = Literal["combined", "python", "julia", "prose"]
+
+
+@dataclass(frozen=True, slots=True)
+class BuildSelection:
+    variant: BuildVariant
+    profile: str | None
+    included: tuple[Path, ...]
+    skipped: tuple[Path, ...]
+    warning: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class DocsBuildResult:
+    project_root: Path
+    output_root: Path
+    selection: BuildSelection
+    retained_count: int
+    inspection: SiteExportResult | None
+    changed_retained: tuple[Path, ...]
+
+
+def _load_config(project_root: Path) -> dict:
+    path = project_root / "_quarto.yml"
+    if not path.is_file():
+        raise ValueError(f"Quarto project configuration does not exist: {path}")
+    loaded = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def discover_render_inputs(project_root: Path) -> tuple[Path, ...]:
+    """Expand the base project's ordered ``project.render`` entries."""
+    project_root = Path(project_root).resolve()
+    config = _load_config(project_root)
+    render = (config.get("project") or {}).get("render", [])
+    if isinstance(render, str):
+        render = [render]
+    found: list[Path] = []
+    for pattern in render:
+        if not isinstance(pattern, str) or pattern.startswith("!"):
+            continue
+        matches = sorted(project_root.glob(pattern))
+        for match in matches:
+            if (
+                match.is_file()
+                and not match.name.endswith(".html.md")
+                and match not in found
+            ):
+                found.append(match)
+    return tuple(found)
+
+
+def _qmd_language(path: Path) -> Language | None:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return None
+    end = text.find("\n---", 3)
+    if end < 0:
+        return None
+    metadata = yaml.safe_load(text[3:end]) or {}
+    engine = str(metadata.get("jupyter", metadata.get("engine", ""))).lower()
+    if "julia" in engine:
+        return "julia"
+    if engine in {"python", "python3", "jupyter"} or "python" in engine:
+        return "python"
+    return None
+
+
+def classify_render_inputs(paths: Sequence[Path]) -> dict[Language, tuple[Path, ...]]:
+    result: dict[Language, list[Path]] = {"python": [], "julia": []}
+    for path in paths:
+        suffix = path.suffix.lower()
+        language = {".py": "python", ".jl": "julia"}.get(suffix)
+        if suffix == ".qmd":
+            language = _qmd_language(path)
+        if language:
+            result[language].append(path)
+    return {key: tuple(value) for key, value in result.items()}
+
+
+def _normalize_input_path(path: Path, project_root: Path) -> Path:
+    """Resolve an input path when it stays inside the project root."""
+    candidate = path if path.is_absolute() else project_root / path
+    resolved = candidate.resolve()
+    try:
+        resolved.relative_to(project_root)
+    except ValueError:
+        return candidate
+    return resolved
+
+
+def select_build_variant(
+    project_root: Path,
+    inputs: Sequence[Path],
+    *,
+    only: Language | None = None,
+    julia: str | None = None,
+) -> BuildSelection:
+    project_root = Path(project_root).resolve()
+    inputs = tuple(_normalize_input_path(Path(path), project_root) for path in inputs)
+    classified = classify_render_inputs(inputs)
+    available = {language for language, paths in classified.items() if paths}
+    if only and not classified[only]:
+        raise ValueError(
+            f"Requested language is absent from configured render inputs: {only}"
+        )
+    if only == "julia" and not julia:
+        raise ValueError("Julia-only documentation build requires Julia on PATH")
+    if only and len(available) > 1:
+        overlay = project_root / f"_quarto-{only}.yml"
+        if not overlay.is_file():
+            raise ValueError(
+                f"Explicit {only} build requires reduced overlay: {overlay}"
+            )
+    if only:
+        skipped = tuple(
+            path
+            for language, paths in classified.items()
+            if language != only
+            for path in paths
+        )
+        profile = only if len(available) > 1 else None
+        return BuildSelection(
+            only,
+            profile,
+            tuple(path for path in inputs if path not in skipped),
+            skipped,
+            None,
+        )
+    if available == {"python", "julia"}:
+        if julia:
+            return BuildSelection("combined", None, tuple(inputs), (), None)
+        overlay = project_root / "_quarto-python.yml"
+        if not overlay.is_file():
+            raise ValueError(
+                f"Automatic Python fallback requires reduced overlay: {overlay}"
+            )
+        skipped = classified["julia"]
+        warning = "Julia unavailable; skipping configured files:\n" + "\n".join(
+            f"- {path.relative_to(project_root)}" for path in skipped
+        )
+        included = tuple(path for path in inputs if path not in skipped)
+        return BuildSelection("python", "python", included, skipped, warning)
+    if available == {"julia"}:
+        if julia:
+            return BuildSelection("julia", None, tuple(inputs), (), None)
+        raise ValueError("Configured Julia documentation inputs require Julia on PATH")
+    if available == {"python"}:
+        return BuildSelection("python", None, tuple(inputs), (), None)
+    return BuildSelection("prose", None, tuple(inputs), (), None)
+
+
+def snapshot_retained_markdown(project_root: Path) -> dict[Path, bytes]:
+    project_root = Path(project_root).resolve()
+    output = _output_root(project_root)
+    return {
+        path.relative_to(project_root): path.read_bytes()
+        for path in project_root.rglob("*.html.md")
+        if not path.is_relative_to(output) and ".quarto" not in path.parts
+    }
+
+
+def changed_retained_markdown(
+    before: Mapping[Path, bytes],
+    project_root: Path,
+) -> tuple[Path, ...]:
+    after = snapshot_retained_markdown(project_root)
+    return tuple(
+        sorted(
+            path
+            for path in before.keys() | after.keys()
+            if before.get(path) != after.get(path)
+        )
+    )
+
+
+def stage_retained_markdown(
+    project_root: Path,
+    output_root: Path,
+    inputs: Sequence[Path],
+) -> int:
+    project_root = Path(project_root).resolve()
+    output_root = Path(output_root).resolve()
+    for stale in output_root.rglob("*.html.md") if output_root.exists() else ():
+        stale.unlink()
+    count = 0
+    for authored in inputs:
+        retained = _retained_destination(authored)
+        if not retained.is_file():
+            continue
+        relative = authored.relative_to(project_root)
+        destination = output_root / relative.with_name(relative.stem + ".html.md")
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(retained, destination)
+        count += 1
+    return count
+
+
+def _output_root(project_root: Path) -> Path:
+    project = _load_config(project_root).get("project") or {}
+    return project_root / project.get("output-dir", "_site")
+
+
+def _contains_source_symlinks(project_root: Path, output_root: Path) -> bool:
+    """Return whether a Quarto source tree contains symlinked inputs/resources."""
+    project_root = project_root.resolve()
+    output_root = output_root.resolve()
+    for path in project_root.rglob("*"):
+        if path.is_relative_to(output_root) or ".quarto" in path.parts:
+            continue
+        if path.is_symlink():
+            return True
+    return False
+
+
+def _copy_project_without_build_outputs(
+    project_root: Path,
+    staged_root: Path,
+    output_root: Path,
+) -> None:
+    """Materialise a symlinked Quarto project as ordinary files for rendering."""
+    try:
+        output_relative = output_root.relative_to(project_root)
+    except ValueError as error:
+        raise ValueError(
+            "Symlinked Quarto projects require project.output-dir to remain "
+            f"inside the project root: {output_root}"
+        ) from error
+    if not output_root.resolve().is_relative_to(project_root.resolve()):
+        raise ValueError(
+            "Symlinked Quarto projects require project.output-dir to remain "
+            f"inside the project root: {output_root}"
+        )
+
+    def ignore(directory: str, names: list[str]) -> set[str]:
+        relative = Path(directory).relative_to(project_root)
+        ignored: set[str] = set()
+        for name in names:
+            candidate = relative / name
+            if candidate == output_relative or name == ".quarto":
+                ignored.add(name)
+        return ignored
+
+    shutil.copytree(
+        project_root,
+        staged_root,
+        symlinks=False,
+        ignore=ignore,
+        dirs_exist_ok=True,
+    )
+
+
+def _retained_destination(authored: Path) -> Path:
+    """Return the canonical retained-Markdown destination for an authored input."""
+    canonical = authored.resolve() if authored.is_symlink() else authored
+    return canonical.with_name(canonical.stem + ".html.md")
+
+
+def _publish_materialised_render(
+    staged_root: Path,
+    project_root: Path,
+    inputs: Sequence[Path],
+) -> None:
+    """Publish a successful staged render and its retained Markdown."""
+    staged_output = _output_root(staged_root)
+    output_root = _output_root(project_root)
+    if not staged_output.is_dir():
+        raise RuntimeError(
+            f"Quarto did not create the configured output: {staged_output}"
+        )
+
+    for authored in inputs:
+        relative = authored.relative_to(project_root)
+        staged_authored = staged_root / relative
+        staged_retained = staged_authored.with_name(staged_authored.stem + ".html.md")
+        if not staged_retained.is_file():
+            continue
+        destination = _retained_destination(authored)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(staged_retained, destination)
+
+    if output_root.exists() or output_root.is_symlink():
+        if output_root.is_symlink() or output_root.is_file():
+            output_root.unlink()
+        else:
+            shutil.rmtree(output_root)
+    shutil.copytree(staged_output, output_root, symlinks=False)
+
+
+@contextmanager
+def _render_project_root(
+    project_root: Path,
+    output_root: Path,
+) -> Iterator[tuple[Path, bool]]:
+    """Yield a Quarto-safe project root, materialising symlinks when required."""
+    if not _contains_source_symlinks(project_root, output_root):
+        yield project_root, False
+        return
+
+    staged_root = Path(
+        tempfile.mkdtemp(
+            prefix=f".{project_root.name}-render-",
+            dir=project_root.parent,
+        )
+    )
+    try:
+        _copy_project_without_build_outputs(project_root, staged_root, output_root)
+        yield staged_root, True
+    finally:
+        shutil.rmtree(staged_root, ignore_errors=True)
+
+
+def build_docs(
+    project_root: str | Path,
+    *,
+    only: Language | None = None,
+    quarto: str | Path | None = None,
+    inspection: bool = True,
+    render_inspection: bool = True,
+    strict_tables: bool = False,
+    check_retained: bool = False,
+) -> DocsBuildResult:
+    project_root = Path(project_root).resolve()
+    quarto_command = str(quarto) if quarto else shutil.which("quarto")
+    if not quarto_command:
+        raise FileNotFoundError("Quarto is required. Install Quarto or pass --quarto.")
+    inputs = discover_render_inputs(project_root)
+    julia = shutil.which("julia")
+    selection = select_build_variant(project_root, inputs, only=only, julia=julia)
+    if selection.warning:
+        print(selection.warning)
+    before = snapshot_retained_markdown(project_root) if check_retained else {}
+    output_root = _output_root(project_root)
+    with _render_project_root(project_root, output_root) as (render_root, staged):
+        command = [quarto_command, "render", render_root.name]
+        if selection.profile:
+            command.extend(["--profile", selection.profile])
+        subprocess.run(command, cwd=render_root.parent, check=True)
+        if staged:
+            _publish_materialised_render(
+                render_root,
+                project_root,
+                selection.included,
+            )
+    retained_count = stage_retained_markdown(
+        project_root, output_root, selection.included
+    )
+    exported = None
+    if inspection:
+        exported = export_embedding_site(
+            output_root,
+            project_root.parent / ".tracecite" / "embedding-site",
+            project_config=project_root / "_quarto.yml",
+            project_profile=selection.profile,
+            source_project=project_root,
+            strict=strict_tables,
+            render=render_inspection,
+            quarto=quarto_command,
+        )
+    changed = changed_retained_markdown(before, project_root) if check_retained else ()
+    return DocsBuildResult(
+        project_root, output_root, selection, retained_count, exported, changed
+    )

tracecite/docs/config.py

@@ -0,0 +1,114 @@
+"""TOML loading and deterministic validation for the docs contract."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from .contract import DocsEvidenceContract
+
+_FIELDS = {
+    "authored_root",
+    "retained_root",
+    "staged_root",
+    "source_links",
+    "index_output",
+    "publication_exclude",
+    "host_render_command",
+}
+
+
+def _path(value: object, *, name: str, repo_root: Path) -> Path:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{name} must be a non-empty repository-relative path")
+    raw = Path(value)
+    if raw.is_absolute():
+        raise ValueError(f"{name} must be repository-relative")
+    if ".." in raw.parts:
+        raise ValueError(f"{name} must not escape the repository")
+    resolved = (repo_root / raw).resolve(strict=False)
+    if not resolved.is_relative_to(repo_root):
+        raise ValueError(f"{name} resolves outside the repository")
+    return resolved
+
+
+def _overlap(left: Path, right: Path) -> bool:
+    return left.is_relative_to(right) or right.is_relative_to(left)
+
+
+def load_docs_contract(
+    path: str | Path, *, repo_root: str | Path
+) -> DocsEvidenceContract:
+    config_path = Path(path).resolve()
+    root = Path(repo_root).resolve()
+    try:
+        data = tomllib.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ValueError(f"invalid docs configuration: {exc}") from exc
+    if data.get("schema_version") != 1:
+        raise ValueError("docs configuration requires schema_version = 1")
+    if set(data) - {"schema_version", "docs"} or not isinstance(data.get("docs"), dict):
+        raise ValueError("docs configuration requires a [docs] table")
+    docs = data["docs"]
+    unknown = set(docs) - _FIELDS
+    if unknown:
+        raise ValueError(
+            f"unknown docs configuration field(s): {', '.join(sorted(unknown))}"
+        )
+    missing = _FIELDS - set(docs) - {"host_render_command"}
+    if missing:
+        raise ValueError(
+            f"missing docs configuration field(s): {', '.join(sorted(missing))}"
+        )
+
+    authored = _path(docs.get("authored_root"), name="authored_root", repo_root=root)
+    retained = _path(docs.get("retained_root"), name="retained_root", repo_root=root)
+    staged = _path(docs.get("staged_root"), name="staged_root", repo_root=root)
+    source_links = _path(docs.get("source_links"), name="source_links", repo_root=root)
+    index_output = _path(docs.get("index_output"), name="index_output", repo_root=root)
+    if not authored.is_dir() or not retained.is_dir():
+        raise ValueError("authored_root and retained_root must be existing directories")
+    if not source_links.is_file():
+        raise ValueError("source_links must be an existing file")
+    if _overlap(retained, staged):
+        raise ValueError("retained_root and staged_root must not overlap")
+    roots = (authored, retained, staged, source_links, index_output)
+    for index, left in enumerate(roots):
+        for right in roots[index + 1 :]:
+            if (left == authored and right == retained) or (
+                left == retained and right == authored
+            ):
+                if not _overlap(left, right) or left == right:
+                    continue
+                raise ValueError(
+                    "authored_root and retained_root may overlap only when equal"
+                )
+            if _overlap(left, right):
+                raise ValueError("docs contract paths must not contain one another")
+
+    excludes = docs.get("publication_exclude")
+    if not isinstance(excludes, list):
+        raise ValueError("publication_exclude must be an array")  # noqa: TRY004
+    publication_exclude = tuple(
+        _path(value, name="publication_exclude", repo_root=root) for value in excludes
+    )
+    command = docs.get("host_render_command")
+    if command is not None:
+        if (
+            not isinstance(command, list)
+            or not command
+            or not all(isinstance(item, str) and item for item in command)
+        ):
+            raise ValueError("host_render_command must be a non-empty argument array")
+        command_tuple = tuple(command)
+    else:
+        command_tuple = None
+    return DocsEvidenceContract(
+        authored,
+        retained,
+        staged,
+        source_links,
+        index_output,
+        publication_exclude,
+        command_tuple,
+    )

tracecite/docs/contract.py

@@ -0,0 +1,17 @@
+"""Validated, repository-neutral documentation evidence contract."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class DocsEvidenceContract:
+    authored_root: Path
+    retained_root: Path
+    staged_root: Path
+    source_links: Path
+    index_output: Path
+    publication_exclude: tuple[Path, ...]
+    host_render_command: tuple[str, ...] | None = None