finding(docs): two doc blocks teach , a helper no package exports — and the #7652 gate cannot see it

[claude]

Found while fixing objectui#7787 (the file-header @example in navigation-overlay.tsx). Measured, not fixed — out of scope for that card, which is fenced to one doc comment and one ledger row.

What is true today (measured on origin/main 445d94c36)

Two doc blocks prescribe, in a copyable @example line, a call to getDataConfig(schema):

file	line	block documents
packages/react/src/hooks/useNavigationOverlay.ts	213	useNavigationOverlay
packages/core/src/utils/record-source.ts	71	resolveRecordSourceObjectName

Both spell it the same way:

const dataConfig = useMemo(() => getDataConfig(schema), [schema]);

getDataConfig is exported by nothing. Measured: grep -rn "export function getDataConfig|export const getDataConfig|export { getDataConfig" packages/ returns zero rows. It survives as a file-local helper in exactly two components — packages/plugin-map/src/ObjectMap.tsx:135 and packages/plugin-grid/src/ObjectGrid.tsx:444 — while packages/plugin-calendar/src/ObjectCalendar.tsx:242 and packages/plugin-tree/src/ObjectTree.tsx:359 obtain the same value from the shared producer objectui#7632 published:

const dataConfig = useMemo(() => resolveRecordSourceConfig(schema), [schema]);

So a reader outside those two plugin files cannot write the line either block teaches: there is no module to import getDataConfig from.

Why it is a finding and not a filed defect

No runtime behaviour changes; both are comments. The cost is the class objectui#7652 measured and objectui#7787 is the last instance of — an example is what the next call site is copied from. This one is a step worse in one respect and better in another: the prescribed line does not compile for any new caller (so a copier notices), but the first thing a copier reaches for when it does not compile is a hand-rolled local copy of the ladder, which is precisely the five-way drift objectui#7632 was filed about.

Why the objectui#7652 gate cannot see it

check-doc-example-shared-reader.mjs needs its condition (a): the @example must call a symbol this repository exports. getDataConfig is exported by nothing, so the pair is never formed and the slot is never compared. The gate is correct to require that — comparing calls to non-exported and third-party names is what produces false positives — but it means this instance is outside its reach by construction, and no other gate reads it either. Confirmed as a reading, not an assumption: the gate runs green over this tree today with an empty ledger.

What a fix probably looks like, and the open question inside it

Pointing both examples at resolveRecordSourceConfig(schema) from @object-ui/core matches what two of the four live sites already do and is importable. But that is not obviously the whole answer, because objectui#7632 (closed) named five local getDataConfig copies and two of them are still here (plugin-map, plugin-grid). Whether those two are deliberate residue or a missed leg is not settled here and is not claimed either way — triage should decide whether the prose is corrected on its own or follows the two remaining components.

Refs: objectui#7787 (the sibling prose instance, fixed by PR #7797) · objectui#7652 (the gate) · objectui#7632 (the shared producer, and the five hand-copies it measured) · objectui#7627 (the shared reader).

---

Generated by Claude Code

[claude]

Claim: PM loop, round 6 — all-opus lane (Clause-② no)
Session: session_01KbJQ1y1J12nZxYzFWhP8Q3
Branch: claude/issue-7798-getdataconfig-doc-example
Worktree: objectui-issue-7798
Domain: domain:ui
File surface: packages/react/src/hooks/useNavigationOverlay.ts（仅 :213 那个文档块）· packages/core/src/utils/record-source.ts（仅 :71 那个文档块）· 本卡自己的 .changeset/*.md. ⛔ Stop on breach: 任何可执行行的改动、任何 plugin-map / plugin-grid 里 getDataConfig 本体的改动、任何对 scripts/check-doc-example-shared-reader.mjs 的改动。Explain in the report.
Container & model: S, mode:subagent, model: opus
Clause-②: no — 两处文档注释。不改变契约接受/拒绝行为，不扩大公开面。⚠️ Void condition: 任何 packages/*/src 下可执行行的改动。
Serial constraints cleared: 无在飞 PR 触碰这两个文件。PR #7797 已合并（9ae1e9d95，本卡正是从它析出的），它改的是 packages/components/src/custom/navigation-overlay.tsx，与本卡两个文件不相交。在飞 #7799（packages/*/src 的 16 个测试）与 #7802（packages/plugin-view/src/__tests__/）都与本卡不相交。

---

缺陷 —— ⚠️ 这次的散文教了一行编译不过的代码

两个文档块在可复制的 @example 里都写着：

const dataConfig = useMemo(() => getDataConfig(schema), [schema]);

文件	行	该块文档化的符号
packages/react/src/hooks/useNavigationOverlay.ts	213	useNavigationOverlay
packages/core/src/utils/record-source.ts	71	resolveRecordSourceObjectName

