Skip to content

The Open Standard for Generative UI

16.3 KB
Raw Blame
import { isASTNode } from "./ast";
import {
  isElementNode,
  type ElementNode,
  type MaterializeCtx,
  type ParamDef,
  type ScalarParamType,
} from "./types";

// ─────────────────────────────────────────────────────────────────────────────
// Schema & value introspection
// ─────────────────────────────────────────────────────────────────────────────

/** `typeof` results a scalar/enum leaf can be checked against. */
const SCALAR_TYPEOFS: readonly string[] = ["string", "number", "boolean"];

const NO_PROPS: Record<string, unknown> = {};
const NO_REQUIRED: readonly string[] = [];

function jsType(value: unknown): string {
  return Array.isArray(value) ? "array" : typeof value;
}

/** `{ $ref: "#/$defs/Name" }` → `"Name"`. */
function refName(s: Record<string, unknown>): string | undefined {
  return typeof s["$ref"] === "string" ? s["$ref"].split("/").pop() : undefined;
}

/** Composite shapes can't be reliably matched to a single plain value. */
function isCompositeSchema(s: Record<string, unknown>): boolean {
  return "$ref" in s || "anyOf" in s || "oneOf" in s || "allOf" in s;
}

/** Scalar type/enum info extracted from a JSON Schema leaf, for describeTypeMismatch. */
interface ScalarTypeInfo {
  /** Scalar leaf type, when the property is a plain string/number/boolean. */
  expectedType?: ScalarParamType;
  /** Allowed literal values from `enum`/`const`. */
  enumValues?: readonly unknown[];
}

/** Extract the scalar leaf type/enum from an already-narrowed JSON Schema object. */
export function getScalarTypeInfo(s: Record<string, unknown>): ScalarTypeInfo {
  if (Array.isArray(s["enum"])) return { enumValues: s["enum"] };
  if ("const" in s) return { enumValues: [s["const"]] };
  switch (s["type"]) {
    case "string":
      return { expectedType: "string" };
    case "number":
    case "integer":
      return { expectedType: "number" };
    case "boolean":
      return { expectedType: "boolean" };
    default:
      return {};
  }
}

/** Read a JSON Schema fragment's `default`, if it carries one. */
export function getSchemaDefaultValue(property: unknown): unknown {
  if (!property || typeof property !== "object" || Array.isArray(property)) {
    return undefined;
  }
  return (property as { default?: unknown }).default;
}

/** Returns the expected type for a param from its schema properties */
export function getTypeFromSchema(property: unknown): string | undefined {
  if (!property || typeof property !== "object" || Array.isArray(property)) {
    return undefined;
  }
  const p = property as Record<string, unknown>;
  // $refs and compound types aren't validator-checkable but still make useful hints.
  const ref = refName(p);
  if (ref) return ref;
  // Scalar/enum leaves: share the validator's schema-leaf interpretation so
  // signatures and type-mismatch messages never disagree.
  const leaf = getScalarTypeInfo(p);
  if (leaf.enumValues) {
    return leaf.enumValues.map((v) => JSON.stringify(v)).join("|");
  }
  if (leaf.expectedType) {
    return leaf.expectedType;
  }
  return typeof p.type === "string" ? p.type : undefined;
}

/**
 * Build a typed signature like `Header(title*: string, variant: "a"|"b")` from
 * compiled params — * marks required. Positional order is preserved so an LLM
 * can fix swapped args.
 */
export function buildParamsSignature(component: string, params: ParamDef[]): string {
  const rendered = params
    .map((p) => {
      const type = getTypeFromSchema(p.schema);
      const marked = p.required ? `${p.name}*` : p.name;
      return type ? `${marked}: ${type}` : marked;
    })
    .join(", ");
  return `${component}(${rendered})`;
}

/** Checks a param's returned value against its expected value */
function checkTypeMismatch(
  value: unknown,
  info: ScalarTypeInfo,
): { expected: string; actual: string } | null {
  const actual = typeof value;
  if (info.enumValues) {
    if (!SCALAR_TYPEOFS.includes(actual)) return null;
    if (info.enumValues.includes(value)) return null;
    return {
      expected: `one of [${info.enumValues.map((v) => JSON.stringify(v)).join(", ")}]`,
      actual: JSON.stringify(value),
    };
  }
  if (info.expectedType && info.expectedType !== actual) {
    return { expected: info.expectedType, actual: jsType(value) };
  }
  return null;
}

// ─────────────────────────────────────────────────────────────────────────────
// Errors
// ─────────────────────────────────────────────────────────────────────────────

/**
 * A structured validation issue. Every error of a kind reads identically
 * because its message template lives in validationMessage — call sites only
 * supply the varying parts.
 */
export type ValidationIssue =
  | { code: "type-mismatch"; expected: string; actual: string }
  | { code: "missing-required"; signature?: string }
  | { code: "null-required"; signature?: string }
  | { code: "unknown-component"; available?: string[] }
  | { code: "inline-reserved" }
  | { code: "excess-args"; declared: number; got: number }
  | { code: "unknown-function" }
  | { code: "no-root"; reason: "missing" | "not-component" | "fallback" };

