mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-11-14 18:24:37 -06:00
139 lines
5.2 KiB
Python
139 lines
5.2 KiB
Python
"""Enforce the shared content skeleton across vol1-vol4.
|
|
|
|
Added 2026-09-07 after an audit found vol3 carrying 24 orphaned outline stubs,
|
|
vol4 carrying 4 orphaned figure directories, and vol4 using a different skeleton
|
|
(chapters/, front-matter/, appendix/, figures/) from the other three volumes.
|
|
|
|
These checks are cheap and catch the drift class that produced that state:
|
|
a chapter dir whose .qmd does not match its name, a config pointing at a file
|
|
that does not exist, a file on disk that no config renders, and a volume whose
|
|
top-level layout diverges from the shared skeleton.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import re
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
REPO = Path(__file__).resolve().parents[2]
|
|
QUARTO = REPO / "books"
|
|
CONTENTS = QUARTO
|
|
CONFIG = QUARTO / "config"
|
|
|
|
VOLUMES = ("vol1", "vol2", "vol3", "vol4")
|
|
RESERVED = {
|
|
"frontmatter",
|
|
"backmatter",
|
|
"parts",
|
|
"appendices",
|
|
"covers",
|
|
"styles",
|
|
"tex",
|
|
"images",
|
|
}
|
|
|
|
QMD_REF = re.compile(r"(?<![\w/.-])(?:vol[1-4]|shared)/[A-Za-z0-9_./-]+\.qmd")
|
|
INCLUDE = re.compile(r"\{\{<\s*include\s+([^>}]+?)\s*>\}\}")
|
|
|
|
|
|
def config_refs() -> set[str]:
|
|
"""Every volume or shared .qmd path any Quarto config mentions."""
|
|
refs: set[str] = set()
|
|
for cfg in CONFIG.rglob("*.yml"):
|
|
refs.update(QMD_REF.findall(cfg.read_text(encoding="utf-8")))
|
|
return refs
|
|
|
|
|
|
def include_refs() -> set[str]:
|
|
"""Every .qmd pulled in via a Quarto {{< include >}} shortcode."""
|
|
refs: set[str] = set()
|
|
for qmd in CONTENTS.rglob("*.qmd"):
|
|
for raw in INCLUDE.findall(qmd.read_text(encoding="utf-8", errors="ignore")):
|
|
target = (qmd.parent / raw.strip()).resolve()
|
|
try:
|
|
refs.add(str(target.relative_to(QUARTO)))
|
|
except ValueError:
|
|
pass
|
|
return refs
|
|
|
|
|
|
@pytest.mark.parametrize("vol", VOLUMES)
|
|
def test_chapter_dir_matches_its_qmd(vol: str) -> None:
|
|
"""Every chapter directory holds <slug>/<slug>.qmd.
|
|
|
|
binder/cli/commands/build.py builds chapter paths from this invariant.
|
|
"""
|
|
bad = []
|
|
for d in sorted((CONTENTS / vol).iterdir()):
|
|
if not d.is_dir() or d.name in RESERVED or d.name.startswith(("_", ".")):
|
|
continue
|
|
if not (d / f"{d.name}.qmd").exists():
|
|
bad.append(f"{vol}/{d.name} has no {d.name}.qmd")
|
|
assert not bad, "Chapter dir/file name mismatch:\n " + "\n ".join(bad)
|
|
|
|
|
|
def test_every_config_path_exists() -> None:
|
|
"""No Quarto config points at a .qmd that is not on disk."""
|
|
missing = sorted(r for r in config_refs() if not (QUARTO / r).exists())
|
|
assert not missing, "Config references missing files:\n " + "\n ".join(missing)
|
|
|
|
|
|
def test_no_orphan_qmd_in_volumes() -> None:
|
|
"""Every .qmd inside a volume is rendered by some config or included by another .qmd.
|
|
|
|
An orphan is a file no build path reaches. That is how vol3 accumulated 24
|
|
superseded outline stubs and vol4 accumulated 4 dead figure directories.
|
|
"""
|
|
live = config_refs() | include_refs()
|
|
orphans = []
|
|
for vol in VOLUMES:
|
|
for qmd in sorted((CONTENTS / vol).rglob("*.qmd")):
|
|
rel = str(qmd.relative_to(QUARTO))
|
|
if rel not in live:
|
|
orphans.append(rel)
|
|
assert not orphans, "Orphaned .qmd files (rendered by nothing):\n " + "\n ".join(orphans)
|
|
|
|
|
|
@pytest.mark.parametrize("vol", VOLUMES)
|
|
def test_shared_skeleton(vol: str) -> None:
|
|
"""Each volume carries the same top-level layout."""
|
|
root = CONTENTS / vol
|
|
problems = []
|
|
for required in ("index.qmd", "README.md"):
|
|
if not (root / required).exists():
|
|
problems.append(f"{vol}/ is missing {required}")
|
|
for required in ("frontmatter", "parts", "backmatter"):
|
|
if not (root / required).is_dir():
|
|
problems.append(f"{vol}/ is missing the {required}/ directory")
|
|
if not (root / "backmatter" / "references.qmd").exists():
|
|
problems.append(f"{vol}/backmatter/ is missing references.qmd")
|
|
# Chapter assets live in images/, never figures/.
|
|
for figures in root.rglob("figures"):
|
|
if figures.is_dir():
|
|
problems.append(f"{figures.relative_to(CONTENTS)} should be named images/")
|
|
# No nesting layer between the volume root and its chapters.
|
|
if (root / "chapters").exists():
|
|
problems.append(f"{vol}/chapters/ should not exist; chapters sit at the volume root")
|
|
assert not problems, "Skeleton drift:\n " + "\n ".join(problems)
|
|
|
|
|
|
@pytest.mark.parametrize("vol", VOLUMES)
|
|
def test_no_stray_build_artifacts(vol: str) -> None:
|
|
"""Quarto build artifacts are never committed into the content tree."""
|
|
strays = [
|
|
str(p.relative_to(CONTENTS))
|
|
for p in sorted((CONTENTS / vol).rglob("*"))
|
|
if p.is_file() and p.suffix in {".quarto_ipynb", ".ipynb_checkpoints"}
|
|
]
|
|
assert not strays, "Build artifacts in content tree:\n " + "\n ".join(strays)
|
|
|
|
|
|
def test_structure_manifest_is_current() -> None:
|
|
"""books/shared/STRUCTURE.md matches what the PDF configs say."""
|
|
import subprocess
|
|
|
|
gen = REPO / "binder" / "tools" / "scripts" / "structure" / "gen_structure.py"
|
|
r = subprocess.run(["python3", str(gen), "--check"], capture_output=True, text=True)
|
|
assert r.returncode == 0, r.stderr or r.stdout
|