miaoda-game-devkit 0.2.2 → 0.2.4

package/README.md

@@ -17,10 +17,14 @@ Scene 命令、restart、业务 checkpoint 和销毁。玩法测试可以调用
 `host.assertGameplayEvidence()` 把这些客观事实设为门禁；它不推断业务语义，
 authoritative state 仍必须由测试显式断言。
 
-玩法测试应优先使用 `gameplayTest`。它在 Vitest 收集阶段写入静态 contract metadata，
-在执行阶段绑定 HEADLESS host，并在 `onTestFinished` 校验 Ledger。`gameplayAudit` reporter
-会在测试执行前报告未声明或重复的 contract，在测试结束后汇总缺失、失败、证据不足、
-Scene 未访问和 registry 不一致。`registerGameplayContract` 保留为不参加执行前预检的低层接口。
+玩法测试应优先使用 `gameplayTest`。它在 Vitest 收集阶段写入测试声明，
+在执行阶段绑定 HEADLESS host，并在 `onTestFinished` 校验 Ledger。配置加载阶段会先校验
+交互项目的最低基线：至少一个 `kind: "playthrough"` contract 必须要求真实输入、完整帧和
+语义 checkpoint，每个非入口 Scene 必须有生产转场覆盖；检测到 `scene.restart()` 时还必须
+声明 `flows.restart: true` 和 `kind: "recovery"` contract。配置预检失败时测试和 coverage
+都不会运行。配置通过后，`gameplayAudit` reporter 才会检查测试声明，并在结束时汇总
+缺失、失败、证据不足、Scene 未访问和 registry 不一致。`registerGameplayContract` 保留为
+不参加执行前预检的低层接口。
 
 模板直接调用开发工具包提供的命令行程序：
 
@@ -83,7 +87,12 @@ DOM 到 Phaser 的输入、命中测试和游戏状态变化，不验证 Canvas/
 断言 authoritative state 后调用 `host.checkpoint("progress")`、
 `host.checkpoint("recovery")` 等稳定检查点，并在清单中通过 `requireCheckpoint` 声明。
 运行结束会输出稳定的 `GAMEPLAY_AUDIT: ALL CONTRACTS PASSED` 或
-`GAMEPLAY_AUDIT: ... FAILED` 标识。
+`GAMEPLAY_AUDIT: ... FAILED` 标识。该标识只表示玩法证据审计；`pnpm test` 的整体结果
+必须以最后的 `TEST_RESULT: PASS` 或 `TEST_RESULT: FAIL` 为准。失败报告会合并重复的问题，
+并给出按类别去重的修复建议，先处理列出的原始测试错误，再重新运行 `pnpm test`。
+
+共享 Vitest 配置使用 `minimal` reporter 和 `text-summary` coverage reporter，保留失败
+定位、Scene 覆盖摘要和最终机器标识，同时避免输出完整测试列表和逐文件噪声。
 
 ## 发布顺序
 

package/dist/{gameplay-audit-CYqLL8gY.d.mts → gameplay-audit-XBGq_jIV.d.mts}

