Skip to content

The Open Standard for Generative UI

17.1 KB
Raw Blame
// ─────────────────────────────────────────────────────────────────────────────
// Schema-aware materialization — single-pass lowering
// ─────────────────────────────────────────────────────────────────────────────

import type { ASTNode } from "./ast";
import { isASTNode, isRuntimeExpr, literalValue, toLiteralAST, walkAST } from "./ast";
import { getCallDefs, isReservedCall, RESERVED_CALLS } from "./builtins";
import { isElementNode, type CallDef, type MaterializeCtx, type ParamDef } from "./types";
import {
  buildParamsSignature,
  INVALID,
  pushValidationIssue,
  resolveInvalidValue,
  validateSchemaValue,
} from "./validation";

/**
 * Recursively check if a prop value contains any AST nodes that need runtime
 * evaluation. Walks into arrays, ElementNode children, and plain objects.
 */
export function containsDynamicValue(v: unknown): boolean {
  if (v == null || typeof v !== "object") return false;
  if (isASTNode(v)) return true;
  if (Array.isArray(v)) return v.some(containsDynamicValue);
  if (isElementNode(v)) {
    return Object.values(v.props).some(containsDynamicValue);
  }
  const obj = v as Record<string, unknown>;
  // A `{steps: [...]}` literal is evaluated too, so data cannot pose as custom action steps
  if (Array.isArray(obj.steps)) return true;
  return Object.values(obj).some(containsDynamicValue);
}

/**
 * Resolve a Ref node: inline from symbol table, detect cycles, emit RuntimeRef
 * for Query/Mutation declarations. Shared by materializeValue and materializeExpr.
 */
function resolveRef(name: string, ctx: MaterializeCtx, mode: "value" | "expr"): unknown | ASTNode {
  if (ctx.visited.has(name)) {
    ctx.unres.push(name);
    return mode === "expr" ? { k: "Ph", n: name } : null;
  }
  if (!ctx.syms.has(name)) {
    ctx.unres.push(name);
    return mode === "expr" ? { k: "Ph", n: name } : null;
  }
  const target = ctx.syms.get(name)!;
  ctx.unreached?.delete(name);
  // Query/Mutation declarations → RuntimeRef (resolved at runtime by evaluator)
  if (target.k === "Comp" && isReservedCall(target.name)) {
    const refType =
      target.name === RESERVED_CALLS.Mutation ? ("mutation" as const) : ("query" as const);
    return { k: "RuntimeRef", n: name, refType };
  }
  ctx.visited.add(name);
  const prevStatementId = ctx.currentStatementId;
  ctx.currentStatementId = name;
  try {
    const result = mode === "value" ? materializeValue(target, ctx) : materializeExpr(target, ctx);
    // Tag ElementNode with its source statement name
    if (mode === "value" && isElementNode(result)) {
      result.statementId = name;
    }
    return result;
  } finally {
    ctx.currentStatementId = prevStatementId;
    ctx.visited.delete(name);
  }
}

/** Registry calls (functions and steps) and reserved calls stay AST for the runtime. */
function isRuntimeCall(name: string, ctx: MaterializeCtx): boolean {
  return getCallDefs(ctx.cat).has(name) || isReservedCall(name);
}

// [Num 1, Ref x] with params [a, b] -> {a: Num 1, b: Ref x}; extra args dropped
export function nameArgs(args: ASTNode[], params: ParamDef[]): Record<string, ASTNode> {
  const named: Record<string, ASTNode> = {};
  for (let i = 0; i < params.length && i < args.length; i++) named[params[i]!.name] = args[i]!;
  return named;
}

