paperkit 0.1.0__py3-none-any.whl

paperkit/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (C) 2026 Vrije Universiteit Brussel. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""paperkit: reproducible builds and pre-submission checks for research papers."""
+
+__version__ = "0.1.0"

paperkit/archive.py

@@ -0,0 +1,183 @@
+# Copyright (C) 2026 Vrije Universiteit Brussel. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""Submission zip creation."""
+
+import datetime as dt
+import fnmatch
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from paperkit import reproducible
+from paperkit.config import PaperkitConfig
+
+# Zip stores DOS timestamps, which cannot predate 1980.
+_DOS_EPOCH = dt.datetime(1980, 1, 1, tzinfo=dt.UTC)
+
+
+def _expand_pattern(root: Path, pattern: str) -> list[Path]:
+    """Expand a glob-style include pattern relative to root.
+
+    Supports {main} placeholder for the main .tex filename.
+    """
+    # Trailing / means include directory recursively
+    if pattern.endswith("/"):
+        d = root / pattern.rstrip("/")
+        if d.is_dir():
+            return sorted(d.rglob("*"))
+        return []
+    return sorted(root.glob(pattern))
+
+
+def _is_excluded(path: Path, excludes: list[str]) -> bool:
+    """Check if a path matches any exclude pattern."""
+    name = path.name
+    return any(fnmatch.fnmatch(name, pat) for pat in excludes)
+
+
+@dataclass
+class ZipResult:
+    """The archive that was written, and anything the caller should be told."""
+
+    path: Path
+    warnings: list[str] = field(default_factory=list)
+
+
+class MissingBblError(Exception):
+    """A requested compiled bibliography is not in the build directory."""
+
+
+def _bbl_entries(config: PaperkitConfig, files: set[Path]) -> tuple[dict[str, Path], list[str]]:
+    """Compiled bibliographies to add, keyed by their path inside the archive.
+
+    One per main whose .tex the archive already carries, taken from the build
+    directory and stored next to that .tex, since a publisher compiling the
+    archive alone looks for <main>.bbl there.
+    """
+    root = config.root
+    entries: dict[str, Path] = {}
+    warnings: list[str] = []
+    missing: list[str] = []
+
+    for main in config.mains or [config.main]:
+        tex = root / f"{main}.tex"
+        if tex not in files:
+            continue  # this main is not part of the archive
+        bbl = root / config.output_dir / main / f"{main}.bbl"
+        if not bbl.is_file():
+            missing.append(f"{bbl.relative_to(root)}")
+            continue
+        entries[f"{main}.bbl"] = bbl
+        warnings += _staleness_warnings(config, main, bbl, tex)
+
+    if missing:
+        raise MissingBblError(
+            "compiled bibliography not found: "
+            + ", ".join(missing)
+            + "; run `paperkit build` first",
+        )
+    return entries, warnings
+
+
+def _staleness_warnings(config: PaperkitConfig, main: str, bbl: Path, tex: Path) -> list[str]:
+    """Warn when the .bbl predates the sources it was compiled from."""
+    warnings = []
+    bbl_mtime = bbl.stat().st_mtime
+    sources = [tex]
+    if config.bib:
+        sources.append(config.root / config.bib)
+    for source in sources:
+        if source.is_file() and source.stat().st_mtime > bbl_mtime:
+            name = source.relative_to(config.root)
+            warnings.append(
+                f"{main}.bbl is older than {name}: the archive may not match the "
+                f"sources, rebuild with `paperkit build`",
+            )
+    return warnings
+
+
+def create_zip(config: PaperkitConfig, include_bbl: bool | None = None) -> ZipResult:
+    """Create the submission zip archive.
+
+    *include_bbl* overrides `[zip] include_bbl` for this run.
+    """
+    root = config.root
+    zip_name = config.zip.name or config.main
+    zip_path = root / f"{zip_name}-sources.zip"
+
+    # Resolve {main} in patterns: expands once per main, so a single
+    # "{main}.tex" entry in the zip include list pulls in every project's .tex.
+    mains = config.mains or [config.main]
+    includes: list[str] = []
+    for include in config.zip.include:
+        if "{main}" in include:
+            includes.extend(include.replace("{main}", m) for m in mains)
+        else:
+            includes.append(include)
+
+    # Collect files
+    files: set[Path] = set()
+    for pattern in includes:
+        for p in _expand_pattern(root, pattern):
+            if p.is_file() and not _is_excluded(p, config.zip.exclude):
+                files.add(p)
+
+    # Resolved before the old archive is removed, so a missing .bbl leaves it
+    # in place. The exclude patterns do not apply: these are asked for by name.
+    wanted = config.zip.include_bbl if include_bbl is None else include_bbl
+    bbl_entries, warnings = _bbl_entries(config, files) if wanted else ({}, [])
+
+    # Entry metadata is normalized to the build timestamp, so the same sources
+    # archive to the same bytes on another machine or a fresh clone, where the
+    # files' own mtimes differ.
+    source_date = reproducible.resolve(config.source_date_epoch, root)
+    entries = {str(f.relative_to(root)): f for f in files}
+    entries.update(bbl_entries)
+
+    zip_path.unlink(missing_ok=True)
+    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for arcname in sorted(entries):
+            zf.writestr(
+                _entry_info(arcname, entries[arcname], source_date), entries[arcname].read_bytes()
+            )
+
+    return ZipResult(zip_path, warnings)
+
+
+def _entry_info(
+    arcname: str, source: Path, source_date: reproducible.SourceDate
+) -> zipfile.ZipInfo:
+    """Zip entry whose metadata depends on the sources, not on this machine.
+
+    The timestamp is the build timestamp rather than the file's mtime (git
+    does not restore mtimes, so a fresh clone would archive differently), and
+    the mode keeps only the executable bit. The zip format stores DOS times,
+    which start in 1980 and have two-second resolution.
+    """
+    stamp = max(dt.datetime.fromtimestamp(source_date.epoch, dt.UTC), _DOS_EPOCH)
+    info = zipfile.ZipInfo(arcname, date_time=stamp.timetuple()[:6])
+    info.compress_type = zipfile.ZIP_DEFLATED
+    info.create_system = 3  # Unix, whatever the host
+    executable = source.stat().st_mode & 0o111
+    info.external_attr = (0o755 if executable else 0o644) << 16
+    return info
+
+
+def print_zip_summary(zip_path: Path) -> None:
+    """Print a summary of the created zip."""
+    size_mb = zip_path.stat().st_size / (1024 * 1024)
+    print(f"==> Created: {zip_path}")
+    print(f"    {size_mb:.1f} MiB")
+
+    with zipfile.ZipFile(zip_path, "r") as zf:
+        names = zf.namelist()
+
+    print("")
+    print("Contents:")
+    for name in names[:40]:
+        print(f"  {name}")
+    if len(names) > 40:
+        print(f"  ... ({len(names)} files total)")
+    else:
+        print(f"  ({len(names)} files total)")

