docs(plugin-calendar): 对齐 README 的导入面与包的真实导出面

[yinlianghui]

Fixes#5010

packages/plugin-calendar/README.md 的导入面与包的真实导出面对齐。卡面点了两处漂移,核对过程扫出第三处(同文件同性质,一并修,下面单列)。⛔ 没有为了让 README 变真而新增任何导出。

前提验证(先行,含证伪反查)

卡面断言	复测	结论
calendarComponents 在 src 零命中	grep -rnw calendarComponents packages/plugin-calendar/src → exit 1,无输出	✅ 成立
零命中不是扫描器坏了	反查确定存在的邻近词:grep -rlnw ObjectCalendar packages/plugin-calendar/src → 5 个文件(ObjectCalendar.tsx、CalendarView.tsx、index.tsx、两个 test)	✅ 扫描器正常,零命中是真零命中
CalendarViewSchema 真身在 @object-ui/types	packages/types/src/complex.ts:174 声明,packages/types/src/index.ts:268 导出;本包 src/calendar-view-renderer.tsx:10 只 import,src/index.tsx 无 re-export	✅ 成立

两处漂移都成立,premise_still_valid: true。

编译探针实测 README 在 origin/main 上的原样(tsc 直读源码,非 dist):

c-readme-asis.ts(4,10): error TS2305: Module '"@object-ui/plugin-calendar"' has no exported member 'calendarComponents'.
c-readme-asis.ts(5,15): error TS2724: '"@object-ui/plugin-calendar"' has no exported member named 'CalendarViewSchema'. Did you mean 'CalendarView'?
c-readme-asis.ts(15,3): error TS2322: Type 'string' is not assignable to type 'Date'.
c-readme-asis.ts(16,3): error TS2322: Type 'string' is not assignable to type 'Date'.

一处与卡面小有出入,如实记:CalendarViewSchema 报的是 TS2724(带拼写建议的「无此导出成员」)而非卡面写的 TS2305 —— 同族诊断,不影响判定与修法。后两条 TS2322 就是下面的第三处漂移。

三处漂移:判定与修法(刻意区分,勿混)

#	位置(原行号)	症状	判定	修法
1	:106-112 "Manual Registration"	calendarComponents 不存在 → 照抄拿 undefined,Object.entries(undefined) 抛 TypeError,整节跑不起来	虚构	删虚构节,改教真实注册方式
2	:242	CalendarViewSchema 类型是真的,但属于 @object-ui/types,本包只 import 不 re-export	路径错	改导入路径
3	:242-249(卡面未列)	同一例子里的 CalendarEvent 是本包真导出,但是运行时类型;示例的 ISO 字符串与 CalendarViewSchema.events 要的授权类型对不上	同名撞车(名字真、类型错)	改导入来源

第三处漂移的来历(为什么只改路径不够)

把 #2 的路径改对之后,示例仍然不编译。探针 A(只改 #2 的路径、CalendarEvent 继续从本包导入)实测:

a-pathfix-only.ts(10,3): error TS2322: Type 'string' is not assignable to type 'Date'.
a-pathfix-only.ts(11,3): error TS2322: Type 'string' is not assignable to type 'Date'.
a-pathfix-only.ts(16,12): error TS2322: Type '…/plugin-calendar/src/CalendarView").CalendarEvent'
is not assignable to type '…/types/src/complex").CalendarEvent'.
Types of property 'id' are incompatible.
Type 'string | number' is not assignable to type 'string'.

根因是两个同名类型:

	@object-ui/types(授权 JSON)	@object-ui/plugin-calendar(组件运行时)
id	string	string | number
start	string | Date	Date
end	string | Date(必填)	Date(可选)
description	有	无

CalendarViewSchema.events 要授权型,README 这个例子导的是运行时型。名集合核对看不见这一类(两个名字都是真导出),只有真编译看得见。

修法定向不是猜的:README 自己的 "Calendar Event Structure" 一节记的就是授权型的形状(ISO 字符串 + description),整篇 schema 示例也全用 ISO 字符串。所以两个授权型统一从 @object-ui/types 取,并加一段把两个同名类型并列写清,免得下一个读者(或 IDE 自动导入)再挑错。探针 B(本 PR 的写法)实测 0 error。

同名本身没动 —— 那是契约变更,已另立 #5044 并给出三个方向与推荐。

名集合核对读数(全部自包导入,含多行块)

方法按 #5010 楼上立卡人的方法学备注:不做文本近似。用 TypeScript compiler API 从 src/index.tsx 取 checker.getExportsOfModule 的导出符号集(解析 alias 后再判 value/type —— export { ObjectCalendar } 是 Alias 符号、不带 Value flag,按 alias 判会把每个 re-export 误标成 type),再用跨行正则抓 README 全部 import 语句(单行 + 多行块),剥掉注释后逐名核对。

