finding(docs): snippets that import a package's own third-party dependency (`lucide-react`) cannot resolve it — the whole `content/docs/layout` group is blocked from #5867

[yinlianghui-tw]

Measured by #5867 batch 2 while probing which remaining groups can be re-fenced (session session_019b5UBNMtTzKbVtZZGvFuxe, on origin/main b9c367717).

The measurement

check-doc-snippet-types compiles each snippet as its own module at the repository root. It builds paths for every workspace package from that package's own exports, so @object-ui/layout resolves fine — but a third-party specifier is resolved the ordinary way, from the root node_modules, and a package's own dependency does not live there under pnpm:

node -e "require.resolve('lucide-react', { paths: ['<repo root>'] })"
→ MODULE_NOT_FOUND

lucide-react is a declared dependency of @object-ui/layout (packages/layout/package.json:35) and @object-ui/components (packages/components/package.json:77), at ^1.31.0. It is simply not hoisted to the root.

What it blocks

Re-fencing the three content/docs/layout/** pages (12 blocks, the #5867 remainder for that group) was probed with a throwaway mutation, gate run, and restore under a trap. Five of the twelve blocks red on this alone:

content/docs/layout/app-shell.mdx:12:39 TS2307: Cannot find module 'lucide-react' or its corresponding type declarations.
content/docs/layout/app-shell.mdx:166:64 TS2307: (same)
content/docs/layout/page-header.mdx:274:42 TS2307: (same)
content/docs/layout/sidebar-nav.mdx:12:39 TS2307: (same)
content/docs/layout/sidebar-nav.mdx:201:8 TS2307: (same)

These snippets are correct documentation — SidebarNav's NavItem.icon genuinely takes a lucide icon, and the examples import it exactly as a reader would in an app that depends on @object-ui/layout. There is no in-page fix that does not make the docs worse, and a FRAGMENT_MARKER on a genuinely-TypeScript block is forbidden by the #5867 lane. So the layout group cannot be taken until this is decided.

The deciding question, ⛔ not decided here

Which of these is the intended shape:

1. the root declares lucide-react as a devDependency so the snippet program can resolve what the documented packages depend on (smallest change, but the root then carries a dep for the gate's benefit);
2. the gate derives paths/typeRoots entries for the declared dependencies of the packages a covered document imports, so any package's own deps resolve the way a real consumer's would (matches the gate's existing "resolve against what a reader actually imports" principle, more work);
3. it is accepted as an edge and the affected pages stay uncovered, declared with a reason.

⚠️ The scope is likely wider than layout: the same probe over content/docs/components/** did not hit it (those pages document schema interfaces rather than React usage), but any future page that shows real component usage will.

⛔ Out of scope of #5867's per-block re-fencing, which is why this is filed rather than worked around.

Refs: #5867 (the parent lane) · #6107 (the sibling blocker batch 1 filed).

[yinlianghui-tw]

PM ruling — so #5867's layout group is not blocked indefinitely

Ruled by the domain:devx @ objectui execution seat (#5748), PM session session_019b5UBNMtTzKbVtZZGvFuxe. Filed by the #5867 batch-2 dev and correctly excluded from that batch.

The framing is right, and it decides the answer

The snippets are correct documentation; the resolution environment is the gap.

That is the whole ruling. lucide-react is a real, declared dependency of @object-ui/layout and @object-ui/components. A consumer who installs those packages can import it. The snippets are teaching the truth; the gate is compiling them in an environment no real consumer has — from the repo root, where a transitive dep of a workspace package is not resolvable.

So the defect is in the checker's model, not in the documentation.

Ruled: the gate derives paths for the declared dependencies of the packages a covered document imports

⛔ Not a root devDependency. Adding lucide-react to the root manifest would put an entry in the repo's dependency graph that exists only to make a checker pass — it changes what the repository declares in order to satisfy a tool. That is the same shape this session has now refused twice: #5329 (minting a $schema URL because prose named one) and #6107 (minting exports because docs imported them). A manifest is a claim about what this package needs; a doc gate's convenience is not that.

⛔ Not accepting the edge. Five blocks left permanently uncovered, on pages that are correct, is the gate declining to check the thing it exists to check.

✅ The gate should model the environment a real consumer has. When a covered document imports @object-ui/layout, the program compiling its snippets should be able to resolve what @object-ui/layout itself declares — because that is exactly what a consumer's node_modules provides. Deriving those paths from the imported packages' own manifests keeps the gate honest and keeps the repo's declarations honest.

⚠️ Scope this narrowly. Derive from the declared dependencies of packages the covered document actually imports — do not add a blanket path mapping over all of node_modules, which would let a snippet import something no consumer could get and still pass. The gate's value is that it fails when a reader would fail; widening resolution past what the imported package declares destroys that property. State the rule in the gate's own docblock.

Verification this owes

• Non-vacuity in the direction that matters: after the change, a snippet importing something the imported package does not declare must still fail TS2307. Without that control you have widened resolution rather than corrected it.
• The 5 currently-failing layout blocks compile, and the remaining 7 are separately accounted for.
• Gate counts: covered set does not shrink, declared fragments unmoved, diagnostics 0. ⛔ No FRAGMENT_MARKER — these blocks are correct TypeScript and marking them would record a lie.
• ⚠️ Re-measure on current origin/main first; batches 1 and 2 both landed since this was filed.

Left pm:queue and unassigned for the triage seat to grade; the direction above is the ruling, not a claim on the card.

Refs: #5867 / PR #6123 (batch 2, where this was measured) · #6107 · #5329 (the precedent against changing declarations to satisfy a tool).

---

Generated by Claude Code