[Ewan-yuan]

事故说明

PR #305 因绕过 git 走 REST 传文件时误用 gh api -f content=@file（不做 @file 展开），5 个文件被 12 字节占位符字符串覆盖（共 -3642 行），合并后 dev 构建损坏。

本 PR

从本地已验证的提交 452c752b 恢复 5 个文件的完整内容（PR #304 原实现 + 类型修复：ShapeElement 补 adj?: number | undefined、caption/delta/shadow 的 exactOptionalPropertyTypes 违规修复、mark 断言收窄、测试 "type" in narrow）。

校验

• 上传 blob 的 GitHub 返回 sha 与本地 git hash-object 计算 sha 逐一相等（字节级等价）：415065a711 / 6e2a7ec2d0 / 43b7ea155b / c662bdc5c9 / 8dd2a323ba
• 该内容在本地已通过 CI 同款 8 包 typecheck 全绿

[github-actions]

审查结论：恢复内容已验证正确，无阻塞问题

本 PR 的唯一目的是修复 PR #305 造成的事故（5 个文件被 12 字节占位符覆盖），我做了逐项核验：

恢复正确性（已验证 ✅）

1. dev 基线确实损坏：efd59c39（PR base）上这 5 个文件的内容均为占位符字符串（如 @../blobtmp/elements.ts），dev 构建确实处于损坏状态。
2. 语义等价性：以 --ignore-space-at-eol 对比 f3971c4b（PR #304 合并态，最后已知完好版本）与本 PR，语义差异仅 10 行新增 / 5 行删除，且恰好就是描述中声称的 5 处类型修复——不是重写，是忠实恢复。
3. blob SHA 与描述一致：commit 中 5 个文件的新 blob SHA（415065a7 / 6e2a7ec2 / 43b7ea15 / c662bdc5 / 8dd2a323）与 PR 描述声称的逐一相符。
4. 无残留损坏：git grep blobtmp 在整个 head 树中零命中。
5. 类型修复逐项核验均正确：
   • elements.ts:47 新增 adj?: number | undefined 与既有用法匹配（compile.ts:94/112/123/139/158/175/197、leaf-renderers.ts:244/302、comparison.ts:95/108、pricing-tiers.ts:72/136）；
   • compile.ts:107 的 shadow 条件展开与原三元写法运行时等价；
   • components/index.ts:194 的 as "yes" | "mid" | "no" 等价于原 ComparisonPoint["mark"]（去掉 undefined，且有 truthiness 守卫，非法值由 bad() 抛错拦截，tree.test.ts:1448 有覆盖）；
   • schema.ts:282/346 的 caption/delta 重构：optionalText(undefined, …) 安全返回 undefined（schema.ts:485-488），行为等价，且为 exactOptionalPropertyTypes（tsconfig.json:10 已开启）所必需；
   • tree.test.ts:1439-1440 的 "type" in 收窄仅影响类型层面。

无安全/隐私问题：纯内部布局代码恢复，不涉及网络、密钥或数据流变更。

---

非阻塞发现

1.（中低）5 个文件全部被改为 CRLF 行尾，原文件为 LF

全部 3647 个新增行均带 \r，而 f3971c4b 上的原文件为纯 LF。影响评估：

• 不会挂 CI：本仓库 CI 只跑 pnpm typecheck / test:ci / build，无 lint/format 行尾门禁；tsc 与 vitest 均接受 CRLF；也确认这 5 个文件没有跨行模板字符串，不存在 \r 泄入运行时字符串的风险。
• 但会造成：仓库内混合行尾（无 .gitattributes/.editorconfig 约束）；本次 diff 呈整文件重写（噪音放大约 370 倍）；后续任何人归一化行尾时会再次触发整文件 diff，污染 blame。

建议后续 follow-up：添加 .gitattributes（如 * text=auto）并对这 5 个文件执行 dos2unix / git add --renormalize，单独一个小 PR 处理即可，不阻塞本 PR 合并（当前优先恢复 dev 可构建状态）。

2.（低）PR 描述引用的来源提交 452c752b 在远端不存在

git cat-file -t 452c752b 报 fatal: Not a valid object name，审阅者无法直接复核该出处。我已改用 f3971c4b 直接对比完成验证，结论不受影响，仅提示描述中的可追溯性声明无法被独立验证。