texmodel 0.2.0__py3-none-any.whl

texmodel_build/result.py

@@ -0,0 +1,65 @@
+"""`CompileResult` (C1): a failed compile is a result, not an exception (E3)."""
+
+import dataclasses
+import pathlib
+from typing import Any, Self
+
+from .diagnostics import Diagnostic, Measurement, Severity, diagnostic_from_dict
+from .errors import CompileError
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class CompileResult:
+    pdf: pathlib.Path | None
+    log: pathlib.Path | None
+    passes: int
+    pages: int | None
+    diagnostics: tuple[Diagnostic, ...]
+    seconds: float
+    engine: str
+    engine_version: str
+    latexmk_version: str
+    image: str | None = None  # None: ran on the host, not in the reference image
+    image_digest: str | None = None
+    image_revision: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.pdf is not None and not self.errors
+
+    @property
+    def errors(self) -> tuple[Diagnostic, ...]:
+        return tuple(d for d in self.diagnostics if d.severity is Severity.ERROR)
+
+    @property
+    def probes(self) -> dict[str, str]:
+        return {d.name: d.value for d in self.diagnostics if isinstance(d, Measurement)}
+
+    def probe(self, name: str) -> str:
+        return self.probes[name]
+
+    def raise_for_status(self) -> None:
+        if self.ok:
+            return
+        first = self.errors[0] if self.errors else None
+        raise CompileError(
+            f"compile failed: {len(self.errors)} error(s)"
+            + (f", first: {first.code} {first.message}" if first else ""),
+            code=first.code if first else "TM-X099",
+            diagnostics=self.diagnostics,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        data = dataclasses.asdict(self)
+        data["pdf"] = str(self.pdf) if self.pdf else None
+        data["log"] = str(self.log) if self.log else None
+        data["diagnostics"] = [d.to_dict() for d in self.diagnostics]
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], **override: Any) -> Self:
+        data = {**data, **override}
+        data["pdf"] = pathlib.Path(data["pdf"]) if data["pdf"] else None
+        data["log"] = pathlib.Path(data["log"]) if data["log"] else None
+        data["diagnostics"] = tuple(diagnostic_from_dict(d) for d in data["diagnostics"])
+        return cls(**data)

texmodel_build/roots.py

@@ -0,0 +1,41 @@
+"""Ordered asset roots (C4): the first root holding a name wins, and the rest are reported as shadowed."""
+
+import dataclasses
+import logging
+import pathlib
+from collections.abc import Sequence
+
+from texmodel.errors import ValidationError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclasses.dataclass(frozen=True)
+class Resolution:
+    name: str
+    path: pathlib.Path
+    shadowed: tuple[pathlib.Path, ...] = ()
+
+
+def resolve(name: str, roots: Sequence[pathlib.Path]) -> Resolution | None:
+    """Find `name` under `roots`; the winner is the earliest root. Absolute names and `..` are refused (Z1)."""
+    rel = pathlib.PurePosixPath(name)
+    if rel.is_absolute() or ".." in rel.parts:
+        raise ValidationError(
+            f"asset name {name!r} escapes the asset roots", code="TM-C100", hint="use a relative name"
+        )
+    hits = [root / name for root in roots if (root / name).is_file()]
+    if not hits:
+        return None
+    if len(hits) > 1:
+        logger.warning("asset %s exists in %d roots; %s wins over %s", name, len(hits), hits[0], hits[1:])
+    return Resolution(name, hits[0], tuple(hits[1:]))
+
+
+def shadowing(roots: Sequence[pathlib.Path]) -> list[Resolution]:
+    """Every name present in more than one root, with the winner and what it hides."""
+    seen: dict[str, list[pathlib.Path]] = {}
+    for root in roots:
+        for path in sorted(p for p in root.rglob("*") if p.is_file()):
+            seen.setdefault(path.relative_to(root).as_posix(), []).append(path)
+    return [Resolution(name, paths[0], tuple(paths[1:])) for name, paths in sorted(seen.items()) if len(paths) > 1]

texmodel_build/targets.py

@@ -0,0 +1,43 @@
+"""Build every declared target (C10): reruns until stable are the compiler's, this adds parallelism and one summary."""
+
+import dataclasses
+import pathlib
+from collections.abc import Iterable
+from concurrent.futures import ThreadPoolExecutor
+
+from texmodel.pointer import load_plan
+
+from .compiler import Compiler
+from .config import Target
+from .engines import get_engine
+from .result import CompileResult
+
+
+@dataclasses.dataclass(frozen=True)
+class BuildSummary:
+    results: dict[str, CompileResult]
+
+    @property
+    def ok(self) -> bool:
+        return all(r.ok for r in self.results.values())
+
+    def lines(self) -> list[str]:
+        return [
+            f"{'ok    ' if r.ok else 'FAILED'} {name}: {len(r.errors)} error(s), {r.pages} page(s), {r.seconds}s"
+            for name, r in self.results.items()
+        ]
+
+
+def build_targets(
+    targets: Iterable[Target], compiler: Compiler, *, root: pathlib.Path, outdir: pathlib.Path, jobs: int = 1
+) -> BuildSummary:
+    """Compile each target into `outdir/<name>`; the engine comes from the target. Results keep declared order."""
+    chosen = list(targets)
+
+    def one(target: Target) -> CompileResult:
+        mine = dataclasses.replace(compiler, engine=get_engine(target.engine))
+        plan = load_plan(target.plan, root) if target.plan else None
+        return mine.compile(root / target.source, outdir / target.name, plan=plan)
+
+    with ThreadPoolExecutor(max_workers=max(1, jobs)) as pool:
+        return BuildSummary({t.name: r for t, r in zip(chosen, pool.map(one, chosen), strict=True)})

