@uicast/core 0.0.1-beta.1 → 0.0.1-beta.2

package/src/expr/analyze.ts

@@ -1,190 +0,0 @@
-import type * as acorn from "acorn";
-import { childNodes } from "./ast-utils";
-
-// Static analysis of a parsed expression (not the security check — that's
-// validate.ts). Two things the renderer needs: whether the expr is async
-// (containsAwait), and which scopes.X.Y paths it reads (extractScopeReads), so it
-// can subscribe without the LLM writing a deps array.
-
-/** Does the expression `await` anything? */
-export function containsAwait(node: acorn.AnyNode | null | undefined): boolean {
-  if (!node || typeof node !== "object") return false;
-  if (node.type === "AwaitExpression") return true;
-  for (const child of childNodes(node)) {
-    if (containsAwait(child)) return true;
-  }
-  return false;
-}
-
-// Collect every static scopes.X.Y chain the expression reads, stopping at the
-// first dynamic segment (computed key, call, non-identifier property). A method
-// call drops its last segment (rows.filter(...) depends on rows, not .filter).
-// The test file pins the trickier cases.
-
-// Read a member chain into its identifier segments (`a.b.c` -> ["a","b","c"]), or
-// null if it hits a computed / non-identifier segment.
-function collectChain(node: acorn.AnyNode | null | undefined): string[] | null {
-  const parts: string[] = [];
-  let cur: acorn.AnyNode | null | undefined = node;
-  while (cur) {
-    if (cur.type === "MemberExpression") {
-      if (cur.computed) return null;
-      const prop = cur.property;
-      if (prop.type !== "Identifier") return null;
-      parts.unshift(prop.name);
-      cur = cur.object;
-    } else if (cur.type === "Identifier") {
-      parts.unshift(cur.name);
-      return parts;
-    } else {
-      return null;
-    }
-  }
-  return null;
-}
-
-// A computed key can read scopes itself (`scopes.x[scopes.y]`), so walk the
-// computed parts of a chain too.
-function walkComputedKeysWithin(memberExpr: acorn.AnyNode, out: Set<string>): void {
-  let cur: acorn.AnyNode = memberExpr;
-  while (cur.type === "MemberExpression") {
-    if (cur.computed) {
-      walkScopeReads(cur.property, out);
-    }
-    cur = cur.object;
-  }
-}
-
-// The recursive walker behind extractScopeReads().
-function walkScopeReads(
-  node: acorn.AnyNode | null | undefined,
-  out: Set<string>,
-): void {
-  if (!node || typeof node !== "object") return;
-
-  // A method call depends on the chain, not the method name — record the chain
-  // without the method, then recurse args.
-  if (node.type === "CallExpression") {
-    const callee = node.callee;
-    if (callee.type === "MemberExpression" && !callee.computed) {
-      const chain = collectChain(callee.object);
-      if (chain && chain[0] === "scopes" && chain.length > 1) {
-        out.add(chain.join("."));
-        walkComputedKeysWithin(callee.object, out);
-      } else {
-        walkScopeReads(callee.object, out);
-      }
-    } else {
-      walkScopeReads(callee, out);
-    }
-    for (const arg of node.arguments) {
-      walkScopeReads(arg, out);
-    }
-    return;
-  }
-
-  // A plain member read: take the chain if it's rooted at `scopes`.
-  if (node.type === "MemberExpression") {
-    const chain = collectChain(node);
-    if (chain && chain[0] === "scopes" && chain.length > 1) {
-      out.add(chain.join("."));
-      walkComputedKeysWithin(node, out);
-      return;
-    }
-    // Not a scopes chain (or it hit a computed segment) — recurse for nested reads.
-    walkScopeReads(node.object, out);
-    if (node.computed) {
-      walkScopeReads(node.property, out);
-    }
-    return;
-  }
-
-  for (const child of childNodes(node)) {
-    walkScopeReads(child, out);
-  }
-}
-
-export function extractScopeReads(ast: acorn.AnyNode): string[] {
-  const out = new Set<string>();
-  walkScopeReads(ast, out);
-  return [...out];
-}
-
-// Free identifiers — names read from the outer scope (globals + injected
-// context). Anything bound by a param, destructuring, or a local declaration
-// stays internal and is not reported.
-function bindPattern(
-  node: acorn.AnyNode | null | undefined,
-  scope: Set<string>,
-): void {
-  if (!node) return;
-  if (node.type === "Identifier") {
-    scope.add(node.name);
-  } else if (node.type === "ObjectPattern") {
-    for (const p of node.properties)
-      bindPattern(p.type === "RestElement" ? p.argument : p.value, scope);
-  } else if (node.type === "ArrayPattern") {
-    for (const el of node.elements) if (el) bindPattern(el, scope);
-  } else if (node.type === "AssignmentPattern") {
-    bindPattern(node.left, scope);
-  } else if (node.type === "RestElement") {
-    bindPattern(node.argument, scope);
-  }
-}
-
-function isBound(name: string, stack: Set<string>[]): boolean {
-  for (let i = stack.length - 1; i >= 0; i--)
-    if (stack[i].has(name)) return true;
-  return false;
-}
-
-function walkFree(
-  node: acorn.AnyNode | null | undefined,
-  stack: Set<string>[],
-  out: Set<string>,
-): void {
-  if (!node || typeof node !== "object") return;
-
-  switch (node.type) {
-    case "Identifier":
-      if (!isBound(node.name, stack)) out.add(node.name);
-      return;
-    case "MemberExpression":
-      walkFree(node.object, stack, out);
-      if (node.computed) walkFree(node.property, stack, out);
-      return;
-    case "Property":
-      if (node.computed) walkFree(node.key, stack, out);
-      walkFree(node.value, stack, out);
-      return;
-    case "VariableDeclarator":
-      bindPattern(node.id, stack[stack.length - 1]);
-      walkFree(node.init, stack, out);
-      return;
-    case "ArrowFunctionExpression":
-    case "FunctionExpression": {
-      const scope = new Set<string>();
-      if (node.type === "FunctionExpression" && node.id)
-        scope.add(node.id.name);
-      for (const p of node.params) bindPattern(p, scope);
-      const inner = [...stack, scope];
-      for (const p of node.params) walkFree(p, inner, out);
-      walkFree(node.body, inner, out);
-      return;
-    }
-    case "CatchClause": {
-      const scope = new Set<string>();
-      if (node.param) bindPattern(node.param, scope);
-      walkFree(node.body, [...stack, scope], out);
-      return;
-    }
-  }
-
-  for (const child of childNodes(node)) walkFree(child, stack, out);
-}
-
-export function extractFreeIdentifiers(ast: acorn.AnyNode): string[] {
-  const out = new Set<string>();
-  walkFree(ast, [new Set()], out);
-  return [...out];
-}

