miaoda-game-devkit 0.1.1 → 0.2.0

package/dist/vitest-config.js

@@ -24,17 +24,352 @@ __export(vitest_config_exports, {
 });
 module.exports = __toCommonJS(vitest_config_exports);
 var import_node_module = require("module");
-var import_node_path = require("path");
+var import_node_path2 = require("path");
 var import_config = require("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
+var import_node_path = require("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(projectRoot, options) {
+    this.projectRoot = projectRoot;
+    this.options = options;
+  }
+  /** 每次 Vitest 运行开始时重置预检状态，并检查清单中的测试文件是否会执行。 */
+  onTestRunStart(specifications) {
+    this.preflightIssues.clear();
+    const scheduledFiles = new Set(
+      specifications.map(
+        (specification) => normalizePath((0, import_node_path.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 = (0, import_node_module.createRequire)((0, import_node_path.resolve)(options.projectRoot, "package.json"));
-  const phaserPackageRoot = (0, import_node_path.dirname)(projectRequire.resolve("phaser/package.json"));
-  const phaserBrowserBuild = (0, import_node_path.resolve)(phaserPackageRoot, "dist/phaser.js");
+  const auditIssues = validateGameplayAuditOptions(options.gameplayAudit);
+  if (auditIssues.length > 0) {
+    throw new Error(
+      `\u65E0\u6548\u7684 gameplayAudit \u914D\u7F6E\uFF1A
+- ${auditIssues.join("\n- ")}`
+    );
+  }
+  const projectRequire = (0, import_node_module.createRequire)(
+    (0, import_node_path2.resolve)(options.projectRoot, "package.json")
+  );
+  const phaserPackageRoot = (0, import_node_path2.dirname)(
+    projectRequire.resolve("phaser/package.json")
+  );
+  const phaserBrowserBuild = (0, import_node_path2.resolve)(phaserPackageRoot, "dist/phaser.js");
   return (0, import_config.defineConfig)({
     resolve: {
       alias: {
         ...options.aliases,
-        "@": (0, import_node_path.resolve)(options.projectRoot, "src"),
+        "@": (0, import_node_path2.resolve)(options.projectRoot, "src"),
         phaser: phaserBrowserBuild
       }
     },
@@ -57,6 +392,10 @@ function defineGameVitestConfig(options) {
         "miaoda-game-devkit/vitest-setup",
         ...options.additionalSetupFiles ?? []
       ],
+      reporters: [
+        "default",
+        new GameplayAuditReporter(options.projectRoot, options.gameplayAudit)
+      ],
       restoreMocks: true,
       clearMocks: true,
       coverage: {