miaoda-game-devkit 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# miaoda-game-devkit
+
+妙搭 Phaser 3.90+ 和 Phaser 4 游戏模板的共享开发基础设施。
+
+该开发工具包提供：
+
+- 支持 DOM 鼠标输入的确定性 Phaser 无头测试宿主；
+- 不依赖渲染器的运行时、交互区域和文字健康检查；
+- 由模板平台维护的通用 Vitest 契约测试；
+- 统一的 `miaoda-game-lint` 命令，聚合 TypeScript、Biome、Tailwind、
+  Oxlint 和 Phaser 通用契约检查。
+- 统一的 `defineGameVitestConfig` 配置工厂，固定 Phaser 无头测试依赖的基础配置，
+  同时允许每个游戏配置自身的测试范围、覆盖率和超时等业务选项。
+
+`createHeadlessGame` 还记录测试期间真实发生的输入、完整帧、物理步和 Scene 切换。
+玩法测试可以调用 `host.assertGameplayEvidence()` 把这些客观事实设为门禁；它不推断
+业务语义，authoritative state 仍必须由测试显式断言。
+
+需要将证据绑定到 Vitest 单测试时，使用 `registerGameplayContract` 并传入测试上下文
+中的 `task` 和 `onTestFinished`。验证在测试完成生命周期执行，支持与模板通用
+`afterEach` cleanup 配合；contract id 和 evidence 摘要只通过可序列化 metadata 传递。
+
+模板直接调用开发工具包提供的命令行程序：
+
+```json
+{
+  "scripts": {
+    "lint": "miaoda-game-lint"
+  }
+}
+```
+
+开发工具包自行维护工具版本，并从自身依赖中解析可执行文件，使用方不需要重复声明
+Biome、Oxlint 或 tsgo。仓库中保留稳定的命令入口，因此 `dist/` 尚未生成时，pnpm
+也能正确建立命令链接；工作区开发状态下由 Nx 在模板检查前构建开发工具包，发布包则
+直接携带运行时 `dist/`。`dist/lint/**/*.test.*` 仅供开发工具包自身的契约测试使用，
+由发布文件清单排除，不会进入 npm 包。
+
+monorepo 中的模板可以放置只包含 `extends: ["miaoda-game-devkit/biome"]` 的薄配置，
+用于让 Biome 从模板 package.json 判断依赖声明。规则本身仍由本开发工具包维护；生成后的
+独立模板位于仓库根目录，不需要这个 workspace 定位配置。
+
+模板的 `tsconfig.json` 应继承 `miaoda-game-devkit/tsconfig-base`，只保留源码范围和路径
+别名等项目差异。TypeScript 严格模式、bundler 模块解析和无输出检查等平台基线由开发
+工具包集中维护，`miaoda-game-lint` 会直接检查模板的这个配置。
+
+具体游戏的玩法测试仍由模板使用方放在 `tests/`。运行时测试从本开发工具包
+导入 `createHeadlessGame`，通过真实 DOM 输入驱动游戏，并断言有意义的业务状态变化。
+同步帧逻辑使用 `stepFrames()`；`update()` 返回 Promise 时使用
+`await stepFramesAsync()`，其他同步操作启动生命周期 Promise 后使用 `await settle()`。
+
+模板的 `vitest.config.ts` 应从 `miaoda-game-devkit/vitest-config` 导入
+`defineGameVitestConfig`。JSDOM 环境、Phaser 浏览器构建别名、通用 setup 和 mock 隔离
+以及 Scene coverage 均由开发工具包统一维护。模板只传入 `projectRoot`；确有需要时，可以
+通过 `aliases`、`additionalSetupFiles`、`testTimeout` 和 `hookTimeout` 增加安全的项目配置，
+不能覆盖测试范围、运行环境或 coverage 基线。
+
+## 发布顺序
+
+1. 在开发工具包中运行类型检查和测试。
+2. 使用 `pnpm run release:dry-run` 检查将要发布的文件和清理后的 `package.json`。
+3. 根据版本类型运行 `pnpm run release:patch`、`release:minor` 或 `release:major`。
+   发布脚本会先测试和构建，再通过 `clean-publish` 从临时目录发布；发布包会移除
+   `devDependencies` 和开发脚本，不会修改工作区中的原始 `package.json`。
+4. 也可以使用 `pnpm run release` 发布已经手动设置好版本的开发工具包。
+5. 最后运行模板的 `pnpm run build:template`，让 `output/` 使用已发布版本重新生成锁文件。
+
+`pnpm-workspace.yaml` 已将 `miaoda-game-devkit` 加入 `minimumReleaseAgeExclude`，
+因此新版本发布后无需等待 24 小时即可生成模板锁文件。`--skip-install` 仅用于发布前
+检查 `output/` 的产物边界，不能用于正式 CI 构建。