真实导出面(7 个):

type CalendarEvent value CalendarView
type CalendarViewProps value ObjectCalendar
type ObjectCalendarComponentProps
type ObjectCalendarProps value ObjectCalendarRenderer

修复前:

README 行	形态	导入名	判定
:106	单行	calendarComponents	❌ 虚构
:242	单行	CalendarViewSchema	❌ 路径错 → 真身 @object-ui/types
:242	单行	CalendarEvent	✅ 真(但见第三处漂移:名真、类型错)

修复后(0 处缺陷):

README 行	形态	导入名	判定
:124	多行块	ObjectCalendar / CalendarView / ObjectCalendarRenderer	✅ 真(value ×3)
:130	多行块	ObjectCalendarComponentProps / CalendarViewProps / CalendarEvent	✅ 真(type ×3)
:142	单行	ObjectCalendarRenderer	✅ 真(value)
:279	单行	CalendarViewSchema / CalendarEvent	✅ 真,来自 @object-ui/types

跨包导入顺带核过:ComponentRegistry → @object-ui/core(src/registry/Registry.ts)✅;createObjectStackAdapter → @object-ui/data-objectstack(src/index.ts)✅。

删因(逐节一行)

• 删 ### Manual Registration(原 :103-113) —— 删因:所教的 calendarComponents 导出不存在且从未存在(src 零命中),整节照抄即 TypeError;本包注册纯粹是 import 入口的副作用,没有可遍历的组件表,所以这一节不是「写错了」而是「描述了一个不存在的机制」,无法就地改对,只能删。
  • 补位内容(不是恢复该节,是改教真实机制):新增 ### What the side-effect import registers,列副作用 import 真正 claim 的三个 schema type 及其命名空间键(plugin-calendar:object-calendar、view:calendar、plugin-calendar:calendar-view,均取自 ComponentRegistry.register(...) 实际调用);新增 ### Public exports 列真实导出面;想要自定义注册键的宿主,改教注册已导出的ObjectCalendarRenderer(ComponentRegistry 是 Registry 实例,register(type, component, meta?) 的 meta 可省,两参调用合法)。

除此之外没有删任何一节。

反向验证(docs 形)

预判方向:往名集合核对里塞假名,应当被抓出;并且要专门验证立卡人指出的下限 —— 多行 import 块。

往两个多行块各塞一个假名(calendarComponents、CalendarBogusSchema)后实测:

FABRICATED README:124 calendarComponents → no such export anywhere
FABRICATED README:131 CalendarBogusSchema → no such export anywhere
(2 defective self-package imported name(s))

两个都在多行块里、两个都被抓出 —— 正是单行 grep 看不到的那一类。截读数后已还原,临时改动未进 commit(grep -n "PLANTED|CalendarBogusSchema|calendarComponents" README.md → exit 1;还原后核对读数回到 0 缺陷)。

顺带一记核对器自身的假阳性并已修:第一版没剥行尾 // 注释,多行块里的注释被粘到前一个标识符上,把三个真名报成虚构。这条已写进 #5043。

验证

• 仓根 pnpm exec turbo run type-check --concurrency=2 —— Tasks: 81 successful, 81 total,exit 0(4m4s)。
• node scripts/check-control-bytes.mjs —— OK,扫 4504 个已跟踪文本文件(含本 PR 两个新增/改动文件)。
• grep -naP 控制字节自扫改动文件 —— exit 1,无控制字节;file README.md 报 UTF-8 text(未被当成 binary)。
• node scripts/check-doc-links.mjs —— Links are valid across 13 scan roots.
• node scripts/check-changeset-fixed.mjs + check-changeset-no-major.mjs —— 均 ✅(patch,未声明 major)。
• README 内每个 TypeScript 示例的自包导入均对导出面核验;新增的两段示例(公共导出多行块、自定义注册键)编译探针实测 0 error,保持可照抄运行。

changeset

一文件:.changeset/plugin-calendar-readme-export-surface-5010.md,@object-ui/plugin-calendar: patch。README 在本包 package.json 的 files 里,随 npm 发布,属用户可见。

顺手记录的 finding(未在本 PR 修)

