Skip to content

refactor(docs-site): stop parsing C++ source for the palette, hand outbound links to lychee (p-ponytail-b) - #565

Merged
JArmandoAnaya merged 1 commit into
mainfrom
refactor/ponytail-docs-site
Aug 12, 2026
Merged

refactor(docs-site): stop parsing C++ source for the palette, hand outbound links to lychee (p-ponytail-b)#565
JArmandoAnaya merged 1 commit into
mainfrom
refactor/ponytail-docs-site

Conversation

@JArmandoAnaya

Copy link
Copy Markdown
Contributor

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.

Stacked on main alongside #564. Both add a ### Changed entry at the same
anchor, so this one gets rebased and the CHANGELOG re-resolved once #564
lands.

theme-css.mjs → the help.css pattern

It located graphite_amber() inside theme.cpp with indexOf, then regexed
the QColor(0x..) literals back out of the initializer:

const start = text.indexOf('const Theme& graphite_amber()');
const block = text.slice(start, text.indexOf('};', start));
const pattern = /\.(\w+)\s*=\s*QColor\(\s*0x([0-9a-fA-F]{2})\s*, .../g;

A JavaScript parser of C++ source. Any reformat of theme.cpp breaks it, and
nothing 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 the help_style::css() it
copies — and docs-site/src/styles/theme.css is committed and gated by
HelpStyle.StarlightCssMatchesCommittedThemeCss.

Every colour value is unchanged — diffed against the old script's output,
not assumed:

diff <(grep -- --sl-color theme-old.css) <(grep -- --sl-color theme.css)
→ identical

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 theme is gone from package.json, build-web.mjs and build-local.mjs.

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, and it is invisible on macOS
and Linux.

report-external-links.mjs → lychee

125 lines of hand-rolled fetch, 8-way concurrency and timeout handling, to
produce a report that always exits 0 — while lychee was already a CI dependency,
running --offline on the PR path. A weekly non-blocking external-links
workflow replaces it, output going to the run summary.

A separate workflow, not a job in ci.yml: adding schedule there would
arm 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.mjs stays — it checks the built, assembled, multi-version
publish tree, which neither lychee nor the source-side adapter check can see.
Its one test that imported collectExternalLinks goes with the script.

Verification

result
npm test 25/25
npm run licenses pass
npm run build:web -- --base=/dev/ + check:links 40 pages, 2922 references, all resolve
npm run build:local + check:local 40 pages, no root-absolute refs, search correctly absent
accent reaches the build --sl-color-accent: #f5a623 in dist/_astro/index.*.css
HelpStyle.* 5/5
clang-format --dry-run --Werror clean

The new gate was sabotage-checked: change one hex digit in the committed
theme.css and 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.

…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
JArmandoAnaya force-pushed the refactor/ponytail-docs-site branch from 0d2e8d5 to f347c69 Compare August 12, 2026 14:50
@JArmandoAnaya
JArmandoAnaya merged commit 419dd8c into main Aug 12, 2026
18 checks passed
@JArmandoAnaya
JArmandoAnaya deleted the refactor/ponytail-docs-site branch August 12, 2026 15:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Collapse the duplicated enum tables and XML helpers the persistence layer maintains twice (ponytail audit)

1 participant