Files
cs249r_book/binder/tests/test_pdf_layout_checks.py

1369 lines
46 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.
"""Tests for PDF overfull-box and margin-overflow detection.
Covers:
* Log-based vertical-overflow gate (Overfull \\vbox) — blocking when severe,
because it corresponds to rendered content exceeding page geometry.
* The pure margin-overflow geometry used by `binder layout margins`.
The log-based hbox gate and the cross-ref/traceback scans predate this change
and are exercised indirectly here only where they intersect severity handling.
"""
from pathlib import Path
from binder.cli.commands._pdf_checks import (
PdfCheckItem,
PdfIssue,
PdfValidationResult,
format_checklist,
scan_build_log,
scan_pdf_text,
)
from binder.cli.commands.layout import LayoutCommand
from binder.cli.commands.layout import PageReport
from binder.cli.commands.layout import CollisionFinding
from binder.cli.checks.margin_geometry import MarginGeometryFinding, MarginGeometrySummary
from binder.cli.checks.margin_geometry import scan_page as scan_margin_geometry_page
# --------------------------------------------------------------------------
# Log-based vbox gate (A1)
# --------------------------------------------------------------------------
def _write_log(tmp_path, text):
p = tmp_path / "latex-build.log"
p.write_text(text, encoding="utf-8")
return p
def test_vbox_overflow_emitted_as_error(tmp_path):
log = _write_log(
tmp_path,
"Overfull \\vbox (48.5pt too high) has occurred while \\output is active [17]\n"
"Overfull \\vbox (22.0pt too high) detected [33]\n"
"Overfull \\vbox (5.0pt too high) has occurred while \\output is active [40]\n",
)
issues = scan_build_log(log)
vbox = [i for i in issues if i.code == "overfull-vbox"]
assert len(vbox) == 1
assert vbox[0].severity == "error"
# 48.5 and 22.0 are >= 20pt; 5.0 is excluded.
assert vbox[0].count == 2
assert "17" in vbox[0].message and "33" in vbox[0].message
assert "40" not in vbox[0].message # sub-threshold page not reported
def test_hbox_stays_error_level(tmp_path):
log = _write_log(
tmp_path,
"Overfull \\hbox (35.0pt too wide) in paragraph at lines 100--102\n",
)
issues = scan_build_log(log)
hbox = [i for i in issues if i.code == "overfull-hbox"]
assert len(hbox) == 1
assert hbox[0].severity == "error"
def test_no_vbox_when_all_below_threshold(tmp_path):
log = _write_log(
tmp_path,
"Overfull \\vbox (3.0pt too high) has occurred while \\output is active [9]\n",
)
assert not [i for i in scan_build_log(tmp_path / "latex-build.log")
if i.code == "overfull-vbox"]
# --------------------------------------------------------------------------
# severity → result.ok and checklist rendering
# --------------------------------------------------------------------------
def _result(issues, checks):
return PdfValidationResult(
volume="vol2", pdf_path=tmp_pdf(), issues=issues, checks=checks
)
def tmp_pdf():
from pathlib import Path
return Path("Machine-Learning-Systems-Vol2.pdf")
def test_warning_only_keeps_result_ok():
res = _result(
issues=[PdfIssue(code="overfull-vbox", message="m", severity="warning")],
checks=[PdfCheckItem("overfull-vbox", "No vbox", passed=False, is_warning=True)],
)
assert res.ok is True
def test_error_issue_fails_result_ok():
res = _result(
issues=[PdfIssue(code="overfull-hbox", message="m", severity="error")],
checks=[PdfCheckItem("overfull-hbox", "No hbox", passed=False)],
)
assert res.ok is False
def test_checklist_renders_warning_section():
res = _result(
issues=[PdfIssue(code="overfull-vbox", message="margin overflow", severity="warning")],
checks=[PdfCheckItem("overfull-vbox", "No vbox", passed=False, is_warning=True)],
)
out = format_checklist(res)
assert "Warnings (non-blocking):" in out
assert "⚠" in out
assert "Issues:" not in out # no error-level issues
def test_pdf_text_scan_flags_bare_crossrefs(monkeypatch, tmp_path):
pdf = tmp_path / "artifact.pdf"
pdf.write_bytes(b"%PDF placeholder")
monkeypatch.setattr(
"binder.cli.commands._pdf_checks._pdftotext",
lambda _: (
"Adversarial training is covered in @sec-robust-ai. "
"Decorators like @staticmethod, emails like a@b.com, and "
"explanatory @citekey text are not Quarto cross-refs."
),
)
issues = scan_pdf_text(pdf)
literal = [i for i in issues if i.code == "literal-crossref"]
assert len(literal) == 1
assert "@sec-robust-ai" in literal[0].message
assert not [i for i in issues if i.code == "unresolved-crossref"]
def test_pdf_text_scan_flags_question_mark_crossrefs_once(monkeypatch, tmp_path):
pdf = tmp_path / "artifact.pdf"
pdf.write_bytes(b"%PDF placeholder")
monkeypatch.setattr(
"binder.cli.commands._pdf_checks._pdftotext",
lambda _: "Broken output shows ?@tbl-defense-selection-framework.",
)
issues = scan_pdf_text(pdf)
assert len([i for i in issues if i.code == "unresolved-crossref"]) == 1
assert not [i for i in issues if i.code == "literal-crossref"]
def test_pdf_text_scan_flags_layout_offset_leaks(monkeypatch, tmp_path):
pdf = tmp_path / "artifact.pdf"
pdf.write_bytes(b"%PDF placeholder")
monkeypatch.setattr(
"binder.cli.commands._pdf_checks._pdftotext",
lambda _: "Roofline position10[-25mm] depends on the workload.",
)
issues = scan_pdf_text(pdf)
leaked_offsets = [i for i in issues if i.code == "layout-offset-leak"]
assert len(leaked_offsets) == 1
assert "[-25mm]" in leaked_offsets[0].message
def test_pdf_text_scan_flags_numeric_appendix_callout_prefix(monkeypatch, tmp_path):
pdf = tmp_path / "Machine-Learning-Systems-Vol1.pdf"
pdf.write_bytes(b"%PDF placeholder")
monkeypatch.setattr(
"binder.cli.commands._pdf_checks._pdftotext",
lambda _: (
"napkin math 16.1: valid final chapter\n"
"Systems Perspective 18.1: invalid appendix prefix\n"
"napkin math B.1: valid appendix prefix\n"
),
)
issues = scan_pdf_text(pdf)
appendix_numbers = [i for i in issues if i.code == "appendix-callout-number"]
assert len(appendix_numbers) == 1
assert appendix_numbers[0].count == 1
assert "Systems Perspective 18.1" in appendix_numbers[0].message
# --------------------------------------------------------------------------
# margin-overflow geometry (A2) — pure, no PDF needed
# --------------------------------------------------------------------------
PW, PH = 600.0, 800.0 # footer band top = 752
def _char(x0, bottom, text="x", x1=None):
return {
"x0": x0,
"x1": x0 + 6 if x1 is None else x1,
"bottom": bottom,
"top": bottom - 8,
"text": text,
}
def _img(x0, bottom):
# Narrow margin figure (~1.25in = 90pt wide).
return {"x0": x0, "x1": x0 + 90, "bottom": bottom, "top": bottom - 40}
def test_margin_image_past_footer_is_flagged():
over_c, over_i = LayoutCommand._page_overflow(
PW, PH, chars=[], images=[_img(500, 775)], tol=2.0
)
assert len(over_i) == 1 and not over_c
def test_left_margin_content_past_footer_is_flagged():
over_c, over_i = LayoutCommand._page_overflow(
PW, PH, chars=[_char(40, 775)], images=[_img(30, 775)], tol=2.0
)
assert len(over_c) == 1 and len(over_i) == 1
def test_main_column_content_below_footer_is_not_margin_overflow():
# x0=200 is the main column, not the margin — handled by `collisions`, not here.
over_c, over_i = LayoutCommand._page_overflow(
PW, PH, chars=[_char(200, 775)], images=[_img(200, 775)], tol=2.0
)
assert not over_c and not over_i
def test_margin_content_above_footer_is_clean():
over_c, over_i = LayoutCommand._page_overflow(
PW, PH, chars=[_char(500, 740)], images=[_img(500, 700)], tol=2.0
)
assert not over_c and not over_i
def test_tolerance_respected():
# bottom=755 is 3pt below the 752 footer line.
over_tight, _ = LayoutCommand._page_overflow(
PW, PH, chars=[_char(500, 755)], images=[], tol=2.0
)
over_loose, _ = LayoutCommand._page_overflow(
PW, PH, chars=[_char(500, 755)], images=[], tol=10.0
)
assert len(over_tight) == 1 # 755 > 752+2
assert len(over_loose) == 0 # 755 < 752+10
def test_full_width_line_is_not_margin_overflow():
# A code-listing / wide-table line in the main/body column should not be
# flagged as margin content.
chars = [_char(200, 775), _char(400, 775)] # same baseline
over_c, _ = LayoutCommand._page_overflow(PW, PH, chars=chars, images=[], tol=2.0)
assert not over_c
def test_full_width_image_straddling_margin_is_not_flagged():
# A figure spanning the text block (x0 left of the margin, wide) is main
# content even if it dips low; only narrow margin figures count.
wide = {"x0": 80, "x1": 520, "bottom": 775, "top": 600}
_, over_i = LayoutCommand._page_overflow(PW, PH, chars=[], images=[wide], tol=2.0)
assert not over_i
def test_narrow_margin_figure_past_footer_still_flagged():
# A genuine margin figure: starts in the margin, ~1.25in (90pt) wide.
fig = {"x0": 500, "x1": 590, "bottom": 775, "top": 660}
_, over_i = LayoutCommand._page_overflow(PW, PH, chars=[], images=[fig], tol=2.0)
assert len(over_i) == 1
def test_text_flung_below_page_edge_is_excluded():
# Figure-internal label placed off-canvas (bottom well past page height) is
# not a margin caption clipping at the edge — exclude from the text signal.
over_c, _ = LayoutCommand._page_overflow(
PW, PH, chars=[_char(500, PH + 120)], images=[], tol=2.0
)
assert not over_c
def test_caption_clipping_at_page_edge_is_flagged():
# A margin caption dipping into the footer band but still on-page → flagged.
over_c, _ = LayoutCommand._page_overflow(
PW, PH, chars=[_char(500, PH - 5)], images=[], tol=2.0
)
assert len(over_c) == 1
def test_scan_margin_overflow_missing_file_returns_none():
from binder.cli.commands.layout import scan_margin_overflow
assert scan_margin_overflow("/no/such/file.pdf") is None
def test_chapter_filter_matches_title_slug_and_substring():
assert LayoutCommand._matches_chapter("Inference at Scale", ["Inference at Scale"])
assert LayoutCommand._matches_chapter("Inference at Scale", ["inference-at-scale"])
assert LayoutCommand._matches_chapter("Distributed Training Systems", ["training"])
assert not LayoutCommand._matches_chapter("Inference at Scale", ["Model Training"])
def test_source_line_match_normalizes_pdf_hyphenation(tmp_path):
qmd = tmp_path / "chapter.qmd"
qmd.write_text(
"\n".join([
"# Introduction",
"",
"[^fn-wsc]: **Warehouse-Scale Computer (WSC)**: Barroso and "
"Holzle describe the datacenter as one system.",
]),
encoding="utf-8",
)
assert LayoutCommand._find_source_line(
qmd,
"Ware-house-Scale Com-puter (WSC)",
) == 3
def test_source_line_match_strips_rendered_sidenote_number(tmp_path):
qmd = tmp_path / "chapter.qmd"
qmd.write_text(
"\n".join([
"# System Paradigms",
"",
"HIPAA (Health Insurance Portability and Accountability Act) appears "
"in prose before the rendered sidenote.",
"",
"[^fn-hipaa]: **HIPAA (Health Insurance Portability and "
"Accountability Act)**: This US law translates security measures.",
]),
encoding="utf-8",
)
assert LayoutCommand._find_source_line(
qmd,
"15 HIPAA (Health In- surance Portability and Accountability Act)",
) == 5
def test_source_line_match_prefers_footnote_title_over_nearby_mentions(tmp_path):
qmd = tmp_path / "chapter.qmd"
qmd.write_text(
"\n".join([
"# System Paradigms",
"",
"[^fn-inference]: **Inference**: Mentions 2 W edge accelerators.",
"",
"[^fn-cloud-elastic-cost]: **Pay-as-You-Go Pricing**: Sustained "
"workloads drive the total cost of ownership (TCO) analysis later.",
"",
"[^fn-tco]: [offset=65mm] **Total Cost of Ownership (TCO)**: "
"Quantifies the gap between sticker price and true system cost.",
]),
encoding="utf-8",
)
assert LayoutCommand._find_source_line(
qmd,
"16 Total Cost of Ownership (TCO) : Quantifies the gap",
) == 7
def test_source_line_match_ignores_short_bold_title_subset(tmp_path):
qmd = tmp_path / "chapter.qmd"
qmd.write_text(
"\n".join([
"# Neural Computation",
"",
"[^fn-inference]: **Inference**: This boundary changes which "
"hardware is viable, from data center GPUs to 2 W edge accelerators.",
"",
"[^fn-edge]: [offset=-65mm] **Edge Inference Accelerators**: "
"The Edge TPU operates in the mobile tier.",
]),
encoding="utf-8",
)
assert LayoutCommand._find_source_line(
qmd,
"44 Edge Inference Ac- celerators : The Edge TPU",
) == 5
def test_source_line_match_allows_short_rendered_labels(tmp_path):
qmd = tmp_path / "chapter.qmd"
qmd.write_text(
"\\node[right=12pt] {Execution\\\\ Opt.};\n",
encoding="utf-8",
)
assert LayoutCommand._find_source_line(qmd, "Execution Opt.") == 1
def test_callout_break_suggestion_moves_existing_late_tcbbreak(tmp_path):
qmd_dir = tmp_path / "books" / "vol1" / "hw"
qmd_dir.mkdir(parents=True)
qmd = qmd_dir / "hw.qmd"
qmd.write_text(
"\n".join([
":::: {#nbk-throughput .callout-notebook title=\"The throughput ceiling\"}",
"",
"**The hardware constraints**",
"",
"- Peak compute",
"",
"**The workload characteristics**",
"",
"- Model",
"- Data movement",
"",
"```{=latex}",
"\\tcbbreak",
"```",
"",
"**The prediction**",
"",
"::::",
]),
encoding="utf-8",
)
cmd = LayoutCommand(_Cfg(tmp_path), None)
suggestion = cmd._suggest_callout_break_fix(
"books/vol1/hw/hw.qmd",
7,
"The workload characteristics",
)
assert "move existing \\tcbbreak from line 13 to before line 7" in suggestion
assert "The throughput ceiling" in suggestion
def test_callout_break_suggestion_inserts_at_semantic_label(tmp_path):
qmd_dir = tmp_path / "books" / "vol1" / "hw"
qmd_dir.mkdir(parents=True)
qmd = qmd_dir / "hw.qmd"
qmd.write_text(
"\n".join([
":::: {#chk-example .callout-checkpoint title=\"Checkpoint\"}",
"",
"**First section**",
"",
"- Item A",
"",
"**Second section**",
"",
"- Item B",
"",
"::::",
]),
encoding="utf-8",
)
cmd = LayoutCommand(_Cfg(tmp_path), None)
suggestion = cmd._suggest_callout_break_fix(
"books/vol1/hw/hw.qmd",
8,
"Item B",
)
assert "insert \\tcbbreak before line 7" in suggestion
assert "callout-checkpoint" in suggestion
def test_callout_break_suggestion_moves_whole_callout_near_start(tmp_path):
qmd_dir = tmp_path / "books" / "vol1" / "hw"
qmd_dir.mkdir(parents=True)
qmd = qmd_dir / "hw.qmd"
qmd.write_text(
"\n".join([
":::: {#chk-example .callout-checkpoint title=\"Checkpoint\"}",
"",
"**First section**",
"",
"- Item A",
"",
"::::",
]),
encoding="utf-8",
)
cmd = LayoutCommand(_Cfg(tmp_path), None)
suggestion = cmd._suggest_callout_break_fix(
"books/vol1/hw/hw.qmd",
3,
"First section",
)
assert "move the whole callout or its lead-in earlier" in suggestion
def test_layout_strategy_routes_callout_source_context(tmp_path):
qmd_dir = tmp_path / "books" / "vol1" / "hw"
qmd_dir.mkdir(parents=True)
qmd = qmd_dir / "hw.qmd"
qmd.write_text(
"\n".join([
":::: {#chk-example .callout-checkpoint title=\"Checkpoint\"}",
"",
"**First section**",
"",
"- Item A",
"",
"**Second section**",
"",
"- Item B",
"",
"::::",
"",
"Some adjacent source-flow block.",
]),
encoding="utf-8",
)
cmd = LayoutCommand(_Cfg(tmp_path), None)
report = PageReport(
sheet=1,
label="1",
chapter="Hardware",
whitespace_pts=160,
whitespace_frac=0.28,
body_bottom_y=500,
usable_bottom_y=660,
cause="callout/box",
detail="Second section",
source_file="books/vol1/hw/hw.qmd",
source_line=7,
)
assert cmd._layout_strategy(report) == "callout-tcbbreak"
report.source_line = 13
assert cmd._layout_strategy(report) == "source-flow-callout-adjacent"
report.source_file = ""
report.source_line = 0
assert cmd._layout_strategy(report) == "callout-localize"
def test_margin_geometry_strategy_routes_source_context(tmp_path):
qmd_dir = tmp_path / "books" / "vol1" / "hw"
qmd_dir.mkdir(parents=True)
qmd = qmd_dir / "hw.qmd"
qmd.write_text(
"\n".join([
"# Hardware",
"",
"::: {.column-margin}",
"![](images/svg/accel.svg){width=\"100%\"}",
"*Accelerator margin caption.*",
":::",
"",
"[^fn-chip]: **Chip placement**: The note sits in the margin.",
]),
encoding="utf-8",
)
cmd = LayoutCommand(_Cfg(tmp_path), None)
finding = MarginGeometryFinding(
page=4,
issue="overflow-bottom",
side="right",
detail="text extends to 724pt, 28pt below text box",
bbox=(420, 680, 520, 724),
snippet="Chip placement",
)
base_row = {
"finding": finding,
"source_file": "books/vol1/hw/hw.qmd",
"source_line": 0,
}
row = dict(base_row, source_line=8)
assert cmd._margin_geometry_strategy(row) == "margin-offset"
row = dict(base_row, source_line=4)
assert cmd._margin_geometry_strategy(row) == "margin-vspace"
row = dict(base_row, source_file="", source_line=0)
assert cmd._margin_geometry_strategy(row) == "margin-geometry-review"
def test_layout_plan_defers_margin_until_main_flow_is_clean(tmp_path):
cmd = LayoutCommand(_Cfg(tmp_path), None)
main = PageReport(
sheet=10,
label="8",
chapter="Hardware",
whitespace_pts=160,
whitespace_frac=0.28,
body_bottom_y=500,
usable_bottom_y=660,
cause="callout/box",
detail="Second section",
source_file="books/vol1/hw/hw.qmd",
source_line=7,
layout_strategy="callout-tcbbreak",
)
margin_finding = MarginGeometryFinding(
page=11,
issue="overflow-bottom",
side="right",
detail="text extends to 724pt, 28pt below text box",
bbox=(420, 680, 520, 724),
snippet="Chip placement",
)
margin_row = {
"finding": margin_finding,
"label": "9",
"chapter": "Hardware",
"source_file": "books/vol1/hw/hw.qmd",
"source_line": 8,
"section": "Accelerators",
}
plan = cmd._layout_plan_payload(
volume="vol1",
pdf_path=tmp_path / "vol1.pdf",
whitespace_rows=[main],
margin_rows=[margin_row],
pages_scanned=20,
page_count=20,
)
assert plan["workflow"]["next_phase"] == "1-main-flow"
assert plan["counts"]["ready"] == 1
assert plan["counts"]["deferred"] == 1
main_item, margin_item = plan["items"]
assert main_item["phase"] == "1-main-flow"
assert main_item["ready"] is True
assert margin_item["phase"] == "2-margin-calibration"
assert margin_item["deferred"] is True
assert margin_item["ready"] is False
margin_only = cmd._layout_plan_payload(
volume="vol1",
pdf_path=tmp_path / "vol1.pdf",
whitespace_rows=[],
margin_rows=[margin_row],
pages_scanned=20,
page_count=20,
)
assert margin_only["workflow"]["next_phase"] == "2-margin-calibration"
assert margin_only["items"][0]["deferred"] is False
def test_source_map_is_scoped_to_pdf_volume(tmp_path):
root = tmp_path
vol1 = root / "books" / "vol1" / "introduction"
vol2 = root / "books" / "vol2" / "introduction"
vol1.mkdir(parents=True)
vol2.mkdir(parents=True)
(vol1 / "introduction.qmd").write_text("# Introduction\n", encoding="utf-8")
(vol2 / "introduction.qmd").write_text("# Introduction\n", encoding="utf-8")
pdf_dir = root / "books" / "_build" / "pdf-vol1"
pdf_dir.mkdir(parents=True)
source_map = LayoutCommand(None, None)._build_source_map(
pdf_dir / "Machine-Learning-Systems-Vol1.pdf"
)
assert source_map["Introduction"] == (
Path("books/vol1/introduction/introduction.qmd")
)
def test_margin_baseline_crowding_uses_baseline_gap_not_bbox_overlap():
crowded = [
_char(500, 108, text="first line", x1=555),
_char(500, 110, text="second line", x1=560),
]
normal = [
_char(500, 108, text="first line", x1=555),
_char(500, 116, text="second line", x1=560),
]
assert len(LayoutCommand._margin_baseline_crowding(PW, crowded)) == 1
assert not LayoutCommand._margin_baseline_crowding(PW, normal)
def test_margin_image_text_overlap_ignores_tiny_icons_and_flags_big_images():
chars = [_char(500, 108, text="substantial label", x1=560)]
tiny_icon = {"x0": 500, "x1": 510, "top": 96, "bottom": 112}
big_image = {"x0": 490, "x1": 590, "top": 96, "bottom": 130}
assert not LayoutCommand._margin_image_text_overlaps(PW, chars, [tiny_icon])
assert len(LayoutCommand._margin_image_text_overlaps(PW, chars, [big_image])) == 1
def test_left_margin_vector_text_overlap_is_flagged():
chars = [_char(40, 108, text="substantial label", x1=110)]
vector_box = {"x0": 30, "x1": 120, "top": 96, "bottom": 130}
assert len(LayoutCommand._margin_image_text_overlaps(PW, chars, [vector_box])) == 1
# --------------------------------------------------------------------------
# Binder-native margin geometry (PyMuPDF-shaped fake page, no PDF needed)
# --------------------------------------------------------------------------
class _Rect:
def __init__(self, x0, y0, x1, y1):
self.x0 = x0
self.y0 = y0
self.x1 = x1
self.y1 = y1
self.width = x1 - x0
self.height = y1 - y0
self.is_empty = self.width <= 0 or self.height <= 0
class _FakePage:
def __init__(self, blocks=None, drawings=None):
self._blocks = blocks or []
self._drawings = [{"rect": _Rect(*d)} for d in (drawings or [])]
def get_text(self, kind):
assert kind == "dict"
return {"blocks": self._blocks}
def get_drawings(self):
return self._drawings
def _text_block(x0, y0, x1, y1, text="margin text"):
return {
"type": 0,
"bbox": (x0, y0, x1, y1),
"lines": [{"spans": [{"text": text}]}],
}
def test_native_margin_geometry_detects_real_graphic_text_overlap():
page = _FakePage(
blocks=[_text_block(470, 100, 555, 150, "overlapping margin note")],
drawings=[(480, 130, 540, 180)],
)
findings = scan_margin_geometry_page(page, 12)
assert [f.issue for f in findings] == ["overlap"]
assert findings[0].page == 12
assert "overlapping margin note" in findings[0].snippet
def test_native_margin_geometry_merges_adjacent_caption_with_figure():
page = _FakePage(
blocks=[_text_block(470, 144, 555, 164, "caption directly below")],
drawings=[(480, 100, 540, 140)],
)
assert scan_margin_geometry_page(page, 12) == []
def test_native_margin_geometry_ignores_body_figure_internals_in_margin_band():
page = _FakePage(
blocks=[_text_block(70, 700, 105, 716, "axis label")],
drawings=[
(63, 680, 450, 730), # full body/table graphic inside the trim edge
(74, 704, 82, 714), # internal icon in the physical margin band
],
)
assert scan_margin_geometry_page(page, 12) == []
def test_native_margin_geometry_flags_true_margin_bottom_overflow():
page = _FakePage(
blocks=[_text_block(470, 690, 555, 720, "caption below text box")],
)
findings = scan_margin_geometry_page(page, 12)
assert [f.issue for f in findings] == ["overflow-bottom"]
assert findings[0].side == "right"
def test_native_margin_geometry_flags_body_text_crossing_main_frame():
page = _FakePage(
blocks=[_text_block(82, 650, 410, 704, "Bitter Lesson prose")],
)
findings = scan_margin_geometry_page(page, 44)
assert [f.issue for f in findings] == ["body-overflow-bottom"]
assert findings[0].side == "body"
assert "Bitter Lesson prose" in findings[0].snippet
def test_native_margin_geometry_allows_normal_final_line_glyph_depth():
page = _FakePage(
blocks=[_text_block(82, 650, 410, 696, "ordinary final baseline")],
)
assert scan_margin_geometry_page(page, 43) == []
def test_native_margin_geometry_ignores_narrow_margin_note_below_main_frame():
page = _FakePage(
blocks=[_text_block(470, 650, 555, 710, "intentional margin note")],
)
findings = scan_margin_geometry_page(page, 41)
assert [f.issue for f in findings] == ["overflow-bottom"]
def test_release_gate_blocks_body_and_trim_but_not_margin_advisories():
assert LayoutCommand._release_blocking_issue("body-overflow-bottom")
assert LayoutCommand._release_blocking_issue("trim-overflow-bottom")
assert not LayoutCommand._release_blocking_issue("overlap")
assert not LayoutCommand._release_blocking_issue("overflow-bottom")
assert not LayoutCommand._release_blocking_issue("overflow-top")
def test_margin_geometry_colours_preserve_existing_and_release_policies():
assert LayoutCommand._margin_geometry_colour("overlap") == "red"
assert LayoutCommand._margin_geometry_colour(
"overlap", release_policy=True
) == "yellow"
assert LayoutCommand._margin_geometry_colour(
"body-overflow-bottom", release_policy=True
) == "red"
def test_release_command_executes_reporting_path(monkeypatch, capsys, tmp_path):
finding = MarginGeometryFinding(
44,
"body-overflow-bottom",
"body",
"body text extends 11pt below main text frame",
(144, 572, 532, 704),
"Bitter Lesson prose",
)
row = {
"finding": finding,
"label": "10",
"chapter": "Introduction",
"source_file": "",
"source_line": 0,
"section": "The Bitter Lesson",
}
command = LayoutCommand(None, None)
monkeypatch.setattr(
command,
"_collect_margin_geometry_rows",
lambda *_args, **_kwargs: ([row], 1, 1),
)
assert not command._release_layout(tmp_path / "release.pdf")
output = capsys.readouterr().out
assert "body-frame" in output
assert "BLOCKING release geometry" in output
def test_release_command_passes_with_advisory_margin_overlap(
monkeypatch, capsys, tmp_path
):
finding = MarginGeometryFinding(
18,
"overlap",
"right",
"mixed and text boxes intersect by 4pt",
(470, 130, 540, 150),
"diagram label",
)
row = {
"finding": finding,
"label": "18",
"chapter": "Introduction",
"source_file": "",
"source_line": 0,
"section": "",
}
command = LayoutCommand(None, None)
monkeypatch.setattr(
command,
"_collect_margin_geometry_rows",
lambda *_args, **_kwargs: ([row], 1, 1),
)
assert command._release_layout(tmp_path / "release.pdf")
output = capsys.readouterr().out
assert "BLOCKING release geometry 0" in output
assert "ADVISORY margin geometry 1" in output
def test_native_margin_geometry_flags_body_drawing_crossing_trim():
page = _FakePage(drawings=[(80, 676, 468, 907)])
findings = scan_margin_geometry_page(page, 215)
assert [f.issue for f in findings] == ["trim-overflow-bottom"]
assert findings[0].page == 215
def test_native_margin_geometry_ignores_clipped_vector_sentinel_bounds():
page = _FakePage(drawings=[(105, 299, 333, 60768)])
assert scan_margin_geometry_page(page, 95) == []
def test_native_margin_geometry_ignores_cover_page_label_in_printer_strip():
page = _FakePage(
blocks=[_text_block(576, 742, 586, 752, "i")],
)
assert scan_margin_geometry_page(page, 1) == []
def test_native_margin_geometry_keeps_cover_exemption_out_of_body_pages():
page = _FakePage(
blocks=[_text_block(576, 742, 586, 752, "i")],
)
findings = scan_margin_geometry_page(page, 5)
assert "trim-overflow-bottom" in [f.issue for f in findings]
def test_native_margin_geometry_flags_body_text_crossing_trim():
page = _FakePage(
blocks=[_text_block(144, 713, 532, 761, "section prose beyond trim")],
)
findings = scan_margin_geometry_page(page, 248)
assert [f.issue for f in findings] == ["trim-overflow-bottom"]
assert "section prose beyond trim" in findings[0].snippet
def test_native_margin_geometry_flags_body_text_wholly_below_trim():
page = _FakePage(
blocks=[_text_block(90, 748, 468, 761, "paragraph hidden below trim")],
)
findings = scan_margin_geometry_page(page, 248)
assert [f.issue for f in findings] == ["trim-overflow-bottom"]
assert "paragraph hidden below trim" in findings[0].snippet
def test_margin_geometry_summary_separates_trim_crossing_from_text_box_overflow(tmp_path):
summary = MarginGeometrySummary(
pdf_path=tmp_path / "book.pdf",
page_count=2,
pages_scanned=2,
findings=[
MarginGeometryFinding(
1,
"overflow-bottom",
"right",
"caption below text box but inside trim",
(470, 660, 555, 700),
),
MarginGeometryFinding(
2,
"trim-overflow-bottom",
"bottom",
"drawing crosses trim",
(80, 664, 468, 907),
),
],
)
assert summary.overflows == 2
assert [finding.page for finding in summary.page_edge_overflows] == [2]
def test_collision_csv_is_machine_readable(capsys):
finding = CollisionFinding(
sheet=74,
label="66",
chapter="Inference at Scale",
band="footer",
y=688.4,
snippet="Bursts starve shared KV cache.",
)
LayoutCommand(None, None)._render_collisions_csv([finding])
out = capsys.readouterr().out
assert "chapter,sheet,label,band,y,snippet" in out
assert "Inference at Scale,74,66,footer,688.4" in out
# --------------------------------------------------------------------------
# table-only layout audit extraction — pure, no Quarto/PDF render needed
# --------------------------------------------------------------------------
class _Cfg:
def __init__(self, root):
self.root_dir = root
self.book_dir = root / "books"
def test_pipe_table_extraction_preserves_label_colwidths_and_source(tmp_path):
qmd_dir = (
tmp_path
/ "books"
/ "vol2"
/ "inference"
)
qmd_dir.mkdir(parents=True)
qmd = qmd_dir / "inference.qmd"
qmd.write_text(
"\n".join([
"# Inference",
"",
"| **Phase** | **Duration** |",
"|:----------|-------------:|",
"| Startup | 5s |",
"| Warmup | 15s |",
"",
": **Cold-Start Timeline**: Per-phase duration. "
"{#tbl-cold-start tbl-colwidths=\"[60,40]\"}",
"",
]),
encoding="utf-8",
)
entries = LayoutCommand(_Cfg(tmp_path), None)._extract_pipe_tables(qmd)
assert len(entries) == 1
entry = entries[0]
assert entry.label == "tbl-cold-start"
assert entry.source_file == "vol2/inference/inference.qmd"
assert entry.source_line == 8
assert entry.columns == 2
assert entry.rows == 2
assert entry.has_colwidths is True
assert entry.colwidths == "[60,40]"
assert "Cold-Start Timeline" in entry.caption
def test_pipe_table_extraction_ignores_uncaptioned_tables(tmp_path):
qmd_dir = tmp_path / "books" / "vol2" / "ops"
qmd_dir.mkdir(parents=True)
qmd = qmd_dir / "ops.qmd"
qmd.write_text(
"| A | B |\n|---|---|\n| 1 | 2 |\n\nNo caption here.\n",
encoding="utf-8",
)
assert LayoutCommand(_Cfg(tmp_path), None)._extract_pipe_tables(qmd) == []
def test_static_table_warnings_flag_dense_tables_not_simple_defaults():
dense = LayoutCommand._static_table_warnings(
columns=5,
rows=6,
max_cell_chars=48,
has_colwidths=False,
)
simple = LayoutCommand._static_table_warnings(
columns=2,
rows=4,
max_cell_chars=20,
has_colwidths=True,
)
assert "wide-dense-table-without-colwidths" in dense
assert "many-columns-without-colwidths" in dense
assert "simple-table-has-colwidths-review-necessity" in simple
# --------------------------------------------------------------------------
# Missing-glyph gate (added 2026-09-02)
# --------------------------------------------------------------------------
def test_missing_glyph_detected_and_grouped(tmp_path):
log = _write_log(
tmp_path,
"Missing character: There is no × (U+00D7) in font lmroman10-regular!\n"
"Missing character: There is no × (U+00D7) in font lmroman10-regular!\n"
"Missing character: There is no ≤ (U+2264) in font [LibertinusSerif-Regular]!\n",
)
glyphs = [i for i in scan_build_log(log) if i.code == "missing-glyph"]
assert len(glyphs) == 1
# 3 dropped characters across 2 distinct glyph/font pairs.
assert glyphs[0].count == 3
assert "2 glyph/font pair(s)" in glyphs[0].message
# Font name is reported with the surrounding brackets stripped.
assert "LibertinusSerif-Regular" in glyphs[0].message
assert "[LibertinusSerif-Regular]" not in glyphs[0].message
def test_missing_glyph_is_blocking():
"""Unlike overfull boxes there is no tolerable amount: severity is error."""
issue = PdfIssue(code="missing-glyph", message="x", count=1)
assert issue.severity == "error"
result = PdfValidationResult(volume="vol1", pdf_path=Path("x.pdf"), issues=[issue])
assert not result.ok
def test_missing_glyph_handles_byte_escape_form(tmp_path):
"""LuaTeX also emits ^^xx byte escapes rather than a printable character."""
log = _write_log(
tmp_path,
"Missing character: There is no ^^e2 in font [TeXGyreHeros-Regular]!\n",
)
glyphs = [i for i in scan_build_log(log) if i.code == "missing-glyph"]
assert len(glyphs) == 1
assert glyphs[0].count == 1
assert "^^e2" in glyphs[0].message
def test_no_missing_glyph_issue_on_clean_log(tmp_path):
log = _write_log(
tmp_path,
"Overfull \\hbox (35.0pt too wide) in paragraph at lines 100--102\n"
"This line mentions Missing character handling but is not a warning.\n",
)
assert not [i for i in scan_build_log(log) if i.code == "missing-glyph"]
def test_missing_glyph_skipped_when_no_log():
assert scan_build_log(None) == []
def test_default_log_path_discovers_sibling_log(tmp_path):
"""With latex-clean: false the .log sits beside the .tex in the quarto dir."""
from binder.cli.commands._pdf_checks import default_log_path
assert default_log_path(tmp_path, "vol1") is None # nothing built yet
(tmp_path / "Machine-Learning-Systems-Vol1.log").write_text("ok", encoding="utf-8")
found = default_log_path(tmp_path, "vol1")
assert found is not None and found.name == "Machine-Learning-Systems-Vol1.log"
# vol2 is independent and still absent.
assert default_log_path(tmp_path, "vol2") is None
def test_default_log_path_discovers_preserved_volume_log_and_rejects_stale(tmp_path):
import os
from binder.cli.commands._pdf_checks import default_log_path, default_pdf_path
pdf = default_pdf_path(tmp_path, "vol2")
pdf.parent.mkdir(parents=True)
pdf.write_bytes(b"%PDF-1.7\n")
log = pdf.parent / "latex-build.log"
log.write_text("Current post-render log")
os.utime(pdf, (1_700_000_000, 1_700_000_000))
os.utime(log, (1_700_000_002, 1_700_000_002))
assert default_log_path(tmp_path, "vol2") == log
assert default_log_path(tmp_path, "vol1") is None
os.utime(log, (1_699_996_400, 1_699_996_400))
assert default_log_path(tmp_path, "vol2") is None
def test_volume_verification_uses_preserved_log_without_explicit_argument(tmp_path, monkeypatch):
import fitz
from binder.cli.commands._pdf_checks import default_pdf_path, verify_volume_pdf
pdf = default_pdf_path(tmp_path, "vol2")
pdf.parent.mkdir(parents=True)
with fitz.open() as document:
document.new_page().insert_text((72, 72), "PDF verification fixture")
document.save(pdf)
(pdf.parent / "latex-build.log").write_text(
"Missing character: There is no 𝛷 (U+1D6F7) in font [TeXGyrePagellaX-Bold.otf]!\n"
)
result = verify_volume_pdf(tmp_path, "vol2")
assert not result.ok
glyph_check = next(check for check in result.checks if check.check_id == "missing-glyph")
assert not glyph_check.skipped and not glyph_check.passed
assert any(issue.code == "missing-glyph" for issue in result.issues)
# Missing text-extraction tooling must fail independently without hiding
# the diagnostic already present in the authoritative LaTeX log.
monkeypatch.setattr("binder.cli.commands._pdf_checks.shutil.which", lambda name: None)
result = verify_volume_pdf(tmp_path, "vol2")
assert not result.ok
assert any(issue.code == "pdftotext-missing" for issue in result.issues)
assert any(issue.code == "missing-glyph" for issue in result.issues)
def test_inline_code_wrap_preserves_escaping_and_html_literal_text():
import html
import re
import subprocess
filter_path = Path(__file__).resolve().parents[2] / "books/shared/filters/inline-code-wrap.lua"
code = r'package_search(query="pool timeout") a.b x_{a}\b%#&'
source = f"`{code}`\n"
def render(format_name, filtered=True):
command = ["quarto", "pandoc", "--from", "markdown", "--to", format_name]
if filtered:
command.extend(["--lua-filter", str(filter_path)])
return subprocess.run(command, input=source, text=True, capture_output=True, check=True).stdout
latex = render("latex")
assert "a.\\allowbreak{}b" in latex
assert '"pool timeout"' in latex
assert latex.replace("\\allowbreak{}", "") == render("latex", False).replace("\\ ", " ")
output_html = render("html")
literal = re.search(r"<code>(.*?)</code>", output_html).group(1)
assert html.unescape(literal) == code
assert output_html == render("html", False)
source = "`task.grant.permits`{#api.anchor .custom}\n"
assert render("latex") == render("latex", False)
def test_build_postflight_does_not_substitute_console_output_for_latex_log(tmp_path):
from types import SimpleNamespace
import fitz
from binder.cli.commands._pdf_checks import default_pdf_path
from binder.cli.commands.build import BuildCommand
pdf = default_pdf_path(tmp_path, "vol2")
pdf.parent.mkdir(parents=True)
with fitz.open() as document:
document.new_page().insert_text((72, 72), "Postflight fixture")
document.save(pdf)
(pdf.parent / "latex-build.log").write_text(
"Missing character: There is no 𝛷 (U+1D6F7) in font [TeXGyrePagellaX-Bold.otf]!\n"
)
console_log = tmp_path / "quarto-console.log"
console_log.write_text("Output created: Machine-Learning-Systems-Vol2.pdf\n")
command = object.__new__(BuildCommand)
command.config_manager = SimpleNamespace(book_dir=tmp_path)
assert not command._postflight_pdf_validation("vol2", log_path=console_log)
# The independent Quarto warning stream must still be checked when LaTeX
# itself reports no defect.
(pdf.parent / "latex-build.log").write_text("LaTeX finished without warnings\n")
console_log.write_text("WARNING: Unable to resolve crossref @fig-missing\n")
assert not command._postflight_pdf_validation("vol2", log_path=console_log)
def test_unnumbered_chapter_preserves_objects_and_numbered_chapter_resets_them(tmp_path):
import subprocess
helper = Path(__file__).resolve().parents[2] / "books/shared/tex/unnumbered-chapter-counters.tex"
counts = {"table": 18, "figure": 7, "equation": 4, "algorithm": 3, "codelisting": 2}
source = (
r"\documentclass{scrbook}" "\n"
r"\usepackage{longtable}" "\n"
r"\newcounter{algorithm}[chapter]\newcounter{codelisting}[chapter]" "\n"
+ r"\input{" + str(helper) + "}\n"
+ r"\begin{document}\chapter{First}" "\n"
)
for counter, value in counts.items():
source += rf"\setcounter{{{counter}}}{{{value}}}" + "\n"
source += (
r"\mlsysSaveChapterObjectCounters\chapter*{Principles}\mlsysRestoreChapterObjectCounters" "\n"
)
for counter in counts:
source += rf"\typeout{{PRESERVED-{counter}: \arabic{{{counter}}}}}" + "\n"
source += (
r"\begin{longtable}{l}\caption{Continued}\label{tbl-continued}\\Example\\\end{longtable}" "\n"
r"\chapter{Second}" "\n"
)
for counter in counts:
source += rf"\typeout{{RESET-{counter}: \arabic{{{counter}}}}}" + "\n"
source += (
r"\begin{longtable}{l}\caption{New chapter}\label{tbl-new}\\Example\\\end{longtable}" "\n"
r"\end{document}" "\n"
)
(tmp_path / "counter.tex").write_text(source)
subprocess.run(
["lualatex", "-draftmode", "-interaction=nonstopmode", "-halt-on-error", "counter.tex"],
cwd=tmp_path, capture_output=True, text=True, check=True,
)
log = (tmp_path / "counter.log").read_text()
for counter, value in counts.items():
assert f"PRESERVED-{counter}: {value}" in log
assert f"RESET-{counter}: 0" in log
aux = (tmp_path / "counter.aux").read_text()
assert r"\newlabel{tbl-continued}{{1." + str(counts["table"] + 1) + "}" in aux
assert r"\newlabel{tbl-new}{{2.1}" in aux
def test_missing_glyph_survives_wrapped_log_lines(tmp_path):
"""A wrap that hides 'in font' must not turn a defect into a silent pass."""
log = _write_log(
tmp_path,
# Wrapped mid-codepoint: the regex cannot attribute either warning, but
# the marker count still holds, so the gate must still fire.
"Missing character: There is no ≤ (U+22\n"
"64) in font [LibertinusSerif-Regular]!\n"
"Missing character: There is no × (U+00\n"
"D7) in font lmroman10-regular!\n",
)
glyphs = [i for i in scan_build_log(log) if i.code == "missing-glyph"]
assert len(glyphs) == 1
assert glyphs[0].count == 2
assert "detail unavailable" in glyphs[0].message
assert "wrapped" in glyphs[0].message
def test_missing_glyph_reports_partial_attribution(tmp_path):
"""One intact warning plus one wrapped: count is 2, detail covers the intact one."""
log = _write_log(
tmp_path,
"Missing character: There is no × (U+00D7) in font lmroman10-regular!\n"
"Missing character: There is no ≤ (U+22\n"
"64) in font [LibertinusSerif-Regular]!\n",
)
glyphs = [i for i in scan_build_log(log) if i.code == "missing-glyph"]
assert glyphs[0].count == 2
assert "lmroman10-regular" in glyphs[0].message
assert "1 further warning(s) too wrapped to attribute" in glyphs[0].message
def test_stale_log_is_not_auto_discovered(tmp_path):
"""A log older than the PDF describes a different render; do not trust it."""
import os
from binder.cli.commands._pdf_checks import default_log_path, default_pdf_path
log = tmp_path / "Machine-Learning-Systems-Vol1.log"
log.write_text("ok", encoding="utf-8")
pdf = default_pdf_path(tmp_path, "vol1")
pdf.parent.mkdir(parents=True, exist_ok=True)
pdf.write_bytes(b"%PDF-1.7\n")
# Log an hour older than the PDF -> refused.
old = pdf.stat().st_mtime - 3600
os.utime(log, (old, old))
assert default_log_path(tmp_path, "vol1") is None
# Log newer than the PDF (normal, and also the failed-build case) -> used.
fresh = pdf.stat().st_mtime + 5
os.utime(log, (fresh, fresh))
assert default_log_path(tmp_path, "vol1") == log
def test_log_discovered_when_pdf_absent(tmp_path):
"""No PDF to compare against: fall back to using the log rather than skipping."""
from binder.cli.commands._pdf_checks import default_log_path
log = tmp_path / "Machine-Learning-Systems-Vol1.log"
log.write_text("ok", encoding="utf-8")
assert default_log_path(tmp_path, "vol1") == log
def test_source_map_ignores_volume_prefixed_generated_files(tmp_path):
books = tmp_path / 'books'
chapter = books / 'vol4/01_boundary/01_boundary.qmd'
chapter.parent.mkdir(parents=True)
chapter.write_text('# The Causal Boundary\n')
for name in ('vol4-preface-check.tex', 'vol3.pdf', 'vol2'):
(books / name).write_text('Generated artifact must not be traversed as a directory.\n')
unrelated = books / 'vol4-notes/01_boundary'
unrelated.mkdir(parents=True)
(unrelated / '01_boundary.qmd').write_text('# Unrelated notes\n')
# An unscoped PDF exercises fallback discovery; all artifacts are retained.
result = LayoutCommand(None, None)._build_source_map(books / '_build/proof.pdf')
assert result == {'The Causal Boundary': Path('books/vol4/01_boundary/01_boundary.qmd')}
assert (books / 'vol4-preface-check.tex').is_file()
def test_source_map_recognizes_vol3_and_vol4_and_nearest_volume(tmp_path):
books = tmp_path / 'books'
for volume in ('vol3', 'vol4'):
chapter = books / volume / 'introduction/introduction.qmd'
chapter.parent.mkdir(parents=True)
chapter.write_text('# Introduction\n')
for volume in ('vol3', 'vol4'):
result = LayoutCommand(None, None)._build_source_map(
books / f'_build/pdf-{volume}/Machine-Learning-Systems-{volume}.pdf')
assert result['Introduction'] == Path(f'books/{volume}/introduction/introduction.qmd')
assert LayoutCommand._volume_from_pdf_path(
Path('/tmp/MLSysBook-vol1/books/_build/pdf-vol4/01_boundary.pdf')) == 'vol4'