build_gallery.py: 1,918-line file with inline CSS/JS and a Markdown renderer, and no unit tests #528

Summary

scripts/build_gallery.py is a 1,918-line file that holds about 990 lines of CSS/JS/HTML in Python string literals, a hand-rolled Markdown renderer, entry validation and page assembly, and it has no unit tests. Its only check is a regenerate-and-diff against committed output, which is circular: a generator bug is committed together with its output.

Where

• scripts/build_gallery.py:180-1166 (SHELL, GALLERY_CSS at :220, INDEX_JS at :611, DETAIL_JS at :1000, CARD/MINI_CARD with __PLACEHOLDER__ replace chains at :1428-1433)
• scripts/build_gallery.py:1177-1347 (render_inline, slugify, md_to_html)
• scripts/build_gallery.py:102-178 (load_gallery_entries, check_alts, check_categories)
• scripts/build_gallery.py:1635 (first_sentence)
• .github/workflows/validate.yml:103-107 (staleness diff)

Details

The landing build (scripts/site/build_site.py) uses Jinja2 templates on disk, so the site has two templating systems. No test in tests/ imports build_gallery. Precedent: PR #68 (teaches.split(".")[0] truncated 14 of 21 card alts), which CLAUDE.md now works around with a manual "read the generated HTML character by character" step.

Impact

Every gallery UI change edits CSS/JS inside Python without editor tooling, and any change to README Markdown handling can silently regress about 150 pages.

Suggested fix

1. Add tests/test_build_gallery.py first:
   • first_sentence("Uses bmesh.ops.create_cone. Then…") does not split at bmesh.
   • slugify de-duplicates and avoids RESERVED_IDS
   • render_inline escapes <script> in text and code spans
   • md_to_html handles escaped pipes in tables and skip_first_h1
   • check_alts exits on empty, too-long or backticked alts
   • a fixture entry's card alt= equals the source alt verbatim
2. Move GALLERY_CSS, INDEX_JS and DETAIL_JS verbatim to files under scripts/site/, read at build time (byte-identical output, proven by the staleness diff).
3. Extract md_to_html and helpers into a module with golden-file tests over 3-4 real READMEs.
4. Optionally move SHELL/CARD/MINI_CARD to .j2 templates (Jinja2 is already a site dependency).

Acceptance criteria

• Unit tests for the listed functions run in Validate.
• CSS/JS live in their own files; regenerated output is byte-identical.

_{Filed by repo-audit/full-audit at 077cdd9a. Severity: medium. Effort: M. audit-key: tech-debt|scripts/build_gallery.py|god-file-no-tests}