@@ -162,6 +162,8 @@ declare function createHeadlessGame<TScene extends Phaser.Scene>(scene: TScene,
 
 /** 一个必须由指定测试文件证明的玩法契约。 */
 interface GameplayAuditContract extends HeadlessGameplayEvidenceRequirements {
+    /** 契约用途；boot 不得替代交互游戏的 playthrough。 */
+    kind: "boot" | "playthrough" | "transition" | "recovery";
     /** 在整个游戏项目中唯一且稳定的契约标识。 */
     id: string;
     /** 相对于游戏项目根目录的 Vitest 测试文件。 */
@@ -171,6 +173,15 @@ interface GameplayAuditContract extends HeadlessGameplayEvidenceRequirements {
 }
 /** 游戏项目在一次 Vitest 运行中必须完成的玩法审计清单。 */
 interface GameplayAuditOptions {
+    /** 默认按交互游戏审计；纯演示项目必须显式豁免并说明原因。 */
+    mode?: "interactive" | "non-interactive";
+    /** non-interactive 模式的可审计豁免理由。 */
+    nonInteractiveJustification?: string;
+    /** 应用声明的可恢复流程；restart 会触发 recovery contract 基线。 */
+    flows?: {
+        restart?: boolean;
+        reset?: boolean;
+    };
     /** 生产 Scene registry 中预期出现的全部 Scene key。 */
     scenes: string[];
     /** 必须定义、执行并满足证据要求的玩法契约。 */
@@ -178,6 +189,8 @@ interface GameplayAuditOptions {
 }
 /** 通过 Vitest task metadata 在 worker 与 reporter 之间传递的契约数据。 */
 interface GameplayContractMetadata {
+    /** 契约用途。 */
+    kind: GameplayAuditContract["kind"];
     /** 契约唯一标识。 */
     id: string;
     /** 契约负责证明的生产 Scene key。 */

package/dist/{gameplay-audit-CYqLL8gY.d.ts → gameplay-audit-XBGq_jIV.d.ts}

@@ -162,6 +162,8 @@ declare function createHeadlessGame<TScene extends Phaser.Scene>(scene: TScene,
 
 /** 一个必须由指定测试文件证明的玩法契约。 */
 interface GameplayAuditContract extends HeadlessGameplayEvidenceRequirements {
+    /** 契约用途；boot 不得替代交互游戏的 playthrough。 */
+    kind: "boot" | "playthrough" | "transition" | "recovery";
     /** 在整个游戏项目中唯一且稳定的契约标识。 */
     id: string;
     /** 相对于游戏项目根目录的 Vitest 测试文件。 */
@@ -171,6 +173,15 @@ interface GameplayAuditContract extends HeadlessGameplayEvidenceRequirements {
 }
 /** 游戏项目在一次 Vitest 运行中必须完成的玩法审计清单。 */
 interface GameplayAuditOptions {
+    /** 默认按交互游戏审计；纯演示项目必须显式豁免并说明原因。 */
+    mode?: "interactive" | "non-interactive";
+    /** non-interactive 模式的可审计豁免理由。 */
+    nonInteractiveJustification?: string;
+    /** 应用声明的可恢复流程；restart 会触发 recovery contract 基线。 */
+    flows?: {
+        restart?: boolean;
+        reset?: boolean;
+    };
     /** 生产 Scene registry 中预期出现的全部 Scene key。 */
     scenes: string[];
     /** 必须定义、执行并满足证据要求的玩法契约。 */
@@ -178,6 +189,8 @@ interface GameplayAuditOptions {
 }
 /** 通过 Vitest task metadata 在 worker 与 reporter 之间传递的契约数据。 */
 interface GameplayContractMetadata {
+    /** 契约用途。 */
+    kind: GameplayAuditContract["kind"];
     /** 契约唯一标识。 */
     id: string;
     /** 契约负责证明的生产 Scene key。 */

package/dist/index.d.mts

@@ -1,10 +1,12 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CYqLL8gY.mjs';
-export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CYqLL8gY.mjs';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-XBGq_jIV.mjs';
+export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-XBGq_jIV.mjs';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
 /** 将单个 Vitest 测试绑定到玩法 Ledger 的契约选项。 */
 interface GameplayContractOptions extends HeadlessGameplayEvidenceRequirements {
+    /** 契约用途；交互项目不能只使用 boot。 */
+    kind: "boot" | "playthrough" | "transition" | "recovery";
     /** 生产玩法清单中稳定且唯一的 contract 标识。 */
     id: string;
     /** 当前契约负责证明的生产 Scene key。 */

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CYqLL8gY.js';
-export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CYqLL8gY.js';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-XBGq_jIV.js';
+export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-XBGq_jIV.js';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
 /** 将单个 Vitest 测试绑定到玩法 Ledger 的契约选项。 */
 interface GameplayContractOptions extends HeadlessGameplayEvidenceRequirements {
+    /** 契约用途；交互项目不能只使用 boot。 */
+    kind: "boot" | "playthrough" | "transition" | "recovery";
     /** 生产玩法清单中稳定且唯一的 contract 标识。 */
     id: string;
     /** 当前契约负责证明的生产 Scene key。 */

package/dist/index.js

@@ -1089,6 +1089,8 @@ async function createHeadlessGame(scene, options = {}) {
 var import_vitest = require("vitest");
 
 // src/gameplay-audit.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
 function normalizeList(value) {
   if (value === void 0) return [];
   const values = typeof value === "string" ? [value] : value;
@@ -1119,6 +1121,7 @@ function createGameplayContractMetadata(contract) {
   const scenes = normalizeSet(contract.scenes);
   return {
     id: contract.id.trim(),
+    kind: contract.kind,
     scenes,
     requirements: normalizeGameplayRequirements(contract, scenes),
     verified: false

package/dist/index.mjs

@@ -1047,6 +1047,8 @@ async function createHeadlessGame(scene, options = {}) {
 import { test } from "vitest";
 
 // src/gameplay-audit.ts
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
 function normalizeList(value) {
   if (value === void 0) return [];
   const values = typeof value === "string" ? [value] : value;
@@ -1077,6 +1079,7 @@ function createGameplayContractMetadata(contract) {
   const scenes = normalizeSet(contract.scenes);
   return {
     id: contract.id.trim(),
+    kind: contract.kind,
     scenes,
     requirements: normalizeGameplayRequirements(contract, scenes),
     verified: false