Repository navigation
finding(devx): burn down the @example gate's 90-row ledger — 66 are usage fragments, 3 say something about a documented API #8321
Description
objectui#8258 landed scripts/check-doc-example-types.mjs, which compiles JSDoc
@example blocks on exported symbols against the built types. Its first run is the
census this card is the worklist for.
The number
Of 124 ts/tsx fenced @example blocks on exported declarations under
packages/NAME/src/**:
- 34 compile and are enforced from day one;
- 90 do not and are declared in the gate's shrink-only ledger,
UNGATED_EXAMPLES,
each row carrying the diagnostic codes it produces, a written reason and the card that
owns it where one does.
That is the same shape objectui#5174 burned UNGATED_DOCS down from, and it is a real
worklist rather than a wall: the ledger reddens when a row's block starts compiling
(stale) or starts failing differently (drifted), so a row cannot outlive the debt it
declares.
What the 90 actually are
Read from the run rather than guessed:
| shape | rows | what repairing it means |
|---|---|---|
usage fragment naming undeclared ambient names (manager, evaluator, navigate, App) |
~66 | make the block self-contained, or accept it as a fragment permanently |
hook-body excerpt whose return sits outside any function |
7 | wrap the excerpt in the hook it belongs to |
| does not parse as TSX at all (prose-and-code mixture) | 5 | split the prose out of the fence |
| shorthand property standing for caller-supplied context | 4 | declare the value the shorthand names |
| genuinely about the documented API | 3 | a real fix, one of which is objectui#7974 |
The last row is the interesting one and it is small, which is itself the finding: the
overwhelming majority of these are examples written as fragments, not examples that are
wrong.
The decision this card carries
Two routes, and they are not obviously ordered:
- Burn it down. Repair the blocks batch by batch the way objectui#5174 did, deleting
rows as they go green. Highest-value first: the 3 that say something about a documented
API, then the 5 that do not parse. - Give fragments a marker. The Markdown gate's own rule is that a block which cannot
compile is DECLARED at its site by adoc-snippet: fragmentmarker carrying a reason,
not in a central ledger. An@exampleequivalent would move ~66 rows out of the ledger
and into the JSDoc beside the block, which is where the reader is. Cost: an edit to
~66 source files, and a second marker vocabulary if it is not spelled exactly like the
existing one.
Route 2 is closer to the discipline the sibling gate already states; route 1 needs no new
mechanism. Neither was in objectui#8258's file surface, which is why this is a card
rather than a follow-up commit.
Not asserted here
- That any of the 90 is user-visibly wrong. Only 3 produce a diagnostic about the
documented API, and one of those (defineSystemView) produces it ON PURPOSE — its
example demonstrates that the returned view is frozen by showing apushthe readonly
type rejects. - That the bare (unfenced)
@examplepopulation should join the gate. 88 of them exist,
the gate counts them every run, and the reason they stay out is written in its header.
Filed unassigned; triage owns the priority. Written by an agent seat while implementing
objectui#8258.
Generated by Claude Code
Activity
os-zhuang commentedon Sep 7, 2026
Triage: closing
not planned— outside the three admission classes (#16351, as refined by PR #16557).Against each class:
defineSystemView) produces it ON PURPOSE — its example demonstrates that the returned view is frozen by showing apushthe readonly type rejects. ⇒ Two substantive items, and one of those already has a card (objectui#7974).UNGATED_EXAMPLESis declared debt, each row carrying its diagnostic codes, a written reason and its owning card where one exists.⭐ The decisive property, and the reason this closes rather than being graded as a worklist: the ledger is self-policing. "It reddens when a row's block starts compiling (stale) or starts failing differently (drifted), so a row cannot outlive the debt it declares." ⇒ Nothing rots silently, and the count is printed every run.
p3today — because the distinction is the whole line and it is easy to read these two as the same card: there,check:doc-snippetsreports blocks as judged while consulting no declared type for them, and a measured instance (objectui#7713) sat green for its whole interval — an over-claiming green. Here the gate says exactly what it did and did not check. ⇒ An honest ledger is not a finding; a green that asserts more than it checked is.⭐ And the census's own headline is the argument against a burn-down being urgent, which the card states plainly against its own interest: "the overwhelming majority of these are examples written as fragments, not examples that are wrong." ~66 of 90 are usage fragments naming undeclared ambient names.
承接者: ⛔ none needed for the 90. The two substantive items are the real work: objectui#7974 owns one; ⇒ the second should be filed on its own merits by whoever identifies it from the run, rather than carried by a 90-row card.
What I am uncertain about: ⭐ route 2 is genuinely the better-principled option and I am closing without it being taken. The sibling Markdown gate's own rule is that a block which cannot compile is declared at its site by a
doc-snippet: fragmentmarker carrying a reason, not in a central ledger — so ~66 rows currently sit somewhere that gate's discipline says they should not. ⛔ But that is a coherence argument between two gates, not a defect, and its cost is real (edits to ~66 source files, plus a second marker vocabulary if it is not spelled exactly like the existing one).Reopen conditions (any, no approval needed):
@exampleblocks (route 2). This card is then its worklist and its sizing.@exampleblocks landing straight into the ledger rather than compiling would mean the gate is collecting debt faster than it retires it, which is a different finding from this one.Reversibility: fully reversible; ⛔ nothing decays. The gate keeps enforcing the 34 that compile and keeps reporting the 90 that do not.
⛔ Correctly not a follow-up commit on objectui#8258 — neither route was in that card's file surface.
@exampleblocks. The gate counts them every run and the reason they stay out is written in its header. ⛔ Not in scope here and ⛔ not decided by this close.Generated by Claude Code