// @Percent("x", 4) -> type-mismatch at parse time, call becomes null
export function mapCallArgs(
  name: string,
  args: ASTNode[],
  def: CallDef,
  ctx: MaterializeCtx,
): Record<string, ASTNode> | null {
  const { params } = def;
  if (args.length > params.length) {
    pushValidationIssue(ctx, name, "", {
      code: "excess-args",
      declared: params.length,
      got: args.length,
    });
  }
  const mapped = nameArgs(args, params);
  let invalid = false;
  const errorsBefore = ctx.errors.length;
  for (const p of params) {
    const arg = mapped[p.name];
    const lit = arg ? literalValue(arg) : { v: undefined };
    if (!lit) continue;
    if (lit.v == null) {
      if (!p.required || p.defaultValue !== undefined) continue;
      pushValidationIssue(ctx, name, `/${p.name}`, {
        code: arg ? "null-required" : "missing-required",
        signature: buildParamsSignature(name, params),
      });
      invalid = true;
      continue;
    }
    let next = validateSchemaValue(lit.v, p.schema, name, `/${p.name}`, ctx);
    if (next === INVALID) next = resolveInvalidValue(p.required, p.defaultValue);
    if (next === INVALID) invalid = true;
    else if (next === undefined) delete mapped[p.name];
    else if (next !== lit.v) mapped[p.name] = toLiteralAST(next);
  }
  // An action never runs with a value the model did not write:
  // @ExportFile("report", "xlsx") is a no-op, not an export with the "csv" default
  if (def.kind === "action" && ctx.errors.length > errorsBefore) invalid = true;
  return invalid ? null : mapped;
}

// @Percent(3, total) -> mappedProps {part: Num 3, total: <total AST>}
function materializeCall(
  node: ASTNode & { k: "Comp" },
  ctx: MaterializeCtx,
  materializeArg: (a: ASTNode) => ASTNode,
): ASTNode {
  const args = node.args.map(materializeArg);
  const def = getCallDefs(ctx.cat).get(node.name);
  if (!def || def.lazy) return { ...node, args };
  // Built-ins coerce their args, so only library calls are checked
  const mappedProps = def.builtin
    ? nameArgs(args, def.params)
    : mapCallArgs(node.name, args, def, ctx);
  if (mappedProps) return { ...node, args, mappedProps };
  // An invalid action step is an empty plan, a no-op
  return def.kind === "action"
    ? { k: "Comp", name: "Action", args: [{ k: "Arr", els: [] }] }
    : { k: "Null" };
}

// Query("s", {n: @Count(rows)}): names @Count's args in place.
// Literal library args are checked like props; an invalid call keeps raw names and is null at runtime.
export function nameRawCallArgs(args: ASTNode[], ctx: MaterializeCtx, statementId: string): void {
  const prevStatementId = ctx.currentStatementId;
  ctx.currentStatementId = statementId;
  const seen = new Set<ASTNode>(); // walkAST visits nested calls through args and mappedProps
  for (const arg of args) {
    walkAST(arg, (node) => {
      if (node.k !== "Comp" || seen.has(node)) return;
      seen.add(node);
      const def = getCallDefs(ctx.cat).get(node.name);
      if (!def || def.lazy) return;
      const checked = def.builtin ? null : mapCallArgs(node.name, node.args, def, ctx);
      node.mappedProps = checked ?? nameArgs(node.args, def.params);
    });
  }
  ctx.currentStatementId = prevStatementId;
}

/**
 * If node is a lazy builtin like Each(arr, varName, template), temporarily
 * scope the iterator variable during materialization so template refs resolve.
 * Returns the materialized Comp node, or null if not a lazy builtin.
 */
function materializeLazyBuiltin(
  node: ASTNode & { k: "Comp" },
  ctx: MaterializeCtx,
  scopedRefs: ReadonlySet<string>,
): ASTNode | null {
  const def = getCallDefs(ctx.cat).get(node.name);
  if (def?.kind !== "function" || !def.lazy || node.args.length < 3) return null;
  const varArg = node.args[1];
  const varName = varArg.k === "Ref" ? varArg.n : varArg.k === "Str" ? varArg.v : null;
  if (!varName) return null;

  const nextScopedRefs = new Set(scopedRefs);
  nextScopedRefs.add(varName);
  // Skip args[1] (the iterator declaration) but preserve scoped refs elsewhere.
  const recursedArgs = node.args.map((a, i) =>
    i === 1 ? a : materializeExprInternal(a, ctx, nextScopedRefs),
  );
  return { ...node, args: recursedArgs };
}

