@lingfan-engine/editor 0.0.0-stage → 0.1.0

package/src/script/expr/registry.ts

@@ -0,0 +1,130 @@
+/**
+ * 变量注册表与句柄：显式注册制的声明面。
+ *
+ * 引擎表达式是字符串、求值归引擎，本层只负责生成表达式文本——
+ * `defineVars` 声明一个故事源用到的变量（IDE 补全与拼写检查由此而来），
+ * 句柄树的叶子是 `VarHandle`，装配期按注册表核对：未注册的引用直接抛错。
+ *
+ * 注册表与警告池是模块态，一次导入 = 一个故事源。
+ */
+
+import type { EditorTexts } from "../../contracts/index.ts";
+import { resolveEditorTexts } from "../../contracts/index.ts";
+
+/** 变量种类（注册时声明；构建期轻校验的判类依据） */
+export type VarKind = "num" | "str" | "bool";
+
+export interface VarHandle {
+  readonly kind: VarKind;
+  /** 引擎状态键（如 `player.gold`） */
+  readonly key: string;
+}
+
+const VAR_KINDS: ReadonlySet<string> = new Set(["num", "str", "bool"]);
+
+/** 真句柄 = kind 为三种之一且 key 为字符串——未注册子树 Proxy 的 kind 是对象，判否 */
+export function isVarHandle(value: unknown): value is VarHandle {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { kind?: unknown; key?: unknown };
+  return (
+    typeof candidate.kind === "string" &&
+    VAR_KINDS.has(candidate.kind) &&
+    typeof candidate.key === "string"
+  );
+}
+
+/** 嵌套句柄树（`vars.player.gold` ⇒ handle{key: "player.gold"}） */
+export interface VarTree {
+  [prop: string]: VarTree | VarHandle;
+}
+
+/** 当前注册表（`expr` 标签读取；`defineVars` 绑定——每个故事源文件声明一次） */
+export let currentRegistry: ReadonlyMap<string, VarKind> | null = null;
+
+/** 构建期警告池（与 currentRegistry 同范式的模块态：一次导入 = 一个故事源；drain 后清零；装配层写入） */
+export let warningSink: ExpressionWarning[] = [];
+
+/**
+ * 取走并清空构建期警告。stories-build 在源模块导入完成后调用一次进 BuildReport；
+ * 连续两次调用，第二次必为空（drain 即清零）。
+ */
+export function drainExpressionWarnings(): readonly ExpressionWarning[] {
+  const out = warningSink;
+  warningSink = [];
+  return out;
+}
+
+/**
+ * 构建期轻类型校验警告（引擎 type-error 的构建期预告；不拦构建）。
+ * 规则名与引擎 `runtime/expr/` 的类型规则一一对应（见 `ExpressionAuditor`）。
+ */
+export interface ExpressionWarning {
+  /** 完整表达式文本（含 `{}` 包装） */
+  readonly expression: string;
+  readonly rule:
+    | "arith-non-num"
+    | "compare-non-num"
+    | "equality-kind-mismatch"
+    | "logical-non-bool"
+    | "unary-not-non-bool"
+    | "unary-minus-non-num"
+    | "ternary-cond-non-bool"
+    | "interpolation-inside-string"
+    | "unclosed-string-literal";
+  /** 人话说明（含引擎将抛的 type-error 语义与出错操作数） */
+  readonly message: string;
+}
+
+function makeTree(
+  prefix: string,
+  handles: ReadonlyMap<string, VarHandle>,
+  texts: EditorTexts,
+): VarTree {
+  return new Proxy({} as VarTree, {
+    get(_target, prop): VarTree | VarHandle {
+      if (typeof prop !== "string" || prop === "then") {
+        throw new Error(texts.invalidVarHandlePath(String(prop), prefix || "(根)"));
+      }
+      const key = prefix === "" ? prop : `${prefix}.${prop}`;
+      const handle = handles.get(key);
+      if (handle !== undefined) return handle;
+      // 未注册路径：继续给子树 Proxy（链式展开），expr 求值时校验终值
+      return makeTree(key, handles, texts);
+    },
+  });
+}
+
+/**
+ * 声明变量清单并绑定为本文件的 `expr` 上下文。
+ * 每个故事源文件调用一次（重复调用 = 覆盖前一份注册表——源文件间的变量清单
+ * 各自独立声明，不共享）。
+ *
+ * ```ts
+ * const vars = defineVars({ "player.gold": "num", "player.name": "str" });
+ * cond`${vars.player.gold} >= 25` // ⇒ "{player.gold >= 25}"
+ * ```
+ */
+export function defineVars(
+  spec: Record<string, VarKind>,
+  texts: Partial<EditorTexts> = {},
+): VarTree {
+  const t = resolveEditorTexts(texts);
+  currentRegistry = new Map(Object.entries(spec));
+  const handles = new Map<string, VarHandle>(
+    Object.entries(spec).map(([key, kind]) => [key, { kind, key }]),
+  );
+  return makeTree("", handles, t);
+}
+
+/** 句柄对应的注册键（expr 内部用；未注册 ⇒ 抛错——拼写错误在构建期就红） */
+export function varKeyOf(
+  handle: VarHandle,
+  registry: ReadonlyMap<string, VarKind>,
+  texts: Partial<EditorTexts> = {},
+): string {
+  const t = resolveEditorTexts(texts);
+  if (!registry.has(handle.key)) {
+    throw new Error(t.unregisteredVariable(handle.key));
+  }
+  return handle.key;
+}

