@lingfan-engine/editor 0.1.0 → 0.1.3

package/src/diagnostics/analyze.ts

@@ -1,161 +1,161 @@
-/**
- * 分析入口：先取符号索引（./symbols），再叠加结构校验与逐条语义诊断。
- * 行为契约（诊断族与缺省跳过口径）见 analyzeStory 的函数注释。
- */
-import type { Story } from "@lingfan-engine/core";
-import { ELEMENT_OPS_BLOCKED } from "@lingfan-engine/core";
-import type { AnalyzeOptions, Diagnostic, EditorTexts } from "../contracts/index.ts";
-import { escapePointerToken, resolveEditorTexts } from "../contracts/index.ts";
-import { UNIMPLEMENTED_ELEMENT_ATTRS } from "../schema/index.ts";
-import { walkStoryElements } from "../schema/index.ts";
-import { validateStory } from "../schema/index.ts";
-import { isPlainObject } from "../shared/index.ts";
-import { indexStory } from "./symbols.ts";
-
-/**
- * 编辑期诊断集（结构校验 + 语义诊断，一律带 JSON Pointer）。
- * resourceFiles / overlayKeys 缺省时对应诊断族跳过（供给侧数据未接入不误报）。
- * `texts`（可选）= 集中文案表注入（缺省 defaultEditorTexts）。
- */
-export function analyzeStory(
-  story: Story,
-  options: AnalyzeOptions = {},
-): Diagnostic[] {
-  const texts: EditorTexts = resolveEditorTexts(options.texts);
-  const out: Diagnostic[] = validateStory(story);
-  const index = indexStory(story);
-
-  for (const duplicate of index.duplicateColumns) {
-    out.push({
-      code: "duplicate-column",
-      severity: "error",
-      message: texts.duplicateColumn(duplicate.id),
-      pointer: duplicate.pointer,
-    });
-  }
-  if (
-    typeof index.entry === "string" &&
-    index.entry !== "" &&
-    !index.columnPointers.has(index.entry)
-  ) {
-    out.push({
-      code: "missing-entry",
-      severity: "error",
-      message: texts.missingEntryColumn(index.entry),
-      pointer: "/entry",
-    });
-  }
-  for (const target of index.targets) {
-    const found =
-      target.kind === "column"
-        ? index.columnPointers.has(target.target)
-        : target.kind === "function"
-          ? index.functions.has(target.target)
-          : // callable：列或 func **任一存在**即通过
-            index.columnPointers.has(target.target) ||
-            index.functions.has(target.target);
-    if (!found) {
-      out.push({
-        // `"function"` 分支当前**无字段产出**（`call` 用的是 `callable`）——
-        // 保留它是**契约完备性**（`TargetKind` 有三种，判定要覆盖三种），
-        // 将来若出现「只允许 func」的新字段即可直接复用（当前无产出路径，非冗余代码）。
-        code:
-          target.kind === "function" ? "unknown-function" : "missing-target",
-        severity: "error",
-        message:
-          target.kind === "column"
-            ? texts.missingJumpTargetColumn(target.target)
-            : target.kind === "function"
-              ? texts.unknownFunction(target.target)
-              : texts.missingCallTarget(target.target),
-        pointer: target.pointer,
-      });
-    }
-  }
-  for (const ref of index.variableRefs) {
-    if (ref.name.startsWith("_")) continue;
-    if (index.definedKeys.has(ref.name)) continue;
-    out.push({
-      code: "undefined-variable",
-      severity: ref.kind === "expression" ? "error" : "warning",
-      message:
-        ref.kind === "expression"
-          ? texts.undefinedVariableExpression(ref.name)
-          : texts.undefinedVariableInterpolation(ref.name),
-      pointer: ref.pointer,
-    });
-  }
-  if (options.resourceFiles !== undefined) {
-    for (const resource of index.resources) {
-      if (!options.resourceFiles.has(resource.path)) {
-        out.push({
-          code: "missing-resource",
-          // 提醒级：素材"先写引用后补"是正常工作流，
-          // error 会拦保存门禁；运行期缺资源由运行时自己 fail-closed 兜底。
-          severity: "warning",
-          message: texts.missingResource(resource.path),
-          pointer: resource.pointer,
-        });
-      }
-    }
-  }
-  if (options.overlayKeys !== undefined) {
-    for (const key of options.overlayKeys) {
-      if (!index.originals.has(key)) {
-        out.push({
-          code: "unused-translation",
-          severity: "warning",
-          message: texts.unusedTranslationKey(key),
-          pointer: "",
-        });
-      }
-    }
-    // 缺译（正向，与 unused-translation 反向对称）：原文在**全部语言**的 overlay
-    // 里都没有 = 玩家必然看到原文（提醒级，不拦保存）。仅在「工程确实启用了 i18n」
-    // （overlay 非空）时提醒——不启用 i18n 的工程原文直出是常态（"不需要多语言
-    // 就不需要 i18n"），不制造全量噪声。
-    if (options.overlayKeys.size > 0) {
-      for (const original of index.originals) {
-        if (!options.overlayKeys.has(original)) {
-          out.push({
-            code: "missing-translation",
-            severity: "warning",
-            message: texts.missingTranslationOriginal(original),
-            pointer: "",
-          });
-        }
-      }
-    }
-  }
-  // 未实现属性清单：已声明但**当前无渲染语义**的元素属性（写了不生效且静默）→ warning。
-  // 指针精确到该属性；清单与表单下架同源（`UNIMPLEMENTED_ELEMENT_ATTRS`），避免两份事实。
-  walkStoryElements(story, (node, pointer) => {
-    if (!isPlainObject(node)) return; // 非对象由 invalid-element 负责
-    for (const attr of UNIMPLEMENTED_ELEMENT_ATTRS) {
-      if (node[attr] === undefined) continue;
-      out.push({
-        code: "unimplemented-element-attr",
-        severity: "warning",
-        message: texts.unimplementedElementAttr(attr),
-        pointer: `${pointer}/${escapePointerToken(attr)}`,
-      });
-    }
-    // 点击动作序列里的**执行期必拒** op：编辑期即报，别等运行时才发现点不动。
-    // 清单与执行期同源（引擎契约 `ELEMENT_OPS_BLOCKED`）——两处各写一份必然漂移。
-    const ops = node.ops;
-    if (Array.isArray(ops)) {
-      ops.forEach((item, i) => {
-        if (!isPlainObject(item)) return; // 形态问题由 invalid-element 负责
-        const op = item.op;
-        if (typeof op !== "string" || !ELEMENT_OPS_BLOCKED.has(op)) return;
-        out.push({
-          code: "element-ops-blocked-op",
-          severity: "error",
-          message: texts.elementOpsBlockedOp(op),
-          pointer: `${pointer}/ops/${i}`,
-        });
-      });
-    }
-  });
-  return out;
-}
+/**
+ * 分析入口：先取符号索引（./symbols），再叠加结构校验与逐条语义诊断。
+ * 行为契约（诊断族与缺省跳过口径）见 analyzeStory 的函数注释。
+ */
+import type { Story } from "@lingfan-engine/core";
+import { ELEMENT_OPS_BLOCKED } from "@lingfan-engine/core";
+import type { AnalyzeOptions, Diagnostic, EditorTexts } from "../contracts/index.ts";
+import { escapePointerToken, resolveEditorTexts } from "../contracts/index.ts";
+import { UNIMPLEMENTED_ELEMENT_ATTRS } from "../schema/index.ts";
+import { walkStoryElements } from "../schema/index.ts";
+import { validateStory } from "../schema/index.ts";
+import { isPlainObject } from "../shared/index.ts";
+import { indexStory } from "./symbols.ts";
+
+/**
+ * 编辑期诊断集（结构校验 + 语义诊断，一律带 JSON Pointer）。
+ * resourceFiles / overlayKeys 缺省时对应诊断族跳过（供给侧数据未接入不误报）。
+ * `texts`（可选）= 集中文案表注入（缺省 defaultEditorTexts）。
+ */
+export function analyzeStory(
+  story: Story,
+  options: AnalyzeOptions = {},
+): Diagnostic[] {
+  const texts: EditorTexts = resolveEditorTexts(options.texts);
+  const out: Diagnostic[] = validateStory(story);
+  const index = indexStory(story);
+
+  for (const duplicate of index.duplicateColumns) {
+    out.push({
+      code: "duplicate-column",
+      severity: "error",
+      message: texts.duplicateColumn(duplicate.id),
+      pointer: duplicate.pointer,
+    });
+  }
+  if (
+    typeof index.entry === "string" &&
+    index.entry !== "" &&
+    !index.columnPointers.has(index.entry)
+  ) {
+    out.push({
+      code: "missing-entry",
+      severity: "error",
+      message: texts.missingEntryColumn(index.entry),
+      pointer: "/entry",
+    });
+  }
+  for (const target of index.targets) {
+    const found =
+      target.kind === "column"
+        ? index.columnPointers.has(target.target)
+        : target.kind === "function"
+          ? index.functions.has(target.target)
+          : // callable：列或 func **任一存在**即通过
+            index.columnPointers.has(target.target) ||
+            index.functions.has(target.target);
+    if (!found) {
+      out.push({
+        // `"function"` 分支当前**无字段产出**（`call` 用的是 `callable`）——
+        // 保留它是**契约完备性**（`TargetKind` 有三种，判定要覆盖三种），
+        // 将来若出现「只允许 func」的新字段即可直接复用（当前无产出路径，非冗余代码）。
+        code:
+          target.kind === "function" ? "unknown-function" : "missing-target",
+        severity: "error",
+        message:
+          target.kind === "column"
+            ? texts.missingJumpTargetColumn(target.target)
+            : target.kind === "function"
+              ? texts.unknownFunction(target.target)
+              : texts.missingCallTarget(target.target),
+        pointer: target.pointer,
+      });
+    }
+  }
+  for (const ref of index.variableRefs) {
+    if (ref.name.startsWith("_")) continue;
+    if (index.definedKeys.has(ref.name)) continue;
+    out.push({
+      code: "undefined-variable",
+      severity: ref.kind === "expression" ? "error" : "warning",
+      message:
+        ref.kind === "expression"
+          ? texts.undefinedVariableExpression(ref.name)
+          : texts.undefinedVariableInterpolation(ref.name),
+      pointer: ref.pointer,
+    });
+  }
+  if (options.resourceFiles !== undefined) {
+    for (const resource of index.resources) {
+      if (!options.resourceFiles.has(resource.path)) {
+        out.push({
+          code: "missing-resource",
+          // 提醒级：素材"先写引用后补"是正常工作流，
+          // error 会拦保存门禁；运行期缺资源由运行时自己 fail-closed 兜底。
+          severity: "warning",
+          message: texts.missingResource(resource.path),
+          pointer: resource.pointer,
+        });
+      }
+    }
+  }
+  if (options.overlayKeys !== undefined) {
+    for (const key of options.overlayKeys) {
+      if (!index.originals.has(key)) {
+        out.push({
+          code: "unused-translation",
+          severity: "warning",
+          message: texts.unusedTranslationKey(key),
+          pointer: "",
+        });
+      }
+    }
+    // 缺译（正向，与 unused-translation 反向对称）：原文在**全部语言**的 overlay
+    // 里都没有 = 玩家必然看到原文（提醒级，不拦保存）。仅在「工程确实启用了 i18n」
+    // （overlay 非空）时提醒——不启用 i18n 的工程原文直出是常态（"不需要多语言
+    // 就不需要 i18n"），不制造全量噪声。
+    if (options.overlayKeys.size > 0) {
+      for (const original of index.originals) {
+        if (!options.overlayKeys.has(original)) {
+          out.push({
+            code: "missing-translation",
+            severity: "warning",
+            message: texts.missingTranslationOriginal(original),
+            pointer: "",
+          });
+        }
+      }
+    }
+  }
+  // 未实现属性清单：已声明但**当前无渲染语义**的元素属性（写了不生效且静默）→ warning。
+  // 指针精确到该属性；清单与表单下架同源（`UNIMPLEMENTED_ELEMENT_ATTRS`），避免两份事实。
+  walkStoryElements(story, (node, pointer) => {
+    if (!isPlainObject(node)) return; // 非对象由 invalid-element 负责
+    for (const attr of UNIMPLEMENTED_ELEMENT_ATTRS) {
+      if (node[attr] === undefined) continue;
+      out.push({
+        code: "unimplemented-element-attr",
+        severity: "warning",
+        message: texts.unimplementedElementAttr(attr),
+        pointer: `${pointer}/${escapePointerToken(attr)}`,
+      });
+    }
+    // 点击动作序列里的**执行期必拒** op：编辑期即报，别等运行时才发现点不动。
+    // 清单与执行期同源（引擎契约 `ELEMENT_OPS_BLOCKED`）——两处各写一份必然漂移。
+    const ops = node.ops;
+    if (Array.isArray(ops)) {
+      ops.forEach((item, i) => {
+        if (!isPlainObject(item)) return; // 形态问题由 invalid-element 负责
+        const op = item.op;
+        if (typeof op !== "string" || !ELEMENT_OPS_BLOCKED.has(op)) return;
+        out.push({
+          code: "element-ops-blocked-op",
+          severity: "error",
+          message: texts.elementOpsBlockedOp(op),
+          pointer: `${pointer}/ops/${i}`,
+        });
+      });
+    }
+  });
+  return out;
+}

