Skip to content

fix(docs): 按清单校正 9 行 peer 陈述,并把断言加宽到整个 Peer Dependencies 区块 (#3750) - #3779

Merged
yinlianghui merged 1 commit into
mainfrom
claude/issue-3750-peer-block-parity
Aug 8, 2026
Merged

fix(docs): 按清单校正 9 行 peer 陈述,并把断言加宽到整个 Peer Dependencies 区块 (#3750)#3779
yinlianghui merged 1 commit into
mainfrom
claude/issue-3750-peer-block-parity

Conversation

@yinlianghui

Copy link
Copy Markdown
Collaborator

Fixes #3750

11 个包 README 的 Peer Dependencies 区块共 28 条 backtick 陈述,#3717 的断言只覆盖 ledger 登记的 12 条 react 行;无人比对的另外 16 条里 9 条与本包清单不符。本 PR 两半一起落:修 9 行,并把断言从 ledger 驱动加宽到区块每一行。

逐行处置(全部在 origin/main = d229dfa7b 复核过,非沿用卡片的 8ad6070)

README 原声明 清单 处置 依据
packages/components 41 tailwindcss ^3.0.0 ^4.2.1 README 收窄到 ^4.2.1 实测真相侧,见下
packages/auth 24 react-dom ^18.0.0 || ^19.0.0 未声明 删行 src 零引用 + 清单未声明
packages/collaboration 23 同上 未声明 删行 同上
packages/i18n 24 同上 未声明 删行 同上
packages/mobile 24 同上 未声明 删行 同上
packages/permissions 23 同上 未声明 删行 同上
packages/plugin-ai 22 @object-ui/core(无区间) 未声明为 peer 删行 见「依据修正」
packages/plugin-designer 28 同上 未声明为 peer 删行 同上
packages/plugin-report 26 同上 未声明为 peer 删行 同上
packages/plugin-designer (无) 声明 react-router-dom ^6.0.0 || ^7.0.0 补行 反向断言新发现,见下

tailwindcss:先测真相侧,结论是清单对

#3690 的方法,不预判哪边错。实测 @object-ui/componentsTailwind 4 专属:

  • postcss.config.js 加载 @tailwindcss/postcss —— 该插件没有 v3 对应物(v3 的 postcss 插件就是 tailwindcss 本身);
  • src/index.css 首行 @import 'tailwindcss',并使用 @theme@custom-variant 两个 v4 专属 at-rule;
  • 整个包没有 tailwind.config.js(v4 的 CSS-first 配置);
  • devDependencies 钉 tailwindcss ^4.3.3,store 里唯一安装版本是 4.3.3;
  • 用装好的 4.3.3 实跑该 postcss 管线:TAILWIND 4 COMPILE OK — bytes: 165326,utilities 正常生成。

即 3.x 不是「未测」而是结构上跑不起来。照 README 装 tailwind 3 的读者会拿到一个装不上的 peer —— 这是本卡里用户今天就会踩的那一行。故收窄 README,不动清单。

依据修正:@object-ui/core 三行不是「src 零引用」

卡片与派发都把这三行归到「src 零引用 + 清单未声明」。前半对不上:三个包都确实 import @object-ui/core(plugin-ai 1 处、plugin-designer 3 处、plugin-report 8 处)。成立的是后半 —— 它是普通 dependencies(workspace:*),随包解析,读者不必自己安装;把它列进 Peer Dependencies 是在让读者去装一个已经随包来的东西。按「清单未声明为 peer」删除,结论不变但依据据实更正。

5 处 react-dom 的零引用主张则逐包复核成立:src 零 react-dom 引用,dependencies/devDependencies 也都没有,清单 peerDependencies 只有 react

门禁侧

正向加宽:断言输入集从「ledger 有条目的行」改为「ledger 解析出的陈述 ∪ 每个 Peer Dependencies 区块的每一条 bullet」,按行去重(12 条 react 行两条路都能到,去重保证一处失真只有一个报告者)。比对数从 12 升到 21,vacuity floor 相应从 10 提到 18,并新增一条「必须真的找到区块」的下限,防止 union 靠 ledger 条目独自撑过 floor。

区块读取刻意不复用 parsePeerStatement:后者对 - @object-ui/core 这种无版本区间的行返回 null(这是它的正确行为),而区块内「有包名、无区间」本身就是要报的结构缺陷 —— 上面三行正是这么藏住的。区块 walker 因此把区间当作可选,缺区间交给断言判。

反向(清单声明的 peer 必须出现在区块里)也加了,但限定在已经写了区块的包,并把取舍写进注释:实测 39 个包里 11 个有区块,没有区块的 28 个里 20 个声明了 peer;全仓版本会为了让测试变绿而逼出 20 个新区块,那是给测试而不是给读者的开销。限定版本的正当性是 README 自己许下的承诺 —— 写了区块就是宣称「这就是全部 peer」。它在正向已经干净的树上找到一处真缺口:plugin-designer 清单声明 react-router-dom peer 而区块从未提及,读者照 README 装完仍会拿到 unmet-peer 警告,故补上该行。

TOOLCHAIN 词界:补上小写包名拼写 tailwindcss\bTailwind\btailwindcss 上没有词边界(后面紧接 css),该行自写下之日起从未被扫到,也就从未进 ledger。实测在 221 文件语料上只新增匹配这一行,已随之登记为 restatement

反向验证(先预判方向,再跑)

六个扰动,方向全部与预判一致;每次跑完 revert,末次全绿:

扰动 预判 实测
A 还原 tailwindcss ^3.0.0 棘轮上行 + 棘轮下行 + peer 断言(3 红) 3 failed / 11 passed ✅
B 清单 react^19.0.0(#3690 形状) 只 peer 断言红,棘轮绿 1 failed / 13 passed ✅
C 还原被删的 react-dom 只 peer 断言红,棘轮绿 1 failed / 13 passed ✅
D 还原无区间的 @object-ui/core 只 peer 断言红,棘轮绿 1 failed / 13 passed ✅
E 删掉新补的 react-router-dom 反向断言红 1 failed / 13 passed ✅
F 只回退 TOOLCHAIN 词表(README 保持正确) 只棘轮下行红,peer 断言保持绿 1 failed / 13 passed ✅

C/D 是加宽本身的证明:这两类在棘轮里恒绿(react-dom 不匹配扫描正则,@object-ui/core 根本没有版本字面量),只有区块路径能看见。实测报文:

packages/auth/README.md:24  react-dom: the README lists it as a peer, but this package's
peerDependencies does not declare react-dom at all - delete the line, or declare the peer …
packages/plugin-ai/README.md:22  @object-ui/core: the README lists it as a peer, but this
package's peerDependencies does not declare @object-ui/core at all - …

F 是派发问题 4 的诚实答案:加宽之后,tailwindcss 那一已由区块断言覆盖,与词表无关 —— 回退词表它照样绿。词表修复剩下的价值是区块之外的 tailwindcss 版本字面量(语料里今天没有,但正是这种休眠死角会回来);它现在由棘轮下行钉住,即 KNOWN_CLAIMS 里那条 ^4.2.1 条目不是摆设。

验证

pnpm vitest run scripts/__tests__            → 21 files / 404 tests passed
pnpm run type-check:scripts                  → exit 0
pnpm run check:control-bytes                 → OK (3715 tracked text files)
pnpm run docs:check-links                    → Links are valid across 7 scan roots
node scripts/check-changeset-presence.mjs    → 10 files changed, 0 under any released package's src/ → 无需 changeset
grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]'     → 10 个改动文件零命中

Changeset:presence 门禁明确判定不欠(它按 src/ 取面,README 与清单都不在其中,本 PR 也没动任何 package.json)。仓库先例一致:近 60 次涉及 packages/*/README.md 的提交里,6 次是纯 README 提交,全部 0 changeset,含本门禁自己注释引用的 PR #3688(36 个 README 的清理)。

越界发现(已另立,未在本 PR 修)

见下方评论。


Generated by Claude Code

11 个包 README 的 Peer Dependencies 区块共 28 条 backtick 陈述,#3717 的断言只
覆盖 ledger 登记的 12 条 `react` 行;无人比对的另外 16 条里有 9 条与本包清单不符。

## 文档侧(9 行)

`packages/components/README.md` 的 `tailwindcss` 按 #3690 的方法先测真相侧,再
决定改哪一边 —— 实测结论是清单对、README 错,故收窄 README:

- `postcss.config.js` 加载 `@tailwindcss/postcss`,该插件没有 v3 对应物;
- `src/index.css` 首行 `@import 'tailwindcss'`,并使用 `@theme` / `@custom-variant`
  两个 v4 专属 at-rule;整个包没有任何 `tailwind.config.js`;
- devDependencies 钉 `tailwindcss ^4.3.3`,store 里唯一安装版本是 4.3.3;
- 用装好的 tailwind 4.3.3 实跑 postcss 管线:编译通过,产出 165326 字节、utilities
  正常生成。

即 3.x 不是"未测",而是结构上跑不起来,`^3.0.0` 会让照 README 装 tailwind 3 的
读者拿到一个装不上的 peer。README 改为 `^4.2.1`(清单原文)。

auth / collaboration / i18n / mobile / permissions 五处声明的 `react-dom` peer:
逐包复核确认 `src` 零 react-dom 引用、dependencies 与 devDependencies 均无
react-dom、清单 peerDependencies 只有 `react` —— README 在让读者去装一个这些包
不需要的东西,删除。

plugin-ai / plugin-designer / plugin-report 三处的 `@object-ui/core`:这三个包
确实用 core,但它是普通 `dependencies`(`workspace:*`)而非 peer,随包解析,读者
不必自己安装;卡片记的"src 零引用"对这三行并不成立,成立的是"清单未声明为 peer"。
按后者删除。

## 门禁侧

断言的输入集从「ledger 有条目的行」加宽为「ledger 解析出的陈述 ∪ 每个
Peer Dependencies 区块的每一条 bullet」,按行去重,一处失真只有一个报告者。
区块读取刻意不复用 `parsePeerStatement`:后者对 `- \`@object-ui/core\`` 这种无
版本区间的行返回 null,而区块内「有包名无区间」本身就是要报的结构缺陷 —— 上面
三行正是这么藏住的。

反向(清单声明的 peer 必须出现在区块里)也加了,但**限定在已经写了区块的包**。
实测:39 个包里 11 个有区块,没有区块的 28 个里 20 个声明了 peer;全仓版本会为了
让测试变绿而逼出 20 个新区块,那是给测试而不是给读者的开销。限定版找到一处真缺口:
plugin-designer 清单声明 `react-router-dom` peer,区块从未提及,读者照 README 装完
仍会拿到 unmet-peer 警告 —— 一并补上该行。

`TOOLCHAIN` 词表补上小写包名拼写 `tailwindcss`:`\bTailwind\b` 在 `tailwindcss`
上没有词边界(后面接着 `css`),该行自写下之日起就没被扫到过。实测在 221 文件语料
上只新增匹配这一行,已随之登记为 `restatement`。注意这半是给**区块之外**的
tailwindcss 版本字面量兜底 —— 区块之内的那一行,加宽后的断言已经覆盖。

Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt

Co-authored-by: Claude <noreply@anthropic.com>
@vercel

vercel Bot commented Aug 8, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated (UTC)
objectui Ignored Ignored Aug 8, 2026 2:40pm

Request Review

@github-actions github-actions Bot added documentation Improvements or additions to documentation package: components plugin tests labels Aug 8, 2026

Copy link
Copy Markdown
Collaborator Author

越界发现(已另立为 unassigned issue,均未在本 PR 修)

两条都是实施本卡时撞见的同族问题,按「越界即停」另立而不是顺手改:

本 PR 新加的区块检测器 PEER_BLOCK_HEADING 刻意锚定为独占一行的 **Peer Dependencies:**,正是为了不把 #3781 那页的散文、以及 troubleshooting.md## 3. Missing Peer Dependencies 标题拖进 walker 然后解析失败 —— 这三条近似行已作为负例钉进测试。所以 #3781明确记录的残留死角,不是本 PR 的疏漏。


Generated by Claude Code

@github-actions

github-actions Bot commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

✅ Console Performance Budget

Metric Value Budget
Main entry (gzip) 28.1 KB 350 KB
Entry file index-sT8JmNjn.js
Status PASS

📦 Bundle Size Report

Package Size Gzipped
app-shell (index.js) 8.66KB 3.13KB
app-shell (runtime-config.js) 7.42KB 2.32KB
app-shell (types.js) 0.01KB 0.04KB
app-shell (urlParams.js) 7.57KB 2.97KB
auth (AuthContext.js) 0.31KB 0.24KB
auth (AuthGuard.js) 1.17KB 0.53KB
auth (AuthProvider.js) 22.10KB 4.37KB
auth (AuthShell.js) 3.49KB 1.40KB
auth (ForgotPasswordForm.js) 12.21KB 3.45KB
auth (LoginForm.js) 18.13KB 5.39KB
auth (PreviewBanner.js) 0.90KB 0.50KB
auth (RegisterForm.js) 6.64KB 2.21KB
auth (SocialSignInButtons.js) 9.60KB 3.89KB
auth (UserMenu.js) 3.40KB 1.22KB
auth (auth-gate-events.js) 1.29KB 0.66KB
auth (authStyles.js) 5.04KB 1.72KB
auth (createAuthClient.js) 35.76KB 9.11KB
auth (createAuthenticatedFetch.js) 4.37KB 1.69KB
auth (index.js) 2.35KB 1.07KB
auth (org-roles.js) 6.66KB 2.78KB
auth (phone-identifier.js) 1.11KB 0.66KB
auth (types.js) 0.59KB 0.35KB
auth (useAuth.js) 4.91KB 0.87KB
auth (useIsWorkspaceAdmin.js) 1.61KB 0.85KB
collaboration (CommentThread.js) 26.07KB 7.56KB
collaboration (LiveCursors.js) 3.17KB 1.27KB
collaboration (PresenceAvatars.js) 6.49KB 2.64KB
collaboration (PresenceProvider.js) 2.79KB 1.13KB
collaboration (index.js) 1.65KB 0.73KB
collaboration (useCollaborationTranslation.js) 6.05KB 2.52KB
collaboration (useCommentSearch.js) 1.98KB 0.88KB
collaboration (useConflictResolution.js) 7.75KB 1.86KB
collaboration (useMentionNotifications.js) 1.81KB 0.68KB
collaboration (usePresence.js) 6.33KB 1.84KB
collaboration (useRealtimeSubscription.js) 7.91KB 2.01KB
components (index.js) 482.22KB 106.21KB
core (index.js) 2.96KB 1.13KB
create-plugin (index.js) 9.85KB 3.18KB
data-objectstack (index.js) 138.22KB 35.46KB
fields (index.js) 230.90KB 56.84KB
i18n (LocalizationContext.js) 1.76KB 0.96KB
i18n (currency.js) 1.22KB 0.64KB
i18n (i18n.js) 4.32KB 1.77KB
i18n (index.js) 2.65KB 1.06KB
i18n (pickLocalized.js) 1.70KB 0.83KB
i18n (provider.js) 9.48KB 3.27KB
i18n (useObjectLabel.js) 27.59KB 6.63KB
i18n (useSafeTranslation.js) 4.52KB 1.96KB
layout (index.js) 38.53KB 10.71KB
mobile (MobileProvider.js) 0.92KB 0.49KB
mobile (ResponsiveContainer.js) 0.94KB 0.38KB
mobile (breakpoints.js) 1.51KB 0.70KB
mobile (createOfflineDataSource.js) 5.61KB 1.74KB
mobile (index.js) 1.50KB 0.62KB
mobile (offlineQueue.js) 3.91KB 1.35KB
mobile (pwa.js) 0.97KB 0.49KB
mobile (serviceWorker.js) 1.48KB 0.62KB
mobile (serviceWorkerSource.js) 3.41KB 1.48KB
mobile (useBreakpoint.js) 1.54KB 0.65KB
mobile (useGesture.js) 6.96KB 1.98KB
mobile (useOfflineSync.js) 1.99KB 0.72KB
mobile (usePullToRefresh.js) 2.53KB 0.85KB
mobile (useResponsive.js) 0.71KB 0.42KB
mobile (useResponsiveConfig.js) 1.36KB 0.63KB
mobile (useSpecGesture.js) 4.32KB 1.64KB
mobile (useTouchTarget.js) 1.01KB 0.54KB
permissions (MePermissionsProvider.js) 8.75KB 3.06KB
permissions (PermissionContext.js) 0.31KB 0.25KB
permissions (PermissionGuard.js) 0.89KB 0.45KB
permissions (PermissionProvider.js) 3.67KB 1.12KB
permissions (evaluator.js) 4.41KB 1.44KB
permissions (index.js) 0.91KB 0.41KB
permissions (store.js) 0.91KB 0.42KB
permissions (useFieldPermissions.js) 1.28KB 0.52KB
permissions (usePermissions.js) 1.55KB 0.71KB
plugin-ai (index.js) 15.71KB 3.79KB
plugin-calendar (index.js) 44.98KB 12.37KB
plugin-charts (index.js) 61.04KB 17.31KB
plugin-chatbot (index.js) 180.09KB 42.72KB
plugin-dashboard (index.js) 117.06KB 30.24KB
plugin-designer (index.js) 210.51KB 42.51KB
plugin-detail (index.js) 232.81KB 57.42KB
plugin-editor (index.js) 2.46KB 1.10KB
plugin-form (index.js) 112.10KB 27.10KB
plugin-gantt (index.js) 162.55KB 39.57KB
plugin-grid (index.js) 187.71KB 49.68KB
plugin-kanban (index.js) 48.30KB 13.28KB
plugin-list (index.js) 105.12KB 25.48KB
plugin-map (index.js) 16.81KB 5.24KB
plugin-markdown (index.js) 13.72KB 4.69KB
plugin-report (index.js) 40.58KB 10.58KB
plugin-timeline (index.js) 25.76KB 7.33KB
plugin-tree (index.js) 8.50KB 2.88KB
plugin-view (index.js) 84.03KB 20.55KB
providers (DataSourceProvider.js) 0.75KB 0.39KB
providers (MetadataProvider.js) 1.37KB 0.59KB
providers (ThemeProvider.js) 1.90KB 0.85KB
providers (UploadProvider.js) 11.71KB 3.53KB
providers (index.js) 0.44KB 0.22KB
providers (types.js) 0.01KB 0.04KB
react-runtime (index.js) 5.67KB 2.37KB
react (LazyPluginLoader.js) 3.77KB 1.33KB
react (SchemaRenderer.js) 19.28KB 6.38KB
react (data-invalidation.js) 5.05KB 2.08KB
react (index.js) 1.02KB 0.55KB
react (spec-input.js) 0.20KB 0.18KB
sdui-parser (codegen.js) 4.09KB 1.74KB
sdui-parser (index.js) 4.47KB 2.03KB
sdui-parser (parse.js) 10.04KB 2.82KB
sdui-parser (types.js) 0.29KB 0.24KB
sdui-parser (validate.js) 4.69KB 1.48KB
types (ai.js) 0.20KB 0.17KB
types (api-types.js) 0.20KB 0.18KB
types (app.js) 2.87KB 0.99KB
types (base.js) 0.20KB 0.18KB
types (blocks.js) 0.20KB 0.18KB
types (complex.js) 0.20KB 0.18KB
types (crud.js) 0.20KB 0.18KB
types (data-display.js) 0.20KB 0.18KB
types (data-protocol.js) 0.20KB 0.19KB
types (data.js) 0.20KB 0.18KB
types (designer.js) 1.87KB 0.85KB
types (disclosure.js) 0.20KB 0.18KB
types (error-code.js) 1.54KB 0.88KB
types (feedback.js) 0.20KB 0.18KB
types (field-types.js) 0.20KB 0.18KB
types (form.js) 0.20KB 0.18KB
types (http-retry.js) 4.32KB 2.02KB
types (index.js) 2.71KB 1.34KB
types (layout.js) 0.20KB 0.18KB
types (managed-by.js) 0.19KB 0.18KB
types (mobile.js) 2.59KB 1.31KB
types (navigation.js) 0.20KB 0.18KB
types (objectql.js) 0.20KB 0.18KB
types (overlay.js) 0.20KB 0.18KB
types (permissions.js) 0.20KB 0.18KB
types (plugin-scope.js) 0.20KB 0.18KB
types (record-components.js) 0.20KB 0.19KB
types (record-semantics.js) 1.28KB 0.67KB
types (registry.js) 0.20KB 0.18KB
types (reports.js) 0.20KB 0.18KB
types (spec-report.js) 5.05KB 1.93KB
types (system-fields.js) 3.33KB 1.54KB
types (theme.js) 0.20KB 0.18KB
types (ui-action.js) 3.40KB 1.71KB
types (views.js) 0.20KB 0.18KB
types (widget.js) 0.20KB 0.18KB

Size Limits

  • ✅ Core packages should be < 50KB gzipped
  • ✅ Component packages should be < 100KB gzipped
  • ⚠️ Plugin packages should be < 150KB gzipped

@yinlianghui
yinlianghui marked this pull request as ready for review August 8, 2026 15:03
@yinlianghui
yinlianghui added this pull request to the merge queue Aug 8, 2026
Merged via the queue into main with commit 00b9451 Aug 8, 2026
19 checks passed
@yinlianghui
yinlianghui deleted the claude/issue-3750-peer-block-parity branch August 8, 2026 15:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation package: components plugin tests

Projects

None yet

2 participants