miaoda-game-devkit 0.1.0 → 0.2.0

package/dist/lint/contracts.config.mjs

@@ -0,0 +1,36 @@
+// src/lint/vitest.config.ts
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { defineConfig } from "vitest/config";
+var phaserPackageRoot = dirname(
+  fileURLToPath(import.meta.resolve("phaser/package.json"))
+);
+var vitest_config_default = defineConfig({
+  resolve: {
+    alias: {
+      phaser: resolve(phaserPackageRoot, "dist/phaser.js")
+    }
+  },
+  test: {
+    server: {
+      deps: {
+        inline: [/miaoda-game-/]
+      }
+    },
+    environment: "jsdom",
+    environmentOptions: {
+      jsdom: {
+        url: "http://localhost/"
+      }
+    },
+    include: [resolve(import.meta.dirname, "*.contract.mjs")],
+    // 发布后的契约位于使用方的 node_modules 目录中。
+    exclude: [],
+    setupFiles: [resolve(import.meta.dirname, "setup.mjs")],
+    restoreMocks: true,
+    clearMocks: true
+  }
+});
+export {
+  vitest_config_default as default
+};

package/dist/lint/gameplay-audit.contract.mjs

@@ -0,0 +1,426 @@
+// src/lint/gameplay-audit.test.ts
+import { describe, expect, it } from "vitest";
+
+// src/gameplay-audit.ts
+function normalizeList(value) {
+  if (value === void 0) return [];
+  const values = typeof value === "string" ? [value] : value;
+  return [...new Set(values.map((item) => item.trim()).filter(Boolean))];
+}
+function normalizeSet(values) {
+  return [
+    ...new Set(values.map((value) => value.trim()).filter(Boolean))
+  ].sort();
+}
+function sameSet(left, right) {
+  return JSON.stringify(normalizeSet(left)) === JSON.stringify(normalizeSet(right));
+}
+function normalizeGameplayRequirements(requirements, scenes) {
+  const requiredScenes = normalizeSet([
+    ...scenes,
+    ...normalizeList(requirements.requireScene)
+  ]);
+  return {
+    requireInput: requirements.requireInput || void 0,
+    requireFrameAdvance: requirements.requireFrameAdvance || void 0,
+    requirePhysicsStep: requirements.requirePhysicsStep || void 0,
+    requireTransition: normalizeList(requirements.requireTransition),
+    requireScene: requiredScenes,
+    requireRestart: normalizeList(requirements.requireRestart),
+    requireCheckpoint: normalizeList(requirements.requireCheckpoint),
+    requireDestroy: true
+  };
+}
+function createGameplayContractMetadata(contract) {
+  const scenes = normalizeSet(contract.scenes);
+  return {
+    id: contract.id.trim(),
+    scenes,
+    requirements: normalizeGameplayRequirements(contract, scenes),
+    verified: false
+  };
+}
+function validateGameplayAuditOptions(options2) {
+  const issues = [];
+  const scenes = normalizeSet(options2.scenes);
+  if (scenes.length === 0) issues.push("gameplayAudit.scenes \u4E0D\u80FD\u4E3A\u7A7A\u3002");
+  if (scenes.length !== options2.scenes.length) {
+    issues.push("gameplayAudit.scenes \u4E0D\u80FD\u5305\u542B\u7A7A\u503C\u6216\u91CD\u590D Scene key\u3002");
+  }
+  const contractIds = /* @__PURE__ */ new Set();
+  const coveredScenes = /* @__PURE__ */ new Set();
+  for (const contract of options2.contracts) {
+    const id = contract.id.trim();
+    if (!id) {
+      issues.push("gameplayAudit.contracts \u4E2D\u5B58\u5728\u7A7A contract id\u3002");
+    } else if (id !== contract.id) {
+      issues.push(`contract id "${contract.id}" \u4E0D\u80FD\u5305\u542B\u9996\u5C3E\u7A7A\u767D\u3002`);
+    } else if (contractIds.has(id)) {
+      issues.push(`gameplayAudit.contracts \u5305\u542B\u91CD\u590D contract id\uFF1A${id}\u3002`);
+    } else {
+      contractIds.add(id);
+    }
+    const testFile = contract.testFile.replaceAll("\\", "/");
+    if (!/^tests\/.+\.test\.ts$/.test(testFile) || testFile.split("/").includes("..")) {
+      issues.push(
+        `contract "${id || "<empty>"}" \u7684 testFile \u5FC5\u987B\u5339\u914D tests/**/*.test.ts\u3002`
+      );
+    }
+    const contractScenes = normalizeSet(contract.scenes);
+    if (contractScenes.length === 0) {
+      issues.push(`contract "${id || "<empty>"}" \u5FC5\u987B\u58F0\u660E\u81F3\u5C11\u4E00\u4E2A Scene\u3002`);
+    }
+    for (const scene of contractScenes) {
+      coveredScenes.add(scene);
+      if (!scenes.includes(scene)) {
+        issues.push(
+          `contract "${id}" \u5F15\u7528\u4E86\u672A\u5217\u5165 gameplayAudit.scenes \u7684 Scene\uFF1A${scene}\u3002`
+        );
+      }
+    }
+  }
+  for (const scene of scenes) {
+    if (!coveredScenes.has(scene)) {
+      issues.push(`Scene "${scene}" \u6CA1\u6709\u4EFB\u4F55 gameplay contract \u8D1F\u8D23\u9A8C\u8BC1\u3002`);
+    }
+  }
+  if (options2.contracts.length === 0)
+    issues.push("gameplayAudit.contracts \u4E0D\u80FD\u4E3A\u7A7A\u3002");
+  return issues;
+}
+function getDefinitionIssues(expected, actual) {
+  const issues = [];
+  const expectedMetadata = createGameplayContractMetadata(expected);
+  if (!sameSet(expectedMetadata.scenes, actual.scenes)) {
+    issues.push(
+      `contract "${expected.id}" \u58F0\u660E\u7684 Scene \u4E0E gameplayAudit \u6E05\u5355\u4E0D\u4E00\u81F4\u3002`
+    );
+  }
+  if (JSON.stringify(expectedMetadata.requirements) !== JSON.stringify(actual.requirements)) {
+    issues.push(
+      `contract "${expected.id}" \u7684 evidence requirements \u4E0E gameplayAudit \u6E05\u5355\u4E0D\u4E00\u81F4\u3002`
+    );
+  }
+  return issues;
+}
+function auditGameplayCollection(options2, file, tests) {
+  const normalizedFile = file.replaceAll("\\", "/");
+  const expected = options2.contracts.filter(
+    (contract) => contract.testFile.replaceAll("\\", "/") === normalizedFile
+  );
+  const actual = tests.filter((test) => test.metadata);
+  const issues = [];
+  for (const contract of expected) {
+    const matches = actual.filter((test) => test.metadata?.id === contract.id);
+    if (matches.length === 0) {
+      issues.push(
+        `\u6D4B\u8BD5\u6267\u884C\u524D\u672A\u6536\u96C6\u5230 contract "${contract.id}"\uFF08${normalizedFile}\uFF09\u3002`
+      );
+    } else if (matches.length > 1) {
+      issues.push(
+        `contract "${contract.id}" \u5728 ${normalizedFile} \u4E2D\u91CD\u590D\u5B9A\u4E49\u3002`
+      );
+    } else if (matches[0]?.metadata) {
+      issues.push(...getDefinitionIssues(contract, matches[0].metadata));
+    }
+  }
+  for (const test of actual) {
+    const id = test.metadata?.id;
+    if (!id) continue;
+    const expectedContract = options2.contracts.find(
+      (contract) => contract.id === id
+    );
+    if (!expectedContract) {
+      issues.push(
+        `\u6D4B\u8BD5 "${test.name}" \u58F0\u660E\u4E86\u672A\u5217\u5165 gameplayAudit \u6E05\u5355\u7684 contract "${id}"\u3002`
+      );
+    } else if (expectedContract.testFile.replaceAll("\\", "/") !== normalizedFile) {
+      issues.push(
+        `contract "${id}" \u5FC5\u987B\u4F4D\u4E8E ${expectedContract.testFile}\uFF0C\u5B9E\u9645\u4F4D\u4E8E ${normalizedFile}\u3002`
+      );
+    }
+  }
+  return { passed: issues.length === 0, issues };
+}
+function getGameplayEvidenceIssues(id, requirements, evidence) {
+  const issues = [];
+  const inputEvents = evidence.mouseEvents + evidence.keyboardEvents + evidence.touchEvents;
+  if (requirements.requireInput && inputEvents === 0)
+    issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002`);
+  if (requirements.requireFrameAdvance && evidence.frames === 0)
+    issues.push(`contract "${id}" \u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27\u3002`);
+  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0)
+    issues.push(`contract "${id}" \u672A\u63A8\u8FDB Arcade Physics\u3002`);
+  for (const target of normalizeList(requirements.requireTransition)) {
+    if (!evidence.transitions.some((transition) => transition.to === target)) {
+      issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u5230 ${target} \u7684 Scene \u8F6C\u573A\u3002`);
+    }
+  }
+  for (const scene of normalizeList(requirements.requireScene)) {
+    if (!evidence.visitedScenes.includes(scene))
+      issues.push(`contract "${id}" \u672A\u8BBF\u95EE Scene "${scene}"\u3002`);
+  }
+  for (const scene of normalizeList(requirements.requireRestart)) {
+    if (!evidence.restartedScenes.includes(scene))
+      issues.push(`contract "${id}" \u672A\u91CD\u542F Scene "${scene}"\u3002`);
+  }
+  for (const checkpoint of normalizeList(requirements.requireCheckpoint)) {
+    if (!evidence.checkpoints.includes(checkpoint))
+      issues.push(`contract "${id}" \u7F3A\u5C11 checkpoint "${checkpoint}"\u3002`);
+  }
+  if (requirements.requireDestroy && !evidence.destroyed)
+    issues.push(`contract "${id}" \u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1\u3002`);
+  return issues;
+}
+function auditGameplayRun(options2, tests) {
+  const issues = [];
+  const actualContracts = tests.filter((test) => test.metadata);
+  const acceptedEvidence = [];
+  for (const expected of options2.contracts) {
+    const matches = actualContracts.filter(
+      (test2) => test2.metadata?.id === expected.id
+    );
+    if (matches.length === 0) {
+      issues.push(`\u7F3A\u5C11 gameplay contract "${expected.id}"\u3002`);
+      continue;
+    }
+    if (matches.length > 1) {
+      issues.push(`gameplay contract "${expected.id}" \u88AB\u591A\u4E2A\u6D4B\u8BD5\u91CD\u590D\u58F0\u660E\u3002`);
+      continue;
+    }
+    const test = matches[0];
+    const metadata = test?.metadata;
+    if (!test || !metadata) continue;
+    if (test.file.replaceAll("\\", "/") !== expected.testFile.replaceAll("\\", "/")) {
+      issues.push(
+        `contract "${expected.id}" \u5FC5\u987B\u4F4D\u4E8E ${expected.testFile}\uFF0C\u5B9E\u9645\u4F4D\u4E8E ${test.file}\u3002`
+      );
+    }
+    issues.push(...getDefinitionIssues(expected, metadata));
+    if (test.state !== "passed") {
+      issues.push(`contract "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      continue;
+    }
+    if (!metadata.verified || !metadata.evidence) {
+      issues.push(`contract "${expected.id}" \u672A\u5B8C\u6210 onTestFinished \u8BC1\u636E\u6821\u9A8C\u3002`);
+      continue;
+    }
+    const evidenceIssues = getGameplayEvidenceIssues(
+      expected.id,
+      metadata.requirements,
+      metadata.evidence
+    );
+    issues.push(...evidenceIssues);
+    if (evidenceIssues.length === 0) acceptedEvidence.push(metadata.evidence);
+  }
+  for (const test of actualContracts) {
+    const id = test.metadata?.id;
+    if (id && !options2.contracts.some((contract) => contract.id === id)) {
+      issues.push(
+        `\u53D1\u73B0\u672A\u5217\u5165 gameplayAudit \u6E05\u5355\u7684 contract "${id}"\uFF08${test.file}\uFF09\u3002`
+      );
+    }
+  }
+  const registeredScenes = normalizeSet(
+    acceptedEvidence.flatMap((evidence) => evidence.registeredScenes)
+  );
+  const expectedScenes = normalizeSet(options2.scenes);
+  for (const scene of expectedScenes) {
+    if (!registeredScenes.includes(scene))
+      issues.push(
+        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u4EFB\u4F55\u901A\u8FC7\u5BA1\u8BA1\u7684 host registry \u4E2D\u3002`
+      );
+  }
+  for (const scene of registeredScenes) {
+    if (!expectedScenes.includes(scene))
+      issues.push(
+        `host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "${scene}"\u3002`
+      );
+  }
+  return { passed: issues.length === 0, issues: [...new Set(issues)] };
+}
+
+// src/lint/gameplay-audit.test.ts
+var options = {
+  scenes: ["IndexScene", "BattleScene"],
+  contracts: [
+    {
+      id: "gameplay.main-flow",
+      testFile: "tests/gameplay.test.ts",
+      scenes: ["IndexScene", "BattleScene"],
+      requireInput: true,
+      requireFrameAdvance: true,
+      requireTransition: "BattleScene",
+      requireCheckpoint: ["progress", "recovery"],
+      requireRestart: "BattleScene"
+    }
+  ]
+};
+function createEvidence() {
+  return {
+    frames: 3,
+    physicsSteps: 0,
+    mouseEvents: 3,
+    keyboardEvents: 0,
+    touchEvents: 0,
+    clicks: 1,
+    registeredScenes: ["IndexScene", "BattleScene"],
+    visitedScenes: ["IndexScene", "BattleScene"],
+    restartedScenes: ["BattleScene"],
+    checkpoints: ["progress", "recovery"],
+    destroyed: true,
+    transitions: [{ from: "IndexScene", to: "BattleScene", method: "start" }]
+  };
+}
+function createPassingTest() {
+  const metadata = createGameplayContractMetadata(options.contracts[0]);
+  metadata.evidence = createEvidence();
+  metadata.verified = true;
+  return {
+    file: "tests/gameplay.test.ts",
+    name: "main gameplay flow",
+    state: "passed",
+    metadata
+  };
+}
+describe("gameplay audit", () => {
+  it("\u62D2\u7EDD\u672A\u88AB contract \u8986\u76D6\u7684\u751F\u4EA7 Scene", () => {
+    expect(
+      validateGameplayAuditOptions({
+        scenes: ["IndexScene", "ResultScene"],
+        contracts: [options.contracts[0]]
+      })
+    ).toContain('Scene "ResultScene" \u6CA1\u6709\u4EFB\u4F55 gameplay contract \u8D1F\u8D23\u9A8C\u8BC1\u3002');
+  });
+  it("\u62D2\u7EDD\u4F1A\u5728 metadata \u4E2D\u88AB\u9759\u9ED8\u6539\u5199\u7684 contract id", () => {
+    expect(
+      validateGameplayAuditOptions({
+        scenes: ["IndexScene"],
+        contracts: [
+          {
+            id: " IndexScene.boot ",
+            testFile: "tests/gameplay.test.ts",
+            scenes: ["IndexScene"]
+          }
+        ]
+      })
+    ).toContain('contract id " IndexScene.boot " \u4E0D\u80FD\u5305\u542B\u9996\u5C3E\u7A7A\u767D\u3002');
+  });
+  it("\u8BA9 contract testFile \u4E0E\u5171\u4EAB Vitest \u6D4B\u8BD5\u8303\u56F4\u4FDD\u6301\u4E00\u81F4", () => {
+    const createOptions = (testFile) => ({
+      scenes: ["IndexScene"],
+      contracts: [
+        {
+          id: "IndexScene.boot",
+          testFile,
+          scenes: ["IndexScene"]
+        }
+      ]
+    });
+    expect(
+      validateGameplayAuditOptions(createOptions("tests/gameplay.test.tsx"))
+    ).toContain(
+      'contract "IndexScene.boot" \u7684 testFile \u5FC5\u987B\u5339\u914D tests/**/*.test.ts\u3002'
+    );
+    expect(
+      validateGameplayAuditOptions(
+        createOptions("tests/flows/flow..recovery.test.ts")
+      )
+    ).not.toContain(
+      'contract "IndexScene.boot" \u7684 testFile \u5FC5\u987B\u5339\u914D tests/**/*.test.ts\u3002'
+    );
+    expect(
+      validateGameplayAuditOptions(createOptions("tests/../outside.test.ts"))
+    ).toContain(
+      'contract "IndexScene.boot" \u7684 testFile \u5FC5\u987B\u5339\u914D tests/**/*.test.ts\u3002'
+    );
+  });
+  it("\u5728\u6D4B\u8BD5\u6267\u884C\u524D\u62A5\u544A\u672A\u6536\u96C6\u5230\u7684\u9759\u6001 contract", () => {
+    const result = auditGameplayCollection(
+      options,
+      "tests/gameplay.test.ts",
+      []
+    );
+    expect(result).toEqual({
+      passed: false,
+      issues: [
+        '\u6D4B\u8BD5\u6267\u884C\u524D\u672A\u6536\u96C6\u5230 contract "gameplay.main-flow"\uFF08tests/gameplay.test.ts\uFF09\u3002'
+      ]
+    });
+  });
+  it("\u5728\u6D4B\u8BD5\u6267\u884C\u524D\u62A5\u544A\u5199\u5728\u9519\u8BEF\u6587\u4EF6\u4E2D\u7684 contract", () => {
+    const metadata = createGameplayContractMetadata(options.contracts[0]);
+    const result = auditGameplayCollection(options, "tests/wrong.test.ts", [
+      {
+        file: "tests/wrong.test.ts",
+        name: "misplaced gameplay flow",
+        state: "pending",
+        metadata
+      }
+    ]);
+    expect(result).toEqual({
+      passed: false,
+      issues: [
+        'contract "gameplay.main-flow" \u5FC5\u987B\u4F4D\u4E8E tests/gameplay.test.ts\uFF0C\u5B9E\u9645\u4F4D\u4E8E tests/wrong.test.ts\u3002'
+      ]
+    });
+  });
+  it("\u63A5\u53D7\u5B9A\u4E49\u3001Ledger \u548C Scene registry \u90FD\u5B8C\u6574\u7684\u6D4B\u8BD5\u8FD0\u884C", () => {
+    expect(auditGameplayRun(options, [createPassingTest()])).toEqual({
+      passed: true,
+      issues: []
+    });
+  });
+  it("\u6C47\u603B checkpoint\u3001restart\u3001destroy \u548C\u989D\u5916 Scene \u7F3A\u53E3", () => {
+    const evidence = createEvidence();
+    evidence.checkpoints = ["progress"];
+    evidence.restartedScenes = [];
+    evidence.destroyed = false;
+    evidence.registeredScenes.push("DebugScene");
+    const test = createPassingTest();
+    test.metadata.evidence = evidence;
+    const result = auditGameplayRun(options, [test]);
+    expect(result.passed).toBe(false);
+    expect(result.issues).toEqual(
+      expect.arrayContaining([
+        'contract "gameplay.main-flow" \u672A\u91CD\u542F Scene "BattleScene"\u3002',
+        'contract "gameplay.main-flow" \u7F3A\u5C11 checkpoint "recovery"\u3002',
+        'contract "gameplay.main-flow" \u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1\u3002'
+      ])
+    );
+  });
+  it("\u62D2\u7EDD\u901A\u8FC7\u5951\u7EA6\u7684 host registry \u4E2D\u51FA\u73B0\u6E05\u5355\u5916 Scene", () => {
+    const test = createPassingTest();
+    test.metadata.evidence.registeredScenes.push("DebugScene");
+    expect(auditGameplayRun(options, [test]).issues).toContain(
+      'host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "DebugScene"\u3002'
+    );
+  });
+  it("\u5355\u72EC\u8FD4\u56DE\u53EF\u64CD\u4F5C\u7684 evidence \u7F3A\u53E3", () => {
+    const metadata = createGameplayContractMetadata(options.contracts[0]);
+    const evidence = createEvidence();
+    evidence.mouseEvents = 0;
+    evidence.transitions = [];
+    expect(
+      getGameplayEvidenceIssues(metadata.id, metadata.requirements, evidence)
+    ).toEqual(
+      expect.arrayContaining([
+        'contract "gameplay.main-flow" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002',
+        'contract "gameplay.main-flow" \u672A\u8BB0\u5F55\u5230 BattleScene \u7684 Scene \u8F6C\u573A\u3002'
+      ])
+    );
+  });
+  it("\u4EC5\u5728\u5951\u7EA6\u663E\u5F0F\u58F0\u660E\u65F6\u8981\u6C42 Arcade Physics \u8BC1\u636E", () => {
+    const evidence = createEvidence();
+    expect(getGameplayEvidenceIssues("no-physics", {}, evidence)).not.toContain(
+      'contract "no-physics" \u672A\u63A8\u8FDB Arcade Physics\u3002'
+    );
+    expect(
+      getGameplayEvidenceIssues(
+        "arcade-physics",
+        { requirePhysicsStep: true },
+        evidence
+      )
+    ).toContain('contract "arcade-physics" \u672A\u63A8\u8FDB Arcade Physics\u3002');
+  });
+});