@telorun/cel 0.0.0-stage → 0.108.0

package/src/cel-expression.ts

@@ -0,0 +1,53 @@
+/**
+ * One CEL expression, read and resolved.
+ *
+ * This is the front end's whole answer: the source as written, the canonical tree,
+ * the namespace set the tree was resolved under, and at most one syntax diagnostic.
+ * **Every expression this module hands out is already resolved** — there is no way
+ * to obtain an unresolved tree and then forget to resolve it, and `namespaces`
+ * records what it was resolved under so a consumer checking it against a different
+ * set can refuse rather than quietly answer the wrong question.
+ *
+ * Reading an expression never throws: a source it cannot read gives a tree for the
+ * longest prefix it could, plus the diagnostic saying where it stopped.
+ */
+
+import {
+  namespaceSetsEqual,
+  normalizeNamespaces,
+  resolveNamespaces,
+} from "./namespace-resolution.js";
+import type { ParseOptions } from "./parser.js";
+import { parseSyntax } from "./parser.js";
+import type { CelSyntaxDiagnostic } from "./syntax-diagnostic.js";
+import type { CelNode } from "./syntax-tree.js";
+
+export interface CelExpression {
+  readonly source: string;
+  readonly root: CelNode;
+  /** The namespace set the tree was resolved under, in canonical order. */
+  readonly namespaces: readonly string[];
+  /** At most one entry; one exactly when the source could not be read whole. */
+  readonly diagnostics: readonly CelSyntaxDiagnostic[];
+}
+
+export interface ParseExpressionOptions extends ParseOptions {
+  /** The names that denote namespaces rather than values at this site. */
+  readonly namespaces?: Iterable<string>;
+}
+
+export function parseExpression(source: string, options?: ParseExpressionOptions): CelExpression {
+  const namespaces = normalizeNamespaces(options?.namespaces ?? []);
+  const parsed = parseSyntax(source, options);
+  return {
+    source,
+    root: resolveNamespaces(parsed.root, namespaces),
+    namespaces,
+    diagnostics: parsed.diagnostics,
+  };
+}
+
+/** Whether the expression was resolved under exactly these namespaces. */
+export function resolvedUnder(expression: CelExpression, namespaces: Iterable<string>): boolean {
+  return namespaceSetsEqual(expression.namespaces, normalizeNamespaces(namespaces));
+}

package/src/cel-map-value.ts