package/src/script/index.ts

@@ -0,0 +1,168 @@
+/**
+ * Script 词汇层 · 出口（全量 op 覆盖 + 复合词 + 表达式句柄）。
+ *
+ * **SCRIPT_COVERAGE = builder ↔ op 双射的机器可读面**——生成物（./vocabulary.g.ts，
+ * 由 generate-vocabulary.ts 重建，勿手改）：直接词条来自 words 源返回注解扫描，
+ * 辅助词走显式补充表，注册表键集快照同步入内。改注册表/词条后未重建 =
+ * tests/editor/script-vocabulary.test.ts 的生成物新鲜度用例红。
+ * `$` 前缀 = 辅助词（不直接产出独立 op）——互锁比较时跳过。
+ */
+export {
+  SCRIPT_COVERAGE,
+  VOCABULARY_OPS,
+  type VocabularyOp,
+} from "./vocabulary.g.ts";
+
+// —— 类型（裸写命令的强类型形态：op 判别联合，与 OP_SCHEMA_MAP / validateCommand 同源）——
+// 裸对象 `const cmd: ScriptCommand = { op: "say", text, z }` ⇒ op 决定字段、未知字段编译期红；
+// 扩展 op 不在联合内（闭合防逃生舱漏洞）——走 `extOp()` 或显式 `: StoryCommand` 注解。
+export type {
+  CommandOf,
+  ScriptCommand,
+  ScriptOpName,
+  ScriptValue,
+} from "../schema/index.ts";
+
+// —— 表达式句柄 ——
+export {
+  defineVars,
+  expr,
+  cond,
+  drainExpressionWarnings,
+  type VarKind,
+  type VarHandle,
+  type VarTree,
+  type ExpressionWarning,
+} from "./expr/index.ts";
+
+// —— 编译期构造（仅 Stories.src 源内可用，运行期不提供实现）——
+export { staticFor } from "./words/index.ts";
+export type { StoryFn } from "./words/index.ts";
+
+// —— 具名实现槽位（build-time 声明词）——
+export {
+  cell,
+  type CellHandle,
+  type ColumnNameRegistry,
+  type GuardNameRegistry,
+  type InterpolationKeyRegistry,
+  type KnownColumnName,
+  type KnownGuardName,
+  type KnownInterpolationKey,
+} from "./words/index.ts";
+
+// —— 叙事 ——
+export { say, option, menu, input, notify, nvl, character, uncharacter } from "./words/index.ts";
+export type {
+  MenuOptionSpec,
+  SayOptions,
+  NotifyOptions,
+  NvlCommandMode,
+  CharacterOptions,
+} from "./words/index.ts";
+
+// —— 流程 ——
+export {
+  type Stmt,
+  wait,
+  pause,
+  random,
+  jump,
+  navigate,
+  func,
+  call,
+  ret,
+  when,
+  whenChain,
+  whileDo,
+  forIn,
+  forEach,
+  switchOn,
+  breakLoop,
+  continueLoop,
+  assert,
+  guard,
+} from "./words/index.ts";
+
+// —— 变量 ——
+export {
+  set,
+  define,
+  letVar,
+  localVar,
+  undef,
+  newArray,
+  arrayPush,
+  arrayPop,
+  dict,
+  dictSet,
+} from "./words/index.ts";
+
+// —— 存档 / 音频 / 视频 / 小游戏 ——
+export { save, load, autoSave, saveDelete } from "./words/index.ts";
+export {
+  bgm,
+  stopBgm,
+  se,
+  ambient,
+  stopAmbient,
+  voice,
+  stopVoice,
+} from "./words/index.ts";
+export type {
+  PlayOptions,
+  BgmOptions,
+  StopOptions,
+  VoiceOptions,
+} from "./words/index.ts";
+export {
+  video,
+  cutscene,
+  seekVideo,
+  pauseVideo,
+  resumeVideo,
+  stopVideo,
+  videoSkipable,
+} from "./words/index.ts";
+export type { VideoOptions, CutsceneOptions } from "./words/index.ts";
+export { minigame, reward } from "./words/index.ts";
+export type { MinigameOptions } from "./words/index.ts";
+export { interaction } from "./words/index.ts";
+export type { InteractionOptions } from "./words/index.ts";
+
+// —— 扩展 ——
+export { extOp } from "./words/index.ts";
+
+// —— 元素 ——
+export {
+  show,
+  hide,
+  background,
+  bgSwitch,
+  setZ,
+  style,
+  dialogWindow,
+  animate,
+  animateBlock,
+  transition,
+  shake,
+  textTypewriter,
+} from "./words/index.ts";
+export type {
+  ShowOptions,
+  AnimateOptions,
+  AnimateBlockOptions,
+  ShakeOptions,
+  TypewriterOptions,
+  DialogWindowMode,
+} from "./words/index.ts";
+
+// —— 复合词 ——
+export {
+  sceneSetup,
+  buttonElement,
+  textElement,
+  imageElement,
+  sceneType,
+} from "./words/index.ts";
+export type { ElementOptions } from "./words/index.ts";

