Files
cs249r_book/binder/tests/test_selective_volume_build.py
Vijay Janapa Reddi 27d4f8114b binder: fix repo-root, build, doctor and info bugs; clearer errors; dedup
Bug fixes
- Build lock is keyed on books/ so builds started from different
  directories block each other (fixes two tests broken by 89b828efa3).
- ConfigManager resolves the repo root when binder runs from books/ or
  binder/, so bib, newsletter, doctor and render paths are right.
- `build <word> --all` treats intro/scaling/agentic/physical as chapter
  names (it built every volume), and Ctrl-C stops a --all loop.
- doctor checked chapter names that no longer exist and failed on the
  generated _quarto.yml; info defaulted to a deleted books/contents.
- `headings apply --path <typo>` no longer rewrites the whole book;
  `bib clean` stops on unreadable chapters instead of dropping entries.
- Discovery falls back to a line scan on invalid YAML instead of crashing.
- Volume III/IV were labeled Volume II in layout and release output.

Output
- Unexpected errors print the command, exception type, and raising
  file:line (new cli/core/errors.py), with the traceback on stderr.
- Chapter-not-found suggests the closest names and the list command.
- Silent except blocks in bib lookups, info, headings, layout,
  maintenance, preview and debug now say what went wrong.

Cleanup
- Shared qmd_files_under/display_path, file-rewrite loop, doctor result
  helper, preview server, clean helpers, volume display names.
- Removed legacy import fallbacks, dead config attributes, legacy backup
  restore logic, and unused imports.
2026-10-19 19:28:49 +02:00

380 lines
17 KiB
Python

