Skip to content

The Open Standard for Generative UI

23.1 KB
Raw Blame
// ─────────────────────────────────────────────────────────────────────────────
// AST evaluator — resolves AST nodes to runtime values.
// Framework-agnostic. No React imports.
// ─────────────────────────────────────────────────────────────────────────────

import type { ASTNode } from "../parser/ast";
import { isASTNode, toLiteralAST } from "../parser/ast";
import {
  ACTION_STEPS,
  BUILTIN_CALLS,
  BUILTIN_STEPS,
  BUILTINS,
  isStep,
  toNumber,
} from "../parser/builtins";
import { nameArgs } from "../parser/materialize";
import type {
  ActionPlan,
  ActionStep,
  ElementNode,
  FunctionSchema,
  JSONSchemaDef,
  MaterializeCtx,
  ParamDef,
} from "../parser/types";
import { isElementNode } from "../parser/types";
import { getSchemaDefaultValue, INVALID, validateSchemaValue } from "../parser/validation";
import { isReactiveSchema } from "../reactive";
import { evaluatePropCore } from "./evaluate-prop";

/** Optional schema context for reactive-aware evaluation. */
export interface SchemaContext {
  /** Component library — used to look up reactive schemas per prop. */
  library: { components: Record<string, { props: { shape?: Record<string, unknown> } }> };
}

export interface EvaluationContext {
  /** Read $variable from the store */
  getState(name: string): unknown;
  /** Resolve a reference to another declaration's evaluated value */
  resolveRef(name: string): unknown;
  /** Extra scope for $value injection during reactive prop evaluation */
  extraScope?: Record<string, unknown>;
  /** Library functions: `library.toJSONSchema().functions` entries plus each `fn`. */
  functions?: Record<string, RuntimeFunction>;
  /** Custom actions: the `library.toJSONSchema().actions` entries. */
  actions?: Record<string, FunctionSchema>;
  /** Reports a runtime error, such as a library function call that evaluated to null. */
  reportError?: (message: string) => void;
}

/** A library function as the evaluator runs it. */
export interface RuntimeFunction extends FunctionSchema {
  fn: (args: any) => unknown;
}

export interface ReactiveAssign {
  __reactive: "assign";
  target: string;
  expr: ASTNode;
}

export function isReactiveAssign(value: unknown): value is ReactiveAssign {
  return typeof value === "object" && value !== null && (value as any).__reactive === "assign";
}

/**
 * Evaluate an AST node to a runtime value.
 */