package/src/expr/ast-utils.ts

@@ -1,28 +0,0 @@
-import type * as acorn from "acorn";
-
-// Low-level acorn-AST helpers shared by validate.ts and analyze.ts. NOT a parser
-// — acorn parses; these are a node type-guard and a child-traversal helper.
-
-/** Runtime guard: does `x` look like an AST node (object with a string `type`)? */
-export function isNode(x: unknown): x is acorn.AnyNode {
-  return (
-    typeof x === "object" &&
-    x !== null &&
-    typeof (x as { type?: unknown }).type === "string"
-  );
-}
-
-// Direct child nodes, flattening array-valued fields — for key-agnostic walks.
-export function childNodes(node: acorn.AnyNode): acorn.AnyNode[] {
-  const out: acorn.AnyNode[] = [];
-  for (const value of Object.values(
-    node as unknown as Record<string, unknown>,
-  )) {
-    if (Array.isArray(value)) {
-      for (const child of value) if (isNode(child)) out.push(child);
-    } else if (isNode(value)) {
-      out.push(value);
-    }
-  }
-  return out;
-}

package/src/expr/evaluate.ts

@@ -1,74 +0,0 @@
-import type { StandardToolV0 } from "standard-tool";
-import type { ValueSource } from "../types";
-import { EntryError } from "../entry-error";
-import { ALLOWED_GLOBALS } from "./globals";
-import { SaferEval, SaferEvalError } from "./safer-eval";
-
-const saferEval = new SaferEval({
-  allowGlobals: ALLOWED_GLOBALS,
-  enforceAllowlist: true,
-});
-
-// Every scopes.X.Y path an expression reads, via the shared SaferEval singleton
-// (so extractDeps doesn't reach into the evaluator). Same parse cache as eval().
-export const getScopeReads = (expr: string): string[] =>
-  saferEval.scopeReads(expr);
-
-// Classify an evaluation failure by provenance: SaferEval's own rejections
-// carry their reason (syntax / policy / unknown identifier); an EntryError
-// passes through (a host function already tagged it); anything else threw
-// while the compiled expression ran.
-const wrapEvalError = (err: unknown): EntryError => {
-  if (EntryError.is(err)) return err;
-  if (err instanceof SaferEvalError) return EntryError.wrap(err, err.reason);
-  return EntryError.wrap(err, "expression-runtime");
-};
-
-// Evaluate a ValueSource: a `literal` is returned as-is, an `expr` runs through
-// SaferEval against context + host functions. Returns unknown — an async expr
-// resolves to a Promise (callers check `value instanceof Promise`). `functions`
-// (a StandardToolV0[]) are spread after context, so a host fn wins a name clash.
-// Every failure surfaces as a classified EntryError.
-export const evaluate = (
-  expr: ValueSource,
-  context: Record<string, unknown>,
-  options?: { functions?: StandardToolV0[]; allowedGlobals?: string[] },
-): unknown => {
-  if ("literal" in expr) return expr.literal;
-  if (!expr.expr) return null;
-  const functions = Object.fromEntries(
-    (options?.functions ?? []).map((tool) => [
-      tool.name,
-      // This closure is the engine/host boundary: anything escaping
-      // `tool.execute` is host code failing — unless the host already threw a
-      // classified EntryError itself (e.g. "invalid-arguments"), which wrap()
-      // passes through.
-      (input: unknown) => {
-        try {
-          const result = tool.execute(input);
-          return result instanceof Promise
-            ? result.catch((err) => {
-                throw EntryError.wrap(err, "host-function");
-              })
-            : result;
-        } catch (err) {
-          throw EntryError.wrap(err, "host-function");
-        }
-      },
-    ]),
-  );
-  try {
-    const result = saferEval.eval(
-      expr.expr,
-      { ...context, ...functions },
-      options?.allowedGlobals,
-    );
-    return result instanceof Promise
-      ? result.catch((err) => {
-          throw wrapEvalError(err);
-        })
-      : result;
-  } catch (err) {
-    throw wrapEvalError(err);
-  }
-};

