feat(docs): CI gate to keep llm-guide.md in sync with token registry - #383
Conversation
Adds scripts/check-llm-guide.js with two checks:
- Hard fail: any --sf-* name in the guide that is not a live token in
token-registry.json (catches renames/deletions immediately).
- Warning: PUBLIC/PUBLIC-ADVANCED knob tokens absent from the guide
(surfaces coverage gaps without blocking CI).
Wires the script into the artifacts-freshness CI job and npm run
check:llm-guide. Fixes five stale token references caught by the new
gate (--sf-color-code-block-{bg,text}, --sf-field-{border,text}-color,
--sf-section-pad-xl-plus). Adds a mandatory "LLM guide sync" section
to CLAUDE.md documenting the qualitative update obligation.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GBbqrooCfW68LAjUMuNnYY
📝 WalkthroughWalkthroughAdds ChangesLLM Guide Token Freshness Check
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ee0fd8c3b7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const liveTokens = new Set( | ||
| registry.tokens.filter((t) => !t.removed).map((t) => t.name), |
There was a problem hiding this comment.
Using token-registry.json as the sole source of live tokens makes the new gate reject supported scoped override hooks that are not catalogued there. For example, core/tokens.css lists --sf-color-code-block-bg, --sf-color-code-block-text, --sf-field-border-color, and --sf-field-text-color as PUBLIC scoped override tokens, and core/base.css/optional/forms.css still consume them, but they are absent from the registry; this already forced their removal from the LLM guide and will block re-documenting those supported APIs. The live set needs to include these non-registered public hooks or the registry generator needs to catalogue them before this hard-fail check runs.
Useful? React with 👍 / 👎.
| const TOKEN_RE = /--sf-[a-z0-9_-]+/g; | ||
| const guideRefs = new Set( | ||
| [...guideText.matchAll(TOKEN_RE)] | ||
| .map((m) => m[0]) | ||
| .filter((name) => !name.endsWith('-')), |
There was a problem hiding this comment.
The extractor only records the first fully prefixed token, so existing guide shorthand such as --sf-animation-fade-in / -fade-out, --sf-grid-min-xs / -s / -m, and --sf-safe-top / -bottom leaves the suffixed tokens out of both the stale-token check and the coverage calculation. If one of those documented shorthand tokens is renamed or removed, CI still passes because the reference is never validated, while the warning list also incorrectly reports several documented knobs as missing.
Useful? React with 👍 / 👎.
The stale check incorrectly excluded --sf-field-border-color, --sf-field-text-color, --sf-color-code-block-bg, and --sf-color-code-block-text — these are real PUBLIC scoped override hooks declared and consumed in core/states.css, optional/forms.css, and core/base.css, but absent from token-registry.json (the registry only covers catalogued tokens, not all framework-level properties). Fix: extend the live token set to also include any --sf-* custom property that appears as a declaration in core/ or optional/ CSS files. This ensures scoped override hooks that haven't yet been added to the registry don't trigger false stale failures. Also re-adds the four scoped override tokens to docs/llm-guide.md with accurate descriptions of their scoping purpose. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GBbqrooCfW68LAjUMuNnYY
2 participants
Summary
scripts/check-llm-guide.js— a two-tier validation script:--sf-*name indocs/llm-guide.mdthat isn't a live token intoken-registry.json(catches renames and deletions — stale guide references break CI immediately)artifacts-freshnessCI job andnpm run check:llm-guide--sf-color-code-block-{bg,text},--sf-field-{border-color,text-color},--sf-section-pad-xl-plusCLAUDE.mddocumenting which changes require a guide update and how to verify locallyTest plan
npm run check:llm-guidepasses locally with exit 0Verify all generated artifactsjob passes🤖 Generated with Claude Code
https://claude.ai/code/session_01GBbqrooCfW68LAjUMuNnYY
Generated by Claude Code
Summary by cubic
Adds a CI gate to keep
docs/llm-guide.mdin sync with the live token set, now defined astoken-registry.jsonplus any--sf-*declarations incore/andoptional/CSS. Blocks stale refs and warns on missing PUBLIC knobs; restores scoped override tokens in the guide.New Features
scripts/check-llm-guide.js: hard-fails token names not found in the union of the registry and CSS-declared tokens; warns on undocumented PUBLIC/PUBLIC-ADVANCED knob tokens.artifacts-freshness; added npm scriptcheck:llm-guide.Migration
docs/llm-guide.md(see “LLM guide sync” inCLAUDE.md).npm run check:llm-guidelocally; CI fails on stale refs.Written for commit a3dd3e4. Summary will update on new commits.
Summary by CodeRabbit
Documentation
Chores