gen:schema silently drops PageTabsProps since #2967 — references regen would delete real docs

[os-zhuang]

现象

pnpm --filter @objectstack/spec build(gen:schema)日志:

⊘ UI.PageTabsProps: Transforms cannot be represented in JSON Schema (skipped)

#2967(conditional tabs,#2606 的 visibleWhen CEL 谓词)给 PageTabsProps 引入了 .transform,zod-to-json-schema 无法表示,build-schemas.ts 按既有策略静默跳过。后果链:

1. json-schema/ui/PageTabsProps.json 消失(下游任何依赖 JSON Schema 校验/IDE 提示的场景失去该 schema);
2. gen:docs 以 json-schema/ 为输入 → 全量重新生成 content/docs/references/ 会删除 ui/component.mdx 里整个 PageTabsProps 章节及其 import 列表条目——一个真实存在、刚发布的 schema 从公开参考文档消失;
3. 已提交的 references 目前仍含 PageTabsProps(feat(spec): conditional tabs — page:tabs items accept a visibleWhen CEL predicate (#2606) #2967 合并时未 regen),处于「文档比管线正确」的倒挂状态——在修复前请勿全量 regen references。

建议

• 修复:把 transform 改为 JSON-Schema 可表示的形态(z.preprocess/pipe 外移、或为文档/JSON-Schema 提供无 transform 的 source-shape 变体);
• 加固:build-schemas.ts 对「上一次存在、本次消失」的 schema 应响亮失败(棘轮),静默跳过只适用于从未支持过的类型——否则任何人加一个 transform 都会无声地从 JSON Schema 面上撤下一个公开契约,违反 Prime Directive chore: version packages #10(declared ≠ delivered 不宣传的反面:delivered 却悄悄不再 declared)。

复现

pnpm --filter @objectstack/spec build 2>&1 | grep "PageTabsProps"
ls packages/spec/json-schema/ui/ | grep -i tabs   # 空
pnpm --filter @objectstack/spec gen:docs
git diff content/docs/references/ui/component.mdx  # PageTabsProps 章节被删

发现于品牌命名清理的 references 漂移排查(#2963 后续)。当前 references 与 spec 的其余漂移(ADR-0091/0095 时期 7 个文件)已被 #2965/#2967 等合并顺带修复,唯一剩余差异就是本回归。

🤖 Generated with Claude Code

https://claude.ai/code/session_0162o68e5w3bpUBEVRQboUGG