@lingfan-engine/editor 0.0.0-stage → 0.1.2

package/src/contracts/forms.ts

@@ -0,0 +1,69 @@
+/**
+ * 表单契约：属性面板表单描述符，由 op schema（Zod 单一事实源）派生。
+ */
+
+/** op 分组（属性面板/时间线插入菜单的呈现归类） */
+export type OpGroup =
+  | "narrative"
+  | "presentation"
+  | "flow"
+  | "variables"
+  | "save"
+  | "audio"
+  | "video"
+  | "minigame";
+
+/**
+ * 字段呈现语义（驱动诊断扫描面与表单控件选型）：
+ * - text：插值面（先 Translate 后插值 + {var} 求值，行内标记透传）
+ * - expression：表达式面（cond/on/in；失败即停机）
+ * - value：任意值（字符串 {expr}/复合赋值 = 表达式，其余字面量）
+ * - identifier：变量/列/函数/槽位名
+ * - resource：资源逻辑路径（经 ResourcePort 寻址）
+ */
+export type FieldKind =
+  | "string"
+  | "number"
+  | "integer"
+  | "boolean"
+  | "enum"
+  | "text"
+  | "expression"
+  | "value"
+  | "identifier"
+  | "resource"
+  | "array"
+  | "object"
+  | "tuple"
+  /** 命令体（if.then/while.body 等）：子面板递归编辑 */
+  | "body";
+
+export interface FieldDescriptor {
+  /** 本层字段名（嵌套项内的字段相对该项根） */
+  key: string;
+  label: string;
+  kind: FieldKind;
+  required: boolean;
+  hasDefault: boolean;
+  defaultValue?: unknown;
+  /** enum 可选值 */
+  enumValues?: readonly string[];
+  /** array/tuple 的元素描述 */
+  item?: FieldDescriptor;
+  tupleItems?: FieldDescriptor[];
+  /** object 的子字段 */
+  properties?: FieldDescriptor[];
+}
+
+export interface OpMeta {
+  op: string;
+  label: string;
+  group: OpGroup;
+}
+
+export interface OpFormDescriptor {
+  op: string;
+  label: string;
+  group: OpGroup;
+  fields: FieldDescriptor[];
+}

package/src/contracts/index.ts

@@ -0,0 +1,22 @@
+export type {
+  AnalyzeOptions,
+  Diagnostic,
+  DiagnosticSeverity,
+  SymbolIndex,
+} from "./diagnostics.ts";
+export { escapePointerToken, joinPointer } from "../shared/index.ts";
+export type {
+  FieldDescriptor,
+  FieldKind,
+  OpFormDescriptor,
+  OpGroup,
+  OpMeta,
+} from "./forms.ts";
+export type {
+  ContainerField,
+  ContainerInfo,
+  StoryListener,
+  UndoEntry,
+} from "./editing.ts";
+export type { EditorTexts } from "./texts.ts";
+export { defaultEditorTexts, resolveEditorTexts } from "./texts.ts";

package/src/contracts/texts.ts

