miaoda-game-devkit 0.6.2 → 0.6.4

package/dist/cli/phaser-lint.js

@@ -12,6 +12,8 @@ var import_node_path2 = require("path");
 var import_node_fs = require("fs");
 var import_node_path = require("path");
 var PRODUCTION_PLAYTHROUGH = "tests/production-playthrough.test.tsx";
+var PRODUCTION_APP = "src/App.tsx";
+var EXAMPLE_IMPORT_PREFIX = "@/game/example/";
 var REACT_RUNTIME_ENTRY = "miaoda-game-devkit/react";
 var REACT_TESTING_ENTRY = "miaoda-game-devkit/react/testing";
 var CLOCK_IMPORTS = /* @__PURE__ */ new Set(["browserGameClock"]);
@@ -20,6 +22,19 @@ var CONTROLLER_IMPORTS = /* @__PURE__ */ new Set([
   "useOwnedGameController"
 ]);
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx"]);
+function runnableTestFiles(root, directory = (0, import_node_path.join)(root, "tests")) {
+  if (!(0, import_node_fs.existsSync)(directory)) return [];
+  const files = [];
+  for (const entry of (0, import_node_fs.readdirSync)(directory, { withFileTypes: true })) {
+    const path = (0, import_node_path.join)(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...runnableTestFiles(root, path));
+    } else if (entry.isFile() && /\.test\.[cm]?[jt]sx?$/.test(entry.name)) {
+      files.push(path);
+    }
+  }
+  return files;
+}
 function extension(path) {
   const index = path.lastIndexOf(".");
   return index < 0 ? "" : path.slice(index);
@@ -109,6 +124,32 @@ function codePositions(source) {
   }
   return positions;
 }
+function importedModuleSpecifiers(source) {
+  const clean = withoutComments(source);
+  const positions = codePositions(clean);
+  const modules = [];
+  const pattern = /\b(?:from\s+|import\s*(?:\(\s*)?)["']([^"']+)["']\s*\)?/g;
+  for (const match of clean.matchAll(pattern)) {
+    if (positions[match.index]) modules.push(match[1]);
+  }
+  return modules;
+}
+function productionFileImportsExample(file, projectRoot2) {
+  const exampleRoot = (0, import_node_path.join)(projectRoot2, "src/game/example");
+  return importedModuleSpecifiers((0, import_node_fs.readFileSync)(file, "utf8")).some(
+    (moduleName) => {
+      if (moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)) return true;
+      if (!moduleName.startsWith(".")) return false;
+      const target = (0, import_node_path.resolve)((0, import_node_path.dirname)(file), moduleName);
+      return target === exampleRoot || target.startsWith(`${exampleRoot}${import_node_path.sep}`);
+    }
+  );
+}
+function importsExampleAlias(source) {
+  return importedModuleSpecifiers(source).some(
+    (moduleName) => moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)
+  );
+}
 function namedImports(source, moduleName) {
   const names = /* @__PURE__ */ new Set();
   const clean = withoutComments(source);
@@ -141,15 +182,39 @@ function declaresObserve(source) {
 function auditReactAuthoritativePlaythrough(projectRoot2) {
   const clockFiles = [];
   const controllerFiles = [];
-  for (const file of sourceFiles(projectRoot2)) {
-    const imports = namedImports((0, import_node_fs.readFileSync)(file, "utf8"), REACT_RUNTIME_ENTRY);
+  const productionFiles = sourceFiles(projectRoot2);
+  for (const file of productionFiles) {
+    const imports = namedImports(
+      (0, import_node_fs.readFileSync)(file, "utf8"),
+      REACT_RUNTIME_ENTRY
+    );
     const projectPath = (0, import_node_path.relative)(projectRoot2, file).replaceAll("\\", "/");
     if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
-    if (containsAny(imports, CONTROLLER_IMPORTS)) controllerFiles.push(projectPath);
+    if (containsAny(imports, CONTROLLER_IMPORTS))
+      controllerFiles.push(projectPath);
   }
+  const appPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_APP);
+  const productionEntryExists = (0, import_node_fs.existsSync)(appPath);
+  const productionUsesExample = productionFiles.some(
+    (file) => productionFileImportsExample(file, projectRoot2)
+  );
+  const staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot2).filter((file) => importsExampleAlias((0, import_node_fs.readFileSync)(file, "utf8"))).map((file) => (0, import_node_path.relative)(projectRoot2, file).replaceAll("\\", "/"));
   const issues = [];
+  if (staleExampleTestFiles.length > 0) {
+    issues.push(
+      `Production ${PRODUCTION_APP} no longer imports ${EXAMPLE_IMPORT_PREFIX}*, but runnable product tests still do: ${staleExampleTestFiles.join(", ")}. Replace those CollectGame tests with tests for the production game or delete genuinely inapplicable slots. Teaching examples under tests/examples/**/*.example.* remain allowed.`
+    );
+  }
   if (clockFiles.length === 0 && controllerFiles.length === 0) {
-    return { ok: true, issues, clockFiles, controllerFiles };
+    return {
+      ok: issues.length === 0,
+      issues,
+      clockFiles,
+      controllerFiles,
+      productionEntryExists,
+      productionUsesExample,
+      staleExampleTestFiles
+    };
   }
   const testPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_PLAYTHROUGH);
   const testSource = (0, import_node_fs.existsSync)(testPath) ? (0, import_node_fs.readFileSync)(testPath, "utf8") : "";
@@ -165,7 +230,15 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
       `${PRODUCTION_PLAYTHROUGH} must import ManualGameClock because production owns gameplay time in ${clockFiles.join(", ")}. Inject it through the production <App /> factory and advance it with a non-empty deterministic step.`
     );
   }