function materializeExprInternal(
  node: ASTNode,
  ctx: MaterializeCtx,
  scopedRefs: ReadonlySet<string>,
): ASTNode {
  switch (node.k) {
    case "Ref":
      return scopedRefs.has(node.n) ? node : (resolveRef(node.n, ctx, "expr") as ASTNode);

    case "Ph":
      return node;

    case "Comp": {
      if (node.fn && !isRuntimeCall(node.name, ctx)) {
        pushValidationIssue(ctx, node.name, "", { code: "unknown-function" });
        return { k: "Null" };
      }
      const lazy = materializeLazyBuiltin(node, ctx, scopedRefs);
      if (lazy) return lazy;
      // Built-ins, library functions, action steps, reserved calls: keep as AST
      if (isRuntimeCall(node.name, ctx)) {
        return materializeCall(node, ctx, (a) => materializeExprInternal(a, ctx, scopedRefs));
      }
      const recursedArgs = node.args.map((a) => materializeExprInternal(a, ctx, scopedRefs));
      // Catalog component: add mappedProps for the evaluator
      const def = ctx.cat?.get(node.name);
      if (def) {
        const mappedProps: Record<string, ASTNode> = {};
        for (let i = 0; i < def.params.length && i < recursedArgs.length; i++) {
          mappedProps[def.params[i].name] = recursedArgs[i];
        }
        return { ...node, args: recursedArgs, mappedProps };
      }
      // Unknown component in expression: push error (same as value path)
      pushValidationIssue(ctx, node.name, "", {
        code: "unknown-component",
        available: ctx.cat && [...ctx.cat.keys()],
      });
      return { ...node, args: recursedArgs };
    }

    case "Arr":
      return { ...node, els: node.els.map((e) => materializeExprInternal(e, ctx, scopedRefs)) };
    case "Obj":
      return {
        ...node,
        entries: node.entries.map(
          ([k, v]) => [k, materializeExprInternal(v, ctx, scopedRefs)] as [string, ASTNode],
        ),
      };
    case "BinOp":
      return {
        ...node,
        left: materializeExprInternal(node.left, ctx, scopedRefs),
        right: materializeExprInternal(node.right, ctx, scopedRefs),
      };
    case "UnaryOp":
      return { ...node, operand: materializeExprInternal(node.operand, ctx, scopedRefs) };
    case "Ternary":
      return {
        ...node,
        cond: materializeExprInternal(node.cond, ctx, scopedRefs),
        then: materializeExprInternal(node.then, ctx, scopedRefs),
        else: materializeExprInternal(node.else, ctx, scopedRefs),
      };
    case "Member":
      return { ...node, obj: materializeExprInternal(node.obj, ctx, scopedRefs) };
    case "Index":
      return {
        ...node,
        obj: materializeExprInternal(node.obj, ctx, scopedRefs),
        index: materializeExprInternal(node.index, ctx, scopedRefs),
      };
    case "Assign":
      return { ...node, value: materializeExprInternal(node.value, ctx, scopedRefs) };

    // Literals, StateRef, RuntimeRef — pass through unchanged
    default:
      return node;
  }
}

/**
 * Normalize an AST node for use inside runtime expressions.
 * Resolves Refs, adds mappedProps to catalog Comp nodes.
 * Returns ASTNode — structure preserved for runtime evaluation by the evaluator.
 */
export function materializeExpr(node: ASTNode, ctx: MaterializeCtx): ASTNode {
  return materializeExprInternal(node, ctx, new Set());
}

/**
 * Schema-aware materialization: resolves refs, normalizes catalog component args
 * to named props, validates required props, applies defaults, converts literals
 * to plain values, and preserves runtime expressions as AST nodes — all in a
 * single recursive traversal.
 *
 * Returns:
 *   - ElementNode for catalog/unknown components
 *   - ASTNode for builtins and runtime expression nodes
 *   - Plain values for literals, arrays, objects
 *   - null for placeholders
 */
