@lingfan-engine/editor 0.0.0-stage → 0.1.2

package/src/schema/opSchemas/validate.ts

@@ -0,0 +1,184 @@
+/**
+ * 编辑期 fail-closed 校验执行：把 zod issue 翻译为中文人话诊断（未知 op /
+ * 未知字段 / 缺必填 / 类型错），供 `validateStory` 与属性面板实时校验共用。
+ */
+import { z } from "zod";
+import type { Diagnostic, EditorTexts } from "../../contracts/index.ts";
+import { escapePointerToken, resolveEditorTexts } from "../../contracts/index.ts";
+import { OP_SCHEMAS } from "./map.ts";
+
+/**
+ * **「resource 为空」时该用哪个停止命令**。
+ *
+ * 为什么需要：既有工程里有 `bgm ""` 表「停止 BGM」的写法，而播放器对空路径
+ * **无特判**（直接以空串去加载）⇒ **静默失败**——作者以为停了，其实没有。
+ * 显式报错比「静默通过」更正确，但直接抛 zod 英文原话
+ * （`Too small: expected string to have >=1 characters`）作者既看不懂、
+ * 也不知道该改什么。
+ *
+ * 处置 = **保持严格校验**（不引入「空路径=停止」这种隐式约定）
+ * + **把正确写法直接告诉作者**（语义明确）。
+ */
+const STOP_OP_BY_RESOURCE_OWNER: Readonly<Record<string, string>> = {
+  bgm: "stop_bgm",
+  ambient: "stop_ambient",
+  voice: "stop_voice",
+  video: "stop_video",
+  cutscene: "stop_video",
+};
+
+/**
+ * zod 错误 → **中文人话**（编辑期诊断给作者看，不该直接透传英文）。
+ *
+ * **兜底保留原文**：没覆盖的 code 返回 `issue.message`——
+ * 宁可英文也不静默丢信息（不吞信息）。
+ *
+ * 文案经 EditorTexts 表（本模块是唯一 zod→中文翻译点；表方法由本函数调用）。
+ */
+function localizeZodIssue(
+  op: string,
+  issue: z.core.$ZodIssue,
+  texts: EditorTexts,
+): string {
+  const field = issue.path.map(String).join(".");
+  const at = field === "" ? "" : `${field} `;
+  switch (issue.code) {
+    case "too_small": {
+      const min = (issue as { minimum?: number }).minimum;
+      if (field === "resource" || field.endsWith(".resource")) {
+        const stopOp = STOP_OP_BY_RESOURCE_OWNER[op];
+        return stopOp === undefined
+          ? texts.resourcePathEmpty()
+          : texts.resourcePathEmptyStop(stopOp);
+      }
+      return typeof min === "number" && min > 0
+        ? texts.valueTooSmall(at, min)
+        : texts.valueTooSmallBare(at);
+    }
+    case "too_big": {
+      const max = (issue as { maximum?: number }).maximum;
+      return typeof max === "number"
+        ? texts.valueTooBig(at, max)
+        : texts.valueTooBigBare(at);
+    }
+    case "invalid_type": {
+      const expected = (issue as { expected?: unknown }).expected;
+      return texts.invalidType(at, typeof expected === "string" ? expected : "");
+    }
+    case "invalid_format": {
+      const format = (issue as { format?: unknown }).format;
+      return texts.invalidFormat(at, typeof format === "string" ? format : "");
+    }
+    default:
+      return issue.message;
+  }
+}
+
+function issueToDiagnostic(
+  issue: z.core.$ZodIssue,
+  basePointer: string,
+  op: string,
+  texts: EditorTexts,
+): Diagnostic {
+  const segments = issue.path.map((seg) => escapePointerToken(String(seg)));
+  const pointer =
+    segments.length > 0 ? `${basePointer}/${segments.join("/")}` : basePointer;
+  if (issue.code === "unrecognized_keys") {
+    const keys =
+      "keys" in issue && Array.isArray(issue.keys)
+        ? issue.keys.map(String).join(", ")
+        : issue.message;
+    return {
+      code: "unknown-field",
+      severity: "error",
+      message: texts.unknownPayloadFields(op, keys),
+      pointer,
+      op,
+    };
+  }
+  const received = (issue as { received?: unknown }).received;
+  if (
+    issue.code === "invalid_type" &&
+    (received === undefined || received === "undefined")
+  ) {
+    return {
+      code: "missing-required",
+      severity: "error",
+      message: texts.missingRequired(
+        op,
+        issue.path.length > 0 ? issue.path.join(".") : "",
+      ),
+      pointer,
+      op,
+    };
+  }
+  return {
+    code: "invalid-value",
+    severity: "error",
+    message: texts.invalidValue(
+      op,
+      issue.path.length > 0 ? issue.path.join(".") : "",
+      localizeZodIssue(op, issue, texts),
+    ),
+    pointer,
+    op,
+  };
+}
+
+/**
+ * 编辑期单命令 fail-closed 校验（结构层）：未知 op / 未知字段 / 缺必填 / 类型错。
+ * pointer = 命令对象自身在 Story 树上的 JSON Pointer。
+ * `schemas`（可选）= op 负载 schema 面（缺省内建 OP_SCHEMAS；扩展注册后传合并集）。
+ * `texts`（可选）= 集中文案表注入（缺省 defaultEditorTexts）。
+ * 编辑期 fail-closed 校验的测试见 validation.test。
+ */
+export function validateCommand(
+  cmd: unknown,
+  pointer = "",
+  schemas: Readonly<Record<string, z.ZodType>> = OP_SCHEMAS,
+  texts: Partial<EditorTexts> = {},
+): Diagnostic[] {
+  const t = resolveEditorTexts(texts);
+  if (typeof cmd !== "object" || cmd === null || Array.isArray(cmd)) {
+    return [
+      {
+        code: "invalid-structure",
+        severity: "error",
+        message: t.commandMustBeObject(),
+        pointer,
+      },
+    ];
+  }
+  const op = (cmd as Record<string, unknown>).op;
+  if (typeof op !== "string" || op === "") {
+    return [
+      {
+        code: "invalid-structure",
+        severity: "error",
+        message: t.commandMustHaveOp(),
+        pointer,
+      },
+    ];
+  }
+  const schema = schemas[op];
+  if (schema === undefined) {
+    return [
+      {
+        code: "unknown-op",
+        severity: "error",
+        message: t.unknownCommand(op),
+        pointer,
+        op,
+      },
+    ];
+  }
+  const payload: Record<string, unknown> = {
+    ...(cmd as Record<string, unknown>),
+  };
+  delete payload.op;
+  const result = schema.safeParse(payload);
+  if (result.success) return [];
+  return result.error.issues.map((issue) =>
+    issueToDiagnostic(issue, pointer, op, t),
+  );
+}

