mirror of
https://github.com/motajs/template.git
synced 2026-10-21 23:00:29 +08:00
docs(09-22): 修订第 5 轮审查（jsDoc 基线改为 Task 0 一次性捕获 / 门禁与提交解耦）
This commit is contained in:
parent
539c651672
commit
9ce3b62480
@ -30,7 +30,7 @@ must_haves:
|
||||
- "**构建范围与顺序不变（用户裁定 3 / 4 / D-93）：** 只改构建脚本与其测试；**不改** `script/build-lib.ts`、`package.json`、`index.html`、`dev.md`、`src/**`、`public/**`、数据端/渲染端源码（`packages-user/**`、`packages/**`）、`vite.config.ts`、lockfile、`script/dev.ts`；**不改构建顺序**（准备 → 渲染端 → 数据端 → content → LICENSE）；**不做特殊失败处理**（无 BLOCKED 分支、无 baseline / 范围门禁、无外部状态检查）。"
|
||||
- "**开发环境不受影响：** 修饰器删除插件 `apply: 'build'`（`pnpm dev` 仍保留装饰器，`script/dev.ts` 不改）；插件 `enforce: 'pre'`，其 `transform` 早于 Vite 的 TS/JSX 转译。"
|
||||
- "**测试是必需产物：** 扩展 `script/build-plugin.test.ts`（新增 `describe`，不改动既有 `dataIsolationPlugin` 用例）并新增 `script/build-resource.test.ts`；每个 `it` 前一行注释（AGENTS.md）；content 测试用临时 fixture 目录，不触碰 `src/content`。"
|
||||
- "**验证可运行且范围诚实（Nyquist）：** 修饰器删除用「纯函数文本断言 + **对照式双装饰器**真实 `vite.build()`」双证——同一 fixture 必须**导出一个类**、两个方法分别带 `@shouldReplay('...')` 与 `@ignoreReplay('...')`、各自返回**不同**的唯一字面量（`mota_replay_probe` / `mota_ignore_probe`），且 `shouldReplay` / `ignoreReplay` **工厂函数只在 fixture 内本地定义、不得导出**（否则实验组也会保留名字，对照失效）。**对照构建** `plugins: []` 产物必须 `toContain('shouldReplay')`、`toContain('ignoreReplay')`、`toContain('mota_replay_probe')`、`toContain('mota_ignore_probe')` 且两个方法名都在；**实验构建**（带插件）必须 `not.toContain('shouldReplay')`、`not.toContain('ignoreReplay')`、`toContain('mota_replay_probe')`、`toContain('mota_ignore_probe')` 且两个方法名都在（缺任一侧即成空断言）；另含字符串/注释不误删、`node_modules` 跳过。content 过滤以 fixture 行为测试证明（`defaults` 全量（即使 `defaults/` 内出现 `.list.jsonc`）、清单引用保留、未引用剔除、无清单子文件夹全量、**根目录即使出现 `.list.jsonc` 也全量**、`.list.jsonc` 压缩去注释、jsonc 去注释）。另加真实 `src/content` 的「清单覆盖率」检查、按函数切片的结构门禁、`build-resource.ts` 的「既有注释零删除」git 门禁放在 **Task 2**、`build-plugin.ts` 的同口径门禁放在 **Task 1 提交前**（各自以 `git show HEAD:<file>` 的注释行集合为基线逐行比对，**不依赖暂存状态**；Task 1 的门禁额外自校验「基线不得已含新导出 `replayDecoratorPlugin`」，否则基线已被本任务的提交污染、门禁作废），以及 `script/build-*.ts` 范围内的 `eslint`。结构门禁只断言**行为与导出形态**（AST API 标记、`enforce` / `apply`、导入绑定与注入位置），不硬编码提议命名。所有 `node -e` 门禁**只用单引号字面量**（PowerShell 5.1 下 `\"` 会提前闭合字符串，实测确定性 SyntaxError）。命令一律 `cmd /c \"pnpm exec ...\"`（PowerShell 5.1 下裸 `pnpm` 会因 `pnpm.ps1` 的 `PSSecurityException` 失败）。"
|
||||
- "**验证可运行且范围诚实（Nyquist）：** 修饰器删除用「纯函数文本断言 + **对照式双装饰器**真实 `vite.build()`」双证——同一 fixture 必须**导出一个类**、两个方法分别带 `@shouldReplay('...')` 与 `@ignoreReplay('...')`、各自返回**不同**的唯一字面量（`mota_replay_probe` / `mota_ignore_probe`），且 `shouldReplay` / `ignoreReplay` **工厂函数只在 fixture 内本地定义、不得导出**（否则实验组也会保留名字，对照失效）。**对照构建** `plugins: []` 产物必须 `toContain('shouldReplay')`、`toContain('ignoreReplay')`、`toContain('mota_replay_probe')`、`toContain('mota_ignore_probe')` 且两个方法名都在；**实验构建**（带插件）必须 `not.toContain('shouldReplay')`、`not.toContain('ignoreReplay')`、`toContain('mota_replay_probe')`、`toContain('mota_ignore_probe')` 且两个方法名都在（缺任一侧即成空断言）；另含字符串/注释不误删、`node_modules` 跳过。content 过滤以 fixture 行为测试证明（`defaults` 全量（即使 `defaults/` 内出现 `.list.jsonc`）、清单引用保留、未引用剔除、无清单子文件夹全量、**根目录即使出现 `.list.jsonc` 也全量**、`.list.jsonc` 压缩去注释、jsonc 去注释）。另加真实 `src/content` 的「清单覆盖率」检查、按函数切片的结构门禁、`build-resource.ts` 的「既有注释零删除」门禁放在 **Task 2**、`build-plugin.ts` 的同口径门禁放在 **Task 1**（两者都与 **Task 0 一次性捕获、写在仓库外 `os.tmpdir()/gsd-09-22-jsdoc-baseline.json` 的注释行集合**逐行比对——**与 git 提交无关、可重复执行**，`gsd-executor` 的逐 task 提交不会让基线漂移；门禁另校验基线注释行数下限与「基线不得已含新标识 `replayDecoratorPlugin` / `removeReplayDecorators`」），以及 `script/build-*.ts` 范围内的 `eslint`。结构门禁只断言**行为与导出形态**（AST API 标记、`enforce` / `apply`、导入绑定与注入位置），不硬编码提议命名。所有 `node -e` 门禁**只用单引号字面量**（PowerShell 5.1 下 `\"` 会提前闭合字符串，实测确定性 SyntaxError）。命令一律 `cmd /c \"pnpm exec ...\"`（PowerShell 5.1 下裸 `pnpm` 会因 `pnpm.ps1` 的 `PSSecurityException` 失败）。"
|
||||
- "**命名须先获批（D-04）：** OI-1（`removeReplayDecorators` / `replayDecoratorPlugin` / `name: 'mota-replay-decorator'`，以及新增的模块级常量 `REPLAY_DECORATORS`（目标装饰器名集合）/ `SCRIPT_EXTENSIONS`（`.ts` / `.tsx` 后缀集合）/ `NODE_MODULES_SEGMENT`（`node_modules` 路径判定））、OI-2（`LIST_FILE_NAME` / `DEFAULTS_DIRECTORY` / `readListNames` / `collectListedNames` / `isListedFile` / `processDirectory` 新增的 `isRoot` 参数）、OI-3（`script/build-resource.test.ts` 文件名）。未获批前不得落码。**若用户在 Task 0 指定了与提议不同的命名，必须先按新命名修订本计划（门禁命令、测试用例与 SUMMARY 关键字同步）并重新获批后执行**——门禁本身按行为、值标记与导出形态断言，不会自动跟随改名。"
|
||||
artifacts:
|
||||
- path: script/build-plugin.ts
|
||||
@ -44,7 +44,7 @@ must_haves:
|
||||
- path: script/build-resource.test.ts
|
||||
provides: "**新增**行为测试：临时 fixture 验证根文件、**根目录即使存在 `.list.jsonc` 也全量输出**、`defaults/` 全量（**fixture 内 `defaults/.list.jsonc` 只列 `env`，`env.jsonc` 与 `other.jsonc` 仍都输出**，镜像根目录用例）、`maps/` 与 `texture/` 与 `font/` 的清单保留/剔除、**无清单子文件夹全量**、`.list.jsonc` 压缩且剥离整行 `//` 注释（fixture 清单原文带注释）、`item.ts` 原样拷贝；每个 `it` 前一行注释（文件名待批准，OI-3）"
|
||||
- path: .planning/phases/09-minimum-browser-runnable/09-22-SUMMARY.md
|
||||
provides: "执行摘要：content 逐文件夹过滤规则与清单匹配口径、修饰器删除口径（TS AST + 双端注入 + 不删 import）、命名获批情形、门禁结果、`open_items` 处置、已知边界（未端到端跑全量 `build:game`；生产产物不再做录像安全检查；`index.html` 仍引用 `/styles.css`）"
|
||||
provides: "执行摘要：content 逐文件夹过滤规则与清单匹配口径、修饰器删除口径（TS AST + 双端注入 + 不删 import）、命名获批情形、门禁结果（含与 Task 0 捕获基线 `os.tmpdir()/gsd-09-22-jsdoc-baseline.json` 比对的注释零丢失，及该基线的 40 位 `head` SHA）、`estimate.tokens=46000` 为**未校准**估算（`confidence: low`）的声明、`open_items` 处置、已知边界（未端到端跑全量 `build:game`；生产产物不再做录像安全检查；`index.html` 仍引用 `/styles.css`）"
|
||||
key_links:
|
||||
- "`replayDecoratorPlugin()`（`script/build-plugin.ts`）↔ `buildClient` 与 `buildData` 的 `plugins` 数组（`script/build-game.ts`）—— 用户裁定 2「双端都删」的唯一执行点"
|
||||
- "`removeReplayDecorators` 的 AST 切片 ↔ `@shouldReplay('...')` / `@ignoreReplay('...')` 装饰器文本 —— 只删装饰器节点范围，字符串/注释中的同名文本不会被误删"
|
||||
@ -78,6 +78,7 @@ must_haves:
|
||||
- "**不得引入特殊失败处理：** 不写 BLOCKED 分支、不写 baseline / 范围门禁、不检查外部文件或仓库状态；构建失败即以非零退出并打印错误。"
|
||||
- "**不得改范围外文件：** 不改 `script/build-lib.ts`、`package.json`、`index.html`、`dev.md`、`src/**`、`public/**`、`packages-user/**`、`packages/**`、`vite.config.ts`、lockfile、`script/dev.ts`。"
|
||||
- "**既有注释 / jsDoc 一律逐字保留（AGENTS.md）：** `script/build-resource.ts` 中 `processDirectory` / `minifyJSONC` / `compressFont` / `buildContent` 与接口成员的 jsDoc 不得改写或删除；`script/build-plugin.ts` 中 `dataIsolationPlugin`、`SPECIFIER_BANS` / `PATH_BANS` / `findBan` 的注释同理。新逻辑的说明只能写在新函数 / 新常量上。"
|
||||
- "**注释基线不得随提交漂移：** 「既有注释零删除」门禁必须与 Task 0 捕获的 `os.tmpdir()/gsd-09-22-jsdoc-baseline.json` 比对；不得改用 `git show HEAD:<file>`（`gsd-executor` 逐 task 提交后基线即变成改后状态，门禁要么空洞要么自失败），也不得要求「必须在提交前运行」这类依赖时序的门禁。"
|
||||
- "**不得在 `node -e` 门禁里用 `\\\"` 转义双引号：** PowerShell 5.1 会提前闭合字符串并抛 SyntaxError；内联脚本只允许单引号字面量（需引号字符时用 `String.fromCharCode(39)`），且不得出现 `$` 与反引号。"
|
||||
- "**不得删掉对照构建：** 不带插件的对照构建缺失时，`not.toContain` 就是空断言（编译产物本就不含 `@shouldReplay` 语法）。"
|
||||
- "**不得让对照 fixture 失效：** fixture 必须**导出一个类**、两个方法分别带 `@shouldReplay` / `@ignoreReplay` 并各自返回**不同**的唯一字面量（`mota_replay_probe` / `mota_ignore_probe`），`shouldReplay` / `ignoreReplay` 工厂函数**必须在 fixture 内本地定义且不得导出**——导出或把工厂放到别的模块，都会让实验组也保留名字，对照变成无效断言。"
|
||||
@ -136,7 +137,7 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
<task type="checkpoint:decision" gate="blocking-human">
|
||||
<name>Task 0: 预执行汇报关卡 —— 汇报两处修复的范围、content 过滤规则、修饰器删除口径与待批准命名，等待「可以执行」</name>
|
||||
<precondition>`script/build-plugin.ts` 仅含 `dataIsolationPlugin`；`script/build-resource.ts` 为全量镜像实现（`processDirectory` 无清单过滤）；`src/content` 共 23 个 `.jsonc`，`animation` / `audio` / `font` / `maps` / `texture` 各有 `.list.jsonc`、`defaults/` 有 8 个 `.jsonc`；`packages-user/data-common/src/replay/func.ts` 仍导出 `shouldReplay` / `ignoreReplay`，数据端源码中仍有大量 `@shouldReplay` 应用；`script/build-resource.test.ts` 尚不存在。</precondition>
|
||||
<files>（只读汇报，不修改任何文件）</files>
|
||||
<files>（不改仓库文件）os.tmpdir()/gsd-09-22-jsdoc-baseline.json（仓库外临时基线，本任务一次性写入）</files>
|
||||
<read_first>
|
||||
- .planning/phases/09-minimum-browser-runnable/09-CONTEXT.md（D-93 / D-96 / D-98；D-03 / D-04）
|
||||
- .planning/phases/09-minimum-browser-runnable/09-21-SUMMARY.md（上游执行结果与已知边界）
|
||||
@ -146,7 +147,9 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
- AGENTS.md（执行前须获批、命名须先反馈、修改方式须预先声明）；dev.md（命名、jsDoc、无副作用、非空判断）
|
||||
</read_first>
|
||||
<action>
|
||||
**停下并向用户汇报，等待回复「可以执行」后才继续；汇报本身只读。**
|
||||
**停下并向用户汇报，等待回复「可以执行」后才继续；除 ⓪ 的仓库外临时基线外不写任何文件。**
|
||||
|
||||
⓪ **先捕获 jsDoc 注释基线（仓库外，一次性）：** 运行本任务 `<verify>` 的第一条命令，把 `git rev-parse HEAD` 与 `script/build-plugin.ts` / `script/build-resource.ts` 的**注释行集合**写入 `os.tmpdir()/gsd-09-22-jsdoc-baseline.json`；文件已存在且未含新标识时复用、不覆盖（幂等）。此基线供 Task 1 / Task 2 的「既有注释零删除」门禁比对，判断**与 git 提交无关**，重跑门禁仍成立。汇报时一并给出本次基线 SHA（40 位）。
|
||||
|
||||
① **要解决的问题：** 见 objective 的两条（content 未过滤、录像装饰器进了生产构建）。
|
||||
|
||||
@ -156,7 +159,7 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
|
||||
④ **修饰器删除口径（用户裁定 2）：** 构建时删除**所有** `@shouldReplay(...)` / `@ignoreReplay(...)` 应用（当前 `@shouldReplay` = **69 次应用 / 20 个 `.ts` 文件**；`packages-user/data-common/src/replay/func.ts` 另有 1 行注释含 2 处 `@shouldReplay` 文本，非应用；`@ignoreReplay` 无实际应用），**数据端与渲染端都删**（`buildData` + `buildClient` 各注入一次）；用 **TypeScript AST**（`ts.createSourceFile` + `ts.canHaveDecorators` / `ts.getDecorators`）取装饰器节点范围后**逆序切片删除**，字符串 / 注释中的同名文本不删；仅处理项目自身 `.ts` / `.tsx`，跳过 `node_modules`，不处理 `.vue`；**不手动删 import**（交给依赖分析 tree-shaking）。插件 `apply: 'build'`，故 `pnpm dev` 行为不变。
|
||||
|
||||
⑤ **验证方式：** `script/build-plugin.test.ts` 扩展为「纯函数断言（删装饰器、字符串/注释不误删、带引号与括号的参数整段删除）+ **对照式双装饰器**真实 `vite.build()`（同一 fixture 构建两次：fixture **导出一个类**，两个方法分别带 `@shouldReplay` / `@ignoreReplay` 并各自返回不同唯一字面量 `mota_replay_probe` / `mota_ignore_probe`，`shouldReplay` / `ignoreReplay` 工厂在 fixture 内**本地定义、不导出**；**对照** `plugins: []` 产物必须含 `shouldReplay`、`ignoreReplay`、两个唯一字面量与两个方法名，**实验组**必须不含 `shouldReplay` / `ignoreReplay`，但两个唯一字面量与两个方法名**仍在**——两侧缺一即空断言）」；`script/build-resource.test.ts` 用临时 fixture 验证根文件、**根目录即使存在 `.list.jsonc` 也全量输出**、`defaults/` 全量（即使 `defaults/` 内存在 `.list.jsonc`）、`maps` / `texture` / `font` 的保留与剔除、**无清单子文件夹全量**、`.list.jsonc` 压缩且剥离整行 `//` 注释、`item.ts` 原样；另加真实 `src/content` 的清单覆盖率检查（每个清单目录内非清单文件都必须被清单命中，防止过滤掉现有素材）、`build-game` 按函数切片的结构门禁（只断言导入绑定与注入位置，不绑定提议命名）、`build-resource.ts` 与 `build-plugin.ts` 的「既有注释零删除」门禁（各自从 `git show HEAD:<file>` 取注释行集合逐行比对，**不受暂存状态影响**，并校验基线注释行数下限防空洞；**`build-plugin.ts` 的门禁落在 Task 1 提交前**——基线若已含新导出即自失败，`build-resource.ts` 的门禁落在 Task 2），以及 `script/build-*.ts` 范围内的 `eslint`；命令一律 `cmd /c "pnpm exec ..."`，内联 `node -e` 只用单引号字面量。
|
||||
⑤ **验证方式：** `script/build-plugin.test.ts` 扩展为「纯函数断言（删装饰器、字符串/注释不误删、带引号与括号的参数整段删除）+ **对照式双装饰器**真实 `vite.build()`（同一 fixture 构建两次：fixture **导出一个类**，两个方法分别带 `@shouldReplay` / `@ignoreReplay` 并各自返回不同唯一字面量 `mota_replay_probe` / `mota_ignore_probe`，`shouldReplay` / `ignoreReplay` 工厂在 fixture 内**本地定义、不导出**；**对照** `plugins: []` 产物必须含 `shouldReplay`、`ignoreReplay`、两个唯一字面量与两个方法名，**实验组**必须不含 `shouldReplay` / `ignoreReplay`，但两个唯一字面量与两个方法名**仍在**——两侧缺一即空断言）」；`script/build-resource.test.ts` 用临时 fixture 验证根文件、**根目录即使存在 `.list.jsonc` 也全量输出**、`defaults/` 全量（即使 `defaults/` 内存在 `.list.jsonc`）、`maps` / `texture` / `font` 的保留与剔除、**无清单子文件夹全量**、`.list.jsonc` 压缩且剥离整行 `//` 注释、`item.ts` 原样；另加真实 `src/content` 的清单覆盖率检查（每个清单目录内非清单文件都必须被清单命中，防止过滤掉现有素材）、`build-game` 按函数切片的结构门禁（只断言导入绑定与注入位置，不绑定提议命名）、`build-resource.ts` 与 `build-plugin.ts` 的「既有注释零删除」门禁（⓪ 已把两个文件的注释行集合与 `git rev-parse HEAD` 存到仓库外的临时基线；Task 1 / Task 2 各自与**该基线**逐行比对，**与提交无关、可重复执行**，并校验基线注释行数下限防空洞与「基线不得已含 `replayDecoratorPlugin` / `removeReplayDecorators`」），以及 `script/build-*.ts` 范围内的 `eslint`；命令一律 `cmd /c "pnpm exec ..."`，内联 `node -e` 只用单引号字面量。
|
||||
|
||||
⑥ **已知边界（原样告知）：** ① **不端到端运行全量 `build:game`**（渲染端仍有用户 WIP 的 stale import；09-21 已记录），验证只到单测 + 结构门禁 + 真实清单覆盖率；② 生产构建不再有录像安全检查装饰器，属预期结果；③ `index.html` 仍引用 `/styles.css`，本计划不产出、不改；④ `animation` / `audio` / `font` 目录当前无对应素材（清单为空或无文件），过滤不会影响现有产物。
|
||||
|
||||
@ -182,6 +185,8 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
</options>
|
||||
<resume-signal>回复「可以执行」即可；如需调整命名或规则细节，请在回复中一并指明。</resume-signal>
|
||||
<verify>
|
||||
<automated>node -e "const fs=require('fs'),os=require('os'),path=require('path'),cp=require('child_process');const out=path.join(os.tmpdir(),'gsd-09-22-jsdoc-baseline.json');const files=['script/build-plugin.ts','script/build-resource.ts'];const marks=['//','/*','*'];const isComment=l=>marks.some(m=>l.startsWith(m));const bad=[];let sha='';try{sha=cp.execSync('git rev-parse HEAD',{encoding:'utf8'}).trim()}catch(e){bad.push('cannot rev-parse HEAD: '+e.message)}if(sha.length!==40)bad.push('HEAD sha is not 40 chars: '+sha);const fresh={head:sha,capturedAt:new Date().toISOString(),files:{}};for(const f of files){fresh.files[f]=fs.readFileSync(f,'utf8').split(/\r?\n/).map(l=>l.trim()).filter(isComment)}let base=fresh;if(fs.existsSync(out)){const prev=JSON.parse(fs.readFileSync(out,'utf8'));let poisoned=false;for(const f of files){const ls=prev.files?prev.files[f]:undefined;if(!Array.isArray(ls)){poisoned=true;break}for(const l of ls){if(l.indexOf('replayDecoratorPlugin')>-1){poisoned=true;break}if(l.indexOf('removeReplayDecorators')>-1){poisoned=true;break}}if(poisoned)break}if(poisoned)bad.push('existing baseline already contains new identifiers - delete '+out+' and recapture before any edit');else{base=prev;console.log('reuse existing baseline ('+prev.capturedAt+', head '+prev.head+')')}}else{fs.writeFileSync(out,JSON.stringify(fresh,null,2));console.log('captured baseline at '+out+' (head '+sha+')')}for(const f of files){const ls=base.files?base.files[f]:undefined;if(!Array.isArray(ls)){bad.push('baseline missing comment lines for '+f);continue}const min=f==='script/build-plugin.ts'?5:8;if(ls.length<min)bad.push(f+' baseline comment lines too few ('+ls.length+'<'+min+')');console.log(f+' baseline comment lines = '+ls.length)}if(bad.length>0){console.error('JSDOC BASELINE CAPTURE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK jsdoc baseline ready: head '+base.head)"</automated>
|
||||
<fails_when>non-zero exit，或 stderr 含 "JSDOC BASELINE CAPTURE FAILED"：`git rev-parse HEAD` 失败或 SHA 不是 40 位 / 已存在的临时基线已含 `replayDecoratorPlugin` 或 `removeReplayDecorators`（说明它是在编辑之后捕获的，须删除该临时文件并在任何编辑前重跑）/ 某文件基线注释行数低于下限（`build-plugin.ts` 5 行、`build-resource.ts` 8 行）</fails_when>
|
||||
<automated>node -e "const fs=require('fs'),path=require('path');const bad=[];for(const p of ['script/build-plugin.ts','script/build-plugin.test.ts','script/build-game.ts','script/build-resource.ts','script/build-lib.ts','src/content/core.jsonc','src/content/texture/.list.jsonc','packages-user/data-common/src/replay/func.ts']){if(!fs.existsSync(p))bad.push('missing '+p)}const jc=fs.readdirSync('src/content',{recursive:true}).filter(f=>String(f).endsWith('.jsonc'));if(jc.length!==23)bad.push('expected 23 jsonc, got '+jc.length);for(const d of ['animation','audio','font','maps','texture']){if(!fs.existsSync(path.join('src','content',d,'.list.jsonc')))bad.push('missing list in '+d)}if(fs.readdirSync(path.join('src','content','defaults')).filter(f=>String(f).endsWith('.jsonc')).length!==8)bad.push('defaults must contain 8 jsonc');if(fs.existsSync('script/build-resource.test.ts'))bad.push('build-resource.test.ts must not exist yet');const p=fs.readFileSync('script/build-plugin.ts','utf8');if(p.indexOf('dataIsolationPlugin')<0)bad.push('dataIsolationPlugin missing from build-plugin.ts');const g=fs.readFileSync('script/build-game.ts','utf8');if(g.indexOf('dataIsolationPlugin')<0||g.indexOf('buildContent')<0)bad.push('build-game.ts is not the 09-21 implementation');const rf=fs.readFileSync('packages-user/data-common/src/replay/func.ts','utf8');if(rf.indexOf('export function shouldReplay')<0||rf.indexOf('export function ignoreReplay')<0)bad.push('replay decorator definitions missing');if(fs.readFileSync('src/content/texture/.list.jsonc','utf8').indexOf('// --- SYSTEM PREFIX END --- //')<0)bad.push('list jsonc marker changed');if(bad.length>0){console.error('PRESTATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK prestate: 09-21 scripts in place, 23 jsonc, 5 list folders, defaults=8, decorator defs present, build-resource.test.ts absent')"</automated>
|
||||
<fails_when>non-zero exit，或 stderr 含 "PRESTATE FAILED"：必需文件缺失 / `.jsonc` 数量不是 23 / 某个素材子文件夹缺 `.list.jsonc` / `defaults/` 不是 8 个 jsonc / `script/build-resource.test.ts` 已存在 / `build-plugin.ts` 缺 `dataIsolationPlugin` / `build-game.ts` 已不是 09-21 实现 / 修饰器定义缺失 / `.list.jsonc` 的系统标记行已变化</fails_when>
|
||||
<human-check>用户明确回复「可以执行」；若就 OI-1 / OI-2 / OI-3 指定了与提议不同的命名，须先按新命名修订本计划（门禁命令、测试用例与 SUMMARY 关键字同步）并重新获批，未修订前不得执行</human-check>
|
||||
@ -195,13 +200,14 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
- 已说明生产构建不再有录像安全检查装饰器（属用户裁定 2 的预期结果）
|
||||
- 已说明 `defaults/` 显式豁免过滤、**根目录经 `isRoot` 跳过过滤**、`.list.jsonc` 自身始终压缩输出、`minifyJSONC` 行为不改
|
||||
- 已说明本计划不端到端运行全量 `build:game`
|
||||
- 已运行 ⓪ 的基线捕获命令：`os.tmpdir()/gsd-09-22-jsdoc-baseline.json` 存在（或已存在的干净基线被复用），`head` 为 40 位 SHA 并在汇报中给出，`script/build-plugin.ts` ≥5 行、`script/build-resource.ts` ≥8 行注释基线
|
||||
</acceptance_criteria>
|
||||
<done>用户明确回复「可以执行」；在此之前未执行任何任务、未修改任何仓库文件、未派发任何执行子代理</done>
|
||||
<done>用户明确回复「可以执行」；jsDoc 注释基线已写入仓库外的 `os.tmpdir()/gsd-09-22-jsdoc-baseline.json` 且基线 SHA 已在汇报中记录；在此之前未执行任何任务、未修改任何仓库文件、未派发任何执行子代理</done>
|
||||
</task>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: 修饰器删除插件（`script/build-plugin.ts`）+ 双端注入（`script/build-game.ts`）+ 测试</name>
|
||||
<precondition>Task 0 已闭环（用户回复「可以执行」，OI-1 已获批；若用户改了命名，本计划已按新命名修订并重新获批——门禁按导出形态与导入绑定断言，未修订不得执行）。`typescript` 与 `vitest` 可用；`script/build-plugin.ts` 仅含 `dataIsolationPlugin`；`script/build-game.ts` 为 09-21 实现（`buildClient` < `buildData` < `buildGame` 的定义顺序）。</precondition>
|
||||
<precondition>`os.tmpdir()/gsd-09-22-jsdoc-baseline.json` 已由 Task 0 捕获（含 40 位 `head` 与 `script/build-plugin.ts` / `script/build-resource.ts` 的注释行集合；若缺失，先按 Task 0 ⓪ 的捕获命令补捕——此时两个文件尚未被本任务修改）。Task 0 已闭环（用户回复「可以执行」，OI-1 已获批；若用户改了命名，本计划已按新命名修订并重新获批——门禁按导出形态与导入绑定断言，未修订不得执行）。`typescript` 与 `vitest` 可用；`script/build-plugin.ts` 仅含 `dataIsolationPlugin`；`script/build-game.ts` 为 09-21 实现（`buildClient` < `buildData` < `buildGame` 的定义顺序）。</precondition>
|
||||
<files>script/build-plugin.ts, script/build-plugin.test.ts, script/build-game.ts</files>
|
||||
<read_first>
|
||||
- .planning/phases/09-minimum-browser-runnable/09-CONTEXT.md（D-04；用户裁定 2）
|
||||
@ -256,8 +262,8 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
<fails_when>non-zero exit，或任一断言失败（装饰器未被删 / 参数残留碎片 / 字符串或注释中的同名文本被误删 / 对照产物缺 `shouldReplay` 或 `ignoreReplay` 或某个唯一字面量（token 前提不成立）/ 带插件产物仍含 `shouldReplay` / `ignoreReplay` / 带插件产物丢了 `mota_replay_probe`、`mota_ignore_probe` 或方法名 / 既有 `dataIsolationPlugin` 用例回归）</fails_when>
|
||||
<automated>node -e "const fs=require('fs');const bad=[];const q=String.fromCharCode(39);const t=fs.readFileSync('script/build-plugin.ts','utf8');const need=['ts.createSourceFile','canHaveDecorators','getDecorators','node_modules','shouldReplay','ignoreReplay','dataIsolationPlugin','transform(','code: string','fileName: string','): string','): Plugin','enforce: '+q+'pre'+q,'apply: '+q+'build'+q];for(const x of need){if(t.indexOf(x)<0)bad.push('build-plugin.ts missing: '+x)}const exported=[...t.matchAll(/export function (\w+)/g)].map(m=>m[1]);if(exported.length<3)bad.push('build-plugin.ts must export dataIsolationPlugin plus two strip APIs, found '+exported.length);if(exported.indexOf('dataIsolationPlugin')<0)bad.push('dataIsolationPlugin export lost');const tp=fs.readFileSync('script/build-plugin.test.ts','utf8');for(const x of ['@shouldReplay','@ignoreReplay','node_modules','mota_replay_probe','mota_ignore_probe','export class','build(','not.toContain']){if(tp.indexOf(x)<0)bad.push('build-plugin.test.ts missing: '+x)}if(tp.indexOf('plugins: []')<0&&tp.indexOf('plugins:[]')<0)bad.push('test must include a control vite.build without the plugin');const cnt=(s,sub)=>s.split(sub).length-1;const pos='.toContain('+q,neg='.not.toContain('+q;for(const name of ['shouldReplay','ignoreReplay','mota_replay_probe','mota_ignore_probe']){if(cnt(tp,pos+name+q+')')-cnt(tp,neg+name+q+')')<1)bad.push('test must positively assert '+name+' in the control build')}for(const name of ['shouldReplay','ignoreReplay']){if(cnt(tp,neg+name+q+')')<1)bad.push('test must negatively assert '+name+' in the plugin build')}for(const fn of ['shouldReplay','ignoreReplay']){if(tp.indexOf('function '+fn+'(')<0)bad.push('fixture must locally define '+fn);if(tp.indexOf('export function '+fn)>-1)bad.push('fixture must NOT export '+fn)}const g=fs.readFileSync('script/build-game.ts','utf8');const s=g.indexOf('async function buildClient('),d=g.indexOf('async function buildData('),b=g.indexOf('async function buildGame(');if(s<0||d<0||b<0||!(s<d&&d<b))bad.push('function order changed; slicing gate needs buildClient < buildData < buildGame');else{const idx=g.indexOf('./build-plugin');if(idx<0)bad.push('build-game.ts must import from ./build-plugin');else{const start=g.lastIndexOf('import',idx),open=g.indexOf('{',start),close=g.indexOf('}',open);const bindings=g.slice(open+1,close).split(',').map(v=>v.trim()).filter(Boolean);const extra=bindings.filter(n=>n!=='dataIsolationPlugin');if(bindings.indexOf('dataIsolationPlugin')<0)bad.push('dataIsolationPlugin import lost');if(extra.length!==1)bad.push('exactly one new binding expected from ./build-plugin, got '+extra.length);else{const client=g.slice(s,d),data=g.slice(d,b);if(client.indexOf(extra[0])<0)bad.push('buildClient must inject the replay decorator plugin');if(data.indexOf(extra[0])<0)bad.push('buildData must inject the replay decorator plugin');if(data.indexOf('dataIsolationPlugin')<0)bad.push('buildData must keep dataIsolationPlugin');if(client.indexOf('dataIsolation'+'Plugin')>=0)bad.push('dataIsolationPlugin must stay out of buildClient')}}}if(bad.length>0){console.error('REPLAY PLUGIN GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK replay plugin: AST strip + dual-sided wiring')"</automated>
|
||||
<fails_when>non-zero exit，或 stderr 含 "REPLAY PLUGIN GATE FAILED"（插件缺 AST 定位（`ts.createSourceFile` / `canHaveDecorators` / `getDecorators`）/ 缺 `enforce: 'pre'` 或 `apply: 'build'` / 缺 `node_modules` 跳过 / 导出数少于 3 或丢了 `dataIsolationPlugin` / 缺 `code: string` + `fileName: string` + `): string` 或 `): Plugin` 导出形态 / 测试缺关键用例字样或 `mota_ignore_probe` / 测试缺 `export class` 形态 / 测试缺少不带插件的对照构建（`plugins: []`）/ 测试缺少对 `shouldReplay` / `ignoreReplay` / `mota_replay_probe` / `mota_ignore_probe` 的**正向**断言 / 测试缺少对 `shouldReplay` / `ignoreReplay` 的**负向**断言 / 测试导出了 `shouldReplay` 或 `ignoreReplay` 工厂（对照会失效）/ 函数定义顺序不满足切片前提 / `./build-plugin` 的导入绑定不是「`dataIsolationPlugin` + 恰好 1 个新插件」/ `buildClient` 或 `buildData` 片段缺该新插件 / `buildData` 丢了 `dataIsolationPlugin` / `dataIsolationPlugin` 被接进 `buildClient`）</fails_when>
|
||||
<automated>node -e "const fs=require('fs'),cp=require('child_process');const f='script/build-plugin.ts';const bad=[];let head='';try{head=cp.execSync('git show HEAD:'+f,{encoding:'utf8'})}catch(e){bad.push('cannot read HEAD version of '+f+': '+e.message)}if(head.indexOf('replayDecoratorPlugin')>-1)bad.push('baseline HEAD:'+f+' already contains replayDecoratorPlugin - this comment gate must run BEFORE this task commits');const marks=['//','/*','*'];const isComment=l=>marks.some(m=>l.startsWith(m));const baseSet=new Set(head.split(/\r?\n/).map(l=>l.trim()).filter(isComment));if(baseSet.size<5)bad.push(f+' baseline comment lines too few ('+baseSet.size+'<5), comment gate would be vacuous');const curSet=new Set(fs.readFileSync(f,'utf8').split(/\r?\n/).map(l=>l.trim()));const lost=[...baseSet].filter(l=>!curSet.has(l));if(lost.length>0)bad.push(f+' lost '+lost.length+' existing comment/jsDoc line(s), first: '+lost[0]);if(bad.length>0){console.error('PLUGIN COMMENT GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK plugin comments: HEAD-baseline comment lines intact ('+baseSet.size+' lines)')"</automated>
|
||||
<fails_when>non-zero exit，或 stderr 含 "PLUGIN COMMENT GATE FAILED"：`git show HEAD:script/build-plugin.ts` 基线中的既有注释 / jsDoc 行在当前文件中缺失（被删除或改写）/ 基线注释行数低于下限 5（门禁可能空洞）/ 基线已含新导出 `replayDecoratorPlugin`——说明本门禁跑在本任务提交之后、基线已被污染，必须回退到提交前执行</fails_when>
|
||||
<automated>node -e "const fs=require('fs'),os=require('os'),path=require('path');const f='script/build-plugin.ts';const bad=[];const bp=path.join(os.tmpdir(),'gsd-09-22-jsdoc-baseline.json');let base=null;if(!fs.existsSync(bp))bad.push('jsdoc baseline missing: '+bp+' - Task 0 must capture it before any edit');else{base=JSON.parse(fs.readFileSync(bp,'utf8'));if(typeof base.head!=='string'||base.head.length!==40)bad.push('baseline head is not a 40-char sha')}let baseSet=new Set();if(base){const ls=base.files?base.files[f]:undefined;if(!Array.isArray(ls))bad.push('baseline has no comment lines for '+f);else{baseSet=new Set(ls);for(const l of baseSet){if(l.indexOf('replayDecoratorPlugin')>-1||l.indexOf('removeReplayDecorators')>-1){bad.push('baseline already contains new identifiers (captured after edits?) - delete '+bp+' and recapture before edits');break}}}}if(baseSet.size<5)bad.push(f+' baseline comment lines too few ('+baseSet.size+'<5), comment gate would be vacuous');const curSet=new Set(fs.readFileSync(f,'utf8').split(/\r?\n/).map(l=>l.trim()));const lost=[...baseSet].filter(l=>!curSet.has(l));if(lost.length>0)bad.push(f+' lost '+lost.length+' existing comment/jsDoc line(s), first: '+lost[0]);if(bad.length>0){console.error('PLUGIN COMMENT GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK plugin comments: Task-0 baseline ('+base.head.slice(0,8)+') comment lines intact ('+baseSet.size+' lines)')"</automated>
|
||||
<fails_when>non-zero exit，或 stderr 含 "PLUGIN COMMENT GATE FAILED"：`os.tmpdir()/gsd-09-22-jsdoc-baseline.json` 不存在或没有 `script/build-plugin.ts` 的注释行（Task 0 未捕获基线）/ 基线 `head` 不是 40 位 SHA / 基线已含 `replayDecoratorPlugin` 或 `removeReplayDecorators`（基线是在编辑后捕获的，须删除临时文件并在任何编辑前重捕）/ 基线注释行数低于下限 5（门禁可能空洞）/ 基线中的既有注释 / jsDoc 行在当前文件中缺失（被删除或改写）</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `script/build-plugin.ts` 新增 `removeReplayDecorators` 与 `replayDecoratorPlugin`（命名按 OI-1 获批结果），`enforce: 'pre'` + `apply: 'build'`，仅处理项目内 `.ts` / `.tsx`，跳过 `node_modules`
|
||||
@ -265,14 +271,14 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
- `script/build-game.ts` 在 `buildClient` 与 `buildData` 各注入一次；`buildData` 仍保持 `dataIsolationPlugin` 首位；构建顺序与其余配置未改
|
||||
- 既有 `dataIsolationPlugin` 的行为与用例零回归
|
||||
- `script/build-plugin.test.ts` 覆盖「删两类装饰器、参数含引号/括号、字符串不误删、注释不误删、`node_modules` 跳过、**对照式双装饰器** `vite.build()`（fixture 导出类 + 两个方法各带一种装饰器各返回唯一字面量 + 工厂本地不导出；`plugins: []` 对照产物含 `shouldReplay` / `ignoreReplay` / 两个唯一字面量 / 两个方法名，带插件产物不含 `shouldReplay` / `ignoreReplay` 但两个唯一字面量与两个方法名仍在）」；每个 `it` 前一行注释
|
||||
- 既有注释未被改写：`dataIsolationPlugin` / `SPECIFIER_BANS` / `PATH_BANS` / `findBan` 的注释逐字保留（由**本任务提交前**的 `git show HEAD:script/build-plugin.ts` 基线门禁证明；基线若已含新导出 `replayDecoratorPlugin` 即门禁自失败）；新增 jsDoc 只出现在新函数上
|
||||
- 既有注释未被改写：`dataIsolationPlugin` / `SPECIFIER_BANS` / `PATH_BANS` / `findBan` 的注释逐字保留（由与 **Task 0 捕获的 `os.tmpdir()/gsd-09-22-jsdoc-baseline.json`** 比对的注释门禁证明——**与 git 提交无关，提交后重跑同一门禁仍成立**；基线若已含 `replayDecoratorPlugin` / `removeReplayDecorators` 即门禁自失败并要求在编辑前重捕）；新增 jsDoc 只出现在新函数上
|
||||
- 未手删任何 import；未改 `packages-user/**` / `packages/**` / `src/**` / `script/dev.ts`
|
||||
</acceptance_criteria>
|
||||
<done>修饰器删除插件就位并双端注入：数据端与渲染端构建都不再编译 `@shouldReplay` / `@ignoreReplay` 应用（AST 精确切片、字符串与注释无损伤、`node_modules` 跳过），对照构建证明 token 在未处理时确实存在，开发服务行为不变；单测、结构门禁与注释基线门禁全绿，既有隔离插件零回归</done>
|
||||
</task>
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: content 清单过滤（`script/build-resource.ts`）+ 行为测试 + SUMMARY</name>
|
||||
<precondition>Task 1 已完成（修饰器插件就位并双端注入）；Task 0 已闭环（OI-2 / OI-3 已获批；若用户改了命名，本计划已按新命名修订并重新获批，未修订不得执行）。`src/content` 的 `animation` / `audio` / `font` / `maps` / `texture` 各有 `.list.jsonc`，`defaults/` 有 8 个 `.jsonc`、无清单；`script/build-resource.test.ts` 尚不存在。</precondition>
|
||||
<precondition>Task 1 已完成（修饰器插件就位并双端注入）；Task 0 已闭环且 `os.tmpdir()/gsd-09-22-jsdoc-baseline.json` 仍存在（含 `script/build-resource.ts` 的注释行集合与 40 位 `head`——本任务的注释门禁与它比对，不随 Task 1 的提交漂移）；Task 0 已闭环（OI-2 / OI-3 已获批；若用户改了命名，本计划已按新命名修订并重新获批，未修订不得执行）。`src/content` 的 `animation` / `audio` / `font` / `maps` / `texture` 各有 `.list.jsonc`，`defaults/` 有 8 个 `.jsonc`、无清单；`script/build-resource.test.ts` 尚不存在。</precondition>
|
||||
<files>script/build-resource.ts, script/build-resource.test.ts, .planning/phases/09-minimum-browser-runnable/09-22-SUMMARY.md</files>
|
||||
<read_first>
|
||||
- .planning/phases/09-minimum-browser-runnable/09-CONTEXT.md（D-96；用户裁定 1）
|
||||
@ -311,7 +317,7 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
- **统计：** 返回值 `files` 等于输出目录实际文件数、`jsonc` 等于压缩的 `.jsonc` 数（含 `.list.jsonc`）、`fonts` 为 0。
|
||||
- 测试用 `chars: ''`；不触碰仓库 `src/content`。
|
||||
|
||||
(3) **`09-22-SUMMARY.md`：** 记录范围（只动构建脚本与测试）、content 逐文件夹规则与清单匹配口径（含根目录 `isRoot` 跳过）、修饰器删除口径（TypeScript AST + 双端注入 + 不手删 import + `apply: 'build'`）、命名获批情形、门禁结果（两个单测 + 对照式**双装饰器** `vite.build()`（含对照组含 `shouldReplay` / `ignoreReplay` / 两个唯一字面量的证据）+ 结构门禁 + `git show HEAD` 基线注释零丢失 + 真实 `src/content` 清单覆盖率 + 范围内的 `eslint`）、`open_items` 处置，并**明确记录已知边界**：未端到端运行全量 `build:game`（渲染端仍有 stale import）、生产构建不再有录像安全检查、`index.html` 仍引用 `/styles.css`。需出现关键字：`defaults`、`.list.jsonc`、`node_modules`、`build:game`、`D-96`、`shouldReplay`。
|
||||
(3) **`09-22-SUMMARY.md`：** 记录范围（只动构建脚本与测试）、content 逐文件夹规则与清单匹配口径（含根目录 `isRoot` 跳过）、修饰器删除口径（TypeScript AST + 双端注入 + 不手删 import + `apply: 'build'`）、命名获批情形、门禁结果（两个单测 + 对照式**双装饰器** `vite.build()`（含对照组含 `shouldReplay` / `ignoreReplay` / 两个唯一字面量的证据）+ 结构门禁 + **与 Task 0 捕获的 `os.tmpdir()/gsd-09-22-jsdoc-baseline.json` 比对的注释零丢失**（提交后重跑同一门禁仍成立）+ 真实 `src/content` 清单覆盖率 + 范围内的 `eslint`）、`open_items` 处置，并**明确记录已知边界**：未端到端运行全量 `build:game`（渲染端仍有 stale import）、生产构建不再有录像安全检查、`index.html` 仍引用 `/styles.css`。**另须记录两件事：** ① 注释基线信息——文件路径 `gsd-09-22-jsdoc-baseline.json` 与捕获时的 `head` SHA（40 位，逐字写入 SUMMARY）；② `estimate.tokens=46000` 是**未校准**的原始估算（`confidence: low`，尚无实际执行样本），不得表述为实测值。需出现关键字：`defaults`、`.list.jsonc`、`node_modules`、`build:game`、`D-96`、`shouldReplay`、`gsd-09-22-jsdoc-baseline`、`uncalibrated`。
|
||||
</action>
|
||||
<behavior>
|
||||
- 根 `.jsonc` → 输出纯 JSON，后缀仍 `.jsonc`。
|
||||
@ -327,8 +333,8 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
<verify>
|
||||
<automated>cmd /c "pnpm exec vitest run script/build-resource.test.ts"</automated>
|
||||
<fails_when>non-zero exit，或任一断言失败（`defaults/` 被过滤 / 清单引用文件被剔除 / 未引用文件仍被输出 / `.list.jsonc` 被剔除或未压缩 / 根 `.jsonc` 未压成纯 JSON / `item.ts` 拷贝内容不一致 / 统计值与实际输出不一致）</fails_when>
|
||||
<automated>node -e "const fs=require('fs'),cp=require('child_process');const bad=[];const t=fs.readFileSync('script/build-resource.ts','utf8');for(const x of ['.list.jsonc','defaults','basename','JSON.parse','minifyJSONC','buildContent','Fontmin','chars: string','IContentBuildOptions','IContentBuildStats']){if(t.indexOf(x)<0)bad.push('build-resource.ts missing: '+x)}const commentMarks=['//','/*','*'];const isComment=l=>commentMarks.some(m=>l.startsWith(m));for(const f of ['script/build-resource.ts']){let head='';try{head=cp.execSync('git show HEAD:'+f,{encoding:'utf8'})}catch(e){bad.push('cannot read HEAD version of '+f+': '+e.message)}const baseSet=new Set(head.split(/\r?\n/).map(l=>l.trim()).filter(isComment));const min=8;if(baseSet.size<min)bad.push(f+' baseline comment lines too few ('+baseSet.size+'<'+min+'), comment gate would be vacuous');const curSet=new Set(fs.readFileSync(f,'utf8').split(/\r?\n/).map(l=>l.trim()));const lost=[...baseSet].filter(l=>!curSet.has(l));if(lost.length>0)bad.push(f+' lost '+lost.length+' existing comment/jsDoc line(s), first: '+lost[0])}if(!fs.existsSync('script/build-resource.test.ts'))bad.push('script/build-resource.test.ts missing');const sp='.planning/phases/09-minimum-browser-runnable/09-22-SUMMARY.md';if(!fs.existsSync(sp))bad.push('09-22-SUMMARY.md missing');else{const sm=fs.readFileSync(sp,'utf8');for(const tok of ['defaults','.list.jsonc','node_modules','build:game','D-96','shouldReplay']){if(sm.indexOf(tok)<0)bad.push('SUMMARY must record token: '+tok)}}if(bad.length>0){console.error('CONTENT FILTER GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK content filter: list retention + build-resource.ts HEAD-baseline comments intact + SUMMARY tokens')"</automated>
|
||||
<fails_when>non-zero exit，或 stderr 含 "CONTENT FILTER GATE FAILED"（`build-resource.ts` 缺 `.list.jsonc` / `defaults` / `basename` / `JSON.parse` 等值标记 / 既有导出改成别名或丢失（`minifyJSONC` / `buildContent` / `IContentBuildOptions` / `IContentBuildStats`）/ `chars: string` 丢失 / **`git show HEAD:script/build-resource.ts` 基线中的既有注释或 jsDoc 行在当前 `build-resource.ts` 中缺失（被删除或改写）**（`build-plugin.ts` 的同口径门禁落在 Task 1 提交前，不在此处重复） / 基线注释行数低于下限（门禁可能空洞）/ 缺测试文件 / 缺 SUMMARY 或 SUMMARY 未记录 `defaults`、`.list.jsonc`、`node_modules`、`build:game`、`D-96`、`shouldReplay`）</fails_when>
|
||||
<automated>node -e "const fs=require('fs'),os=require('os'),path=require('path');const bad=[];const f='script/build-resource.ts';const t=fs.readFileSync(f,'utf8');for(const x of ['.list.jsonc','defaults','basename','JSON.parse','minifyJSONC','buildContent','Fontmin','chars: string','IContentBuildOptions','IContentBuildStats']){if(t.indexOf(x)<0)bad.push('build-resource.ts missing: '+x)}const bp=path.join(os.tmpdir(),'gsd-09-22-jsdoc-baseline.json');let base=null;if(!fs.existsSync(bp))bad.push('jsdoc baseline missing: '+bp+' - Task 0 must capture it before any edit');else{base=JSON.parse(fs.readFileSync(bp,'utf8'));if(typeof base.head!=='string'||base.head.length!==40)bad.push('baseline head is not a 40-char sha')}let baseSet=new Set();if(base){const ls=base.files?base.files[f]:undefined;if(!Array.isArray(ls))bad.push('baseline has no comment lines for '+f);else{baseSet=new Set(ls);for(const l of baseSet){if(l.indexOf('.list.jsonc')>-1||l.indexOf('readListNames')>-1){bad.push('baseline already contains new content-filter identifiers (captured after edits?) - delete '+bp+' and recapture before edits');break}}}}if(baseSet.size<8)bad.push(f+' baseline comment lines too few ('+baseSet.size+'<8), comment gate would be vacuous');const curSet=new Set(t.split(/\r?\n/).map(l=>l.trim()));const lost=[...baseSet].filter(l=>!curSet.has(l));if(lost.length>0)bad.push(f+' lost '+lost.length+' existing comment/jsDoc line(s), first: '+lost[0]);if(!fs.existsSync('script/build-resource.test.ts'))bad.push('script/build-resource.test.ts missing');const sp='.planning/phases/09-minimum-browser-runnable/09-22-SUMMARY.md';if(!fs.existsSync(sp))bad.push('09-22-SUMMARY.md missing');else{const sm=fs.readFileSync(sp,'utf8');for(const tok of ['defaults','.list.jsonc','node_modules','build:game','D-96','shouldReplay','gsd-09-22-jsdoc-baseline','uncalibrated']){if(sm.indexOf(tok)<0)bad.push('SUMMARY must record token: '+tok)}if(base&&sm.indexOf(base.head)<0)bad.push('SUMMARY must record jsdoc baseline HEAD sha '+base.head)}if(bad.length>0){console.error('CONTENT FILTER GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK content filter: list retention + Task-0 baseline ('+base.head.slice(0,8)+') comments intact ('+baseSet.size+' lines) + SUMMARY tokens')"</automated>
|
||||
<fails_when>non-zero exit，或 stderr 含 "CONTENT FILTER GATE FAILED"（`build-resource.ts` 缺 `.list.jsonc` / `defaults` / `basename` / `JSON.parse` 等值标记 / 既有导出改成别名或丢失（`minifyJSONC` / `buildContent` / `IContentBuildOptions` / `IContentBuildStats`）/ `chars: string` 丢失 / **`os.tmpdir()/gsd-09-22-jsdoc-baseline.json` 不存在或没有 `script/build-resource.ts` 的注释行（Task 0 未捕获基线）** / 基线 `head` 不是 40 位 SHA / 基线已含 `.list.jsonc` 或 `readListNames`（基线是在编辑后捕获的）/ **基线中的既有注释或 jsDoc 行在当前 `build-resource.ts` 中缺失（被删除或改写）** / 基线注释行数低于下限 8（门禁可能空洞）/ 缺测试文件 / 缺 SUMMARY 或 SUMMARY 未记录 `defaults`、`.list.jsonc`、`node_modules`、`build:game`、`D-96`、`shouldReplay`、`gsd-09-22-jsdoc-baseline`、`uncalibrated`，或未记录基线 `head` SHA）</fails_when>
|
||||
<automated>node -e "const fs=require('fs'),path=require('path');const bad=[];function names(f){const t=fs.readFileSync(f,'utf8').split(/\r?\n/).filter(l=>!l.trim().startsWith('//')).join('\n');const set=new Set();(function walk(v){if(typeof v==='string')set.add(v);else if(Array.isArray(v))v.forEach(walk);else if(v&&typeof v==='object')Object.values(v).forEach(walk)})(JSON.parse(t));return set}for(const d of ['animation','audio','font','maps','texture']){const dir=path.join('src','content',d);const list=path.join(dir,'.list.jsonc');if(!fs.existsSync(list)){bad.push('missing '+list);continue}const set=names(list);for(const e of fs.readdirSync(dir,{withFileTypes:true})){if(e.isDirectory()||e.name==='.list.jsonc')continue;const stem=e.name.slice(0,e.name.length-path.extname(e.name).length);if(!set.has(e.name)&&!set.has(stem))bad.push('unlisted asset would be dropped: '+path.join(dir,e.name))}}if(bad.length>0){console.error('CONTENT COVERAGE GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK content coverage: every existing asset under the 5 list folders is referenced by its list')"</automated>
|
||||
<fails_when>non-zero exit，或 stderr 含 "CONTENT COVERAGE GATE FAILED"：某个素材子文件夹缺 `.list.jsonc`，或该目录内存在既未被完整文件名、也未被去扩展名主文件名命中的现存素材（真实施加过滤后会丢文件）</fails_when>
|
||||
<automated>cmd /c "pnpm exec eslint script/build-plugin.ts script/build-resource.ts script/build-game.ts script/build-plugin.test.ts script/build-resource.test.ts"</automated>
|
||||
@ -339,13 +345,13 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
- 清单解析走 `minifyJSONC`（去注释）+ `JSON.parse` + 递归收集字符串；匹配仅「完整文件名」与「去扩展名主文件名」两种精确方式；`minifyJSONC` 行为未改（只剥离整行 `//` 注释）
|
||||
- 既有导出名称与签名（`minifyJSONC` / `buildContent` / `IContentBuildOptions`（`chars: string`）/ `IContentBuildStats` / `IContentBuildCounter`）未改；字体分支与告警文案未改
|
||||
- `script/build-resource.test.ts` 覆盖 9 类用例（根 jsonc、**根目录存在 `.list.jsonc` 仍全量**、`defaults` 全量（**`defaults/` 内存在 `.list.jsonc` 时仍全量**）、maps 清单（fixture 清单原文含 `//` 注释且输出已剥离）、texture 对象清单、font 清单、无清单子文件夹全量、`item.ts` 原样、统计），每个 `it` 前一行注释
|
||||
- `processDirectory` / `minifyJSONC` / `compressFont` / `buildContent` 与接口成员的既有 jsDoc **逐字未改**（由本任务的 `git show HEAD:script/build-resource.ts` 基线门禁证明，不依赖 git 暂存状态）；`script/build-plugin.ts` 的既有注释由 **Task 1 提交前**的同口径门禁证明（基线已含新导出即自失败）；过滤与删除的说明只写在新函数 / 新常量上
|
||||
- `processDirectory` / `minifyJSONC` / `compressFont` / `buildContent` 与接口成员的既有 jsDoc **逐字未改**（由与 **Task 0 捕获的 `os.tmpdir()/gsd-09-22-jsdoc-baseline.json`** 比对的注释门禁证明——**与 git 提交无关、Task 1 提交后重跑仍成立**）；`script/build-plugin.ts` 的既有注释由 **Task 1** 的同口径门禁（同一基线文件）证明；过滤与删除的说明只写在新函数 / 新常量上
|
||||
- 五个改动文件通过范围内的 `eslint`（`pnpm exec eslint` 零报告）
|
||||
- 真实 `src/content` 清单覆盖率门禁通过（现有素材无一被过滤掉）
|
||||
- `09-22-SUMMARY.md` 已写并含 6 个必需关键字与三项已知边界
|
||||
- `09-22-SUMMARY.md` 已写并含 8 个必需关键字、基线 `head` SHA（40 位）、`estimate.tokens=46000` **未校准**（`confidence: low`）的说明与三项已知边界
|
||||
- 未改 `packages-user/**` / `packages/**` / `src/**` / `package.json` / `index.html` / `dev.md` / `vite.config.ts` / lockfile / `script/dev.ts` / `script/build-lib.ts`
|
||||
</acceptance_criteria>
|
||||
<done>content 构建按清单过滤：`defaults/` 与无清单目录全量输出、根目录 `isRoot` 跳过过滤（即使出现 `.list.jsonc` 也不过滤）、5 个素材子文件夹只保留被引用文件、`.list.jsonc` 自身压缩输出、jsonc 仍压成纯 JSON；行为测试、`build-resource.ts` 的 HEAD 基线注释零丢失与真实清单覆盖率门禁全绿；范围内的 `eslint` 零报告；SUMMARY 记录两处修复与三项已知边界</done>
|
||||
<done>content 构建按清单过滤：`defaults/` 与无清单目录全量输出、根目录 `isRoot` 跳过过滤（即使出现 `.list.jsonc` 也不过滤）、5 个素材子文件夹只保留被引用文件、`.list.jsonc` 自身压缩输出、jsonc 仍压成纯 JSON；行为测试、`script/build-resource.ts` 与 Task 0 捕获基线的注释零丢失比对、真实清单覆盖率门禁全绿；范围内的 `eslint` 零报告；SUMMARY 记录两处修复、基线 SHA、未校准估算声明与三项已知边界</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
@ -378,9 +384,9 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- **Task 0：** 预执行状态（09-21 构建脚本为当前实现 / 23 个 jsonc / 5 个清单目录 / `defaults` 8 个 jsonc / 修饰器定义存在 / `script/build-resource.test.ts` 不存在）检查；人工关卡（用户回复「可以执行」；OI-1 / OI-2 / OI-3 若被改名须先修订计划再获批）；汇报须含三项已知边界与「既有 jsDoc 逐字保留」的说明。
|
||||
- **Task 1：** `script/build-plugin.ts` 结构（**按导出形态断言**：两个新导出 + `dataIsolationPlugin` 保留 / AST 定位标记 / `enforce: 'pre'` / `apply: 'build'` / `node_modules` 跳过，不硬编码提议命名）；`build-game` **按函数切片**断言（从 `./build-plugin` 的导入绑定推导新插件名——`dataIsolationPlugin` + 恰好 1 个新绑定，`buildClient` 与 `buildData` 各含该绑定、`buildData` 仍含隔离插件、隔离插件不进 `buildClient`、定义顺序未变）；`script/build-plugin.test.ts` 行为（删两类装饰器、参数含引号括号、字符串与注释不误删、`node_modules` 跳过、**对照式双装饰器** `vite.build()`：fixture 导出类 + 两个方法分别带 `@shouldReplay` / `@ignoreReplay` 且各返回 `mota_replay_probe` / `mota_ignore_probe` + 两个工厂本地不导出；`plugins: []` 对照产物含 `shouldReplay`、`ignoreReplay`、两个唯一字面量与两个方法名，带插件产物不含 `shouldReplay` / `ignoreReplay` 但两个唯一字面量与两个方法名仍在；结构门禁另行校验正/负向断言都在、工厂未被导出）；另加 `script/build-plugin.ts` 的「既有注释零丢失」门禁——**必须在 Task 1 的提交前执行**（`git show HEAD:script/build-plugin.ts` 基线，基线已含 `replayDecoratorPlugin` 即自失败）。
|
||||
- **Task 2：** `script/build-resource.ts` 结构（`.list.jsonc` / `defaults` / `basename` / `JSON.parse` 值标记、既有导出与 `chars: string` 未变、**`git show HEAD:script/build-resource.ts` 基线注释行零丢失**，并校验基线行数下限防止门禁空洞；`build-plugin.ts` 的同口径门禁在 Task 1 提交前执行）；`script/build-resource.test.ts` 行为（根 jsonc、**根目录存在 `.list.jsonc` 仍全量**、`defaults` 全量（含 `defaults/.list.jsonc` 时仍全量）、maps 清单保留与剔除 + 清单输出已剥离 `//`、texture 对象清单、font 清单、无清单子文件夹全量、`item.ts` 原样、统计）；真实 `src/content` **清单覆盖率**（5 个清单目录内现存素材必须全部被命中）；`eslint`（五个改动文件零报告）；SUMMARY 关键字。
|
||||
- **Task 0：** 预执行状态（09-21 构建脚本为当前实现 / 23 个 jsonc / 5 个清单目录 / `defaults` 8 个 jsonc / 修饰器定义存在 / `script/build-resource.test.ts` 不存在）检查；**jsDoc 基线一次性捕获**（`git rev-parse HEAD` + 两文件注释行集合写入 `os.tmpdir()/gsd-09-22-jsdoc-baseline.json`，幂等复用、行数下限与「不含新标识」自校验）；人工关卡（用户回复「可以执行」；OI-1 / OI-2 / OI-3 若被改名须先修订计划再获批）；汇报须含基线 SHA、三项已知边界与「既有 jsDoc 逐字保留」的说明。
|
||||
- **Task 1：** `script/build-plugin.ts` 结构（**按导出形态断言**：两个新导出 + `dataIsolationPlugin` 保留 / AST 定位标记 / `enforce: 'pre'` / `apply: 'build'` / `node_modules` 跳过，不硬编码提议命名）；`build-game` **按函数切片**断言（从 `./build-plugin` 的导入绑定推导新插件名——`dataIsolationPlugin` + 恰好 1 个新绑定，`buildClient` 与 `buildData` 各含该绑定、`buildData` 仍含隔离插件、隔离插件不进 `buildClient`、定义顺序未变）；`script/build-plugin.test.ts` 行为（删两类装饰器、参数含引号括号、字符串与注释不误删、`node_modules` 跳过、**对照式双装饰器** `vite.build()`：fixture 导出类 + 两个方法分别带 `@shouldReplay` / `@ignoreReplay` 且各返回 `mota_replay_probe` / `mota_ignore_probe` + 两个工厂本地不导出；`plugins: []` 对照产物含 `shouldReplay`、`ignoreReplay`、两个唯一字面量与两个方法名，带插件产物不含 `shouldReplay` / `ignoreReplay` 但两个唯一字面量与两个方法名仍在；结构门禁另行校验正/负向断言都在、工厂未被导出）；另加 `script/build-plugin.ts` 的「既有注释零丢失」门禁——**与 Task 0 捕获的 `os.tmpdir()/gsd-09-22-jsdoc-baseline.json` 比对**（**与 git 提交无关、可重复执行**，基线须为 40 位 `head`、行数 ≥5、不含 `replayDecoratorPlugin` / `removeReplayDecorators`）。
|
||||
- **Task 2：** `script/build-resource.ts` 结构（`.list.jsonc` / `defaults` / `basename` / `JSON.parse` 值标记、既有导出与 `chars: string` 未变、**与 Task 0 捕获的同一基线比对注释行零丢失**，并校验基线行数下限 8 防止门禁空洞）；`script/build-resource.test.ts` 行为（根 jsonc、**根目录存在 `.list.jsonc` 仍全量**、`defaults` 全量（含 `defaults/.list.jsonc` 时仍全量）、maps 清单保留与剔除 + 清单输出已剥离 `//`、texture 对象清单、font 清单、无清单子文件夹全量、`item.ts` 原样、统计）；真实 `src/content` **清单覆盖率**（5 个清单目录内现存素材必须全部被命中）；`eslint`（五个改动文件零报告）；SUMMARY 关键字 + 基线 `head` SHA + `estimate.tokens` 未校准声明。
|
||||
- **一致性：** `dist/content/**` 落点与 `src/data/constant.ts` 的 `content/core.jsonc` 一致；`build-game.ts` 的插件导入路径 `./build-plugin` 与 Task 1 产物一致；`script/build-resource.ts` 被 `build-game.ts` 以 `buildContent` / `IContentBuildOptions` 原名调用。
|
||||
- **无全仓门禁：** 不使用 `pnpm check:type` / `pnpm build` / 全量 `pnpm test:ci`（用户 WIP 存在历史类型错误）；本计划**不端到端运行全量** `build:game`。
|
||||
- **人工复核：** 结论（含三项已知边界）写入 `09-22-SUMMARY.md`。
|
||||
@ -391,8 +397,8 @@ Phase 9 · 任务 11 · 第 22 个计划 —— **构建脚本的 content 过滤
|
||||
- **用户裁定 2（修饰器）：** 构建时删除所有 `@shouldReplay` / `@ignoreReplay` 应用，数据端与渲染端都删；删除基于 TypeScript AST、不误伤字符串与注释、跳过 `node_modules`；**未手删任何 import**。
|
||||
- **用户裁定 3 / 4（边界）：** 只改构建脚本与其测试；未改 `build-lib.ts` / `package.json` / `index.html` / `dev.md` / `src/**` / `public/**` / `packages-user/**` / `packages/**` / `vite.config.ts` / lockfile / `script/dev.ts`；未改构建顺序；无特殊失败处理。
|
||||
- **D-93 / D-96 / D-98：** 任务 11 的构建脚本继续承担 content 处理；`build-game` 仍是唯一编排入口；未回退 09-21 已落地的数据端 ESM 产物与隔离检测。
|
||||
- **验证：** 两个测试文件与六个门禁（插件结构、content 结构 + `git show HEAD` 基线注释零丢失、真实清单覆盖率、`eslint`、SUMMARY 关键字，以及对照式**双装饰器** `vite.build()` 的正/负向双向断言）全部跑到确定结论；**未端到端运行全量 `build:game` 的事实已写入 SUMMARY**。
|
||||
- **注释纪律：** 既有 jsDoc / 注释逐字保留；新增说明只出现在新函数与新常量上（`build-plugin.ts` 由 Task 1 提交前的 HEAD 基线门禁证明、`build-resource.ts` 由 Task 2 的 HEAD 基线门禁证明）。
|
||||
- **验证：** 两个测试文件与六个门禁（插件结构、content 结构 + 与 **Task 0 捕获基线**比对的注释零丢失、真实清单覆盖率、`eslint`、SUMMARY 关键字 + 基线 SHA，以及对照式**双装饰器** `vite.build()` 的正/负向双向断言）全部跑到确定结论；**未端到端运行全量 `build:game` 的事实已写入 SUMMARY**；SUMMARY 同时声明 `estimate.tokens=46000` 为**未校准**估算（`confidence: low`）。
|
||||
- **注释纪律：** 既有 jsDoc / 注释逐字保留；新增说明只出现在新函数与新常量上（`build-plugin.ts` 与 `build-resource.ts` 都由同一个 **Task 0 捕获的临时基线**证明——门禁在逐 task 提交后重跑仍成立，不依赖「提交前」时序）。
|
||||
- **已知边界：** 生产产物不再产生录像安全检查信息（预期）；`index.html` 仍引用 `/styles.css`（09-21 已记录）；`animation` / `audio` / `font` 当前无素材，其过滤规则由测试覆盖。
|
||||
</success_criteria>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user