-  return { ok: issues.length === 0, issues, clockFiles, controllerFiles };
+  return {
+    ok: issues.length === 0,
+    issues,
+    clockFiles,
+    controllerFiles,
+    productionEntryExists,
+    productionUsesExample,
+    staleExampleTestFiles
+  };
 }
 
 // src/cli/lint.ts

package/dist/cli/react-lint.js

@@ -12,6 +12,8 @@ var import_node_path2 = require("path");
 var import_node_fs = require("fs");
 var import_node_path = require("path");
 var PRODUCTION_PLAYTHROUGH = "tests/production-playthrough.test.tsx";
+var PRODUCTION_APP = "src/App.tsx";
+var EXAMPLE_IMPORT_PREFIX = "@/game/example/";
 var REACT_RUNTIME_ENTRY = "miaoda-game-devkit/react";
 var REACT_TESTING_ENTRY = "miaoda-game-devkit/react/testing";
 var CLOCK_IMPORTS = /* @__PURE__ */ new Set(["browserGameClock"]);
@@ -20,6 +22,19 @@ var CONTROLLER_IMPORTS = /* @__PURE__ */ new Set([
   "useOwnedGameController"
 ]);
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx"]);
+function runnableTestFiles(root, directory = (0, import_node_path.join)(root, "tests")) {
+  if (!(0, import_node_fs.existsSync)(directory)) return [];
+  const files = [];
+  for (const entry of (0, import_node_fs.readdirSync)(directory, { withFileTypes: true })) {
+    const path = (0, import_node_path.join)(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...runnableTestFiles(root, path));
+    } else if (entry.isFile() && /\.test\.[cm]?[jt]sx?$/.test(entry.name)) {
+      files.push(path);
+    }
+  }
+  return files;
+}
 function extension(path) {
   const index = path.lastIndexOf(".");
   return index < 0 ? "" : path.slice(index);
@@ -109,6 +124,32 @@ function codePositions(source) {
   }
   return positions;
 }