@@ -0,0 +1,204 @@
+/**
+ * 编辑器集中文案表（contract 层只放类型 + 缺省实现，与 engine 的 contracts/messages.ts 同形）。
+ *
+ * 规则：
+ * - 所有面向用户的中文文案都从这里走；缺省串即编辑器的既有文案（只搬位置，不改文案）。
+ * - 消费方经函数参数可选注入 `texts?: Partial<EditorTexts>`，缺省 `defaultEditorTexts`；
+ *   禁止模块级可变全局或注册表 setter。
+ */
+
+/** 编辑器集中文案表：每个方法对应一条已迁移的用户可见文案（方法名即文案身份）。 */
+export interface EditorTexts {
+  /** diagnostics：columnId 重复（columnId 全局唯一）。 */
+  duplicateColumn(columnId: string): string;
+  /** diagnostics：入口列不存在。 */
+  missingEntryColumn(entry: string): string;
+  /** diagnostics：跳转目标列不存在。 */
+  missingJumpTargetColumn(target: string): string;
+  /** diagnostics：调用未注册的函数。 */
+  unknownFunction(target: string): string;
+  /** diagnostics：调用目标既不是 func 也不是列。 */
+  missingCallTarget(target: string): string;
+  /** diagnostics：表达式里使用未定义变量。 */
+  undefinedVariableExpression(name: string): string;
+  /** diagnostics：插值里使用未定义变量。 */
+  undefinedVariableInterpolation(name: string): string;
+  /** diagnostics：资源路径不存在。 */
+  missingResource(path: string): string;
+  /** diagnostics：未使用的译文键。 */
+  unusedTranslationKey(key: string): string;
+  /** diagnostics：原文未有任何译文。 */
+  missingTranslationOriginal(original: string): string;
+  /** diagnostics：元素属性已声明但无渲染语义。 */
+  unimplementedElementAttr(attr: string): string;
+  /** diagnostics：元素动作序列里不可用的动作。 */
+  elementOpsBlockedOp(op: string): string;
+
+  /** schema/validate：命令带未知负载字段（编辑期 fail-closed）。 */
+  unknownPayloadFields(op: string, keys: string): string;
+  /** schema/validate：必填字段缺失（path 为空时无点段）。 */
+  missingRequired(op: string, path: string): string;
+  /** schema/validate：字段值不合法（localized 是 zod issue 的中文翻译）。 */
+  invalidValue(op: string, path: string, localized: string): string;
+  /** schema/validate：命令必须为对象。 */
+  commandMustBeObject(): string;
+  /** schema/validate：命令必须含非空 op 字符串。 */
+  commandMustHaveOp(): string;
+  /** schema/validate：未知或未实现的命令。 */
+  unknownCommand(op: string): string;
+  /** schema/validate：资源路径不能为空。 */
+  resourcePathEmpty(): string;
+  /** schema/validate：资源路径不能为空（要停止该通道请用 ${stopOp}）。 */
+  resourcePathEmptyStop(stopOp: string): string;
+  /** schema/validate：数值太小。 */
+  valueTooSmall(at: string, min: number): string;
+  /** schema/validate：值太小（无数值上下文）。 */
+  valueTooSmallBare(at: string): string;
+  /** schema/validate：数值太大。 */
+  valueTooBig(at: string, max: number): string;
+  /** schema/validate：值太大（无数值上下文）。 */
+  valueTooBigBare(at: string): string;
+  /** schema/validate：类型不对（expected 缺省时无括注）。 */
+  invalidType(at: string, expected: string): string;
+  /** schema/validate：格式不对（format 缺省时无括注）。 */
+  invalidFormat(at: string, format: string): string;
+
+  /** i18n/table：译文表不是合法 JSON。 */
+  invalidJson(error: string): string;
+  /** i18n/table：译文表根节点必须是对象。 */
+  tableRootMustBeObject(): string;
+  /** i18n/table：键不能为空。 */
+  keyEmpty(): string;
+  /** i18n/table：键的首尾不能有空白。 */
+  keySurroundingWhitespace(): string;
+  /** i18n/table：键不能含控制字符。 */
+  keyControlChars(): string;
+  /** i18n/table：键已存在。 */
+  keyAlreadyExists(key: string): string;
+  /** i18n/table：目标键不在表中。 */
+  keyNotInTable(key: string): string;
+  /** i18n/table：改名目标键已存在，不能合并两行。 */
+  renameConflict(key: string): string;
+
+  /** i18n/skeleton：语言码不合法。 */
+  invalidLangCode(lang: string): string;
+  /** i18n/skeleton：故事路径不合法。 */
+  invalidStoryPath(storyPath: string): string;
+
+  /** i18n/reconcile：某语言缺译 0 条（覆盖完整）。 */
+  missingZero(lang: string): string;
+  /** i18n/reconcile：某语言缺译 N 条。 */
+  missingCount(lang: string, count: number): string;
+  /** i18n/reconcile：多译 0 条（无冗余译文键）。 */
+  unusedZero(): string;
+  /** i18n/reconcile：多译 N 条。 */
+  unusedCount(count: number): string;
+
+  /** script/expr：未 defineVars 就使用 expr。 */
+  exprRequiresDefineVars(): string;
+  /** script/expr：不支持的插值类型。 */
+  unsupportedInterpolationType(type: string): string;
+  /** script/expr 警告：插值落在字符串字面量内部。 */
+  interpolationInsideString(): string;
+  /** script/expr 警告：未闭合的字符串字面量。 */
+  unclosedStringLiteral(): string;
+  /** script/expr：变量句柄路径非法。 */
+  invalidVarHandlePath(prop: string, prefix: string): string;
+  /** script/expr：未注册的变量。 */
+  unregisteredVariable(key: string): string;
+  /** script/expr 审计：操作数类型不匹配。 */
+  operandKindMismatch(op: string, side: string, want: string, described: string, note: string): string;
+  /** script/expr 审计：三元条件必须为 boolean。 */
+  ternaryCondNotBool(described: string): string;
+  /** script/expr 审计：不支持跨类型比较。 */
+  crossTypeComparison(op: string, left: string, right: string): string;
+  /** script/expr 审计：未知类型的操作数标签。 */
+  unknownOperandKind(): string;
+
+  /** schema/surface：扩展 op 归组不合法。 */
+  invalidOpGroup(extensionId: string, op: string, declaredGroup: string, validGroups: string): string;
+}
+
+/** 缺省文案表：即编辑器的既有文案（只搬位置，不改文案）。 */
+export const defaultEditorTexts: EditorTexts = {
+  duplicateColumn: (columnId) => `columnId 重复：${columnId}（columnId 全局唯一）`,
+  missingEntryColumn: (entry) => `入口列 ${entry} 不存在`,
+  missingJumpTargetColumn: (target) => `跳转目标列不存在：${target}`,
+  unknownFunction: (target) => `调用未注册的函数：${target}`,
+  missingCallTarget: (target) => `调用目标不存在：${target}（既不是 func 也不是列）`,
+  undefinedVariableExpression: (name) =>
+    `未定义变量：${name}（表达式里使用，求值会失败并**停机**——请先用 set/define 定义它）`,
+  undefinedVariableInterpolation: (name) =>
+    `未定义变量：${name}（插值失败将按原文保留——若它应是变量请先定义，若只是普通文字请去掉花括号）`,
+  missingResource: (path) => `资源路径不存在：${path}`,
+  unusedTranslationKey: (key) =>
+    `未使用的译文键：${key}（say / menu / input / notify 四个翻译面均未命中原文——该键运行期不会生效；若这段文字只用于元素文本或宿主界面，本条可忽略）`,
+  missingTranslationOriginal: (original) =>
+    `原文未有任何译文：${original}（所有语言的 overlay 均未命中——运行期回退原文；专有名词等有意保留原文的可忽略）`,
+  unimplementedElementAttr: (attr) => `元素属性 ${attr} 已声明但当前无渲染语义（写入不生效）`,
+  elementOpsBlockedOp: (op) =>
+    `元素动作序列里的 ${op} 不可用（等待/位置/存档类会打断当前叙事流）；跳列请用 nav 属性`,
+
+  unknownPayloadFields: (op, keys) => `${op} 未知负载字段：${keys}（编辑期 fail-closed）`,
+  missingRequired: (op, path) => `${op}${path ? `.${path}` : ""} 必填`,
+  invalidValue: (op, path, localized) => `${op}${path ? `.${path}` : ""}：${localized}`,
+  commandMustBeObject: () => "命令必须为对象",
+  commandMustHaveOp: () => "命令必须为含非空 op 字符串的命令对象",
+  unknownCommand: (op) => `未知或未实现的命令：${op}`,
+  resourcePathEmpty: () => "资源路径不能为空",
+  resourcePathEmptyStop: (stopOp) => `资源路径不能为空（要**停止**该通道请用 \`${stopOp}\`）`,
+  valueTooSmall: (at, min) => `${at}不能小于 ${min}`,
+  valueTooSmallBare: (at) => `${at}值太小`,
+  valueTooBig: (at, max) => `${at}不能大于 ${max}`,
+  valueTooBigBare: (at) => `${at}值太大`,
+  invalidType: (at, expected) =>
+    expected === "" ? `${at}类型不对` : `${at}类型不对（需要 ${expected}）`,
+  invalidFormat: (at, format) =>
+    format === "" ? `${at}格式不对` : `${at}格式不对（要求 ${format}）`,
+
+  invalidJson: (error) => `不是合法 JSON：${error}`,
+  tableRootMustBeObject: () => "译文表根节点必须是对象（键 → 译文）",
+  keyEmpty: () => "键不能为空",
+  keySurroundingWhitespace: () => "键的首尾不能有空白",
+  keyControlChars: () => "键不能含控制字符",
+  keyAlreadyExists: (key) => `键「${key}」已存在`,
+  keyNotInTable: (key) => `键「${key}」不在表中`,
+  renameConflict: (key) => `键「${key}」已存在，不能合并两行`,
+
+  invalidLangCode: (lang) => `语言码不合法：${lang}（须为单段安全文件名）`,
+  invalidStoryPath: (storyPath) =>
+    `故事路径不合法：${storyPath}（须为相对 Stories/ 的段级安全路径，如 chapter1/tavern）`,
+
+  missingZero: (lang) => `[${lang}] 缺译 0 条（覆盖完整）`,
+  missingCount: (lang, count) => `[${lang}] 缺译 ${count} 条（运行期回退原文）：`,
+  unusedZero: () => "多译 0 条（无冗余译文键）",
+  unusedCount: (count) => `多译 ${count} 条（未使用 = 冗余）：`,
+
+  exprRequiresDefineVars: () => "expr 需要先 defineVars（变量注册是表达式句柄的前提）",
+  unsupportedInterpolationType: (type) =>
+    `expr 不支持的插值类型：${type}——若是变量句柄，请确认已在 defineVars 注册`,
+  interpolationInsideString: () =>
+    "插值落在字符串字面量内部（引号未闭合）——插值文本会被并进字面量，不会成为表达式操作数",
+  unclosedStringLiteral: () => "表达式存在未闭合的字符串字面量（引擎将 parse-error）",
+  invalidVarHandlePath: (prop, prefix) => `变量句柄路径非法：${prop}（前缀 ${prefix}）`,
+  unregisteredVariable: (key) => `未注册的变量：${key}——请在 defineVars 清单中声明后再引用`,
+  operandKindMismatch: (op, side, want, described, note) =>
+    `'${op}' ${side}操作数必须为 ${want}——${described}（引擎 type-error${note}）`,
+  ternaryCondNotBool: (described) =>
+    `三元 '?' 条件必须为 boolean（引擎 type-error）——条件${described}`,
+  crossTypeComparison: (op, left, right) =>
+    `'${op}' 不支持跨类型比较（${left} vs ${right}）——引擎仅同类型标量相等`,
+  unknownOperandKind: () => "未知类型",
+
+  invalidOpGroup: (extensionId, op, declaredGroup, validGroups) =>
+    `扩展「${extensionId}」的 op「${op}」归组不合法：${declaredGroup}（须为 ${validGroups} 之一）`,
+};
+
+/**
+ * 把调用方可选注入的部分文案合并成完整表：`{ ...defaultEditorTexts, ...texts }`。
+ * 各消费函数内部用它把 `texts?: Partial<EditorTexts>` 归一成 `EditorTexts`。
+ * （契约层只放类型：以 const 箭头函数形态导出——export function 违反包结构互锁测试。）
+ */
+export const resolveEditorTexts = (
+  texts?: Partial<EditorTexts>,
+): EditorTexts => ({ ...defaultEditorTexts, ...texts });

