test(app): harden manualChunks pins and comments

Author: Aparencia

app/src/build/manualChunks.test.ts

@@ -12,7 +12,7 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
-import { manualChunks, packageNameOf, vendorGroupOf, type VendorGroup } from "./manualChunks";
+import { EXACT, manualChunks, packageNameOf, vendorGroupOf, type VendorGroup } from "./manualChunks";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -104,3 +104,148 @@ describe("覆盖闸：package.json 的每个运行时依赖都必须有归属",
     expect(ungrouped).toEqual([]);
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Task 3 加固（评审 task-3-review.md Important-1 / Minor-2）。以上 40 条一字未动，
+// 以下全是**加测试**；实现侧只多一个 `export const EXACT` 供键集断言用，分组逻辑零改动。
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * EXACT 表的**全量字面钉值**（Minor-2：原 49 条里 28 条无钉值 ⇒ 改错分组不报错）。
+ * 期望值必须**字面写死**、不能从实现里读出来比对：期望若取自被审查的同一张表，
+ * 「把 `bail` 挪进 `vendor-katex`」这类编辑会连期望值一起改，断言恒真（自指空转）。
+ * 键集一致断言（本段最后一条）补齐另一半：新增/删除登记行也必须同步改这里。
+ */
+const EXACT_PINS: readonly (readonly [string, VendorGroup])[] = [
+  ["gsap", "vendor-gsap"],
+  ["@gsap/react", "vendor-gsap"],
+  ["react", "vendor-react"],
+  ["react-dom", "vendor-react"],
+  ["scheduler", "vendor-react"],
+  ["@tauri-apps/api", "vendor-tauri"],
+  ["@tauri-apps/plugin-dialog", "vendor-tauri"],
+  ["katex", "vendor-katex"],
+  ["rehype-katex", "vendor-katex"],
+  ["hast-util-from-dom", "vendor-katex"],
+  ["hast-util-to-text", "vendor-katex"],
+  ["hast-util-from-html-isomorphic", "vendor-katex"],
+  ["hast-util-is-element", "vendor-katex"],
+  ["hast-util-parse-selector", "vendor-katex"],
+  ["hastscript", "vendor-katex"],
+  ["property-information", "vendor-katex"],
+  ["web-namespaces", "vendor-katex"],
+  ["codemirror", "vendor-editor"],
+  ["crelt", "vendor-editor"],
+  ["style-mod", "vendor-editor"],
+  ["w3c-keyname", "vendor-editor"],
+  ["classcat", "vendor-canvas"],
+  ["zustand", "vendor-canvas"],
+  ["use-sync-external-store", "vendor-canvas"],
+  ["react-markdown", "vendor-md"],
+  ["unified", "vendor-md"],
+  ["bail", "vendor-md"],
+  ["trough", "vendor-md"],
+  ["vfile", "vendor-md"],
+  ["vfile-message", "vendor-md"],
+  ["extend", "vendor-md"],
+  ["is-plain-obj", "vendor-md"],
+  ["devlop", "vendor-md"],
+  ["zwitch", "vendor-md"],
+  ["ccount", "vendor-md"],
+  ["longest-streak", "vendor-md"],
+  ["markdown-table", "vendor-md"],
+  ["trim-lines", "vendor-md"],
+  ["escape-string-regexp", "vendor-md"],
+  ["decode-named-character-reference", "vendor-md"],
+  ["comma-separated-tokens", "vendor-md"],
+  ["space-separated-tokens", "vendor-md"],
+  ["html-url-attributes", "vendor-md"],
+  ["style-to-js", "vendor-md"],
+  ["style-to-object", "vendor-md"],
+  ["inline-style-parser", "vendor-md"],
+  ["estree-util-is-identifier-name", "vendor-md"],
+  ["@ungap/structured-clone", "vendor-md"],
+  ["@types/katex", "vendor-katex"],
+];
+
+/**
+ * PREFIX 族的**有效**钉值（Minor-2：`^rehype-` / `^vfile` 原先没有任何由它们决定分组的
+ * 钉值 —— `rehype-katex` / `vfile` 都被 EXACT 抢走 ⇒ 改前缀的组不会变红）。
+ * 每个前缀一条代表；`EXACT[name]` 必须为 undefined 是**有效性判据**：代表一旦被 EXACT
+ * 接管，这条钉值就不再约束前缀表（原缺口正是这么产生的）。
+ */
+const PREFIX_PINS: readonly (readonly [string, VendorGroup])[] = [
+  ["@codemirror/view", "vendor-editor"],
+  ["@lezer/common", "vendor-editor"],
+  ["@marijn/find-cluster-break", "vendor-editor"],
+  ["@xyflow/system", "vendor-canvas"],
+  ["d3-zoom", "vendor-canvas"],
+  ["micromark", "vendor-md"],
+  ["mdast-util-to-hast", "vendor-md"],
+  ["hast-util-to-jsx-runtime", "vendor-md"],
+  ["unist-util-visit", "vendor-md"],
+  ["remark-gfm", "vendor-md"],
+  ["rehype-raw", "vendor-md"], // 未安装（惰性，同 gsap 行）：冻结 `^rehype-` 族归属本身
+  ["vfile-location", "vendor-md"], // 已随 react-markdown 装上且非 EXACT ⇒ 真由 `^vfile` 决定
+];
+
+describe("EXACT 表全量钉值（Minor-2：28/49 条原先无钉值）", () => {
+  for (const [name, group] of EXACT_PINS) {
+    it(`EXACT ${name} → ${group}`, () => {
+      expect(EXACT[name]).toBe(group); // 表内字面值
+      const id = `/r/node_modules/${name}/index.js`;
+      expect(vendorGroupOf(id)).toBe(group); // 解析路径：packageNameOf → EXACT
+      expect(manualChunks(id)).toBe(group); // 接线面：Task 4 接的正是它
+    });
+  }
+
+  it("EXACT 键集与钉值表逐字一致（新增/删除登记行必须同步钉值）", () => {
+    expect(Object.keys(EXACT).sort()).toEqual(EXACT_PINS.map(([n]) => n).sort());
+  });
+});
+
+describe("PREFIX 族有效钉值（每个前缀至少一条由它决定分组）", () => {
+  for (const [name, group] of PREFIX_PINS) {
+    it(`PREFIX ${name} → ${group}`, () => {
+      expect(EXACT[name]).toBeUndefined(); // 有效性：确实由前缀表决定，未被 EXACT 接管
+      expect(vendorGroupOf(`/r/node_modules/${name}/index.js`)).toBe(group);
+    });
+  }
+});
+
+describe("确定性与无状态（Important-1：原 40 条对跨调用/跨顺序零约束）", () => {
+  // 覆盖四类 id，且**走到末尾 `return undefined` 的未登记包恰为 2 个（偶数）**：
+  // 「逆序重放」只有在此数为偶数时才能观察到「按调用计数」的状态 —— 若为奇数，
+  // 正序与逆序给同一 id 的计数奇偶相同、抖动互相抵消，断言会假绿。
+  const ids: readonly string[] = [
+    "/r/node_modules/react/index.js", // EXACT
+    "/r/node_modules/bail/lib/index.js", // EXACT（加固前无钉值的 28 条之一）
+    "/r/node_modules/remark-gfm/index.js", // PREFIX ^remark-
+    "/r/node_modules/@xyflow/react/dist/index.js", // EXACT（裸 token 陷阱）
+    "/r/node_modules/katex/dist/katex.mjs", // EXACT
+    "/r/node_modules/not-a-real-package/index.js", // 未登记 ①（末尾 return undefined）
+    "/r/node_modules/zzz-also-not-real/index.js", // 未登记 ②（同上）
+    "/r/app/src/App.tsx", // 非 node_modules（提前 return，不计数）
+    "/r/vendor/node_modules_backup/react/index.js", // 伪路径（同上）
+  ];
+
+  it("同一 id 连续两次调用结果相同（计数器/缓存类跨调用状态必红）", () => {
+    for (const id of ids) expect(manualChunks(id)).toBe(manualChunks(id));
+  });
+
+  it("逆序重放后逐 id 映射与正序相同（无顺序依赖）", () => {
+    expect(ids.map(manualChunks)).toEqual([...ids].reverse().map(manualChunks).reverse());
+  });
+});
+
+describe("接线面全量一致（manualChunks 不许有第二套逻辑）", () => {
+  it("整份混合列表上 manualChunks 与 vendorGroupOf 逐元素相同", () => {
+    const ids = [
+      "/r/node_modules/react/index.js",
+      "/r/node_modules/bail/lib/index.js",
+      "/r/node_modules/not-a-real-package/index.js",
+      "/r/app/src/App.tsx",
+    ];
+    expect(ids.map(manualChunks)).toEqual(ids.map((id) => vendorGroupOf(id)));
+  });
+});

app/src/build/manualChunks.ts

@@ -3,10 +3,13 @@
  *
  * @ai-context: 批 2 包体治理的原子层。Vite 的 `build.rollupOptions.output.manualChunks`
  *              接收模块 id，返回 chunk 名；返回 `undefined` 表示「交回 rollup 默认算法」。
- * @ai-context: 为什么**必须按「解析出的包名」精确匹配**，而不是 `id.includes("node_modules/react")`：
- *              本仓实测的子串碰撞 —— `node_modules/react` 同时是
- *              `react-dom` / `react-markdown` / `@xyflow/react` 的子串。用 includes 会把
- *              markdown 栈与画布栈并进 `vendor-react`，懒加载边界**静默失效**
+ * @ai-context: 为什么**必须按「解析出的包名」精确匹配**，而不是 `id.includes(...)`：
+ *              本仓实测（单测 `manualChunks.test.ts` 的「子串碰撞陷阱」段即机器判据）——
+ *              裸 token `react` 才是 `react-dom` / `react-markdown` / `@xyflow/react` 三者的
+ *              共同子串；`@xyflow/react` 的模块 id 里**没有**连续子串 `node_modules/react`
+ *              （中间隔着 `@xyflow/`）。于是两种朴素口径各错一半：裸 `includes("react")`
+ *              把 markdown 栈与画布栈一起吞进 `vendor-react`；`includes("node_modules/react")`
+ *              只吞前两者，把画布栈**漏回 rollup 默认算法**。两者都让懒加载边界**静默失效**
  *              （构建照样成功、gzip 照样降一点，但批 6 的 GSAP 独立 chunk 承诺当场落空）。
  *              这是批 1 六例「裸 includes 判活」教训在构建配置上的镜像。
  * @ai-context: 为什么 GSAP 现在就在表里（而依赖还没装）：规格 §13 风险表要求
@@ -29,8 +32,11 @@ export type VendorGroup =
   | "vendor-canvas"
   | "vendor-md";
 
-/** 精确包名 → 分组。**先于前缀族匹配**，因此 `rehype-katex` 不会被 `rehype-` 抢走。 */
-const EXACT: Readonly<Record<string, VendorGroup>> = {
+/** 精确包名 → 分组。**先于前缀族匹配**，因此 `rehype-katex` 不会被 `rehype-` 抢走。
+ *  导出**只为单测**：钉值表要能断言「本表每一条都有字面钉值、且键集与钉值表逐字一致」
+ *  （评审 Minor-2 —— 28/49 条无钉值时，把 `bail` 挪进 `vendor-katex` 不会变红）。
+ *  生产代码不得 import 它（分组只能经 `vendorGroupOf` / `manualChunks` 表达）。 */
+export const EXACT: Readonly<Record<string, VendorGroup>> = {
   // 批 6 预留（本批不安装；规则惰性，见文件头注释）
   gsap: "vendor-gsap",
   "@gsap/react": "vendor-gsap",

app/vite.config.ts

@@ -13,8 +13,11 @@ export default defineConfig(async () => ({
   // Why 放在这里而不是对象形式 `{ "vendor-react": ["react", …] }`：
   //   ① 对象形式在包未安装时**直接让构建失败**（rollup 解析不到入口），
   //      而本批必须为批 6 的 GSAP 预留一个「现在惰性、将来自动生效」的槽；
-  //   ② 函数形式可以按**解析出的包名**精确匹配，避开 `node_modules/react`
-  //      同时是 react-dom / react-markdown / @xyflow/react 子串的碰撞陷阱。
+  //   ② 函数形式可以按**解析出的包名**精确匹配：实测**裸 token `react`** 才是 react-dom /
+  //      react-markdown / @xyflow/react 三者的共同子串，而 `node_modules/react` **不是**
+  //      （`@xyflow/react` 的 id 中间隔着 `@xyflow/`）。用 id.includes 一类朴素口径会把
+  //      markdown 栈与画布栈一起吞进 react chunk、或把画布栈漏回 rollup 默认算法 ——
+  //      两种都让懒加载边界静默失效（判据见 src/build/manualChunks.test.ts）。
   // 规则与单测见 src/build/manualChunks.ts（纯函数，tsc 与 vitest 都覆盖得到）。
   build: {
     rollupOptions: {