+function importedModuleSpecifiers(source) {
+  const clean = withoutComments(source);
+  const positions = codePositions(clean);
+  const modules = [];
+  const pattern = /\b(?:from\s+|import\s*(?:\(\s*)?)["']([^"']+)["']\s*\)?/g;
+  for (const match of clean.matchAll(pattern)) {
+    if (positions[match.index]) modules.push(match[1]);
+  }
+  return modules;
+}
+function productionFileImportsExample(file, projectRoot2) {
+  const exampleRoot = (0, import_node_path.join)(projectRoot2, "src/game/example");
+  return importedModuleSpecifiers((0, import_node_fs.readFileSync)(file, "utf8")).some(
+    (moduleName) => {
+      if (moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)) return true;
+      if (!moduleName.startsWith(".")) return false;
+      const target = (0, import_node_path.resolve)((0, import_node_path.dirname)(file), moduleName);
+      return target === exampleRoot || target.startsWith(`${exampleRoot}${import_node_path.sep}`);
+    }
+  );
+}
+function importsExampleAlias(source) {
+  return importedModuleSpecifiers(source).some(
+    (moduleName) => moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)
+  );
+}
 function namedImports(source, moduleName) {
   const names = /* @__PURE__ */ new Set();
   const clean = withoutComments(source);
@@ -141,15 +182,39 @@ function declaresObserve(source) {
 function auditReactAuthoritativePlaythrough(projectRoot2) {
   const clockFiles = [];
   const controllerFiles = [];
-  for (const file of sourceFiles(projectRoot2)) {
-    const imports = namedImports((0, import_node_fs.readFileSync)(file, "utf8"), REACT_RUNTIME_ENTRY);
+  const productionFiles = sourceFiles(projectRoot2);
+  for (const file of productionFiles) {
+    const imports = namedImports(
+      (0, import_node_fs.readFileSync)(file, "utf8"),
+      REACT_RUNTIME_ENTRY
+    );
     const projectPath = (0, import_node_path.relative)(projectRoot2, file).replaceAll("\\", "/");
     if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
-    if (containsAny(imports, CONTROLLER_IMPORTS)) controllerFiles.push(projectPath);
+    if (containsAny(imports, CONTROLLER_IMPORTS))
+      controllerFiles.push(projectPath);
   }
+  const appPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_APP);
+  const productionEntryExists = (0, import_node_fs.existsSync)(appPath);
+  const productionUsesExample = productionFiles.some(
+    (file) => productionFileImportsExample(file, projectRoot2)
+  );
+  const staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot2).filter((file) => importsExampleAlias((0, import_node_fs.readFileSync)(file, "utf8"))).map((file) => (0, import_node_path.relative)(projectRoot2, file).replaceAll("\\", "/"));
   const issues = [];
+  if (staleExampleTestFiles.length > 0) {
+    issues.push(
+      `Production ${PRODUCTION_APP} no longer imports ${EXAMPLE_IMPORT_PREFIX}*, but runnable product tests still do: ${staleExampleTestFiles.join(", ")}. Replace those CollectGame tests with tests for the production game or delete genuinely inapplicable slots. Teaching examples under tests/examples/**/*.example.* remain allowed.`
+    );
+  }
   if (clockFiles.length === 0 && controllerFiles.length === 0) {
-    return { ok: true, issues, clockFiles, controllerFiles };
+    return {
+      ok: issues.length === 0,
+      issues,
+      clockFiles,
+      controllerFiles,
+      productionEntryExists,
+      productionUsesExample,
+      staleExampleTestFiles
+    };
   }
   const testPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_PLAYTHROUGH);
   const testSource = (0, import_node_fs.existsSync)(testPath) ? (0, import_node_fs.readFileSync)(testPath, "utf8") : "";
@@ -165,7 +230,15 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
       `${PRODUCTION_PLAYTHROUGH} must import ManualGameClock because production owns gameplay time in ${clockFiles.join(", ")}. Inject it through the production <App /> factory and advance it with a non-empty deterministic step.`
     );
   }
-  return { ok: issues.length === 0, issues, clockFiles, controllerFiles };
+  return {
+    ok: issues.length === 0,
+    issues,
+    clockFiles,
+    controllerFiles,
+    productionEntryExists,
+    productionUsesExample,
+    staleExampleTestFiles
+  };
 }
 
 // src/cli/lint.ts

package/dist/react/index.js

