miaoda-game-devkit 0.2.14 → 0.2.16

package/dist/react/vitest-config.mjs

@@ -1,8 +1,326 @@
 // src/react-vitest-config.ts
-import { existsSync, readFileSync } from "fs";
-import { dirname, resolve } from "path";
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { dirname, resolve as resolve2 } from "path";
 import { defineConfig } from "vitest/config";
 
+// src/react/react-playthrough-reporter.ts
+import { existsSync } from "fs";
+import { relative, resolve } from "path";
+
+// src/react/react-playthrough.ts
+import { render } from "@testing-library/react";
+import { expect, test } from "vitest";
+
+// src/react/react-playthrough-core.ts
+import { act } from "@testing-library/react";
+function normalizePlaythroughWaiverReason(waiverReason) {
+  if (waiverReason === void 0) return void 0;
+  const reason = waiverReason.trim();
+  if (reason.length < 20) {
+    throw new Error(
+      "playthroughTest.skip reason must contain at least 20 characters."
+    );
+  }
+  return reason;
+}
+async function runBoundedUntil(condition, options = {}) {
+  const maxSteps = options.maxSteps ?? 120;
+  if (!Number.isSafeInteger(maxSteps) || maxSteps < 0 || maxSteps > 1e4) {
+    throw new RangeError(
+      "stepUntil maxSteps must be a safe integer between 0 and 10000."
+    );
+  }
+  for (let step = 0; step <= maxSteps; step += 1) {
+    if (condition()) return step;
+    if (step < maxSteps) {
+      await act(async () => {
+        await options.step?.(step + 1);
+      });
+    }
+  }
+  throw new Error(
+    `Playthrough outcome was not reached within ${maxSteps} steps.`
+  );
+}
+
+// src/react/react-playthrough.ts
+var INPUT_EVENTS = [
+  "click",
+  "keydown",
+  "keyup",
+  "pointerdown",
+  "pointerup",
+  "touchstart",
+  "touchend"
+];
+function createMetadata(waiverReason) {
+  return {
+    version: 1,
+    waiverReason,
+    evidence: {
+      domInputEvents: 0,
+      boundedRuns: 0,
+      assertionsAfterOutcome: 0,
+      verified: false
+    }
+  };
+}
+function definePlaythrough(element, run, waiverReason) {
+  const reason = normalizePlaythroughWaiverReason(waiverReason);
+  const metadata = createMetadata(reason);
+  test("production game completes a bounded playthrough", {
+    skip: Boolean(reason),
+    meta: { reactPlaythrough: metadata }
+  }, async () => {
+    const evidence = metadata.evidence;
+    let assertionsAtOutcome;
+    const recordInput = () => {
+      evidence.domInputEvents += 1;
+    };
+    for (const event of INPUT_EVENTS) {
+      document.addEventListener(event, recordInput, true);
+    }
+    try {
+      const view = render(element);
+      if (view.container.childNodes.length === 0) {
+        throw new Error(
+          "playthroughTest must render the production game entry."
+        );
+      }
+      await run({
+        view,
+        async stepUntil(condition, options = {}) {
+          const steps = await runBoundedUntil(condition, options);
+          if (evidence.domInputEvents === 0) {
+            throw new Error(
+              "stepUntil reached an outcome before any production DOM input."
+            );
+          }
+          evidence.boundedRuns += 1;
+          assertionsAtOutcome = expect.getState().assertionCalls;
+          return steps;
+        }
+      });
+      const assertionCalls = expect.getState().assertionCalls;
+      evidence.assertionsAfterOutcome = assertionsAtOutcome === void 0 ? 0 : assertionCalls - assertionsAtOutcome;
+      if (evidence.domInputEvents === 0) {
+        throw new Error(
+          "playthroughTest did not observe production DOM input."
+        );
+      }
+      if (evidence.boundedRuns === 0) {
+        throw new Error("playthroughTest must complete one bounded stepUntil.");
+      }
+      if (evidence.assertionsAfterOutcome === 0) {
+        throw new Error(
+          "Assert an authoritative game outcome after stepUntil returns."
+        );
+      }
+      evidence.verified = true;
+    } finally {
+      for (const event of INPUT_EVENTS) {
+        document.removeEventListener(event, recordInput, true);
+      }
+    }
+  });
+}
+var playthroughTest = Object.assign(
+  (element, run) => definePlaythrough(element, run),
+  {
+    skip: (reason, element, run) => definePlaythrough(element, run, reason)
+  }
+);
+function auditReactPlaythroughRun(tests) {
+  const declared = tests.filter((candidate) => candidate.metadata);
+  const valid = declared.filter(({ state, metadata }) => {
+    const evidence = metadata?.evidence;
+    return state === "passed" && evidence?.verified === true && evidence.domInputEvents > 0 && evidence.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0;
+  });
+  const waivers = declared.filter(
+    ({ state, metadata }) => state === "skipped" && (metadata?.waiverReason?.trim().length ?? 0) >= 20
+  );
+  const issues = [];
+  if (declared.length === 0) {
+    issues.push(
+      "\u7F3A\u5C11\u751F\u4EA7\u6E38\u620F\u53EF\u73A9\u6027\u9A8C\u8BC1\uFF1A\u4F7F\u7528 playthroughTest \u6E32\u67D3 <App />\uFF0C\u901A\u8FC7\u771F\u5B9E DOM \u8F93\u5165\u5B8C\u6210\u4E00\u4E2A\u6709\u6B65\u6570\u4E0A\u9650\u7684\u5173\u952E\u6D41\u7A0B\u3002"
+    );
+  } else {
+    for (const candidate of declared) {
+      const isValid = valid.includes(candidate);
+      const isWaived = waivers.includes(candidate);
+      if (isValid || isWaived) continue;
+      if (candidate.state === "skipped") {
+        issues.push(
+          `\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u88AB\u8DF3\u8FC7\uFF0C\u4F46\u6CA1\u6709\u81F3\u5C11 20 \u4E2A\u5B57\u7B26\u7684\u660E\u786E\u7406\u7531\u3002`
+        );
+      } else if (candidate.state !== "passed") {
+        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7684\u72B6\u6001\u4E3A ${candidate.state}\u3002`);
+      } else {
+        issues.push(
+          `\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u6CA1\u6709\u7559\u4E0B\u5B8C\u6574\u7684\u8F93\u5165\u3001\u6709\u9650\u63A8\u8FDB\u548C\u7ED3\u679C\u65AD\u8A00\u8BC1\u636E\u3002`
+        );
+      }
+    }
+  }
+  if (issues.length > 0) return { passed: false, waived: false, issues };
+  if (valid.length > 0) return { passed: true, waived: false, issues: [] };
+  if (waivers.length > 0) return { passed: true, waived: true, issues: [] };
+  return { passed: false, waived: false, issues };
+}
+
+// src/react/react-playthrough-reporter.ts
+var PRODUCTION_PLAYTHROUGH_FILE = "tests/production-playthrough.test.tsx";
+function isMetadata(value) {
+  if (!value || typeof value !== "object") return false;
+  const metadata = value;
+  return metadata.version === 1 && Boolean(metadata.evidence);
+}
+function toAuditInput(test2) {
+  const metadata = test2.meta().reactPlaythrough;
+  return {
+    name: test2.fullName,
+    state: test2.result().state,
+    metadata: isMetadata(metadata) ? metadata : void 0
+  };
+}
+function firstLine(value) {
+  if (typeof value !== "string") return void 0;
+  return value.split("\n").map((line) => line.trim()).find(Boolean);
+}
+function toModuleResult(module, projectRoot) {
+  const tests = [...module.children.allTests()];
+  const errors = [
+    ...module.errors().map((error) => firstLine(error.message)),
+    ...tests.flatMap(
+      (test2) => (test2.result().errors ?? []).map((error) => firstLine(error.message))
+    )
+  ].filter((message) => Boolean(message));
+  return {
+    file: relative(projectRoot, module.moduleId).replaceAll("\\", "/"),
+    state: module.state(),
+    errors,
+    tests: tests.map(toAuditInput)
+  };
+}
+function assessReactPlaythroughReport(input) {
+  const base = { file: input.expectedFile };
+  if (!input.expectedFileScheduled) {
+    if (input.expectedFileExists) {
+      return {
+        ...base,
+        status: "NOT_CHECKED",
+        next: `\u672C\u6B21\u662F\u805A\u7126\u8FD0\u884C\uFF0C\u672A\u68C0\u67E5\u6700\u4F4E\u53EF\u73A9\u6D41\u7A0B\uFF1B\u63D0\u4EA4\u524D\u8FD0\u884C pnpm test\uFF0C\u786E\u4FDD ${input.expectedFile} \u901A\u8FC7\u3002`,
+        failsRun: false
+      };
+    }
+    return {
+      ...base,
+      status: "FAILED",
+      cause: "\u751F\u4EA7\u53EF\u73A9\u6027\u6D4B\u8BD5\u6587\u4EF6\u4E0D\u5B58\u5728\u3002",
+      next: "\u521B\u5EFA\u8BE5\u6587\u4EF6\uFF1A\u4ECE <App /> \u89E6\u53D1\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u771F\u5B9E\u72B6\u6001\u7684\u53EA\u8BFB snapshot\uFF0C\u518D\u65AD\u8A00\u7ED3\u679C\u3002",
+      failsRun: true
+    };
+  }
+  const productionModule = input.modules.find(
+    (module) => module.file === input.expectedFile
+  );
+  const executedProductionFlow = productionModule?.tests.some(
+    (test2) => test2.state !== "skipped" && test2.state !== "pending"
+  );
+  if (input.focusedSelection && !executedProductionFlow) {
+    return {
+      ...base,
+      status: "NOT_CHECKED",
+      next: `\u672C\u6B21\u540D\u79F0\u6216\u884C\u53F7\u8FC7\u6EE4\u6CA1\u6709\u6267\u884C\u6700\u4F4E\u53EF\u73A9\u6D41\u7A0B\uFF1B\u63D0\u4EA4\u524D\u8FD0\u884C pnpm test\uFF0C\u786E\u4FDD ${input.expectedFile} \u901A\u8FC7\u3002`,
+      failsRun: false
+    };
+  }
+  if (!productionModule || productionModule.tests.length === 0) {
+    return {
+      ...base,
+      status: "NOT_RUN",
+      cause: productionModule?.errors[0] ?? input.unhandledErrors?.[0] ?? "\u751F\u4EA7\u53EF\u73A9\u6027\u6D4B\u8BD5\u672A\u5B8C\u6210\u6536\u96C6\u6216\u6267\u884C\u3002",
+      next: "\u5148\u4FEE\u590D Vitest \u4E0A\u65B9\u9996\u4E2A\u8BED\u6CD5\u3001\u5BFC\u5165\u6216\u6536\u96C6\u9519\u8BEF\uFF0C\u518D\u8FD0\u884C pnpm test\uFF1B\u4E0D\u8981\u7528 skip \u63A9\u76D6\u52A0\u8F7D\u5931\u8D25\u3002",
+      failsRun: true
+    };
+  }
+  const tests = input.modules.flatMap((module) => module.tests);
+  const audit = auditReactPlaythroughRun(tests);
+  if (!audit.passed) {
+    const cause = productionModule.errors[0] ?? input.unhandledErrors?.[0] ?? audit.issues[0] ?? "\u751F\u4EA7\u53EF\u73A9\u6D41\u7A0B\u6CA1\u6709\u7559\u4E0B\u5B8C\u6574\u8BC1\u636E\u3002";
+    const timedOut = /outcome was not reached within \d+ steps/i.test(cause);
+    return {
+      ...base,
+      status: "FAILED",
+      cause,
+      next: timedOut ? "\u771F\u5B9E\u8F93\u5165\u5DF2\u6267\u884C\uFF0C\u4F46\u73A9\u6CD5\u6CA1\u6709\u5728\u4E0A\u9650\u5185\u4EA7\u751F\u7ED3\u679C\uFF1B\u68C0\u67E5\u70B9\u51FB\u6216\u6309\u952E\u662F\u5426\u771F\u7684\u8C03\u7528\u6E38\u620F\u7684\u751F\u4EA7\u63A7\u5236\u65B9\u6CD5\uFF0C\u4EE5\u53CA\u6E38\u620F\u771F\u5B9E\u72B6\u6001\u662F\u5426\u5230\u8FBE\u5E76\u663E\u793A\u7ED3\u679C\u3002" : "\u4ECE\u751F\u4EA7\u5165\u53E3\u6267\u884C\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u771F\u5B9E\u72B6\u6001\u7684\u53EA\u8BFB snapshot\uFF0C\u5E76\u5728\u5176\u540E\u65AD\u8A00\uFF1B\u4E0D\u8981\u76F4\u8FBE\u5185\u90E8\u5173\u5361\u6216\u4FEE\u6539\u73A9\u6CD5\u72B6\u6001\u3002",
+      failsRun: true
+    };
+  }
+  if (audit.waived) {
+    return {
+      ...base,
+      status: "WAIVED",
+      waiverReasons: tests.map((test2) => test2.metadata?.waiverReason).filter((reason) => Boolean(reason)),
+      failsRun: false
+    };
+  }
+  return { ...base, status: "PASS", failsRun: false };
+}
+function formatReactPlaythroughReport(report) {
+  const lines = [`REACT_PLAYTHROUGH: ${report.status}`, `FILE: ${report.file}`];
+  if (report.cause) lines.push(`CAUSE: ${report.cause}`);
+  if (report.waiverReasons?.length) {
+    lines.push(`REASON: ${report.waiverReasons.join("\uFF1B")}`);
+  }
+  if (report.next) lines.push(`NEXT: ${report.next}`);
+  return `
+${lines.join("\n")}`;
+}
+var ReactPlaythroughReporter = class {
+  /** 绑定模板根目录，以稳定识别生产可玩性测试而不依赖测试名称。 */
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.expectedModuleId = resolve(projectRoot, this.expectedFile);
+  }
+  projectRoot;
+  expectedFile = PRODUCTION_PLAYTHROUGH_FILE;
+  expectedModuleId;
+  expectedFileScheduled = false;
+  focusedSelection = false;
+  /** 记录本轮是否实际选择了生产流程文件，用于区分聚焦运行与门禁失败。 */
+  onTestRunStart(specifications) {
+    this.expectedFileScheduled = specifications.some(
+      (specification) => resolve(specification.moduleId) === this.expectedModuleId
+    );
+    this.focusedSelection = specifications.some(
+      (specification) => Boolean(specification.project.globalConfig.testNamePattern) || Boolean(specification.testNamePattern) || Boolean(specification.testLines?.length)
+    );
+  }
+  /** 测试运行结束后执行项目级主流程门禁，并写入最终退出码。 */
+  onTestRunEnd(testModules, unhandledErrors) {
+    const report = assessReactPlaythroughReport({
+      expectedFile: this.expectedFile,
+      expectedFileExists: existsSync(this.expectedModuleId),
+      expectedFileScheduled: this.expectedFileScheduled,
+      focusedSelection: this.focusedSelection,
+      modules: testModules.map(
+        (module) => toModuleResult(module, this.projectRoot)
+      ),
+      unhandledErrors: unhandledErrors.map((error) => firstLine(error.message)).filter((message) => Boolean(message))
+    });
+    const output = formatReactPlaythroughReport(report);
+    if (report.failsRun) {
+      console.error(output);
+      process.exitCode = 1;
+    } else if (report.status === "WAIVED" || report.status === "NOT_CHECKED") {
+      console.warn(output);
+    } else {
+      console.log(output);
+    }
+  }
+};
+
 // src/testing/vitest-node-args.ts
 function getJSDOMWorkerExecArgv() {
   const nodeMajor = Number.parseInt(process.versions.node, 10);
@@ -11,16 +329,16 @@ function getJSDOMWorkerExecArgv() {
 
 // src/react-vitest-config.ts
 function resolvePhaser3BrowserEntry(projectRoot) {
-  const manifestPath = resolve(projectRoot, "node_modules/phaser/package.json");
-  if (!existsSync(manifestPath)) return void 0;
+  const manifestPath = resolve2(projectRoot, "node_modules/phaser/package.json");
+  if (!existsSync2(manifestPath)) return void 0;
   try {
     const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
     if (!manifest.version?.startsWith("3.")) return void 0;
-    const browserEntry = resolve(
+    const browserEntry = resolve2(
       dirname(manifestPath),
       manifest.browser ?? "dist/phaser.js"
     );
-    return existsSync(browserEntry) ? browserEntry : void 0;
+    return existsSync2(browserEntry) ? browserEntry : void 0;
   } catch {
     return void 0;
   }
@@ -32,7 +350,7 @@ function defineReactGameVitestConfig(options) {
       alias: {
         ...phaser3BrowserEntry ? { phaser: phaser3BrowserEntry } : {},
         ...options.aliases,
-        "@": resolve(options.projectRoot, "src")
+        "@": resolve2(options.projectRoot, "src")
       }
     },
     test: {
@@ -55,7 +373,8 @@ function defineReactGameVitestConfig(options) {
       sequence: {
         setupFiles: "list"
       },
-      reporters: ["minimal"],
+      // minimal 保留业务失败；附加 reporter 负责项目级最低可玩性门禁。
+      reporters: ["minimal", new ReactPlaythroughReporter(options.projectRoot)],
       restoreMocks: true,
       clearMocks: true,
       testTimeout: options.testTimeout,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Shared React and Phaser game lint plus deterministic testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -108,7 +108,7 @@
           "build"
         ],
         "options": {
-          "command": "vitest run --config dist/lint/contracts.config.mjs",
+          "command": "pnpm run test:contracts && pnpm run test:published",
           "cwd": "packages/game-devkit"
         }
       }
@@ -121,7 +121,7 @@
     "oxc-resolver": "11.24.2",
     "oxlint": "1.76.0",
     "tailwindcss": "3.4.19",
-    "vitest": "^4.1.10"
+    "vitest": "4.1.10"
   },
   "peerDependencies": {
     "@testing-library/jest-dom": ">=6 <8",