export function evaluate(
  node: ASTNode,
  context: EvaluationContext,
  schemaCtx?: SchemaContext,
): unknown {
  switch (node.k) {
    // ── Literals ──────────────────────────────────────────────────────────
    case "Str":
      return node.v;
    case "Num":
      return node.v;
    case "Bool":
      return node.v;
    case "Null":
      return null;
    case "Ph":
      return null;

    // ── State references ──────────────────────────────────────────────────
    case "StateRef":
      return context.extraScope?.[node.n] ?? context.getState(node.n);

    // ── References ────────────────────────────────────────────────────────
    case "Ref":
    case "RuntimeRef":
      return context.resolveRef(node.n);

    // ── Collections ───────────────────────────────────────────────────────
    case "Arr":
      return node.els.map((el) => evaluate(el, context));
    case "Obj":
      return Object.fromEntries(node.entries.map(([k, v]) => [k, evaluate(v, context)]));

    // ── Component ─────────────────────────────────────────────────────────
    case "Comp": {
      // Built-ins coerce their args, so they skip validation. Lazy ones get them unevaluated.
      const builtin = BUILTINS[node.name];
      if (builtin) {
        if (builtin.lazy) return evaluateLazyBuiltin(node.name, node.args, context, schemaCtx);
        return builtin.fn!(evaluateArgs(node, context));
      }
      // Built-in steps and Action([...]) → an ActionPlan
      if (isStep(node.name)) return evaluateActionCall(node, context);
      const fns = context.functions;
      if (fns && Object.prototype.hasOwnProperty.call(fns, node.name)) {
        return callFunction(node.name, fns[node.name]!, node, context);
      }
      // Custom actions: a one-step plan; any invalid arg gives an empty plan, a no-op,
      // even an optional one with a default: @ExportFile("r", "xlsx") must not export csv
      const acts = context.actions;
      if (acts && Object.prototype.hasOwnProperty.call(acts, node.name)) {
        const def = acts[node.name]!;
        const args = callArgs(node, context, def.params);
        if (missesRequired(args, def.params)) return { steps: [] };
        const params = checkValue(args, def.params, node.name, "", context, true);
        if (params === INVALID) return { steps: [] };
        const step: ActionStep = {
          type: "custom_action",
          name: node.name,
          params: params as Record<string, unknown>,
        };
        customSteps.add(step);
        return { steps: [step] };
      }
      // If parser already mapped args→props (via materializeExpr), use named props.
      // With schema context: emit ReactiveAssign for StateRef on reactive props.
      // Without schema context: preserve StateRef as AST for evaluate-tree to handle.
      if (node.mappedProps) {
        const def = schemaCtx?.library.components[node.name];
        const props: Record<string, unknown> = {};
        for (const [key, val] of Object.entries(node.mappedProps)) {
          const propSchema = def?.props?.shape?.[key];
          if (val.k === "StateRef" && propSchema && isReactiveSchema(propSchema)) {
            // Reactive schema + StateRef → emit ReactiveAssign marker
            props[key] = {
              __reactive: "assign" as const,
              target: val.n,
              expr: { k: "StateRef" as const, n: "$value" },
            };
          } else if (val.k === "StateRef") {
            // Non-reactive StateRef or no schema context → preserve for evaluate-tree
            props[key] = schemaCtx ? context.getState(val.n) : val;
          } else {
            props[key] = evaluate(val, context, schemaCtx);
          }
        }
        const result: ElementNode = {
          type: "element",
          typeName: node.name,
          props,
          partial: false,
          hasDynamicProps: true,
        };
        // If we have schema context, recursively evaluate nested ElementNodes in props
        if (schemaCtx) {
          for (const [key, val] of Object.entries(props)) {
            if (isElementNode(val)) {
              props[key] = evaluateElementInline(val, context, schemaCtx);
            } else if (Array.isArray(val)) {
              props[key] = val.map((item) =>
                isElementNode(item) ? evaluateElementInline(item, context, schemaCtx) : item,
              );
            }
          }
        }
        return result;
      }
      // After materializeValue, all catalog/unknown components are lowered to
      // ElementNode at parse time. Only builtins and mappedProps Comp nodes
      // reach here. If we somehow get an unmapped Comp, warn and return null.
      console.warn(`[openui] Unexpected unmapped Comp node: ${node.name}`);
      return null;
    }

    // ── Binary operators ──────────────────────────────────────────────────
    case "BinOp": {
      // Short-circuit operators evaluate lazily
      if (node.op === "&&") {
        const left = evaluate(node.left, context);
        return left ? evaluate(node.right, context) : left;
      }
      if (node.op === "||") {
        const left = evaluate(node.left, context);
        return left ? left : evaluate(node.right, context);
      }

      const left = evaluate(node.left, context);
      const right = evaluate(node.right, context);

      switch (node.op) {
        case "+":
          if (typeof left === "string" || typeof right === "string") {
            // Treat null/undefined as "" for string concat to avoid "textnull"
            return String(left ?? "") + String(right ?? "");
          }
          return toNumber(left) + toNumber(right);
        case "-":
          return toNumber(left) - toNumber(right);
        case "*":
          return toNumber(left) * toNumber(right);
        case "/":
          // DSL design choice: division by zero returns 0 instead of JavaScript's Infinity/NaN.
          return toNumber(right) === 0 ? 0 : toNumber(left) / toNumber(right);
        case "%":
          return toNumber(right) === 0 ? 0 : toNumber(left) % toNumber(right);
        case "==":
          // Use loose equality so that e.g. 5 == "5" is true,
          // consistent with the toNumber coercion used by comparison operators.
          return left == right;
        case "!=":
          return left != right;
        case ">":
          return toNumber(left) > toNumber(right);
        case "<":
          return toNumber(left) < toNumber(right);
        case ">=":
          return toNumber(left) >= toNumber(right);
        case "<=":
          return toNumber(left) <= toNumber(right);
        default:
          return null;
      }
    }

    // ── Unary operators ───────────────────────────────────────────────────
    case "UnaryOp":
      if (node.op === "!") {
        return !evaluate(node.operand, context);
      }
      if (node.op === "-") {
        return -toNumber(evaluate(node.operand, context));
      }
      return null;

    // ── Ternary ───────────────────────────────────────────────────────────
    case "Ternary": {
      const cond = evaluate(node.cond, context);
      return cond ? evaluate(node.then, context) : evaluate(node.else, context);
    }

    // ── Member access ─────────────────────────────────────────────────────
    case "Member": {
      const obj = evaluate(node.obj, context) as any;
      if (obj == null) return null;
      // Array pluck: if obj is an array, extract field from every element
      if (Array.isArray(obj)) {
        if (node.field === "length") return obj.length;
        return obj.map((item: any) => item?.[node.field] ?? null);
      }
      return obj[node.field];
    }

    // ── Index access ──────────────────────────────────────────────────────
    case "Index": {
      const obj = evaluate(node.obj, context) as any;
      const idx = evaluate(node.index, context);
      if (obj == null || idx == null) return null;
      if (Array.isArray(obj)) {
        return obj[toNumber(idx)];
      }
      return obj[String(idx)];
    }

    // ── Assignment ────────────────────────────────────────────────────────
    case "Assign":
      return {
        __reactive: "assign" as const,
        target: node.target,
        expr: node.value,
      };
  }
}

