🎉 🤖 add component registry derived from JSDoc on archieML types#6543
Draft
mlbrgl wants to merge 3 commits into
Draft
🎉 🤖 add component registry derived from JSDoc on archieML types#6543mlbrgl wants to merge 3 commits into
mlbrgl wants to merge 3 commits into
Conversation
Member
Author
This stack of pull requests is managed by Graphite. Learn more about stacking. |
|
All alerts resolved. Learn more about Socket for GitHub. This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored. |
Contributor
|
Quick links (staging server):
Login:
Archive:SVG tester:Number of differences (graphers): 0 ✅ Edited: 2026-05-27 20:29:15 UTC |
10 tasks
|
This PR has had no activity within the last two weeks. It is considered stale and will be closed in 3 days if no further activity is detected. |
Establish a single source of truth for ArchieML component documentation — the TypeScript types themselves. Each archieMLComponents/<Name>.ts now carries JSDoc on its EnrichedBlock<Name> type with a description, When to use / When NOT to use, Variations, and one or more @example blocks in raw ArchieML. devTools/gdocs/generate-components-reference.ts walks every archieMLComponents file via the TS compiler API, extracts the JSDoc, parses each @example through archieToEnriched, and emits two artifacts: - docs/components-reference.generated.md: human-readable reference intended to replace the hand-maintained "Writing OWID Articles" Google Doc. Every example round-trips through the parser at generation time, so drift fails CI (exit 1, listing the broken examples). - docs/components.registry.generated.json: machine-readable bundle for agent consumption (Claude Code skills, future admin component picker). 61 components documented across all files. 49 have full JSDoc + at least one @example drawn from the Gdoc reference; 12 have minimal markers (internal components not covered by the hand-written doc) to be filled in later. Two components — Table and Additional Charts — intentionally have no @example because their content derives from a native Google Docs table / bulleted list that can't be expressed in pure ArchieML text. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Each EnrichedBlock* type now points to a sibling .md sidecar via `@see`, instead of carrying its full author-facing docs in a JSDoc block. The generator now reads those sidecars (using tsgo to walk the OwidEnrichedGdocBlock union for canonical iteration order) and derives example names from the markdown heading immediately above each ` ```archie ` fence. Adds a vitest that asserts every union member has a sidecar, and a CI job that regenerates the reference + registry and fails on drift. Also removes a duplicate EnrichedBlockResearchAndWriting entry from the OwidEnrichedGdocBlock union. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
2 participants
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.
Context
First PR of the claude-cms stack (followed by #6544, gdoc write-back fidelity, and #6545, file-first CMS). It establishes a single source of truth for ArchieML component documentation: the TypeScript types themselves.
archieMLComponents/<Name>.tstype carries a short JSDoc that points via@seeto a sibling.mdsidecar holding the author-facing docs: description, When to use / When NOT to use, Variations, and one or more```archieexample blocks.devTools/gdocs/generate-components-reference.tswalks theOwidEnrichedGdocBlockunion via the TS compiler API (canonical iteration order), reads the sidecars, parses every example througharchieToEnriched, and emits two artifacts:docs/components-reference.generated.md— human-readable reference, intended to replace the hand-maintained "Writing OWID Articles" Google Docdocs/components.registry.generated.json— machine-readable bundle for agent consumption (Claude Code skills, a future admin component picker)Drift can't accumulate silently:
components-reference) regenerates both artifacts and fails ongit diffdevTools/gdocs/sidecars.test.ts) asserts every union member has a sidecarCoverage: 61 components documented. 49 have full docs plus at least one example drawn from the gdoc reference; 12 internal components have minimal markers to be filled in later. Table and Additional Charts intentionally have no example — their content derives from native Google Docs tables/lists that can't be expressed in pure ArchieML text.
Also removes a duplicate
EnrichedBlockResearchAndWritingentry from theOwidEnrichedGdocBlockunion.Testing guidance
yarn generateComponentsReference— should complete without errors and produce no diff indocs/yarn test run devTools/gdocs/sidecars.test.tsdocs/components-reference.generated.mdand spot-check a few components against the "Writing OWID Articles" gdoc🤖 Generated with Claude Code