@@ -0,0 +1,97 @@
+/**
+ * Building a CEL map, and the one identity a key has.
+ *
+ * A map's entries live in a `Map` keyed by each key's **own typed value**, never by a
+ * property name. Three consequences, all load-bearing:
+ *
+ * - A map holds CEL's four key types (int, uint, bool, string) in one container, and an
+ *   int key and a uint key of the same number are **one** key, because CEL equality
+ *   makes them equal — so a literal writing both is a duplicate rather than two entries.
+ * - Nothing a key spells can reach a prototype, a method or an inherited member. A map
+ *   built from `{'__proto__': 1}` holds `__proto__` as data and reads it back as data;
+ *   dropping such a key would be swallowing what the author wrote.
+ * - The types separate themselves. A `Map` compares its keys by type as well as value, so
+ *   a string `"1"` and an int `1` are distinct keys with nothing prefixed to say so — and a
+ *   second engine keys an entry by its own discriminant rather than reproducing this one's
+ *   text byte for byte.
+ */
+
+import type { CelMap, CelMapKey, CelMapValueEntry, CelValue } from "./cel-value.js";
+import {
+  CEL_VALUE_TYPE,
+  celError,
+  isCelError,
+  isCelUint,
+  type CelError,
+} from "./cel-value.js";
+import type { SourceRange } from "./syntax-tree.js";
+
+/**
+ * What identifies a key. The `bigint` covers the numeric types together: CEL equality
+ * makes `1`, `1u` and `1.0` one key, so a map carrying two of them is not a map and a
+ * lookup by any of the three finds the entry — which is what
+ * `{1u: 1.0, 2: 2.0, 3u: 3.0}[?3.0]` reads. A double that is not whole identifies
+ * nothing, since no entry can hold it.
+ *
+ * A string and a bool identify themselves, and nothing is prefixed to keep the types
+ * apart: a `Map` key of one type never equals a key of another, so `"1"` and `1` are
+ * distinct keys and `"true"` is not `true`.
+ */
+export function mapKeyIdentity(key: CelValue): CelMapKey | undefined {
+  const held = typeof key;
+  if (held === "string" || held === "boolean" || held === "bigint") return key as CelMapKey;
+  if (held === "number") return Number.isInteger(key) ? BigInt(key as number) : undefined;
+  return isCelUint(key) ? key.value : undefined;
+}
+
+/** An empty map, for a literal with no entries. */
+export function celMapOf(entries: ReadonlyMap<CelMapKey, CelMapValueEntry>): CelMap {
+  return { [CEL_VALUE_TYPE]: "map", entries };
+}
+
+/**
+ * A map from its entries in written order, or the error that stops it: a key of a type
+ * no map is keyed by, or two keys CEL equality makes one.
+ *
+ * The entries arrive **flat** — key, value, key, value — because a literal of n entries
+ * then costs one allocation rather than one per entry, and both backends write the same
+ * call. A duplicate is caught by the size not moving, which is the one hash lookup the
+ * insert already performs.
+ */
+export function celMapFromEntries(flat: readonly CelValue[], range?: SourceRange): CelMap | CelError {
+  const entries = new Map<CelMapKey, CelMapValueEntry>();
+  for (let at = 0; at < flat.length; at += 2) {
+    const key = flat[at] as CelValue;
+    const value = flat[at + 1] as CelValue;
+    if (isCelError(key)) return key;
+    if (isCelError(value)) return value;
+    // A map is **built** with an int, uint, bool or string key: a double is not a key
+    // type, even one that is whole. It still LOOKS one up, because `{1u: …}[?1.0]` reads
+    // the entry — equality across the numeric types holds for a key as for a value.
+    const identity = typeof key === "number" ? undefined : mapKeyIdentity(key);
+    if (identity === undefined) {
+      return celError(
+        "unsupported_key_type",
+        "a map is keyed by an int, a uint, a bool or a string",
+        range,
+      );
+    }
+    const before = entries.size;
+    entries.set(identity, { key, value });
+    if (entries.size === before) {
+      return celError("duplicate_map_key", `the key ${describeKey(key)} is written twice`, range);
+    }
+  }
+  return celMapOf(entries);
+}
+
+function describeKey(key: CelValue): string {
+  if (typeof key === "string") return JSON.stringify(key);
+  if (isCelUint(key)) return `${key.value}u`;
+  return String(key);
+}
+
+/** Every key of a map, in insertion order — what a comprehension ranges over. */
+export function celMapKeys(map: CelMap): CelValue[] {
+  return [...map.entries.values()].map((entry) => entry.key);
+}

package/src/cel-program.ts