/**
 * Strip a ReactiveAssign to its current value in a non-reactive context.
 * When transport args or non-reactive props contain a ReactiveAssign, this
 * resolves it to the current state value (or null if getState is unavailable).
 */
export function stripReactiveAssign(value: unknown, context: EvaluationContext): unknown {
  if (!isReactiveAssign(value)) return value;
  return context.getState(value.target) ?? null;
}

/**
 * Evaluate an ElementNode's props with schema awareness. Used by evaluate()
 * when schema context is available and a Comp produces an ElementNode that
 * needs its own props evaluated with reactive schema detection.
 */
function evaluateElementInline(
  el: ElementNode,
  context: EvaluationContext,
  schemaCtx: SchemaContext,
): ElementNode {
  if (el.hasDynamicProps === false) return el;
  const def = schemaCtx.library.components[el.typeName];
  const evaluated: Record<string, unknown> = {};

  for (const [key, value] of Object.entries(el.props)) {
    const propSchema = def?.props?.shape?.[key];
    evaluated[key] = evaluatePropInline(value, context, schemaCtx, propSchema);
  }
  return { ...el, props: evaluated };
}

/**
 * Evaluate a single prop value with schema awareness.
 * Delegates to shared evaluatePropCore with inline-specific recursion callbacks.
 */
function evaluatePropInline(
  value: unknown,
  context: EvaluationContext,
  schemaCtx: SchemaContext,
  reactiveSchema?: unknown,
): unknown {
  return evaluatePropCore(value, context, schemaCtx, reactiveSchema, {
    recurseElement: (el) => evaluateElementInline(el, context, schemaCtx),
    recurse: (v, rs) => evaluatePropInline(v, context, schemaCtx, rs),
  });
}

// @Percent(done, 10) with done = 3 -> {part: 3, total: 10}
function evaluateArgs(
  node: ASTNode & { k: "Comp" },
  context: EvaluationContext,
  params: ParamDef[] = BUILTIN_CALLS.get(node.name)?.params ?? [],
): Record<string, unknown> {
  // The parser names args in mappedProps; an AST from parseExpression() alone is named here
  const named = node.mappedProps ?? nameArgs(node.args, params);
  const args: Record<string, unknown> = {};
  for (const key in named) args[key] = evaluate(named[key]!, context);
  return args;
}

/** A library function's or action's args; an explicit null for an optional param is omitted, so its default applies. */
function callArgs(
  node: ASTNode & { k: "Comp" },
  context: EvaluationContext,
  params: JSONSchemaDef,
): Record<string, unknown> {
  const names = Object.keys(params.properties ?? {});
  const args = evaluateArgs(
    node,
    context,
    names.map((name) => ({ name, required: false })),
  );
  for (const key in args) {
    if (args[key] === null && !params.required?.includes(key)) delete args[key];
  }
  return args;
}