package/src/diagnostics/analyze.ts

@@ -0,0 +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;
+}

package/src/diagnostics/grouping.ts

@@ -0,0 +1,164 @@
+/**
+ * 诊断面板 · **按类型分组与折叠判据**（纯函数，可测）。
+ *
+ * 存在理由：诊断面板是编辑期的「仪表盘」，而工程里**同质诊断会淹没异质诊断**
+ * —— 常见情形是 33 条里 31 条都是 `unused-translation`，把 2 条真错误
+ * （`undefined-variable`）埋掉了。根因是**信息架构**（无分组/折叠），
+ * **不是排版**：调间距/字号救不了「扫读」。
+ *
+ * 排序与折叠两条规则都写在这里（视图只渲染 + 收集意图）：
+ *
+ * 1. **严重度优先**（`error` 在前）⇒ 真错误永远浮在顶部，不被警告挤下去。
+ * 2. **同严重度按条数降序** ⇒ 最「成灾」的类型最显眼（1 条 warning 不该压过 8 条 warning）。
+ * 3. **同条数按 code 码元序** ⇒ 组间顺序确定，不随输入顺序抖动。
+ *
+ * **组内也按 pointer 排序**（不是保留输入顺序）：若组顺序确定但组内
+ * 随输入顺序变，`JSON.stringify` 结果就不同 ⇒ 同一份诊断两次渲染出不同 DOM，
+ * 一切「按结果判等」的守卫都会假绿。**pointer 是稳定的天然键**（无 pointer 的
+ * 全局诊断排在最后、同pointer 组内再按 code 排，仍是确定的）。
+ *
+ * **折叠不是「一律折」**：`error` 组**永不默认折叠**（错误被藏起来 = 仪表盘失效）；
+ * 只有 `warning` 组在条数 > 1 时可默认折叠，且**只对每组第一条生效**（其余由用户手动控制）。
+ */
+
+import type { Diagnostic, DiagnosticSeverity } from "../contracts/index.ts";
+
+/** 严重度排序权重（数字小 = 靠前） */
+const SEVERITY_RANK: Readonly<Record<DiagnosticSeverity, number>> = {
+  error: 0,
+  warning: 1,
+};
+
+/** 诊断码的中文标签（面板组头显示；**未知码如实回显原码**，不编造也不隐藏） */
+const CODE_LABELS: Readonly<Record<string, string>> = {
+  "unknown-op": "未知命令",
+  "unknown-field": "未知字段",
+  "missing-required": "缺必填字段",
+  "invalid-value": "值不合法",
+  "duplicate-column": "列 id 重复",
+  "missing-target": "跳转目标缺失",
+  "unknown-function": "函数不存在",
+  "undefined-variable": "未定义变量",
+  "missing-resource": "资源不存在",
+  "missing-entry": "入口列缺失",
+  "invalid-structure": "结构不合法",
+  "unused-translation": "未使用的译文键",
+  "missing-translation": "缺译文",
+  "invalid-element": "元素不合法",
+  "unimplemented-element-attr": "元素属性未实现",
+};
+
+/** 组头显示的标签（未知码 ⇒ 原样回显，**不吞信息**） */
+export function diagnosticCodeLabel(code: string): string {
+  return CODE_LABELS[code] ?? code;
+}
+
+/** 一个诊断分组 */
+export interface DiagnosticGroup {
+  /** 诊断码（同组同码） */
+  readonly code: string;
+  /** 组头标签（中文；未知码为原码） */
+  readonly label: string;
+  /** 该组最严重的严重度（组内可能混档，取最高） */
+  readonly severity: DiagnosticSeverity;
+  /** 组内条目（**按 pointer 稳定排序**——确定性，见文件头排序规则） */
+  readonly items: readonly Diagnostic[];
+  /** **是否建议默认折叠**（`error` 组恒 `false`） */
+  readonly collapsedByDefault: boolean;
+}
+
+/** 分组判据。空输入 ⇒ 空数组（空态由视图表达，不塞占位组） */
+export function groupDiagnostics(
+  diagnostics: readonly Diagnostic[],
+): readonly DiagnosticGroup[] {
+  const buckets = new Map<string, Diagnostic[]>();
+  for (const d of diagnostics) {
+    const bucket = buckets.get(d.code);
+    if (bucket === undefined) buckets.set(d.code, [d]);
+    else bucket.push(d);
+  }
+  const groups: DiagnosticGroup[] = [];
+  for (const [code, items] of buckets) {
+    // 组严重度 = 取最高（error > warning）——同组可能混档
+    const severity: DiagnosticSeverity = items.some(
+      (d) => d.severity === "error",
+    )
+      ? "error"
+      : "warning";
+    groups.push({
+      code,
+      label: diagnosticCodeLabel(code),
+      severity,
+      // 组内排序：pointer 非空优先（可定位的排前面），再按 pointer 码元序。
+      // 空 pointer = 全局诊断，天然沉底。
+      items: [...items].sort(compareItems),
+      // error 组永不默认折叠；warning 组多条时才建议折（单条折了没意义且更烦）
+      collapsedByDefault: severity !== "error" && items.length > 1,
+    });
+  }
+  return groups.sort(compareGroups);
+}
+
+/** 组内比较：有 pointer 优先 → pointer 码元序 → message 码元序（**全序，确定性**） */
+function compareItems(a: Diagnostic, b: Diagnostic): number {
+  if ((a.pointer === "") !== (b.pointer === ""))
+    return a.pointer === "" ? 1 : -1;
+  if (a.pointer !== b.pointer) return a.pointer < b.pointer ? -1 : 1;
+  return a.message < b.message ? -1 : a.message > b.message ? 1 : 0;
+}
+
+/** 组间比较：严重度 → 条数降序 → code 码元序（**确定性**，不抖） */
+function compareGroups(a: DiagnosticGroup, b: DiagnosticGroup): number {
+  const bySeverity = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+  if (bySeverity !== 0) return bySeverity;
+  if (a.items.length !== b.items.length) return b.items.length - a.items.length;
+  return a.code < b.code ? -1 : a.code > b.code ? 1 : 0;
+}
+
+/** 面板顶部汇总文案（**不逐条罗列**——那正是淹没的来源）：`3 条 · 2 类 · 1 个错误` */
+export interface DiagnosticSummary {
+  readonly total: number;
+  readonly kinds: number;
+  readonly errors: number;
+  readonly warnings: number;
+}
+
+export function summarizeDiagnostics(
+  groups: readonly DiagnosticGroup[],
+): DiagnosticSummary {
+  let errors = 0;
+  let warnings = 0;
+  for (const g of groups) {
+    for (const d of g.items) {
+      if (d.severity === "error") errors += 1;
+      else warnings += 1;
+    }
+  }
+  return { total: errors + warnings, kinds: groups.length, errors, warnings };
+}
+
+/** 汇总文本（**零诊断时给「无」而不是「0 条 · 0 类」**——那不是状态，是空数据的算术） */
+export function diagnosticSummaryText(summary: DiagnosticSummary): string {
+  if (summary.total === 0) return "无";
+  const parts: string[] = [];
+  if (summary.errors > 0) parts.push(`${summary.errors} 个错误`);
+  if (summary.warnings > 0) parts.push(`${summary.warnings} 个警告`);
+  return `${summary.total} 条 · ${parts.join(" · ")}`;
+}
+
+/**
+ * 严重度筛选（**null = 全部**）。
+ *
+ * 为什么进纯函数：徽章「可点筛选」的语义只有一条——按 severity 等值过滤、
+ * **不重排不改写**（排序仍归 `groupDiagnostics`）。放这里组件就没有机会
+ * 在筛选时夹带别的规则（比如把全局诊断滤掉），两处口径永不漂移。
+ */
+export type SeverityFilter = "error" | "warning" | null;
+
+export function filterDiagnosticsBySeverity(
+  diagnostics: readonly Diagnostic[],
+  filter: SeverityFilter,
+): readonly Diagnostic[] {
+  if (filter === null) return diagnostics;
+  return diagnostics.filter((d) => d.severity === filter);
+}

