SpineWallpaper/tools/checks/README.md

tools/checks/ — 验收套件

跑一遍就相当于"这次改动没把东西弄坏"的全部证据。它原来是散在 .scratch/ 里的， 而 .scratch/ 按 AGENTS.md 是问题与规格的存放处——这些脚本不是某条 issue 的产物， issue 关掉之后还要一直跑，所以搬到了这里。

---

怎么跑

它们的前置条件不一样，不能一条命令全跑完。按下面三组来：

① 不需要服务器

pnpm check                                     # 类型 + 构建 + 语法 + 路径 + 产物自包含 + 游戏合集文案归属
pnpm build sim                                 # 下面几项要 sim 产物
node tools/checks/test-sim-gate.mts            # 门禁真的会拦（往页面注入四种外部依赖）
node tools/checks/test-inline-guard.mts        # 内联 </script 守卫真的会拦
node tools/checks/test-transform-module.mts    # 模块合成的 export 改写
node tools/checks/diff-project.mts             # 产物 project.json vs 已发布基线
node tools/checks/check-collection-copy.mts    # 游戏合集的文案是"它自己那个游戏"的（先 pnpm build）
node tools/checks/verify-sim-page.mts <分发名>  # 自包含包 file:// 可用（含"零 http 请求"）
node tools/checks/verify-static-preview.mts <分发名>  # 静态托管子路径可用（自带服务器）
node tools/checks/read-audio-tags.mts          # 读音频文件自带标签（核对歌名用）
node tools/checks/check-sim-scripts.mts [页面]  # 抽出自包含页的每个内联 script 单独语法检查
node tools/checks/check-downloader.mts         # 抓取器：能编译 + 夹具绿 + 四处破坏必红（不联网）
node tools/checks/verify-scene-player.mts      # 场景播放器：多骨架+平面合成、画面非空、atlas 指错必红

verify-scene-player 自己跑 tsc -p tsconfig.runtime.json 并自造夹具（用抓取器 staged 的 kv45/scene_main 与 nico-tea/scene_main——staging 是"一个场景一个壁纸目录"）， 不碰 wallpapers/、不需要 pnpm build；前置只有 python -m tools.downloader fetch --page kv45。

verify-static-preview 需要 pnpm build --with-sim（面板要随产物走）。

② 需要 serve.mjs（对拍驱动 window.__test 只有它注入）

⚠ 跑 test-inline-guard 之前必须先停掉 pnpm dev。 它会故意把 src/vendor/spine-player.js 改坏来验证守卫，而调试服的热更新正在监听 src/——两者会抢构建，结果随机失败。 同理，任何会写 dist/ 的构建都别和 watcher 同时跑（pnpm build sim 与 watcher 也会抢 dist/）。

node tools/serve.mjs 8190 --root dist/releases/collection-all   # 另开一个终端
node tools/checks/test-props.mjs        # bgm 选择/回落 + fps 限流
node tools/checks/test-resize.mjs       # 改窗口尺寸不泄漏、不跑偏
node tools/checks/test-acceptance.mjs   # 体积/文案/音源/构图总验收
node tools/checks/verify-fitter.mjs     # viewport-fitter 的纯函数

③ 需要 pnpm dev（模拟器面板）

node tools/dev.ts --port 5173 --no-build                        # 另开一个终端
node tools/checks/smoke-dev.mts 5173          # 路由、注入、越界 404
node tools/checks/smoke-sim.mts http://127.0.0.1:5173           # 面板真的挂上、属性真的下发
node tools/checks/verify-panel.mts http://127.0.0.1:5173       # 面板还原度（12 组）
node tools/checks/verify-hot-reload.mts http://127.0.0.1:5173  # 改 CSS 只换样式表、改 runtime 整页刷新
node tools/checks/check-single-bgm.mts http://127.0.0.1:5173   # 单档分发里切歌真的换音源
node tools/checks/shot-panel.mts http://127.0.0.1:5173 [输出目录]  # 给面板出图（不是断言）

verify-dev-flags.mts 要另一个模式：先 node tools/build.ts --with-sim， 再 node tools/dev.ts --port 5173 --no-build --with-sim，然后 node tools/checks/verify-dev-flags.mts。它验的是"热更新重建后 --with-sim 还在"。

verify-visual-equivalence.mts 要两步：先用 tools/capture.mjs 拍到 tools/shots/visual-current/，再跑它。基线在 tools/shots/baseline-pre-refactor/， 不能重新生成。

---

两层，以及为什么

后缀	是否被 pnpm typecheck 检查	说明
.mts	✅ 走 tsconfig.checks.json	后来写的验收脚本
.mjs	❌	四个早期的运行时测试：test-acceptance / test-props / test-resize / verify-fitter

tsconfig.checks.json 只关掉 noImplicitAny 一项，其余严格模式照旧—— 正是严格模式翻出了 28 处真问题（可能 undefined、[] 推成 never[]、catch 里 error 是 unknown、 参数个数不符），其中一条是"文件头声明了 ⑤ 但从未实现的断言"。

往 .mjs 里写类型注解会让它运行时崩。 .mjs 是纯 JS，(x: string) => … 是 SyntaxError， 而 tsc 不管 .mjs，所以这个错在类型检查里完全看不见——踩过一次。 要写类型就先改成 .mts。

把那四个 .mjs 也并进受检层是一件独立的、该单独做的事：实测会立刻多出约 80 处既有问题。 别在别的改动的尾巴上顺手做。

---

约定

• 一个从不失败的检查等于没有检查。 门禁类的脚本（test-sim-gate / test-inline-guard） 都要"先证明它会红"——注入一个坏东西，确认它报错，再还原。
• 验证要先检查前置条件。 verify-dev-flags.mts 第一件事是 fetch("/") 断言服务活着； 否则"服务没起来"会被当成"验证通过"——这是真实发生过的一次空验证。
• 区分"选项在"和"能生效"。 verify-panel.mts 断言面板上有那个下拉； check-single-bgm.mts 断言选了之后 <audio>.src 真的变了。两者缺一不可。