package/bin/miaoda-game-lint.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require("../dist/cli/lint.js");

package/biome-config.json

@@ -0,0 +1,24 @@
+{
+  "files": {
+    "includes": ["**/src/**/*.{js,ts}"]
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": false,
+      "correctness": {
+        "noUndeclaredDependencies": "error",
+        "useExhaustiveDependencies": "warn"
+      },
+      "suspicious": {
+        "noRedeclare": "error"
+      },
+      "style": {
+        "noCommonJs": "error"
+      }
+    }
+  },
+  "formatter": {
+    "enabled": false
+  }
+}

package/dist/cli/lint.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli/lint.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_module = require("module");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var devkitRoot = (0, import_node_path.resolve)(__dirname, "../..");
+var projectRoot = process.cwd();
+var requireFromDevkit = (0, import_node_module.createRequire)((0, import_node_path.join)(devkitRoot, "package.json"));
+var contractsOnly = process.argv.slice(2).includes("--contracts-only");
+var projectBiomeConfig = (0, import_node_path.join)(projectRoot, "biome.json");
+var biomeConfig = (0, import_node_fs.existsSync)(projectBiomeConfig) ? projectBiomeConfig : (0, import_node_path.join)(devkitRoot, "biome-config.json");
+function resolveBin(packageName, binName) {
+  const packageJsonPath = requireFromDevkit.resolve(`${packageName}/package.json`);
+  const packageJson = JSON.parse((0, import_node_fs.readFileSync)(packageJsonPath, "utf8"));
+  const relativeBin = typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin?.[binName];
+  if (!relativeBin) {
+    throw new Error(`${packageName} does not expose the ${binName} executable`);
+  }
+  return (0, import_node_path.resolve)((0, import_node_path.dirname)(packageJsonPath), relativeBin);
+}
+function run(name, packageName, binName, args) {
+  return new Promise((resolveResult) => {
+    const child = (0, import_node_child_process.spawn)(process.execPath, [resolveBin(packageName, binName), ...args], {
+      cwd: projectRoot,
+      env: process.env,
+      stdio: "inherit"
+    });
+    child.once("error", (error) => {
+      console.error(`[${name}] ${error.message}`);
+      resolveResult({ name, ok: false });
+    });
+    child.once("exit", (code) => {
+      resolveResult({ name, ok: code === 0 });
+    });
+  });
+}
+async function runContracts() {
+  return run(
+    "vitest",
+    "vitest",
+    "vitest",
+    ["run", "--config", (0, import_node_path.join)(devkitRoot, "dist/lint/vitest.config.mjs")]
+  );
+}
+async function runAllChecks() {
+  if (contractsOnly) {
+    return [await runContracts()];
+  }
+  const [tsgo, biome] = await Promise.all([
+    run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),
+    run("biome", "@biomejs/biome", "biome", [
+      "lint",
+      "--config-path",
+      biomeConfig,
+      "src"
+    ])
+  ]);
+  const tailwindOutput = (0, import_node_path.join)((0, import_node_os.tmpdir)(), `miaoda-game-devkit-${process.pid}.css`);
+  const tailwind = await run("tailwind", "tailwindcss", "tailwindcss", [
+    "-i",
+    (0, import_node_path.join)(projectRoot, "src/index.css"),
+    "-o",
+    tailwindOutput
+  ]);
+  (0, import_node_fs.rmSync)(tailwindOutput, { force: true });
+  const oxlint = await run("oxlint", "oxlint", "oxlint", [
+    "-c",
+    (0, import_node_path.join)(devkitRoot, "oxlint-config.json"),
+    "src"
+  ]);
+  const contracts = await runContracts();
+  return [tsgo, biome, tailwind, oxlint, contracts];
+}
+async function main() {
+  const results = await runAllChecks();
+  const failed = results.filter((result) => !result.ok);
+  console.log("");
+  if (failed.length === 0) {
+    console.log("RESULT: ALL CHECKS PASSED - Finished with 0 errors. Found no issues.");
+    return;
+  }
+  console.error(`RESULT: FAILED - Found errors in: ${failed.map(({ name }) => name).join(", ")}`);
+  console.error("Fix all lint errors, then re-run 'pnpm lint'.");
+  process.exitCode = 1;
+}
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/dist/index.d.mts