paperkit/bibliography.py

@@ -0,0 +1,321 @@
+# Copyright (C) 2026 Vrije Universiteit Brussel. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""Project-wide bibliography checks: unused entries per bib file.
+
+Several build targets may share a bib file, so an entry is unused only if no
+target that uses the file cites it. Which bib files a target uses and which
+keys it cites come from its LaTeX output, never from scanning sources:
+
+  * bibtex:   `\\bibdata{a,b}` and `\\citation{k1,k2}` in the .aux (and the
+              .aux files it pulls in with `\\@input`); `\\citation{*}` is
+              `\\nocite{*}`, which uses every entry.
+  * biber:    the .bcf `<bcf:datasource>` and `<bcf:citekey>` elements.
+
+Targets not built or checked in this run are resolved from their existing
+.aux if it is up to date, else from a draft LaTeX pass into a scratch
+directory. If neither works, the target is "not checked" and no entry it
+might cite is reported as unused.
+"""
+
+import re
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from paperkit.builder import BuildResult, run_latex
+from paperkit.checks import CheckResult, CheckStatus, check_bibtex_tidy
+from paperkit.config import PaperkitConfig
+
+_DIM = "\033[2m"
+_RESET = "\033[0m"
+
+_CITATION_RE = re.compile(r"\\citation\{([^}]*)\}")
+_ABX_CITE_RE = re.compile(r"\\abx@aux@cite\{[^}]*\}\{([^}]+)\}")
+_BIBDATA_RE = re.compile(r"\\bibdata\{([^}]*)\}")
+_INPUT_RE = re.compile(r"\\@input\{([^}]*)\}")
+_BCF_DATASOURCE_RE = re.compile(r"<bcf:datasource\b[^>]*>([^<]+)</bcf:datasource>")
+_BCF_CITEKEY_RE = re.compile(r"<bcf:citekey\b[^>]*>([^<]+)</bcf:citekey>")
+_BIB_ENTRY_RE = re.compile(r"^\s*@(\w+)\s*\{\s*([^,\s{}]+)", re.MULTILINE)
+# Bib "entries" that are not citable references.
+_NON_ENTRY_TYPES = {"string", "preamble", "comment"}
+
+# Only these files can change what a target cites, so they decide whether an
+# existing .aux is still up to date.
+_SOURCE_SUFFIXES = {".tex", ".sty", ".cls", ".bib", ".bst", ".bbx", ".cbx", ".def", ".cfg"}
+
+
+@dataclass
+class AuxData:
+    """What a target's LaTeX run recorded about its bibliography."""
+
+    bibdata: list[str] = field(default_factory=list)  # bib names as written
+    citations: set[str] = field(default_factory=set)
+    cite_all: bool = False  # \nocite{*}
+
+
+@dataclass
+class TargetUsage:
+    """Bib files used and keys cited by one build target."""
+
+    name: str
+    bib_files: set[Path]
+    citations: set[str]
+    cite_all: bool
+    origin: str  # "this run", "existing .aux", "draft pass"
+
+
+def parse_aux(aux_path: Path) -> AuxData:
+    """Parse an .aux file and the .aux files it includes with \\@input."""
+    return _parse_aux(aux_path.resolve(), aux_path.resolve().parent, set())
+
+
+def _parse_aux(aux_path: Path, base: Path, seen: set[Path]) -> AuxData:
+    data = AuxData()
+    if aux_path in seen or not aux_path.is_file():
+        return data
+    seen.add(aux_path)
+
+    text = aux_path.read_text(errors="replace")
+    for m in _BIBDATA_RE.finditer(text):
+        data.bibdata += [b.strip() for b in m.group(1).split(",") if b.strip()]
+    keys = [k for m in _CITATION_RE.finditer(text) for k in m.group(1).split(",")]
+    keys += [m.group(1) for m in _ABX_CITE_RE.finditer(text)]
+    _add_keys(data, keys)
+
+    for m in _INPUT_RE.finditer(text):
+        # Every \@input path, however deeply nested, is relative to the output
+        # directory holding the main .aux.
+        nested = _parse_aux((base / m.group(1).strip()).resolve(), base, seen)
+        data.bibdata += [b for b in nested.bibdata if b not in data.bibdata]
+        data.citations |= nested.citations
+        data.cite_all = data.cite_all or nested.cite_all
+    return data
+
+
+def parse_bcf(bcf_path: Path) -> AuxData:
+    """Parse biblatex's control file (.bcf), which biber reads."""
+    data = AuxData()
+    if not bcf_path.is_file():
+        return data
+    text = bcf_path.read_text(errors="replace")
+    data.bibdata = [m.group(1).strip() for m in _BCF_DATASOURCE_RE.finditer(text)]
+    _add_keys(data, [m.group(1) for m in _BCF_CITEKEY_RE.finditer(text)])
+    return data
+
+
+def _add_keys(data: AuxData, keys: list[str]) -> None:
+    for key in (k.strip() for k in keys):
+        if key == "*":
+            data.cite_all = True
+        elif key:
+            data.citations.add(key)
+
+
+def resolve_bib_file(root: Path, name: str) -> Path | None:
+    """Project bib file for a \\bibdata / datasource name, or None.
+
+    Names resolve against the project root (where paperkit points bibtex and
+    biber). Files found only in the TeX tree (e.g. IEEEabrv) are not the
+    project's and are left out.
+    """
+    path = root / name
+    if path.suffix != ".bib":
+        path = path.with_name(path.name + ".bib")
+    return path.resolve() if path.is_file() else None
+
+
+def usage_from_dir(
+    config: PaperkitConfig,
+    name: str,
+    directory: Path,
+    origin: str,
+) -> TargetUsage | None:
+    """Usage recorded in *directory*'s <name>.aux (and .bcf with biber)."""
+    aux = directory / f"{name}.aux"
+    if not aux.is_file():
+        return None
+    data = parse_aux(aux)
+    if config.biber:
+        bcf = parse_bcf(directory / f"{name}.bcf")
+        data.bibdata += bcf.bibdata
+        data.citations |= bcf.citations
+        data.cite_all = data.cite_all or bcf.cite_all
+    bib_files = {p for b in data.bibdata if (p := resolve_bib_file(config.root, b))}
+    return TargetUsage(name, bib_files, data.citations, data.cite_all, origin)
+
+
+def _newest_source_mtime(config: PaperkitConfig, name: str, usage: TargetUsage) -> float:
+    """Newest modification time of anything that can change *name*'s citations."""
+    out_dir = (config.root / config.output_dir).resolve()
+    paths = [config.root / f"{name}.tex", *usage.bib_files]
+    if config.bib:
+        paths.append(config.root / config.bib)
+    for d in config.content_dirs:
+        for p in (config.root / d).rglob("*"):
+            if p.suffix in _SOURCE_SUFFIXES and out_dir not in p.resolve().parents:
+                paths.append(p)
+    return max((p.stat().st_mtime for p in paths if p.is_file()), default=0.0)
+
+
+def is_up_to_date(config: PaperkitConfig, usage: TargetUsage, aux: Path) -> bool:
+    return aux.stat().st_mtime > _newest_source_mtime(config, usage.name, usage)
+
+
+def draft_usage(config: PaperkitConfig, name: str) -> TargetUsage | None:
+    """Citations of *name* from one draft LaTeX pass into a scratch directory.
+
+    No PDF is written (shell-escape tools such as minted still run), and the
+    real output directory is not touched. None if the pass fails.
+    """
+    flag = "-no-pdf" if config.engine == "xelatex" else "-draftmode"
+    with tempfile.TemporaryDirectory(prefix=f"paperkit-draft-{name}-") as tmp:
+        rc = run_latex(
+            config.engine,
+            config.root / f"{name}.tex",
+            Path(tmp),
+            shell_escape=config.shell_escape,
+            extra_args=[flag],
+        )
+        if rc != 0:
+            return None
+        return usage_from_dir(config, name, Path(tmp), "draft pass")
+
+
+def resolve_other_targets(
+    config: PaperkitConfig,
+    known: dict[str, TargetUsage],
+    skip: set[str],
+) -> tuple[dict[str, TargetUsage], list[str]]:
+    """Usage of every main not in *known*: (resolved usages, names not checked).
+
+    Mains in *skip* (e.g. a failed build in this run) are not checked.
+    """
+    usages = dict(known)
+    unchecked: list[str] = []
+    for name in config.mains:
+        if name in usages:
+            continue
+        if name in skip:
+            unchecked.append(name)
+            continue
+        out_dir = config.root / config.output_dir / name
+        usage = usage_from_dir(config, name, out_dir, "existing .aux")
+        if usage and is_up_to_date(config, usage, out_dir / f"{name}.aux"):
+            usages[name] = usage
+            continue
+        if config.checks.unused_bib.draft_pass:
+            print(f"  {_DIM}citations of {name}: draft {config.engine} pass ...{_RESET}")
+            usage = draft_usage(config, name)
+            if usage:
+                usages[name] = usage
+                continue
+        unchecked.append(name)
+    return usages, unchecked
+
+
+def bib_entry_keys(bib_path: Path) -> set[str]:
+    text = bib_path.read_text(errors="replace")
+    return {
+        m.group(2).strip()
+        for m in _BIB_ENTRY_RE.finditer(text)
+        if m.group(1).lower() not in _NON_ENTRY_TYPES
+    }
+
+
+def unused_bib_checks(
+    config: PaperkitConfig,
+    usages: dict[str, TargetUsage],
+    unchecked: list[str],
+    focus: list[str],
+) -> list[CheckResult]:
+    """One "Unused bib entries" result per bib file used by the *focus* targets."""
+    focus_usages = [usages[n] for n in focus if n in usages]
+    configured = resolve_bib_file(config.root, config.bib) if config.bib else None
+    bib_files = {p for u in focus_usages for p in u.bib_files}
+    # A configured bib file no target declares (e.g. bibliography commented
+    # out) is still checked against the focus targets' citations.
+    legacy = configured is not None and not any(configured in u.bib_files for u in usages.values())
+    if legacy and configured is not None:
+        bib_files.add(configured)
+
+    if not focus_usages or not bib_files:
+        skipped = CheckResult(name="Unused bib entries")
+        skipped.messages.append("Skipped (aux or bib file not found)")
+        return [skipped]
+
+    ignore = set(config.checks.unused_bib.ignore)
+    root = config.root.resolve()
+    multi = len(config.mains) > 1
+    results = []
+    for bib in sorted(bib_files):
+        users = [u for u in usages.values() if bib in u.bib_files]
+        if legacy and bib == configured:
+            users = focus_usages
+        rel = bib.relative_to(root) if bib.is_relative_to(root) else bib
+        name = "Unused bib entries" if len(bib_files) == 1 else f"Unused bib entries ({rel})"
+        results.append(_unused_result(name, bib, users, unchecked, ignore, multi))
+    return results
+
+
+def _unused_result(
+    name: str,
+    bib: Path,
+    users: list[TargetUsage],
+    unchecked: list[str],
+    ignore: set[str],
+    multi: bool,
+) -> CheckResult:
+    result = CheckResult(name=name)
+    if any(u.cite_all for u in users):
+        result.messages.append("All bib entries are cited (\\nocite{*})")
+        return result
+    cited = set().union(*(u.citations for u in users))
+    not_cited = sorted(bib_entry_keys(bib) - cited - ignore)
+    user_names = ", ".join(u.name for u in users)
+
+    if not not_cited:
+        result.messages.append("All bib entries are cited")
+    elif unchecked:
+        # Another target may cite these: say so, but never call them unused.
+        result.show_details = True
+        result.messages.append(
+            f"{len(not_cited)} not cited by {user_names or 'the checked targets'}; "
+            f"other targets not checked: {', '.join(unchecked)}",
+        )
+        result.messages.extend(f"  {key}" for key in not_cited)
+    else:
+        result.status = CheckStatus.WARNING
+        if multi:
+            result.messages.append(
+                f"{len(not_cited)} unused bib entry/entries (cited by no target: {user_names}):",
+            )
+        else:
+            result.messages.append(f"{len(not_cited)} unused bib entry/entries:")
+        result.messages.extend(f"  {key}" for key in not_cited)
+    return result
+
+
+def project_bib_checks(
+    config: PaperkitConfig,
+    outputs: dict[str, BuildResult],
+    focus: list[str],
+    failed: set[str] | None = None,
+) -> list[CheckResult]:
+    """Bibliography checks for the bib files the *focus* targets use.
+
+    *outputs* holds this run's build (or checked) output per target; other
+    mains are resolved with resolve_other_targets.
+    """
+    results: list[CheckResult] = []
+    if config.checks.unused_bib.enabled:
+        known = {
+            name: usage
+            for name, out in outputs.items()
+            if (usage := usage_from_dir(config, name, out.output_dir, "this run"))
+        }
+        usages, unchecked = resolve_other_targets(config, known, skip=failed or set())
+        results += unused_bib_checks(config, usages, unchecked, focus)
+    if config.checks.bibtex_tidy.enabled:
+        results.append(check_bibtex_tidy(config))
+    return results

