2.2 模式校验与语义校验

// file: core/src/ashdeck/validate.ts
// tier: P
// verify: node --test 'core/test/gd_mech_02_validate.test.ts'
//
// 规格的两级校验：
//   模式校验 validateSchema    —— 必填字段存在、类型正确、数值在域内（结构）；
//   语义校验 validateSemantics —— 引用完整性（strategy 的 p<i> 可达、卡池非空、turnLimit>0、energyMax>=0）。
// 返回错误字符串数组，空数组即合法。判据全整数、无浮点，只允许可擦除 TS 语法（禁 enum / namespace / 装饰器）。

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

export const TOP_FIELDS: string[] = [
  "spec_version", "id", "name", "seed", "rng", "params", "cards", "goals", "invariants", "strategy",
];
export const RNG_FIELDS: string[] = ["algo", "mod", "mul"];
export const PARAM_FIELDS: string[] = [
  "playerHp", "enemyHp", "enemyAttack", "energyMax", "handSize", "turnLimit", "rewardGold", "punishHp",
];
export const CARD_FIELDS: string[] = ["id", "cost", "damage", "block", "count", "rarity"];
export const CARD_INT_FIELDS: string[] = ["cost", "damage", "block", "count"];

/** 整数判据：JS 的 number 只有整数与 IEEE754 双精度两种，这里只认整数。 */
export function isInt(x: unknown): boolean {
  return typeof x === "number" && Number.isInteger(x);
}

function isObj(x: unknown): boolean {
  return x !== null && typeof x === "object" && !Array.isArray(x);
}

/** 模式校验：必填字段存在、类型正确、数值在域内。返回错误清单。 */
export function validateSchema(spec: Record<string, unknown>): string[] {
  const errs: string[] = [];
  if (!isObj(spec)) return ["schema: 根节点必须是对象"];

  for (const k of TOP_FIELDS) if (!(k in spec)) errs.push(`schema: 缺字段 ${k}`);
  if (!isInt(spec.spec_version)) errs.push("schema: spec_version 必须是整数");
  if (typeof spec.id !== "string" || spec.id === "") errs.push("schema: id 必须是非空字符串");
  if (typeof spec.name !== "string" || spec.name === "") errs.push("schema: name 必须是非空字符串");
  if (!isInt(spec.seed)) errs.push("schema: seed 必须是整数");

  if (!isObj(spec.rng)) errs.push("schema: rng 必须是对象");
  else {
    const r = spec.rng as Record<string, unknown>;
    for (const k of RNG_FIELDS) if (!(k in r)) errs.push(`schema: 缺 rng.${k}`);
    if (typeof r.algo !== "string") errs.push("schema: rng.algo 必须是字符串");
    if (!isInt(r.mod)) errs.push("schema: rng.mod 必须是整数");
    if (!isInt(r.mul)) errs.push("schema: rng.mul 必须是整数");
  }

  if (!isObj(spec.params)) errs.push("schema: params 必须是对象");
  else {
    const p = spec.params as Record<string, unknown>;
    for (const k of PARAM_FIELDS) {
      if (!(k in p)) errs.push(`schema: 缺 params.${k}`);
      else if (!isInt(p[k])) errs.push(`schema: params.${k} 必须是整数`);
    }
  }

  if (!Array.isArray(spec.cards)) errs.push("schema: cards 必须是数组");
  else if (spec.cards.length === 0) errs.push("schema: cards 不能为空数组");
  else {
    for (let i = 0; i < spec.cards.length; i += 1) {
      const c = spec.cards[i];
      if (!isObj(c)) {
        errs.push(`schema: cards[${i}] 必须是对象`);
        continue;
      }
      const card = c as Record<string, unknown>;
      for (const k of CARD_FIELDS) if (!(k in card)) errs.push(`schema: 缺 cards[${i}].${k}`);
      if (typeof card.id !== "string" || card.id === "") errs.push(`schema: cards[${i}].id 必须是非空字符串`);
      if (typeof card.rarity !== "string" || card.rarity === "") errs.push(`schema: cards[${i}].rarity 必须是非空字符串`);
      for (const k of CARD_INT_FIELDS) {
        if (!isInt(card[k])) errs.push(`schema: cards[${i}].${k} 必须是整数`);
      }
    }
  }

  if (!isObj(spec.goals)) errs.push("schema: goals 必须是对象");
  else {
    const g = spec.goals as Record<string, unknown>;
    for (const k of ["primary", "secondary", "limit"]) {
      if (typeof g[k] !== "string" || g[k] === "") errs.push(`schema: goals.${k} 必须是非空字符串`);
    }
  }

  if (!Array.isArray(spec.invariants)) errs.push("schema: invariants 必须是数组");
  else if (spec.invariants.length === 0) errs.push("schema: invariants 不能为空数组");
  else if (!spec.invariants.every((x) => typeof x === "string")) errs.push("schema: invariants 元素必须是字符串");

  if (!Array.isArray(spec.strategy)) errs.push("schema: strategy 必须是数组");
  else if (spec.strategy.length === 0) errs.push("schema: strategy 不能为空数组");
  else if (!spec.strategy.every((x) => typeof x === "string")) errs.push("schema: strategy 元素必须是字符串");

  return errs;
}