@@ -0,0 +1,111 @@
+import * as Phaser from 'phaser';
+
+interface HeadlessGameHost<TScene extends Phaser.Scene> {
+    game: Phaser.Game;
+    scene: TScene;
+    input: HeadlessInputDriver;
+    /** 当前隔离 host 实际执行过的客观操作证据。 */
+    readonly evidence: Readonly<HeadlessGameplayEvidence>;
+    /** 当缺少所要求的输入、时间、物理或转场证据时失败。 */
+    assertGameplayEvidence(requirements?: HeadlessGameplayEvidenceRequirements): void;
+    settle(): Promise<void>;
+    stepFrames(count?: number): void;
+    stepFramesAsync(count?: number): Promise<void>;
+    stepUntil(condition: () => boolean, maxFrames?: number): number;
+    stepPhysics(steps?: number): void;
+    assertTextHealth(): void;
+    destroy(): void;
+}
+interface HeadlessGameplayEvidence {
+    /** 通过 host 公共 API 推进的完整 Phaser 帧数。 */
+    frames: number;
+    /** 显式执行的 Arcade Physics 单步数。 */
+    physicsSteps: number;
+    /** 投递到 Phaser canvas 的 DOM 鼠标事件数。 */
+    mouseEvents: number;
+    /** 通过输入辅助方法投递的复合 click 次数。 */
+    clicks: number;
+    /** 通过 Scene Plugin 公共 API 观察到的 Scene 操作。 */
+    transitions: ReadonlyArray<{
+        from: string;
+        to: string;
+        method: "start" | "launch" | "switch" | "sleep" | "wake";
+    }>;
+}
+interface HeadlessGameplayEvidenceRequirements {
+    /** 至少要求一次真实 DOM 鼠标事件。 */
+    requireInput?: boolean;
+    /** 至少要求推进一个完整 Phaser 帧。 */
+    requireFrameAdvance?: boolean;
+    /** 至少要求执行一次显式 Arcade Physics 单步。 */
+    requirePhysicsStep?: boolean;
+    /** 要求发生一个或多个目标 key 匹配的 Scene 转场。 */
+    requireTransition?: string | string[];
+}
+interface HeadlessCanvasBounds {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+interface HeadlessInputPoint {
+    clientX: number;
+    clientY: number;
+}
+interface HeadlessMouseInput {
+    move(x: number, y: number, buttons?: number): Promise<void>;
+    down(x: number, y: number): Promise<void>;
+    up(x: number, y: number): Promise<void>;
+    click(x: number, y: number): Promise<void>;
+}
+interface HeadlessInputDriver {
+    readonly canvas: HTMLCanvasElement;
+    readonly mouse: HeadlessMouseInput;
+    setCanvasBounds(bounds: HeadlessCanvasBounds): void;
+    gameToClient(x: number, y: number): HeadlessInputPoint;
+    settle(): Promise<void>;
+}
+type HeadlessGameOptions = Omit<Phaser.Types.Core.GameConfig, "type" | "scene" | "callbacks"> & {
+    /** Maximum time to wait for Scene creation to complete. */
+    bootTimeoutMs?: number;
+    /** Scene types that must be registered before the initial Scene starts. */
+    additionalScenes?: Phaser.Types.Scenes.SceneType[];
+};
+/** Creates one isolated Phaser game and resolves after the scene has run create(). */
+declare function createHeadlessGame<TScene extends Phaser.Scene>(scene: TScene, options?: HeadlessGameOptions): Promise<HeadlessGameHost<TScene>>;
+
+interface GameplayContractOptions extends HeadlessGameplayEvidenceRequirements {
+    /** 生产玩法清单中稳定且可读的 contract 标识。 */
+    id: string;
+}
+interface GameplayContractHandle<TScene extends Phaser.Scene> {
+    /** 将当前 contract 绑定到实际创建的 HEADLESS host。 */
+    attachHost(host: HeadlessGameHost<TScene>): void;
+    /** 立即验证证据；通常由生命周期回调自动执行。 */
+    verify(): void;
+}
+interface GameplayTestContext {
+    task: {
+        meta: Record<string, unknown>;
+    };
+    onTestFinished(callback: () => void | Promise<void>): void;
+    onTestFailed?: (callback: () => void) => void;
+}
+/**
+ * 将一个 gameplay contract 绑定到当前 Vitest 测试。
+ *
+ * 证据校验在 `onTestFinished` 中执行，晚于 `afterEach`，因此即使测试使用
+ * 通用 cleanup 销毁 host，也仍可读取 host 的 renderer-independent evidence。
+ * contract 元数据只包含可序列化值，供 reporter 在 worker 之外汇总。
+ */
+declare function registerGameplayContract<TScene extends Phaser.Scene>(context: GameplayTestContext, options: GameplayContractOptions): GameplayContractHandle<TScene>;
+
+declare function assertSceneRuntimeHealth(scene: Phaser.Scene): void;
+declare function assertSceneInteractiveHealth(scene: Phaser.Scene): void;
+
+/** Returns non-whitespace UTF-16 code units that are absent from a Bitmap Font. */
+declare function collectMissingBitmapGlyphs(text: string, chars: Record<number, unknown>): string[];
+/** Throws an actionable error suitable for CI and coding-agent feedback. */
+declare function assertSceneTextHealth(scene: Phaser.Scene): void;
+
+export { type GameplayContractHandle, type GameplayContractOptions, type GameplayTestContext, type HeadlessCanvasBounds, type HeadlessGameHost, type HeadlessGameOptions, type HeadlessGameplayEvidence, type HeadlessGameplayEvidenceRequirements, type HeadlessInputDriver, type HeadlessInputPoint, type HeadlessMouseInput, assertSceneInteractiveHealth, assertSceneRuntimeHealth, assertSceneTextHealth, collectMissingBitmapGlyphs, createHeadlessGame, registerGameplayContract };

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import * as Phaser from 'phaser';
+
+interface HeadlessGameHost<TScene extends Phaser.Scene> {
+    game: Phaser.Game;
+    scene: TScene;
+    input: HeadlessInputDriver;
+    /** 当前隔离 host 实际执行过的客观操作证据。 */
+    readonly evidence: Readonly<HeadlessGameplayEvidence>;
+    /** 当缺少所要求的输入、时间、物理或转场证据时失败。 */
+    assertGameplayEvidence(requirements?: HeadlessGameplayEvidenceRequirements): void;
+    settle(): Promise<void>;
+    stepFrames(count?: number): void;
+    stepFramesAsync(count?: number): Promise<void>;
+    stepUntil(condition: () => boolean, maxFrames?: number): number;
+    stepPhysics(steps?: number): void;
+    assertTextHealth(): void;
+    destroy(): void;
+}
+interface HeadlessGameplayEvidence {
+    /** 通过 host 公共 API 推进的完整 Phaser 帧数。 */
+    frames: number;
+    /** 显式执行的 Arcade Physics 单步数。 */
+    physicsSteps: number;
+    /** 投递到 Phaser canvas 的 DOM 鼠标事件数。 */
+    mouseEvents: number;
+    /** 通过输入辅助方法投递的复合 click 次数。 */
+    clicks: number;
+    /** 通过 Scene Plugin 公共 API 观察到的 Scene 操作。 */
+    transitions: ReadonlyArray<{
+        from: string;
+        to: string;
+        method: "start" | "launch" | "switch" | "sleep" | "wake";
+    }>;
+}
+interface HeadlessGameplayEvidenceRequirements {
+    /** 至少要求一次真实 DOM 鼠标事件。 */
+    requireInput?: boolean;
+    /** 至少要求推进一个完整 Phaser 帧。 */
+    requireFrameAdvance?: boolean;
+    /** 至少要求执行一次显式 Arcade Physics 单步。 */
+    requirePhysicsStep?: boolean;
+    /** 要求发生一个或多个目标 key 匹配的 Scene 转场。 */
+    requireTransition?: string | string[];
+}
+interface HeadlessCanvasBounds {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+interface HeadlessInputPoint {
+    clientX: number;
+    clientY: number;
+}
+interface HeadlessMouseInput {
+    move(x: number, y: number, buttons?: number): Promise<void>;
+    down(x: number, y: number): Promise<void>;
+    up(x: number, y: number): Promise<void>;
+    click(x: number, y: number): Promise<void>;
+}
+interface HeadlessInputDriver {
+    readonly canvas: HTMLCanvasElement;
+    readonly mouse: HeadlessMouseInput;
+    setCanvasBounds(bounds: HeadlessCanvasBounds): void;
+    gameToClient(x: number, y: number): HeadlessInputPoint;
+    settle(): Promise<void>;
+}
+type HeadlessGameOptions = Omit<Phaser.Types.Core.GameConfig, "type" | "scene" | "callbacks"> & {
+    /** Maximum time to wait for Scene creation to complete. */
+    bootTimeoutMs?: number;
+    /** Scene types that must be registered before the initial Scene starts. */
+    additionalScenes?: Phaser.Types.Scenes.SceneType[];
+};
+/** Creates one isolated Phaser game and resolves after the scene has run create(). */
+declare function createHeadlessGame<TScene extends Phaser.Scene>(scene: TScene, options?: HeadlessGameOptions): Promise<HeadlessGameHost<TScene>>;
+
+interface GameplayContractOptions extends HeadlessGameplayEvidenceRequirements {
+    /** 生产玩法清单中稳定且可读的 contract 标识。 */
+    id: string;
+}
+interface GameplayContractHandle<TScene extends Phaser.Scene> {
+    /** 将当前 contract 绑定到实际创建的 HEADLESS host。 */
+    attachHost(host: HeadlessGameHost<TScene>): void;
+    /** 立即验证证据；通常由生命周期回调自动执行。 */
+    verify(): void;
+}
+interface GameplayTestContext {
+    task: {
+        meta: Record<string, unknown>;
+    };
+    onTestFinished(callback: () => void | Promise<void>): void;
+    onTestFailed?: (callback: () => void) => void;
+}
+/**
+ * 将一个 gameplay contract 绑定到当前 Vitest 测试。
+ *
+ * 证据校验在 `onTestFinished` 中执行，晚于 `afterEach`，因此即使测试使用
+ * 通用 cleanup 销毁 host，也仍可读取 host 的 renderer-independent evidence。
+ * contract 元数据只包含可序列化值，供 reporter 在 worker 之外汇总。
+ */
+declare function registerGameplayContract<TScene extends Phaser.Scene>(context: GameplayTestContext, options: GameplayContractOptions): GameplayContractHandle<TScene>;
+
+declare function assertSceneRuntimeHealth(scene: Phaser.Scene): void;
+declare function assertSceneInteractiveHealth(scene: Phaser.Scene): void;
+
+/** Returns non-whitespace UTF-16 code units that are absent from a Bitmap Font. */
+declare function collectMissingBitmapGlyphs(text: string, chars: Record<number, unknown>): string[];
+/** Throws an actionable error suitable for CI and coding-agent feedback. */
+declare function assertSceneTextHealth(scene: Phaser.Scene): void;
+
+export { type GameplayContractHandle, type GameplayContractOptions, type GameplayTestContext, type HeadlessCanvasBounds, type HeadlessGameHost, type HeadlessGameOptions, type HeadlessGameplayEvidence, type HeadlessGameplayEvidenceRequirements, type HeadlessInputDriver, type HeadlessInputPoint, type HeadlessMouseInput, assertSceneInteractiveHealth, assertSceneRuntimeHealth, assertSceneTextHealth, collectMissingBitmapGlyphs, createHeadlessGame, registerGameplayContract };