package/src/script/vocabulary-gen.ts

@@ -0,0 +1,202 @@
+/**
+ * 词汇层声明生成器（纯函数：无 fs、无副作用、无控制台输出）。
+ *
+ * 两个真相源在渲染时合流成一份机器可读声明（vocabulary.g.ts，由同目录
+ * generate-vocabulary.ts 重建），词表不再手写双份：
+ * - **op 注册表**（OP_SCHEMA_MAP 键集）→ `VOCABULARY_OPS`：注册表面的单一快照；
+ * - **words 域源码扫描**：返回注解为 `CommandOf<"op">` 的导出函数 = 直接词条。
+ * 不产独立 op 的导出词（复合词、菜单项、扩展出口等）走 `HELPER_WORDS` 显式补充表，
+ * 缺登记 = fail-closed（抛错），新词不可能静默漏网。
+ */
+import * as ts from "typescript";
+
+/** 单个被扫描源文件（file = 展示与分组用短名，text = 全文） */
+export interface VocabSource {
+  readonly file: string;
+  readonly text: string;
+}
+
+/** 扫描出的直接词条（builder ↔ op） */
+export interface DirectEntry {
+  readonly builder: string;
+  readonly op: string;
+  readonly file: string;
+}
+
+/** 扫描名单的排除集：barrel 出口 + 两处非词汇词文件
+ * （cells = 具名实现槽位、compile-time = 编译期构造，都不产词汇词）。 */
+const SKIP_FILES = new Set(["index.ts", "cells.ts", "compile-time.ts"]);
+
+/** 扫描名单规则（重建 CLI 与新鲜度测试共用，规则只有这一份） */
+export function selectWordSources(fileNames: readonly string[]): string[] {
+  return fileNames
+    .filter((f) => f.endsWith(".ts") && !SKIP_FILES.has(f))
+    .sort();
+}
+
+/** 辅助词补充表：words 域里不产独立 op 的导出词。
+ *  `$` 前缀 = 互锁比较跳过标记；新增辅助词必须在此登记，
+ *  未登记的新导出词会让重建失败（见 renderVocabulary 的缺登记核对）。 */
+export const HELPER_WORDS: Readonly<Record<string, string>> = {
+  option: "$menu.option",
+  whenChain: "$if.chain",
+  reward: "$minigame.reward",
+  extOp: "$ext.op",
+  sceneSetup: "$composite.scene",
+  buttonElement: "$composite.button",
+  textElement: "$composite.text",
+  imageElement: "$composite.image",
+  sceneType: "$column.type",
+};
+
+/** 返回注解是否为 CommandOf<"op"> 字面量形态，是则取 op 名 */
+function commandOfOpName(
+  returnType: ts.TypeNode | undefined,
+): string | undefined {
+  if (!returnType || !ts.isTypeReferenceNode(returnType)) return undefined;
+  if (
+    !ts.isIdentifier(returnType.typeName) ||
+    returnType.typeName.text !== "CommandOf"
+  ) {
+    return undefined;
+  }
+  const arg = returnType.typeArguments?.[0];
+  if (!arg || !ts.isLiteralTypeNode(arg) || !ts.isStringLiteral(arg.literal)) {
+    return undefined;
+  }
+  return arg.literal.text;
+}
+
+function isExportedFunction(
+  node: ts.Statement,
+): node is ts.FunctionDeclaration {
+  if (!ts.isFunctionDeclaration(node) || !node.name || !node.body) return false;
+  return (
+    node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false
+  );
+}
+
+/** 扫描直接词条：导出函数中返回注解为 `CommandOf<"op">` 者。
+ *  同一 op 被两个 builder 声明 = 抛错（双射面不允许一 op 多词）。 */
+export function scanDirectBuilders(
+  sources: readonly VocabSource[],
+): DirectEntry[] {
+  const entries: DirectEntry[] = [];
+  const opOwner = new Map<string, string>();
+  for (const { file, text } of sources) {
+    const sf = ts.createSourceFile(file, text, ts.ScriptTarget.ES2022, true);
+    for (const node of sf.statements) {
+      // FunctionDeclaration.name 可选：谓词收窄不含「名字存在」，此处再核一次
+      if (!isExportedFunction(node) || !node.name) continue;
+      const op = commandOfOpName(node.type);
+      if (op === undefined) continue;
+      const builder = node.name.text;
+      const clash = opOwner.get(op);
+      if (clash !== undefined) {
+        throw new Error(
+          `op "${op}" 被两个 builder 声明：${clash} 与 ${builder}（${file}）`,
+        );
+      }
+      opOwner.set(op, builder);
+      entries.push({ builder, op, file });
+    }
+  }
+  return entries;
+}
+
+/** 扫描 words 域全部导出函数名（辅助词核对用） */
+export function scanExportedFunctionNames(
+  sources: readonly VocabSource[],
+): Set<string> {
+  const names = new Set<string>();
+  for (const { file, text } of sources) {
+    const sf = ts.createSourceFile(file, text, ts.ScriptTarget.ES2022, true);
+    for (const node of sf.statements) {
+      if (!isExportedFunction(node) || !node.name) continue;
+      names.add(node.name.text);
+    }
+  }
+  return names;
+}
+
+/** 渲染词汇层声明全文（与入库存量逐字节比对的就是这个输出）。
+ *  三处不一致都会抛错而非静默产出：
+ *  - 词条 op 不在注册表快照（词先于 schema）；
+ *  - 补充表登记了不存在的导出函数（幽灵登记）；
+ *  - words 域出现既非直接词条也无补充条目的导出函数（漏登记）。 */
+export function renderVocabulary(
+  registryKeys: readonly string[],
+  sources: readonly VocabSource[],
+): string {
+  const direct = scanDirectBuilders(sources);
+  const unknownOps = direct
+    .map((e) => e.op)
+    .filter((op) => !registryKeys.includes(op));
+  if (unknownOps.length > 0) {
+    throw new Error(
+      `词条产出注册表快照之外的 op：${unknownOps.join(", ")}——先在 OP_SCHEMA_MAP 登记再重建`,
+    );
+  }
+  const exported = scanExportedFunctionNames(sources);
+  const ghostHelpers = Object.keys(HELPER_WORDS).filter(
+    (b) => !exported.has(b),
+  );
+  if (ghostHelpers.length > 0) {
+    throw new Error(
+      `辅助词补充表登记了不存在的导出函数：${ghostHelpers.join(", ")}`,
+    );
+  }
+  const missingHelpers = [...exported].filter(
+    (b) => !direct.some((e) => e.builder === b) && !(b in HELPER_WORDS),
+  );
+  if (missingHelpers.length > 0) {
+    throw new Error(
+      `words 域存在未登记的导出函数（既非直接词条也无补充表条目）：${missingHelpers.join(", ")}`,
+    );
+  }
+
+  const lines: string[] = [
+    "/**",
+    " * 生成文件：词汇层声明（勿手改）。",
+    " *",
+    " * 由 packages/editor/src/script/generate-vocabulary.ts 重建（两个真相源）：",
+    " * - OP_SCHEMA_MAP 键快照 → VOCABULARY_OPS（op 注册表面的单一来源）；",
+    " * - words/*.ts 导出函数扫描 → SCRIPT_COVERAGE（builder ↔ op 双射面，",
+    ' *   返回注解 CommandOf<"op"> = 直接词条；不产独立 op 的走补充表）。',
+    " * 手改会在下次重建时被覆盖；改注册表/词条后未重建 =",
+    " * tests/editor/script-vocabulary.test.ts 的生成物新鲜度用例红。",
+    " */",
+    "",
+    "/** op 注册表键快照（与 OP_SCHEMA_MAP 键集恒等；排序保证 diff 稳定） */",
+    "export const VOCABULARY_OPS = [",
+  ];
+  for (const op of [...registryKeys].sort()) {
+    lines.push(`  "${op}",`);
+  }
+  lines.push(
+    "] as const;",
+    "",
+    "/** op 名字面量联合（快照派生，与 ScriptOpName 同键集） */",
+    "export type VocabularyOp = (typeof VOCABULARY_OPS)[number];",
+    "",
+    "/**",
+    " * builder ↔ op 双射面（词汇层互锁守卫的数据源）。",
+    " * `$` 前缀 = 辅助词（不直接产出独立 op）——互锁比较时跳过。",
+    " */",
+    "export const SCRIPT_COVERAGE: Readonly<Record<string, string>> = {",
+  );
+  let lastFile = "";
+  for (const { builder, op, file } of direct) {
+    if (file !== lastFile) {
+      lines.push(`  // —— ${file} ——`);
+      lastFile = file;
+    }
+    lines.push(`  ${builder}: "${op}",`);
+  }
+  lines.push("  // —— 辅助词（补充表登记，不产独立 op） ——");
+  for (const [builder, op] of Object.entries(HELPER_WORDS)) {
+    lines.push(`  ${builder}: "${op}",`);
+  }
+  lines.push("};", "");
+  return lines.join("\n");
+}