paperkit/builder.py

@@ -0,0 +1,186 @@
+# Copyright (C) 2026 Vrije Universiteit Brussel. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""LaTeX build pipeline (pdflatex, lualatex, xelatex + bibtex/biber)."""
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from paperkit import reproducible
+from paperkit.config import PaperkitConfig
+
+# ANSI
+_BOLD = "\033[1m"
+_DIM = "\033[2m"
+_GREEN = "\033[32m"
+_RED = "\033[31m"
+_RESET = "\033[0m"
+
+
+@dataclass
+class BuildResult:
+    """Result of a paper build."""
+
+    pdf: Path | None = None
+    log: Path | None = None
+    blg: Path | None = None
+    aux: Path | None = None
+    output_dir: Path = field(default_factory=lambda: Path("out"))
+    success: bool = False
+
+
+def run_latex(
+    engine: str,
+    tex_file: Path,
+    output_dir: Path,
+    shell_escape: bool = True,
+    extra_args: list[str] | None = None,
+    env: dict[str, str] | None = None,
+    prelude: str = "",
+) -> int:
+    """Run a single LaTeX pass (pdflatex, lualatex, or xelatex). Returns exit code.
+
+    *prelude* is TeX code executed before the main file is read; the job name
+    is then set explicitly, since the engine would otherwise name the job
+    after that code instead of the file.
+    """
+    cmd = [
+        engine,
+        "-interaction=nonstopmode",
+        f"-output-directory={output_dir}",
+    ]
+    if shell_escape:
+        cmd.append("-shell-escape")
+    cmd += extra_args or []
+    if prelude:
+        cmd.append(f"-jobname={tex_file.stem}")
+        cmd.append(f"{prelude}\\input{{{tex_file}}}")
+    else:
+        cmd.append(str(tex_file))
+
+    result = subprocess.run(cmd, capture_output=True, env=_environment(env))
+    return result.returncode
+
+
+def _environment(extra: dict[str, str] | None) -> dict[str, str]:
+    """The caller's environment plus *extra*."""
+    env = os.environ.copy()
+    env.update(extra or {})
+    return env
+
+
+def run_bibtex(
+    aux_file: Path, bib_search_dir: Path, extra_env: dict[str, str] | None = None
+) -> int:
+    """Run bibtex with BIBINPUTS pointing to *bib_search_dir*. Returns exit code."""
+    env = _environment(extra_env)
+    env["BIBINPUTS"] = f"{bib_search_dir}:"
+
+    result = subprocess.run(
+        ["bibtex", aux_file.stem],
+        cwd=aux_file.parent,
+        env=env,
+        capture_output=True,
+    )
+    return result.returncode
+
+
+def run_biber(
+    jobname: str,
+    output_dir: Path,
+    project_root: Path,
+    extra_env: dict[str, str] | None = None,
+) -> int:
+    """Run biber from the project root with output in *output_dir*. Returns exit code."""
+    result = subprocess.run(
+        ["biber", f"--output-directory={output_dir}", jobname],
+        cwd=project_root,
+        capture_output=True,
+        env=_environment(extra_env),
+    )
+    return result.returncode
+
+
+def build_paper(config: PaperkitConfig, main: str | None = None) -> BuildResult:
+    """Orchestrate the full build for one main: N LaTeX passes with bibtex/biber after pass 1."""
+    if main is None:
+        main = config.main
+    root = config.root
+    output_dir = root / config.output_dir / main
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    tex_file = root / f"{main}.tex"
+    result = BuildResult(output_dir=output_dir)
+
+    # One timestamp for the whole pipeline, so rebuilds are byte-identical.
+    source_date = reproducible.resolve(config.source_date_epoch, root)
+    if source_date.warning:
+        print(f"  {_DIM}warning: {source_date.warning}{_RESET}")
+    env = reproducible.build_env(source_date)
+    prelude = (
+        reproducible.trailer_id_code(config.engine, source_date, main)
+        if reproducible.needs_trailer_id(config.engine)
+        else ""
+    )
+
+    use_bib = config.bibtex or config.biber
+    bib_tool = "biber" if config.biber else "bibtex"
+    total_steps = config.passes + (1 if use_bib else 0)
+    step = 0
+
+    for i in range(1, config.passes + 1):
+        # Run bibliography tool after pass 1
+        if use_bib and i == 2:
+            step += 1
+            print(f"  {_DIM}[{step}/{total_steps}]{_RESET} {bib_tool} ...")
+            if config.biber:
+                run_biber(main, output_dir, root, env)
+            else:
+                aux = output_dir / f"{main}.aux"
+                run_bibtex(aux, root, env)
+
+        step += 1
+        label = f"pass {i}"
+        if i == config.passes and config.passes >= 4:
+            label += " \u2013 pbalance"
+        print(f"  {_DIM}[{step}/{total_steps}]{_RESET} {config.engine} ({label}) ...")
+        run_latex(
+            config.engine,
+            tex_file,
+            output_dir,
+            shell_escape=config.shell_escape,
+            env=env,
+            prelude=prelude,
+        )
+
+    # Check outputs
+    pdf_path = output_dir / f"{main}.pdf"
+    log_path = output_dir / f"{main}.log"
+    blg_path = output_dir / f"{main}.blg"
+    aux_path = output_dir / f"{main}.aux"
+
+    result.log = log_path if log_path.is_file() else None
+    result.blg = blg_path if blg_path.is_file() else None
+    result.aux = aux_path if aux_path.is_file() else None
+
+    if pdf_path.is_file():
+        result.pdf = pdf_path
+        result.success = True
+        dest = root / f"{main}.pdf"
+        shutil.copy2(pdf_path, dest)
+        print(f"  {_GREEN}\u2714{_RESET} {_BOLD}{main}.pdf{_RESET}")
+
+        # Best-effort: dump LaTeX-free title and abstract next to the PDF for
+        # easy paste into submission systems (HotCRP, EasyChair, ...).
+        from paperkit.text_export import print_text_exports, write_text_exports
+
+        print_text_exports(write_text_exports(config, main, output_dir))
+    else:
+        print(f"  {_RED}\u2718 ERROR: {main}.pdf was not produced{_RESET}")
+        if log_path.is_file():
+            print(f"    See {log_path} for details")
+
+    return result