@@ -0,0 +1,103 @@
+/**
+ * A compiled expression, and what happens at the top of an evaluation.
+ *
+ * An error is a **value** throughout evaluation, so that `false && <missing key>` is
+ * `false`. At the top there is nothing left to short-circuit, so a surviving error
+ * becomes a thrown failure carrying its code — the one place the engine throws about an
+ * expression's own data, and the only form a caller can be expected to handle.
+ */
+
+import type { CelActivation } from "./activation.js";
+import type { CelStep, CompileTarget, NamespaceDispatch } from "./backend-runtime.js";
+import { compileTree } from "./closure-backend.js";
+import type { CelError, CelEvaluationCode, CelValue } from "./cel-value.js";
+import { celError, isCelError, isThenable } from "./cel-value.js";
+import type { CelExpression } from "./cel-expression.js";
+import type { SourceRange } from "./syntax-tree.js";
+
+/** A failure an evaluation could not carry any further. */
+export class CelEvaluationError extends Error {
+  readonly code: CelEvaluationCode;
+  readonly range?: SourceRange;
+
+  constructor(code: CelEvaluationCode, message: string, range?: SourceRange) {
+    super(message);
+    this.name = "CelEvaluationError";
+    this.code = code;
+    if (range) this.range = range;
+  }
+}
+
+export interface EvaluateOptions {
+  /**
+   * What a namespaced call (`Alias.fn(x)`) is dispatched through. A host binds it per
+   * evaluation, because which functions a scope reaches is the host's own question; a
+   * call nothing binds is `unbound_function`.
+   */
+  readonly namespaceFunction?: NamespaceDispatch;
+}
+
+export interface CelProgram {
+  readonly source: string;
+  /** The value, or a throw carrying the code of the error that survived to the top. */
+  evaluate(activation?: CelActivation, options?: EvaluateOptions): CelValue;
+  /** The value or the error value, for a caller that carries errors itself. */
+  evaluateToValue(activation?: CelActivation, options?: EvaluateOptions): CelValue;
+}
+
+/** The refusal a thenable surviving to the top is, spanning the whole expression. */
+function asyncRefused(source: string): CelError {
+  return celError(
+    "async_value_unsupported",
+    "a value that must be awaited reached evaluation, and CEL evaluates synchronously",
+    [0, source.length],
+  );
+}
+
+const NO_ACTIVATION: CelActivation = Object.freeze(Object.create(null) as CelActivation);
+/** A frame that binds nothing needs no slots, and allocating none is measurable. */
+const NO_SLOTS: CelValue[] = [];
+
+export function compileExpression(expression: CelExpression, target: CompileTarget): CelProgram {
+  const compiled = compileTree(expression.root, target);
+  return new Program(expression.source, compiled.step, compiled.slots);
+}
+
+/**
+ * A program over a step a backend already built — what an emitted module's function
+ * becomes. The top of an evaluation is the same either way: the thenable backstop, and a
+ * surviving error turning into a throw. A second implementation of that top would be a
+ * second answer to "what does a caller see", which is the one thing two backends may not
+ * disagree about.
+ */
+export function programOfStep(source: string, step: CelStep, slots = 0): CelProgram {
+  return new Program(source, step, slots);
+}
+
+class Program implements CelProgram {
+  constructor(
+    readonly source: string,
+    private readonly step: CelStep,
+    private readonly slots: number,
+  ) {}
+
+  evaluateToValue(activation: CelActivation = NO_ACTIVATION, options: EvaluateOptions = {}): CelValue {
+    // One shape, every time: a frame built two ways is two shapes, and every step that
+    // reads one would see both.
+    const value = this.step({
+      activation,
+      slots: this.slots === 0 ? NO_SLOTS : new Array<CelValue>(this.slots),
+      namespaceFunction: options.namespaceFunction,
+    });
+    // The backstop, one check per evaluation: every door refuses a thenable where the value
+    // enters, and this is what catches a door nobody has thought of yet rather than handing a
+    // promise to a caller as though it were a value.
+    return isThenable(value) ? asyncRefused(this.source) : value;
+  }
+
+  evaluate(activation?: CelActivation, options?: EvaluateOptions): CelValue {
+    const value = this.evaluateToValue(activation, options);
+    if (isCelError(value)) throw new CelEvaluationError(value.code, value.message, value.range);
+    return value;
+  }
+}

package/src/cel-type.ts

