miaoda-game-devkit 0.1.1 → 0.2.1

package/dist/lint/phaser-text-assertions.contract.mjs

@@ -12,7 +12,9 @@ function collectMissingBitmapGlyphs(text, chars) {
     const code = text.charCodeAt(index);
     if (seen.has(code) || chars[code] !== void 0) continue;
     seen.add(code);
-    missing.push(`${JSON.stringify(character)} (U+${code.toString(16).toUpperCase().padStart(4, "0")})`);
+    missing.push(
+      `${JSON.stringify(character)} (U+${code.toString(16).toUpperCase().padStart(4, "0")})`
+    );
   }
   return missing;
 }

package/dist/lint/setup.mjs

@@ -12,43 +12,40 @@ function createCanvasContext(canvas) {
     canvas,
     font: "16px sans-serif"
   };
-  const context = new Proxy(
-    state,
-    {
-      get(target, property) {
-        if (property in target) {
-          return target[property];
-        }
-        if (property === "createImageData" || property === "getImageData") {
-          return (...args) => imageData(args.at(-2), args.at(-1));
-        }
-        if (property === "measureText") {
-          return (value) => {
-            const font = String(target.font ?? "16px sans-serif");
-            const size = Number.parseFloat(font.match(/([\d.]+)px/)?.[1] ?? "16");
-            const width = [...String(value)].reduce((total, character) => {
-              if (/\s/.test(character)) return total + size * 0.33;
-              if (/[^\u0000-\u00ff]/.test(character)) return total + size;
-              if (/[MW@#%&]/.test(character)) return total + size * 0.9;
-              if (/[ilI1.,'`]/.test(character)) return total + size * 0.32;
-              if (/[A-Z0-9]/.test(character)) return total + size * 0.64;
-              return total + size * 0.56;
-            }, 0);
-            return {
-              width,
-              actualBoundingBoxAscent: size * 0.8,
-              actualBoundingBoxDescent: size * 0.2
-            };
+  const context = new Proxy(state, {
+    get(target, property) {
+      if (property in target) {
+        return target[property];
+      }
+      if (property === "createImageData" || property === "getImageData") {
+        return (...args) => imageData(args.at(-2), args.at(-1));
+      }
+      if (property === "measureText") {
+        return (value) => {
+          const font = String(target.font ?? "16px sans-serif");
+          const size = Number.parseFloat(font.match(/([\d.]+)px/)?.[1] ?? "16");
+          const width = [...String(value)].reduce((total, character) => {
+            if (/\s/.test(character)) return total + size * 0.33;
+            if (/[^\u0000-\u00ff]/.test(character)) return total + size;
+            if (/[MW@#%&]/.test(character)) return total + size * 0.9;
+            if (/[ilI1.,'`]/.test(character)) return total + size * 0.32;
+            if (/[A-Z0-9]/.test(character)) return total + size * 0.64;
+            return total + size * 0.56;
+          }, 0);
+          return {
+            width,
+            actualBoundingBoxAscent: size * 0.8,
+            actualBoundingBoxDescent: size * 0.2
           };
-        }
-        if (property === "createLinearGradient" || property === "createRadialGradient") {
-          return () => ({ addColorStop() {
-          } });
-        }
-        return () => void 0;
+        };
       }
+      if (property === "createLinearGradient" || property === "createRadialGradient") {
+        return () => ({ addColorStop() {
+        } });
+      }
+      return () => void 0;
     }
-  );
+  });
   return context;
 }
 HTMLCanvasElement.prototype.getContext = function getContext(contextId) {

package/dist/lint/vitest-config.contract.mjs

@@ -5,12 +5,345 @@ import { describe, expect, it } from "vitest";
 // src/vitest-config.ts
 import { createRequire } from "module";
 import { dirname, resolve } from "path";
-import {
-  defineConfig
-} from "vitest/config";
+import { defineConfig } from "vitest/config";
+
+// src/gameplay-audit.ts
+function normalizeList(value) {
+  if (value === void 0) return [];
+  const values = typeof value === "string" ? [value] : value;
+  return [...new Set(values.map((item) => item.trim()).filter(Boolean))];
+}
+function normalizeSet(values) {
+  return [
+    ...new Set(values.map((value) => value.trim()).filter(Boolean))
+  ].sort();
+}
+function sameSet(left, right) {
+  return JSON.stringify(normalizeSet(left)) === JSON.stringify(normalizeSet(right));
+}
+function normalizeGameplayRequirements(requirements, scenes) {
+  const requiredScenes = normalizeSet([
+    ...scenes,
+    ...normalizeList(requirements.requireScene)
+  ]);
+  return {
+    requireInput: requirements.requireInput || void 0,
+    requireFrameAdvance: requirements.requireFrameAdvance || void 0,
+    requirePhysicsStep: requirements.requirePhysicsStep || void 0,
+    requireTransition: normalizeList(requirements.requireTransition),
+    requireScene: requiredScenes,
+    requireRestart: normalizeList(requirements.requireRestart),
+    requireCheckpoint: normalizeList(requirements.requireCheckpoint),
+    requireDestroy: true
+  };
+}
+function createGameplayContractMetadata(contract) {
+  const scenes = normalizeSet(contract.scenes);
+  return {
+    id: contract.id.trim(),
+    scenes,
+    requirements: normalizeGameplayRequirements(contract, scenes),
+    verified: false
+  };
+}
+function validateGameplayAuditOptions(options) {
+  const issues = [];
+  const scenes = normalizeSet(options.scenes);
+  if (scenes.length === 0) issues.push("gameplayAudit.scenes \u4E0D\u80FD\u4E3A\u7A7A\u3002");
+  if (scenes.length !== options.scenes.length) {
+    issues.push("gameplayAudit.scenes \u4E0D\u80FD\u5305\u542B\u7A7A\u503C\u6216\u91CD\u590D Scene key\u3002");
+  }
+  const contractIds = /* @__PURE__ */ new Set();
+  const coveredScenes = /* @__PURE__ */ new Set();
+  for (const contract of options.contracts) {
+    const id = contract.id.trim();
+    if (!id) {
+      issues.push("gameplayAudit.contracts \u4E2D\u5B58\u5728\u7A7A contract id\u3002");
+    } else if (id !== contract.id) {
+      issues.push(`contract id "${contract.id}" \u4E0D\u80FD\u5305\u542B\u9996\u5C3E\u7A7A\u767D\u3002`);
+    } else if (contractIds.has(id)) {
+      issues.push(`gameplayAudit.contracts \u5305\u542B\u91CD\u590D contract id\uFF1A${id}\u3002`);
+    } else {
+      contractIds.add(id);
+    }
+    const testFile = contract.testFile.replaceAll("\\", "/");
+    if (!/^tests\/.+\.test\.ts$/.test(testFile) || testFile.split("/").includes("..")) {
+      issues.push(
+        `contract "${id || "<empty>"}" \u7684 testFile \u5FC5\u987B\u5339\u914D tests/**/*.test.ts\u3002`
+      );
+    }
+    const contractScenes = normalizeSet(contract.scenes);
+    if (contractScenes.length === 0) {
+      issues.push(`contract "${id || "<empty>"}" \u5FC5\u987B\u58F0\u660E\u81F3\u5C11\u4E00\u4E2A Scene\u3002`);
+    }
+    for (const scene of contractScenes) {
+      coveredScenes.add(scene);
+      if (!scenes.includes(scene)) {
+        issues.push(
+          `contract "${id}" \u5F15\u7528\u4E86\u672A\u5217\u5165 gameplayAudit.scenes \u7684 Scene\uFF1A${scene}\u3002`
+        );
+      }
+    }
+  }
+  for (const scene of scenes) {
+    if (!coveredScenes.has(scene)) {
+      issues.push(`Scene "${scene}" \u6CA1\u6709\u4EFB\u4F55 gameplay contract \u8D1F\u8D23\u9A8C\u8BC1\u3002`);
+    }
+  }
+  if (options.contracts.length === 0)
+    issues.push("gameplayAudit.contracts \u4E0D\u80FD\u4E3A\u7A7A\u3002");
+  return issues;
+}
+function getDefinitionIssues(expected, actual) {
+  const issues = [];
+  const expectedMetadata = createGameplayContractMetadata(expected);
+  if (!sameSet(expectedMetadata.scenes, actual.scenes)) {
+    issues.push(
+      `contract "${expected.id}" \u58F0\u660E\u7684 Scene \u4E0E gameplayAudit \u6E05\u5355\u4E0D\u4E00\u81F4\u3002`
+    );
+  }
+  if (JSON.stringify(expectedMetadata.requirements) !== JSON.stringify(actual.requirements)) {
+    issues.push(
+      `contract "${expected.id}" \u7684 evidence requirements \u4E0E gameplayAudit \u6E05\u5355\u4E0D\u4E00\u81F4\u3002`
+    );
+  }
+  return issues;
+}
+function auditGameplayCollection(options, file, tests) {
+  const normalizedFile = file.replaceAll("\\", "/");
+  const expected = options.contracts.filter(
+    (contract) => contract.testFile.replaceAll("\\", "/") === normalizedFile
+  );
+  const actual = tests.filter((test) => test.metadata);
+  const issues = [];
+  for (const contract of expected) {
+    const matches = actual.filter((test) => test.metadata?.id === contract.id);
+    if (matches.length === 0) {
+      issues.push(
+        `\u6D4B\u8BD5\u6267\u884C\u524D\u672A\u6536\u96C6\u5230 contract "${contract.id}"\uFF08${normalizedFile}\uFF09\u3002`
+      );
+    } else if (matches.length > 1) {
+      issues.push(
+        `contract "${contract.id}" \u5728 ${normalizedFile} \u4E2D\u91CD\u590D\u5B9A\u4E49\u3002`
+      );
+    } else if (matches[0]?.metadata) {
+      issues.push(...getDefinitionIssues(contract, matches[0].metadata));
+    }
+  }
+  for (const test of actual) {
+    const id = test.metadata?.id;
+    if (!id) continue;
+    const expectedContract = options.contracts.find(
+      (contract) => contract.id === id
+    );
+    if (!expectedContract) {
+      issues.push(
+        `\u6D4B\u8BD5 "${test.name}" \u58F0\u660E\u4E86\u672A\u5217\u5165 gameplayAudit \u6E05\u5355\u7684 contract "${id}"\u3002`
+      );
+    } else if (expectedContract.testFile.replaceAll("\\", "/") !== normalizedFile) {
+      issues.push(
+        `contract "${id}" \u5FC5\u987B\u4F4D\u4E8E ${expectedContract.testFile}\uFF0C\u5B9E\u9645\u4F4D\u4E8E ${normalizedFile}\u3002`
+      );
+    }
+  }
+  return { passed: issues.length === 0, issues };
+}
+function getGameplayEvidenceIssues(id, requirements, evidence) {
+  const issues = [];
+  const inputEvents = evidence.mouseEvents + evidence.keyboardEvents + evidence.touchEvents;
+  if (requirements.requireInput && inputEvents === 0)
+    issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002`);
+  if (requirements.requireFrameAdvance && evidence.frames === 0)
+    issues.push(`contract "${id}" \u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27\u3002`);
+  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0)
+    issues.push(`contract "${id}" \u672A\u63A8\u8FDB Arcade Physics\u3002`);
+  for (const target of normalizeList(requirements.requireTransition)) {
+    if (!evidence.transitions.some((transition) => transition.to === target)) {
+      issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u5230 ${target} \u7684 Scene \u8F6C\u573A\u3002`);
+    }
+  }
+  for (const scene of normalizeList(requirements.requireScene)) {
+    if (!evidence.visitedScenes.includes(scene))
+      issues.push(`contract "${id}" \u672A\u8BBF\u95EE Scene "${scene}"\u3002`);
+  }
+  for (const scene of normalizeList(requirements.requireRestart)) {
+    if (!evidence.restartedScenes.includes(scene))
+      issues.push(`contract "${id}" \u672A\u91CD\u542F Scene "${scene}"\u3002`);
+  }
+  for (const checkpoint of normalizeList(requirements.requireCheckpoint)) {
+    if (!evidence.checkpoints.includes(checkpoint))
+      issues.push(`contract "${id}" \u7F3A\u5C11 checkpoint "${checkpoint}"\u3002`);
+  }
+  if (requirements.requireDestroy && !evidence.destroyed)
+    issues.push(`contract "${id}" \u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1\u3002`);
+  return issues;
+}
+function auditGameplayRun(options, tests) {
+  const issues = [];
+  const actualContracts = tests.filter((test) => test.metadata);
+  const acceptedEvidence = [];
+  for (const expected of options.contracts) {
+    const matches = actualContracts.filter(
+      (test2) => test2.metadata?.id === expected.id
+    );
+    if (matches.length === 0) {
+      issues.push(`\u7F3A\u5C11 gameplay contract "${expected.id}"\u3002`);
+      continue;
+    }
+    if (matches.length > 1) {
+      issues.push(`gameplay contract "${expected.id}" \u88AB\u591A\u4E2A\u6D4B\u8BD5\u91CD\u590D\u58F0\u660E\u3002`);
+      continue;
+    }
+    const test = matches[0];
+    const metadata = test?.metadata;
+    if (!test || !metadata) continue;
+    if (test.file.replaceAll("\\", "/") !== expected.testFile.replaceAll("\\", "/")) {
+      issues.push(
+        `contract "${expected.id}" \u5FC5\u987B\u4F4D\u4E8E ${expected.testFile}\uFF0C\u5B9E\u9645\u4F4D\u4E8E ${test.file}\u3002`
+      );
+    }
+    issues.push(...getDefinitionIssues(expected, metadata));
+    if (test.state !== "passed") {
+      issues.push(`contract "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      continue;
+    }
+    if (!metadata.verified || !metadata.evidence) {
+      issues.push(`contract "${expected.id}" \u672A\u5B8C\u6210 onTestFinished \u8BC1\u636E\u6821\u9A8C\u3002`);
+      continue;
+    }
+    const evidenceIssues = getGameplayEvidenceIssues(
+      expected.id,
+      metadata.requirements,
+      metadata.evidence
+    );
+    issues.push(...evidenceIssues);
+    if (evidenceIssues.length === 0) acceptedEvidence.push(metadata.evidence);
+  }
+  for (const test of actualContracts) {
+    const id = test.metadata?.id;
+    if (id && !options.contracts.some((contract) => contract.id === id)) {
+      issues.push(
+        `\u53D1\u73B0\u672A\u5217\u5165 gameplayAudit \u6E05\u5355\u7684 contract "${id}"\uFF08${test.file}\uFF09\u3002`
+      );
+    }
+  }
+  const registeredScenes = normalizeSet(
+    acceptedEvidence.flatMap((evidence) => evidence.registeredScenes)
+  );
+  const expectedScenes = normalizeSet(options.scenes);
+  for (const scene of expectedScenes) {
+    if (!registeredScenes.includes(scene))
+      issues.push(
+        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u4EFB\u4F55\u901A\u8FC7\u5BA1\u8BA1\u7684 host registry \u4E2D\u3002`
+      );
+  }
+  for (const scene of registeredScenes) {
+    if (!expectedScenes.includes(scene))
+      issues.push(
+        `host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "${scene}"\u3002`
+      );
+  }
+  return { passed: issues.length === 0, issues: [...new Set(issues)] };
+}
+
+// src/gameplay-audit-reporter.ts
+import { relative } from "path";
+function normalizePath(path) {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function isGameplayContractMetadata(value) {
+  if (!value || typeof value !== "object") return false;
+  const record = value;
+  return typeof record.id === "string" && Array.isArray(record.scenes) && Boolean(record.requirements) && typeof record.requirements === "object";
+}
+function toAuditTest(test) {
+  const metadata = test.meta().gameplayContract;
+  return {
+    file: normalizePath(test.module.relativeModuleId),
+    name: test.fullName,
+    state: test.result().state,
+    metadata: isGameplayContractMetadata(metadata) ? metadata : void 0
+  };
+}
+function printIssues(stage, issues) {
+  if (issues.length === 0) return;
+  console.error(`
+GAMEPLAY_AUDIT: ${stage} FAILED`);
+  for (const issue of issues) console.error(`- ${issue}`);
+}
+var GameplayAuditReporter = class {
+  projectRoot;
+  options;
+  preflightIssues = /* @__PURE__ */ new Set();
+  /** 创建绑定到单个游戏项目根目录和权威清单的 reporter。 */
+  constructor(projectRoot2, options) {
+    this.projectRoot = projectRoot2;
+    this.options = options;
+  }
+  /** 每次 Vitest 运行开始时重置预检状态，并检查清单中的测试文件是否会执行。 */
+  onTestRunStart(specifications) {
+    this.preflightIssues.clear();
+    const scheduledFiles = new Set(
+      specifications.map(
+        (specification) => normalizePath(relative(this.projectRoot, specification.moduleId))
+      )
+    );
+    for (const contract of this.options.contracts) {
+      const testFile = normalizePath(contract.testFile);
+      if (!scheduledFiles.has(testFile)) {
+        this.reportPreflightIssue(
+          `contract "${contract.id}" \u7684\u6D4B\u8BD5\u6587\u4EF6\u672A\u8FDB\u5165\u672C\u6B21 Vitest \u8FD0\u884C\uFF1A${testFile}\u3002`
+        );
+      }
+    }
+  }
+  /** 在测试文件执行前检查静态 metadata 是否声明了该文件负责的全部 contract。 */
+  onTestModuleCollected(testModule) {
+    const file = normalizePath(testModule.relativeModuleId);
+    const tests = [...testModule.children.allTests()].map(toAuditTest);
+    const result = auditGameplayCollection(this.options, file, tests);
+    for (const issue of result.issues) this.reportPreflightIssue(issue);
+  }
+  /** 在测试运行结束后汇总全部 contract、Ledger 和 Scene registry，并决定命令退出码。 */
+  onTestRunEnd(testModules) {
+    const tests = testModules.flatMap(
+      (testModule) => [...testModule.children.allTests()].map(toAuditTest)
+    );
+    const result = auditGameplayRun(this.options, tests);
+    if (!result.passed) {
+      printIssues("FINAL", result.issues);
+      process.exitCode = 1;
+    } else {
+      console.log(
+        `
+GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${this.options.contracts.length} contracts, ${this.options.scenes.length} scenes)`
+      );
+    }
+  }
+  /** 立即输出一个此前未报告过的预检缺口，并让本次测试命令失败。 */
+  reportPreflightIssue(issue) {
+    if (this.preflightIssues.has(issue)) return;
+    this.preflightIssues.add(issue);
+    printIssues("PREFLIGHT", [issue]);
+    process.exitCode = 1;
+  }
+};
+
+// src/vitest-config.ts
 function defineGameVitestConfig(options) {
-  const projectRequire = createRequire(resolve(options.projectRoot, "package.json"));
-  const phaserPackageRoot = dirname(projectRequire.resolve("phaser/package.json"));
+  const auditIssues = validateGameplayAuditOptions(options.gameplayAudit);
+  if (auditIssues.length > 0) {
+    throw new Error(
+      `\u65E0\u6548\u7684 gameplayAudit \u914D\u7F6E\uFF1A
+- ${auditIssues.join("\n- ")}`
+    );
+  }
+  const projectRequire = createRequire(
+    resolve(options.projectRoot, "package.json")
+  );
+  const phaserPackageRoot = dirname(
+    projectRequire.resolve("phaser/package.json")
+  );
   const phaserBrowserBuild = resolve(phaserPackageRoot, "dist/phaser.js");
   return defineConfig({
     resolve: {
@@ -26,7 +359,10 @@ function defineGameVitestConfig(options) {
       hookTimeout: options.hookTimeout,
       server: {
         deps: {
-          inline: [/miaoda-game-/]
+          // devkit 模块需要在配置和审计阶段使用 Node 内置模块。
+          // 如果强制内联，Vite 会把这些模块按浏览器模块转换，
+          // 最终触发 "No such built-in module: node:"。
+          external: [/miaoda-game-devkit/]
         }
       },
       environment: "jsdom",
@@ -39,6 +375,10 @@ function defineGameVitestConfig(options) {
         "miaoda-game-devkit/vitest-setup",
         ...options.additionalSetupFiles ?? []
       ],
+      reporters: [
+        "default",
+        new GameplayAuditReporter(options.projectRoot, options.gameplayAudit)
+      ],
       restoreMocks: true,
       clearMocks: true,
       coverage: {
@@ -62,18 +402,35 @@ function defineGameVitestConfig(options) {
 
 // src/lint/vitest-config.test.ts
 var projectRoot = resolve2(import.meta.dirname, "../..");
+var gameplayAudit = {
+  scenes: ["InputScene"],
+  contracts: [
+    {
+      id: "InputScene.boot",
+      testFile: "tests/input.test.ts",
+      scenes: ["InputScene"],
+      requireFrameAdvance: true
+    }
+  ]
+};
 describe("defineGameVitestConfig", () => {
   it("\u63D0\u4F9B Phaser \u8FD0\u884C\u65F6\u6D4B\u8BD5\u9700\u8981\u7684\u56FA\u5B9A\u57FA\u7EBF", () => {
-    const config = defineGameVitestConfig({ projectRoot });
+    const config = defineGameVitestConfig({ projectRoot, gameplayAudit });
     expect(config.resolve?.alias).toMatchObject({
       "@": resolve2(projectRoot, "src"),
       phaser: expect.stringContaining("phaser/dist/phaser.js")
     });
     expect(config.test).toMatchObject({
       include: ["tests/**/*.test.ts"],
+      server: {
+        deps: {
+          external: [/miaoda-game-devkit/]
+        }
+      },
       environment: "jsdom",
       environmentOptions: { jsdom: { url: "http://localhost/" } },
       setupFiles: ["miaoda-game-devkit/vitest-setup"],
+      reporters: ["default", expect.any(Object)],
       restoreMocks: true,
       clearMocks: true,
       coverage: {
@@ -96,18 +453,27 @@ describe("defineGameVitestConfig", () => {
   it("\u4FDD\u7559\u5B89\u5168\u6269\u5C55\u5E76\u5728\u57FA\u7840 setup \u4E4B\u540E\u8FFD\u52A0\u9879\u76EE setup", () => {
     const config = defineGameVitestConfig({
       projectRoot,
+      gameplayAudit,
       additionalSetupFiles: ["tests/custom-setup.ts"],
       testTimeout: 5e3,
       hookTimeout: 2e3
     });
     expect(config.test).toMatchObject({
       include: ["tests/**/*.test.ts"],
-      setupFiles: [
-        "miaoda-game-devkit/vitest-setup",
-        "tests/custom-setup.ts"
-      ],
+      setupFiles: ["miaoda-game-devkit/vitest-setup", "tests/custom-setup.ts"],
       testTimeout: 5e3,
       hookTimeout: 2e3
     });
   });
+  it("\u62D2\u7EDD\u7F3A\u5C11 Scene contract \u7684\u5BA1\u8BA1\u6E05\u5355", () => {
+    expect(
+      () => defineGameVitestConfig({
+        projectRoot,
+        gameplayAudit: {
+          scenes: ["InputScene", "ResultScene"],
+          contracts: gameplayAudit.contracts
+        }
+      })
+    ).toThrow(/ResultScene.*没有任何 gameplay contract/s);
+  });
 });

package/dist/vitest-config.d.mts

@@ -1,8 +1,12 @@
 import { ViteUserConfig } from 'vitest/config';
+import { c as GameplayAuditOptions } from './gameplay-audit-CYqLL8gY.mjs';
+import 'phaser';
 
 interface GameVitestConfigOptions {
     /** 模板项目的绝对根目录，通常传入 `import.meta.dirname`。 */
     projectRoot: string;
+    /** 测试前后都必须审计的生产 Scene 和玩法契约清单。 */
+    gameplayAudit: GameplayAuditOptions;
     /** 项目需要的额外路径别名；`@` 和 `phaser` 由 devkit 统一维护。 */
     aliases?: Record<string, string>;
     /** 在 devkit 基础 setup 之后执行的项目级 setup 文件。 */
@@ -15,8 +19,8 @@ interface GameVitestConfigOptions {
 /**
  * 创建妙搭 Phaser 游戏的 Vitest 配置。
  *
- * HEADLESS 环境、游戏测试范围、Scene coverage 和 mock 隔离均由 devkit
- * 固定；模板只传入项目根目录及少量安全扩展。
+ * HEADLESS 环境、游戏测试范围、Scene coverage、玩法审计和 mock 隔离均由 devkit
+ * 固定；模板传入项目根目录、玩法清单及少量安全扩展。
  */
 declare function defineGameVitestConfig(options: GameVitestConfigOptions): ViteUserConfig;
 

package/dist/vitest-config.d.ts

@@ -1,8 +1,12 @@
 import { ViteUserConfig } from 'vitest/config';
+import { c as GameplayAuditOptions } from './gameplay-audit-CYqLL8gY.js';
+import 'phaser';
 
 interface GameVitestConfigOptions {
     /** 模板项目的绝对根目录，通常传入 `import.meta.dirname`。 */
     projectRoot: string;
+    /** 测试前后都必须审计的生产 Scene 和玩法契约清单。 */
+    gameplayAudit: GameplayAuditOptions;
     /** 项目需要的额外路径别名；`@` 和 `phaser` 由 devkit 统一维护。 */
     aliases?: Record<string, string>;
     /** 在 devkit 基础 setup 之后执行的项目级 setup 文件。 */
@@ -15,8 +19,8 @@ interface GameVitestConfigOptions {
 /**
  * 创建妙搭 Phaser 游戏的 Vitest 配置。
  *
- * HEADLESS 环境、游戏测试范围、Scene coverage 和 mock 隔离均由 devkit
- * 固定；模板只传入项目根目录及少量安全扩展。
+ * HEADLESS 环境、游戏测试范围、Scene coverage、玩法审计和 mock 隔离均由 devkit
+ * 固定；模板传入项目根目录、玩法清单及少量安全扩展。
  */
 declare function defineGameVitestConfig(options: GameVitestConfigOptions): ViteUserConfig;