package/src/expr/extract-deps.ts

@@ -1,32 +0,0 @@
-import { type ComponentEntry, isComponentListEntry } from "../types";
-import { getScopeReads } from "./evaluate";
-
-// Entries are immutable, so cached reads never go stale; WeakMap so a dropped
-// entry can be collected.
-const cache = new WeakMap<ComponentEntry, string[]>();
-
-// The reactive scopes.X.Y paths an entry reads, across its props, hidden, and each
-// expressions — the renderer subscribes to these. (seed run once and
-// callbacks read at fire time, so neither is scanned.)
-export function extractDeps(entry: ComponentEntry): string[] {
-  const cached = cache.get(entry);
-  if (cached) return cached;
-
-  const out = new Set<string>();
-
-  if (entry.props && "expr" in entry.props && entry.props.expr) {
-    for (const r of getScopeReads(entry.props.expr)) out.add(r);
-  }
-  if (entry.hidden) {
-    for (const r of getScopeReads(entry.hidden)) out.add(r);
-  }
-
-  // `each` reads both the list and anything its filter touches (e.g. a search term).
-  if (isComponentListEntry(entry)) {
-    for (const r of getScopeReads(entry.each)) out.add(r);
-  }
-
-  const result = [...out];
-  cache.set(entry, result);
-  return result;
-}