package/src/diagnostics/index.ts

@@ -0,0 +1,35 @@
+/**
+ * 诊断（编辑期）：符号索引 + 诊断集，全部带 JSON Pointer。
+ * - 未定义变量：定义集 = defines + set/define/let/local/array/dict 键 + random.var +
+ *   循环变量 + input.store（并集保守策略：let/local 块级精度为已知限界，不误报优先）；
+ *   `_` 前缀豁免；行内标记白名单镜像执行器语义（已定义变量 > 行内标记）。
+ * - 跳转目标不存在、未知函数、重复 columnId、入口列缺失、资源路径缺失、
+ *   未使用翻译键（overlay 键 − 可翻译原文）、已声明但无渲染语义的元素属性。
+ *
+ * 实现分布：表达式引用抽取在 ./refs，符号索引在 ./symbols，分析入口在 ./analyze
+ * ——本文件只做转发，不承载实现。
+ */
+export { extractExpressionRefs } from "./refs.ts";
+export { indexStory } from "./symbols.ts";
+export { analyzeStory } from "./analyze.ts";
+export type { AnalyzeOptions } from "../contracts/index.ts";
+
+/**
+ * 诊断集的分组与摘要（可按严重度筛选），以及消息文本的拆分与一句话简述。
+ * 两族住在同域的其他文件里，此处一并转发，让本目录只有一个取用入口。
+ */
+export {
+  diagnosticCodeLabel,
+  diagnosticSummaryText,
+  filterDiagnosticsBySeverity,
+  groupDiagnostics,
+  summarizeDiagnostics,
+  type DiagnosticGroup,
+  type DiagnosticSummary,
+  type SeverityFilter,
+} from "./grouping.ts";
+export {
+  diagnosticBrief,
+  splitDiagnosticMessage,
+  type DiagnosticMessageParts,
+} from "./message.ts";