docs: five published READMEs import symbols their packages do not export — 15 TS2305, measured against the built dist

[os-zhuang]

Filed unassigned from the implementation of #5138 (shape 2, the snippet compile gate). Not fixed there — that card builds the gate; this is what the gate's adoption survey found in documents it does not yet cover.

What was measured

scripts/check-doc-snippet-types.mjs (landing on claude/issue-5138-doc-snippet-compile-gate) extracts every fenced ts/tsx block and compiles it --strict against each package's built dist/index.d.ts — the surface a consumer imports, not src. Run once with the coverage ledger emptied, over the whole corpus (460 blocks, 57 documents), filtering for TS2305 / TS2724 / TS2614 only — i.e. "imports a name the module does not export", the #5016 / #5048 defect class:

content/docs/guide/objectos-integration.mdx:80 TS2305: Module '"@objectstack/spec"' has no exported member 'AppManifest'.
content/docs/guide/objectos-integration.mdx:330 TS2305: Module '"@object-ui/data-objectstack"' has no exported member 'useObjectQuery'.
content/docs/guide/objectos-integration.mdx:330 TS2305: Module '"@object-ui/data-objectstack"' has no exported member 'useObjectMutation'.
packages/app-shell/README.md:26 TS2305: Module '"@object-ui/app-shell"' has no exported member 'ObjectRenderer'.
packages/app-shell/README.md:43 TS2305: Module '"@object-ui/app-shell"' has no exported member 'DashboardRenderer'.
packages/components/README.md:73 TS2305: Module '"@object-ui/components"' has no exported member 'registerDefaultRenderers'.
packages/components/README.md:84 TS2305: Module '"@object-ui/components"' has no exported member 'registerDefaultRenderers'.
packages/components/README.md:203 TS2305: Module '"@object-ui/react"' has no exported member 'registerRenderer'.
packages/core/README.md:25 TS2305: Module '"@object-ui/core"' has no exported member 'PageSchema'.
packages/core/README.md:26 TS2305: Module '"@object-ui/core"' has no exported member 'FormSchema'.
packages/core/README.md:27 TS2305: Module '"@object-ui/core"' has no exported member 'InputSchema'.
packages/core/README.md:28 TS2305: Module '"@object-ui/core"' has no exported member 'BaseSchema'.
packages/core/README.md:51 TS2305: Module '"@object-ui/core"' has no exported member 'DataScope'.
packages/core/README.md:97 TS2305: Module '"@object-ui/core"' has no exported member 'defineView'.
packages/react/README.md:166 TS2305: Module '"@object-ui/react"' has no exported member 'useRegistry'.

Why this is worth a card rather than a note

Four of the five files are package READMEs, which sit in each package's published files and therefore ship to npm. A reader who copies one of those imports does not get a degraded render — they get a compile error, which is the same shape #5016 (ReportBuilder, registerDrillHandler, ScheduleConfig) and #5048 carried, in four more packages.

Every one of these has been green under every existing gate the whole time. check-doc-component-types reads type literals, check-doc-links reads links, and neither reads an import.

What each entry needs, and why it is not one batch edit

The three dispositions #5053 established apply here too, and they are not interchangeable:

