Docs samples import from subpaths the packages do not export, and nothing checks them

[borisno2]

The problem

docs/content/reference/context-api.md imports getContext from @opensaas/stack-core/context in four places. That subpath is not exported by the package at all, so every one of those samples fails to resolve for a reader who copies it.

Found by a mechanical sweep while fixing the same class of error in the RAG docs on PR #1293. Two more instances there — import { sudo } from '@opensaas/stack-core/context' — were fixed on that PR because they sat inside blocks it had rewritten. These four are pre-existing and in a non-RAG file, so they were left alone rather than widening that diff.

Worth confirming while fixing: sudo is reached as context.sudo() returning a sudo context, not as a free function taking a promise. If context-api.md documents it the other way, that is wrong too.

What to do

Point the samples at the path that genuinely exports getContext, and check the rest of the file's imports the same way.

Worth doing at the same time

Nothing catches this class of error. Markdown is not typechecked, and the docs link-check only validates internal links, so a documentation sample importing from a non-existent subpath builds green and ships. The sweep that found these was a throwaway script parsing every @opensaas/… import in the changed files against the built export surfaces.

That script, made permanent and run over all of docs/content/, would close the gap for good. It is closely related to #1278, which records the same shape of hole for pnpm generate.

Context

• rag_search through nearest(); RAG docs to provisioning; install script deleted #1293 — where the sweep ran and the sibling instances were fixed.
• CI never runs pnpm generate against the third-party field packages, so a broken generate passes green #1278 — CI has no generate coverage for the field packages; same category of missing check.

---

Generated by Claude Code

[borisno2]

Three more, all confirmed present before the field-builder deletion branch, so they are pre-existing and belong here rather than on that PR. Each was checked against the package's real exports map and the exported names in its built type declarations.

Location	Import	Reality
docs/content/how-to/write-a-plugin.md:166	list from @opensaas/stack-core/fields	list is exported from the package root, not /fields. That subpath exports 18 names, all field builders and helpers.
docs/content/how-to/migrate.md:832	getAdminContext from @opensaas/stack-ui/server	The name exists nowhere in the tree. That entry point exports only two types.
CLAUDE.md:1164	getAdminContext from @opensaas/stack-ui/server	Same.

The last one matters more than its line count suggests: CLAUDE.md is the repository's own agent guidance, so an agent following it writes an import of a function that does not exist.

This strengthens the case for the permanent check proposed above. The sweep that found these resolved every @opensaas/* import against the real export surfaces, including following export * transitively — worth building that way rather than as a simple grep.

---

🤖 Generated with Claude Code

[borisno2]

The tool this issue asks for now exists, and it needs wiring into CI.

PR #1318 built it: scripts/check-doc-typescript-blocks.mjs with scripts/doc-blocks/, runnable as pnpm build && pnpm check:doc-ts-blocks. It extracts every fenced TypeScript block from a listed set of files and runs three checks per block:

1. Compiles against the built type declarations.
2. Imports resolve — the prelude is split in two and each block is compiled a second time without the package-export half, so a block that carries its own imports but still leans on a prelude name fails.
3. No shadowing — a block declaring a type whose name matches a real export is compared structurally against the real one, in both directions.

That third check exists because a block redeclaring EmbeddingProvider locally compiled cleanly while documenting a required member as optional. Shadowing makes a compile check blind, which is worth knowing before anyone trusts a green table.

Two things the build of it taught, both worth carrying into the wider rollout:

• Falsify the harness, then falsify it again. Seven controls were written; two did not fire. skipLibCheck was skipping the prelude itself, so a type @opensaas/stack-core does not export became a silent any and hid everything downstream. Fixing that immediately surfaced eight more silent anys — field builders imported from the package root rather than /fields. A harness that cannot fail certifies nothing.
• A wrong classification is worse than none. Nine blocks had been excused as fragments "containing a // ... elision". None contained one. A plausible-looking reason stops anyone looking again, so every exclusion needs its real diagnostic recorded.

What is left: the check runs over a listed set of files, not the whole tree, and it is not wired into CI — it needs pnpm build first, and the lint job does not build the packages, so wiring it means restructuring that workflow.

Until it runs automatically it will rot, which is precisely the failure mode this issue exists to close. Extending its file list to all of docs/content/ and the package READMEs would also subsume #1317, and it is the natural home for a context.db key check (#1304) and a check that documented CLI commands exist (#1314, now closed).

---

🤖 Generated with Claude Code

[borisno2]

Tracking one thing that will need doing when prisma-8 reaches main.

PR #1324 wires the documentation block check into CI, gated to skip pull requests targeting main. That skip is justified today rather than a convenience — verified rather than assumed: all five checked documents exist on main but differ from the integration branch by roughly 919 insertions and 848 deletions, and main does not yet carry the secured-surface exports the shadowing check compares against. Running it there would fail on every entry for reasons that say nothing about the documentation.

The important part is that the skip is no longer silent. Both steps now emit a workflow annotation on every pull request into main, naming the exact gate to flip and pointing here.

What to do when the integration branch lands: flip the gate so the check runs against main, and re-baseline the fixtures against main's documents in the same change. Until that happens the check protects the integration branch only.

Worth stating plainly because it is the failure mode this issue exists to prevent: a check that silently stops running is indistinguishable from a check that passes. The annotation is what keeps that from happening quietly, and this note is the durable half of it.

---

🤖 Generated with Claude Code

[borisno2]

Measured state of whole-tree coverage, from the review of PR #1324 (2026-09-09). The checker pointed at all 34 docs/content/**/*.md files gives 698 blocks, 507 FAIL, 27 tsx UNCHECKED, 245 s. The failures are almost entirely tooling gaps rather than doc defects, and they are what stands between #1324's six-file allowlist and this issue's actual ask. The list, so the extension is one ticket's work rather than rediscovered per page:

