@lingfan-engine/editor 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,370 @@
+/**
+ * 表达式审计：把装配时产出的 token 流按引擎的类型规则判类，违规记入警告池。
+ *
+ * 判类器是一个整体（方法共享游标 `pos` 与警告池），所以实现文件刻意只留一条导入。
+ */
+
+import {
+  BAIL,
+  type AuditToken,
+  type ExpressionWarning,
+  type OperandKind,
+  type VarKind,
+} from "./token.ts";
+import type { EditorTexts } from "../../../contracts/index.ts";
+import { resolveEditorTexts } from "../../../contracts/index.ts";
+
+/**
+ * 递归下降判类器——**优先级链与引擎逐层一致**：`?: → || → && → ==/!= → 比较 →
+ * + - → * / % → 一元 → 成员/调用`。相邻配对会在 `isVIP || gold == 1` 这类
+ * 优先级场景错怪操作数，故必须按结构配对。
+ *
+ * 类型传播口径（与引擎「输入合型 ⇒ 有结果必为输出型」一致）：
+ * - 违规（已知操作数不合运算符要求）⇒ 记警告，结果按 unknown（防连锁噪声）；
+ * - 无违规 ⇒ 结果 = 运算符输出型（算术 num / 比较·相等·逻辑·`!` bool / 一元减 num），
+ *   即使另一侧 unknown——引擎在「不报错」的前提下结果型是确定的。
+ */
+export class ExpressionAuditor {
+  private pos = 0;
+
+  private readonly tokens: readonly AuditToken[];
+  private readonly pending: Array<{
+    rule: ExpressionWarning["rule"];
+    message: string;
+  }>;
+  private readonly texts: EditorTexts;
+
+  constructor(
+    tokens: readonly AuditToken[],
+    pending: Array<{
+      rule: ExpressionWarning["rule"];
+      message: string;
+    }>,
+    texts: Partial<EditorTexts> = {},
+  ) {
+    this.tokens = tokens;
+    this.pending = pending;
+    this.texts = resolveEditorTexts(texts);
+  }
+
+  /** 入口：整体解析一次；任何结构不理解 / 残留 token ⇒ 全部放弃（零误报） */
+  audit(): void {
+    const saved = [...this.pending];
+    try {
+      this.ternary();
+      if (this.pos !== this.tokens.length) throw BAIL;
+    } catch {
+      this.pending.length = 0;
+      this.pending.push(...saved);
+    }
+  }
+
+  private peek(): AuditToken | undefined {
+    return this.tokens[this.pos];
+  }
+
+  private isOp(text: string): boolean {
+    const tok = this.peek();
+    return tok !== undefined && tok.t === "op" && tok.text === text;
+  }
+
+  private isPunct(text: string): boolean {
+    const tok = this.peek();
+    return tok !== undefined && tok.t === "punct" && tok.text === text;
+  }
+
+  private eatOp(text: string): boolean {
+    if (this.isOp(text)) {
+      this.pos += 1;
+      return true;
+    }
+    return false;
+  }
+
+  private describe(operand: { kind: OperandKind; label: string }): string {
+    return `${operand.kind === "unknown" ? this.texts.unknownOperandKind() : operand.kind}「${operand.label}」`;
+  }
+
+  /** 单侧核对：已知操作数必须为 want，否则记警告并返回 true（违规）。note 追加引擎语义注记 */
+  private requireKind(
+    op: string,
+    rule: ExpressionWarning["rule"],
+    side: string,
+    operand: { kind: OperandKind; label: string } | undefined,
+    want: VarKind,
+    note = "",
+  ): boolean {
+    if (operand === undefined || operand.kind === "unknown") return false;
+    if (operand.kind === want) return false;
+    this.pending.push({
+      rule,
+      message: this.texts.operandKindMismatch(
+        op,
+        side,
+        want,
+        this.describe(operand),
+        note,
+      ),
+    });
+    return true;
+  }
+
+  private ternary(): OperandKind {
+    const condKind = this.or();
+    if (!this.isPunct("?")) return condKind;
+    this.pos += 1;
+    const whenTrue = this.ternary();
+    if (!this.isPunct(":")) throw BAIL;
+    this.pos += 1;
+    const whenFalse = this.ternary();
+    let violated = false;
+    if (condKind !== "unknown" && condKind !== "bool") {
+      this.pending.push({
+        rule: "ternary-cond-non-bool",
+        message: this.texts.ternaryCondNotBool(
+          this.describe({ kind: condKind, label: "条件表达式" }),
+        ),
+      });
+      violated = true;
+    }
+    if (violated) return "unknown";
+    return whenTrue !== "unknown" ? whenTrue : whenFalse;
+  }
+
+  private or(): OperandKind {
+    let left = this.and();
+    while (this.eatOp("||")) {
+      const right = this.and();
+      const violated =
+        this.requireKind(
+          "||",
+          "logical-non-bool",
+          "左",
+          { kind: left, label: "左操作数" },
+          "bool",
+        ) ||
+        this.requireKind(
+          "||",
+          "logical-non-bool",
+          "右",
+          { kind: right, label: "右操作数" },
+          "bool",
+          "；右支仅在被求值时检查——'||' 左支为真即短路",
+        );
+      left = violated ? "unknown" : "bool";
+    }
+    return left;
+  }
+
+  private and(): OperandKind {
+    let left = this.equality();
+    while (this.eatOp("&&")) {
+      const right = this.equality();
+      const violated =
+        this.requireKind(
+          "&&",
+          "logical-non-bool",
+          "左",
+          { kind: left, label: "左操作数" },
+          "bool",
+        ) ||
+        this.requireKind(
+          "&&",
+          "logical-non-bool",
+          "右",
+          { kind: right, label: "右操作数" },
+          "bool",
+          "；右支仅在被求值时检查——'&&' 左支为假即短路",
+        );
+      left = violated ? "unknown" : "bool";
+    }
+    return left;
+  }
+
+  /** 相等级：至多一个 ==/!=（引擎不支持链式比较）；仅同类型标量相等 */
+  private equality(): OperandKind {
+    const left = this.comparison();
+    let op: "==" | "!=" | null = null;
+    if (this.eatOp("==")) op = "==";
+    else if (this.eatOp("!=")) op = "!=";
+    if (op === null) return left;
+    const right = this.comparison();
+    if (left !== "unknown" && right !== "unknown" && left !== right) {
+      this.pending.push({
+        rule: "equality-kind-mismatch",
+        message: this.texts.crossTypeComparison(op, left, right),
+      });
+      return "unknown";
+    }
+    return "bool";
+  }
+
+  /** 比较级：至多一个比较符（引擎不支持链式比较）；只支持 number */
+  private comparison(): OperandKind {
+    const left = this.additive();
+    let op: string | null = null;
+    for (const candidate of [">=", "<=", ">", "<"]) {
+      if (this.eatOp(candidate)) {
+        op = candidate;
+        break;
+      }
+    }
+    if (op === null) return left;
+    const right = this.additive();
+    const violated =
+      this.requireKind(
+        op,
+        "compare-non-num",
+        "左",
+        { kind: left, label: "左操作数" },
+        "num",
+      ) ||
+      this.requireKind(
+        op,
+        "compare-non-num",
+        "右",
+        { kind: right, label: "右操作数" },
+        "num",
+      );
+    return violated ? "unknown" : "bool";
+  }
+
+  private additive(): OperandKind {
+    let left = this.multiplicative();
+    for (;;) {
+      const op = this.eatOp("+") ? "+" : this.eatOp("-") ? "-" : null;
+      if (op === null) return left;
+      const right = this.multiplicative();
+      const violated =
+        this.requireKind(
+          op,
+          "arith-non-num",
+          "左",
+          { kind: left, label: "左操作数" },
+          "num",
+        ) ||
+        this.requireKind(
+          op,
+          "arith-non-num",
+          "右",
+          { kind: right, label: "右操作数" },
+          "num",
+        );
+      left = violated ? "unknown" : "num";
+    }
+  }
+
+  private multiplicative(): OperandKind {
+    let left = this.unary();
+    for (;;) {
+      const op = this.eatOp("*")
+        ? "*"
+        : this.eatOp("/")
+          ? "/"
+          : this.eatOp("%")
+            ? "%"
+            : null;
+      if (op === null) return left;
+      const right = this.unary();
+      const violated =
+        this.requireKind(
+          op,
+          "arith-non-num",
+          "左",
+          { kind: left, label: "左操作数" },
+          "num",
+        ) ||
+        this.requireKind(
+          op,
+          "arith-non-num",
+          "右",
+          { kind: right, label: "右操作数" },
+          "num",
+        );
+      left = violated ? "unknown" : "num";
+    }
+  }
+
+  private unary(): OperandKind {
+    if (this.eatOp("!")) {
+      const inner = this.unary();
+      if (
+        this.requireKind(
+          "!",
+          "unary-not-non-bool",
+          "",
+          { kind: inner, label: "操作数" },
+          "bool",
+        )
+      ) {
+        return "unknown";
+      }
+      return "bool";
+    }
+    if (this.eatOp("-")) {
+      const inner = this.unary();
+      if (
+        this.requireKind(
+          "-",
+          "unary-minus-non-num",
+          "",
+          { kind: inner, label: "操作数" },
+          "num",
+        )
+      ) {
+        return "unknown";
+      }
+      return "num";
+    }
+    return this.primary();
+  }
+
+  private primary(): OperandKind {
+    const tok = this.peek();
+    if (tok === undefined) throw BAIL;
+    if (tok.t === "operand") {
+      this.pos += 1;
+      // 函数调用：ident( … ) ⇒ 结果未知（内置函数参数规则不进本层）
+      if (this.isPunct("(")) {
+        this.skipBalancedParens();
+        return "unknown";
+      }
+      // 成员路径：ident.ident … ⇒ 结果未知（字典下钻的值型构建期不可知）
+      if (this.isPunct(".") && tok.kind === "unknown") {
+        while (this.isPunct(".")) {
+          this.pos += 1;
+          const seg = this.peek();
+          if (seg === undefined || seg.t !== "operand") throw BAIL;
+          this.pos += 1;
+        }
+        return "unknown";
+      }
+      return tok.kind;
+    }
+    if (tok.t === "punct" && tok.text === "(") {
+      this.pos += 1;
+      const inner = this.ternary();
+      if (!this.isPunct(")")) throw BAIL;
+      this.pos += 1;
+      return inner;
+    }
+    throw BAIL;
+  }
+
+  /** 括号平衡跳过（函数调用参数整体不判型） */
+  private skipBalancedParens(): void {
+    let depth = 0;
+    for (;;) {
+      const tok = this.peek();
+      if (tok === undefined) throw BAIL;
+      this.pos += 1;
+      if (tok.t === "punct") {
+        if (tok.text === "(") depth += 1;
+        if (tok.text === ")") {
+          depth -= 1;
+          if (depth === 0) return;
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * 判类器使用的词法词汇：装配层产出的 token 流，与「结构不认识」的中止信号。
+ *
+ * `OperandKind` 是判类结果（三种变量种类 + 未知）；注册表侧的两个类型在此转出，
+ * 判类器的实现文件便只需一条导入。
+ */
+
+import type { ExpressionWarning, VarKind } from "../registry.ts";
+
+export type { ExpressionWarning, VarKind };
+
+export type OperandKind = VarKind | "unknown";
+
+export type AuditToken =
+  | {
+      readonly t: "operand";
+      readonly kind: OperandKind;
+      readonly label: string;
+    }
+  | { readonly t: "op"; readonly text: string }
+  | { readonly t: "punct"; readonly text: string };
+
+export const BAIL = Symbol("audit-bail");

package/src/script/expr/build.ts

@@ -0,0 +1,203 @@
+/**
+ * 表达式标签的装配：把模板字面量拼成 `{…}` 文本，插值按句柄与字面量规则渲染。
+ *
+ * 组装同时做构建期轻类型校验（判类器在 `./audit`）：警告进池、由
+ * `drainExpressionWarnings` 取走；表达式产物与既有行为逐字节一致（校验零侵入）。
+ */
+
+import {
+  currentRegistry,
+  isVarHandle,
+  varKeyOf,
+  warningSink,
+  type ExpressionWarning,
+  type VarKind,
+} from "./registry.ts";
+import { ExpressionAuditor, type AuditToken, type OperandKind } from "./audit/index.ts";
+import { defaultEditorTexts } from "../../contracts/index.ts";
+
+/**
+ * expr 标签函数的文案取缺省表（例外登记）：模板标签函数无法携带可选参数注入，
+ * 这四条是构建期开发者诊断（缺省不可变直引，无模块级 setter）。
+ * varKeyOf / ExpressionAuditor 的文案仍走调用点注入。
+ */
+const texts = defaultEditorTexts;
+
+/**
+ * 表达式标签：`expr\`${vars.player.gold} >= 25\` ⇒ "{player.gold >= 25}"`。
+ * 插值规则：VarHandle ⇒ 注册键（未注册抛错）；number/boolean ⇒ 字面量；
+ * string ⇒ JSON 字面量（带引号，与引擎字符串字面量口径一致）。
+ *
+ * 组装同时做轻类型校验（见文件头）：警告进池，由 `drainExpressionWarnings` 取走；
+ * 表达式产物与既有行为逐字节一致（校验零侵入）。
+ *
+ * 产物是 `"{…}"` 表达式串：引擎在**执行到包含它的命令时**求值——
+ * 条件语境（{@link when} / whileDo）求出布尔；赋值语境（{@link set} 等）
+ * 求出值；台词/通知文本在显示时插值。
+ *
+ * 必须先经 defineVars 注册变量，否则抛错。
+ *
+ * @param strings 模板字面量的静态片段。
+ * @param parts 插值：变量句柄 / number / boolean / string。
+ * @returns `"{…}"` 表达式串（放进故事数据，运行期求值）。
+ * @example
+ * expr`${vars.player.gold} >= 25`   // ⇒ "{player.gold >= 25}"
+ * expr`${vars.greeting}, 旅行者`    // string 插值 ⇒ 带引号字面量
+ */
+export function expr(
+  strings: TemplateStringsArray,
+  ...parts: unknown[]
+): string {
+  const registry = currentRegistry;
+  if (registry === null) {
+    throw new Error(texts.exprRequiresDefineVars());
+  }
+  const tokens: AuditToken[] = [];
+  const pending: Array<{ rule: ExpressionWarning["rule"]; message: string }> =
+    [];
+  // 引号状态跨片段/插值跟踪（`"pre${name}post"` 的吞并 footgun：插值会被并进字面量）
+  let quote: string | null = null;
+  let escaped = false;
+
+  /** 片段词法：引号（跨片段）、双字运算符优先、字面量/数字/标识符；括号与结构标点进流 */
+  const lexFragment = (segment: string): void => {
+    for (let i = 0; i < segment.length; i += 1) {
+      const ch = segment[i]!;
+      if (quote !== null) {
+        if (escaped) {
+          escaped = false;
+          continue;
+        }
+        if (ch === "\\") {
+          escaped = true;
+          continue;
+        }
+        if (ch === quote) quote = null;
+        continue;
+      }
+      if (ch === '"' || ch === "'") {
+        quote = ch;
+        tokens.push({ t: "operand", kind: "str", label: "字符串字面量" });
+        continue;
+      }
+      const two = segment.slice(i, i + 2);
+      if (
+        two === "==" ||
+        two === "!=" ||
+        two === "&&" ||
+        two === "||" ||
+        two === ">=" ||
+        two === "<="
+      ) {
+        tokens.push({ t: "op", text: two });
+        i += 1;
+        continue;
+      }
+      if ("+-*/%<>!".includes(ch)) {
+        tokens.push({ t: "op", text: ch });
+        continue;
+      }
+      if ("(),?:.[]".includes(ch)) {
+        tokens.push({ t: "punct", text: ch });
+        continue;
+      }
+      if (/[0-9]/.test(ch)) {
+        let j = i;
+        while (j < segment.length && /[0-9.]/.test(segment[j]!)) j += 1;
+        const literal = segment.slice(i, j);
+        i = j - 1;
+        tokens.push({ t: "operand", kind: "num", label: literal });
+        continue;
+      }
+      if (/[A-Za-z_]/.test(ch)) {
+        let j = i;
+        while (j < segment.length && /[A-Za-z0-9_]/.test(segment[j]!)) j += 1;
+        const word = segment.slice(i, j);
+        i = j - 1;
+        tokens.push(
+          word === "true" || word === "false"
+            ? { t: "operand", kind: "bool", label: word }
+            : { t: "operand", kind: "unknown", label: word },
+        );
+        continue;
+      }
+      // 其余字符（空白等）：词法噪声，不进流
+    }
+  };
+
+  /** 插值贡献（文本 + 判类）：产物文本与既有行为逐字节一致（校验零侵入） */
+  const appendPart = (
+    part: unknown,
+  ): { text: string; kind: OperandKind; label: string } => {
+    if (isVarHandle(part)) {
+      const key = varKeyOf(part, registry, texts);
+      return { text: key, kind: part.kind, label: `变量 ${key}` };
+    }
+    if (typeof part === "number" || typeof part === "boolean") {
+      return {
+        text: String(part),
+        kind: typeof part as VarKind,
+        label: String(part),
+      };
+    }
+    if (typeof part === "string") {
+      return {
+        text: JSON.stringify(part),
+        kind: "str",
+        label: JSON.stringify(part),
+      };
+    }
+    throw new Error(
+      texts.unsupportedInterpolationType(typeof part),
+    );
+  };
+
+  let out = "{";
+  strings.forEach((segment, i) => {
+    lexFragment(segment);
+    out += segment;
+    if (i >= parts.length) return;
+    const part = parts[i];
+    if (quote !== null) {
+      // 校验零侵入：警告照记，但文本照旧并入产物（与既有行为逐字节一致）
+      pending.push({
+        rule: "interpolation-inside-string",
+        message: texts.interpolationInsideString(),
+      });
+      out += appendPart(part).text;
+      return;
+    }
+    const applied = appendPart(part);
+    out += applied.text;
+    tokens.push({ t: "operand", kind: applied.kind, label: applied.label });
+  });
+
+  const finalize = (): string => `${out}}`;
+  if (quote !== null) {
+    // 字面量到表达式末尾都没闭合：引擎将 parse-error——类型核查无意义，只报这一条
+    pending.push({
+      rule: "unclosed-string-literal",
+      message: texts.unclosedStringLiteral(),
+    });
+    warningSink.push(
+      ...pending.map((item) => ({ expression: finalize(), ...item })),
+    );
+    return finalize();
+  }
+  new ExpressionAuditor(tokens, pending, texts).audit();
+  for (const item of pending) {
+    warningSink.push({ expression: finalize(), ...item });
+  }
+  return finalize();
+}
+
+/**
+ * `expr` 的别名（条件语境的语义化写法；同一实现、同一校验）。
+ *
+ * @param strings 模板字面量的静态片段。
+ * @param parts 插值：变量句柄 / number / boolean / string。
+ * @returns `"{…}"` 条件表达式串（引擎执行条件命令时求值，须产出布尔）。
+ * @example
+ * when(cond`${vars.door.locked} == false`, [navigate("hall")]);
+ */
+export const cond = expr;

package/src/script/expr/index.ts

@@ -0,0 +1,17 @@
+/**
+ * 表达式层出口：变量句柄、表达式标签与构建期警告。
+ *
+ * 实现按职责分文件——注册表与句柄、判类器、装配；消费方（`script/index.ts`）
+ * 只从这里取。
+ */
+
+export {
+  defineVars,
+  drainExpressionWarnings,
+  varKeyOf,
+  type ExpressionWarning,
+  type VarHandle,
+  type VarKind,
+  type VarTree,
+} from "./registry.ts";
+export { cond, expr } from "./build.ts";