package/src/i18n/reconcile.ts

@@ -1,71 +1,71 @@
-/**
- * i18n 工具链 · 缺译 / 多译对账。
- *
- * 对账 = 原文键集合与各语言 overlay 键集合的双向差：
- * - **缺译**（正向）= 原文 − 该语言 overlay（按语言分组；运行期「缺译文回退原文」的预警）
- * - **多译**（反向）= overlay 键 − 原文（与诊断 `unused-translation` 同口径：未使用 = 冗余）
- *
- * 纯函数 + 可读报告文本（编辑器面板一节 / CLI stdout 共用）。加密 overlay（`.json.enc`）
- * 走同一解密供给后与明文同口径参与（供给侧职责见 adapters `loadDiagnosticSupply`）。
- */
-
-import type { EditorTexts } from "../contracts/index.ts";
-import { resolveEditorTexts } from "../contracts/index.ts";
-
-export interface TranslationReconcileReport {
-  /** 每语言缺译键（稳定排序；语言无缺译时为空数组——「齐」也是显式状态） */
-  missingByLang: ReadonlyMap<string, readonly string[]>;
-  /** 多译键（跨语言并集口径，稳定排序；= unused-translation 诊断同源） */
-  unused: readonly string[];
-}
-
-/**
- * 三态对账：某语言缺译 / 多译 / 齐。`overlayKeysByLang` 的键 = 语言码
- * （单语言工具传单键对象即可）。
- */
-export function reconcileTranslations(
-  sources: readonly string[],
-  overlayKeysByLang: Readonly<Record<string, readonly string[]>>,
-): TranslationReconcileReport {
-  const sourceSet = new Set(sources);
-  const missingByLang = new Map<string, readonly string[]>();
-  const unused = new Set<string>();
-  for (const [lang, keys] of Object.entries(overlayKeysByLang)) {
-    const keySet = new Set(keys);
-    for (const key of keySet) {
-      if (!sourceSet.has(key)) unused.add(key);
-    }
-    const missing: string[] = [];
-    for (const source of sourceSet) {
-      if (!keySet.has(source)) missing.push(source);
-    }
-    missing.sort();
-    missingByLang.set(lang, missing);
-  }
-  return { missingByLang, unused: [...unused].sort() };
-}
-
-/** 可读报告（编辑器面板一节 / CLI stdout 共用）；逐语言缺译 + 多译两节。
- * `texts`（可选）= 集中文案表注入（缺省 defaultEditorTexts）。 */
-export function formatTranslationReport(
-  report: TranslationReconcileReport,
-  texts: Partial<EditorTexts> = {},
-): string {
-  const t = resolveEditorTexts(texts);
-  const lines: string[] = [];
-  for (const [lang, missing] of [...report.missingByLang.entries()].sort()) {
-    if (missing.length === 0) {
-      lines.push(t.missingZero(lang));
-      continue;
-    }
-    lines.push(t.missingCount(lang, missing.length));
-    for (const key of missing) lines.push(`  - ${key}`);
-  }
-  if (report.unused.length === 0) {
-    lines.push(t.unusedZero());
-  } else {
-    lines.push(t.unusedCount(report.unused.length));
-    for (const key of report.unused) lines.push(`  - ${key}`);
-  }
-  return lines.join("\n");
-}
+/**
+ * i18n 工具链 · 缺译 / 多译对账。
+ *
+ * 对账 = 原文键集合与各语言 overlay 键集合的双向差：
+ * - **缺译**（正向）= 原文 − 该语言 overlay（按语言分组；运行期「缺译文回退原文」的预警）
+ * - **多译**（反向）= overlay 键 − 原文（与诊断 `unused-translation` 同口径：未使用 = 冗余）
+ *
+ * 纯函数 + 可读报告文本（编辑器面板一节 / CLI stdout 共用）。加密 overlay（`.json.enc`）
+ * 走同一解密供给后与明文同口径参与（供给侧职责见 adapters `loadDiagnosticSupply`）。
+ */
+
+import type { EditorTexts } from "../contracts/index.ts";
+import { resolveEditorTexts } from "../contracts/index.ts";
+
+export interface TranslationReconcileReport {
+  /** 每语言缺译键（稳定排序；语言无缺译时为空数组——「齐」也是显式状态） */
+  missingByLang: ReadonlyMap<string, readonly string[]>;
+  /** 多译键（跨语言并集口径，稳定排序；= unused-translation 诊断同源） */
+  unused: readonly string[];
+}
+
+/**
+ * 三态对账：某语言缺译 / 多译 / 齐。`overlayKeysByLang` 的键 = 语言码
+ * （单语言工具传单键对象即可）。
+ */
+export function reconcileTranslations(
+  sources: readonly string[],
+  overlayKeysByLang: Readonly<Record<string, readonly string[]>>,
+): TranslationReconcileReport {
+  const sourceSet = new Set(sources);
+  const missingByLang = new Map<string, readonly string[]>();
+  const unused = new Set<string>();
+  for (const [lang, keys] of Object.entries(overlayKeysByLang)) {
+    const keySet = new Set(keys);
+    for (const key of keySet) {
+      if (!sourceSet.has(key)) unused.add(key);
+    }
+    const missing: string[] = [];
+    for (const source of sourceSet) {
+      if (!keySet.has(source)) missing.push(source);
+    }
+    missing.sort();
+    missingByLang.set(lang, missing);
+  }
+  return { missingByLang, unused: [...unused].sort() };
+}
+
+/** 可读报告（编辑器面板一节 / CLI stdout 共用）；逐语言缺译 + 多译两节。
+ * `texts`（可选）= 集中文案表注入（缺省 defaultEditorTexts）。 */
+export function formatTranslationReport(
+  report: TranslationReconcileReport,
+  texts: Partial<EditorTexts> = {},
+): string {
+  const t = resolveEditorTexts(texts);
+  const lines: string[] = [];
+  for (const [lang, missing] of [...report.missingByLang.entries()].sort()) {
+    if (missing.length === 0) {
+      lines.push(t.missingZero(lang));
+      continue;
+    }
+    lines.push(t.missingCount(lang, missing.length));
+    for (const key of missing) lines.push(`  - ${key}`);
+  }
+  if (report.unused.length === 0) {
+    lines.push(t.unusedZero());
+  } else {
+    lines.push(t.unusedCount(report.unused.length));
+    for (const key of report.unused) lines.push(`  - ${key}`);
+  }
+  return lines.join("\n");
+}