export function materializeValue(node: ASTNode, ctx: MaterializeCtx): unknown {
  switch (node.k) {
    // ── Ref resolution ───────────────────────────────────────────────────
    case "Ref":
      return resolveRef(node.n, ctx, "value");

    // ── Literals → plain values ──────────────────────────────────────────
    case "Str":
      return node.v;
    case "Num":
      return node.v;
    case "Bool":
      return node.v;
    case "Null":
      return null;
    case "Ph":
      return null;

    // ── Collections ──────────────────────────────────────────────────────
    case "Arr": {
      const items: unknown[] = [];
      for (const e of node.els) {
        // Drop unresolved placeholders from arrays
        if (e.k === "Ph") continue;
        const value = materializeValue(e, ctx);
        // Drop null entries from component/ref resolution (incomplete props, unresolved refs, unknown components)
        if (value === null && (e.k === "Comp" || e.k === "Ref")) continue;
        items.push(value);
      }
      return items;
    }
    case "Obj": {
      const o: Record<string, unknown> = {};
      for (const [k, v] of node.entries) o[k] = materializeValue(v, ctx);
      return o;
    }

    // ── Component nodes ──────────────────────────────────────────────────
    case "Comp": {
      const { name, args } = node;

      if (node.fn && !isRuntimeCall(name, ctx)) {
        pushValidationIssue(ctx, name, "", { code: "unknown-function" });
        return null;
      }

      // Inline Query/Mutation (not from a statement-level declaration) → validation error
      if (isReservedCall(name)) {
        pushValidationIssue(ctx, name, "", { code: "inline-reserved" });
        return null;
      }

      // Built-ins, library functions and action steps → preserve as ASTNode for runtime
      if (isRuntimeCall(name, ctx)) {
        const lazy = materializeLazyBuiltin(node, ctx, new Set());
        if (lazy) return lazy;
        return materializeCall(node, ctx, (a) => materializeExpr(a, ctx));
      }

      const def = ctx.cat?.get(name);
      const props: Record<string, unknown> = {};

      if (def) {
        // Set when a REQUIRED prop holds invalid data with no default to fall
        // back on — the only case where invalidity reaches the component itself.
        let dropComponent = false;
        // Catalog component: map positional args → named props
        for (let i = 0; i < def.params.length && i < args.length; i++) {
          const param = def.params[i];
          const value = materializeValue(args[i], ctx);
          props[param.name] = value;
          if (param.schema === undefined) continue;
          // Single validation entry point: scalar leaf type/enum for simple
          // props, recursive key/type checks (with pruning) for nested shapes.
          let next = validateSchemaValue(value, param.schema, name, `/${param.name}`, ctx);
          if (next === INVALID) {
            // Invalid prop value (error already reported). Same resolution rule as
            // every nested edge; propagation here means dropping the component.
            next = resolveInvalidValue(param.required, param.defaultValue);
            if (next === INVALID) dropComponent = true;
            else if (next === undefined) delete props[param.name];
          }
          if (next !== INVALID && next !== undefined) props[param.name] = next;
        }

        // Report excess positional args (extra args are silently dropped)
        if (args.length > def.params.length) {
          pushValidationIssue(ctx, name, "", {
            code: "excess-args",
            declared: def.params.length,
            got: args.length,
          });
        }

        // Validate required props — try defaultValue first before dropping
        const missingRequired = def.params.filter(
          (p) => p.required && (!(p.name in props) || props[p.name] === null),
        );
        if (missingRequired.length) {
          const stillInvalid = missingRequired.filter((p) => {
            if (p.defaultValue !== undefined) {
              props[p.name] = p.defaultValue;
              return false;
            }
            return true;
          });
          if (stillInvalid.length) {
            for (const p of stillInvalid) {
              pushValidationIssue(ctx, name, `/${p.name}`, {
                code: p.name in props ? "null-required" : "missing-required",
                signature: buildParamsSignature(name, def.params),
              });
            }
            return null;
          }
        }

        // A required prop with unsalvageable data (no default) drops the
        // component — its error was already reported during validation.
        if (dropComponent) return null;
      } else {
        // Unknown component: error and drop from tree
        pushValidationIssue(ctx, name, "", {
          code: "unknown-component",
          available: ctx.cat && [...ctx.cat.keys()],
        });
        return null;
      }

      const hasDynamicProps = Object.values(props).some((v) => containsDynamicValue(v));
      return { type: "element", typeName: name, props, partial: ctx.partial, hasDynamicProps };
    }

    // ── Runtime expression nodes → preserve as ASTNode, normalize children ─
    default: {
      if (isRuntimeExpr(node)) {
        return materializeExpr(node, ctx);
      }
      // Unreachable for well-formed AST, but preserve the value defensively.
      return node;
    }
  }
}