⭐ getDataConfig 任何包都不导出（卡的实测：grep -rn "export function getDataConfig|export const getDataConfig|export { getDataConfig" packages/ 零行）。它只作为文件局部 helper 活在两处 —— plugin-map/src/ObjectMap.tsx:135 与 plugin-grid/src/ObjectGrid.tsx:444；而 plugin-calendar/src/ObjectCalendar.tsx:242 与 plugin-tree/src/ObjectTree.tsx:359 拿的是 objectui#7632 发布的共享生产者：

const dataConfig = useMemo(() => resolveRecordSourceConfig(schema), [schema]);

⇒ 那两个 plugin 文件之外的读者，根本写不出这两个块教的那一行 —— 没有模块可以 import getDataConfig。

⭐⭐ 这处缺陷按构造对刚落地的那道门不可见

PR #7789 落地的 scripts/check-doc-example-shared-reader.mjs，其条件 (a) 要求示例调用的是仓库导出的符号。getDataConfig 不导出 ⇒ 配对永不形成，门永远看不到它。

⚠️ ⛔ 这不是让你去改那道门。 那是它有意的收窄边界（改宽会引爆假阳性——那道门的席位实测过：更粗的判据在 main 上产生 11 条点名假阳性）。本卡只修散文；「门看不见这一类」这个事实已经记在本卡正文里，那就是它该待的地方。

修法

把两处 @example 指向 resolveRecordSourceConfig(schema)（来自 @object-ui/core，objectui#7632 发布），与 plugin-calendar / plugin-tree 这两个活的调用点一致。

⭐ 形状照抄刚合并的 PR #7797：它做的是同一件事（把 navigation-overlay.tsx 的示例指向共享 reader），并且它的判断依据正是本卡要用的那条 —— 跟着活的调用点走，不跟着另一份文档走。⛔ 不要自己另发明一套解释。

⛔ 四条禁止：

1. ⛔ 不要改 plugin-map / plugin-grid 里的 getDataConfig 本体，也不要"顺手"把它们改成共享生产者 —— 那是运行期改动、是作废条件，且属于另一张卡。若你认为它们该收敛，立卡，不要顺手做。
2. ⛔ 不要导出 getDataConfig 来让文档成立。那是把散文的错误固化成公开面。
3. ⛔ 不要改 scripts/check-doc-example-shared-reader.mjs 去让它能看见这一类。
4. ⛔ 不要动任何可执行行。

验收

• 两处 @example 的 git diff，显示只有注释行变化。⭐ 用双路径证明只改了注释（照 PR docs(cli): state the union-arm property, not the arm count #7788 的做法）：① 所有增删 diff 行都匹配注释前缀；② 用仓库自带的 TypeScript 以 removeComments:true 转译两个修订，两个文件的输出逐字节相同而原文不同。
• pnpm --filter @object-ui/react type-check 与 pnpm --filter @object-ui/core type-check ⇒ 走 turbo（⚠️ type-check dependsOn ^build），报出任务数与 exit code。
• ⚠️ 顺带核一件事并报出来：改完之后 pnpm check:doc-example-readers 应当仍是绿的且台账仍为空（PR docs(components): navigation-overlay's file-header @example reads the shared record source (objectui#7787) #7797 刚把它清空）。⛔ 若它变红，停下上报 —— 那意味着你的新措辞触发了门的四条件，需要判断而不是硬改。
• ⚠️ 另请顺带普查一次：除这两处外，packages/ 里还有没有别的 @example 教 getDataConfig？给出计数与清单（可能为零）。面内的一并修；面外的立卡。

变更集

改动落在发版包的 src/ 下 ⇒ 按 AGENTS.md:161 大概率需要。⛔ 不要凭规则推断：跑 node scripts/check-changeset-presence.mjs，判词原样抄进报告，按判词行事；欠就写空 frontmatter。⛔ 永不写 major。

⚠️ 五个仪器陷阱（今天各席实测）

1. 裸 tsc --noEmit 不是本仓的门 —— turbo type-check dependsOn ^build 且到不了非包目录；⚠️ 有些 project 还要先构建依赖的声明，构建前跑出的 TS2882 是未满足的前提、不是结果，⛔ 不要当结果报。
2. ⛔ 本容器没有「未认证的探测」 —— 代理注入凭据，匿名样子的 POST 是真写入。探通道只用 GET。
3. ⚠️ scripts/__tests__/check-doc-links.test.ts 共享盒上 15s 超时是已知 flake。
4. ⛔ new URL(rel, import.meta.url) 被 Vite 重写成 http://localhost:3000/@fs/…，两种 cwd 下 fileURLToPath 都抛。
5. ⭐ ⛔ 不要用两点式 origin/main..HEAD 报「本 PR 改了几个文件」 —— 并发落地会让它虚报（今天实测 4 vs 真实 2）。以记录的 base 或 GitHub 的 changed_files 为准。

契约复审

Clause-② 是 no ⇒ 不排在契约复审后面。

---

Generated by Claude Code