texmodel_build/testkit.py

@@ -0,0 +1,59 @@
+"""Contract checks a verifier plugin must pass (L1). Plain asserts, so any test runner can call them."""
+
+import pathlib
+import tempfile
+from collections.abc import Mapping
+
+from texmodel.errors import Violation
+from texmodel.package import Package, PreambleSlots
+from texmodel.plan import Plan
+from texmodel.testing import check_exports, export_probes
+from texmodel.types import Raw
+
+from .compiler import Compiler
+from .diagnostics import Measurement
+from .verify import Profile, Verifier, verify_file
+
+
+def run_probes(
+    compiler: Compiler, tex: str, files: Mapping[str, str] | None = None, *, plans: Mapping[str, Plan] | None = None
+) -> list[Measurement]:
+    """Compile `tex` and return its `texmodel:probe:` lines in log order (§21a 20, C5a). `files` are written beside it
+    first (path -> text: the `.sty` the document loads); the build directory is removed afterwards. A document that
+    does not compile raises `CompileError`, so a test never reads probes from a broken run; its diagnostics carry the
+    `path` from `plans` (file name -> the plan that wrote it)."""
+    with tempfile.TemporaryDirectory() as tmp:
+        work = pathlib.Path(tmp).resolve() / "src"
+        for rel, text in {**(files or {}), "probe.tex": tex}.items():
+            path = work / rel
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(text, encoding="utf-8")
+        result = compiler.compile(work / "probe.tex", pathlib.Path(tmp).resolve() / "out", plans=plans)
+        result.raise_for_status()
+        return [d for d in result.diagnostics if isinstance(d, Measurement)]
+
+
+def check_library(compiler: Compiler, package: Package, files: Mapping[str, str] | None = None) -> list[Violation]:
+    """Compile `package` and check that every component a library block defines exists with the declared arguments
+    (§21a 12): `Package.test_document` with `export_probes`, run with `run_probes`, read by `check_exports`. A block
+    TeX refuses raises `CompileError` whose diagnostics name the block as their `path`. `files` are other files the
+    package loads."""
+    tex = package.test_document(preamble=PreambleSlots(after_package=(Raw(export_probes(package)),)))
+    sty = f"{package.name}.sty"
+    found = run_probes(compiler, tex, {sty: package.render(), **(files or {})}, plans={sty: package.render_plan()})
+    return check_exports(package, {m.name: m.value for m in found})
+
+
+def check_verifier_contract(verifier: Verifier, tmp_path: pathlib.Path) -> None:
+    """A verifier names itself, and a missing file or an unavailable tool fails; neither passes nor raises."""
+    assert isinstance(verifier.name, str) and verifier.name, "a verifier needs a non-empty name"
+    available = {verifier.name: verifier}
+    profile = Profile(checks=(verifier.name,))
+    report = verify_file(tmp_path / "does-not-exist", profile, available)
+    assert not report.ok, "a missing file must fail, not pass"
+    why = verifier.unavailable({})
+    assert why is None or isinstance(why, str), "unavailable() returns a reason or None"
+    if why is not None:
+        present = tmp_path / "present"
+        present.write_bytes(b"x")
+        assert not verify_file(present, profile, available).ok, "an unavailable verifier must fail the file"

texmodel_build/verify.py

