miaoda-game-devkit 0.6.5 → 0.7.0

package/dist/react/testing.js

@@ -122,47 +122,145 @@ function safeJson(value) {
     return void 0;
   }
 }
-function collectEntries(value, fallbackCode, seen) {
+function diagnosticValue(value) {
+  if (value === void 0) return void 0;
   if (typeof value === "string") {
-    return value.trim() ? [{ code: fallbackCode, message: truncate(value) }] : [];
+    return truncate(value.replace(/\s+/g, " ").trim());
+  }
+  if (value === null || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (typeof value === "symbol") return value.toString();
+  if (typeof value === "function") {
+    return `Function<${value.name || "anonymous"}>`;
+  }
+  const json = safeJson(value);
+  return truncate(json ?? String(value));
+}
+function normalizeFile(value) {
+  return value.replaceAll("\\", "/").replace(/^file:\/\//, "");
+}
+function failureLayer(file) {
+  const normalized = normalizeFile(file);
+  if (normalized.includes("/miaoda-game-devkit/") || normalized.includes("/packages/game-devkit/")) {
+    return "harness";
+  }
+  if (normalized.includes("/node_modules/")) return "dependency";
+  if (/(?:^|\/)tests?\//.test(normalized) || /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(normalized)) {
+    return "test";
+  }
+  if (/(?:^|\/)src\//.test(normalized)) return "product";
+  return "unknown";
+}
+function parsedOrigin(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const frame = value;
+  if (typeof frame.file !== "string" || typeof frame.line !== "number" || typeof frame.column !== "number") {
+    return void 0;
+  }
+  return {
+    file: normalizeFile(frame.file),
+    line: frame.line,
+    column: frame.column
+  };
+}
+function stackOrigins(record) {
+  if (Array.isArray(record.stacks)) {
+    const parsed = record.stacks.map(parsedOrigin).filter((origin) => Boolean(origin));
+    if (parsed.length > 0) return parsed;
+  }
+  if (typeof record.stack !== "string") return [];
+  const origins = [];
+  const pattern = /(?:at\s+.*?\()?((?:file:\/\/)?[^()\s]+):(\d+):(\d+)\)?/g;
+  for (const match of record.stack.matchAll(pattern)) {
+    origins.push({
+      file: normalizeFile(match[1]),
+      line: Number(match[2]),
+      column: Number(match[3])
+    });
+  }
+  return origins;
+}
+function selectOrigin(record) {
+  const origins = stackOrigins(record);
+  return origins.find((origin) => {
+    const layer = failureLayer(origin.file);
+    return layer === "product" || layer === "test";
+  }) ?? origins.find((origin) => failureLayer(origin.file) !== "dependency");
+}
+function fallbackCode(record, origin, defaultCode) {
+  if (typeof record.code === "string" && record.code.trim()) {
+    return record.code.trim();
+  }
+  if (record.name === "AssertionError" && record.actual !== void 0 && record.expected !== void 0) {
+    return "EXPECTATION_MISMATCH";
+  }
+  if (record.name === "TypeError" && origin) {
+    const layer = failureLayer(origin.file);
+    if (layer === "product") return "PRODUCT_RUNTIME_TYPE_ERROR";
+    if (layer === "test") return "TEST_API_MISMATCH";
+  }
+  return defaultCode;
+}
+function structuredEntry(record, message, defaultCode) {
+  const origin = selectOrigin(record);
+  return {
+    code: fallbackCode(record, origin, defaultCode),
+    message: truncate(message),
+    errorName: typeof record.name === "string" && record.name.trim() ? record.name.trim() : void 0,
+    actual: diagnosticValue(record.actual),
+    expected: diagnosticValue(record.expected),
+    origin,
+    layer: origin ? failureLayer(origin.file) : void 0
+  };
+}
+function collectEntries(value, fallbackCode2, seen) {
+  if (typeof value === "string") {
+    return value.trim() ? [{ code: fallbackCode2, message: truncate(value) }] : [];
   }
   if (value === null || value === void 0 || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "symbol") {
-    return [{ code: fallbackCode, message: String(value) }];
+    return [{ code: fallbackCode2, message: String(value) }];
   }
   if (typeof value === "function") {
     return [
-      { code: fallbackCode, message: `Function<${value.name || "anonymous"}>` }
+      { code: fallbackCode2, message: `Function<${value.name || "anonymous"}>` }
     ];
   }
   if (seen.has(value)) return [];
   seen.add(value);
   if (Array.isArray(value)) {
-    return value.flatMap((item) => collectEntries(item, fallbackCode, seen));
+    return value.flatMap((item) => collectEntries(item, fallbackCode2, seen));
   }
   const record = value;
-  const code = typeof record.code === "string" && record.code.trim() ? record.code.trim() : fallbackCode;
   const entries = [];
   if (typeof record.message === "string" && record.message.trim()) {
-    entries.push({ code, message: truncate(record.message) });
+    entries.push(structuredEntry(record, record.message, fallbackCode2));
   }
   if (record.cause !== void 0) {
-    entries.push(...collectEntries(record.cause, fallbackCode, seen));
+    entries.push(...collectEntries(record.cause, fallbackCode2, seen));
   }
   if (Array.isArray(record.errors)) {
-    entries.push(...collectEntries(record.errors, fallbackCode, seen));
+    entries.push(...collectEntries(record.errors, fallbackCode2, seen));
   }
   if (entries.length > 0) return entries;
   if (typeof record.stack === "string" && record.stack.trim()) {
-    return [{ code, message: truncate(record.stack) }];
+    return [structuredEntry(record, record.stack, fallbackCode2)];
   }
   const json = safeJson(value);
-  return json && json !== "{}" ? [{ code, message: truncate(json) }] : [];
+  return json && json !== "{}" ? [structuredEntry(record, json, fallbackCode2)] : [];
 }
-function extractFailureEntries(value, fallbackCode = "TEST_FAILURE") {
-  const entries = collectEntries(value, fallbackCode, /* @__PURE__ */ new WeakSet());
+function extractFailureEntries(value, fallbackCode2 = "TEST_FAILURE") {
+  const entries = collectEntries(value, fallbackCode2, /* @__PURE__ */ new WeakSet());
   const keys = /* @__PURE__ */ new Set();
   return entries.filter((entry) => {
-    const key = `${entry.code}\0${entry.message}`;
+    const key = [
+      entry.code,
+      entry.message,
+      entry.errorName,
+      entry.actual,
+      entry.expected,
+      entry.origin ? `${entry.origin.file}:${entry.origin.line}:${entry.origin.column}` : void 0
+    ].join("\0");
     if (keys.has(key)) return false;
     keys.add(key);
     return true;
@@ -243,10 +341,10 @@ async function runBoundedUntil(condition, options = {}) {
     }
   }
   const diagnostics = formatDiagnostics(options.diagnostics);
-  const guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, so time-driven gameplay was not advanced. Inject a ManualGameClock for this test and pass step: () => clock.stepFrame().";
+  const guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, and the condition did not become true after the stage action. This does not identify a clock problem; inspect the condition, production input wiring, and observed state boundary.";
   const suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
   throw codedError(
-    options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_CLOCK_NOT_ADVANCED",
+    options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_OUTCOME_NOT_REACHED",
     `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
   );
 }

package/dist/react/testing.mjs

@@ -84,47 +84,145 @@ function safeJson(value) {
     return void 0;
   }
 }
-function collectEntries(value, fallbackCode, seen) {
+function diagnosticValue(value) {
+  if (value === void 0) return void 0;
   if (typeof value === "string") {
-    return value.trim() ? [{ code: fallbackCode, message: truncate(value) }] : [];
+    return truncate(value.replace(/\s+/g, " ").trim());
+  }
+  if (value === null || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (typeof value === "symbol") return value.toString();
+  if (typeof value === "function") {
+    return `Function<${value.name || "anonymous"}>`;
+  }
+  const json = safeJson(value);
+  return truncate(json ?? String(value));
+}
+function normalizeFile(value) {
+  return value.replaceAll("\\", "/").replace(/^file:\/\//, "");
+}
+function failureLayer(file) {
+  const normalized = normalizeFile(file);
+  if (normalized.includes("/miaoda-game-devkit/") || normalized.includes("/packages/game-devkit/")) {
+    return "harness";
+  }
+  if (normalized.includes("/node_modules/")) return "dependency";
+  if (/(?:^|\/)tests?\//.test(normalized) || /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(normalized)) {
+    return "test";
+  }
+  if (/(?:^|\/)src\//.test(normalized)) return "product";
+  return "unknown";
+}
+function parsedOrigin(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const frame = value;
+  if (typeof frame.file !== "string" || typeof frame.line !== "number" || typeof frame.column !== "number") {
+    return void 0;
+  }
+  return {
+    file: normalizeFile(frame.file),
+    line: frame.line,
+    column: frame.column
+  };
+}
+function stackOrigins(record) {
+  if (Array.isArray(record.stacks)) {
+    const parsed = record.stacks.map(parsedOrigin).filter((origin) => Boolean(origin));
+    if (parsed.length > 0) return parsed;
+  }
+  if (typeof record.stack !== "string") return [];
+  const origins = [];
+  const pattern = /(?:at\s+.*?\()?((?:file:\/\/)?[^()\s]+):(\d+):(\d+)\)?/g;
+  for (const match of record.stack.matchAll(pattern)) {
+    origins.push({
+      file: normalizeFile(match[1]),
+      line: Number(match[2]),
+      column: Number(match[3])
+    });
+  }
+  return origins;
+}
+function selectOrigin(record) {
+  const origins = stackOrigins(record);
+  return origins.find((origin) => {
+    const layer = failureLayer(origin.file);
+    return layer === "product" || layer === "test";
+  }) ?? origins.find((origin) => failureLayer(origin.file) !== "dependency");
+}
+function fallbackCode(record, origin, defaultCode) {
+  if (typeof record.code === "string" && record.code.trim()) {
+    return record.code.trim();
+  }
+  if (record.name === "AssertionError" && record.actual !== void 0 && record.expected !== void 0) {
+    return "EXPECTATION_MISMATCH";
+  }
+  if (record.name === "TypeError" && origin) {
+    const layer = failureLayer(origin.file);
+    if (layer === "product") return "PRODUCT_RUNTIME_TYPE_ERROR";
+    if (layer === "test") return "TEST_API_MISMATCH";
+  }
+  return defaultCode;
+}
+function structuredEntry(record, message, defaultCode) {
+  const origin = selectOrigin(record);
+  return {
+    code: fallbackCode(record, origin, defaultCode),
+    message: truncate(message),
+    errorName: typeof record.name === "string" && record.name.trim() ? record.name.trim() : void 0,
+    actual: diagnosticValue(record.actual),
+    expected: diagnosticValue(record.expected),
+    origin,
+    layer: origin ? failureLayer(origin.file) : void 0
+  };
+}
+function collectEntries(value, fallbackCode2, seen) {
+  if (typeof value === "string") {
+    return value.trim() ? [{ code: fallbackCode2, message: truncate(value) }] : [];
   }
   if (value === null || value === void 0 || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "symbol") {
-    return [{ code: fallbackCode, message: String(value) }];
+    return [{ code: fallbackCode2, message: String(value) }];
   }
   if (typeof value === "function") {
     return [
-      { code: fallbackCode, message: `Function<${value.name || "anonymous"}>` }
+      { code: fallbackCode2, message: `Function<${value.name || "anonymous"}>` }
     ];
   }
   if (seen.has(value)) return [];
   seen.add(value);
   if (Array.isArray(value)) {
-    return value.flatMap((item) => collectEntries(item, fallbackCode, seen));
+    return value.flatMap((item) => collectEntries(item, fallbackCode2, seen));
   }
   const record = value;
-  const code = typeof record.code === "string" && record.code.trim() ? record.code.trim() : fallbackCode;
   const entries = [];
   if (typeof record.message === "string" && record.message.trim()) {
-    entries.push({ code, message: truncate(record.message) });
+    entries.push(structuredEntry(record, record.message, fallbackCode2));
   }
   if (record.cause !== void 0) {
-    entries.push(...collectEntries(record.cause, fallbackCode, seen));
+    entries.push(...collectEntries(record.cause, fallbackCode2, seen));
   }
   if (Array.isArray(record.errors)) {
-    entries.push(...collectEntries(record.errors, fallbackCode, seen));
+    entries.push(...collectEntries(record.errors, fallbackCode2, seen));
   }
   if (entries.length > 0) return entries;
   if (typeof record.stack === "string" && record.stack.trim()) {
-    return [{ code, message: truncate(record.stack) }];
+    return [structuredEntry(record, record.stack, fallbackCode2)];
   }
   const json = safeJson(value);
-  return json && json !== "{}" ? [{ code, message: truncate(json) }] : [];
+  return json && json !== "{}" ? [structuredEntry(record, json, fallbackCode2)] : [];
 }
-function extractFailureEntries(value, fallbackCode = "TEST_FAILURE") {
-  const entries = collectEntries(value, fallbackCode, /* @__PURE__ */ new WeakSet());
+function extractFailureEntries(value, fallbackCode2 = "TEST_FAILURE") {
+  const entries = collectEntries(value, fallbackCode2, /* @__PURE__ */ new WeakSet());
   const keys = /* @__PURE__ */ new Set();
   return entries.filter((entry) => {
-    const key = `${entry.code}\0${entry.message}`;
+    const key = [
+      entry.code,
+      entry.message,
+      entry.errorName,
+      entry.actual,
+      entry.expected,
+      entry.origin ? `${entry.origin.file}:${entry.origin.line}:${entry.origin.column}` : void 0
+    ].join("\0");
     if (keys.has(key)) return false;
     keys.add(key);
     return true;
@@ -205,10 +303,10 @@ async function runBoundedUntil(condition, options = {}) {
     }
   }
   const diagnostics = formatDiagnostics(options.diagnostics);
-  const guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, so time-driven gameplay was not advanced. Inject a ManualGameClock for this test and pass step: () => clock.stepFrame().";
+  const guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, and the condition did not become true after the stage action. This does not identify a clock problem; inspect the condition, production input wiring, and observed state boundary.";
   const suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
   throw codedError(
-    options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_CLOCK_NOT_ADVANCED",
+    options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_OUTCOME_NOT_REACHED",
     `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
   );
 }

package/dist/react/vitest-config.d.mts

@@ -3,6 +3,11 @@ import { ViteUserConfig } from 'vitest/config';
 interface ReactGameVitestConfigOptions {
     /** React 模板的绝对根目录，通常传入 `import.meta.dirname`。 */
     projectRoot: string;
+    /**
+     * Opt in to the legacy structured playthrough gate. Ordinary React game
+     * projects should use independent Vitest scenarios and leave this disabled.
+     */
+    enablePlaythroughReporter?: boolean;
     aliases?: Record<string, string>;
     additionalSetupFiles?: string[];
     testTimeout?: number;

package/dist/react/vitest-config.d.ts

@@ -3,6 +3,11 @@ import { ViteUserConfig } from 'vitest/config';
 interface ReactGameVitestConfigOptions {
     /** React 模板的绝对根目录，通常传入 `import.meta.dirname`。 */
     projectRoot: string;
+    /**
+     * Opt in to the legacy structured playthrough gate. Ordinary React game
+     * projects should use independent Vitest scenarios and leave this disabled.
+     */
+    enablePlaythroughReporter?: boolean;
     aliases?: Record<string, string>;
     additionalSetupFiles?: string[];
     testTimeout?: number;