表达式语言与运行时

表达式的消费点：
  表单：visibleWhen / requiredWhen / defaultValue / optionsFilter
  表格：列显隐、行样式、单元格格式化
  流程：gateway 条件、任务分配规则、超时策略
  集成：URL 拼接、请求体映射、结果断言
  权限：数据行级过滤条件

共同特征：
  短小（通常一行）
  声明式（无副作用）
  需要被平台静态分析（依赖、类型）

type TokenType = 'num' | 'str' | 'ident' | 'op' | 'punc';
interface Token { t: TokenType; v: string; pos: number }

// Pratt 解析：用绑定力（binding power）统一处理优先级与结合性
const BP: Record<string, number> = {
  '||': 1, '??': 1,
  '&&': 2,
  '==': 3, '!=': 3,
  '>': 4, '<': 4, '>=': 4, '<=': 4,
  '+': 5, '-': 5,
  '*': 6, '/': 6, '%': 6,
};

function parseBinary(lhs: Node, minBp: number): Node {
  for (;;) {
    const op = peekOp();
    const bp = op ? BP[op] : 0;
    if (!bp || bp < minBp) return lhs;
    next();
    const rhs = parseBinary(parseUnary(), bp + 1);  // 左结合
    lhs = { k: 'binary', op, l: lhs, r: rhs };
  }
}

type Node =
  | { k: 'lit'; v: unknown }
  | { k: 'ref'; path: string[] }              // form.amount
  | { k: 'unary'; op: string; x: Node }
  | { k: 'binary'; op: string; l: Node; r: Node }
  | { k: 'cond'; c: Node; t: Node; f: Node }  // a ? b : c
  | { k: 'member'; o: Node; key: string; optional: boolean }
  | { k: 'call'; name: string; args: Node[] }
  | { k: 'arr'; items: Node[] }
  | { k: 'obj'; entries: Array<[string, Node]> };

function evalNode(n: Node, scope: Scope): unknown {
  switch (n.k) {
    case 'lit': return n.v;
    case 'ref': return scope.get(n.path);
    case 'member': {
      const o = evalNode(n.o, scope);
      if (o == null) return n.optional ? undefined : fail('NULL_MEMBER', n);
      return readProp(o, n.key);          // 白名单读取，见第 7 节
    }
    case 'unary': return UNARY[n.op](evalNode(n.x, scope));
    case 'binary': return evalBinary(n, scope);
    case 'cond': return truthy(evalNode(n.c, scope))
      ? evalNode(n.t, scope) : evalNode(n.f, scope);
    case 'call': return callFn(n.name, n.args.map((a) => evalNode(a, scope)));
    case 'arr': return n.items.map((i) => evalNode(i, scope));
    case 'obj': return Object.fromEntries(n.entries.map(([k, v]) => [k, evalNode(v, scope)]));
  }
}

function collectDeps(n: Node, out = new Set<string>()): Set<string> {
  switch (n.k) {
    case 'ref': out.add(n.path.join('.')); break;
    case 'member': collectDeps(n.o, out); break;
    case 'unary': collectDeps(n.x, out); break;
    case 'binary': collectDeps(n.l, out); collectDeps(n.r, out); break;
    case 'cond':
      collectDeps(n.c, out); collectDeps(n.t, out); collectDeps(n.f, out); break;
    case 'call': n.args.forEach((a) => collectDeps(a, out)); break;
    case 'arr': n.items.forEach((i) => collectDeps(i, out)); break;
    case 'obj': n.entries.forEach(([, v]) => collectDeps(v, out)); break;
  }
  return out;
}

类型来源：
  1. 数据模型：form.amount 的类型来自字段定义
  2. 内置函数表：函数签名声明参数与返回类型
  3. 推断：字面量、二元运算的结果类型、三元合并
  4. 标注：允许显式 as 断言（谨慎使用）

interface FnSig { params: Type[]; ret: Type; variadic?: boolean }

const FUNCTIONS: Record<string, FnSig> = {
  len:   { params: ['string|array'], ret: 'number' },
  round: { params: ['number', 'number?'], ret: 'number' },
  upper: { params: ['string'], ret: 'string' },
  sum:   { params: ['array'], ret: 'number' },
  now:   { params: [], ret: 'datetime' },
};

错误分类与提示策略：
  语法错误     → 位置 + 期望 token（"第 12 列：期望 ) 但得到 }"）
  未知标识符   → 拼写建议（编辑距离最近的字段名）
  类型不匹配   → 期望类型 vs 实际类型
  空值成员访问 → 提示使用 ?. 或先判空
  函数参数错误 → 哪个参数、期望几个

class ExprError extends Error {
  constructor(
    public code: string,
    message: string,
    public span: [number, number],
    public suggestion?: string,
  ) { super(message); }
}

const BLOCKED = new Set(['__proto__', 'constructor', 'prototype']);

function readProp(obj: unknown, key: string): unknown {
  if (BLOCKED.has(key)) throw new ExprError('UNSAFE_PROP', `禁止访问 ${key}`, [0, 0]);
  if (typeof obj !== 'object' || obj === null) return undefined;
  const v = (obj as Record<string, unknown>)[key];
  return typeof v === 'function' ? undefined : v;   // 不把函数引用交出去
}

安全规则清单：
  1. 函数白名单：只有 FUNCTIONS 表里的名字可调用
  2. 属性读取走 readProp：拦原型链、不返回函数引用
  3. 禁止动态下标：obj[expr] 只允许字面量键
  4. 步数/超时上限：防止在超大集合上做昂贵运算
  5. 不暴露宿主对象：作用域里只有纯数据

class Scope {
  private steps = 0;
  tick() {
    if (++this.steps > 10_000) throw new ExprError('TIMEOUT', '表达式执行超时', [0, 0]);
  }
}

决策建议：
  元数据层（显隐、校验、分支、参数映射）→ 自研 DSL
  中等复杂度数据变换 → 引入 JSONata 这类成熟库，但限制其函数集
  复杂业务逻辑 → 不要在表达式里硬写，退回自定义代码

const astCache = new Map<string, Node>();

function compileCached(src: string, langVersion: number): Node {
  const key = `${langVersion}:${src}`;
  let ast = astCache.get(key);
  if (!ast) {
    ast = parse(src);            // 解析是 O(n)，求值是 O(节点数)
    astCache.set(key, ast);
    if (astCache.size > 5_000) astCache.clear();   // 简单 LRU 兜底
  }
  return ast;
}

兼容策略：
  1. 语法只增不减：新增运算符/函数，不移除
  2. 函数表按平台版本注入，旧版本环境不加载新函数
  3. 表达式保存时记录 langVersion，求值器按版本分派
  4. 弃用先告警：先在使用处标黄，两个大版本后再移除
  5. 语义变更必须当成破坏性变更，走迁移工具