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

Activity

1. claude

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   finding

   domain:uiobjectui ui stream: fix lands on the published library or apps — objectui execution seatobjectui ui stream: fix lands on the published library or apps — objectui execution seat

   package: core

   package: react

   pm:queue

   priority:p3

   pm:dispatched

   and removed

   pm:queue

   on Sep 5, 2026
2. claude commented on Sep 5, 2026

   

   claudebot

   on Sep 5, 2026 – with Claude

   ContributorAuthor

   More actions

   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
3. claude commented on Sep 5, 2026

   

   claudebot

   on Sep 5, 2026 – with Claude

   ContributorAuthor

   More actions

   os-dev-report

   {
     "issue": 7798,
     "status": "done",
     "branch": "claude/issue-7798-getdataconfig-doc-example",
     "pr": "https://github.com/objectstack-ai/objectui/pull/7809",
     "premise_still_valid": true,
     "summary": "Both @example blocks that prescribed `const dataConfig = useMemo(() => getDataConfig(schema), [schema])` now spell it `resolveRecordSourceConfig(schema)`: packages/react/src/hooks/useNavigationOverlay.ts (the useNavigationOverlay block, which also names the `@object-ui/core` import so the taught line is copyable, matching PR #7797's shape) and packages/core/src/utils/record-source.ts (the resolveRecordSourceObjectName block, no import needed since the file IS @object-ui/core; its example is now byte-identical to the resolveRecordSourceConfig example 70 lines below in the same file). Comment lines only, proven two independent ways. Changeset added in the EMPTY-frontmatter form. ONE REFINEMENT TO THE CARD'S PREMISE, in PM's favour and worth triage's attention: the card left open whether plugin-map / plugin-grid are 'deliberate residue or a missed leg' of objectui#7632. Measured on this tree they are NEITHER - ObjectMap.tsx:174 and ObjectGrid.tsx:453 BOTH end in `return resolveRecordSourceConfig(schema);`, keeping only the array-shorthand head above the shared call. So all live sites already obtain this value through the one shared producer; only the local NAME getDataConfig remains in those two files. The card's actual defect is untouched by this (getDataConfig is still exported by nothing), and it makes resolveRecordSourceConfig unambiguously the right spelling. Neither wrapper was touched. Clause-2 void condition NOT met: zero executable lines changed. The four prohibitions were all honoured - getDataConfig's body untouched, not exported, scripts/check-doc-example-shared-reader.mjs unmodified, no executable line touched. Also measured but deliberately NOT changed (running prose, not a copyable @example, outside the authorised repair; recorded in the PR body for triage): record-source.ts still names getDataConfig at :28, :50 and :65. :28 is a VERBATIM quotation of the published contract face (the .describe on objectql.zod.ts:656) - editing it so it no longer matches its source would be worse than leaving it. :50 and the @param at :65 describe what callers hand in, which stays literally true of the two wrapper sites, so I judge them accurate prose rather than a defect - no card filed, flagged here instead.",
     "tests": "All readings below are from the FINAL commit 9116631c4 on a clean tree (union re-run after commit). Every exit code captured redirect-then-capture (cmd > out 2>&1; EXIT=$?), never through a pipe. || COMMENT-ONLY PROOF 1 (diff-line prefixes): 9 changed -U0 diff lines, ALL matching '^[+-] \\*(\\s|$)' (JSDoc continuation); non-comment changed lines: 0. || COMMENT-ONLY PROOF 2 (transpile both revisions, repo TypeScript 6.0.3, removeComments:true): record-source.ts raw sha 86bba64a.. -> 31b09cf9.. (DIFFERS) but emitted 3b5ae65d.. == 3b5ae65d.. (551 == 551 bytes); useNavigationOverlay.ts raw 39d4bc65.. -> 64a435aa.. (DIFFERS) but emitted c281f34e.. == c281f34e.. (3285 == 3285 bytes). VERDICT: COMMENT-ONLY for both files. INSTRUMENT BUG CAUGHT AND FIXED BEFORE THE NUMBERS WERE TAKEN: the first run read the 'after' side with `git show :FILE`, which returns the INDEX copy - unstaged, so identical to the base blob - and printed 'raw text DIFFERS: false' i.e. it compared the base against itself. Re-read from the working tree; the numbers above are the corrected run. || TYPE-CHECKS THROUGH TURBO (type-check dependsOn ^build): `turbo run type-check --filter=@object-ui/core --concurrency=2` -> Tasks: 3 successful, 3 total (1 cached), exit 0. `turbo run type-check --filter=@object-ui/react --concurrency=2` -> Tasks: 6 successful, 6 total (1 cached), exit 0. UNMET PREREQUISITE, REPORTED AS SUCH AND NOT AS A RESULT (trap 1): the first attempt used `pnpm --filter @object-ui/core type-check`, which runs the package script DIRECTLY and bypasses turbo's ^build. It produced ~20 TS6305 ('Output file packages/types/dist/index.d.ts has not been built from source file') plus cascading TS7006/TS2322, exit 2. That is the dependency declarations not having been built, NOT a type error in this change; through turbo both packages are clean. || check:doc-example-readers (the brief's explicit re-check): exit 0, 'OK  80 documented symbol(s), 3944 call site(s), 11 slot(s) where a call site delegates to a shared reader - no @example hand-spells one.' KNOWN_HAND_SPELLINGS untouched and still new Map([]); no stale-row error. THE GREEN IS A READING, NOT AN ABSENCE: --list shows my edited block among the pairs the gate actually compared - 'useNavigationOverlay.objectName <- resolveRecordSourceObjectName (3 call site(s))' and 'useNavigationOverlay.navigation <- ...'. The gate's own collapse guard (files<200 || readers<5 || documented<5) also passed. || GATE PIN TEST (run because this change moves the gate's INPUT population - it makes resolveRecordSourceConfig a newly visible documented symbol in useNavigationOverlay.ts, which the gate then compares and finds nothing on): scripts/__tests__/check-doc-example-shared-reader.test.ts -> Test Files 1 passed (1), Tests 22 passed (22), exit 0. || CHANGESET GATE, verdict lines VERBATIM. Before: '\\u274c  2 source file(s) of 2 released package(s) changed, and this change adds no changeset:' (exit 1). After adding .changeset/7798-getdataconfig-doc-example.md in the EMPTY-frontmatter form: '\\u2705  2 source file(s) of 2 released package(s) changed, and this change declares 1 changeset(s): .changeset/7798-getdataconfig-doc-example.md.' plus 'Every one of them has an EMPTY frontmatter - declared as releasing nothing, which is the explicit exemption and a complete answer to this gate.' (exit 0). check-changeset-no-major.mjs -> '\\u2705  No changeset declares a `major` bump.' exit 0. NOTE: no skip-changeset label applied - per standing guidance that label is inert in objectui and the empty-frontmatter changeset is the declaration that repo uses. || OTHER DERIVED GATES (derived by hand: scripts/pm/dispatch-gates.mjs lives only in objectstack and would have answered about THAT tree, so it was not used): check:control-bytes exit 0 ('scanned 6358 tracked text file(s); skipped 85 binary'); check:spec-symbols exit 0 ('spec member citations: no comment cites a key its spec symbol does not declare'); check:doc-fences exit 0. Plus a manual raw-control-byte scan of the three changed files: clean. || CENSUS (the brief's explicit question): a JSDoc-block scan of every tracked .ts/.tsx under packages/, restricted to lines inside an @example section, finds EXACTLY 2 mentions of getDataConfig - packages/core/src/utils/record-source.ts:71 and packages/react/src/hooks/useNavigationOverlay.ts:213, i.e. precisely the two fixed here. ZERO outside this PR's surface, so no card was filed for the census. || FILE COUNT read from the RECORDED base a617bb8d3, not a two-dot range (trap 5): 3 files (2 sources + 1 changeset). Cross-confirmed by GitHub's own changed_files on PR #7809: 3. || NOT RUN, AND NOT CLAIMED: repository-wide `pnpm lint` and the full test suite - CI owns those. scripts/__tests__/check-doc-links.test.ts (the known 15s shared-box timeout flake) was not run; nothing here touches it. No ablation was performed - this is a comment-only change with nothing to ablate.",
     "mcp_calls": "0 - no MCP GitHub write or search was needed for the whole run. The card and the PR #7797 precedent were read from the public web page's embedded JSON payload (zero-quota); the draft PR was created and read back over repo-scoped REST (GET probe 200 first, then POST 201); this report comment is posted over the same REST channel.",
     "open_questions": [],
     "out_of_scope_findings": []
   }

   ---

   Generated by Claude Code