@@ -0,0 +1,359 @@
+/**
+ * CEL's types.
+ *
+ * The domain is deliberately richer than the one an expression can spell, because
+ * the checker's whole value is in what it can be *told*: a variable typed from a
+ * JSON Schema carries its nested objects, its element types and its unions, and a
+ * typo two levels down is then a type error rather than something only a running
+ * request discovers.
+ *
+ * Four shapes exist for that reason and have no syntax of their own:
+ *
+ * - `record` — an object with named fields, each typed in turn; `open` says whether
+ *   a field it does not declare is unjudged (a schema with no `properties`) or
+ *   undeclared (a closed schema).
+ * - `union` — carried as a union rather than collapsed to `dyn`, so `int|null` keeps
+ *   both the arithmetic and the null that makes a dereference worth reporting.
+ * - `nominal` — a named type over a base, with invariant arguments: the mechanism a
+ *   host registers its own vocabulary through. **A nominal is not its base**: it
+ *   accepts only what is registered for it, which is what makes a slot expecting one
+ *   refuse a plain value of the base. (The vectors pin this: an operator the base
+ *   accepts is refused on the named type.)
+ * - `parameter` — a type variable in a signature, unified per call and invariant.
+ *
+ * `dyn` is the top: it is assignable both ways, which is what keeps an unlisted
+ * variable or an unknown call result from cascading into a second error.
+ */
+
+export type PrimitiveName =
+  | "int"
+  | "uint"
+  | "double"
+  | "bool"
+  | "string"
+  | "bytes"
+  | "null"
+  | "type"
+  | "timestamp"
+  | "duration";
+
+export interface DynType {
+  readonly kind: "dyn";
+}
+export interface PrimitiveType {
+  readonly kind: "primitive";
+  readonly name: PrimitiveName;
+}
+export interface ListType {
+  readonly kind: "list";
+  readonly element: CelType;
+}
+export interface MapType {
+  readonly kind: "map";
+  readonly key: CelType;
+  readonly value: CelType;
+}
+export interface OptionalType {
+  readonly kind: "optional";
+  readonly value: CelType;
+}
+export interface RecordType {
+  readonly kind: "record";
+  readonly name?: string;
+  readonly fields: ReadonlyMap<string, CelType>;
+  /** A field the record does not declare is unjudged when open, undeclared when closed. */
+  readonly open: boolean;
+}
+export interface UnionType {
+  readonly kind: "union";
+  readonly members: readonly CelType[];
+}
+export interface NominalType {
+  readonly kind: "nominal";
+  readonly name: string;
+  readonly base: CelType;
+  readonly args: readonly CelType[];
+}
+export interface ParameterType {
+  readonly kind: "parameter";
+  readonly name: string;
+}
+
+export type CelType =
+  | DynType
+  | PrimitiveType
+  | ListType
+  | MapType
+  | OptionalType
+  | RecordType
+  | UnionType
+  | NominalType
+  | ParameterType;
+
+export const DYN: DynType = { kind: "dyn" };
+
+const primitive = (name: PrimitiveName): PrimitiveType => ({ kind: "primitive", name });
+
+export const INT = primitive("int");
+export const UINT = primitive("uint");
+export const DOUBLE = primitive("double");
+export const BOOL = primitive("bool");
+export const STRING = primitive("string");
+export const BYTES = primitive("bytes");
+export const NULL = primitive("null");
+export const TYPE = primitive("type");
+export const TIMESTAMP = primitive("timestamp");
+export const DURATION = primitive("duration");
+
+export const listOf = (element: CelType): ListType => ({ kind: "list", element });
+export const mapOf = (key: CelType, value: CelType): MapType => ({ kind: "map", key, value });
+export const optionalOf = (value: CelType): OptionalType => ({ kind: "optional", value });
+export const parameterOf = (name: string): ParameterType => ({ kind: "parameter", name });
+
+/** A union of its distinct members; one member is that member, none is `dyn`. */
+export function unionOf(members: readonly CelType[]): CelType {
+  const flat: CelType[] = [];
+  for (const member of members) {
+    for (const part of member.kind === "union" ? member.members : [member]) {
+      if (!flat.some((held) => typesEqual(held, part))) flat.push(part);
+    }
+  }
+  if (flat.length === 0) return DYN;
+  if (flat.length === 1) return flat[0]!;
+  if (flat.some((member) => member.kind === "dyn")) return DYN;
+  return { kind: "union", members: flat };
+}
+
+/** The names the timestamp and duration types are written and printed under. */
+export const WELL_KNOWN_TYPE_NAMES: Readonly<Record<string, PrimitiveName>> = {
+  "google.protobuf.Timestamp": "timestamp",
+  "google.protobuf.Duration": "duration",
+};
+
+const PRIMITIVE_PRINTED: Readonly<Record<PrimitiveName, string>> = {
+  int: "int",
+  uint: "uint",
+  double: "double",
+  bool: "bool",
+  string: "string",
+  bytes: "bytes",
+  null: "null",
+  type: "type",
+  timestamp: "google.protobuf.Timestamp",
+  duration: "google.protobuf.Duration",
+};
+
+export function isDyn(type: CelType): boolean {
+  return type.kind === "dyn";
+}
+
+export function typesEqual(left: CelType, right: CelType): boolean {
+  if (left.kind !== right.kind) return false;
+  switch (left.kind) {
+    case "dyn":
+      return true;
+    case "primitive":
+      return left.name === (right as PrimitiveType).name;
+    case "list":
+      return typesEqual(left.element, (right as ListType).element);
+    case "map": {
+      const other = right as MapType;
+      return typesEqual(left.key, other.key) && typesEqual(left.value, other.value);
+    }
+    case "optional":
+      return typesEqual(left.value, (right as OptionalType).value);
+    case "record": {
+      const other = right as RecordType;
+      if (left.name !== other.name || left.open !== other.open || left.fields.size !== other.fields.size) {
+        return false;
+      }
+      for (const [field, type] of left.fields) {
+        const held = other.fields.get(field);
+        if (!held || !typesEqual(type, held)) return false;
+      }
+      return true;
+    }
+    case "union": {
+      const other = right as UnionType;
+      return (
+        left.members.length === other.members.length &&
+        left.members.every((member, at) => typesEqual(member, other.members[at]!))
+      );
+    }
+    case "nominal": {
+      const other = right as NominalType;
+      return (
+        left.name === other.name &&
+        left.args.length === other.args.length &&
+        left.args.every((argument, at) => typesEqual(argument, other.args[at]!))
+      );
+    }
+    case "parameter":
+      return left.name === (right as ParameterType).name;
+  }
+}
+
+/**
+ * How a type is written. `top` collapses a list or map of `dyn` to its bare name,
+ * which is how the whole type of an expression is reported.
+ */
+export function formatType(type: CelType, top = false): string {
+  switch (type.kind) {
+    case "dyn":
+      return "dyn";
+    case "primitive":
+      return PRIMITIVE_PRINTED[type.name];
+    case "list":
+      return top && isDyn(type.element) ? "list" : `list<${formatType(type.element)}>`;
+    case "map":
+      return top && isDyn(type.key) && isDyn(type.value)
+        ? "map"
+        : `map<${formatType(type.key)}, ${formatType(type.value)}>`;
+    case "optional":
+      return `optional<${formatType(type.value)}>`;
+    case "record":
+      // An unnamed record is the shape a map has at runtime, and that is how a
+      // message names it; its fields are what a diagnostic lists, not its type.
+      return type.name ?? "map";
+    case "union":
+      return type.members.map((member) => formatType(member)).join("|");
+    case "nominal":
+      return type.args.length === 0
+        ? type.name
+        : `${type.name}<${type.args.map((argument) => formatType(argument)).join(", ")}>`;
+    case "parameter":
+      return type.name;
+  }
+}
+
+/** The numeric types, over which CEL compares and converts across type. */
+const NUMERIC = new Set<PrimitiveName>(["int", "uint", "double"]);
+
+export function isNumeric(type: CelType): boolean {
+  return type.kind === "primitive" && NUMERIC.has(type.name);
+}
+
+/**
+ * The type with every unresolved type parameter replaced by `dyn` — the last step before a
+ * type is REPORTED.
+ *
+ * cel-spec's rule is that an unresolved parameter behaves as `dyn` wherever it is used, and
+ * the type handed out is a use like any other: a consumer that reads `list<T>` has to know
+ * what `T` means to this engine, and the answer is "nothing — it was never resolved". A
+ * parameter survives only where it is DECLARED: a signature's text, a nominal type's
+ * parameter list.
+ */
+export function withoutParameters(type: CelType): CelType {
+  switch (type.kind) {
+    case "parameter":
+      return DYN;
+    case "list": {
+      const element = withoutParameters(type.element);
+      return element === type.element ? type : listOf(element);
+    }
+    case "map": {
+      const key = withoutParameters(type.key);
+      const value = withoutParameters(type.value);
+      return key === type.key && value === type.value ? type : mapOf(key, value);
+    }
+    case "optional": {
+      const value = withoutParameters(type.value);
+      return value === type.value ? type : optionalOf(value);
+    }
+    case "union":
+      return unionOf(type.members.map(withoutParameters));
+    case "nominal": {
+      const args = type.args.map(withoutParameters);
+      return args.every((argument, at) => argument === type.args[at]) ? type : { ...type, args };
+    }
+    case "record": {
+      let moved = false;
+      const fields = new Map<string, CelType>();
+      for (const [name, held] of type.fields) {
+        const replaced = withoutParameters(held);
+        if (replaced !== held) moved = true;
+        fields.set(name, replaced);
+      }
+      return moved ? { ...type, fields } : type;
+    }
+    default:
+      return type;
+  }
+}
+
+/** Whether `type` admits a null value — a null, or a union holding one. */
+export function admitsNull(type: CelType): boolean {
+  if (type.kind === "primitive") return type.name === "null";
+  if (type.kind === "union") return type.members.some(admitsNull);
+  return false;
+}
+
+/** The type with every null taken out of it; `dyn` and a bare null are unchanged. */
+export function withoutNull(type: CelType): CelType {
+  if (type.kind !== "union") return type;
+  const members = type.members.filter((member) => !admitsNull(member));
+  return members.length === 0 ? type : unionOf(members);
+}
+
+/**
+ * Whether a value of `from` may stand where `to` is wanted.
+ *
+ * `dyn` passes both ways; a nominal type accepts only itself (its base is a
+ * different type); a union passes where every member does, and accepts a value any
+ * member accepts. Numeric types do **not** convert implicitly — CEL's cross-type
+ * arithmetic and comparison are declared overloads, not coercions.
+ */
+export function assignable(from: CelType, to: CelType): boolean {
+  if (isDyn(from) || isDyn(to)) return true;
+  // An unresolved parameter is an unknown type: it stands where anything is wanted and
+  // accepts anything, exactly as `dyn` does. What it does NOT have is members — asking
+  // for one has no answer, and the checker refuses there rather than here.
+  if (to.kind === "parameter" || from.kind === "parameter") return true;
+  if (from.kind === "union") return from.members.every((member) => assignable(member, to));
+  if (to.kind === "union") return to.members.some((member) => assignable(from, member));
+  if (from.kind === "nominal" || to.kind === "nominal") return typesEqual(from, to);
+  switch (to.kind) {
+    case "list":
+      return from.kind === "list" && assignable(from.element, to.element);
+    case "map":
+      return (
+        (from.kind === "map" && assignable(from.key, to.key) && assignable(from.value, to.value)) ||
+        // A record is a map with named keys, so it stands where a string-keyed map does.
+        (from.kind === "record" && assignable(STRING, to.key) && recordValuesAssignable(from, to.value))
+      );
+    case "optional":
+      return from.kind === "optional" && assignable(from.value, to.value);
+    case "record":
+      return from.kind === "record" && typesEqual(from, to);
+    default:
+      return typesEqual(from, to);
+  }
+}
+
+function recordValuesAssignable(record: RecordType, to: CelType): boolean {
+  if (isDyn(to)) return true;
+  if (record.open) return false;
+  return [...record.fields.values()].every((type) => assignable(type, to));
+}
+
+/**
+ * The one type both arms can be. Unlike assignability this is symmetric, and it is
+ * what an aggregate literal's elements and a ternary's branches are reduced through:
+ * nothing in common is `dyn`, which is CEL's own reading of a heterogeneous literal.
+ *
+ * **An unresolved parameter yields to the other side**, so the element type of
+ * `[[[[]]]], [], [[[]]]]` is the deepest list rather than `dyn`: an empty aggregate
+ * says nothing about its elements and must not erase what a sibling does say.
+ */
+export function unify(left: CelType, right: CelType): CelType {
+  if (typesEqual(left, right)) return left;
+  if (left.kind === "parameter") return right;
+  if (right.kind === "parameter") return left;
+  if (isDyn(left) || isDyn(right)) return DYN;
+  if (left.kind === "list" && right.kind === "list") return listOf(unify(left.element, right.element));
+  if (left.kind === "map" && right.kind === "map") {
+    return mapOf(unify(left.key, right.key), unify(left.value, right.value));
+  }
+  if (left.kind === "optional" && right.kind === "optional") return optionalOf(unify(left.value, right.value));
+  return DYN;
+}