@@ -0,0 +1,158 @@
+"""Verifier plugins (V4, V5, L1): checks over a built file, discovered through entry points.
+
+A verifier is any object with a `name`, an `unavailable(options)` that says why it cannot run here (or `None`), and a
+`verify(path, options)` returning findings. Register it in the `texmodel_build.verifiers` entry-point group, as a
+callable that returns the verifier.
+
+The rule that matters is V5, **unconfirmable means failure**: a verifier that cannot run, a file that cannot be opened,
+a plugin that crashes, and a profile that selects nothing are all errors, never skips. The only way to excuse a file is
+the exemption registry, which keeps it listed with its reason.
+"""
+
+import dataclasses
+import fnmatch
+import importlib.metadata
+import pathlib
+from collections.abc import Mapping, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Protocol
+
+from .diagnostics import Severity
+from .errors import ToolchainError
+
+GROUP = "texmodel_build.verifiers"
+
+
+@dataclasses.dataclass(frozen=True)
+class Finding:
+    """One issue a check raised, optionally tied to a 1-based page."""
+
+    check: str
+    severity: Severity
+    message: str
+    page: int | None = None
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Profile:
+    """Which verifiers to run (empty: every registered one) and their options, keyed by verifier name."""
+
+    name: str = "default"
+    checks: tuple[str, ...] = ()
+    options: Mapping[str, Mapping[str, Any]] = dataclasses.field(default_factory=dict[str, Mapping[str, Any]])
+
+
+@dataclasses.dataclass(frozen=True)
+class FileReport:
+    path: pathlib.Path
+    findings: tuple[Finding, ...] = ()
+    exempt: str | None = None  # why the file was declared out of scope; listed, never a failure
+
+    @property
+    def errors(self) -> tuple[Finding, ...]:
+        return tuple(f for f in self.findings if f.severity is Severity.ERROR)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+class Verifier(Protocol):
+    name: str
+
+    def unavailable(self, options: Mapping[str, Any]) -> str | None:
+        """Why this verifier cannot run here with these options (a missing tool, say), or `None`."""
+        ...
+
+    def verify(self, path: pathlib.Path, options: Mapping[str, Any]) -> Sequence[Finding]: ...
+
+
+def registered() -> dict[str, Verifier]:
+    """Every verifier in the entry-point group. A plugin that fails to load is an error, not a silent omission."""
+    found: dict[str, Verifier] = {}
+    for entry in importlib.metadata.entry_points(group=GROUP):
+        try:
+            verifier: Verifier = entry.load()()
+        except Exception as exc:
+            raise ToolchainError(
+                f"verifier plugin {entry.name!r} failed to load: {exc!r}", code="TM-V001", hint="reinstall the plugin"
+            ) from exc
+        found[verifier.name] = verifier
+    return found
+
+
+def exemption(path: pathlib.PurePath, exempt: Mapping[str, str]) -> str | None:
+    """The reason `path` is exempt: a glob matching the path or any trailing part of it (`res/**`, `*_preview.pdf`)."""
+    parts = path.as_posix().split("/")
+    tails = ["/".join(parts[i:]) for i in range(len(parts))]
+    for glob, reason in exempt.items():
+        if any(fnmatch.fnmatch(tail, glob) for tail in tails):
+            return reason
+    return None
+
+
+def verify_file(
+    path: pathlib.Path,
+    profile: Profile,
+    available: Mapping[str, Verifier],
+    exempt: Mapping[str, str] | None = None,
+) -> FileReport:
+    """Run the profile's verifiers over one file. Reports; never raises for a bad file or a bad plugin."""
+    if reason := exemption(path, exempt or {}):
+        return FileReport(path, exempt=reason)
+    names = profile.checks or tuple(available)
+    if not names:
+        return FileReport(
+            path, (Finding("verify", Severity.ERROR, "no verifier selected or installed: nothing was checked"),)
+        )
+    if not path.is_file():
+        return FileReport(path, (Finding("open", Severity.ERROR, "no such file"),))
+    findings: list[Finding] = []
+    for name in names:
+        verifier = available.get(name)
+        if verifier is None:
+            findings.append(Finding(name, Severity.ERROR, f"unknown verifier; installed: {sorted(available)}"))
+            continue
+        options = profile.options.get(name, {})
+        if why := verifier.unavailable(options):
+            findings.append(Finding(name, Severity.ERROR, f"cannot confirm: {why}"))
+            continue
+        try:
+            findings.extend(verifier.verify(path, options))
+        except Exception as exc:
+            findings.append(Finding(name, Severity.ERROR, f"verifier crashed: {exc!r}"))
+    return FileReport(path, tuple(findings))
+
+
+def verify_files(
+    paths: Sequence[pathlib.Path],
+    profile: Profile,
+    available: Mapping[str, Verifier],
+    exempt: Mapping[str, str] | None = None,
+    *,
+    jobs: int = 1,
+) -> list[FileReport]:
+    """One report per path, in order."""
+
+    def one(path: pathlib.Path) -> FileReport:
+        return verify_file(path, profile, available, exempt)
+
+    with ThreadPoolExecutor(max_workers=max(1, jobs)) as pool:
+        return list(pool.map(one, paths))
+
+
+def expand_targets(
+    paths: Sequence[pathlib.Path], exclude: Sequence[str] = (), suffix: str = ".pdf"
+) -> list[pathlib.Path]:
+    """Files as given; a directory expands to every `suffix` file beneath it minus `exclude` globs (relative to it)."""
+    out: list[pathlib.Path] = []
+    for path in paths:
+        if path.is_dir():
+            out += [
+                p
+                for p in sorted(path.rglob(f"*{suffix}"))
+                if exemption(p.relative_to(path), dict.fromkeys(exclude, "")) is None
+            ]
+        else:
+            out.append(path)
+    return out