• finding: 没有门禁核对包内 README 的自包导入名 vs 真实导出面 —— #5002 家族 7 个包的漂移全靠人工巡查发现(附已验证的检查器原型) #5043 —— 没有门禁核对包内 README 自包导入名 vs 真实导出面(plugin-map README teaches an API the package does not implement — every snippet in it renders an empty map #5002 家族 7 个包的根因);附本单验证过的检查器原型与两个已踩的坑。
• finding: 两个结构不兼容的 CalendarEvent 同名并存(@object-ui/types 授权型 vs @object-ui/plugin-calendar 运行时型),已造成一处文档示例不可编译 #5044 —— 两个结构不兼容的 CalendarEvent 同名并存(本 PR 第三处漂移的根因);给了三个方向与推荐。
• finding(plugin-calendar): README 的 "Schema API / CalendarView" 块把必填的 events 标成选填,且只列了 CalendarViewSchema 13 个键里的 6 个 #5045 —— 同文件 "Schema API" 块把必填的 events 标成选填,且只列了 13 个键里的 6 个(不同性质,故未夹带)。

---

Generated by Claude Code

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	25.3 KB	350 KB
Entry file	index-rb00miCg.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	9.56KB	3.59KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	8.92KB	3.41KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	25.13KB	5.40KB
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)	40.21KB	10.79KB
auth (createAuthenticatedFetch.js)	6.34KB	2.43KB
auth (index.js)	2.71KB	1.22KB
auth (invitation-status.js)	1.22KB	0.70KB
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)	5.02KB	0.88KB
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)	502.19KB	112.21KB
core (index.js)	4.11KB	1.62KB
create-plugin (index.js)	10.08KB	3.26KB
data-objectstack (index.js)	159.03KB	44.08KB
fields (index.js)	234.25KB	58.48KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.28KB	1.75KB
i18n (index.js)	3.35KB	1.38KB
i18n (pickLocalized.js)	3.69KB	1.73KB
i18n (provider.js)	23.12KB	7.62KB
i18n (useDisplayLocale.js)	2.84KB	1.45KB
i18n (useObjectLabel.js)	27.59KB	6.63KB
i18n (useSafeTranslation.js)	7.77KB	3.13KB
layout (index.js)	39.16KB	10.97KB
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)	9.35KB	3.31KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	4.42KB	1.42KB
permissions (evaluator.js)	5.12KB	1.74KB
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.81KB	0.83KB
plugin-ai (index.js)	15.75KB	3.80KB
plugin-calendar (index.js)	46.62KB	12.83KB
plugin-charts (index.js)	64.75KB	18.37KB
plugin-chatbot (index.js)	181.21KB	43.14KB
plugin-dashboard (index.js)	127.85KB	32.73KB
plugin-designer (index.js)	212.39KB	42.83KB
plugin-detail (index.js)	241.12KB	60.43KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	122.61KB	29.71KB
plugin-gantt (index.js)	164.10KB	39.87KB
plugin-grid (index.js)	197.61KB	53.03KB
plugin-kanban (index.js)	52.72KB	14.54KB
plugin-list (index.js)	111.17KB	26.99KB
plugin-map (index.js)	18.72KB	6.09KB
plugin-markdown (index.js)	13.72KB	4.69KB
plugin-report (index.js)	41.97KB	11.33KB
plugin-timeline (index.js)	26.68KB	7.66KB
plugin-tree (index.js)	8.50KB	2.88KB
plugin-view (index.js)	83.81KB	20.49KB
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.66KB	3.50KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.62KB	2.34KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	27.53KB	9.41KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.28KB	0.68KB
react (schema-input.js)	1.45KB	0.83KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	5.41KB	2.34KB
sdui-parser (index.js)	4.77KB	2.16KB
sdui-parser (input-type.js)	2.84KB	1.40KB
sdui-parser (parse.js)	10.76KB	3.17KB
sdui-parser (provenance.js)	3.66KB	1.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	6.92KB	2.40KB
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 (dashboard-filter-alias.js)	6.23KB	2.74KB
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)	3.05KB	1.52KB
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]

验证回帖:本地实测输出 + CI 终态(jobs 端点交叉验证)

1. 仓根 type-check(本 PR 的真实类型证据)

 Tasks: 81 successful, 81 total
Cached: 32 cached, 81 total
Time: 4m4.027s
[exited with code 0]

命令:flock -w 7200 /tmp/os-heavy-verify.lock -c 'NODE_OPTIONS=--max-old-space-size=4096 pnpm exec turbo run type-check --concurrency=2'(共享容器,按纪律串行化重阶段 + 限堆)。

2. 门禁脚本

✅ check-control-bytes: OK (scanned 4504 tracked text file(s); skipped 85 binary).
Links are valid across 13 scan roots.
✅ All workspace packages are in the changeset fixed group.
✅ No changeset declares a `major` bump.

控制字节自扫(超出门禁扫描面):grep -naP 对改动的两个文件 → exit 1,无控制字节;file README.md → UTF-8 text(未被当成 binary,grep 仍可见)。

