2.3 规格的版本与迁移

// file: core/src/ashdeck/migrate.ts
// tier: P
// verify: node --test 'core/test/gd_mech_02_migrate.test.ts'
//
// 规格的版本与迁移。v1 → v2 只做一件事：新增 params.critRate（暴击千分比），默认 0。
// 迁移是**纯函数**：不动任何既有字段，故 runSpec 的 digest 迁移前后逐字相同——
// 「语义等价」在这里是一个可断言的事实，不是形容词。只允许可擦除 TS 语法。

import type { Spec } from "./types.ts";
import { validateSpec } from "./validate.ts";

export const SPEC_VERSION_V1 = 1;
export const SPEC_VERSION_V2 = 2;
export const CRIT_RATE_DEFAULT = 0;

export type ParamsV2 = Spec["params"] & { critRate: number };
export type SpecV2 = Omit<Spec, "params"> & { params: ParamsV2 };

/** v1 → v2：补 params.critRate（默认 0）并把 spec_version 抬到 2。已是 v2 则原样返回。 */
export function migrate(spec: Spec): SpecV2 {
  const v = spec.spec_version;
  if (v === SPEC_VERSION_V2) return spec as unknown as SpecV2;
  if (v !== SPEC_VERSION_V1) throw new Error(`未知 spec_version: ${v}`);
  const params: ParamsV2 = { ...spec.params, critRate: CRIT_RATE_DEFAULT };
  return { ...spec, spec_version: SPEC_VERSION_V2, params };
}

/** v2 校验器：v1 的判据 + critRate 必填且落在 0–1000 千分比。 */
export function validateSpecV2(spec: SpecV2): string[] {
  const errs = validateSpec(spec as unknown as Record<string, unknown>);
  if (errs.length > 0) return errs;
  const c = spec.params.critRate;
  if (!Number.isInteger(c)) errs.push("v2: params.critRate 必须是整数");
  else if (c < 0 || c > 1000) errs.push(`v2: params.critRate 必须在 0–1000（实为 ${c}）`);
  return errs;
}

// file: core/test/gd_mech_02_migrate.test.ts
// tier: P
// verify: node --test 'core/test/gd_mech_02_migrate.test.ts'
//
// 2.3 的迁移测试：v1 规格迁到 v2 后①能被 v2 校验器接受，②与「v1 被 v2 校验器拒绝」形成对照，
// ③**语义等价**——迁移前后 runSpec 的 digest 逐字相同（critRate 默认 0，不参与本局结算）。

import { test } from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { dirname, join } from "node:path";

import { runSpec } from "../src/ashdeck/combat.ts";
import { digestSnap } from "../src/ashdeck/digest.ts";
import { migrate, validateSpecV2, SPEC_VERSION_V2, CRIT_RATE_DEFAULT } from "../src/ashdeck/migrate.ts";
import type { Spec } from "../src/ashdeck/types.ts";

const HERE = dirname(fileURLToPath(import.meta.url));
const SPEC: Spec = JSON.parse(
  readFileSync(join(HERE, "..", "..", "config", "play_spec.json"), "utf8"),
);

// 迁移前 v1 规格的基线 digest（与 gd_mech_base.test.ts 同一条）。
const V1_DIGEST =
  '{"block":0,"cardCount":12,"damageConserved":true,"dealt":50,"enemyHp":0,' +
  '"energy":1,"hand":["strike","jab","heavy"],"over":true,"played":9,' +
  '"playerHp":48,"turn":4,"won":true}';

test("迁移：v1 → v2，spec_version=2 且 critRate 落到默认 0", () => {
  const v2 = migrate(SPEC);
  assert.equal(v2.spec_version, SPEC_VERSION_V2);
  assert.equal(v2.params.critRate, CRIT_RATE_DEFAULT);
  assert.equal(v2.params.critRate, 0);
});

test("迁移后能被 v2 校验器接受（0 错）", () => {
  assert.deepEqual(validateSpecV2(migrate(SPEC)), []);
});

test("对照：未迁移的 v1 规格被 v2 校验器拒绝（缺 critRate）", () => {
  const errs = validateSpecV2(SPEC as never);
  assert.ok(errs.some((e) => e.includes("critRate")));
});

test("语义等价：迁移前后 runSpec 的 digest 逐字相同", () => {
  const before = digestSnap(runSpec(SPEC));
  const after = digestSnap(runSpec(migrate(SPEC) as unknown as Spec));
  assert.equal(before, after);
  assert.equal(before, V1_DIGEST);
});

test("迁移是幂等的：二次迁移与一次迁移逐字段相同", () => {
  const once = migrate(SPEC);
  const twice = migrate(once as unknown as Spec);
  assert.deepEqual(twice, once);
});

test("负例：未知 spec_version（99）必须抛错，不许静默放过", () => {
  const bad = { ...SPEC, spec_version: 99 } as Spec;
  assert.throws(() => migrate(bad), /未知 spec_version: 99/);
});

✔ 迁移：v1 → v2，spec_version=2 且 critRate 落到默认 0 (0.514709ms)
✔ 迁移后能被 v2 校验器接受（0 错） (0.677666ms)
✔ 对照：未迁移的 v1 规格被 v2 校验器拒绝（缺 critRate） (0.142167ms)
✔ 语义等价：迁移前后 runSpec 的 digest 逐字相同 (0.286958ms)
✔ 迁移是幂等的：二次迁移与一次迁移逐字段相同 (0.064334ms)
✔ 负例：未知 spec_version（99）必须抛错，不许静默放过 (0.224125ms)
ℹ tests 6
ℹ pass 6
ℹ fail 0

v1 digest {"block":0,"cardCount":12,"damageConserved":true,"dealt":50,"enemyHp":0,"energy":1,"hand":["strike","jab","heavy"],"over":true,"played":9,"playerHp":48,"turn":4,"won":true}
v2 digest {"block":0,"cardCount":12,"damageConserved":true,"dealt":50,"enemyHp":0,"energy":1,"hand":["strike","jab","heavy"],"over":true,"played":9,"playerHp":48,"turn":4,"won":true}
v2 params {"playerHp":60,"enemyHp":50,"enemyAttack":6,"energyMax":3,"handSize":5,"turnLimit":20,"rewardGold":12,"punishHp":4,"critRate":0}
spec_version 2

{
  "playerHp": 60,
  "enemyHp": 50,
  "enemyAttack": 6,
  "energyMax": 3,
  "handSize": 5,
  "turnLimit": 20,
  "rewardGold": 12,
  "punishHp": 4,
  "critRate": 0
}