package/src/schema/surface.ts

@@ -0,0 +1,101 @@
+/**
+ * 扩展 op 面合并：**纯函数**产出扩展集，
+ * 不修改 `OP_SCHEMAS`/`OP_META` 常量本体——消费方（表单/校验/组件面板/遍历器）改读合并面。
+ * 扩展声明形状 = 引擎契约 `OpEditorSchema`（载体：label/group + zod 负载 schema）；
+ * op 名冲突不可能（引擎注册期查重先抛），此处只做聚合。
+ */
+
+import type { z } from "zod";
+import type { OpExtension, WaitSpec } from "@lingfan-engine/core";
+import type { EditorTexts, OpMeta } from "../contracts/index.ts";
+import { resolveEditorTexts } from "../contracts/index.ts";
+import { WAITING_OPS, collectWaitSpecs } from "@lingfan-engine/core";
+import { OP_GROUP_ORDER, OP_META } from "./catalog.ts";
+import { OP_SCHEMAS } from "./opSchemas/index.ts";
+
+/** op 校验/呈现面：内建 = 常量本体；扩展注册后 = 合并集（消费方唯一读取口径） */
+export interface OpSurface {
+  readonly schemas: Readonly<Record<string, z.ZodType>>;
+  readonly meta: readonly OpMeta[];
+  /** op → 等待规格合并面：内建表 + wait:true 的扩展 op（collectWaitSpecs 产物） */
+  readonly waiting?: ReadonlyMap<string, WaitSpec>;
+}
+
+export const BUILTIN_OP_SURFACE: OpSurface = {
+  schemas: OP_SCHEMAS,
+  meta: OP_META,
+};
+
+/** 合并扩展负载 schema（`OpEditorSchema.schema` 以 unknown 载体声明，编辑器窄化为 zod） */
+export function mergeOpSchemas(
+  base: Readonly<Record<string, z.ZodType>>,
+  extensions: readonly OpExtension[],
+): Record<string, z.ZodType> {
+  const merged = { ...base };
+  for (const extension of extensions) {
+    for (const definition of extension.ops ?? []) {
+      if (definition.schema !== undefined) {
+        merged[definition.op] = definition.schema.schema as z.ZodType;
+      }
+    }
+  }
+  return merged;
+}
+
+/** 合并扩展 op 元数据（标签/归组；追加保序——面板分组渲染按 OP_GROUP_ORDER 归位）。
+ * 归组非法（不在 OP_GROUP_ORDER 八组内）= 扩展声明违约 → **装配期 fail-fast 抛错**（带定位），
+ * 与引擎注册期校验同精神——静默丢弃会让扩展 op 从面板消失（不诚实）。
+ * texts（可选）= 集中文案表注入（缺省 defaultEditorTexts；装配期错误无外部调用链，走缺省）。 */
+export function mergeOpMeta(
+  base: readonly OpMeta[],
+  extensions: readonly OpExtension[],
+  texts: Partial<EditorTexts> = {},
+): OpMeta[] {
+  const t = resolveEditorTexts(texts);
+  const additions: OpMeta[] = [];
+  for (const extension of extensions) {
+    for (const definition of extension.ops ?? []) {
+      const declared = definition.schema;
+      if (declared === undefined) continue;
+      if (!OP_GROUP_ORDER.includes(declared.group as never)) {
+        throw new Error(
+          t.invalidOpGroup(
+            extension.id,
+            definition.op,
+            String(declared.group),
+            OP_GROUP_ORDER.join(" / "),
+          ),
+        );
+      }
+      additions.push({
+        op: definition.op,
+        label: declared.label,
+        group: declared.group as OpMeta["group"],
+      });
+    }
+  }
+  return [...base, ...additions];
+}
+
+/** 组合根入口：内建面 + 扩展 → 合并面（缺省扩展 = 内建面原样）。
+ * 等待声明表一并并入：内建表打底，wait:true 的扩展 op 覆盖同名（引擎注册期已查重，实为追加）——
+ * SSOT 仍是引擎的 `WAITING_OPS` + `collectWaitSpecs`，编辑器只透传不复制。 */
+export function mergeOpSurface(
+  extensions: readonly OpExtension[],
+  base: OpSurface = BUILTIN_OP_SURFACE,
+): OpSurface {
+  return {
+    schemas: mergeOpSchemas(base.schemas, extensions),
+    meta: mergeOpMeta(base.meta, extensions),
+    waiting: mergeOpWaiting(base.waiting, extensions),
+  };
+}
+
+/** 合并扩展等待声明：内建表 `WAITING_OPS` 打底（base 缺省时），collectWaitSpecs 的扩展条目并入。
+ * 消费方（steps.ts 边界判定）读合并面——未合并时回退内建口径。 */
+function mergeOpWaiting(
+  base: ReadonlyMap<string, WaitSpec> | undefined,
+  extensions: readonly OpExtension[],
+): ReadonlyMap<string, WaitSpec> {
+  return collectWaitSpecs(extensions, base ?? WAITING_OPS);
+}