// returns z.string() but fn gives 5 -> reports "@Percent: ... expects string but got number".
// strict: any reported error gives INVALID instead of falling back to a default.
function checkValue(
  value: unknown,
  schema: unknown,
  name: string,
  path: string,
  context: EvaluationContext,
  strict = false,
): unknown {
  const ctx = { errors: [], partial: false } as unknown as MaterializeCtx;
  const checked = validateSchemaValue(value, schema, name, path, ctx);
  for (const e of ctx.errors) context.reportError?.(`@${name}: ${e.message}`);
  return strict && ctx.errors.length > 0 ? INVALID : checked;
}

// @Percent($p) with $p unset -> null, no error
function missesRequired(args: Record<string, unknown>, params: RuntimeFunction["params"]): boolean {
  return !!params.required?.some(
    (key) => args[key] == null && getSchemaDefaultValue(params.properties?.[key]) === undefined,
  );
}

// @Percent(1, 0) where fn throws -> null, reports "@Percent threw: ..."
function callFunction(
  name: string,
  def: RuntimeFunction,
  node: ASTNode & { k: "Comp" },
  context: EvaluationContext,
): unknown {
  const raw = callArgs(node, context, def.params);
  if (missesRequired(raw, def.params)) return null;
  const args = checkValue(raw, def.params, name, "", context);
  if (args === INVALID) return null;
  let result: unknown;
  try {
    result = def.fn(args);
  } catch (e) {
    context.reportError?.(`@${name} threw: ${e instanceof Error ? e.message : String(e)}`);
    return null;
  }
  if (!def.returns) return result;
  const checked = checkValue(result, def.returns, name, "/returns", context);
  return checked === INVALID ? null : (checked ?? null);
}

/** True for an evaluated action plan (`{ steps: [...] }`). */
export function isActionPlan(value: unknown): value is ActionPlan {
  return (
    typeof value === "object" &&
    value !== null &&
    Array.isArray((value as { steps?: unknown }).steps)
  );
}

/** Flatten plans (and stray step objects) into one plan; other values are dropped. */
function flattenPlans(values: unknown[]): ActionPlan {
  return ownSteps({
    steps: values.flatMap((v): ActionStep[] => {
      if (isActionPlan(v)) return v.steps;
      return v != null && typeof v === "object" && "type" in v ? [v as ActionStep] : [];
    }),
  });
}

/** The custom steps made by real calls; a custom step read from data is not among them. */
const customSteps = new WeakSet<ActionStep>();

/** Drops the custom steps no real call made, so data cannot pose as a custom action. */
export function ownSteps(plan: ActionPlan): ActionPlan {
  const own = (s: ActionStep | null) => s?.type !== "custom_action" || customSteps.has(s);
  return plan.steps.every(own) ? plan : { ...plan, steps: plan.steps.filter(own) };
}

/** A step call is a one-step plan, an invalid step an empty plan; Action([...]) flattens. */
function evaluateActionCall(node: ASTNode & { k: "Comp" }, context: EvaluationContext): ActionPlan {
  const { name, args } = node;
  if (name === "Action") {
    const list = args.length > 0 ? evaluate(args[0], context) : [];
    return flattenPlans(Array.isArray(list) ? list : []);
  }
  const def = BUILTIN_STEPS[name]!;
  const step = def.step ? def.step(evaluateArgs(node, context)) : evaluateLazyStep(name, args);
  return { steps: step ? [step] : [] };
}

/** The steps whose args are refs, read as AST. */
function evaluateLazyStep(name: string, args: ASTNode[]): ActionStep | null {
  switch (name) {
    case "Run": {
      // Run(runtimeRef); an unresolved Ref is invalid
      const refNode = args[0];
      if (refNode?.k !== "RuntimeRef") return null;
      return { type: ACTION_STEPS.Run, statementId: refNode.n, refType: refNode.refType };
    }
    case "Set": {
      // Set($varName, value). valueAST is evaluated at click time by triggerAction;
      // loop variables (e.g. t.id from Each) are pre-resolved by Each's substituteRef.
      if (args.length < 2 || args[0].k !== "StateRef") return null;
      return { type: ACTION_STEPS.Set, target: args[0].n, valueAST: args[1] };
    }
    case "Reset": {
      // Reset($var1, $var2, ...) restores declared defaults at runtime.
      const targets = args
        .filter((a): a is ASTNode & { k: "StateRef" } => a.k === "StateRef")
        .map((a) => a.n);
      if (targets.length === 0) return null;
      return { type: ACTION_STEPS.Reset, targets };
    }
    default:
      return null;
  }
}

