fix(spec): docs-gen 把 retiredKey() 墓碑渲染成 never,而不是 any (#5606)

[os-zhuang]

Fixes #5606

前提复核(对 origin/main,非引用 issue 正文)

三条都自己量过,前提成立:

1. packages/spec/scripts/lib/format-type.ts 的 formatType() 确实没有 z.never() 分支。

2. 用真实转换器探过墓碑节点,输出向与 io: 'input' 回退向都是同一个形状:

   "heading": { "description": "[REMOVED] …", "not": {} }
   

   无 type / 无 $ref / 无 enum ⇒ 一路落到 return prop.type || 'any'。

3. 页面实例仍在 origin/main:

   • content/docs/references/ui/theme.mdx:130 —— | **fontFamily** | { base?: string; heading?: any; mono?: any } | optional | |,描述列空,两条处方整页不出现。
   • content/docs/references/data/object.mdx:125 与 :199 —— ADR-0049 enforce-or-remove:IndexSchema.type 与 IndexSchema.partial 没有任何 DDL 消费者 #5248 的两处 type?: any(ObjectSchema.indexes / ObjectExtensionSchema.indexes)。

修法

两半都落在 scripts/lib/format-type.ts 内,没有碰 build-docs.ts —— INLINE_KEY_LIMIT 与内联摘要装配本来就住在 format-type.ts 里,所以派单里「可选第二半仅当落点仍在 format-type.ts 时才做」的条件成立(#5837 的 build-docs.ts 读点面未被触及)。

1. { not: {} } → never,置于 formatType() 最前:该节点什么都不接受,后面没有任何分支能比它更具体。准确的 TypeScript(该键 z.input 类型本就是 never),而且不像 any 需要旁边的散文兜底。非空的 not({ not: { type: 'string' } })是普通的否定约束,不匹配,保持原渲染。
2. 内联摘要在计入 INLINE_KEY_LIMIT 之前先剔除墓碑。 摘要格只印前 4 个声明键的 k?: type,压根没有描述列 —— 嵌套的墓碑无处安放处方。退役键已不是可写面,不该占四个槽位之一,更不该把作者必须写的键挤到 … 后面。[spec] 退役 HookContext session.roles —— #4839 双删后零消费方零生产方(ADR-0049) #5050 的「把墓碑挪到 shape 底部」规避办法覆盖不了这一类:ADR-0049 enforce-or-remove:IndexSchema.type 与 IndexSchema.partial 没有任何 DDL 消费者 #5248 把 IndexSchema 退役到只剩 3 个活键,上限为 4 时第一个墓碑在数学上必然进摘要。

渲染变化(单测里钉住的):

位置	之前	之后
Typography.fontFamily	{ base?: string; heading?: any; mono?: any }	{ base?: string }
ObjectSchema.indexes	{ name?: string; fields: string[]; unique?: …; type?: any; … }[]	{ name?: string; fields: string[]; unique?: … }[](无 …,摘要已完整)
Theme.animation 等自有表行的墓碑	类型格 any	类型格 never(描述列 [REMOVED] 处方原样保留)

测试与反向验证

新增 packages/spec/scripts/format-type.test.ts 两个 describe 块,共 8 个 case。

• 全量:pnpm --filter @objectstack/spec test → 325 files / 8316 tests passed。
• 定向:npx vitest run scripts/format-type.test.ts → 1 passed / 27 tests passed。
• pnpm --filter @objectstack/spec typecheck → 绿(check:test-typecheck OK;79 file / 691 error 的既有 debt 账本未增未减)。
• npx eslint 两个改动文件 → 退出码 0。
• node scripts/check-nul-bytes.mjs → OK(5779 个 tracked 文本文件);另按扩面自扫 grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' 三个改动文件,无命中。

反向验证(实测,两半分开做;方向都是常规的「还原缺陷 → 新钉子变红」,因为这些断言的是修复产出的肯定渲染,不是「某个发现消失」):

• 注释掉 isNeverNode 前置返回 → 3 failed | 24 passed,三条红分别报 expected 'any' to be 'never' 与 expected 'any[]' to be 'never[]'。第一块里第 4 个 case 故意保持绿:它断言的是非 never 的渲染(非空 not 的越界护栏),所以是护栏不是死钉。第二块整体保持绿 —— 这是两半彼此独立的诚实信号:把墓碑从摘要里滤掉,与它本来会渲染成什么无关。
• 还原该返回、把摘要改回不过滤的 Object.keys(prop.properties) → 4 failed | 23 passed,四条红全在第二块,报出只做第一半会发布的中间态:{ base?: string; heading?: never; mono?: never }、{ dead1?: never; a: string; dead2?: never; b?: string; … }、{ x?: never; y?: never }。比 any 安全,但仍在拿读者的四个槽位养没人能写的键。

两次实测的数字与红行签名都写进了测试文件的块注释,不用重跑就能读到。

⚠️ 未完成:content/docs/references/** 整体重生成不在本 PR 内

派单要求「只跑 gen:docs,⛔ 不跑 gen:schema」。这条在全新 worktree 里不可执行,实测:

$ pnpm --filter @objectstack/spec gen:docs
❌ packages/spec/json-schema is missing.
   The reference docs are rendered from that tree, and it is a gitignored build
   artifact — nothing in a checkout carries it, and a merge never brings it along.
   Generate it first:
     pnpm --filter @objectstack/spec gen:schema

packages/spec/json-schema/ 被 .gitignore:61 整目录忽略,checkout 里不存在;build-docs.ts 自 #4723 起把「树必须先存在」做成致命前置(b5bdf48 / #6000 今天刚落 main)。也就是说 gen:docs 单跑没有任何路径可以成立。

而 gen:schema 被本座位的权限系统拒绝(两次尝试均被 classifier 拦下)。权限系统的拒绝不是我可以绕的东西 —— 我没有去 shell 出底层脚本、也没有从别的 worktree 拷贝一棵 json-schema 树(后者会正好撞上那道前置守卫要防的「陈旧树假绿」)。

顺带一个副作用值得记下:因为 gen:schema 从未跑过,本分支对三个热点生成物(authorable-surface.json / json-schema.manifest.json / api-surface.json)的改动量是零,git status 全程只有三个文件。派单里那条 ⛔ 的目的其实是完整达成的。

预期红

检查	签名	说明
TypeScript Type Check 作业内的 Check generated reference docs are in sync with the spec(pnpm --filter @objectstack/spec check:docs,.github/workflows/lint.yml:616)	content/docs/references/** 与新渲染器的产出有差异	本次改动自招的红,不是 main 漂移。CI 里 check:authorable-surface 会先生成 json-schema 树,check:docs 再拿它重渲染并逐字节比对;渲染器变了而生成页没跟着变,必红。

更正:初版正文把这条挂在 ESLint 作业下,错了。lint.yml 的 typecheck: job 起自第 402 行,而 check:docs 在第 616 行 —— 落在 typecheck: 里,不是 lint:/ESLint 里。实测确认:失败作业是 TypeScript Type Check,其唯一红步骤就是第 19 步 Check generated reference docs are in sync with the spec;同作业第 13 步 Type check (@objectstack/spec) 绿,第 18 步 check:authorable-surface 绿,其后各步 skipped。

实测红行(第 19 步日志节选):

  ~ content/docs/references/ui/theme.mdx (out of date)
  ~ content/docs/references/data/object.mdx (out of date)
  … 共 17 个 references 页
These files are GENERATED — do not hand-edit them. Regenerate and commit:
  pnpm --filter @objectstack/spec gen:schema && pnpm --filter @objectstack/spec gen:docs

逐字命中本表 —— 这正是上面那节说的、本座位跑不了的那一步。

平台故障(非本 PR 的红)

GitHub Actions 自 2026-08-06 15:42Z 起平台级故障(runner 引导 503)。本 PR 上除 check:docs 外的全部红/取消都是这一签名,已由 PM 验签:

• Failed to resolve action download info. / Service Unavailable(annotation 逐字相同):Auto Label、Build Core、Check PR Size、Console Pin Gate、Flag docs affected by code changes。
• 作业零步骤即被取消(同一故障,连步骤都没起来):ESLint、Console Pin Freshness、Spec property liveness、filter。已对 lint 工作流 rerun_failed_jobs 重投一次(run 31118024384,attempt 2),ESLint 仍是 0 步骤取消,故本 PR 尚无 ESLint 作业的真实判定。本地已单独跑过 npx eslint 两个改动文件(退出码 0);改动不涉及 fake engine / error code / route envelope,家族门的读点面未被触及。
• 绿:Check Changeset、No other open PR may claim the same issue、Dogfood Regression Gate (1/3)、(3/3)、Vercel Preview Comments。

停放期间不为这些红推任何新提交;重投与落地由 PM 驱动。

修法只有一条命令,需要一个 gen:schema 未被拒的座位:

pnpm --filter @objectstack/spec gen:schema   # 只为物化 gitignore 掉的 json-schema/
pnpm --filter @objectstack/spec gen:docs     # 生成页重生成,单独一个 commit

这一步本来就排在解除停放的动作里(见下,「再重跑 gen:docs 整体重生成」),所以现在补一版也会在解除时被重做一次;真正的成本是本 PR 在停放期间带着一条已知红。除上表与上述平台签名之外的任何其它签名都不是预期内的,应当当成真问题处理。

停放

停放:等待 #5837(spec 生成物分片)落地且 spec 座位独占窗口解除;解除后最后一轮 merge origin/main(先 commit merge,再重跑 gen:docs 整体重生成 —— ⛔ 生成页不做文本合并)→ 红清零 → 由 PM 转 ready

关于 changeset

写了真 changeset(.changeset/docs-gen-retired-key-never.md,@objectstack/spec patch),没有走 skip-changeset。理由:本 PR 改的是读者可见的产物。reference 页是升级作者(尤其 AI 作者,ADR-0033)的主要输入面,heading?: any → 键从页面上消失、type?: any → type 从摘要里消失,是升级者会直接撞上的表述变化;而 skip-changeset 的适用面是「test-only / workflow-only / .claude/-only,什么都不发布」。本 PR 不属于那一类。改动虽然只落在 scripts/,但它是生成器,产物是发布面的一部分。Check Changeset 已绿,确认这条判断成立。

对 #5729 的定价(派单要求的回答)

答:变简单(easier),而且是同文件同函数的相邻分支。

字面量加引号发生在 format-type.ts,不在 build-docs.ts:

if (prop.enum) {
  return `Enum<${prop.enum.map((e: any) => `'${e}'`).join(' | ')}>`;
}

if (prop.const !== undefined) {
  return `'${prop.const}'`;
}

两处都无条件套单引号,不看 typeof e / typeof prop.const,所以 z.literal(2) 印成 '2'、数值字面量联合印成字符串型 —— 这就是 #5729。build-docs.ts 里唯一用到 const 的地方是 union options 段的 **Type:** \${variant.properties.type.const}``(反引号,不加单引号),不参与本类缺陷。

对 #5729 的具体影响:

• 落点已锚定:参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729 的修法就是给这两个分支加类型判别(数字 / 布尔 / null 不加引号),不需要再花一轮去找它住在哪。
• 测试载体已就位:format-type.test.ts 现在有现成的 fixture 惯例与断言风格,参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729 直接加一个 describe 块即可。
• 生成页重生成的账已经摊过一次:参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729 同样要整体重生成 content/docs/references/**,与本 PR 完全同一套流程(含上面那条 gen:schema 前置)。
• 唯一的代价是排队:两单改同一个函数,叠在一起 diff 会互相埋掉(这正是 gen:docs 把数组内的 passthrough 对象渲染成 Record<string, any>[],抹掉已声明键 —— #4001 战役每个 open 分类站点都会复发 #4912 / gen:docs 给「元素是联合类型」的数组少了括号,164 处参考页单元格声明了另一种类型(string | number[] ≠ (string | number)[]) #5338 当年分开落的理由),所以 参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729 应当串行排在本单之后,而不是并发。

⛔ 本 PR 不顺手修 #5729 —— 它是独立单,且正文明确要求墓碑这一单不搭车。

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 6, 2026 3:56pm