package/src/schema/validation.ts

@@ -0,0 +1,92 @@
+/**
+ * 编辑期故事级校验：envelope（故事/列结构）+ 共享遍历器的逐命令校验
+ * （嵌套块体里的未知 op/坏负载同样拿到精确 JSON Pointer 诊断）。
+ * 结构校验面与 packages/core 的 `data/format/` 对齐（单列文件名不变量归组装器，此处不管）。
+ */
+
+import { z } from "zod";
+import type { Diagnostic } from "../contracts/index.ts";
+import { escapePointerToken } from "../contracts/index.ts";
+import type { OpExtension } from "@lingfan-engine/core";
+import { validateElementNode } from "@lingfan-engine/core";
+import { validateCommand } from "./opSchemas/index.ts";
+import { mergeOpSurface } from "./surface.ts";
+import { walkStoryCommands, walkStoryElements } from "./walk.ts";
+
+const NonEmpty = z.string().min(1);
+
+export const columnSchema = z.object({
+  id: NonEmpty,
+  kind: z.enum(["scene", "flow"]),
+  elements: z.array(z.unknown()).optional(),
+  entry: z.array(z.unknown()).optional(),
+  commands: z.array(z.unknown()).optional(),
+});
+
+export const storySchema = z.object({
+  formatVersion: z.literal(1),
+  id: NonEmpty,
+  entry: NonEmpty,
+  columns: z.array(columnSchema).min(1),
+  defines: z.record(z.string(), z.unknown()).optional(),
+  lang: z.string().optional(),
+});
+
+function issuesToDiagnostics(
+  issues: z.core.$ZodIssue[],
+  basePointer: string,
+): Diagnostic[] {
+  return issues.map((issue) => {
+    const segments = issue.path.map((seg) => escapePointerToken(String(seg)));
+    const pointer =
+      segments.length > 0
+        ? `${basePointer}/${segments.join("/")}`
+        : basePointer;
+    return {
+      code: "invalid-structure",
+      severity: "error",
+      message: issue.message,
+      pointer,
+    };
+  });
+}
+
+/**
+ * 编辑期整树 fail-closed 校验：envelope 结构 + 全部列（flow/scene 两容器）
+ * 及嵌套块体的逐命令校验。诊断一律带 JSON Pointer。
+ * `extensions`（可选）：扩展 op 经合并面纳入校验（缺省 = 内建面，未注册 op 仍 unknown-op）。
+ */
+export function validateStory(
+  story: unknown,
+  extensions: readonly OpExtension[] = [],
+): Diagnostic[] {
+  const out: Diagnostic[] = [];
+  const result = storySchema.safeParse(story);
+  if (!result.success) {
+    out.push(...issuesToDiagnostics(result.error.issues, ""));
+  }
+  const surface = mergeOpSurface(extensions);
+  walkStoryCommands(
+    story,
+    (cmd, pointer) => {
+      out.push(...validateCommand(cmd, pointer, surface.schemas));
+    },
+    surface,
+  );
+  // scene 列元素：复用引擎单一事实源（编辑期与运行期同口径）。
+  // 逐节点遍历 + `validateElementNode`（**单节点**版）——不能用带递归的 `validateElement`，
+  // 否则与遍历叠加会双报同一子元素问题。
+  walkStoryElements(story, (node, pointer) => {
+    const issues: string[] = [];
+    validateElementNode(node, pointer, issues);
+    for (const message of issues) {
+      out.push({
+        code: "invalid-element",
+        severity: "error",
+        message,
+        pointer,
+      });
+    }
+  });
+  return out;
+}

