@lingfan-engine/editor 0.0.0-stage → 0.1.0

package/src/diagnostics/message.ts

@@ -0,0 +1,60 @@
+/**
+ * 诊断文案 · **主句 / 说明分层**（纯函数，可测）。
+ *
+ * 存在理由：诊断 `message` 把「状态」和「怎么处置」塞进同一句——
+ * 例：`未使用的译文键：第三章 · 相遇（say / menu / input / notify 四个翻译面均未命中原文——该键运行期不会生效；若这段文字只用于元素文本或宿主界面，本条可忽略）`。
+ * 括号里那段**明说「可忽略」**却占主句大半篇幅 ⇒ 窄栏里每条竖排多行，
+ * **扫读成本极高**。
+ *
+ * 分层后：主句只说状态（进列表、可扫读），说明进 `title`/次要行（按需展开）。
+ *
+ * **不改 `Diagnostic.message` 的既有形状**（契约字段、诊断码、pointer 都不动）——
+ * 拆的是**渲染分层**：`detailOf(diagnostic)` 从 message 里切出「主句 / 说明」，
+ * 这样**既有测试与消费方全部不受影响**（不制造第二份文案事实源）。
+ */
+
+/** 主句 / 说明两段文案 */
+export interface DiagnosticMessageParts {
+  /** 主句：状态本身（列表里显示的就是它） */
+  readonly brief: string;
+  /** 说明：怎么处置 / 为什么（默认收起，悬停或展开可见）；无说明时为空串 */
+  readonly detail: string;
+}
+
+/**
+ * 从 `message` 切出主句与说明。
+ *
+ * 判据：**首个全角括号及其后内容**算说明（现有 4 条诊断的说明都在括号里，
+ * 且括号内不含右括号以外的结构）。没括号 ⇒ 整句是主句、无说明。
+ *
+ * **不切 `pointer`**：pointer 是另一个字段，不参与文案分层。
+ */
+export function splitDiagnosticMessage(
+  message: string,
+): DiagnosticMessageParts {
+  const start = message.indexOf("（");
+  if (start <= 0) return { brief: message, detail: "" };
+  // 说明本身若含「（…）」嵌套，只取到**配对**的右括号
+  let depth = 0;
+  let end = -1;
+  for (let i = start; i < message.length; i += 1) {
+    if (message[i] === "（") depth += 1;
+    else if (message[i] === "）") {
+      depth -= 1;
+      if (depth === 0) {
+        end = i;
+        break;
+      }
+    }
+  }
+  if (end < 0) return { brief: message, detail: "" };
+  return {
+    brief: message.slice(0, start).trimEnd(),
+    detail: message.slice(start + 1, end).trim(),
+  };
+}
+
+/** 列表里显示的主句（便捷出口） */
+export function diagnosticBrief(message: string): string {
+  return splitDiagnosticMessage(message).brief;
+}

package/src/diagnostics/refs.ts

