check_links validates img src, closing the figure-variant gap

[dimitri-yatsenko]

Closes #283.

The gap

#278 introduced an invariant — every <img> the hook rewrites points at a file on_post_build actually emits — and nothing checked it. scripts/check_links.py collected hrefs only where tag == "a", so if the generator and the rewriter disagreed, all five CI checks stayed green and the figure 404'd in production.

mkdocs build --strict cannot catch this either: the variants are written in on_post_build, after MkDocs' own reference validation, and the rewrite happens in on_post_page on raw HTML that MkDocs never re-inspects. The built-site job is the only place that can close it.

Changes

scripts/check_links.py — collect <img src> alongside <a href>, reported as no such image. Fragments are now validated only on HTML targets: the rewriter emits #only-light / #only-dark, which name CSS hooks rather than anchors, so checking them against a parsed SVG would have produced 36 false failures on the current site.

scripts/svg_theme.py — four fixes, all of which the new check would otherwise surface as breakage:

• glob → rglob in on_post_build. on_files accepts any depth, so a themed SVG under src/images/<subdir>/ had its pages rewritten to variants that were never generated.
• _themed is keyed by path under images/ rather than by bare stem, so same-named figures in different subdirectories cannot collide.
• Query and fragment are stripped once, before the .svg test and the slice. Previously line 93 stripped them and line 94 tested the unstripped path, so foo.svg#view never rewrote.
• IMG_SRC accepts single-quoted src, which previously fell through silently.

src/images/pipeline.svg — drop the build-time-split note. The module docstring at svg_theme.py:12-23 covers it more completely, extra.css carries a third copy, and keeping it would mean copying the text into the other 17 themed figures, which are regenerated by script.

Verification

Reproduced the CI path locally (pip install -r pip_requirements.txt, mkdocs build --strict, check_links.py site):

• Clean build: 142 pages, all links and images resolve, 18 themed figures producing 18 light/dark pairs and 18 rewritten <img> pairs.
• Added a themed fixture at src/images/sub/fixture.svg and reverted rglob to glob. The build stayed green, and the extended checker reported both missing variants — the exact failure check_links.py does not validate img src, so a rewritten figure can 404 with CI green #283 describes. With rglob restored, the fixture builds and passes. Fixture removed before this PR.
• Unit-checked the rewriter across twelve cases: relative, root-absolute and bare images/ paths, subdirectories, single quotes, fragments, queries, unthemed figures, non-SVG sources, and stem collisions in both directions.

Left alone deliberately

Both theme variants are still fetched, since display:none does not suppress the request. That is inherent to the approach and small for SVG — recorded in #283, not a defect this PR fixes.

[MilagrosMarin]

This closes the gap from #278, so I mutation-tested the new check rather than trusting a green run — a passing CI proves no false positives, not that the check has teeth.

• Missing variant: caught, exit 1. The #283 failure mode now fails the build.
• All references valid, including #only-light on an SVG: clean, no false positives.
• Bad anchor on an HTML target: still caught.

That last one was my main worry: gating fragments on target.suffix == ".html" could have silently disabled anchor checking for ordinary page links. It doesn't, because resolve() already maps a directory URL to its index.html, so page targets keep the suffix. Worth knowing the two are coupled — if resolve() ever stops appending index.html, anchor checking goes quiet rather than failing.

Verified all four svg_theme.py fixes across eleven cases: relative, root-absolute and bare images/ paths, subdirectories, single quotes, fragments, queries, unthemed figures, non-SVG sources, and stem collision in both directions — a/dup.svg themed rewrites while b/dup.svg unthemed stays untouched, which bare-stem keying got wrong. pipeline.svg is an exact revert to its pre-#278 blob.

One small thing, not worth changing: _image_key searches for (?:^|/)images/ anywhere in the path, slightly looser than on_files's startswith. There is a second images directory at src/.overrides/assets/images, currently one PNG, so nothing collides today — and if it ever did, this PR is exactly what would make it loud instead of silent.