package/src/schema/walk.ts

@@ -0,0 +1,167 @@
+/**
+ * 故事树命令遍历器（编辑器内部共享）：列双容器（flow.commands / scene.elements+entry）
+ * + 沿表单描述符递归块体（if.then/elif[].then/else、while/for/foreach.body、
+ * switch.cases[].body/default、func.body）。校验与符号索引共用同一遍历，指针一致。
+ */
+
+import type { FieldDescriptor } from "../contracts/index.ts";
+import { escapePointerToken } from "../contracts/index.ts";
+import { isPlainObject } from "../shared/index.ts";
+import { describeForm } from "./forms.ts";
+import { BUILTIN_OP_SURFACE, type OpSurface } from "./surface.ts";
+
+export type CommandVisitor = (
+  cmd: Record<string, unknown>,
+  pointer: string,
+  fields: readonly FieldDescriptor[] | undefined,
+) => void;
+
+function walkDescriptor(
+  desc: FieldDescriptor,
+  value: unknown,
+  pointer: string,
+  visit: CommandVisitor,
+  surface: OpSurface,
+): void {
+  if (desc.kind === "body") {
+    if (Array.isArray(value)) walkCommands(value, pointer, visit, surface);
+    return;
+  }
+  if (desc.properties !== undefined && isPlainObject(value)) {
+    for (const child of desc.properties) {
+      walkDescriptor(
+        child,
+        value[child.key],
+        `${pointer}/${escapePointerToken(child.key)}`,
+        visit,
+        surface,
+      );
+    }
+    return;
+  }
+  if (desc.item !== undefined && Array.isArray(value)) {
+    value.forEach((element, index) => {
+      walkDescriptor(
+        desc.item!,
+        element,
+        `${pointer}/${index}`,
+        visit,
+        surface,
+      );
+    });
+  }
+}
+
+function walkCommands(
+  commands: unknown[],
+  pointer: string,
+  visit: CommandVisitor,
+  surface: OpSurface,
+): void {
+  commands.forEach((cmd, index) => {
+    const commandPointer = `${pointer}/${index}`;
+    if (!isPlainObject(cmd)) {
+      visit(cmd as Record<string, unknown>, commandPointer, undefined);
+      return;
+    }
+    const fields = describeForm(cmd.op as string, surface)?.fields;
+    visit(cmd, commandPointer, fields);
+    if (fields !== undefined) {
+      walkBodyFields(fields, cmd, commandPointer, visit, surface);
+    }
+  });
+}
+
+/** 块体递归本体（`fields` 已解析——`walkCommandBodies` 与 `walkCommands` 共用，避免重复解析） */
+function walkBodyFields(
+  fields: readonly FieldDescriptor[],
+  cmd: Record<string, unknown>,
+  commandPointer: string,
+  visit: CommandVisitor,
+  surface: OpSurface,
+): void {
+  for (const field of fields) {
+    walkDescriptor(
+      field,
+      cmd[field.key],
+      `${commandPointer}/${escapePointerToken(field.key)}`,
+      visit,
+      surface,
+    );
+  }
+}
+
+/**
+ * 沿**单条命令**的表单描述符递归其全部块体（if.then/elif[].then/else、while/for/foreach.body、
+ * switch.cases[].body/default、func.body），按有序体深度优先回调受控命令。
+ * 与 `walkStoryCommands` 共用同一份「块体字段」知识（表单描述符的单点），
+ * 故「某命令的体里有什么」在本模块内不存在第二套判定。
+ */
+export function walkCommandBodies(
+  cmd: Record<string, unknown>,
+  commandPointer: string,
+  visit: CommandVisitor,
+  surface: OpSurface = BUILTIN_OP_SURFACE,
+): void {
+  const fields = describeForm(cmd.op as string, surface)?.fields;
+  if (fields === undefined) return;
+  walkBodyFields(fields, cmd, commandPointer, visit, surface);
+}
+
+/**
+ * 遍历整棵故事树的全部**命令**（含嵌套块体）；visit 按命令指针回调。
+ * `surface`（可选）= op 合并面（缺省内建；扩展注册后由组合根传入）。
+ * 注意：scene 列的 `elements` **不在**命令遍历内——元素是声明式空间层，
+ * 其形状/属性校验走 `walkStoryElements` + `validateElement`。
+ * 混进命令遍历会被误报 `unknown-op`（元素只有 `type`，没有 `op`）。
+ */
+export function walkStoryCommands(
+  story: unknown,
+  visit: CommandVisitor,
+  surface: OpSurface = BUILTIN_OP_SURFACE,
+): void {
+  if (!isPlainObject(story) || !Array.isArray(story.columns)) return;
+  story.columns.forEach((column, columnIndex) => {
+    if (!isPlainObject(column)) return;
+    const columnPointer = `/columns/${columnIndex}`;
+    const fields = column.kind === "flow" ? ["commands"] : ["entry"];
+    for (const field of fields) {
+      const list = column[field];
+      if (Array.isArray(list)) {
+        walkCommands(list, `${columnPointer}/${field}`, visit, surface);
+      }
+    }
+  });
+}
+
+export type ElementVisitor = (
+  node: Record<string, unknown>,
+  pointer: string,
+) => void;
+
+function walkElementList(
+  list: readonly unknown[],
+  pointer: string,
+  visit: ElementVisitor,
+): void {
+  list.forEach((node, index) => {
+    const nodePointer = `${pointer}/${index}`;
+    // 非对象也回调（由 validateElement 报「必须为对象」，保持诊断口径统一）
+    visit(node as Record<string, unknown>, nodePointer);
+    if (isPlainObject(node) && Array.isArray(node.children)) {
+      walkElementList(node.children, `${nodePointer}/children`, visit);
+    }
+  });
+}
+
+/** 遍历 scene 列的舞台元素（含 `children` 递归）；visit 按元素指针回调（校验与索引共用） */
+export function walkStoryElements(story: unknown, visit: ElementVisitor): void {
+  if (!isPlainObject(story) || !Array.isArray(story.columns)) return;
+  story.columns.forEach((column, columnIndex) => {
+    if (!isPlainObject(column) || column.kind !== "scene") return;
+    const list = column.elements;
+    if (Array.isArray(list)) {
+      walkElementList(list, `/columns/${columnIndex}/elements`, visit);
+    }
+  });
+}

package/src/script/expr/audit/index.ts

@@ -0,0 +1,8 @@
+/**
+ * 审计子模块出口：判类器与它使用的词法词汇。
+ *
+ * 装配层只从这里取，不引子模块内部文件。
+ */
+
+export { ExpressionAuditor } from "./parser.ts";
+export { type AuditToken, type OperandKind } from "./token.ts";