@@ -0,0 +1,123 @@
+/**
+ * 表达式引用抽取（纯函数，零依赖）：
+ * 从故事文本 / 字段值里剥出会被求值的表达式源，并抽出其中的变量键引用。
+ * 供符号索引（./symbols）按字段形态调用；extractExpressionRefs 经
+ * ../diagnostics/index.ts 对外转发。
+ */
+
+/** 行内富文本标记（镜像 packages/core/src/runtime/expr/interpolate.ts；行为互锁见 tests/editor/schema.test.ts） */
+const INLINE_SHORT_TAGS = new Set([
+  "b",
+  "/b",
+  "i",
+  "/i",
+  "u",
+  "/u",
+  "w",
+  "fast",
+  "p",
+  "color",
+  "font",
+  "size",
+]);
+const INLINE_PREFIXED_TAGS = [
+  "color=",
+  "/color",
+  "font=",
+  "/font",
+  "size=",
+  "/size",
+];
+
+function isInlineTag(content: string): boolean {
+  if (INLINE_SHORT_TAGS.has(content)) return true;
+  return INLINE_PREFIXED_TAGS.some((prefix) => content.startsWith(prefix));
+}
+
+/** 表达式内置名与字面量（与引擎 runtime/expr/builtins.ts 全集互锁：新增内建须同步） */
+const EXPR_BUILTINS = new Set([
+  "random",
+  "min",
+  "max",
+  "abs",
+  "clamp",
+  "arrayGet",
+  "dictGet",
+  "optGet",
+  "len",
+  "true",
+  "false",
+]);
+const IDENT_PATH_RE =
+  /[A-Za-z_\u4e00-\u9fa5][A-Za-z0-9_\u4e00-\u9fa5]*(?:\.[A-Za-z_][A-Za-z0-9_\u4e00-\u9fa5]*)*/g;
+
+/** 表达式中的变量键引用（点路径整键 = 全局键路径/字典下钻；跳过字符串字面量/数字尾巴/内置名） */
+export function extractExpressionRefs(expr: string): string[] {
+  let stripped = "";
+  for (let i = 0; i < expr.length; i += 1) {
+    const ch = expr[i];
+    if (ch === '"') {
+      i += 1;
+      while (i < expr.length) {
+        if (expr[i] === "\\") {
+          i += 2;
+          continue;
+        }
+        if (expr[i] === '"') break;
+        i += 1;
+      }
+      continue;
+    }
+    stripped += ch;
+  }
+  const refs: string[] = [];
+  for (const match of stripped.matchAll(IDENT_PATH_RE)) {
+    const name = match[0];
+    const prev = stripped.slice(0, match.index ?? 0).trimEnd();
+    if (/\d$/.test(prev)) continue;
+    if (EXPR_BUILTINS.has(name)) continue;
+    if (!refs.includes(name)) refs.push(name);
+  }
+  return refs;
+}
+
+/** 引号字符串字面量剔除后的 {…} 段求值源提取（插值面：先判行内标记，再剥格式后缀） */
+export function exprSourcesInText(text: string): string[] {
+  const sources: string[] = [];
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] !== "{") {
+      i += 1;
+      continue;
+    }
+    const end = text.indexOf("}", i);
+    if (end < 0) break;
+    const content = text.slice(i + 1, end).trim();
+    if (!isInlineTag(content)) {
+      let exprSrc = content;
+      if (!content.includes("?")) {
+        const colon = content.indexOf(":");
+        if (colon > 0) exprSrc = content.slice(0, colon).trim();
+      }
+      sources.push(exprSrc);
+    }
+    i = end + 1;
+  }
+  return sources;
+}
+
+/** 表达式面源提取（cond/on/in：{…} 包装剥壳，与执行器 evalCond 同构） */
+export function exprSourceInExpressionField(raw: string): string {
+  const t = raw.trim();
+  return t.startsWith("{") && t.endsWith("}") ? t.slice(1, -1) : t;
+}
+
+const COMPOUND_PREFIX = /^\s*(\+=|-=|\*=|\/=|%=)\s*([\s\S]+)$/;
+
+/** value 字段源提取（{expr} 包装或复合赋值右部；其余 = 字面量无引用），与执行器 evalValue/execAssign 同构 */
+export function exprSourceInValueField(raw: string): string | null {
+  const compound = COMPOUND_PREFIX.exec(raw);
+  if (compound !== null) return compound[2];
+  const t = raw.trim();
+  return t.startsWith("{") && t.endsWith("}") ? t.slice(1, -1) : null;
+}

package/src/diagnostics/symbols.ts

@@ -0,0 +1,221 @@
+/**
+ * 符号索引：把故事里的定义键 / 列 / 函数 / 跳转目标 / 变量引用与可翻译原文
+ * 收进一张 SymbolIndex（单次遍历）。消费方是分析器（./analyze）与编辑器功能。
+ */
+import type { Story } from "@lingfan-engine/core";
+import type { FieldDescriptor, SymbolIndex } from "../contracts/index.ts";
+import { joinPointer } from "../contracts/index.ts";
+import { TRANSLATE_SURFACES, valuesAtPath } from "../i18n/index.ts";
+import { walkStoryCommands, walkStoryElements } from "../schema/index.ts";
+import { isPlainObject } from "../shared/index.ts";
+import {
+  extractExpressionRefs,
+  exprSourceInExpressionField,
+  exprSourceInValueField,
+  exprSourcesInText,
+} from "./refs.ts";
+
+/** 变量定义字段（op → 相对字段路径）；键 = 符号索引 definedKeys 的来源 */
+const VAR_DEF_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  set: ["key"],
+  define: ["key"],
+  let: ["key"],
+  local: ["key"],
+  array: ["key"],
+  dict: ["key"],
+  random: ["var"],
+  for: ["var"],
+  foreach: ["var"],
+  input: ["store"],
+};
+
+/** 跳转目标字段（op → [字段路径, 目标种类]） */
+const TARGET_FIELDS: Readonly<
+  Record<
+    string,
+    readonly (readonly [string, "column" | "function" | "callable"])[]
+  >
+> = {
+  jump: [["target", "column"]],
+  // `call` 的目标**可以是列（label）或 func**（「调用子过程（func 或 label）」）
+  // ⇒ `callable` = 任一存在即可。
+  call: [["target", "callable"]],
+  menu: [["options[].target", "column"]],
+};
+
+// 可翻译原文面与路径取值 = i18n 工具链模块的单一事实源：
+// 诊断的 originals 收集与 extractStoryKeys 消费同一张表（互锁: i18n-key-extract-parity）
+
+/** 符号索引：一次遍历收集全部符号与引用（畸形输入 fail-closed 返回空索引） */
+export function indexStory(story: Story): SymbolIndex {
+  const index: SymbolIndex = {
+    columnPointers: new Map(),
+    duplicateColumns: [],
+    entry: story?.entry,
+    definedKeys: new Map(),
+    functions: new Map(),
+    targets: [],
+    resources: [],
+    variableRefs: [],
+    originals: new Set(),
+  };
+  if (story === null || typeof story !== "object") return index;
+  if (Array.isArray(story.columns)) {
+    story.columns.forEach((column, columnIndex) => {
+      if (!isPlainObject(column) || typeof column.id !== "string") return;
+      const columnPointer = joinPointer("columns", columnIndex);
+      if (index.columnPointers.has(column.id)) {
+        index.duplicateColumns.push({ id: column.id, pointer: columnPointer });
+      } else {
+        index.columnPointers.set(column.id, columnPointer);
+      }
+    });
+  }
+  for (const key of Object.keys(story.defines ?? {})) {
+    if (!index.definedKeys.has(key)) {
+      index.definedKeys.set(key, joinPointer("defines", key));
+    }
+  }
+  walkStoryCommands(story, (cmd, pointer, fields) => {
+    if (!isPlainObject(cmd) || typeof cmd.op !== "string") return;
+    const op = cmd.op;
+    if (op === "func" && typeof cmd.name === "string") {
+      if (!index.functions.has(cmd.name)) {
+        index.functions.set(cmd.name, {
+          params: Array.isArray(cmd.params)
+            ? cmd.params.filter((p): p is string => typeof p === "string")
+            : [],
+          pointer,
+        });
+      }
+    }
+    if (op === "navigate") {
+      const scene =
+        typeof cmd.scene === "string" && cmd.scene !== "" ? cmd.scene : null;
+      const target = scene ?? (typeof cmd.path === "string" ? cmd.path : "");
+      if (target !== "") {
+        index.targets.push({ pointer, target, kind: "column" });
+      }
+    }
+    for (const [path, targetKind] of TARGET_FIELDS[op] ?? []) {
+      for (const { value, pointer: fieldPointer } of valuesAtPath(cmd, path)) {
+        if (typeof value === "string" && value !== "") {
+          index.targets.push({
+            pointer: `${pointer}${fieldPointer}`,
+            target: value,
+            kind: targetKind,
+          });
+        }
+      }
+    }
+    for (const path of VAR_DEF_FIELDS[op] ?? []) {
+      for (const { value, pointer: fieldPointer } of valuesAtPath(cmd, path)) {
+        if (
+          typeof value === "string" &&
+          value !== "" &&
+          !index.definedKeys.has(value)
+        ) {
+          index.definedKeys.set(value, `${pointer}${fieldPointer}`);
+        }
+      }
+    }
+    for (const path of TRANSLATE_SURFACES[op] ?? []) {
+      for (const { value } of valuesAtPath(cmd, path)) {
+        if (typeof value === "string" && value !== "")
+          index.originals.add(value);
+      }
+    }
+    scanFields(cmd, pointer, fields ?? [], index);
+  });
+  // 翻译面：元素展示文字（`text`，运行期装载时 Translate）也计入原文集合
+  walkStoryElements(story, (node) => {
+    if (!isPlainObject(node)) return;
+    const text = node.text;
+    if (typeof text === "string" && text !== "") index.originals.add(text);
+  });
+  return index;
+}
+
+function scanFields(
+  cmd: Record<string, unknown>,
+  pointer: string,
+  fields: readonly FieldDescriptor[],
+  index: SymbolIndex,
+): void {
+  for (const field of fields) {
+    const value = cmd[field.key];
+    const fieldPointer = `${pointer}/${field.key}`;
+    switch (field.kind) {
+      case "expression":
+        if (typeof value === "string" && value !== "") {
+          for (const name of extractExpressionRefs(
+            exprSourceInExpressionField(value),
+          )) {
+            index.variableRefs.push({
+              pointer: fieldPointer,
+              name,
+              kind: "expression",
+            });
+          }
+        }
+        break;
+      case "value":
+        if (typeof value === "string" && value !== "") {
+          const source = exprSourceInValueField(value);
+          if (source !== null) {
+            for (const name of extractExpressionRefs(source)) {
+              index.variableRefs.push({
+                pointer: fieldPointer,
+                name,
+                kind: "expression",
+              });
+            }
+          }
+        }
+        break;
+      case "text":
+        if (typeof value === "string" && value !== "") {
+          for (const source of exprSourcesInText(value)) {
+            for (const name of extractExpressionRefs(source)) {
+              index.variableRefs.push({
+                pointer: fieldPointer,
+                name,
+                kind: "interpolation",
+              });
+            }
+          }
+        }
+        break;
+      case "resource":
+        if (typeof value === "string" && value !== "") {
+          index.resources.push({ pointer: fieldPointer, path: value });
+        }
+        break;
+      case "array":
+      case "body":
+      case "object":
+        if (isPlainObject(value)) {
+          scanFields(
+            value as Record<string, unknown>,
+            fieldPointer,
+            field.properties ?? [],
+            index,
+          );
+        } else if (Array.isArray(value) && field.item !== undefined) {
+          value.forEach((element, itemIndex) => {
+            if (isPlainObject(element)) {
+              scanFields(
+                element as Record<string, unknown>,
+                `${fieldPointer}/${itemIndex}`,
+                field.item!.properties ?? [],
+                index,
+              );
+            }
+          });
+        }
+        break;
+      default:
+        break;
+    }
+  }
+}