build-docs.ts 用「剥掉 Schema 后缀」推导 import type 示例,类型别名不存在时生成的文档引用无法编译

现象

packages/spec/scripts/build-docs.ts 生成每个 reference 页的 TypeScript Usage 段时,import type { X } 行是从 schema const 名机械剥掉 Schema 后缀推导的:

// scripts/build-docs.ts:461
const typeNames = schemas.map(s => s.name.replace(/Schema$/, '')).join(', ');
// :466
md += `import type { ${typeNames} } from '@objectstack/spec/${category}';\n\n`;

它假设每个 XSchema 都存在且导出了同名推断类型 X。这个假设没有任何 gate 验证:一旦某个 schema 没有配套的 export type X(或别名被删/改名),生成出的文档会引用一个不存在的导出 —— check:docs 依然全绿,因为它只对比「生成器现在的输出」和「已提交的文档」,不验证 import 行能否编译。

触发实例

#4539 处理 shared TransformType 双源行时,首选方案本来是只删除零消费者的类型别名、保留 TransformTypeSchema 不动,结果发现这样会让生成文档持续宣传 import type { TransformType } from '@objectstack/spec/shared'(该导出已不存在,且与 ./data 的同名 enum 混淆)。最终被迫改成整对重命名(FieldMappingTransformSchema / FieldMappingTransform)来绕开生成器的这个假设 —— 结果是对的,但决策被生成器缺陷绑架了。

建议

生成 import 示例时对照真实导出面(api-surface.json 已按 entry 记录了每个名字,或直接解析入口 d.ts),只列真实存在的名字;或者加一个校验步骤:剥后缀推导出的每个类型名必须出现在对应 entry 的导出里,否则 check:docs 变红。机器可读表面不能撒谎(AGENTS.md「Route & surface ownership」#4)—— 文档里的 import 示例正是 AI 编写元数据应用时最常被复制的行。

关联:#4539(触发场景)、#2978(schema 静默下架删文档的老问题,同一层生成器)。

feat(spec)!: resolve the three cross-form dual-source names (objectst…

认领:PM 循环第 4 轮(全量 backlog 加速批次 1/N)
分支:claude/issue-4570-docs-import-surface
Worktree:objectstack-issue-4570
分诊决定(PM 自决):对照真实导出面生成 import 行 + check:docs 校验步骤(推导名必须存在于对应 entry 导出,否则变红)——两者都做,生成正确 + 门禁兜底。

Generated by Claude Code

PM 验收:ACCEPT → PR #4595(已转正并启用 merge-when-ready,CI 全绿自动入队)。

超出任务书的完成度:不止类型侧对照 api-surface.json 真实导出面(kindOf 可判定),还发现并修正了值导入同样是死的(import { Object } / Object.parse(data) 类,258 页 1690 个值名逐一运行时验证);225 个 reference 页更正。兜底棘轮基线「只减不增、新缺口与陈旧条目双向变红、不接 gen 脚本」——正确套用了 #4446 双源基线的设计理由。负控双层实测(单测 13 项 + 端到端复演 #4539 场景变红),改前 150 个 TS2305 → 改后 0。content/docs/releases/ 零触碰。

衍生已分诊:#4592(build-schemas 首次匹配截断 4 个名字)→ 已入队;#4593(150 个 schema 缺 type 别名,三条路)→ 收件箱等维护者定夺。

Generated by Claude Code

fix(objectstack-ai#4570): spell reference-doc import examples from th…

feat(spec)!: 双源 C2 收敛 — MetadataEvent / MetadataBulkRegisterRequest 归…

Navigation Menu

Repository navigation

build-docs.ts 用「剥掉 Schema 后缀」推导 import type 示例,类型别名不存在时生成的文档引用无法编译 #4570

现象

触发实例

建议

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

build-docs.ts 用「剥掉 Schema 后缀」推导 import type 示例,类型别名不存在时生成的文档引用无法编译 #4570

Description

现象

触发实例

建议

Activity

os-zhuang commented on Aug 2, 2026

os-zhuang commented on Aug 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions