Repository navigation
docs: list every component in the README, and guard that it stays that way - #78
Merged
Merged
Conversation
…t way The package README is the npm page, and it had rotted all the way through: it listed 18 of 61 exports and sold a sixty-component library as sixteen. Table, Toast, Sidebar, Combobox, Command, Field, Busy and the entire date family — 43 components in total — were not named anywhere in the file. That surface is also the only one a search engine indexes for the package, so an incomplete README was both a documentation bug and a discovery bug. `check-docs-coverage` already guards the registry, the docs pages and the agent skill. The one surface a person actually lands on had no guard at all, which is why nobody noticed. - All 60 components now appear, grouped exactly as the docs site groups them, with `.*` marking the namespace compositions — the single/namespace split is the thing consumers and LLMs get wrong most often. - `scripts/check-readme-coverage.mjs` fails when an export is missing from that table, and separately when the stated count disagrees with the exports. Both halves proven: removing `Table.*` reports it by name, and moving the count to 61 reports the mismatch. Wired into `pnpm package`, so it runs before publish. - `apps/docs/README.md` was still the untouched `create-svelte` scaffold for its first 38 lines, burying the visual-regression documentation underneath. It now describes the app, what is generated from what, and its guards. - The root README's repo tree never listed `apps/example/`. - The roadmap said the render guard covers 65 pages; it covers 67.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
7 tasks done
This branch was successfully deployed
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
1 participant
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.
What & why
The package README is the npm page, and it listed 18 of 61 exports. A sixty-component library was selling itself as sixteen.
Table,Toast,Sidebar,Combobox,Command,Select,Tabs,Field,Busyand the whole date family — 43 components — were not named anywhere in the file.That surface is also the only one indexed for the package, so an incomplete README was a documentation bug and a discovery bug.
check-docs-coveragealready guards the registry, the docs pages and the agent skill. The one surface a person actually lands on had no guard at all — which is exactly why it rotted unnoticed.Review path
Start at
packages/sve-ui/scripts/check-readme-coverage.mjs. It is deliberately the same shape ascheck-docs-coverage.mjs: check that the prose exists, keep aNOT_IN_TABLEmap where every exclusion carries a reason, and say something useful when it fails.Then
packages/sve-ui/README.md— the component table it enforces.Intentionally out of scope: generating the README section from the registry. This repo's stated position is that the reasoning in documentation is the valuable half and does not generate; the guard checks completeness and leaves the prose hand-written.
apps/example/README.mdwas audited and left alone — it is current and accurate.Changes
packages/sve-ui/README.md.*marking namespacespackages/sve-ui/scripts/check-readme-coverage.mjspackages/sve-ui/package.jsonpnpm package— it runs before publishapps/docs/README.mdcreate-sveltescaffold with a real READMEREADME.mdapps/example/ROADMAP.mdThe guard, proven to fail
Per this repo's rule that a guard nobody has seen fail is not a guard:
Why the namespace split is marked
Dialog.*versusButtonis the single thing consumers and LLMs get wrong most often — it is called out in the agent skill for that reason. The table now carries it, so the README answers the question without a round trip to the docs site.Test plan
pnpm build— the package guard chain now runs six checks;check-readme-coveragereports60 components, all listed in the READMEpnpm lint && pnpm checkgreen;pnpm format:checkcleanturbo run test --force— 644 tests across 72 filespnpm --filter docs check:render— 67 pages unchangedapps/docs/README.mdverified to exist (gen:props:check,check:render,check:render:update,gen:og,test:visual,render-baseline.json)Checklist
pnpm test)pnpm lint && pnpm check && pnpm buildall green