package/src/expr/globals.ts

@@ -1,118 +0,0 @@
-// Which JavaScript globals an expression can see. The engine enforces an
-// allowlist (safer-eval.ts): a free identifier that is neither an allowed global
-// nor an injected context name is rejected before the expression runs.
-// ALLOWED_GLOBALS is that list — also handed to SaferEval as allowGlobals and
-// shown to the LLM in the prompt. GLOBALS_TO_SHADOW are bound to undefined as a
-// second line of defence, so an allowed-by-mistake reference still stays inert.
-
-/** Globals an expression may reference. Every entry is also usable with `new`. */
-export const ALLOWED_GLOBALS: string[] = [
-  // Namespaces / utilities
-  "Math",
-  "JSON",
-  "Intl",
-  "Object",
-  "Array",
-  // Coercion (use as calls — `new Number(x)` etc. boxes the value)
-  "Number",
-  "String",
-  "Boolean",
-  "parseInt",
-  "parseFloat",
-  // Predicates / constants
-  "isNaN",
-  "isFinite",
-  "undefined",
-  "NaN",
-  "Infinity",
-  // URI helpers
-  "encodeURIComponent",
-  "decodeURIComponent",
-  "encodeURI",
-  "decodeURI",
-  // Constructors & async
-  "Date",
-  "Map",
-  "Set",
-  "RegExp",
-  "URL",
-  "URLSearchParams",
-  "Promise",
-  "BigInt",
-  // Error constructors
-  "Error",
-  "TypeError",
-  "RangeError",
-  "SyntaxError",
-  "ReferenceError",
-  "EvalError",
-  "URIError",
-  "AggregateError",
-];
-
-// Capability globals shadowed to undefined. (`eval` / `arguments` can't be param
-// names in strict mode — blocked in validate.ts instead.)
-export const GLOBALS_TO_SHADOW: string[] = [
-  // Global objects
-  "globalThis",
-  "self",
-  "window",
-  "global",
-  "document",
-  "navigator",
-  "location",
-  "history",
-  "localStorage",
-  "sessionStorage",
-  "indexedDB",
-
-  // Network / IO
-  "fetch",
-  "XMLHttpRequest",
-  "WebSocket",
-  "EventSource",
-  "Worker",
-  "SharedWorker",
-  "ServiceWorker",
-  "importScripts",
-  // Fire a network request via `.src` — an exfiltration channel even with fetch
-  // shadowed.
-  "Image",
-  "Audio",
-
-  // Code execution
-  "Function",
-  "WebAssembly", // runs arbitrary code
-  "setTimeout",
-  "setInterval",
-  "setImmediate",
-  "requestAnimationFrame",
-  "requestIdleCallback",
-  "queueMicrotask",
-
-  // Process / non-browser runtimes
-  "process",
-  "require",
-  "module",
-  "exports",
-  "__dirname",
-  "__filename",
-  "Buffer",
-  "Deno", // runtime god-object (fs/net/env) outside a browser
-  "Bun",
-
-  // DOM
-  "alert",
-  "confirm",
-  "prompt",
-  "close",
-  "open",
-  "print",
-  "postMessage",
-
-  // Constructors that can escape
-  "Proxy",
-  "Reflect",
-  "SharedArrayBuffer",
-  "Atomics",
-];

package/src/expr/safer-eval.ts

