docs(packages): make the three nested package READMEs compile, and retire their UNGATED_DOCS rows - #9521
Merged
Conversation
…tire their UNGATED_DOCS rows
objectui#7308 brought the nested `packages/**` READMEs into `check:doc-snippets`'
scan surface ledger-first, writing three `UNGATED_DOCS` rows rather than leaving
the pages outside the walk. This pays that debt down. The census was re-derived
on this branch's base with the gate's own analyzer before any edit, the rows
temporarily lifted, and every figure the rows recorded still held: 20 blocks, 13
failing (3 syntax-phase, 10 semantic), 37 diagnostics, split across the three
pages exactly as written.
The one reader-visible defect is on `packages/core/src/adapters/README.md`. Its
custom-adapter template declared `implements DataSource<T>` while omitting
`getObjectSchema`, which the interface requires (TS2420), and wrote
`// Your implementation` as the whole body of six methods annotated non-`void`
(TS2355 x6). A reader who copied it got a class that does not satisfy the
interface it claims. The template now implements all six REQUIRED members and
throws from each unimplemented body, so the reader's class type-checks at every
step of being filled in. The page's two other blocks were excerpts naming a
value the prose introduces; each now declares it.
`packages/types/src/zod/README.md` had two `{ ... }` elisions TypeScript reads as
a spread with no operand, six excerpts continuing an earlier block's imports, one
fence holding a before-and-after pair that declared the same two names twice, and
a shape sketch fenced as TypeScript. All four classes are repaired in place; the
sketch is re-fenced as an unhighlighted block, which takes it out of the ts/tsx
population.
`packages/components/src/__tests__/README.md` is the single declared fragment.
Both of its specifiers were measured refused in this program before the marker
was written: `vitest` is this gate's own ROOT-DECLARED control specifier, so the
row's first suggested remedy produces a bound failure by construction, and
`./test-utils` is TS2307 because every block compiles at the repository root
while that helper is suite-local and unshipped. The block now carries the imports
a file in that directory really writes, which is what the page owed its reader.
Nothing about the gate's strictness moved, and no row was deleted to clear the
ledger. The four objectui#7856 card-2 records below them are untouched.
Verification: `pnpm check:doc-snippets` exits 0 over 249 documents, 670 of 670
compiled blocks judged, 0 failed, with the sentinel at TS2305, the positive
control at 0, and both bound controls at TS2307 in the same run.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VGeMu3p6qEFWR6K6GGLaW
github-actions
Bot
added
documentation
Contributor
✅ Console Performance Budget
The eager closure is every chunk the entry reaches through static imports — what the browser fetches and parses before the app renders. The entry chunk on its own is a small fraction of it. 📦 Bundle Size Report
Size Limits
|
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.
Fixes #9412
Pays down all three
UNGATED_DOCSrows objectui#7308 opened for the nestedpackages/**READMEs. No row was deleted to clear the ledger and nothing aboutthe gate's strictness moved: two pages leave by compiling, one block leaves by a
FRAGMENT_MARKERcarrying a written reason, and the four objectui#7856 card-2records beneath them are byte-for-byte untouched.
The census, re-derived first
Re-derived on this branch's base
8196b10631with the gate's own analyzer, thethree rows temporarily lifted —
analyze()for the population,compileSnippets()for the phases — over the closure the gate's own
--build-filternames (35/35turbo tasks successful). Every figure the rows recorded on
9ba7e9c3still held,per page and per diagnostic code:
packages/components/src/__tests__/README.mdpackages/core/src/adapters/README.mdpackages/types/src/zod/README.md20 blocks, 13 failing, 37 diagnostics. In that same run the sentinel produced
TS2305, the positive control 0, and both bound controls TS2307, so those are
readings from a program demonstrably able to report non-zero.
The defect, not the hygiene
packages/core/src/adapters/README.mdfence 239 — the custom-adapter template —declared
implements DataSourcewith the generic parameter while omittinggetObjectSchema, which that interface REQUIRES (TS2420), and wrote// Your implementationas the whole body of six methods annotatednon-
void(TS2355 x6). A reader who copied it got a class that does not satisfythe interface it claims.
Read off the built
packages/types/dist/data.d.ts, that interface has exactlysix required members —
find,findOne,create,update,delete,getObjectSchema— and every other member is optional. The template now carriesall six, and each unimplemented body throws rather than falling off the end, so
the reader's class type-checks at every step of being filled in. Two signatures
were also brought back onto the declared ones:
findOnegained its thirdparameter and
bulk's operation argument is now the declared union rather thanstring. The page's other two failing blocks were excerpts naming a value theprose introduces; each now declares it.
The page that is worth its size — and one correction to why
packages/types/src/zod/README.md, four separable repairs:TypeScript reads as a spread with no operand; both are real initialisers now;
so
ButtonSchemaandbuttonwere each declared twice in one module. Splitinto the two blocks it was really holding, each of which compiles;
now, against the built
dist/*.d.ts, with adeclare conststand-in onlywhere the value is genuinely the reader's own (
userInput,internalConfig,registry);optionality markers written on keys — and is re-fenced as an unhighlighted
block, which takes it out of the ts/tsx population this gate collects. That
page sits below a package root, so it is outside
check:doc-fences' walk bythe coupling pin's own subtraction; that gate is green either way.
@hookform/resolvers/zodwas left alone as a bug and handled as the bound it is:the block imports only what
@object-ui/typesdeclares, and stands the tworeact-hook-form bindings in with
declare, the waypackages/layout/README.mdalready does for its router peers.
rather than carried forward. The retired row said
packages/types"lists thewhole of
src/in its manifestfiles", so this page ships inside the npmtarball. It does not. That manifest's
filesisdist,README.md,CHANGELOG.md,LICENSE, andnpm pack --dry-run --jsonrun in that packagereports 134 tarball entries, zero of them under
src/, with exactly one README —the package-root one. Same answer for
@object-ui/components(216 entries) and@object-ui/core(208). Control in the same command: the identical filter overdist/returns 130, 212 and 204 entries respectively, so the filter does returnnon-zero when there is something to find. The page was still worth clearing, on
the reason every other row gives — it is a page a reader copies from — but a
later card should not plan around it shipping.
The one declared fragment, and why it is not the cheap way out
packages/components/src/__tests__/README.mdholds one block: the suite's"Adding New Tests" pattern. Both routes to compiling it were MEASURED red in this
program before the marker was written:
vitest— the row's own first suggested remedy — produces a[bound]failureby construction, because
vitestIS this gate's ROOT-DECLARED controlspecifier: the only thing that declares it is this repository's own root
manifest, which is not a claim about anything a reader installs;
./test-utilsproduces TS2307, because every block is compiled at therepository root while that helper is suite-local and unshipped
(
@object-ui/componentslistsdistinfiles, anddist/holds notest-utils).The row anticipated exactly this and named the marker as its alternative. The
block now imports both specifiers anyway, because they are the ones a file in
that directory really writes and the page previously taught neither — a
declare conststand-in here would have taught a spelling nobody should copy.The marker costs no coverage: the block imports no documented package surface at
all, so there is nothing underneath it that compiling would have checked.
Verification
pnpm check:doc-snippets— exit 0 at3c5e89cfaf:Ablation, run from the committed tree at
3c5e89cfaf, both legs. DeletinggetObjectSchemafrom the repaired template: the edit was proven on disk first(the anchor's
grep -cwent 1 to 0 and the blob hash moved off the HEAD blob),then the gate returned exit 1 with exactly
TS2420 ... Property 'getObjectSchema' is missing, atpackages/core/src/adapters/README.md:256:14. Restore leg:git checkout HEAD --on that path put the blob hash back to the HEAD blob byte-for-byte,
git diff HEADis empty, and the gate returned to exit 0 with 670 of 670 judged and 0 failed. So
this page's green is a measurement, not an absence.
Other gates, all exit 0:
check:doc-types,check:doc-fences,check:readme-exports,check:doc-examples,check:doc-example-ids,scripts/check-doc-links.mjs,check-changeset-presence,check-changeset-no-major,check:changeset-claims,check-governed-queue-guard --testover all five changed paths (not governed).Tests:
scripts/(158 files, 4646 tests),packages/core+packages/types(342 files, 7567 tests),
packages/components+packages/data-objectstack(341 files, 3568 tests) — all passing.
type-check:scriptsexits 0, andtsc --listFilesconfirms the edited test file is inside that program.Targeted lint rather than the repository-wide scan, declared: the two lintable
files this diff touches were linted with
eslint --no-inline-config --format json,2 files, 0 errors, 0 warnings. The narrowing is safe to read because
eslint.config.jsconfigures no type-aware linting at all — it names noparserOptions.projectand noprojectService— so nothing in this diff can movethe verdict on a file it did not touch. The repository-wide run stays CI's.
Two pins in
scripts/__tests__/check-doc-snippet-types.test.tsasserted thethree rows EXIST, so they INVERTED with the debt rather than relaxing: one now
asserts no nested README is ledgered and that all of them are covered, keeping
verbatim the half that was never about the debt; the other keeps the row-shape
requirement live for any future nested row and is made non-vacuous by exercising
the shape checker against a conforming row and a deficient one, since the
population it used to loop over is now empty.
A changeset is present with EMPTY frontmatter — declared as releasing nothing,
which the tarball evidence above supports.
Generated by Claude Code