• Unmapped @opensaas/* subpaths — about 100 of the 230 TS2307s are real exports (@opensaas/stack-auth/server, @opensaas/stack-ui/*). ci: typecheck the documented TypeScript blocks, with the shadowing check repaired #1324's fix round resolves through each package's own exports map, which should clear this class; re-measure after it lands.
• App-local imports — @/lib/*, @/.opensaas/context, ../opensaas.config. The scratch project needs a stand-in for a generated app: a minimal .opensaas/ bundle emitted from a fixture config, so getContext and Lists.<List>.TypeInfo have real types.
• Third-party imports — next, react, better-auth/plugins, decimal.js, pg. Resolve them from docs/node_modules or a scratch package.json rather than borrowing packages/rag's.
• tsx fences — 45 across the repo (composability.md 12, custom-fields.md 8, packages/ui/README.md 9, theming.md 5). One compiler-option flip (jsx: react-jsx) once React resolves.
• Line-keyed fragments.json — every key is file:line, so a one-paragraph edit near the top of a page orphans or, worse, silently re-targets every entry below it. An in-fence marker (```ts fragment or a comment on the line above) travels with the block and removes the base_ref gate the line keys force.
• Fence info-string attributes — ```ts title="x" is silently skipped today (in ci: typecheck the documented TypeScript blocks, with the shadowing check repaired #1324's fix round).
• CRLF — the closing fence is matched by exact string equality after split('\n'), so a CRLF checkout swallows the rest of the file into the first block. Either normalise line endings on read or add a .gitattributes eol=lf rule for *.md.
• Cost — 219 ts.createProgram builds per run with no host cache, ~43 s for six files, outside turbo so never cache-hit. Program reuse (oldProgram + a cached host for everything outside the scratch dir) and a root turbo task with declared inputs bring a whole-tree run down to seconds and let package-only PRs skip it.
• Doc-local names colliding with exported ones — a correct interface Session { userId: string } (the session is user-defined) is a hard FAIL against core's Session with no way to excuse it. The check needs a per-block way to say "this is a local type, not a redeclaration".

Positive signal from the same run: the shadowing check flagged real contradicting redeclarations of AccessContext, Session, PluginContext, Plugin, ListIndex, BaseFieldConfig and FieldAccess in pages outside the allowlist — the defect class this issue was filed for is present at scale.

#1174 (spec 9's docs rewrite) will add every page it rewrites to files.txt where the tool as merged can compile it, and list here the pages it could not.

---

🤖 Generated with Claude Code