Merge chore/precheck-2026-09-12: skip build output in checks

Author: profvjreddi

binder/cli/checks/concept_maps.py

@@ -8,6 +8,11 @@
 
 import yaml
 
+try:
+    from cli.checks.generated_paths import is_generated
+except ImportError:  # pragma: no cover - package-relative import path
+    from binder.cli.checks.generated_paths import is_generated
+
 LIST_FIELDS = {
     "primary_concepts",
     "secondary_concepts",
@@ -134,7 +139,8 @@ def _validate_concept_map_file(
 def check_concept_maps(contents_dir: Path, repo_root: Path) -> List[ConceptMapIssue]:
     """Validate all concept maps in contents_dir."""
     findings: List[ConceptMapIssue] = []
-    qmd_files = sorted(contents_dir.glob("**/*.qmd"))
+    # 2026-09-12: stale _build copies of chapters failed the push hook.
+    qmd_files = sorted(p for p in contents_dir.glob("**/*.qmd") if not is_generated(p, contents_dir))
     qmd_frontmatter = {path: _frontmatter(path) for path in qmd_files}
 
     referenced_maps: dict[Path, Path] = {}
@@ -154,7 +160,9 @@ def check_concept_maps(contents_dir: Path, repo_root: Path) -> List[ConceptMapIs
             findings.append(ConceptMapIssue("error", qmd_rel, f"frontmatter concepts file is not YAML: {concepts_ref}"))
         referenced_maps[concept_path.resolve()] = qmd_path
 
-    for concept_path in sorted(contents_dir.glob("**/*_concepts.y*ml")):
+    for concept_path in sorted(
+        p for p in contents_dir.glob("**/*_concepts.y*ml") if not is_generated(p, contents_dir)
+    ):
         _validate_concept_map_file(concept_path, qmd_frontmatter, repo_root, findings)
         if concept_path.resolve() not in referenced_maps:
             concept_rel = str(concept_path.relative_to(repo_root)) if concept_path.is_relative_to(repo_root) else str(concept_path)

binder/cli/checks/generated_paths.py

@@ -0,0 +1,25 @@
+"""Recognize generated trees that source checks must never scan.
+
+A local render leaves build output and caches inside ``books/``: HTML and PDF
+output under ``_build/``, Quarto caches under ``.quarto/``, and per-chapter
+figure directories named ``<chapter>_files/``. Those trees hold stale copies
+of sources and assets, so a check that walks them reports defects that do not
+exist in the tracked content.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+GENERATED_DIRS = frozenset(
+    {".quarto", "_build", "__pycache__", ".venv", "venv", "node_modules"}
+)
+
+
+def is_generated(path: Path, root: Path) -> bool:
+    """True when *path* lies inside a generated tree below *root*."""
+    try:
+        parts = path.relative_to(root).parts[:-1]
+    except ValueError:
+        parts = path.parts[:-1]
+    return any(part in GENERATED_DIRS or part.endswith("_files") for part in parts)

binder/cli/commands/validate.py

@@ -11636,15 +11636,19 @@ def _run_image_formats(self, root: Path) -> ValidationRunResult:
         """Validate image file formats using Pillow."""
         try:
             from cli.checks.image_formats import check_file
+            from cli.checks.generated_paths import is_generated
         except ImportError:
             from binder.cli.checks.image_formats import check_file
+            from binder.cli.checks.generated_paths import is_generated
 
         t0 = time.time()
         image_files: List[Path] = []
         for ext in ("*.png", "*.jpg", "*.jpeg", "*.gif", "*.webp"):
+            # 2026-09-12: stale _build copies of covers failed the push hook;
+            # only tracked-content trees are checked.
             image_files.extend([
                 f for f in sorted(root.rglob(ext))
-                if "_files/mediabag/" not in str(f)
+                if not is_generated(f, root)
             ])
 
         issues: List[ValidationIssue] = []

binder/tests/test_generated_paths.py

@@ -0,0 +1,24 @@
+"""Source checks must ignore render output and caches under books/."""
+
+from pathlib import Path
+
+from checks.concept_maps import check_concept_maps
+from checks.generated_paths import is_generated
+
+
+def test_is_generated_flags_build_trees(tmp_path: Path) -> None:
+    assert is_generated(tmp_path / "_build" / "html-vol1" / "index.qmd", tmp_path)
+    assert is_generated(tmp_path / ".quarto" / "idx" / "a.json", tmp_path)
+    assert is_generated(tmp_path / "vol1" / "01_intro" / "01_intro_files" / "f.png", tmp_path)
+    assert not is_generated(tmp_path / "vol1" / "01_intro" / "01_intro.qmd", tmp_path)
+
+
+def test_concept_maps_ignore_stale_build_copies(tmp_path: Path) -> None:
+    books = tmp_path / "books"
+    stale = books / "_build" / "html-vol1" / "vol1" / "conclusion" / "conclusion.qmd"
+    stale.parent.mkdir(parents=True)
+    stale.write_text("---\nconcepts: conclusion_concepts.yml\n---\n", encoding="utf-8")
+
+    findings = check_concept_maps(books, tmp_path)
+
+    assert not [f for f in findings if "_build" in f.path]

books/config/_quarto-html-vol1.yml

@@ -18,8 +18,8 @@ project:
   # collision. Mirrors _quarto-html-vol2.yml. Do NOT remove this as "stale" — it is
   # load-bearing for the vol1 HTML build (removing it in 3d5aa628ae broke CI for weeks).
   resources:
-    - shared/assets/images/covers/*
-    - shared/assets/downloads/*
+    - /shared/assets/images/covers/*
+    - /shared/assets/downloads/*
 
   render:
     - index.qmd

books/config/_quarto-html-vol2.yml

@@ -11,8 +11,8 @@ project:
   execute-dir: project
 
   resources:
-    - shared/assets/images/covers/*
-    - shared/assets/downloads/*
+    - /shared/assets/images/covers/*
+    - /shared/assets/downloads/*
 
   # Full render manifest (vol2 HTML). An explicit list is required here: the
   # project index (index.qmd) and the website homepage (index-vol2.qmd) BOTH

books/config/_quarto-html-vol3.yml

@@ -8,8 +8,8 @@ project:
   execute-dir: project
 
   resources:
-    - shared/assets/images/covers/*
-    - shared/assets/downloads/*
+    - /shared/assets/images/covers/*
+    - /shared/assets/downloads/*
 
   render:
     - index.qmd

books/config/_quarto-html-vol4.yml

@@ -11,8 +11,8 @@ project:
   execute-dir: project
 
   resources:
-    - shared/assets/images/covers/*
-    - shared/assets/downloads/*
+    - /shared/assets/images/covers/*
+    - /shared/assets/downloads/*
 
   render:
     # Generated from vol4/index.qmd. The preface is a separate page below.