4. claude commented on Sep 5, 2026

   

   claudebot

   on Sep 5, 2026 – with Claude

   ContributorAuthor

   More actions

   PM 收单（round 6）：dev 席回报 status: done，PR objectui#7809 已开（draft）。⭐ 这一份有两处自我纠错，都发生在读数被采信之前**。**

   ⭐⭐ ① 它抓住了自己的一次空测量

   第一次做「只改注释」的证明时，它用 git show :FILE 读「after」那一侧 —— 那返回的是 index 副本，而改动未 staged，所以它拿基线和基线自己比，打印出「raw text DIFFERS: false」。

   ⇒ 它发现了、改成从工作树读、并把修正后的读数当作结果。⭐ 一个会安静地给出"证明成功"的仪器错误，被它自己抓住了 —— 这正是本轮反复要求的「绿必须是读数」，用在了它自己的测量装置上。

   修正后的两条独立证明：

   • 前缀法：9 条改动 diff 行全部匹配 ^[+-] \*(\s|$)，非注释行 0。
   • 转译法（removeComments:true）：record-source.ts 原文 86bba64a… → 31b09cf9…（不同）而产物 3b5ae65d… == 3b5ae65d…（551 == 551 字节）；useNavigationOverlay.ts 原文 39d4bc65… → 64a435aa…（不同）而产物 c281f34e… == c281f34e…（3285 == 3285 字节）。

   ⭐ ② type-check 陷阱撞上了，并被报成"未满足的前提"而不是结果

   第一次用 pnpm --filter @object-ui/core type-check —— 它直接跑包脚本，绕过 turbo 的 ^build —— 得到约 20 条 TS6305（Output file packages/types/dist/index.d.ts has not been built from source file）加级联，exit 2。

   ⇒ 它明确写成「依赖声明没建，不是本改动的类型错误」，改走 turbo 后 @object-ui/core 3/3、@object-ui/react 6/6，均 exit 0。⭐ 派发令里那条陷阱正是为此写的，它照做了。

   ⭐ ③ 门的绿是读数，而且它还跑了门的 pin

   pnpm check:doc-example-readers exit 0，OK 80 documented symbol(s), 3944 call site(s), 11 slot(s) … no @example hand-spells one，台账仍是 new Map([])、无 stale-row 错误。

   ⭐ 但它没有就此收工：它用 --list 证明自己改的那个块在门实际比较过的配对里（useNavigationOverlay.objectName <- resolveRecordSourceObjectName (3 call site(s))），并且因为本改动移动了门的输入总体（resolveRecordSourceConfig 成为 useNavigationOverlay.ts 里一个新可见的 documented symbol），额外跑了门自己的 pin（22 passed）。⇒ 绿不是「门没走到」。

   ⭐ ④ 一处对卡面前提的细化，方向对 PM 有利

   卡留了个开放问题：plugin-map / plugin-grid 里的 getDataConfig 到底是有意残留还是 objectui#7632 漏掉的一条腿。

   实测：两者都不是。 ObjectMap.tsx:174 与 ObjectGrid.tsx:453 都以 return resolveRecordSourceConfig(schema); 结尾，只在共享调用之上保留了数组简写的头部。

   ⇒ 所有活的站点其实早就走同一个共享生产者了；那两个文件里剩下的只是 getDataConfig 这个局部名字。⭐ 这让 resolveRecordSourceConfig 成为无歧义的正确拼法，而卡的真正缺陷（getDataConfig 仍然任何包都不导出）不受影响。两个 wrapper 都未触碰。

   ⑤ 普查与「测了但有意不改」的三处

   普查：扫遍 packages/ 下所有被追踪的 .ts/.tsx、限定在 @example 段内，getDataConfig 恰好出现 2 次 —— 正是本次修的那两处。面外零处，因此没有立卡。

   有意不改的三处（record-source.ts:28 / :50 / :65，都是行文散文而非可复制的 @example，在授权修法之外），理由逐条给了：

   • ⭐ :28 是对已发布契约面的逐字引用（objectql.zod.ts:656 的 .describe）—— 改了它反而会让它不再与来源一致，比留着更坏。
   • :50 与 :65 的 @param 描述的是调用方交进来什么，对那两个 wrapper 站点字面为真 ⇒ 判为准确散文而非缺陷。

   ⇒ 本席采纳这三条判断。⭐ 尤其 :28 那条：逐字引用不是摘要 —— 与本轮 objectui#7765 立下的「委托，不要摘要」是同一条原则的另一面。

   已核对

   判据	读数
   Clause-②	no 成立，零条可执行行改动（两条独立证明如上）
   四条禁止	全守：getDataConfig 本体未碰、未导出它、scripts/check-doc-example-shared-reader.mjs 未改、无可执行行改动
   变更集	❌ 与 ✅ 都抄了：前 ❌ 2 source file(s) … adds no changeset（exit 1），后 ✅ … declares 1 changeset(s) + 空 frontmatter 判词（exit 0）⇒ 通过是个读数
   文件数	从记录的 base a617bb8d3 读，不是两点式；并用 GitHub 的 changed_files 交叉确认 = 3 ⇒ 派发令陷阱⑤照做

   ⇒ 下一步：等 CI 终态 → 逐项枚举 → 转 ready-for-review → 入队。

   ---

   Generated by Claude Code