@@ -1,233 +0,0 @@
-import * as acorn from "acorn";
-import {
-  containsAwait,
-  extractFreeIdentifiers,
-  extractScopeReads,
-} from "./analyze";
-import { GLOBALS_TO_SHADOW } from "./globals";
-import { SaferEvalError, validateNode } from "./validate";
-
-// Compiles and runs the expressions validate.ts approves: parse + analyse once
-// (cached), compile to a Function (AsyncFunction when the expr uses `await`),
-// shadow ambient globals as undefined params, run in-realm so Proxy state works.
-// Guardrail, not a sandbox — see the Expressions docs page, § Safety.
-
-// Re-exported from validate.ts for callers of this module.
-export { SaferEvalError };
-
-// The AsyncFunction constructor, for expressions that use `await`.
-const AsyncFunction = Object.getPrototypeOf(async () => {})
-  .constructor as typeof Function;
-
-type CacheEntry = {
-  isAsync: boolean;
-  scopeReads: string[];
-  freeIds: string[];
-  // Built lazily on first compile(); validate()/scopeReads() leave it unset.
-  fn?: (context: Record<string, unknown>) => unknown;
-};
-
-export class SaferEval {
-  #cache = new Map<string, CacheEntry>();
-  #maxCacheSize: number;
-  #shadowParams: string[];
-  #allowGlobals: Set<string>;
-  #enforceAllowlist: boolean;
-
-  constructor(
-    options: {
-      maxCacheSize?: number;
-      extraGlobalsToShadow?: string[];
-      allowGlobals?: string[];
-      enforceAllowlist?: boolean;
-    } = {},
-  ) {
-    const {
-      maxCacheSize = 500,
-      extraGlobalsToShadow = [],
-      allowGlobals = [],
-      enforceAllowlist = false,
-    } = options;
-
-    this.#maxCacheSize = maxCacheSize;
-    this.#enforceAllowlist = enforceAllowlist;
-
-    const allowSet = new Set(allowGlobals);
-    this.#allowGlobals = allowSet;
-    this.#shadowParams = [...GLOBALS_TO_SHADOW, ...extraGlobalsToShadow].filter(
-      (g) => !allowSet.has(g),
-    );
-  }
-
-  // Parse + validate without running. Throws SaferEvalError if invalid; returns
-  // isAsync + scopeReads and caches the analysis (compile() builds the fn later).
-  validate(expression: string): {
-    isAsync: boolean;
-    scopeReads: string[];
-    freeIds: string[];
-  } {
-    if (typeof expression !== "string") {
-      throw new SaferEvalError("Expression must be a string", "expression-syntax");
-    }
-
-    const trimmed = expression.trim();
-    if (!trimmed) {
-      throw new SaferEvalError("Expression cannot be empty", "expression-syntax");
-    }
-
-    const cached = this.#cache.get(expression);
-    if (cached) {
-      return {
-        isAsync: cached.isAsync,
-        scopeReads: cached.scopeReads,
-        freeIds: cached.freeIds,
-      };
-    }
-
-    // Parse as `"use strict"; void (expr)`: void(...) forces expression context
-    // (so `{...}` is an object literal, not a block), and strict mode rejects
-    // sloppy-only constructs (octal, `with`, dup params) here, not at compile.
-    const wrapper = `"use strict"; void (${trimmed})`;
-    let ast: acorn.Program;
-    try {
-      ast = acorn.parse(wrapper, {
-        ecmaVersion: 2022,
-        sourceType: "script",
-        allowAwaitOutsideFunction: true,
-      });
-    } catch (e: unknown) {
-      throw new SaferEvalError(
-        `Syntax error: ${e instanceof Error ? e.message : String(e)}. Expression: ${expression}`,
-        "expression-syntax",
-      );
-    }
-
-    validateNode(ast);
-
-    const analysis = {
-      isAsync: containsAwait(ast),
-      scopeReads: extractScopeReads(ast),
-      freeIds: extractFreeIdentifiers(ast),
-    };
-
-    // Cache the analysis (no fn yet); evict oldest when full.
-    if (this.#cache.size >= this.#maxCacheSize) {
-      const firstKey = this.#cache.keys().next().value;
-      if (firstKey !== undefined) this.#cache.delete(firstKey);
-    }
-    this.#cache.set(expression, { ...analysis });
-
-    return analysis;
-  }
-
-  // Compile to a reusable fn (returns a Promise if the expr uses `await`).
-  compile(expression: string): (context: Record<string, unknown>) => unknown {
-    const { isAsync } = this.validate(expression);
-    const entry = this.#cache.get(expression);
-    if (!entry) {
-      // Unreachable — validate() just inserted this entry.
-      throw new SaferEvalError(
-        `Cache entry missing for expression: ${expression}`,
-      );
-    }
-    if (entry.fn) return entry.fn;
-
-    const expr = expression.trim();
-    const Ctor = isAsync ? AsyncFunction : Function;
-
-    // Single-slot cache: new Ctor bakes in the param names (context keys ∪ shadow
-    // params), so it recompiles only if the context shape changes — which it
-    // doesn't in practice (a given expr always sees the same keys).
-    let cachedSig: string | undefined;
-    let cachedFn: ((...args: unknown[]) => unknown) | undefined;
-
-    const evaluator = (context: Record<string, unknown>) => {
-      const contextKeys = Object.keys(context);
-      const sig = contextKeys.join("\u0000");
-      if (sig !== cachedSig) {
-        // Context keys become params; shadow params follow, bound to undefined.
-        const allParams = [...contextKeys, ...this.#shadowParams];
-        try {
-          cachedFn = new Ctor(
-            ...allParams,
-            `"use strict"; return (${expr})`,
-          ) as (...args: unknown[]) => unknown;
-        } catch (e: unknown) {
-          // Parsed but won't compile — surface as SaferEvalError, not a raw one.
-          throw new SaferEvalError(
-            `Failed to compile expression: ${
-              e instanceof Error ? e.message : String(e)
-            }. Expression: ${expression}`,
-            "expression-syntax",
-          );
-        }
-        cachedSig = sig;
-      }
-
-      // Args match allParams: context values (Object.keys order) then shadow fills.
-      const allArgs = [
-        ...Object.values(context),
-        ...new Array(this.#shadowParams.length).fill(undefined),
-      ];
-      return (cachedFn as (...args: unknown[]) => unknown)(...allArgs);
-    };
-
-    entry.fn = evaluator;
-    return evaluator;
-  }
-
-  isAsync(expression: string): boolean {
-    const cached = this.#cache.get(expression);
-    if (cached) return cached.isAsync;
-    return this.validate(expression).isAsync;
-  }
-
-  // Every `scopes.X.Y` path the expression reads — the renderer auto-subscribes
-  // to these instead of the LLM writing a deps array.
-  scopeReads(expression: string): string[] {
-    const cached = this.#cache.get(expression);
-    if (cached) return cached.scopeReads;
-    return this.validate(expression).scopeReads;
-  }
-
-  // Allowlist gate: every free identifier must be an injected context name, a
-  // base allowed global, or one the host opted into via allowedGlobals.
-  #checkAllowlist(
-    freeIds: string[],
-    contextKeys: string[],
-    allowedGlobals: string[],
-  ): void {
-    const allowed = new Set([
-      ...contextKeys,
-      ...this.#allowGlobals,
-      ...allowedGlobals,
-    ]);
-    for (const id of freeIds) {
-      if (!allowed.has(id)) {
-        // The expression named something that doesn't exist here — an
-        // unregistered function or a global outside the allowlist.
-        throw new SaferEvalError(
-          `"${id}" is not available in expressions`,
-          "unknown-reference",
-        );
-      }
-    }
-  }
-
-  eval(
-    expression: string,
-    context: Record<string, unknown> = {},
-    allowedGlobals: string[] = [],
-  ): unknown {
-    if (this.#enforceAllowlist) {
-      const { freeIds } = this.validate(expression);
-      this.#checkAllowlist(freeIds, Object.keys(context), allowedGlobals);
-    }
-    const evaluator = this.compile(expression);
-    return evaluator(context);
-  }
-
-  clearCache(): void {
-    this.#cache.clear();
-  }
-}