function validationMessage(component: string, path: string, issue: ValidationIssue): string {
  switch (issue.code) {
    case "type-mismatch":
      return `field "${path}" expects ${issue.expected} but got ${issue.actual}`;
    case "missing-required":
      return `missing required field "${path}"${issue.signature ? ` — signature: ${issue.signature}` : ""}`;
    case "null-required":
      return `required field "${path}" cannot be null${issue.signature ? ` — signature: ${issue.signature}` : ""}`;
    case "unknown-component":
      return `Unknown component "${component}" — not found in catalog or builtins${issue.available?.length ? `. Available components: ${issue.available.join(", ")}` : ""}`;
    case "inline-reserved":
      return `${component}() must be declared as a top-level statement, not used inline as a value`;
    case "excess-args":
      return `${component} takes ${issue.declared} arg(s), got ${issue.got} (${issue.got - issue.declared} excess dropped)`;
    case "unknown-function":
      return `Unknown function "@${component}": not a built-in or action step. The call evaluates to null`;
    case "no-root":
      if (issue.reason === "not-component") return "root does not evaluate to a component";
      if (issue.reason === "fallback") {
        return `No root statement. Rendering the first statement that calls the root component ${component}`;
      }
      return component
        ? `No root statement, and no statement calls the root component ${component}`
        : "No root statement";
  }
}

/** Append a validation error, deriving its message from the structured issue. */
export function pushValidationIssue(
  ctx: MaterializeCtx,
  component: string,
  path: string,
  issue: ValidationIssue,
): void {
  ctx.errors.push({
    code: issue.code,
    component,
    path,
    message: validationMessage(component, path, issue),
    statementId: ctx.currentStatementId,
    ...(issue.code === "no-root" &&
      issue.reason === "fallback" && { severity: "warning" as const }),
  });
}

// ─────────────────────────────────────────────────────────────────────────────
// Invalid-value resolution — the edge rule
// ─────────────────────────────────────────────────────────────────────────────

// "x" against {type: "number"} -> INVALID, after reporting the type-mismatch
export const INVALID: unique symbol = Symbol("invalid");

// invalid value: default 5 -> 5; no default -> INVALID if required, else undefined (omit)
export function resolveInvalidValue(required: boolean, defaultValue: unknown): unknown {
  if (defaultValue !== undefined) return defaultValue;
  return required ? INVALID : undefined;
}

// ─────────────────────────────────────────────────────────────────────────────
// Validators — one per schema shape, dispatched by validateSchemaValue
// ─────────────────────────────────────────────────────────────────────────────

/**
 * Position check for a component element in a data slot: slots that admit
 * components ($ref / anyOf / oneOf members) are left unchecked, a slot
 * declaring a plain-data shape can never be satisfied by a component, and
 * unconstrained slots stay conservative.
 */
function validateElementPosition(
  element: ElementNode,
  s: Record<string, unknown>,
  component: string,
  path: string,
  ctx: MaterializeCtx,
): boolean {
  if (isCompositeSchema(s)) return false;
  if (typeof s["type"] === "string" || Array.isArray(s["enum"]) || "const" in s) {
    pushValidationIssue(ctx, component, path, {
      code: "type-mismatch",
      expected: typeof s["type"] === "string" ? s["type"] : "a literal value",
      actual: `component "${element.typeName}"`,
    });
    return true;
  }
  return false;
}

/** The `$ref` names a slot allows: one for `$ref`, several for anyOf/oneOf. */
function slotRefNames(s: Record<string, unknown>): (string | undefined)[] {
  return ((s["anyOf"] ?? s["oneOf"] ?? [s]) as Record<string, unknown>[]).map(refName);
}

/** True when every option of the slot is a `$ref` to a component. */
function isOnlyComponentSlot(s: Record<string, unknown>, ctx: MaterializeCtx): boolean {
  const names = slotRefNames(s);
  return names.length > 0 && names.every((n) => n !== undefined && ctx.cat?.has(n));
}

/**
 * Validate an object-shaped slot: container type, required keys (absent/null
 * ones fill silently from their schema default), then each declared property
 * recursively, resolving invalid children via the edge rule. Copies the object
 * only when a key changes.
 */