• the symbol was renamed — re-spell it;
• the symbol lives in a neighbour package — fix the import path (packages/core/README.md's schema types are the likely case: PageSchema / FormSchema / InputSchema / BaseSchema are @object-ui/types vocabulary, and core only imports them);
• the symbol was removed and nothing replaced it — delete the example and teach the real surface, per the subtraction form of plugin-map README teaches an API the package does not implement — every snippet in it renders an empty map #5002 / PR docs(plugin-map): README 按现码重写,不再教包里不存在的那套 API (#5002) #5021.

Deciding which, per name, is the work. The name set must come from the package's export surface (the built dist/index.d.ts), never from a grep of src/ — #5053 measured that ReportScheduleConfig appears twice in src/ and is not exported, so a grep-based check calls it real.

Reproducing

On that branch, with the packages built:

pnpm exec turbo run build $(node scripts/check-doc-snippet-types.mjs --build-filter)
# then, with UNGATED_DOCS emptied, the survey above

All five documents are on the gate's UNGATED_DOCS ledger today, with their measured diagnostic mix as the reason. Fixing a document is what lets its entry be deleted — the ledger can only shrink.

Related

• finding: no gate reads a doc snippet's schema KEYS against the spec — #4823's deferred "second dimension", closed unbuilt #5138 — the gate this came out of; shape 1 (safeParse against the spec schema) remains unruled there
• plugin-report README 教三个不存在的导出:ReportBuilder 组件、registerDrillHandler、ScheduleConfig 组件 #5016 / plugin-report README's export snippets call every real export with the wrong signature — exportAsCSV(data, 'file.csv') passes a filename where the data argument goes #5048 / docs(plugin-report): README 按真实导出面重写三处虚构导出与陈旧幸存清单 #5053 / docs(plugin-report): rewrite README export snippets against the real signatures #5060 — the same defect class, one document at a time
• finding(docs/gate): check-doc-component-types 的扫描面止于代码围栏 —— 八个 PR 新加的「真实 register 键表」全部在门外,且门从不判 namespace 半边 #5106 — a different gap in check-doc-component-types, not addressed by the new gate either

[os-support-ai]

Triage: queued as Bug — published npm pages importing symbols their packages do not export (15 TS2305 measured against built dist) is the same class as the #5002 family here and objectstack#9544/#9532 there. Baseline/gate reconciliation discipline from those cards applies if this repo grows the same checker (#5043 carries the prototype). (Triage seat, session session_019gCKd9EZfQ6MbGTnMHHJvW.)

---

Generated by Claude Code

[os-support-ai]

Claim: PM loop round 6
Session: session_01RV6yuVCxymHYE16PL9vQkE
Branch: claude/issue-5160-readme-nonexported-imports
Worktree: objectui-issue-5160
Domain: repo:objectui (execution seat)
File surface: packages/app-shell/README.md, packages/components/README.md, packages/core/README.md, packages/react/README.md, content/docs/guide/objectos-integration.mdx, and scripts/check-doc-snippet-types.mjs for its UNGATED_DOCS entry text only (see the scoping call below). ⛔ OUT: every package src/ — this card changes documentation, never the export surface; packages/plugin-view (#5097), components/renderers/form (#5201), examples/hello-world (#5236, PR5244 open).
Container & model: L, mode:subagent, model: opus — 15 symbols × three possible dispositions across five documents and five packages, each decided against a built dist/index.d.ts. The volume is not the hard part; the per-name judgement is.
Clause-②: no — documentation and a ledger's reason text. No code, no exports, no contract.
Serial constraints cleared: nothing open touches any of the five documents or scripts/check-doc-snippet-types.mjs. Note PR5251 merged this round and touched content/docs/blocks/forms.mdx — a different file; rebase and re-verify.

Premise — the gate has LANDED since this card was written

The card was measured on the unlanded branch claude/issue-5138-doc-snippet-compile-gate. That gate is now on main: scripts/check-doc-snippet-types.mjs plus its test. So reproduce against main, not against a branch, and re-measure the 15 diagnostics — the card is ~13 hours old and a dozen PRs have landed since.

Take the name set from each package's built dist/index.d.ts, never from a grep of src/. The card gives the reason and it is a measured one: #5053 found ReportScheduleConfig appears twice in src/ and is not exported, so a grep-based check calls a missing symbol real.

⛔ The scoping call the card does not make — read before planning

The card says "Fixing a document is what lets its entry be deleted — the ledger can only shrink." That is not true for four of these five documents, and I checked the ledger to be sure. Each entry lists far more than its TS2305s:

document	ledger entry says
packages/app-shell/README.md	1 parse + 18 undefined-name + TS2305x2
packages/components/README.md	2 undefined-name + TS2305x3
packages/core/README.md	5 undefined-name + TS2305x6 + TS2351x1
content/docs/guide/objectos-integration.mdx	36 parse + 10 undefined-name + 7 unresolved-module + TS2305x3 + TS2339x1

So fixing the TS2305s leaves every one of these still failing on other diagnostics, still ungated, and its entry still required. My ruling, so you are not left guessing:

1. Fix the 15 TS2305s. That is the card and it is worth doing on its own: four of these files ship to npm inside their package's files, so a reader who copies the import gets a compile error.
2. Re-measure each touched document and UPDATE its UNGATED_DOCS reason text to the new diagnostic mix. Leaving TS2305x6 in core's entry when there are zero is exactly the stale-ledger rot that has cost this seat repeatedly today. The entry text is the ledger's honesty.
3. Delete an entry only if that document reaches zero diagnostics — then the gate covers it and the ratchet has actually moved. Do not force this; do not "fix" unrelated parse diagnostics to chase a deletion.
4. ⛔ Never add an entry, never widen one, never relax the gate. Weakening a gate is maintainer-floor.

If none of the five reaches zero, that is a fine outcome — say so plainly. The deliverable is the published pages stop teaching imports that do not exist, not a shrunken ledger.

The three dispositions — per name, not per batch

From #5053, and they are not interchangeable:

• renamed → re-spell it;
• lives in a neighbour package → fix the import path. The card flags the likely cluster: PageSchema / FormSchema / InputSchema / BaseSchema in packages/core/README.md are @object-ui/types vocabulary that core only imports;
• removed with nothing replacing it → delete the example and teach the real surface (the subtraction form of plugin-map README teaches an API the package does not implement — every snippet in it renders an empty map #5002 / PR5021).

Report the disposition you chose for each of the 15 names, with the evidence. A table is fine. That record is what makes the next document in this family cheap, and it is how a reviewer checks you did not simply delete the awkward ones.

Size — partial delivery is explicitly allowed here

This is larger than a normal card. If the re-measure turns up materially more than 15, or a name's disposition needs a ruling you cannot make from the export surface alone (e.g. a symbol that should arguably be exported rather than the doc changed — that is a contract question, not yours), then:

• deliver the names you can settle,
• open the PR with Part of #5160, ⛔ not Fixes #5160, so merging does not silently close the card,
• and report exactly which names are left and why.

A truthful partial beats a rushed whole. ⛔ Do not "fix" a missing export by adding the export.

Verification

• Re-run the gate over the changed documents and show before/after diagnostics per file.
• The gate's own test must stay green — remember scripts/check-doc-snippet-types.mjs has a test at scripts/__tests__/check-doc-snippet-types.test.ts. Running the script is not running its test; that exact gap turned PR5244 red today. Run both.
• Building is required: the gate compiles against built dist, so use pnpm exec turbo run build $(node scripts/check-doc-snippet-types.mjs --build-filter).

Gates

Derive from your diff. scripts/pm/dispatch-gates.mjs is objectstack-only. Expect Doc Snippet Type Check, Internal Docs Link Check, Build Docs, Control Byte Scan. Changeset: run check-changeset-presence.mjs and follow its verdict — READMEs sit inside published packages, so do not assume either way.

⛔ Do not background a long check and end your turn. Narrow and declare the narrowing if the shared verify lock is contended.

Deliver

Draft PR against main, first body line Fixes #5160 or Part of #5160 per the size note above. Push the branch early. Return the JSON report and post it as a comment whose first line is the literal <!-- os-dev-report --> marker.

---

Generated by Claude Code