@@ -54,6 +54,15 @@ function useOwnedGameController(createController) {
 
 // src/react/use-game-controller.ts
 var import_react2 = require("react");
+
+// src/react/react-error-diagnostics.ts
+function codedError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+// src/react/use-game-controller.ts
 function useGameController(createController) {
   const game = useOwnedGameController(createController);
   useSnapshotIntegrityCheck(game);
@@ -91,7 +100,8 @@ function useSnapshotIntegrityCheck(game) {
       }
       if (previousJson !== void 0 && nextJson !== previousJson) {
         reported.current = true;
-        throw new Error(
+        throw codedError(
+          "GAME_SNAPSHOT_REFERENCE_REUSED",
           "Game state changed while snapshot() returned the same reference. React compares snapshots by reference and skips the render when Object.is(previous, next) is true, so the UI freezes. Publish a new top-level snapshot before each notification, for example cachedSnapshot = { ...state }, and never expose a mutable internal object as the snapshot."
         );
       }

package/dist/react/index.mjs

@@ -26,6 +26,15 @@ function useOwnedGameController(createController) {
 
 // src/react/use-game-controller.ts
 import { useEffect as useEffect2, useRef as useRef2, useSyncExternalStore } from "react";
+
+// src/react/react-error-diagnostics.ts
+function codedError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+// src/react/use-game-controller.ts
 function useGameController(createController) {
   const game = useOwnedGameController(createController);
   useSnapshotIntegrityCheck(game);
@@ -63,7 +72,8 @@ function useSnapshotIntegrityCheck(game) {
       }
       if (previousJson !== void 0 && nextJson !== previousJson) {
         reported.current = true;
-        throw new Error(
+        throw codedError(
+          "GAME_SNAPSHOT_REFERENCE_REUSED",
           "Game state changed while snapshot() returned the same reference. React compares snapshots by reference and skips the render when Object.is(previous, next) is true, so the UI freezes. Publish a new top-level snapshot before each notification, for example cachedSnapshot = { ...state }, and never expose a mutable internal object as the snapshot."
         );
       }

package/dist/react/testing.d.mts

@@ -22,6 +22,15 @@ declare class ManualGameClock implements GameClock {
     pendingTimerCount(): number;
 }
 
+interface ReactFailureEntry {
+    code: string;
+    message: string;
+}
+interface ReactFailureDiagnostic {
+    source: "playthrough" | "test-runtime";
+    entries: ReactFailureEntry[];
+}
+
 /** 有界推进的通用配置，不绑定任何特定 Core、phase 或时钟实现。 */
 interface StepUntilOptions {
     /** 条件仍不成立时允许执行的最大生产步数，默认 120。 */
@@ -57,9 +66,10 @@ interface ReactPlaythroughEvidence {
 }
 /** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
 interface ReactPlaythroughMetadata {
-    version: 4;
+    version: 5;
     waiverReason?: string;
     trace?: string;
+    failure?: ReactFailureDiagnostic;
     evidence: ReactPlaythroughEvidence;
 }
 interface ReactPlaythroughOptions {

package/dist/react/testing.d.ts

@@ -22,6 +22,15 @@ declare class ManualGameClock implements GameClock {
     pendingTimerCount(): number;
 }
 
+interface ReactFailureEntry {
+    code: string;
+    message: string;
+}
+interface ReactFailureDiagnostic {
+    source: "playthrough" | "test-runtime";
+    entries: ReactFailureEntry[];
+}
+
 /** 有界推进的通用配置，不绑定任何特定 Core、phase 或时钟实现。 */
 interface StepUntilOptions {
     /** 条件仍不成立时允许执行的最大生产步数，默认 120。 */
@@ -57,9 +66,10 @@ interface ReactPlaythroughEvidence {
 }
 /** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
 interface ReactPlaythroughMetadata {
-    version: 4;
+    version: 5;
     waiverReason?: string;
     trace?: string;
+    failure?: ReactFailureDiagnostic;
     evidence: ReactPlaythroughEvidence;
 }
 interface ReactPlaythroughOptions {