/** 语义校验：引用完整性。只在结构合法时才有意义（调用方须先过模式校验）。 */
export function validateSemantics(spec: Spec): string[] {
  const errs: string[] = [];
  const p = spec.params;
  const deck = spec.cards.reduce((a, c) => a + c.count, 0);
  if (deck <= 0) errs.push("semantics: 卡池为空（count 之和必须 > 0）");
  if (p.turnLimit <= 0) errs.push(`semantics: turnLimit 必须 > 0（实为 ${p.turnLimit}）`);
  if (p.energyMax < 0) errs.push(`semantics: energyMax 不能为负（实为 ${p.energyMax}）`);
  if (p.handSize <= 0) errs.push(`semantics: handSize 必须 > 0（实为 ${p.handSize}）`);
  if (p.handSize > deck) errs.push(`semantics: handSize(${p.handSize}) 超过卡池总数(${deck})`);
  for (let k = 0; k < spec.strategy.length; k += 1) {
    const cmd = spec.strategy[k];
    if (cmd === "e") continue;
    const m = /^p(\d+)$/.exec(cmd);
    if (m === null) {
      errs.push(`semantics: strategy[${k}] 非法动作 ${cmd}`);
      continue;
    }
    const idx = Number(m[1]);
    if (idx < 0 || idx >= p.handSize) {
      errs.push(`semantics: strategy[${k}] 索引越界 p${idx}（handSize=${p.handSize}）`);
    }
  }
  return errs;
}

/** 合并校验：先模式后语义；结构不合法时语义无意义，直接返回结构错误。 */
export function validateSpec(spec: Record<string, unknown>): string[] {
  const schema = validateSchema(spec);
  if (schema.length > 0) return schema;
  return validateSemantics(spec as unknown as Spec);
}

// file: core/test/gd_mech_02_validate.test.ts
// tier: P
// verify: node --test 'core/test/gd_mech_02_validate.test.ts'
//
// 2.2 的两级校验测试：合法规格 0 错；6 个负例（缺字段 / 类型错 / strategy 索引越界 /
// turnLimit 为 0 / energyMax 为负 / cards 空数组）每个都必须被判为不合法。
// 判据全整数，与 core/src/ashdeck/validate.ts 同源。

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 { validateSchema, validateSemantics, validateSpec } from "../src/ashdeck/validate.ts";
import type { Spec } from "../src/ashdeck/types.ts";

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

function clone(): Record<string, unknown> {
  return JSON.parse(RAW);
}

function paramsOf(spec: Record<string, unknown>): Record<string, number> {
  return spec.params as Record<string, number>;
}

test("合法规格：模式校验 0 错、语义校验 0 错、合并 0 错", () => {
  assert.deepEqual(validateSchema(SPEC as unknown as Record<string, unknown>), []);
  assert.deepEqual(validateSemantics(SPEC), []);
  assert.deepEqual(validateSpec(clone()), []);
});

test("负例 1 · 模式 · 缺字段：删掉 goals 必须被判不合法", () => {
  const bad = clone();
  delete bad.goals;
  const errs = validateSpec(bad);
  assert.ok(errs.length > 0);
  assert.ok(errs.some((e) => e.includes("缺字段 goals")));
});

test("负例 2 · 模式 · 类型错：seed 写成字符串必须被判不合法", () => {
  const bad = clone();
  bad.seed = "20261014";
  const errs = validateSpec(bad);
  assert.ok(errs.length > 0);
  assert.ok(errs.some((e) => e.includes("seed 必须是整数")));
});

test("负例 3 · 语义 · strategy 索引越界 p9 必须被判不合法", () => {
  const bad = clone();
  bad.strategy = ["p0", "p9"];
  assert.deepEqual(validateSchema(bad), []); // 结构本身没问题
  const errs = validateSemantics(bad as unknown as Spec);
  assert.ok(errs.some((e) => e.includes("索引越界 p9")));
});

test("负例 4 · 语义 · turnLimit 为 0 必须被判不合法", () => {
  const bad = clone();
  paramsOf(bad).turnLimit = 0;
  assert.deepEqual(validateSchema(bad), []);
  const errs = validateSemantics(bad as unknown as Spec);
  assert.ok(errs.some((e) => e.includes("turnLimit 必须 > 0")));
});

test("负例 5 · 语义 · energyMax 为负必须被判不合法", () => {
  const bad = clone();
  paramsOf(bad).energyMax = -1;
  assert.ok(validateSpec(bad).some((e) => e.includes("energyMax 不能为负")));
});

test("负例 6 · 模式 · cards 为空数组必须被判不合法", () => {
  const bad = clone();
  bad.cards = [];
  assert.ok(validateSpec(bad).some((e) => e.includes("cards 不能为空数组")));
});

✔ 合法规格：模式校验 0 错、语义校验 0 错、合并 0 错 (1.169959ms)
✔ 负例 1 · 模式 · 缺字段：删掉 goals 必须被判不合法 (0.149792ms)
✔ 负例 2 · 模式 · 类型错：seed 写成字符串必须被判不合法 (0.164625ms)
✔ 负例 3 · 语义 · strategy 索引越界 p9 必须被判不合法 (0.1025ms)
✔ 负例 4 · 语义 · turnLimit 为 0 必须被判不合法 (0.102709ms)
✔ 负例 5 · 语义 · energyMax 为负必须被判不合法 (0.092ms)
✔ 负例 6 · 模式 · cards 为空数组必须被判不合法 (0.075834ms)
ℹ tests 7
ℹ pass 7
ℹ fail 0