check-doc-links 的一个盲区如实记:该脚本明确剥掉 #fragment 再检查(脚本注释:「#fragment … is out of scope, and stripped before the check」),所以本 PR 新增的站内锚点 [Calendar Event Structure](#calendar-event-structure)不在门禁覆盖内,已手工核验:该标题在文件内唯一(第 164 行,count=1,不会被 GitHub 追加 -1 后缀),按 GitHub 的 slug 规则算出的锚点与链接一致 → RESOLVES。

3. CI 终态:19 个 check-run 全部 completed,零 failure

按纪律用 jobs 端点(list_workflow_jobs)交叉验证,未单凭 pulls/:n/check-runs:

workflow	run	jobs 端点读数
CI	32066996239	9 jobs 全 completed —— 8 success + 1 skipped(Test (coverage))
Bundle Analysis	32066996213	1 job success —— 真实跑了 Build packages / Build Console / 性能预算,全绿
Lint / Docs Links / Control Bytes / Doc Component Types / Changeset Guard / Changeset Presence / Skills Paths / Auto Label	—	全 success
Dependabot Auto-merge	32066996370	skipped(与本 PR 无关)

4. 一处需要如实说明的事:CI 的绿不等于跑过测试

jobs 端点比 check-runs 多给出的信息,值得单独点出来,免得后来的人误读这个绿:CI 的 Test (shard 1..4/4)、Type Check、Build & E2E、Build Docs 四个 job 都报 success,但它们的实质步骤全是 skipped —— 每个 job 第 3 步是 Decide whether this change needs a full run / Check for docs changes,对 docs-only 改动短路,后面的 Run tests / Run type-check / Build Console for E2E / Run E2E tests / Build Site 一律 skipped。

也就是说:CI 那枚绿色的 Type Check 徽章并没有真的对本 PR 跑过 type-check。本 PR 的类型证据是上面第 1 节的本地全仓 81/81,不是 CI 徽章。docs-only 大量 path-filter skipped 按纪律计绿,但把它当成「测试跑过了」会是误读,所以在此写明。

唯一对本 PR 真正做了构建的是 Bundle Analysis(全量 build packages + console,全绿)。

---

Generated by Claude Code

[yinlianghui]

PM 验收:ACCEPT(session session_01GTRjn8xBqp75dk7kFupVRt,objectui 分片 PM,批次 22)

实物核验(fetch 分支后按 git merge-base origin/main HEAD 对账):基线恰为 dc9d651a2(批次 22 开批基线),2 files +98/−7 与报告一致,单 commit;提交信息与 diff 的模型标识 grep 双零;content/docs/releases/** 零触碰;改动面就是卡面许可的 README + changeset 两个文件。CI 亲读:CI run 32066996239 九 job 全 completed 零失败(jobs 端点步级时间戳),外围 19 个 check-run 全 completed(17 success + 2 skipped)。

验收要点:

1. 第三处漂移的发现与修法定向是本单的亮点:只改 CalendarViewSchema 路径后示例仍 TS2322 —— CalendarEvent 同名双身(本包运行时型 vs types 授权型)被四个编译探针(C=4 → A=3 → B=0 / D=0 err)钉死,修法由 README 自身文档形状 + 探针共同定向,不是猜的。同文件同性质,卡面明确允许并要求单列 —— 采信,不算夹带。
2. 示例可照抄运行有硬读数:新写的两段示例逐字复制进探针 0 err;不是「看起来对」。
3. 方法学正面命中立卡人指出的下限:名集合核对用 compiler API 取导出面、覆盖多行 import 块;反向验证特意把两个假名埋进多行块,全部被抓出(正是单行 grep 的盲区);过程中还修掉了核对器自身一个假阳性并把坑写进 finding: 没有门禁核对包内 README 的自包导入名 vs 真实导出面 —— #5002 家族 7 个包的漂移全靠人工巡查发现(附已验证的检查器原型) #5043 —— 工具自证,合格。
4. CI 读数诚实:dev 主动指出 docs-only 下 Type Check 徽章的实质步骤全部 path-filter 短路,类型证据是本地全仓 81/81 与 Bundle Analysis 的真实构建 —— 这是对「绿 ≠ 跑过」的正确读法,记入案头供后续 docs-only 单引用。
5. ⛔ 未新增任何导出(包括没有顺手 re-export CalendarViewSchema)—— 契约零扩张,与认领钉子一致。

派生物:#5043(README 自包导入无门禁,含检查器原型与两个已踩坑)、#5044(CalendarEvent 同名双身,契约题待裁)、#5045(同文件 Schema API 节的键断言漂移)均按 finding 入池、无 pm:queue —— 待分诊轮,处置正确。

转 ready 并挂 auto-merge(squash)。

---

Generated by Claude Code