function validateObjectValue(
  value: unknown,
  s: Record<string, unknown>,
  component: string,
  path: string,
  ctx: MaterializeCtx,
): unknown {
  if (typeof value !== "object" || Array.isArray(value)) {
    pushValidationIssue(ctx, component, path, {
      code: "type-mismatch",
      expected: "object",
      actual: jsType(value),
    });
    return INVALID;
  }
  const obj = value as Record<string, unknown>;
  let out: Record<string, unknown> | undefined;
  const props =
    s["properties"] && typeof s["properties"] === "object"
      ? (s["properties"] as Record<string, unknown>)
      : NO_PROPS;
  const required = Array.isArray(s["required"]) ? (s["required"] as string[]) : NO_REQUIRED;
  let invalid = false;
  // Structural checks are streaming-sensitive — only run on complete input.
  if (!ctx.partial) {
    for (const key of required) {
      const present = key in obj;
      if (!present || obj[key] == null) {
        const fallback = getSchemaDefaultValue(props[key]);
        if (fallback !== undefined) {
          (out ??= { ...obj })[key] = fallback;
          continue;
        }
        pushValidationIssue(ctx, component, `${path}/${key}`, {
          code: present ? "null-required" : "missing-required",
        });
        invalid = true;
      }
    }
  }
  for (const key of Object.keys(props)) {
    if (!(key in obj)) continue;
    const sub = props[key];
    let next = validateSchemaValue(obj[key], sub, component, `${path}/${key}`, ctx);
    if (next === INVALID) {
      next = resolveInvalidValue(required.includes(key), getSchemaDefaultValue(sub));
      if (next === INVALID) {
        invalid = true;
        continue;
      }
    }
    if (next === obj[key]) continue;
    out ??= { ...obj };
    if (next === undefined) delete out[key];
    else out[key] = next;
  }
  return invalid ? INVALID : (out ?? obj);
}

/**
 * Validate an array slot. Invalid items are pruned; error paths keep the
 * original indices. Copies the array only when an item changes.
 */
function validateArrayValue(
  value: unknown,
  s: Record<string, unknown>,
  component: string,
  path: string,
  ctx: MaterializeCtx,
): unknown {
  if (!Array.isArray(value)) {
    pushValidationIssue(ctx, component, path, {
      code: "type-mismatch",
      expected: "array",
      actual: jsType(value),
    });
    return INVALID;
  }
  const items = s["items"];
  if (!items || typeof items !== "object" || Array.isArray(items)) return value;
  let out: unknown[] | undefined;
  for (let i = 0; i < value.length; i++) {
    const next = validateSchemaValue(value[i], items, component, `${path}/${i}`, ctx);
    if (next !== value[i] && !out) out = value.slice(0, i);
    if (out && next !== INVALID) out.push(next);
  }
  return out ?? value;
}

/**
 * Validate a scalar/enum leaf. Enum membership defers while streaming — a
 * partial literal may still complete toward a valid member; scalar type
 * checks stay on (a wrong type won't become right with more input).
 */
function validateLeafValue(
  value: unknown,
  s: Record<string, unknown>,
  component: string,
  path: string,
  ctx: MaterializeCtx,
): boolean {
  const leaf = getScalarTypeInfo(s);
  if (leaf.expectedType == null && leaf.enumValues == null) return false;
  if (leaf.enumValues && ctx.partial) return false;
  const mismatch = checkTypeMismatch(value, leaf);
  if (mismatch) {
    pushValidationIssue(ctx, component, path, { code: "type-mismatch", ...mismatch });
    return true;
  }
  return false;
}

/**
 * Recursively validate a materialized value against a JSON Schema fragment.
 * Dispatches on the schema shape: objects and arrays descend recursively
 * (reporting nested errors with JSON-pointer paths), leaf scalars check
 * type/enum, and component elements get a position check only (their own args
 * validate separately).
 *
 * Every violation is reported, then the same rule (resolveInvalidValue)
 * applies at each recursion edge: schema default → substitute; REQUIRED edge →
 * parent invalid, caller repeats one level up; OPTIONAL edge → prune. ARRAY
 * ITEMS are always pruned. Absent/null required keys fill silently from their
 * schema default; reported violations keep their error even when a default steps in.
 *
 * Never mutates: returns the value itself when nothing changes, a cleaned copy
 * when something does, or INVALID.
 */
export function validateSchemaValue(
  value: unknown,
  schema: unknown,
  component: string,
  path: string,
  ctx: MaterializeCtx,
): unknown {
  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return value;
  const s = schema as Record<string, unknown>;
  // Absence is handled by required checks on the parent; skip null/undefined.
  if (value == null) return value;
  // Dynamic runtime expressions ($var, builtins) resolve later — don't flag.
  if (isASTNode(value)) return value;
  // Child components: only their position is checked here.
  if (isElementNode(value)) {
    return validateElementPosition(value, s, component, path, ctx) ? INVALID : value;
  }
  if (isCompositeSchema(s)) {
    // Data (an object, array, string, number or boolean) in a component-only slot is invalid.
    if (!isOnlyComponentSlot(s, ctx)) return value;
    pushValidationIssue(ctx, component, path, {
      code: "type-mismatch",
      expected: slotRefNames(s).join(" | "),
      actual: Array.isArray(value)
        ? "array"
        : typeof value === "object"
          ? "plain object"
          : typeof value,
    });
    return INVALID;
  }

  const type = s["type"];
  if (type === "object") return validateObjectValue(value, s, component, path, ctx);
  if (type === "array") return validateArrayValue(value, s, component, path, ctx);
  return validateLeafValue(value, s, component, path, ctx) ? INVALID : value;
}