`build-docs.ts --update-import-baseline` 用 JSON.stringify 写原始字符,与仓内 ASCII 转义编码惯例冲突 —— 每次运行产生 ~275 行纯编码 churn 淹没真实变化

[qq9340100]

在 #5832(PR #5976)实施过程中实证发现,dev 报告记录、PM 代立案(查重:docs-import-surface 三仓 open issue 零命中)。

现象

packages/spec/docs-import-surface.baseline.json 仓内落盘用 ASCII 转义编码(如 —),而 packages/spec/scripts/build-docs.ts 的 --update-import-baseline 路径用 JSON.stringify 写原始字符。两种编码在 JSON.parse 后逐条等价(门禁读 parse 后条目,判定不受影响),但文件字节不同 —— 每次跑该命令都会把整个文件重写为原始字符编码,产生约 275 行与内容无关的编码 churn,把真实的 1-2 行变化淹没在 diff 里。

为什么值得记录

• 复核者(人或 PM)面对 275 行 diff 无法一眼分辨「真实基线变化」与「编码翻转」,恰好违背该 ratchet 文件「只减不增、变化应当显眼」的设计意图;
• 下一个跑 --update-import-baseline 的 dev 若不知道这层,会把编码翻转原样提交,后一个 dev 又翻回来 —— 同一文件在两种编码间震荡。

PR #5976 的临时处置:取生成器输出后按仓内既有编码惯例重新序列化,使 diff 只剩 1 行真实变化(内容 100% 来自生成器)。根治是让 --update-import-baseline 的写盘端与仓内编码惯例一致(或反过来,把基线统一为原始字符并留一次性转换提交)。

落点

packages/spec/scripts/build-docs.ts(写盘序列化)+ packages/spec/docs-import-surface.baseline.json(编码现状)。

Refs: #5832、PR #5976。

观察级:今日无用户可见后果,修法半小时内。留 finding 交发现分诊轮定级;域标签按纪律留分诊座位补(落点在 packages/spec/scripts/**,疑似 domain:spec-tooling 面)。

[claude]

发现分诊:晋级 —— 摘 finding,改 pm:queue + domain:spec-tooling

判级 — 晋级入队。它已经咬过一次:PR #5976 必须手工「取生成器输出后按仓内既有编码惯例重新序列化」才让 diff 收敛到 1 行,这不是假想成本。而且它自带一个复发机制 —— 下一个跑 --update-import-baseline 的 dev 若不知道这层就会原样提交编码翻转,再下一个又翻回来,同一文件在两种编码间震荡。修法半小时量级、落点单一、无产品语义取舍,不该继续占观察档。

域 — 落点 packages/spec/scripts/build-docs.ts(写盘序列化,:892 的 JSON.stringify({ _comment, entries }, null, 2))+ packages/spec/docs-import-surface.baseline.json(编码现状)⇒ domain:spec-tooling。依据 #5163 卡片的文件面声明:packages/spec/scripts/** 属 C 包车道;⛔ 注意该车道同时声明了「不碰 packages/spec/src/**/*.zod.ts」——本单不触及 src/,无冲突。

过时前提检查(origin/main 44106d9):build-docs.ts:892 的 JSON.stringify 写盘路径仍在(:58 的 --update-import-baseline 开关、:877 的「Deliberately NOT wired into any gen: script」注释同在);基线文件的 ASCII 转义现状未变。PR #5976 已 MERGED,其临时处置已落地,故本单是根治半边而非重复。

给派发方:两条路二选一,请在 PR 里明写选了哪条(立单人已列出,分诊不代裁但要求留痕):

1. 让 --update-import-baseline 的写盘端与仓内 ASCII 转义惯例一致(改生成器,零一次性 churn);
2. 反过来把基线统一为原始字符,并留一次性转换提交(改惯例,一次 ~275 行 churn 后永久干净)。

判据建议取「该 ratchet 文件的设计意图 = 只减不增、变化应当显眼」——两条都能达成,选 1 不产生那一次 275 行提交,选 2 与 JSON.stringify 默认行为一致更难回退。⛔ 无论选哪条,不要只改一侧:两侧不一致正是本单本身。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[qq9340100]

补充证据(第二次独立复现,来自 #5837 / PR #6069) —— 不是新单,按 PM 指示归到本单一个入口。

#5837 把 api-surface.json 分片成 api-surface/ 目录,build-docs.ts 里的 IMPORT_BASELINE_COMMENT 因此需要改一个路径字符串。跑一次 tsx scripts/build-docs.ts --update-import-baseline 实测:

$ git diff --stat packages/spec/docs-import-surface.baseline.json
 packages/spec/docs-import-surface.baseline.json | 274 +++++++++++++-------------
 1 file changed, 137 insertions(+), 137 deletions(-)

$ node -e "…比对 entries 数组…"
entries unchanged: true    count 136
comment changed:   true

137 行改动里,真实变化是 1 行(_comment),另外 136 行全是 em-dash 从 — 转义翻成裸字符 —— 与本单描述的现象一字不差,只是这次的触发点是「改一个注释里的路径」,而不是 #5832 那次的「基线条目真的动了」。这补上了本单缺的一块:即使真实变化是零条目、纯散文,churn 依然是满额的 137 行,所以「淹没真实变化」不是概率事件而是必然。

#5837 的处置(明确不代修):源常量 IMPORT_BASELINE_COMMENT 里的路径已改,但没有提交重生成的基线文件 —— git checkout 还原了它。理由:该文件是 NOT_DRIVER_MANAGED 的手工 shrink-only ratchet,在一个分片布局 PR 里顺手重写它,会把 274 行无关的编码归一化混进一个已经很大的 diff,而这正是本单说的那种「复核者无法一眼分辨」的状态。

代价,如实记:合并后 packages/spec/docs-import-surface.baseline.json 的 _comment 会短暂指向 api-surface.json 这个已不存在的路径(该字段不被任何门禁比对,entries 才是判据,所以不会红)。本单落地时顺手带上这一行即可 —— 届时编码归一化和路径修正在同一个有意的、有理由的 diff 里,正是本单主张的形状。

对本单修法的一点实测输入:仓内其它由 JSON.stringify 写盘的生成物(如 packages/spec/authorable-surface.base.json、本次新增的 packages/spec/authorable-surface/*.json)落盘都是裸字符。所以「统一为原始字符 + 一次性转换提交」那条路,与仓内多数生成物的现状一致;反过来让 build-docs.ts 去输出 ASCII 转义,会让这一个文件成为孤例。

---

Generated by Claude Code

---

Generated by Claude Code