/**
 * Substitute all Ref(varName) nodes in an AST tree with a literal value.
 * This pre-resolves loop variables so deferred expressions (like Action steps)
 * don't lose scope when evaluated later at click time.
 */
function substituteRef(node: ASTNode, varName: string, value: unknown): ASTNode {
  switch (node.k) {
    case "Ref":
      return node.n === varName ? toLiteralAST(value) : node;
    case "Member": {
      // Member access on the loop var: t.id → resolve t, then access .id
      if (isASTNode(node.obj)) {
        const subObj = substituteRef(node.obj as ASTNode, varName, value);
        // If obj resolved to a literal, we can inline the member access result
        if (subObj.k === "Obj") {
          const entry = subObj.entries.find(([k]) => k === node.field);
          if (entry) return entry[1];
        }
        return { ...node, obj: subObj };
      }
      return node;
    }
    case "Index":
      return {
        ...node,
        obj: isASTNode(node.obj) ? substituteRef(node.obj as ASTNode, varName, value) : node.obj,
        index: isASTNode(node.index)
          ? substituteRef(node.index as ASTNode, varName, value)
          : node.index,
      };
    case "BinOp":
      return {
        ...node,
        left: substituteRef(node.left, varName, value),
        right: substituteRef(node.right, varName, value),
      };
    case "UnaryOp":
      return { ...node, operand: substituteRef(node.operand, varName, value) };
    case "Ternary":
      return {
        ...node,
        cond: substituteRef(node.cond, varName, value),
        then: substituteRef(node.then, varName, value),
        else: substituteRef(node.else, varName, value),
      };
    case "Arr":
      return { ...node, els: node.els.map((e) => substituteRef(e, varName, value)) };
    case "Obj":
      return {
        ...node,
        entries: node.entries.map(
          ([k, v]) => [k, substituteRef(v, varName, value)] as [string, ASTNode],
        ),
      };
    case "Comp": {
      const sub = (a: ASTNode) => substituteRef(a, varName, value);
      const result = { ...node, args: node.args.map(sub) };
      if (node.mappedProps) result.mappedProps = mapValues(node.mappedProps, sub);
      return result;
    }
    case "Assign":
      return { ...node, value: substituteRef(node.value, varName, value) };
    default:
      return node;
  }
}

function mapValues(
  record: Record<string, ASTNode>,
  fn: (node: ASTNode) => ASTNode,
): Record<string, ASTNode> {
  const out: Record<string, ASTNode> = {};
  for (const key in record) out[key] = fn(record[key]!);
  return out;
}

/**
 * Each(array, varName, template) — evaluate template once per array item.
 * varName is user-defined (e.g. `issue`, `ticket`) — no $ prefix collision.
 *
 * Before evaluation, substitutes all Ref(varName) in the template with the
 * current item's literal value. This ensures deferred expressions (like
 * Action/Set steps) capture concrete values instead of dangling loop refs.
 */
function evaluateLazyBuiltin(
  name: string,
  args: ASTNode[],
  context: EvaluationContext,
  schemaCtx?: SchemaContext,
): unknown {
  if (name === "Each") {
    if (args.length < 3) return [];
    const arr = evaluate(args[0], context);
    if (!Array.isArray(arr)) return [];

    const varName =
      args[1].k === "Ref" ? args[1].n : args[1].k === "Str" ? (args[1] as any).v : null;
    if (!varName) return [];
    const template = args[2];

    return arr.map((item, _idx) => {
      // Pre-substitute loop variable refs with concrete values in the template AST.
      // This captures the item for deferred expressions (Action steps evaluated at click time).
      const substituted = substituteRef(template, varName, item);
      const childCtx: EvaluationContext = {
        ...context,
        resolveRef: (refName: string) => {
          if (refName === varName) return item;
          return context.resolveRef(refName);
        },
      };
      const result = evaluate(substituted, childCtx, schemaCtx);
      // If schema context is available and result is an ElementNode, evaluate its props
      if (schemaCtx && isElementNode(result)) {
        return evaluateElementInline(result as ElementNode, childCtx, schemaCtx);
      }
      return result;
    });
  }
  return null;
}