《移动游戏产品的架构·网络、资源与热更新》2.3 协议契约测试：把兼容规则写成断言

// file: src/net/contract-check.ts
// tier: L1
// verify: node --test test/net/contract-check.test.ts

export type FieldType = "int" | "float" | "string" | "bool" | "int-array";

export interface FieldSpec {
  readonly name: string;
  readonly type: FieldType;
  readonly required: boolean;
  readonly min?: number;
  readonly max?: number;
  readonly maxLength?: number;
}

export interface MessageSchema {
  readonly name: string;
  readonly version: number;
  readonly fields: readonly FieldSpec[];
}

export interface CorpusSample {
  readonly schema: string;
  readonly value: Readonly<Record<string, unknown>>;
}

export type IssueCode =
  | "missing-field"
  | "type-mismatch"
  | "out-of-range"
  | "too-long"
  | "unknown-field"
  | "unknown-schema"
  | "removed-required"
  | "required-added"
  | "type-changed"
  | "schema-name";

export interface ContractIssue {
  readonly schema: string;
  readonly path: string;
  readonly code: IssueCode;
  readonly detail: string;
}

export interface ContractReport {
  readonly samples: number;
  readonly passed: number;
  readonly failed: number;
  readonly warnings: number;
  readonly issues: readonly ContractIssue[];
}

export const TIDE_MOVE_SCHEMA: MessageSchema = {
  name: "tide.move.submit",
  version: 3,
  fields: [
    { name: "matchId", type: "string", required: true, maxLength: 36 },
    { name: "turn", type: "int", required: true, min: 1 },
    { name: "moves", type: "int-array", required: true },
    { name: "clientSeq", type: "int", required: true, min: 0 },
    { name: "skinId", type: "string", required: false, maxLength: 32 },
  ],
};

export const ARK_INPUT_SCHEMA: MessageSchema = {
  name: "ark.battle.input",
  version: 5,
  fields: [
    { name: "seq", type: "int", required: true, min: 0 },
    { name: "tick", type: "int", required: true, min: 0 },
    { name: "moveX", type: "float", required: true, min: -1, max: 1 },
    { name: "moveY", type: "float", required: true, min: -1, max: 1 },
    { name: "buttons", type: "int", required: true, min: 0, max: 65535 },
    { name: "skillHint", type: "string", required: false, maxLength: 16 },
  ],
};

function typeMatches(type: FieldType, value: unknown): boolean {
  switch (type) {
    case "int":
      return typeof value === "number" && Number.isInteger(value);
    case "float":
      return typeof value === "number" && Number.isFinite(value);
    case "string":
      return typeof value === "string";
    case "bool":
      return typeof value === "boolean";
    case "int-array":
      return Array.isArray(value) && value.every((item) => Number.isInteger(item));
    default:
      return false;
  }
}

export function validateSample(
  schema: MessageSchema,
  sample: Readonly<Record<string, unknown>>,
): readonly ContractIssue[] {
  const issues: ContractIssue[] = [];
  const known = new Set(schema.fields.map((field) => field.name));

  for (const field of schema.fields) {
    const value = sample[field.name];
    if (value === undefined) {
      if (field.required) {
        issues.push({
          schema: schema.name,
          path: field.name,
          code: "missing-field",
          detail: `${field.name} is required`,
        });
      }
      continue;
    }
    if (!typeMatches(field.type, value)) {
      issues.push({
        schema: schema.name,
        path: field.name,
        code: "type-mismatch",
        detail: `${field.name} expects ${field.type}, got ${typeof value}`,
      });
      continue;
    }
    if (typeof value === "number") {
      if (field.min !== undefined && value < field.min) {
        issues.push({
          schema: schema.name,
          path: field.name,
          code: "out-of-range",
          detail: `${field.name}=${value} < min ${field.min}`,
        });
      }
      if (field.max !== undefined && value > field.max) {
        issues.push({
          schema: schema.name,
          path: field.name,
          code: "out-of-range",
          detail: `${field.name}=${value} > max ${field.max}`,
        });
      }
    }
    if (typeof value === "string" && field.maxLength !== undefined && value.length > field.maxLength) {
      issues.push({
        schema: schema.name,
        path: field.name,
        code: "too-long",
        detail: `${field.name} length ${value.length} > ${field.maxLength}`,
      });
    }
  }

  for (const key of Object.keys(sample)) {
    if (!known.has(key)) {
      issues.push({
        schema: schema.name,
        path: key,
        code: "unknown-field",
        detail: `${key} is not declared in ${schema.name} v${schema.version}`,
      });
    }
  }
  return issues;
}

export function checkCorpus(
  schemas: readonly MessageSchema[],
  samples: readonly CorpusSample[],
): ContractReport {
  const byName = new Map(schemas.map((schema) => [schema.name, schema]));
  const issues: ContractIssue[] = [];
  let passed = 0;
  let failed = 0;
  let warnings = 0;

  for (const sample of samples) {
    const schema = byName.get(sample.schema);
    if (schema === undefined) {
      issues.push({
        schema: sample.schema,
        path: "",
        code: "unknown-schema",
        detail: `no schema registered for ${sample.schema}`,
      });
      failed += 1;
      continue;
    }
    const sampleIssues = validateSample(schema, sample.value);
    issues.push(...sampleIssues);
    const errors = sampleIssues.filter((issue) => issue.code !== "unknown-field");
    warnings += sampleIssues.length - errors.length;
    if (errors.length > 0) {
      failed += 1;
    } else {
      passed += 1;
    }
  }

  return {
    samples: samples.length,
    passed,
    failed,
    warnings,
    issues,
  };
}

export function diffSchema(base: MessageSchema, next: MessageSchema): readonly ContractIssue[] {
  const issues: ContractIssue[] = [];
  if (base.name !== next.name) {
    issues.push({
      schema: next.name,
      path: "",
      code: "schema-name",
      detail: `${next.name} != ${base.name}`,
    });
    return issues;
  }
  const nextFields = new Map(next.fields.map((field) => [field.name, field]));
  const baseFields = new Map(base.fields.map((field) => [field.name, field]));

  for (const field of base.fields) {
    const candidate = nextFields.get(field.name);
    if (candidate === undefined) {
      if (field.required) {
        issues.push({
          schema: base.name,
          path: field.name,
          code: "removed-required",
          detail: `${field.name} was required and disappeared`,
        });
      }
      continue;
    }
    if (candidate.type !== field.type) {
      issues.push({
        schema: base.name,
        path: field.name,
        code: "type-changed",
        detail: `${field.name} ${field.type} -> ${candidate.type}`,
      });
    }
    if (!field.required && candidate.required) {
      issues.push({
        schema: base.name,
        path: field.name,
        code: "required-added",
        detail: `${field.name} became required`,
      });
    }
  }

  for (const field of next.fields) {
    if (!baseFields.has(field.name) && field.required) {
      issues.push({
        schema: base.name,
        path: field.name,
        code: "required-added",
        detail: `${field.name} is new and required`,
      });
    }
  }
  return issues;
}

export function describeReport(report: ContractReport): string {
  return `contract samples=${report.samples} passed=${report.passed} failed=${report.failed} warnings=${report.warnings}`;
}