Files

1194 lines
47 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""PDF post-build verification used by `binder build pdf` and `binder check pdf`.
Two evidence sources, because some defects are visible only in one of them.
**Rendered PDF text** (via ``pdftotext``) catches what Quarto/LuaLaTeX emit
without failing the render: unresolved cross-refs (``?@sec-foo``), literal
unrendered cross-refs (``@sec-foo``), undefined LaTeX references
(``Figure ??``), leaked layout-control tokens, leaked Python tracebacks, and
matplotlib/Python ``UserWarning`` text that escaped into the rendered output.
**The LuaLaTeX build log** (``scan_build_log``) catches what the typesetter
knew but the PDF cannot show: unresolved-crossref warnings, overfull hbox/vbox
overflow, and missing glyphs — characters a font could not render, which are
dropped silently and leave no trace in the finished document. The log is found
automatically next to the generated ``.tex`` (see ``default_log_path``); the
PDF-text checks still run when no log is available.
"""
from __future__ import annotations
import re
import shutil
import subprocess
from collections import Counter
from importlib.util import find_spec
from dataclasses import dataclass, field
from pathlib import Path
from typing import Optional
class _PdfVolumeMap(dict):
"""Dictionary that dynamically resolves PDF artifact filenames for arbitrary volumes."""
def __getitem__(self, volume: str) -> str:
"""Resolve PDF artifact filename for volume key.
Returns explicit dictionary mapping if present; otherwise dynamically formats
numeric volumes (e.g. 'vol5' -> 'Machine-Learning-Systems-Vol5.pdf') or capitalized
fallbacks.
Args:
volume: Volume identifier string.
Returns:
PDF filename string.
"""
if volume in self:
return super().__getitem__(volume)
if volume.startswith("vol") and volume[3:].isdigit():
return f"Machine-Learning-Systems-Vol{volume[3:]}.pdf"
return f"{volume.capitalize()}.pdf"
def get(self, volume: str, default: Optional[str] = None) -> str:
"""Resolve PDF artifact filename for volume key with dynamic fallback.
Args:
volume: Volume identifier string.
default: Optional default (unused; falls back dynamically).
Returns:
PDF filename string.
"""
return self[volume]
PDF_BY_VOLUME = _PdfVolumeMap({
"vol1": "Machine-Learning-Systems-Vol1.pdf",
"vol2": "Machine-Learning-Systems-Vol2.pdf",
"vol3": "Machine-Learning-Systems-Vol3.pdf",
"vol4": "Machine-Learning-Systems-Vol4.pdf",
"tinytorch": "TinyTorch.pdf",
})
XREF_KINDS = r"(?:sec|fig|tbl|eq|lst|algo?)"
RESIDUAL_XREF = re.compile(rf"\?@({XREF_KINDS}-[\w.-]+)")
BARE_XREF = re.compile(rf"(?<![?\w])@({XREF_KINDS}-[\w.-]+)")
# Case-insensitive on the leading word: Quarto renders a mid-sentence
# cross-reference in lowercase, so an unresolved one reads "(figure ??)".
# Matching only the capitalized form let a dropped figure ship undetected
# while this check reported "no unresolved refs".
LATEX_UNDEF = re.compile(
r"\b(?i:figure|table|section|equation|listing)\s+\?\?+"
)
# The separator must not cross a blank line. A real "Table 8.2.1" is a single
# reference and at worst wraps once; \s+ also spanned paragraph breaks, so a
# running header ending in "... Case Study" followed by the next subsection
# number ("9.10.1") was reported as a malformed object number. (2026-08-16)
MALFORMED_OBJECT_NUMBER = re.compile(
r"\b(?:Table|Figure|Listing|Algorithm|Lighthouse|Example|Case Study|"
r"Systems Perspective)(?:[ \t]|\n(?!\s*\n))+(\d+\.\d+\.\d+(?:\.\d+)*)\b"
)
CUSTOM_CALLOUT_NUMBER = re.compile(
r"\b(?:Definition|Example|Lighthouse|Systems Perspective|napkin math|"
r"Theorem|Checkpoint|Case Study|War Story)\s+(\d+)\.\d+\b",
re.I,
)
TABLE_CAPTION = re.compile(r"\bTable\s+(\d+\.\d+):\s+([^\n]+)")
NUMBERING_ISSUE_CODES = {
"malformed-object-number",
"duplicate-table-number",
"appendix-callout-number",
}
TABLE_PROSE_MIN_GAP_PT = 6.0
PYTHON_LEAK = re.compile(
r"(?:Traceback \(most recent call last\)|"
r"NameError:|AttributeError:|ModuleNotFoundError:|Error rendering|"
r"UserWarning:)",
re.I,
)
LAYOUT_OFFSET_LEAK = re.compile(r"\[(?:[+-]?\d+(?:\.\d+)?)mm\]")
QUARTO_XREF_WARN = re.compile(
r"Unable to resolve crossref (@(?:sec|fig|tbl|eq|lst|algo)-[\w.-]+)"
)
OVERFULL_HBOX = re.compile(
r"Overfull \\hbox \((\d+(?:\.\d+)?)pt too wide\)"
)
# Vertical overflow: content (tall table/callout, or an overrunning margin note)
# exceeded the available vertical space. LuaLaTeX emits these during \output, so
# they carry a shipped-out page number "[N]" rather than a source "lines N--M".
OVERFULL_VBOX = re.compile(
r"Overfull \\vbox \((\d+(?:\.\d+)?)pt too high\)[^\n\[]*(?:\[(\d+)\])?"
)
# Missing glyph: the font has no outline for this codepoint, so LuaLaTeX drops
# the character silently — it is simply absent from the printed page, with no
# visible marker. Unlike an overfull box (which is a judgment about how much
# overflow is tolerable), every occurrence is a defect: text the author wrote
# did not reach the reader. Added 2026-09-02 after a camera-ready pass fixed
# five of these by eye (missing PDF glyphs in Vol I, font-safe Vol II text
# diagrams and diagnostic tree, PDF-safe pronunciation notation, TikZ font
# family for LuaLaTeX) that the log had already reported for free.
#
# LuaTeX emits either a literal character, a "U+XXXX" form, or a "^^xx" byte
# escape, followed by the font name:
# Missing character: There is no × (U+00D7) in font lmroman10-regular!
# Missing character: There is no ^^e2 in font [LibertinusSerif-Regular]!
MISSING_CHARACTER = re.compile(
r"Missing character: There is no (.+?) in font ([^\n!]+?)!?\s*$",
re.MULTILINE,
)
# TeX wraps log lines at ``max_print_line`` (79 by default; Quarto's LuaLaTeX
# runs use a much larger value, but that is environment-dependent and CI may
# differ). A wrap landing inside the character or font name defeats the regex
# above. Counting the unwrappable marker prefix separately gives an authoritative
# total, so a wrapped log degrades to a less detailed report rather than to a
# silent pass — the one failure mode a gate must never have.
MISSING_CHARACTER_MARKER = "Missing character: There is no "
# A log written well before the PDF it would vouch for is describing a
# different render. Allow a small window because LuaLaTeX writes the log moments
# before the PDF is finalized and copied into _build.
LOG_STALENESS_TOLERANCE_S = 300.0
@dataclass(frozen=True)
class PdfIssue:
"""One finding from a PDF text or build-log scan, aggregated by ``count``."""
code: str
message: str
count: int = 1
# "error" issues fail the build; "warning" issues print but do not (layout
# polish — e.g. vertical/margin overflow — should surface without blocking).
severity: str = "error"
@dataclass
class PdfCheckItem:
"""One row of the PDF validation checklist (pass, fail, warn, or skipped)."""
check_id: str
label: str
passed: bool
skipped: bool = False
detail: str = ""
# A warning-level check shows ⚠ when it fails but does NOT flip result.ok.
is_warning: bool = False
@dataclass
class PdfValidationResult:
"""Issues and checklist for one volume PDF, plus the margin geometry summary if scanned."""
volume: str
pdf_path: Path
issues: list[PdfIssue] = field(default_factory=list)
checks: list[PdfCheckItem] = field(default_factory=list)
margin_geometry: object | None = None
@property
def ok(self) -> bool:
"""True when no error issue exists and every non-warning check passed or was skipped."""
no_errors = not any(i.severity == "error" for i in self.issues)
checks_ok = all(c.passed or c.skipped or c.is_warning for c in self.checks)
return no_errors and checks_ok
def default_pdf_path(quarto_dir: Path, volume: str) -> Path:
"""Return the expected built PDF path, ``<quarto_dir>/_build/pdf-<volume>/<filename>``."""
return quarto_dir / "_build" / f"pdf-{volume}" / PDF_BY_VOLUME[volume]
def default_log_path(quarto_dir: Path, volume: str) -> Path | None:
"""Locate the LuaLaTeX log for ``volume``, or None when it cannot be trusted.
The post-render hook saves the current log beside the volume PDF as
``latex-build.log``. Older builds may retain a named sibling log in the
Quarto directory. Auto-discovering either means the log-based gates (crossref
warnings, overfull boxes, missing glyphs) run on a normal
``binder check pdf`` without the caller remembering ``--log``.
Because ``latex-clean: false`` also means a log *outlives* the run that
produced it, a stale one could vouch for a PDF it never described — a clean
old log silently passing a bad new build. So the log is only returned when
it is at least as new as the PDF; otherwise the caller sees ``None`` and the
log-based checks report as skipped, which is honest rather than wrong. An
explicit ``--log`` bypasses this and is always trusted.
"""
pdf_path = default_pdf_path(quarto_dir, volume)
candidates = (
pdf_path.parent / "latex-build.log",
quarto_dir / Path(PDF_BY_VOLUME[volume]).with_suffix(".log").name,
)
candidate = max((path for path in candidates if path.is_file()),
key=lambda path: path.stat().st_mtime_ns, default=None)
if candidate is None:
return None
if pdf_path.is_file():
if candidate.stat().st_mtime < pdf_path.stat().st_mtime - LOG_STALENESS_TOLERANCE_S:
return None
return candidate
def _pdftotext(pdf_path: Path) -> str:
"""Return layout-preserving text from ``pdftotext``; raise RuntimeError on nonzero exit."""
proc = subprocess.run(
["pdftotext", "-layout", str(pdf_path), "-"],
capture_output=True,
text=True,
)
if proc.returncode != 0:
raise RuntimeError(
f"pdftotext failed on {pdf_path}: {(proc.stderr or proc.stdout or '').strip()}"
)
return proc.stdout or ""
def _x_overlap(a: dict, b: dict) -> float:
"""Return the horizontal overlap in points between two ``x0``/``x1`` boxes (0 if disjoint)."""
return max(0.0, min(a["x1"], b["x1"]) - max(a["x0"], b["x0"]))
def _pdf_line_text(chars: list[dict]) -> str:
"""Reconstruct a line of PDF text with approximate word gaps."""
if not chars:
return ""
parts: list[str] = []
prev: dict | None = None
for char in chars:
if prev is not None:
gap = float(char.get("x0", 0.0) or 0.0) - float(prev.get("x1", 0.0) or 0.0)
size = max(
float(char.get("size", 0.0) or 0.0),
float(prev.get("size", 0.0) or 0.0),
6.0,
)
if gap > max(1.2, size * 0.25):
parts.append(" ")
parts.append(str(char.get("text", "")))
prev = char
return re.sub(r"\s+", " ", "".join(parts)).strip()
def _pdf_main_text_lines(page) -> list[dict]:
"""Cluster main-flow PDF chars into line boxes."""
page_h = float(getattr(page, "height", 0.0) or 0.0)
page_w = float(getattr(page, "width", 0.0) or 0.0)
if page_h <= 0 or page_w <= 0:
return []
header_y = page_h * 0.06
footer_y = page_h * 0.94
main_x = page_w * 0.88
groups: list[list[dict]] = []
for char in sorted(getattr(page, "chars", []) or [], key=lambda c: (c["top"], c["x0"])):
if not (header_y < char.get("top", 0) < footer_y):
continue
if char.get("x0", 0) > main_x:
continue
for group in groups:
if abs(group[0]["top"] - char["top"]) < 2.0:
group.append(char)
break
else:
groups.append([char])
lines: list[dict] = []
for group in groups:
group = sorted(group, key=lambda c: c["x0"])
text = _pdf_line_text(group)
if not text:
continue
lines.append(
{
"text": text,
"x0": min(c["x0"] for c in group),
"x1": max(c["x1"] for c in group),
"top": min(c["top"] for c in group),
"bottom": max(c["bottom"] for c in group),
"size": sum(float(c.get("size", 0.0) or 0.0) for c in group) / len(group),
}
)
return lines
def _pdf_horizontal_rules(page) -> list[dict]:
"""Return rendered horizontal rules in the main text area."""
page_h = float(getattr(page, "height", 0.0) or 0.0)
page_w = float(getattr(page, "width", 0.0) or 0.0)
if page_h <= 0 or page_w <= 0:
return []
header_y = page_h * 0.06
footer_y = page_h * 0.94
main_x = page_w * 0.88
rules: list[dict] = []
for line in getattr(page, "lines", []) or []:
x0 = float(line.get("x0", 0.0) or 0.0)
x1 = float(line.get("x1", 0.0) or 0.0)
top = float(line.get("top", 0.0) or 0.0)
height = abs(float(line.get("height", 0.0) or 0.0))
width = x1 - x0
if width < 120 or height > 1.0:
continue
if not (header_y < top < footer_y):
continue
if x0 > main_x:
continue
rules.append({"x0": x0, "x1": x1, "top": top, "bottom": top, "width": width})
return rules
def _pdf_table_rule_clusters(page) -> list[list[dict]]:
"""Return horizontal-rule clusters that look like booktabs tables."""
rules = _pdf_horizontal_rules(page)
groups: list[list[dict]] = []
for rule in sorted(rules, key=lambda r: (r["x0"], r["x1"], r["top"])):
for group in groups:
if abs(group[0]["x0"] - rule["x0"]) <= 6.0 and abs(group[0]["x1"] - rule["x1"]) <= 6.0:
group.append(rule)
break
else:
groups.append([rule])
return [
sorted(group, key=lambda r: r["top"])
for group in groups
if len(group) >= 3
]
def _line_is_between_table_rules(
line: dict,
bottom_rule: dict,
rules: list[dict],
) -> bool:
"""Return true when the next line is probably a table row, not prose."""
for later in rules:
if later["top"] <= bottom_rule["top"] + 1.0:
continue
overlap = _x_overlap(later, bottom_rule)
min_width = min(float(later.get("width", 0.0) or 0.0), float(bottom_rule.get("width", 0.0) or 0.0))
if overlap < max(80.0, min_width * 0.55):
continue
# Header/body rules are often separated by one table row. If the next
# text line sits in that band, the rule is internal to the table.
if line["top"] < later["top"] and later["top"] - line["top"] <= 90.0:
return True
return False
def _looks_like_post_table_prose(text: str) -> bool:
"""Filter out tick labels, legends, and table rows from spacing warnings."""
normalized = re.sub(r"\s+", " ", text).strip()
if not normalized:
return False
if re.match(r"^(?:Table|Figure|Listing|Algorithm)\s+\d", normalized):
return False
if re.match(r"^[\d.,%~$×+−–—<>=/()\\s-]+$", normalized):
return False
if re.match(r"^\d", normalized):
return False
label_prefixes = (
"Challenge:",
"Consequence:",
"Context:",
"Failure mode:",
"Given:",
"Insight:",
"Lesson:",
"Problem:",
"Resolution:",
"Systems insight:",
"Systemsinsight:",
"Systems lesson:",
"Systemslesson:",
"Takeaway:",
"Why it matters:",
)
if normalized.startswith(label_prefixes):
return True
words = re.findall(r"[A-Za-z][A-Za-z0-9_-]*", normalized)
if len(words) < 7:
return False
digit_chars = sum(ch.isdigit() for ch in normalized)
if digit_chars > len(normalized) * 0.35:
return False
return bool(re.search(r"[a-z]", normalized))
def scan_pdf_text(pdf_path: Path) -> list[PdfIssue]:
"""Return issues found in extracted PDF text."""
body = _pdftotext(pdf_path)
issues: list[PdfIssue] = []
xref_counts = Counter(m.group(1) for m in RESIDUAL_XREF.finditer(body))
for slug, count in sorted(xref_counts.items()):
issues.append(
PdfIssue(
code="unresolved-crossref",
message=f"?@{slug} appears in PDF text (Quarto cross-ref did not resolve)",
count=count,
)
)
bare_xref_counts = Counter(m.group(1) for m in BARE_XREF.finditer(body))
for slug, count in sorted(bare_xref_counts.items()):
issues.append(
PdfIssue(
code="literal-crossref",
message=f"@{slug} appears in PDF text (Quarto cross-ref rendered literally)",
count=count,
)
)
undef_counts = Counter(m.group(0) for m in LATEX_UNDEF.finditer(body))
for text, count in sorted(undef_counts.items()):
issues.append(
PdfIssue(
code="undefined-latex-ref",
message=f'"{text}" appears in PDF text (LaTeX reference undefined)',
count=count,
)
)
malformed_counts = Counter(m.group(0) for m in MALFORMED_OBJECT_NUMBER.finditer(body))
for text, count in sorted(malformed_counts.items()):
issues.append(
PdfIssue(
code="malformed-object-number",
message=(
f'"{text}" appears in PDF text. Numbered objects should use '
"chapter-local numbering such as Table 8.2, not subsection-shaped "
"numbering such as Table 8.2.1."
),
count=count,
)
)
# Volume chapters are numbered 1--16 (Volume I) or 1--17 (Volume II).
# Numeric custom-callout prefixes above those ranges mean an appendix was
# counted as another chapter instead of taking its visible letter prefix.
# This catches the combined-render regression that produced labels such as
# "napkin math 18.1" beside an Appendix B section heading.
volume_match = re.search(r"Vol(?:ume)?[-_ ]?([12])", pdf_path.name, re.I)
max_chapter = {"1": 16, "2": 17}.get(volume_match.group(1)) if volume_match else None
if max_chapter is not None:
leaked_callouts = [
match.group(0)
for match in CUSTOM_CALLOUT_NUMBER.finditer(body)
if int(match.group(1)) > max_chapter
]
if leaked_callouts:
examples = "; ".join(dict.fromkeys(leaked_callouts[:3]))
issues.append(
PdfIssue(
code="appendix-callout-number",
message=(
"Appendix custom callouts use numeric chapter prefixes instead "
f"of appendix letters. Examples: {examples}"
),
count=len(leaked_callouts),
)
)
# A renderer/counter regression can make several distinct in-callout tables
# reuse one number. Repeated occurrences of the same number are fine when the
# caption text is identical (for example a longtable continuation or repeated
# list entry). The failure is one table number attached to multiple captions.
table_captions: dict[str, Counter[str]] = {}
for match in TABLE_CAPTION.finditer(body):
number = match.group(1)
caption = re.sub(r"\s+", " ", match.group(2)).strip()
if not caption:
continue
table_captions.setdefault(number, Counter())[caption] += 1
duplicate_numbers = {
number: captions
for number, captions in table_captions.items()
if len(captions) > 1
}
for number, captions in sorted(duplicate_numbers.items()):
examples = "; ".join(list(captions.keys())[:3])
issues.append(
PdfIssue(
code="duplicate-table-number",
message=(
f"Table {number} is attached to multiple distinct captions in "
f"the PDF text: {examples}"
),
count=sum(captions.values()),
)
)
if PYTHON_LEAK.search(body):
issues.append(
PdfIssue(
code="python-traceback",
message="Python error/traceback text leaked into PDF output",
)
)
layout_offset_counts = Counter(m.group(0) for m in LAYOUT_OFFSET_LEAK.finditer(body))
for token, count in sorted(layout_offset_counts.items()):
issues.append(
PdfIssue(
code="layout-offset-leak",
message=f"{token} appears in PDF text (margin offset marker rendered literally)",
count=count,
)
)
return issues
def scan_build_log(log_path: Path | None) -> list[PdfIssue]:
"""Return cross-ref warnings and overfull hbox alerts from a render log."""
if log_path is None or not log_path.exists():
return []
try:
text = log_path.read_text(encoding="utf-8", errors="replace")
except OSError as exc:
return [PdfIssue(code="log-read-error", message=str(exc))]
issues: list[PdfIssue] = []
warn_counts = Counter(m.group(1) for m in QUARTO_XREF_WARN.finditer(text))
for ref, count in sorted(warn_counts.items()):
issues.append(
PdfIssue(
code="quarto-crossref-warning",
message=f"{ref} flagged in build log (Unable to resolve crossref)",
count=count,
)
)
# Overfull hbox: content overflowed the text block (tables, figures, code).
# Map each warning to a chapter via the companion .tex file.
SEVERE_THRESHOLD_PT = 20.0
overfull_line_re = re.compile(
r"Overfull \\hbox \((\d+(?:\.\d+)?)pt too wide\).*?lines (\d+)"
)
# Build chapter map from the .tex file (cover images mark chapter starts)
chapter_map: list[tuple[int, str]] = []
tex_path = None
if log_path:
# Try the common names for the generated .tex alongside the log
for candidate in (
log_path.with_suffix(".tex"),
log_path.parent / "Machine-Learning-Systems-Vol1.tex",
log_path.parent / "Machine-Learning-Systems-Vol2.tex",
):
if candidate.is_file():
tex_path = candidate
break
if tex_path and tex_path.is_file():
cover_re = re.compile(r"vol[12]/([^/]+)/images/png/cover_")
try:
for i, line in enumerate(tex_path.read_text(errors="replace").splitlines(), 1):
m = cover_re.search(line)
if m:
chapter_map.append((i, m.group(1)))
except OSError:
pass
def _chapter_for_tex_line(line_num: int) -> str:
"""Return the chapter whose cover image last precedes ``line_num``, or "unknown"."""
if not chapter_map:
return "unknown"
result = chapter_map[0][1]
for start, name in chapter_map:
if line_num >= start:
result = name
else:
break
return result
severe_items: list[tuple[float, str]] = []
for m in overfull_line_re.finditer(text):
pts = float(m.group(1))
if pts >= SEVERE_THRESHOLD_PT:
tex_line = int(m.group(2))
chapter = _chapter_for_tex_line(tex_line)
severe_items.append((pts, chapter))
if severe_items:
by_chapter: dict[str, list[float]] = {}
for pts, ch in severe_items:
by_chapter.setdefault(ch, []).append(pts)
details = "; ".join(
f"{ch}: {len(pts_list)} overflow(s), worst {max(pts_list):.0f}pt"
for ch, pts_list in sorted(by_chapter.items(), key=lambda x: -max(x[1]))
)
worst = max(pts for pts, _ in severe_items)
issues.append(
PdfIssue(
code="overfull-hbox",
message=(
f"{len(severe_items)} overfull \\hbox >= {SEVERE_THRESHOLD_PT:.0f}pt "
f"(worst: {worst:.0f}pt). By chapter: {details}"
),
count=len(severe_items),
)
)
# Overfull vbox: vertical overflow — a tall table/callout, or (the case this
# was added for) a margin note/figure that overran its column and pushed off
# the page. Severe rows are blocking because they correspond to rendered
# content exceeding the available page geometry.
vbox_items: list[tuple[float, str]] = []
for m in OVERFULL_VBOX.finditer(text):
pts = float(m.group(1))
if pts >= SEVERE_THRESHOLD_PT:
vbox_items.append((pts, m.group(2) or "?"))
if vbox_items:
worst = max(pts for pts, _ in vbox_items)
pages = sorted({p for _, p in vbox_items if p != "?"}, key=int)
page_note = f" pages: {', '.join(pages)}." if pages else ""
issues.append(
PdfIssue(
code="overfull-vbox",
message=(
f"{len(vbox_items)} overfull \\vbox >= {SEVERE_THRESHOLD_PT:.0f}pt "
f"(worst: {worst:.0f}pt).{page_note} "
f"Run `binder layout margins <pdf>` to localize margin overflow."
),
count=len(vbox_items),
)
)
# Missing glyphs: no threshold and no severity tiering — a dropped character
# is always a defect. The marker count is authoritative (wrap-proof); the
# regex supplies the actionable detail when lines are intact.
total_glyphs = text.count(MISSING_CHARACTER_MARKER)
if total_glyphs:
# Group by (character, font) so one bad glyph in a heavily used face
# reports as a single actionable row rather than hundreds.
glyph_counts: Counter[tuple[str, str]] = Counter()
for m in MISSING_CHARACTER.finditer(text):
char = m.group(1).strip()
# LuaTeX appends the fontspec feature string after a colon
# ("[NimbusRoman-Regular]:mode=node;script=latn;..."). Drop it so
# every instance of one face groups together rather than fragmenting.
font = m.group(2).split(":", 1)[0].strip().strip("[]")
glyph_counts[(char, font)] += 1
if glyph_counts:
worst = glyph_counts.most_common(5)
details = " " + "; ".join(
f"{char!r} missing from {font} (x{count})"
for (char, font), count in worst
)
more = len(glyph_counts) - len(worst)
if more > 0:
details += f"; +{more} more glyph/font pair(s)"
pairs = f"across {len(glyph_counts)} glyph/font pair(s)"
else:
# Every line was wrapped past recognition. Still block: the count is
# real even though the per-glyph breakdown is unavailable.
details = (
" Log lines appear wrapped, so the per-glyph breakdown is "
"unavailable; grep the log for 'Missing character'."
)
pairs = "(detail unavailable)"
unparsed = total_glyphs - sum(glyph_counts.values())
if glyph_counts and unparsed > 0:
details += f"; {unparsed} further warning(s) too wrapped to attribute"
issues.append(
PdfIssue(
code="missing-glyph",
message=(
f"{total_glyphs} dropped character(s) {pairs} — this text is "
f"absent from the printed page.{details}"
),
count=total_glyphs,
)
)
return issues
def scan_table_prose_spacing(
pdf_path: Path,
*,
min_gap_pt: float = TABLE_PROSE_MIN_GAP_PT,
) -> list[PdfIssue]:
"""Warn when rendered table bottom rules are jammed against following text."""
if not pdf_path.is_file():
return []
try:
import pdfplumber # type: ignore
except ImportError:
return []
findings: list[tuple[int, float, str]] = []
try:
with pdfplumber.open(str(pdf_path)) as pdf:
for page_idx, page in enumerate(pdf.pages, start=1):
text_lines = _pdf_main_text_lines(page)
if not text_lines:
continue
rules = _pdf_horizontal_rules(page)
for cluster in _pdf_table_rule_clusters(page):
bottom_rule = cluster[-1]
after = [
line for line in text_lines
if line["top"] > bottom_rule["top"] + 0.5
and _x_overlap(line, bottom_rule) >= 20.0
]
if not after:
continue
next_line = min(after, key=lambda line: line["top"])
# Plot gridlines can look like table rules to PDF geometry;
# their next "line" is often numeric tick labels. This
# check is for prose/semantic labels jammed after tables.
if float(next_line.get("size", 0.0) or 0.0) < 8.5:
continue
if not _looks_like_post_table_prose(next_line["text"]):
continue
if _line_is_between_table_rules(next_line, bottom_rule, rules):
continue
gap = next_line["top"] - bottom_rule["top"]
if 0 < gap < min_gap_pt:
findings.append((page_idx, gap, next_line["text"][:80]))
except Exception as exc:
return [
PdfIssue(
code="table-prose-spacing-scan-error",
message=f"Could not scan rendered table/prose spacing: {exc}",
severity="warning",
)
]
if not findings:
return []
examples = "; ".join(
f"sheet {page}: {gap:.1f}pt before \"{snippet}\""
for page, gap, snippet in findings[:3]
)
return [
PdfIssue(
code="table-prose-crowding",
message=(
f"{len(findings)} rendered table bottom rule(s) are followed "
f"by text with less than {min_gap_pt:.1f}pt of spacing. "
f"Examples: {examples}"
),
count=len(findings),
severity="warning",
)
]
def verify_pdf(
pdf_path: Path,
*,
log_path: Path | None = None,
) -> list[PdfIssue]:
"""Scan ``pdf_path`` (and optional ``log_path``) and return all issues."""
if not pdf_path.is_file():
return [PdfIssue(code="missing-pdf", message=f"PDF not found: {pdf_path}")]
if shutil.which("pdftotext") is None:
return [
PdfIssue(
code="pdftotext-missing",
message="pdftotext not installed; install poppler (e.g. brew install poppler)",
)
] + scan_build_log(log_path)
issues = scan_pdf_text(pdf_path)
issues.extend(scan_table_prose_spacing(pdf_path))
issues.extend(scan_build_log(log_path))
return issues
def scan_pdf_numbering(pdf_path: Path) -> list[PdfIssue]:
"""Return rendered-PDF object-numbering regressions only.
This narrower scan is useful after chapter-only PDF builds, where ordinary
cross-reference checks can fail because other chapters are intentionally
absent from the temporary render.
"""
if not pdf_path.is_file():
return [PdfIssue(code="missing-pdf", message=f"PDF not found: {pdf_path}")]
if shutil.which("pdftotext") is None:
return [
PdfIssue(
code="pdftotext-missing",
message="pdftotext not installed; install poppler (e.g. brew install poppler)",
)
]
return [
issue
for issue in scan_pdf_text(pdf_path)
if issue.code in NUMBERING_ISSUE_CODES
]
def _purpose_normalize(text: str) -> str:
"""Normalize source/PDF typography while retaining anchor word order."""
import unicodedata
text = unicodedata.normalize("NFKC", text)
text = re.sub(r"(?<=\w)[-\u00ad\u2010\u2011]\s*(?=\w)", "", text)
text = re.sub(r"`\{python\}[^`]*`", " ", text)
text = re.sub(r"\\index\{[^}]*\}", "", text)
text = re.sub(r"\[\^[^]]+\]|\[@[^]]+\]", "", text)
text = re.sub(r"[@](?:sec|fig|tbl|eq)-[\w.-]+", " ", text)
return " ".join(re.findall(r"[^\W_]+", text.casefold(), re.UNICODE))
def _purpose_source_anchors(text: str) -> list[tuple[str, str]]:
"""Extract the hook and paragraph tails, including opener callout text.
Supports the titled Purpose section in Volumes I–III and the untitled
italic hook in Volume IV. A pagebreak, learning objectives, or next H2
ends the opener; code, div syntax, images, and raw layout commands do not
become prose anchors (2026-09-11).
"""
purpose = re.search(r"^## Purpose[^\n]*\n", text, re.MULTILINE)
opening = text[purpose.end():] if purpose else text
next_section = re.search(r"^## +", opening, re.MULTILINE)
if next_section:
opening = opening[:next_section.start()]
hook = re.search(r"^([*_])([^\n]+)\1[ \t]*$", opening, re.MULTILINE)
if not hook:
return []
body = opening[hook.end():]
boundary = re.search(
r"\{\{<\s*pagebreak\s*>\}\}|\\(?:newpage|clearpage|cleardoublepage)\b|"
r"^:{3,}.*\.callout-learning-objectives", body, re.MULTILINE)
if boundary:
body = body[:boundary.start()]
body = re.sub(r"<!--[\s\S]*?-->", "", body)
body = re.sub(r"^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1[^\n]*$", "", body, flags=re.MULTILINE)
# Preserve blank lines so separate paragraphs and callouts get their own
# anchors. A missing intermediate paragraph must not produce a false pass.
prose = "\n".join(line for line in body.splitlines()
if not line.lstrip().startswith(("\\", ":", "![", "{{<", "#")))
anchors = [("hook", _purpose_normalize(hook.group(2)))]
for number, paragraph in enumerate(re.split(r"\n\s*\n", prose), 1):
normalized = _purpose_normalize(paragraph)
if len(normalized.split()) >= 4:
anchors.append((f"paragraph {number}", normalized))
return anchors if len(anchors) > 1 else []
def _purpose_chapter_paths(repo_root: Path, volume: str) -> list[Path]:
"""Return main chapter paths in the volume's canonical PDF order."""
import yaml
books = repo_root / "books"
config = yaml.safe_load((books / "config" / f"_quarto-pdf-{volume}.yml").read_text())
def paths(entries):
"""Yield chapter file names from string entries and nested ``file``/``chapters`` dicts."""
for entry in entries:
if isinstance(entry, str):
yield entry
elif isinstance(entry, dict):
if entry.get("file"):
yield entry["file"]
yield from paths(entry.get("chapters", []))
return list(dict.fromkeys(books / name for name in paths(config.get("book", {}).get("chapters", []))
if Path(name).parts[0] == volume and
not {"frontmatter", "backmatter", "parts", "shared"}.intersection(Path(name).parts)
and Path(name).stem not in {"index", "references"}))
def scan_purpose_overflow(
pdf_path: Path, volume: str, repo_root: Path, *, chapter: str | None = None,
) -> list[PdfIssue]:
"""Require every expected opener's hook and prose to end on its title page.
``chapter`` explicitly scopes a selective proof. Without it, all canonical
main chapters are required; missing chapters and unmatched source anchors
fail closed rather than silently passing an incomplete/stale PDF.
"""
if not pdf_path.is_file():
return [PdfIssue(code="missing-pdf", message=f"PDF not found: {pdf_path}")]
if shutil.which("pdftotext") is None:
return [PdfIssue(code="pdftotext-missing", message="pdftotext not installed; install poppler")]
try:
from ..core.discovery import ChapterDiscovery
from .layout import LayoutCommand
discovery = ChapterDiscovery(repo_root / "books")
expected = _purpose_chapter_paths(repo_root, volume)
if chapter:
prefix, _ = discovery._parse_chapter_spec(chapter)
if prefix and prefix != volume:
raise ValueError(f"Chapter {chapter!r} is outside {volume}")
chosen = discovery.find_chapter_file(chapter if prefix else f"{volume}/{chapter}", allow_fuzzy=True)
if chosen not in expected:
raise ValueError(f"Not a configured main chapter of {volume}: {chapter}")
expected = [chosen]
if not expected:
raise ValueError(f"No main chapters configured for {volume}")
out = subprocess.run(["pdftotext", str(pdf_path), "-"], capture_output=True, text=True, check=True).stdout
pages = [_purpose_normalize(page) for page in out.split("\f")]
starts, _ = LayoutCommand._load_chapter_map(pdf_path)
if not starts:
raise ValueError("PDF chapter bookmarks could not be read; opener pages cannot be verified")
except Exception as error:
return [PdfIssue(code="purpose-unverified", message=str(error))]
def find_anchor(words, first, last, *, head=False):
"""Return the first PDF sheet in ``first..last`` containing an anchor from ``words``.
Tries the leading (``head``) or trailing 12, 10, 8, 6, then 4 normalized
tokens, and returns None when no length matches on any sheet.
"""
tokens = words.split()
for count in (12, 10, 8, 6, 4):
if len(tokens) < count:
continue
anchor = " ".join(tokens[:count] if head else tokens[-count:])
for page in range(first, min(last, len(pages)) + 1):
if anchor in pages[page - 1]:
return page
return None
issues: list[PdfIssue] = []
for qmd in expected:
if not qmd.is_file():
issues.append(PdfIssue(code="purpose-source-missing", message=f"Source not found: {qmd}"))
continue
title = _purpose_normalize(discovery._chapter_title(qmd))
matching = [(page, name) for page, name in starts
if _purpose_normalize(re.sub(r"^\d+[.\s]+", "", name)) == title]
if len(matching) != 1:
issues.append(PdfIssue(code="purpose-missing-chapter",
message=f"{qmd.name}: expected one chapter bookmark for {title!r}, found {len(matching)}"))
continue
opener = matching[0][0]
end = min((page - 1 for page, _ in starts if page > opener), default=len(pages))
anchors = _purpose_source_anchors(qmd.read_text(encoding="utf-8"))
if not anchors:
issues.append(PdfIssue(code="purpose-source-unrecognized",
message=f"{qmd.name}: cannot identify opener hook and prose in source"))
continue
for label, words in anchors:
found = find_anchor(words, opener, end, head=label == "hook")
if found is None:
issues.append(PdfIssue(code="purpose-anchor-missing",
message=f"{qmd.name}: {label} anchor not found in PDF sheets {opener}–{end}; source/PDF may differ"))
elif found > opener:
issues.append(PdfIssue(code="purpose-overflow",
message=f"{qmd.name}: {label} reaches PDF sheet {found}, past opener sheet {opener}"))
return issues
def scan_margin_geometry_summary(pdf_path: Path):
"""Return the Binder-native margin geometry summary, or ``None``.
``None`` means the optional PyMuPDF dependency is unavailable. A failure
after the dependency is present is an error, never a skipped clean result.
"""
if find_spec("pymupdf") is None and find_spec("fitz") is None:
return None
try:
from cli.checks.margin_geometry import scan_pdf
except ImportError:
from binder.cli.checks.margin_geometry import scan_pdf
try:
return scan_pdf(pdf_path)
except Exception as exc:
raise RuntimeError(f"Rendered PDF geometry scan failed: {pdf_path}: {exc}") from exc
def verify_volume_pdf(
quarto_dir: Path,
volume: str,
*,
log_path: Path | None = None,
) -> PdfValidationResult:
"""Verify the default built PDF for ``volume`` (a key of ``PDF_BY_VOLUME``)."""
log_path = log_path or default_log_path(quarto_dir, volume)
pdf_path = default_pdf_path(quarto_dir, volume)
issues = verify_pdf(pdf_path, log_path=log_path)
geom_summary = scan_margin_geometry_summary(pdf_path) if pdf_path.is_file() else None
geom = (
(geom_summary.overlaps, geom_summary.overflows)
if geom_summary is not None
else None
)
edge_overflows = (
len(geom_summary.page_edge_overflows)
if geom_summary is not None
else None
)
checks = [
PdfCheckItem("artifact", "PDF artifact exists", pdf_path.is_file()),
PdfCheckItem(
"pdftotext",
"pdftotext available",
shutil.which("pdftotext") is not None,
skipped=shutil.which("pdftotext") is None,
),
PdfCheckItem(
"unresolved-crossref",
"No ?@sec/fig/tbl/eq/lst/alg literals in PDF text",
not any(i.code == "unresolved-crossref" for i in issues),
),
PdfCheckItem(
"literal-crossref",
"No bare @sec/fig/tbl/eq/lst/alg literals in PDF text",
not any(i.code == "literal-crossref" for i in issues),
),
PdfCheckItem(
"undefined-latex-ref",
"No Figure/Table/Section ?? in PDF text",
not any(i.code == "undefined-latex-ref" for i in issues),
),
PdfCheckItem(
"malformed-object-number",
"No subsection-shaped object numbers such as Table 8.2.1",
not any(i.code == "malformed-object-number" for i in issues),
),
PdfCheckItem(
"duplicate-table-number",
"No duplicate table numbers with different captions",
not any(i.code == "duplicate-table-number" for i in issues),
),
PdfCheckItem(
"appendix-callout-number",
"Appendix custom callouts use letter prefixes",
not any(i.code == "appendix-callout-number" for i in issues),
),
PdfCheckItem(
"table-prose-crowding",
"No cramped text immediately after rendered table rules",
not any(i.code == "table-prose-crowding" for i in issues),
is_warning=True,
),
PdfCheckItem(
"python-traceback",
"No Python tracebacks or UserWarnings in PDF text",
not any(i.code == "python-traceback" for i in issues),
),
PdfCheckItem(
"layout-offset-leak",
"No margin offset markers such as [-20mm] in PDF text",
not any(i.code == "layout-offset-leak" for i in issues),
),
PdfCheckItem(
"quarto-crossref-warning",
"No Quarto crossref warnings in build log",
not any(i.code == "quarto-crossref-warning" for i in issues),
skipped=log_path is None,
),
PdfCheckItem(
"overfull-hbox",
"No severe layout overflow (Overfull hbox >= 20pt)",
not any(i.code == "overfull-hbox" for i in issues),
skipped=log_path is None,
),
PdfCheckItem(
"overfull-vbox",
"No vertical/margin overflow (Overfull vbox >= 20pt)",
not any(i.code == "overfull-vbox" for i in issues),
skipped=log_path is None,
),
PdfCheckItem(
"missing-glyph",
"No dropped characters (Missing character in build log)",
not any(i.code == "missing-glyph" for i in issues),
skipped=log_path is None,
),
PdfCheckItem(
"page-edge-overflow",
(
f"No rendered content crosses the physical trim boundary "
f"({edge_overflows} violation(s))"
if edge_overflows is not None
else "Physical trim-boundary scan (PyMuPDF unavailable)"
),
edge_overflows is None or edge_overflows == 0,
skipped=edge_overflows is None,
),
PdfCheckItem(
"margin-geometry",
(
f"Margin geometry: {geom[0]} overlap(s), {geom[1]} overflow "
"(PyMuPDF; run `binder layout overlaps` to localize)"
if geom is not None
else "Margin geometry scan (PyMuPDF unavailable)"
),
geom is None or geom[0] == 0,
skipped=geom is None,
is_warning=True,
),
]
return PdfValidationResult(
volume=volume,
pdf_path=pdf_path,
issues=issues,
checks=checks,
margin_geometry=geom_summary,
)
def format_checklist(result: PdfValidationResult) -> str:
"""Human-readable checklist for console output."""
vol_label = {
"vol1": "Volume I", "vol2": "Volume II", "vol3": "Volume III",
"vol4": "Volume IV", "tinytorch": "TinyTorch",
}.get(result.volume, result.volume)
lines = [f"PDF validation ({vol_label}): {result.pdf_path.name}", ""]
for item in result.checks:
if item.skipped:
mark, status = "ⓘ", "skipped"
elif item.passed:
mark, status = "✓", "pass"
elif item.is_warning:
mark, status = "⚠", "warn"
else:
mark, status = "✗", "fail"
detail = f" — {item.detail}" if item.detail else ""
lines.append(f" [{mark}] {item.label} ({status}){detail}")
errors = [i for i in result.issues if i.severity != "warning"]
warnings = [i for i in result.issues if i.severity == "warning"]
if errors:
lines.extend(["", "Issues:"])
for idx, issue in enumerate(errors, start=1):
suffix = f" ({issue.count} occurrence(s))" if issue.count > 1 else ""
lines.append(f" {idx}. [{issue.code}] {issue.message}{suffix}")
if warnings:
lines.extend(["", "Warnings (non-blocking):"])
for idx, issue in enumerate(warnings, start=1):
suffix = f" ({issue.count} occurrence(s))" if issue.count > 1 else ""
lines.append(f" {idx}. ⚠ [{issue.code}] {issue.message}{suffix}")
return "\n".join(lines)
def format_failure_report(label: str, pdf_path: Path, issues: list[PdfIssue]) -> str:
"""Format a numbered issue list with fix guidance for a failed post-build validation."""
lines = [
f"PDF validation failed for {label}:",
f" artifact: {pdf_path}",
"",
]
for idx, issue in enumerate(issues, start=1):
suffix = f" ({issue.count} occurrence(s))" if issue.count > 1 else ""
lines.append(f" {idx}. [{issue.code}] {issue.message}{suffix}")
lines.extend(
[
"",
"Fix the source QMD (missing {#tbl-...} label, broken @ref, blank lines",
"inside pipe tables, etc.) and rebuild. Bypass with --skip-validate only",
"when you intentionally need a broken artifact.",
]
)
return "\n".join(lines)