refactor(docs-site): stop parsing C++ source for the palette, hand outbound links to lychee (p-ponytail-b) - #565
Merged
Conversation
…tbound links to lychee (#563) Two docs-site scripts go, both replaced by something already in the tree. theme-css.mjs located graphite_amber() inside theme.cpp with indexOf and then regexed the QColor(0x..) literals back out — a JavaScript parser of C++ source, which any reformat of theme.cpp breaks. The repo had already solved this exact problem once, for editor/resources/help/help.css: generate in C++, commit the output, byte-gate the committed file from a gtest. So the palette is now emitted by help_style::starlight_css(), sitting beside the help.css generator it copies, and docs-site/src/styles/theme.css is committed and gated by HelpStyle.StarlightCssMatchesCommittedThemeCss. Every colour value is identical to what the old script produced — diffed, not assumed. The site build still needs nothing but Node (ADR-0009): the gate runs in the C++ matrix, and the site reads a file that is already in the tree. theme.css is pinned `text eol=lf`, the fourth entry in .gitattributes for that reason — a byte gate against a generated file fails on the Windows runner's autocrlf checkout on line endings alone, invisibly on macOS and Linux. report-external-links.mjs was 125 lines of hand-rolled fetch, 8-way concurrency and timeout handling producing a report that always exited 0 — while lychee was already a CI dependency running --offline on the PR path. A weekly non-blocking external-links workflow replaces it. It is a separate workflow rather than a job in ci.yml because adding `schedule` there would arm all fourteen of its jobs, and it keeps the network-touching check off the PR path entirely. check-links.mjs stays: it checks the built, assembled, multi-version tree, which neither lychee nor the source-side adapter check can see. Verified: 25/25 docs-site script tests, licences, build:web + check:links (40 pages, 2922 references), build:local + check:local, and the accent lands in dist/_astro as #f5a623. The new gate was sabotage-checked — one changed hex and it goes red. -56 lines.
JArmandoAnaya
force-pushed
the
refactor/ponytail-docs-site
branch
from
August 12, 2026 14:50
0d2e8d5 to
f347c69
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part 2 of 2 for #563 (ponytail audit remediation), after #564. Two docs-site
scripts go; both are replaced by something already in the tree.
theme-css.mjs→ thehelp.csspatternIt located
graphite_amber()insidetheme.cppwithindexOf, then regexedthe
QColor(0x..)literals back out of the initializer:A JavaScript parser of C++ source. Any reformat of
theme.cppbreaks it, andnothing would catch that until someone looked at the site.
The repo had already solved this exact problem once, for
editor/resources/help/help.css: generate in C++, commit the output,byte-gate the committed file from a gtest. So the palette is now emitted by
help_style::starlight_css()— sitting beside thehelp_style::css()itcopies — and
docs-site/src/styles/theme.cssis committed and gated byHelpStyle.StarlightCssMatchesCommittedThemeCss.Every colour value is unchanged — diffed against the old script's output,
not assumed:
ADR-0009 still holds. The site build needs nothing but Node: the gate runs
in the C++ matrix, and the site reads a file already in the tree.
npm run themeis gone frompackage.json,build-web.mjsandbuild-local.mjs.theme.cssis pinnedtext eol=lf— the fourth entry in.gitattributesfor that reason. A byte gate against a generated file fails on the Windows
runner's autocrlf checkout on line endings alone, and it is invisible on macOS
and Linux.
report-external-links.mjs→ lychee125 lines of hand-rolled
fetch, 8-way concurrency and timeout handling, toproduce a report that always exits 0 — while lychee was already a CI dependency,
running
--offlineon the PR path. A weekly non-blockingexternal-linksworkflow replaces it, output going to the run summary.
A separate workflow, not a job in
ci.yml: addingschedulethere wouldarm all fourteen of its jobs, and gating each one is a worse diff than one small
file. It also keeps the only network-touching check off the PR path entirely.
check-links.mjsstays — it checks the built, assembled, multi-versionpublish tree, which neither lychee nor the source-side adapter check can see.
Its one test that imported
collectExternalLinksgoes with the script.Verification
npm testnpm run licensesnpm run build:web -- --base=/dev/+check:linksnpm run build:local+check:local--sl-color-accent: #f5a623indist/_astro/index.*.cssHelpStyle.*clang-format --dry-run --WerrorThe new gate was sabotage-checked: change one hex digit in the committed
theme.cssand it goes red, then green again when restored.Size
−56 lines excluding the CHANGELOG (+191 / −247). Two scripts and one npm
build step deleted; one C++ function, one committed 16-line CSS file, two gtests
and one 46-line workflow added.
Closes #563.