finding(scripts): check-readme-exports.test.ts reds on a HALF-built tree — and another gate’s own printed build command is what produces one

[claude]

Found while working objectui#5174 batch 9 (PR #7458). Filed unassigned and NOT fixed there — that card is scoped to shrinking UNGATED_DOCS, and this is a different gate's test.

What

Two cases in scripts/__tests__/check-readme-exports.test.ts branch on the build state of the tree:

const off = scan(repoRoot, { excerpts: {} });
const built = off.census.packagesUnbuilt === 0;

and, as the first one's own comment says, are "written to hold built and unbuilt". A half-built tree is a third state neither branch describes, and in it both cases fail:

FAIL scripts/__tests__/check-readme-exports.test.ts >
 the PARTIAL_EXCERPTS ledger, as it stands in this repository >
 hides ONLY omissions, and the tree says so in BOTH build states
 AssertionError: expected false to be true

FAIL scripts/__tests__/check-readme-exports.test.ts >
 repo state — assertions that hold whether or not the tree is built >
 finds no fabricated or wrong-path import when built, and refuses to pass when not
 AssertionError: expected +0 to be 3

With packagesUnbuilt non-zero the else leg runs and asserts every finding is unjudgeable-type; but with most packages built the findings are stale-omission instead, so the leg written for an unbuilt tree is judging a mostly-built one.

Why this is worth a card rather than a shrug

The half-built tree is not exotic — it is what you get by following another gate's own printed instruction. check-doc-snippet-types.mjs prints, on an unbuilt tree:

 pnpm exec turbo run build $(node scripts/check-doc-snippet-types.mjs --build-filter) --concurrency=2

That filter is scoped by design to the packages the covered documents import — 26 of them today. It leaves @object-ui/plugin-ai and @object-ui/plugin-tree unbuilt, which is exactly packagesUnbuilt !== 0 with everything else present. So the ordinary path of "run the doc gate, then run the tests that read it" lands squarely in the untested third state.

Neither assertion message names the cause. expected +0 to be 3 gives a reader nothing to search for, and the case titles both promise the opposite ("in BOTH build states", "whether or not the tree is built"), so the natural first reading is that the diff under test broke something. Measured cost here: one round, spent building plugin-tree to move the tree into a state the suite recognises — after which it is green, 489/489.

Reachability, honestly

Nothing a user hits, and not reachable in CI: pnpm test never builds, so CI takes the unbuilt leg cleanly, and a built CI job takes the other one. The cost is entirely agent/contributor time, and it is paid by whoever next edits a README or a doc gate and runs the suite after building only what a gate told them to build.

Direction, not a mandate

Either make the branch three-way and assert what a partially built tree should mean, or have the two assertions fail with a message that names census.packagesUnbuilt so the reader learns the state they are in rather than inferring a defect in their own diff. The second is small and would have turned this into a ten-second read.

Related: objectui#7306 (which landed this suite), objectui#6214 (the regression its ledger leg pins), objectui#5174 (where it was found).

---

Generated by Claude Code