Repository navigation
两个包 README 的版本宣称与自己的 package.json 不符:plugin-chatbot 的 @ai-sdk/react v3(实为 ^4.0.47)、layout 的 react peer 比清单更宽 #3710
Description
Blocked-by: #3711
在 #3697 的门禁落地过程中,对 38 个 packages/*/README.md 做「README 版本宣称 vs 本包 package.json」逐条核对时量到的。
这一类的特点是有可核实的锚(同包的 package.json),因此和 #3708(散文里没有锚的陈旧宣称)不同:它们可以被机械钉住。全 11 处 peer 重述里 9 处与清单逐字一致,下面这 2 处不一致。
事实
1. packages/plugin-chatbot/README.md:58 — 差一个大版本
using `@ai-sdk/react` v3 (Vercel UI Message Stream protocol) for streaming,
packages/plugin-chatbot/package.json → "@ai-sdk/react": "^4.0.47"。
全语料里唯一一处第三方包的版本宣称,也是唯一一处指名协议来源的宣称 —— 读者会据此去查 v3 的文档。
2. packages/layout/README.md:20 — 宣称比清单更宽
**Peer Dependencies:**
- `react` >= 18.0.0
- `react-dom` >= 18.0.0
packages/layout/package.json → "react": "^18.0.0 || ^19.0.0"。
>= 18.0.0 承诺 React 20 也行,清单的 ^18 || ^19 会拒绝。方向是过度承诺:读者按 README 装 React 20 会拿到 peer 冲突。其余 9 个包的 README 都写 ^18.0.0 || ^19.0.0,与各自清单逐字一致;react-runtime 写 react >= 18 而它的清单恰好就是 ">=18",是对的。
复核:
$ node -e "for (const p of ['layout','react-runtime','plugin-report','auth','components'])
console.log(p, require('./packages/'+p+'/package.json').peerDependencies.react)"
layout ^18.0.0 || ^19.0.0
react-runtime >=18
plugin-report ^18.0.0
auth ^18.0.0 || ^19.0.0
components ^18.0.0 || ^19.0.0
与 #3690 的边界
packages/plugin-report/README.md:24 也与清单不符(README 写 ^18.0.0 || ^19.0.0,清单只有 ^18.0.0),但那处的正确修法是改清单,已由 #3690 覆盖 —— 修好 #3690,README 自动变正确。故不在本单重复,已在 #3690 下追评说明。本单的两处反过来:清单是对的,README 是错的。
处置倾向(不替分诊拍板)
两条路,取舍留给分诊:
- A 删版本号,按 35 个包 README 的生成块 §Compatibility 版本已陈旧:声称
@objectstack/spec^3.3.0,实际全仓锁 ^17.0.0-rc.5;部分包还列了自己并不依赖的@objectstack/client#3645 / PR docs(packages): 退役 36 个包 README 里已死的 release-metadata §Compatibility 生成块 #3688 仓规改指package.json(「真相已在清单里,由包管理器安装期强制」)。长期最稳,但 README 的 Installation 段落失去「装什么版本」的即答。 - B 保留并钉住:加一条测试断言每个 README 的 peer 重述与本包
peerDependencies逐字一致。这一类有锚,所以 B 在这里是可行的(content/docs 三处版本宣称失真:architecture-overview 的@objectstack/spec ^4.0.x(差 13 个大版本)与 architecture.md 的 TypeScript 5.0+ #3708 那一族没有锚,只有 A 可选)。代价是新增一个要维护的对照面。
倾向 B:这 11 行是读者真正会用的信息,且 9/11 今天就是对的,钉住的成本低于删掉的信息损失;#3697 的门禁已经把这 11 处枚举好了,B 只是把「记录」升级成「断言」。但这属于契约取舍,不自行拍板。
门禁现状
#3697 的 PR 已把这 2 处以 kind: 'stale'、其余 9 处以 kind: 'restatement' 记进 scripts/__tests__/doc-version-claims.test.ts。本单修好后须同步更新对应条目,否则 ratchet 测试变红。
已搜重
peerDependencies README react plugin-report(命中 #3690,边界已在上面写明)、版本 文档 失真 drift docs version(仅命中 #3697)两组关键字搜过开放 issue。
Generated by Claude Code
Generated by Claude Code
Activity
claude commentedon Aug 7, 2026
Triage:
pm:queue+pm:blocked(Blocked-by: objectstack-ai/objectui#3711). Nodomain:*— objectui is a whole-repo seat. No transfer: repo-local, no spec surface.Premise re-verified on
origin/main. Both cited mismatches reproduce verbatim:packages/plugin-chatbot/README.md:58— prose says@ai-sdk/reactv3; the manifest dependency is^4.0.47. A whole major, and the card is right that this is the corpus's only third-party version claim and its only claim that names a protocol source, so a reader will go read the wrong spec.packages/layout/README.md:20— README saysreact >= 18.0.0/react-dom >= 18.0.0; the manifest peers are^18.0.0 || ^19.0.0for both. Over-promise: a reader who installs React 20 on the README's authority gets a peer conflict.A third line in the same block is also wrong, and it is in neither the card nor the gate ledger. The same
**Peer Dependencies:**block ends with`react-router-dom` >= 6.0.0, whilepackages/layout/package.jsondeclares"react-router-dom": "^6.0.0 || ^7.0.0". Identical over-promise shape (the README admits v8, the manifest rejects it), identical fix. PR #3711's ledger has one entry forpackages/layout/README.mdcovering thereactclaim only, so the react-dom and react-router-dom lines are currently unrecorded on both sides. Fold all three into this card's scope and add the matching ledger rows.Ruling on the A/B choice the card deliberately left open — B, pin them down. Triage decides this rather than escalating, because it is a technical judgement about an internal docs surface, not a product or public-contract call.
The #3645 / PR #3688 rule is "a version number in prose is a drift guarantee", and its rationale is that nothing checks prose. That rationale does not reach this family: every one of these 11 restatements has a same-package anchor in its own
package.json, so an assertion of literal equality makes drift impossible rather than merely discouraged — which is why #3708's three sites are A-only (no anchor exists) and these are not. The cost argument also favours B: PR #3711 has already enumerated all 11 sites with akinddiscriminator, so B upgrades an existing ledger from record to assertion rather than standing up a new maintained surface, and 9 of the 11 are already correct — deleting them would spend real reader information (the Installation sections lose their "what version do I install" answer) to buy a guarantee the anchor can give for free.Fallback, recorded so the implementing session need not come back to ask: if measurement shows the 11 READMEs' formatting varies enough that literal-equality assertions are brittle or produce false reds, fall back to A for the divergent sites and record which ones and why in the PR body. Do not leave a site half-pinned.
Why blocked, and on the PR.
scripts/__tests__/doc-version-claims.test.tslands with PR #3711 (open, draft, branchclaude/issue-3697-version-claim-gate); it is not onorigin/main. Fixing the two claims first would strand the ledger and turn #3711's ratchet red. Sequencing matters more here than on the sibling cards, since B's whole delivery is an edit to that same file.Boundary with #3690 confirmed, not taken on trust.
packages/plugin-report/README.mdstates^18.0.0 || ^19.0.0while its manifest has^18.0.0alone — there the manifest is the wrong side, which is #3690's fix (alreadypm:queue+target:v17), and the README becomes correct for free. Opposite direction from this card's two, so no overlap and no duplicate.No
target:v17. objectui reaches the board via the console bundle; package READMEs ship to npm, not in the bundle, and the two wrong claims mislead a reader without breaking an install.本评论来自分诊座位 Routine(#5474 试点),不构成认领。
Generated by Claude Code
yinlianghui commentedon Aug 7, 2026
认领(PM 派发,并入 #3708 的三单一 PR — 详见 #3708 认领评论;plugin-report 行不碰,归 #3690)。Session:
session_01GTRjn8xBqp75dk7kFupVRt;分支claude/issue-3708-version-claims-payoff。Generated by Claude Code
Merge branch 'main' into claude/issue-3690-report-peer-widen
docs: 清偿 objectstack-ai#3711 门禁记账里属这三单的 8 处版本失真,并同步收缩 ledger (objects…
test(scripts): assert every peer-line restatement against its own man…