12.3 文本的一致性校验

{
  "namespace": "ne_12_3",
  "checks": [
    { "id": "missing", "name": "漏键", "criterion": "规格引用但表缺 -> FAIL", "expected": 0 },
    { "id": "dangling", "name": "悬空键", "criterion": "表有但规格无引用 -> 报告", "expected": 0 },
    { "id": "variant", "name": "变体覆盖", "criterion": "带条件节点缺 line_else -> 报告（不 FAIL）", "expected": 1 },
    { "id": "placeholder", "name": "占位符一致性", "criterion": "文本占位符名对不上声明变量 -> FAIL", "expected": 0 }
  ],
  "declared_vars": { "aff": 4, "flag": 18, "item": 9, "total": 31 },
  "boundary": "只做文本的结构一致性；译文质量 / 字体字形覆盖 / 配音成本需真实业务环境，命令行不可复现。"
}

// file: core/src/inkwell/ne_12_3_text_consistency.ts
// tier: P
// verify: node --test 'core/test/ne_12_3_*.test.ts'
// 卷二 12.3 文本的一致性校验：四类残差——漏键 / 悬空键 / 变体覆盖 / 占位符一致性。
// 前两类复用 12.1 的抽键与检测；变体覆盖复用 12.2 的矩阵；占位符只做「名字对得上」。
// 只做文本的**结构一致性**：不评价译文质量，也不做文本层面的摘要。

import { extractTextKeys, buildTable, rendererRefs, checkKeys } from "./ne_12_1_text_table.ts";
import { variantMatrix } from "./ne_12_2_variant_plural.ts";

type Spec = { dialogue: unknown[]; state: { vars: string[]; flags: string[]; items: string[] } };
const PLACEHOLDER = /\{([^{}]*)\}/g;

/** 规格声明的变量名全集（含命名空间写法）。 */
export function declaredVars(spec: Spec): Set<string> {
  const s = new Set<string>();
  for (const v of spec.state.vars) {
    s.add(v);
    s.add(`aff.${v}`);
  }
  for (const f of spec.state.flags) {
    s.add(f);
    s.add(`flag.${f}`);
  }
  for (const i of spec.state.items) {
    s.add(i);
    s.add(`item.${i}`);
  }
  return s;
}

/** 扫描文本里的行内占位符，返回命中 / 未解析 / 声明未用。 */
export function scanPlaceholders(texts: string[], declared: Set<string>) {
  const used = new Set<string>();
  const unresolved = new Set<string>();
  for (const t of texts) {
    for (const m of t.matchAll(PLACEHOLDER)) {
      const name = m[1].trim();
      used.add(name);
      if (!declared.has(name)) unresolved.add(name);
    }
  }
  const unused = [...declared].filter((d) => !used.has(d));
  return { used: [...used].sort(), unresolved: [...unresolved].sort(), unused_declared: unused.length };
}

/** 四类残差一次算齐。 */
export function consistencyReport(spec: Spec) {
  const table = buildTable(spec as never);
  const { missing, dangling } = checkKeys(table, rendererRefs(spec as never));
  const variants = variantMatrix(spec as never);
  const under = variants.filter((r) => r.status === "under_declared");
  const ph = scanPlaceholders(Object.values(table), declaredVars(spec));
  return {
    missing_keys: missing,
    dangling_keys: dangling,
    variant_under_declared: under.map((r) => r.id),
    placeholders: ph,
    residual: {
      missing: missing.length,
      dangling: dangling.length,
      variant: under.length,
      placeholder: ph.unresolved.length,
    },
  };
}

export { extractTextKeys };

// file: core/test/ne_12_3_text_consistency.test.ts
// tier: P
// verify: node --test 'core/test/ne_12_3_*.test.ts'
// 卷二 12.3：四类残差一次算齐，并给出占位符的负例。
import test from "node:test";
import assert from "node:assert/strict";
import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { consistencyReport, declaredVars, scanPlaceholders } from "../src/inkwell/ne_12_3_text_consistency.ts";

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, "..", "..");
const spec = JSON.parse(readFileSync(join(ROOT, "config/story_spec.json"), "utf8"));

test("四类残差：漏键 0 / 悬空键 0 / 变体欠声明 1 / 占位符 0", () => {
  const r = consistencyReport(spec);
  assert.deepEqual(r.missing_keys, []);
  assert.deepEqual(r.dangling_keys, []);
  assert.deepEqual(r.variant_under_declared, ["d_lt_2"]);
  assert.deepEqual(r.placeholders.used, []);
  assert.deepEqual(r.placeholders.unresolved, []);
  assert.equal(r.residual.missing, 0);
  assert.equal(r.residual.dangling, 0);
  assert.equal(r.residual.variant, 1);
  assert.equal(r.residual.placeholder, 0);
  console.log(`残差：漏键 ${r.residual.missing} / 悬空键 ${r.residual.dangling} / 变体欠声明 ${r.residual.variant} ${JSON.stringify(r.variant_under_declared)} / 占位符 ${r.residual.placeholder}`);
});

test("声明变量 31 个，文本里一个占位符都没用", () => {
  const declared = declaredVars(spec);
  assert.equal(declared.size, spec.state.vars.length * 2 + spec.state.flags.length * 2 + spec.state.items.length * 2);
  const r = scanPlaceholders(["你持有 3 件线索。"], declared);
  assert.deepEqual(r.used, []);
  console.log(`声明变量 ${declared.size} 个（含命名空间写法），文本占位符命中 ${r.used.length} 处`);
});

test("负例 · 占位符：声明过的名字解析，没声明的报未解析", () => {
  const declared = declaredVars(spec);
  const ok = scanPlaceholders(["好感度 {aff.yan} 现在是多少"], declared);
  assert.deepEqual(ok.used, ["aff.yan"]);
  assert.deepEqual(ok.unresolved, []);
  const bad = scanPlaceholders(["你持有 {aff.__nope__} 件线索"], declared);
  assert.deepEqual(bad.unresolved, ["aff.__nope__"]);
  console.log(`负例·占位符：命中 ${JSON.stringify(ok.used)}；未解析 ${JSON.stringify(bad.unresolved)}`);
});

test("落盘：一致性报告写 out/", () => {
  const r = consistencyReport(spec);
  mkdirSync(join(ROOT, "out"), { recursive: true });
  writeFileSync(join(ROOT, "out/ne_12_3_consistency.json"), JSON.stringify(r, null, 2) + "\n");
  console.log(`落盘：residual = ${JSON.stringify(r.residual)}`);
});

残差：漏键 0 / 悬空键 0 / 变体欠声明 1 ["d_lt_2"] / 占位符 0
声明变量 62 个（含命名空间写法），文本占位符命中 0 处
负例·占位符：命中 ["aff.yan"]；未解析 ["aff.__nope__"]
落盘：residual = {"missing":0,"dangling":0,"variant":1,"placeholder":0}
✔ 四类残差：漏键 0 / 悬空键 0 / 变体欠声明 1 / 占位符 0 (2.981958ms)
✔ 声明变量 31 个，文本里一个占位符都没用 (0.195583ms)
✔ 负例 · 占位符：声明过的名字解析，没声明的报未解析 (0.149875ms)
✔ 落盘：一致性报告写 out/ (3.747792ms)
ℹ tests 4
ℹ suites 0
ℹ pass 4
ℹ fail 0
ℹ duration_ms 523.682584