"""Regression coverage for volume-scoped chapter iteration (2026-09-11)."""
import signal
from pathlib import Path
from unittest.mock import Mock
import pytest
import yaml
from binder.cli.commands.build import BuildCommand
from binder.cli.core.config import ConfigManager, active_config_source
from binder.cli.core.discovery import AmbiguousChapterError, ChapterDiscovery
from binder.cli.core.volume_index import volume_index_source
from binder.cli.main import MLSysBookCLI
ROOT = Path(__file__).resolve().parents[2]
VOLUMES = ('vol1', 'vol2', 'vol3', 'vol4')
def fixture_book(tmp_path, volume='vol4', format_type='pdf'):
books = tmp_path / 'books'
(books / 'config').mkdir(parents=True)
source = volume_index_source(books, volume, format_type)
source.parent.mkdir(parents=True, exist_ok=True)
source.write_bytes(b'# Preface\r\nCanonical introduction.\r\n')
chapter = books / volume / '01_boundary/01_boundary.qmd'
chapter.parent.mkdir(parents=True)
chapter.write_text('# The Causal Boundary {#sec-boundary}\n\nPurpose.\n')
unused = books / volume / '02_body/02_body.qmd'
unused.parent.mkdir(parents=True)
unused.write_text('# The Physical Body\n')
config = books / 'config' / f'_quarto-{format_type}-{volume}.yml'
config.write_text(yaml.safe_dump({
'project': {'output-dir': f'_build/{format_type}-{volume}', 'render': ['index.qmd',
str(chapter.relative_to(books)), str(unused.relative_to(books))],
'post-render': ['shared/hooks.py']},
'book': {'output-file': 'Whole-Volume', 'chapters': ['index.qmd', {'part': 'Anatomy',
'chapters': [str(chapter.relative_to(books)), str(unused.relative_to(books))]}],
'appendices': [f'{volume}/backmatter/references.qmd']},
'format': {'titlepage-pdf': {'coverpage': True}},
'metadata-files': ['config/shared.yml'],
}, sort_keys=False))
manager = ConfigManager(tmp_path)
command = BuildCommand(manager, ChapterDiscovery(books))
return books, source, chapter, config, command
@pytest.mark.parametrize('volume', VOLUMES)
@pytest.mark.parametrize('format_type', ('html', 'pdf', 'epub'))
def test_selected_render_uses_only_index_and_target_and_restores(tmp_path, volume, format_type):
books, source, chapter, canonical, command = fixture_book(tmp_path, volume, format_type)
original_config = canonical.read_bytes()
original_source = source.read_bytes()
active = books / '_quarto.yml'
index = books / 'index.qmd'
active.write_bytes(b'# Prior config\r\n')
index.write_bytes(b'# Prior index\r\n')
full_output = books / f'_build/{format_type}-{volume}/Whole-Volume.{format_type}'
full_output.parent.mkdir(parents=True)
full_output.write_bytes(b'KEEP FULL ARTIFACT')
handlers = {sig: signal.getsignal(sig) for sig in (signal.SIGINT, signal.SIGTERM)}
def fake_render(cmd, *, cwd, description):
current = yaml.safe_load(active.read_text())
assert cwd == books
assert cmd == ['quarto', 'render', '--to=' + ('titlepage-pdf' if format_type == 'pdf' else format_type)]
assert canonical.read_bytes() == original_config
assert index.read_bytes() == original_source
assert active_config_source(active) == canonical.relative_to(books).as_posix()
expected = ['index.qmd', chapter.relative_to(books).as_posix()]
assert current['project']['post-render'] == ['shared/hooks.py']
if format_type == 'html':
assert current['project']['render'] == expected
else:
assert current['book']['chapters'] == expected
assert 'appendices' not in current['book']
assert 'render' not in current['project']
assert current['book']['output-file'] == '01_boundary'
output = books / current['project']['output-dir']
assert output == full_output.parent / 'chapters/01_boundary'
(output / ('index.html' if format_type == 'html' else f'01_boundary.{format_type}')).write_bytes(b'BUILT')
return True
command._run_command = Mock(side_effect=fake_render)
assert command.build_chapters_with_volume(['causal boundary'], format_type, volume,
skip_hygiene=True, skip_validate=True)
assert command._run_command.call_count == 1
assert active.read_bytes() == b'# Prior config\r\n'
assert index.read_bytes() == b'# Prior index\r\n'
assert canonical.read_bytes() == original_config
assert source.read_bytes() == original_source
assert full_output.read_bytes() == b'KEEP FULL ARTIFACT'
assert all(signal.getsignal(sig) == handler for sig, handler in handlers.items())
assert not list((books / 'config').glob('*.backup'))
@pytest.mark.parametrize('outcome', ('failure', 'exception', 'interrupt', 'no-artifact'))
def test_failed_build_restores_legacy_symlink_and_absent_index(tmp_path, outcome):
books, source, chapter, canonical, command = fixture_book(tmp_path)
original = canonical.read_bytes()
active = books / '_quarto.yml'
active.symlink_to(canonical)
def fail(*args, **kwargs):
if outcome == 'exception':
raise RuntimeError('Renderer crashed')
if outcome == 'interrupt':
raise KeyboardInterrupt()
return outcome == 'no-artifact'
command._run_command = fail
assert not command.build_chapters_with_volume(['01_boundary'], 'pdf', 'vol4', skip_validate=True)
assert active.is_symlink() and active.resolve() == canonical
assert canonical.read_bytes() == original
assert not (books / 'index.qmd').exists()
def test_preface_is_not_duplicated_when_it_is_generated_index(tmp_path):
books, source, chapter, canonical, command = fixture_book(tmp_path)
def render(*args, **kwargs):
current = yaml.safe_load((books / '_quarto.yml').read_text())
assert current['book']['chapters'] == ['index.qmd']
output = books / current['project']['output-dir']
(output / 'about.pdf').write_bytes(b'BUILT')
return True
command._run_command = render
assert command.build_chapters_with_volume(['Preface'], 'pdf', 'vol4', skip_validate=True)
@pytest.mark.parametrize('query', ('vol1/01_boundary', 'vol1/01_boundary/01_boundary.qmd', 'missing chapter'))
def test_bad_scope_or_missing_chapter_never_renders(tmp_path, query):
books, source, chapter, canonical, command = fixture_book(tmp_path)
command._run_command = Mock()
assert not command.build_chapters_with_volume([query], 'pdf', 'vol4')
command._run_command.assert_not_called()
assert not (books / '_quarto.yml').exists()
def test_missing_volume_config_cannot_fall_back(tmp_path):
books, source, chapter, canonical, command = fixture_book(tmp_path)
canonical.rename(books / 'config/_quarto-pdf-vol1.yml')
command._run_command = Mock()
assert not command.build_chapters_with_volume(['01_boundary'], 'pdf', 'vol4')
command._run_command.assert_not_called()
@pytest.mark.parametrize('query', ('vol4/01_boundary', 'vol4/01_boundary.qmd',
'vol4/01_boundary/01_boundary.qmd', 'vol4/the causal boundary',
'vol4/causal-boundary', 'vol4/Causal Boundry'))
def test_filename_title_substring_and_typo_queries(tmp_path, query):
books, source, chapter, canonical, command = fixture_book(tmp_path)
assert command.chapter_discovery.find_chapter_file(query, allow_fuzzy=True) == chapter
def test_ambiguous_within_volume_is_not_chosen_by_shorter_name(tmp_path):
books, source, chapter, canonical, command = fixture_book(tmp_path)
other = chapter.with_name('03_boundary_safety.qmd')
other.write_text('# The Boundary and Safety\n')
with pytest.raises(AmbiguousChapterError) as caught:
command.chapter_discovery.find_chapter_file('vol4/boundary', allow_fuzzy=True)
assert len(caught.value.locations) == 2
assert all(path.startswith('vol4/') for path in caught.value.locations)
assert command.chapter_discovery.find_chapter_file('vol4/01_boundary') == chapter
def test_same_stem_across_volumes_requires_scope(tmp_path):
books, source, chapter, canonical, command = fixture_book(tmp_path)
other = books / 'vol3/01_boundary/01_boundary.qmd'
other.parent.mkdir(parents=True)
other.write_text('# Agentic Boundary\n')
with pytest.raises(AmbiguousChapterError):
command.chapter_discovery.find_chapter_file('01_boundary')
assert command.chapter_discovery.find_chapter_file('vol3/01_boundary') == other
@pytest.mark.parametrize('volume', VOLUMES)
def test_parser_preserves_readable_query_and_volume(volume):
cli = object.__new__(MLSysBookCLI)
parsed = cli._parse_build_args(['pdf', '--' + volume, 'the', 'causal', 'boundary'])
assert parsed[:4] == ('pdf', volume, False, 'the causal boundary')
parsed = cli._parse_build_args(['pdf', 'intro', '--' + volume])
assert parsed[:4] == ('pdf', volume, False, 'intro')
def test_parser_rejects_conflicting_volumes():
cli = object.__new__(MLSysBookCLI)
with pytest.raises(ValueError, match='only one volume'):
cli._parse_build_args(['pdf', '--vol4', '--vol1'])
def test_prefixed_build_routes_to_volume_scoped_path(tmp_path):
books, source, chapter, canonical, command = fixture_book(tmp_path)
command.build_chapters_with_volume = Mock(return_value=True)
assert command.build_chapters(['vol4/causal boundary'], 'pdf', skip_validate=True)
command.build_chapters_with_volume.assert_called_once_with(
['vol4/01_boundary/01_boundary.qmd'], 'pdf', 'vol4', skip_hygiene=False, skip_validate=True)
def test_cli_prefixed_html_uses_volume_scoped_dispatch(tmp_path):
books, source, chapter, canonical, command = fixture_book(tmp_path, format_type='html')
command.build_chapters_with_volume = Mock(return_value=True)
command.build_html_only = Mock(return_value=True)
cli = object.__new__(MLSysBookCLI)
cli.config_manager = Mock(book_dir=books)
cli.build_command = command
assert cli.handle_build_command(['html', 'vol4/01_boundary/01_boundary.qmd'])
command.build_chapters_with_volume.assert_called_once_with(
['vol4/01_boundary/01_boundary.qmd'], 'html', 'vol4', skip_hygiene=False, skip_validate=False)
@pytest.mark.parametrize('volume', VOLUMES)
def test_real_volume_discovery_resolves_all_canonical_stems(volume):
discovery = ChapterDiscovery(ROOT / 'books')
stems = discovery.get_chapters_from_config(volume)
assert len(stems) > 10
assert all(discovery.find_chapter_file(f'{volume}/{stem}') for stem in stems)
@pytest.mark.parametrize('verbose', (False, True))
def test_interruption_stops_renderer_group_before_restoration(tmp_path, monkeypatch, verbose):
import os
from binder.cli.commands import build as build_module
books, source, chapter, canonical, command = fixture_book(tmp_path)
command.verbose = verbose
renderer = Mock(pid=987654321)
renderer.poll.return_value = None
renderer.communicate.side_effect = KeyboardInterrupt()
renderer.stdout.readline.side_effect = KeyboardInterrupt()
popen = Mock(return_value=renderer)
monkeypatch.setattr(build_module.subprocess, 'Popen', popen)
kill_group = Mock()
if os.name == 'posix':
monkeypatch.setattr(build_module.os, 'killpg', kill_group)
with pytest.raises(KeyboardInterrupt):
command._run_command(['quarto', 'render'], books, 'Test interrupt')
assert popen.call_args.kwargs['start_new_session'] is True
if os.name == 'posix':
kill_group.assert_called_once_with(renderer.pid, signal.SIGKILL)
else:
renderer.kill.assert_called_once()
renderer.wait.assert_called_once()
@pytest.mark.parametrize('build_kind', ('full', 'volume', 'selective'))
@pytest.mark.parametrize('verbose', (False, True))
@pytest.mark.parametrize('signum', (signal.SIGINT, signal.SIGTERM))
def test_build_signal_stops_renderer_before_shared_file_restoration(
tmp_path, monkeypatch, build_kind, verbose, signum):
"""An interrupted build kills the renderer group, then restores shared files and handlers."""
import os
from binder.cli.commands import build as build_module
books, source, chapter, canonical, command = fixture_book(tmp_path)
command.verbose = verbose
original = canonical.read_bytes()
active = books / '_quarto.yml'
index = books / 'index.qmd'
active.write_bytes(b'# Prior config\n')
index.write_bytes(b'# Prior index\n')
header = books / 'shared/tex/header-includes.tex'
header.parent.mkdir(parents=True)
header.write_text('\\CropMarksfalse\n')
events = []
previous_handlers = {sig: signal.getsignal(sig) for sig in (signal.SIGINT, signal.SIGTERM)}
monkeypatch.setattr(command.config_manager, 'get_config_file', lambda *args: canonical)
renderer = Mock(pid=987654321)
renderer.poll.return_value = None
def interrupt(*args, **kwargs):
signal.getsignal(signum)(signum, None)
def wait_for_renderer(*args, **kwargs):
events.append('wait')
assert active.read_bytes() != b'# Prior config\n'
if build_kind == 'volume':
assert header.read_text() == '\\CropMarkstrue\n'
renderer.communicate.side_effect = interrupt
renderer.stdout.readline.side_effect = interrupt
renderer.wait.side_effect = wait_for_renderer
monkeypatch.setattr(build_module.subprocess, 'Popen', Mock(return_value=renderer))
if os.name == 'posix':
monkeypatch.setattr(build_module.os, 'killpg', lambda *args: events.append('kill'))
else:
renderer.kill.side_effect = lambda: events.append('kill')
try:
if build_kind == 'selective':
assert not command.build_chapters_with_volume(['01_boundary'], 'pdf', 'vol4')
assert active.read_bytes() == b'# Prior config\n'
assert index.read_bytes() == b'# Prior index\n'
elif build_kind == 'full':
assert not command.build_full('pdf')
else:
assert not command.build_volume('vol4', 'pdf', print_marks=True)
assert events == ['kill', 'wait']
assert all(signal.getsignal(sig) == handler for sig, handler in previous_handlers.items())
assert canonical.read_bytes() == original
assert header.read_text() == '\\CropMarksfalse\n'
finally:
for sig, handler in previous_handlers.items():
signal.signal(sig, handler)
def test_no_cover_edits_the_generated_config_not_the_source(tmp_path):
"""--no-cover used to edit the source YAML after it was copied, so it never took effect (2026-09-12)."""
books, source, chapter, canonical, command = fixture_book(tmp_path)
original = canonical.read_bytes()
active = books / '_quarto.yml'
def render(cmd, *, cwd, description):
assert ' coverpage: false' in active.read_text()
assert canonical.read_bytes() == original
return True
command._run_command = Mock(side_effect=render)
assert command.build_volume('vol4', 'pdf', skip_validate=True, no_cover=True)
assert command._run_command.call_count == 1
assert canonical.read_bytes() == original
def test_print_marks_toggles_the_shared_header_and_restores_it(tmp_path):
books, source, chapter, canonical, command = fixture_book(tmp_path)
header = books / 'shared/tex/header-includes.tex'
header.parent.mkdir(parents=True)
header.write_text('\\newif\\ifCropMarks\n\\CropMarksfalse\n')
def render(cmd, *, cwd, description):
assert '\\CropMarkstrue' in header.read_text()
return True
command._run_command = Mock(side_effect=render)
assert command.build_volume('vol4', 'pdf', skip_validate=True, print_marks=True)
assert header.read_text() == '\\newif\\ifCropMarks\n\\CropMarksfalse\n'
def test_presentation_flags_are_rejected_for_non_pdf_volume_builds(tmp_path):
books, source, chapter, canonical, command = fixture_book(tmp_path, format_type='html')
command._run_command = Mock()
assert not command.build_volume('vol4', 'html', no_cover=True)
command._run_command.assert_not_called()
def test_chapters_from_several_volumes_are_rejected(tmp_path):
books, source, chapter, canonical, command = fixture_book(tmp_path)
other = books / 'vol3/05_memory/05_memory.qmd'
other.parent.mkdir(parents=True)
other.write_text('# Memory Hierarchy\n')
command._run_command = Mock()
command.build_chapters_with_volume = Mock(return_value=True)
assert not command.build_chapters(['vol4/01_boundary', 'vol3/05_memory'], 'pdf')
command.build_chapters_with_volume.assert_not_called()
command._run_command.assert_not_called()
@pytest.mark.parametrize('start', ('.', 'books', 'binder'))
def test_config_manager_root_is_repository_root_from_any_start_dir(tmp_path, start):
(tmp_path / 'books' / 'config').mkdir(parents=True)
(tmp_path / 'books' / 'vol1').mkdir()
(tmp_path / 'binder').mkdir()
manager = ConfigManager(tmp_path / start)
assert manager.book_dir == tmp_path / 'books'
assert manager.root_dir == tmp_path
def test_chapter_list_falls_back_to_line_scan_when_yaml_is_invalid(tmp_path, capsys):
from binder.cli.core.discovery import get_chapters_from_config
config = tmp_path / 'config' / '_quarto-pdf-vol1.yml'
config.parent.mkdir()
stems = [f'0{i}_ch' for i in range(1, 7)]
config.write_text('book:\n chapters:\n' + ''.join(f' - vol1/{s}/{s}.qmd\n' for s in stems)
+ ' bad: [unclosed\n')
assert get_chapters_from_config(tmp_path, 'vol1') == stems
assert 'falling back to a line scan' in capsys.readouterr().err