package/src/script/vocabulary.g.ts

@@ -0,0 +1,175 @@
+/**
+ * 生成文件：词汇层声明（勿手改）。
+ *
+ * 由 packages/editor/src/script/generate-vocabulary.ts 重建（两个真相源）：
+ * - OP_SCHEMA_MAP 键快照 → VOCABULARY_OPS（op 注册表面的单一来源）；
+ * - words/*.ts 导出函数扫描 → SCRIPT_COVERAGE（builder ↔ op 双射面，
+ *   返回注解 CommandOf<"op"> = 直接词条；不产独立 op 的走补充表）。
+ * 手改会在下次重建时被覆盖；改注册表/词条后未重建 =
+ * tests/editor/script-vocabulary.test.ts 的生成物新鲜度用例红。
+ */
+
+/** op 注册表键快照（与 OP_SCHEMA_MAP 键集恒等；排序保证 diff 稳定） */
+export const VOCABULARY_OPS = [
+  "ambient",
+  "animate",
+  "animate_block",
+  "array",
+  "array_pop",
+  "array_push",
+  "assert",
+  "auto_save",
+  "background",
+  "bg_switch",
+  "bgm",
+  "break",
+  "call",
+  "character",
+  "continue",
+  "cutscene",
+  "define",
+  "dict",
+  "dict_set",
+  "for",
+  "foreach",
+  "func",
+  "guard",
+  "hide",
+  "if",
+  "input",
+  "interaction",
+  "jump",
+  "let",
+  "load",
+  "local",
+  "menu",
+  "minigame",
+  "navigate",
+  "notify",
+  "nvl",
+  "pause",
+  "pause_video",
+  "random",
+  "resume_video",
+  "return",
+  "save",
+  "save_delete",
+  "say",
+  "se",
+  "seek_video",
+  "set",
+  "shake",
+  "show",
+  "stop_ambient",
+  "stop_bgm",
+  "stop_video",
+  "stop_voice",
+  "style",
+  "switch",
+  "text_typewriter",
+  "transition",
+  "uncharacter",
+  "undef",
+  "video",
+  "video_skipable",
+  "voice",
+  "wait",
+  "while",
+  "window",
+  "zindex",
+] as const;
+
+/** op 名字面量联合（快照派生，与 ScriptOpName 同键集） */
+export type VocabularyOp = (typeof VOCABULARY_OPS)[number];
+
+/**
+ * builder ↔ op 双射面（词汇层互锁守卫的数据源）。
+ * `$` 前缀 = 辅助词（不直接产出独立 op）——互锁比较时跳过。
+ */
+export const SCRIPT_COVERAGE: Readonly<Record<string, string>> = {
+  // —— audio.ts ——
+  bgm: "bgm",
+  stopBgm: "stop_bgm",
+  se: "se",
+  ambient: "ambient",
+  stopAmbient: "stop_ambient",
+  voice: "voice",
+  stopVoice: "stop_voice",
+  // —— elements.ts ——
+  show: "show",
+  hide: "hide",
+  background: "background",
+  bgSwitch: "bg_switch",
+  setZ: "zindex",
+  style: "style",
+  dialogWindow: "window",
+  animate: "animate",
+  animateBlock: "animate_block",
+  transition: "transition",
+  shake: "shake",
+  textTypewriter: "text_typewriter",
+  // —— flow.ts ——
+  wait: "wait",
+  pause: "pause",
+  random: "random",
+  jump: "jump",
+  navigate: "navigate",
+  func: "func",
+  call: "call",
+  ret: "return",
+  when: "if",
+  whileDo: "while",
+  forIn: "for",
+  forEach: "foreach",
+  switchOn: "switch",
+  breakLoop: "break",
+  continueLoop: "continue",
+  assert: "assert",
+  guard: "guard",
+  // —— interaction.ts ——
+  interaction: "interaction",
+  // —— minigame.ts ——
+  minigame: "minigame",
+  // —— narrative.ts ——
+  say: "say",
+  menu: "menu",
+  input: "input",
+  notify: "notify",
+  nvl: "nvl",
+  character: "character",
+  uncharacter: "uncharacter",
+  // —— save.ts ——
+  save: "save",
+  load: "load",
+  autoSave: "auto_save",
+  saveDelete: "save_delete",
+  // —— vars.ts ——
+  set: "set",
+  define: "define",
+  letVar: "let",
+  localVar: "local",
+  undef: "undef",
+  newArray: "array",
+  arrayPush: "array_push",
+  arrayPop: "array_pop",
+  dict: "dict",
+  dictSet: "dict_set",
+  // —— video.ts ——
+  video: "video",
+  cutscene: "cutscene",
+  seekVideo: "seek_video",
+  pauseVideo: "pause_video",
+  resumeVideo: "resume_video",
+  stopVideo: "stop_video",
+  videoSkipable: "video_skipable",
+  // —— 辅助词（补充表登记，不产独立 op） ——
+  option: "$menu.option",
+  whenChain: "$if.chain",
+  reward: "$minigame.reward",
+  extOp: "$ext.op",
+  sceneSetup: "$composite.scene",
+  buttonElement: "$composite.button",
+  textElement: "$composite.text",
+  imageElement: "$composite.image",
+  sceneType: "$column.type",
+};