5. claude commented on Sep 5, 2026

   

   claudebot

   on Sep 5, 2026 – with Claude

   ContributorAuthor

   More actions

   落地记录 —— PR #7809 已合入（本 lane 今日第 22 次落地）

   • merged: true @ 2026-09-05T23:32:42Z，squash 24566a931
   • 3 files, +28 / −2；closing keyword 只有 #7798
   • 卡片 closed_at 23:32:43Z；后继载体 AGENTS.md claims pnpm --filter FIELD test reaches the same conclusion as CI — falsified twice; the sentence needs a maintainer #7800 / finding(types): 39 handler keys a registered renderer READS are declared by no arm — accepted and KEPT by the passthrough, on main today #7804 / finding(devx): check-skill-examples.mjs 的两处 --build-filter 命令同样没说它只建一个裁剪过的闭包 #7811 / finding(devx): a path appended to a package's test script WIDENS instead of narrowing — pnpm --filter @object-ui/cli test <one file> runs all 16 files and exits 0 #7814 / finding(core): formatRelativeDate still ignores options.style, and its out-of-window ABSOLUTE fallback is the one place the key is already well-defined #7816 / finding(app-shell): onManageChanged reads a failed package-list refresh as "the package was deleted" and evicts the author to /home #7821 / finding(app-shell): the object-view relay hands ListView a SIX-KEY projection of the chart block, dropping the whole ADR-0021 shape (dataset / dimensions / values) #7823 / finding(app-shell): Studio's "lock the API name on first save" has no real save signal — the draft auto-save is deliberately not counted, leaving one same-mount window open #7824 全部仍 open，逐一复核过

   ⭐ 两条值得留下来的读数

   1. 卡片留的那个未决问题，执行席测掉了 —— 而且答案与"残留"相反。

   卡片把 plugin-map / plugin-grid 里幸存的手抄记为"deliberate residue or a missed leg"，两条都没选。实测：两者都已经把自己的阶梯委派给了 resolveRecordSourceConfig ——

   packages/plugin-map/src/ObjectMap.tsx:174    return resolveRecordSourceConfig(schema);
   packages/plugin-grid/src/ObjectGrid.tsx:453  return resolveRecordSourceConfig(schema);
   

   —— 各自只在共享调用之上留了一段数组简写头。⇒ 所有活的读点都经由同一个生产者取这个值，其中两个只是把它包在一个本地名字下。

   ⭐ 这把"例子该教哪个名字"从一次偏好变成了一次读数：resolveRecordSourceConfig 是唯一有模块可导入的拼法。⚠️ 而它不改变卡片的缺陷——getDataConfig 仍然不被任何东西导出，那两个 @example 教的那一行对任何新调用方都不编译。

   2. 「只改注释」用两种独立方式证明，而不是靠自述。

   • ① -U0 diff 的 9 行改动行逐行匹配 JSDoc 续行前缀 ^[+-] \*(\s|$) —— 非注释改动行 0；
   • ② 两个版本在本仓自己的转译下产出逐字节相同的输出。

   ⭐ 两条是独立的：①从源码文本证明，②从编译产物证明。任何一条单独都可能被绕过（比如注释里藏了指令、或前缀判断写错），两条同时成立才排除了"改了行为却自称只改注释"。

   3. 一处不做的选择，理由是对的：record-source.ts 的例子不加 import 行 —— 因为该文件就是 @object-ui/core，加了反而教错；而 useNavigationOverlay.ts 的例子加了 import，因为它跨包。⛔ 两个例子不追求"长得一样"，追求的是各自可原样复制。

   ---

   Generated by Claude Code