@telorun/cel 0.0.0-stage → 0.107.0

package/src/macro-check.ts

@@ -0,0 +1,191 @@
+/**
+ * Typing the macros — the constructs that are written as calls and are not functions.
+ *
+ * A macro binds a name, or inspects the shape of its argument, so it cannot be a
+ * registered signature: `xs.map(i, i + 1)` has no argument type for `i`, and `has(a.b)`
+ * is about whether `b` is there rather than about its value. The parser deliberately
+ * leaves each one an ordinary call node (expanding it would make the source unwritable
+ * from the tree), so this is where the comprehension appears — in the checker's own
+ * lowering, which is also why a macro is **not** a dispatched call in the call listing.
+ *
+ * Which arguments a macro binds a name over is declared once, in
+ * `comprehension-bindings.ts`, and read both here and by the free-variable query. Two
+ * tables would be two answers to "what does this macro bind".
+ */
+
+import type { CelType } from "./cel-type.js";
+import { BOOL, DYN, formatType, isDyn, listOf, optionalOf, parameterOf } from "./cel-type.js";
+import type { CelCheckCode } from "./check-diagnostic.js";
+import { namespaceMacroBinding, receiverMacroBinding } from "./comprehension-bindings.js";
+import type { CelNode, SourceRange } from "./syntax-tree.js";
+
+/** What a macro needs of the checker around it. */
+export interface MacroHost {
+  /** The type of a subexpression, in the scope that holds here. */
+  typeOf(node: CelNode): CelType;
+  /** The type of a subexpression with extra names in scope. */
+  typeOfBinding(node: CelNode, bindings: ReadonlyMap<string, CelType>): CelType;
+  report(code: CelCheckCode, message: string, range: SourceRange): void;
+}
+
+/** The reserved namespaces a macro is written on, and the macros on each. */
+const NAMESPACE_MACROS: Readonly<Record<string, readonly string[]>> = {
+  cel: ["bind"],
+  optional: ["of", "none", "ofNonZeroValue"],
+};
+
+/** The optional library's two name-binding members, which no signature can state. */
+const OPTIONAL_BINDING_MACROS = new Set(["optMap", "optFlatMap"]);
+
+/** Whether a call is a macro at all — asked before any overload is looked for. */
+export function isMacroCall(node: CelNode): boolean {
+  if (node.kind === "call") return node.name === "has" && node.args.length === 1;
+  if (node.kind !== "receiverCall") return false;
+  if (receiverMacroBinding(node.name, node.args.length)) return true;
+  const receiver = node.receiver;
+  if (receiver.kind !== "ident") return false;
+  const on = NAMESPACE_MACROS[receiver.name];
+  return on !== undefined && on.includes(node.name);
+}
+
+/**
+ * The type of a macro call. `isMacroCall` has already said it is one; anything this
+ * cannot type reports its own diagnostic and answers `dyn`, so one mistake stays one.
+ */
+export function checkMacro(node: CelNode, host: MacroHost): CelType {
+  if (node.kind === "call") return checkHas(node, host);
+  if (node.kind !== "receiverCall") return DYN;
+  const receiver = node.receiver;
+  if (receiver.kind === "ident" && NAMESPACE_MACROS[receiver.name]) {
+    return receiver.name === "cel"
+      ? checkBind(node, host)
+      : checkOptionalNamespace(node, host);
+  }
+  if (OPTIONAL_BINDING_MACROS.has(node.name) && node.args.length === 2) {
+    return checkOptionalBinding(node, host);
+  }
+  return checkComprehension(node, host);
+}
+
+/**
+ * `opt.optMap(v, expr)` and `opt.optFlatMap(v, expr)`: the held value under a name, for
+ * one expression. `optMap` wraps what that expression answers; `optFlatMap` takes an
+ * optional from it and does not wrap it again.
+ */
+function checkOptionalBinding(node: Extract<CelNode, { kind: "receiverCall" }>, host: MacroHost): CelType {
+  const receiver = host.typeOf(node.receiver);
+  const name = node.args[0]!;
+  if (name.kind !== "ident") return DYN;
+  let held: CelType = DYN;
+  if (receiver.kind === "optional") held = receiver.value;
+  else if (!isDyn(receiver) && receiver.kind !== "parameter") {
+    host.report(
+      "CEL_TYPE_ERROR",
+      `${node.name} reads an optional, and ${formatType(receiver)} is not one`,
+      node.receiver.range,
+    );
+  }
+  const result = host.typeOfBinding(node.args[1]!, new Map([[name.name, held]]));
+  if (node.name === "optMap") return optionalOf(result);
+  if (result.kind === "optional" || isDyn(result) || result.kind === "parameter") return result;
+  host.report(
+    "CEL_TYPE_ERROR",
+    `optFlatMap's expression must answer an optional, and it answers ${formatType(result)}`,
+    node.args[1]!.range,
+  );
+  return optionalOf(DYN);
+}
+
+/** `has(a.b)` — a question about presence. Its shape is already validated. */
+function checkHas(node: Extract<CelNode, { kind: "call" }>, host: MacroHost): CelType {
+  const argument = node.args[0]!;
+  if (argument.kind === "select") host.typeOf(argument);
+  return BOOL;
+}
+
+/** `cel.bind(name, value, body)` — a name for one value, in scope in the body alone. */
+function checkBind(node: Extract<CelNode, { kind: "receiverCall" }>, host: MacroHost): CelType {
+  const binding = namespaceMacroBinding("cel", node.name, node.args.length);
+  if (!binding) {
+    host.report(
+      "CEL_INVALID_ARGUMENT",
+      "cel.bind(name, value, body) takes three arguments: a name, its value, and the expression that reads it",
+      node.range,
+    );
+    return DYN;
+  }
+  const name = node.args[binding.variableArgument]!;
+  if (name.kind !== "ident") return DYN;
+  const value = host.typeOf(node.args[1]!);
+  return host.typeOfBinding(node.args[2]!, new Map([[name.name, value]]));
+}
+
+/** `optional.of(v)`, `optional.ofNonZeroValue(v)` and `optional.none()`. */
+function checkOptionalNamespace(node: Extract<CelNode, { kind: "receiverCall" }>, host: MacroHost): CelType {
+  if (node.name === "none") {
+    if (node.args.length !== 0) {
+      host.report("CEL_INVALID_ARGUMENT", "optional.none() takes no argument", node.range);
+    }
+    return optionalOf(parameterOf("T"));
+  }
+  if (node.args.length !== 1) {
+    host.report("CEL_INVALID_ARGUMENT", `optional.${node.name}(value) takes one argument`, node.range);
+    return optionalOf(DYN);
+  }
+  return optionalOf(host.typeOf(node.args[0]!));
+}
+
+/** `all`, `exists`, `exists_one`, `filter` and `map` over a list or a map. */
+function checkComprehension(node: Extract<CelNode, { kind: "receiverCall" }>, host: MacroHost): CelType {
+  const binding = receiverMacroBinding(node.name, node.args.length)!;
+  const receiver = host.typeOf(node.receiver);
+  const element = iterationType(receiver, node, host);
+  const name = node.args[binding.variableArgument]!;
+  if (name.kind !== "ident") return DYN;
+  const bindings = new Map([[name.name, element]]);
+  const scoped = binding.scopedArguments.map((at) => ({
+    node: node.args[at]!,
+    type: host.typeOfBinding(node.args[at]!, bindings),
+  }));
+
+  if (node.name === "all" || node.name === "exists" || node.name === "exists_one") {
+    requireBool(scoped[0]!, node.name, host);
+    return BOOL;
+  }
+  if (node.name === "filter") {
+    requireBool(scoped[0]!, node.name, host);
+    return listOf(element);
+  }
+  // `map` in both arities: the last scoped argument is the transform, and a third
+  // argument makes the one before it a filter.
+  if (scoped.length === 2) requireBool(scoped[0]!, node.name, host);
+  return listOf(scoped.at(-1)!.type);
+}
+
+function requireBool(
+  scoped: { node: CelNode; type: CelType },
+  name: string,
+  host: MacroHost,
+): void {
+  if (isDyn(scoped.type) || scoped.type.kind === "parameter") return;
+  if (scoped.type.kind === "primitive" && scoped.type.name === "bool") return;
+  host.report(
+    "CEL_TYPE_ERROR",
+    `${name}'s test must be bool, and it is ${formatType(scoped.type)}`,
+    scoped.node.range,
+  );
+}
+
+/** What one element of a comprehension's receiver is: a list's element, a map's key. */
+function iterationType(receiver: CelType, node: CelNode, host: MacroHost): CelType {
+  if (isDyn(receiver) || receiver.kind === "parameter") return DYN;
+  if (receiver.kind === "list") return receiver.element;
+  if (receiver.kind === "map") return receiver.key;
+  if (receiver.kind === "record") return { kind: "primitive", name: "string" };
+  host.report(
+    "CEL_TYPE_ERROR",
+    `a comprehension reads a list or a map, and ${formatType(receiver)} is neither`,
+    node.kind === "receiverCall" ? node.receiver.range : node.range,
+  );
+  return DYN;
+}

package/src/macro-shape.ts

@@ -0,0 +1,66 @@
+/**
+ * Whether each macro call is shaped like one at all, judged before any type is read.
+ *
+ * A macro's own arguments are not values: `xs.map(i, …)` declares the name `i`, and
+ * `has(a.b)` asks about the member `b` of a chain of names. Neither is something a type
+ * can be wrong about — they are either written in the shape the macro takes, or the call
+ * is not that macro. So this is a **structural** pass over the whole tree, and it runs
+ * first: a macro written wrongly is reported before anything inside it is typed, because
+ * the typing of its body depends on a name the call failed to declare.
+ *
+ * The walk is **post-order**, so the innermost mistake is the one reported first. Nesting
+ * macros is how a generated expression goes wrong, and the inner call is the one a reader
+ * has to fix.
+ */
+
+import type { CelCheckCode } from "./check-diagnostic.js";
+import { namespaceMacroBinding, receiverMacroBinding } from "./comprehension-bindings.js";
+import type { CelNode, SourceRange } from "./syntax-tree.js";
+import { childNodes } from "./syntax-tree.js";
+
+export interface MacroShapeFinding {
+  readonly code: CelCheckCode;
+  readonly message: string;
+  readonly range: SourceRange;
+}
+
+/** Every macro call whose own arguments are not the shape it takes, innermost first. */
+export function macroShapeFindings(root: CelNode): readonly MacroShapeFinding[] {
+  const findings: MacroShapeFinding[] = [];
+  collect(root, findings);
+  return findings;
+}
+
+function collect(node: CelNode, findings: MacroShapeFinding[]): void {
+  for (const child of childNodes(node)) collect(child, findings);
+  const finding = shapeOf(node);
+  if (finding) findings.push(finding);
+}
+
+function shapeOf(node: CelNode): MacroShapeFinding | undefined {
+  if (node.kind === "call" && node.name === "has" && node.args.length === 1) {
+    const argument = node.args[0]!;
+    if (argument.kind === "select" && argument.field !== "") return undefined;
+    return {
+      code: "CEL_INVALID_ARGUMENT",
+      message: "has() asks whether a member is there, so it takes a member read: write has(a.b)",
+      range: argument.range,
+    };
+  }
+  if (node.kind !== "receiverCall") return undefined;
+  const binding =
+    receiverMacroBinding(node.name, node.args.length) ??
+    namespaceMacroBinding(
+      node.receiver.kind === "ident" ? node.receiver.name : "",
+      node.name,
+      node.args.length,
+    );
+  if (!binding) return undefined;
+  const variable = node.args[binding.variableArgument]!;
+  if (variable.kind === "ident") return undefined;
+  return {
+    code: "CEL_INVALID_ARGUMENT",
+    message: `${node.name} binds a name here, and this is not a name`,
+    range: variable.range,
+  };
+}

package/src/member-read.ts

@@ -0,0 +1,126 @@
+/**
+ * The member-read seam: **one** lookup, for every form a read is written in.
+ *
+ * `a.b`, `a['b']`, `a[expr]`, `a.?b`, `a[?expr]`, a macro's field read and the presence
+ * question `has()` all resolve here, through a single lookup over the value's **own**
+ * entries. Neither backend ever performs a host property read, so no key — however it
+ * was computed — can reach a prototype, a method or a function property: `a['length']`
+ * on a map is a missing key, not `0`, and `a[request.query.k]` cannot reach
+ * `constructor`.
+ *
+ * That is why the reserved-word set holds CEL's own words and nothing else. A word list
+ * is the wrong instrument: a member *name* is written by the author, while a member
+ * *key* can come from a request, so no list at any position touches the form an
+ * attacker can actually reach — and refusing `__proto__` as a name would make a
+ * resource that may legally be called that unreadable through CEL.
+ *
+ * A key the value does not hold is the `no_such_key` **error value**, which
+ * participates in short-circuit. Never `undefined` passed along.
+ */
+
+import { celMapKeys, mapKeyIdentity } from "./cel-map-value.js";
+import type { CelValue } from "./cel-value.js";
+import { celError, isCelMap, isCelRecord, isCelUint, type CelError } from "./cel-value.js";
+import type { SourceRange } from "./syntax-tree.js";
+
+/**
+ * What one lookup found. The four refusals are **symbols**, not objects: a lookup happens
+ * on nearly every evaluation, and a wrapper object per read is an allocation per read.
+ * `MISSING` is a key the container does not hold — which `has()` answers `false` for and a
+ * read turns into `no_such_key`; the other three are mistakes in the read itself.
+ */
+export const MISSING = Symbol("cel.lookup.missing");
+export const OUT_OF_RANGE = Symbol("cel.lookup.outOfRange");
+export const UNSUPPORTED_CONTAINER = Symbol("cel.lookup.unsupportedContainer");
+export const UNSUPPORTED_KEY = Symbol("cel.lookup.unsupportedKey");
+
+export type Lookup =
+  | CelValue
+  | typeof MISSING
+  | typeof OUT_OF_RANGE
+  | typeof UNSUPPORTED_CONTAINER
+  | typeof UNSUPPORTED_KEY;
+
+/** An int-valued index, or nothing when the value is of no index type. */
+function indexOf(key: CelValue): bigint | undefined {
+  if (typeof key === "bigint") return key;
+  if (isCelUint(key)) return key.value;
+  // A double that holds a whole number indexes a list: a `dyn` arithmetic result is a
+  // double, and cel-spec indexes with it where it is integral.
+  if (typeof key === "number" && Number.isInteger(key)) return BigInt(key);
+  return undefined;
+}
+
+/**
+ * The single lookup. It is total over the value domain: a container that holds no members
+ * at all answers `UNSUPPORTED_CONTAINER` rather than falling back to a property read that
+ * might find `length`, `name`, `call` or `apply`.
+ */
+export function celLookup(container: CelValue, key: CelValue): Lookup {
+  if (typeof key === "string" && isCelRecord(container)) {
+    // An OWN entry, never an inherited one: a host's object is data here.
+    return Object.prototype.hasOwnProperty.call(container, key)
+      ? (container[key] as CelValue)
+      : MISSING;
+  }
+  if (isCelMap(container)) {
+    const identity = mapKeyIdentity(key);
+    if (identity === undefined) return UNSUPPORTED_KEY;
+    const entry = container.entries.get(identity);
+    return entry ? entry.value : MISSING;
+  }
+  if (Array.isArray(container)) {
+    const at = indexOf(key);
+    if (at === undefined) return UNSUPPORTED_KEY;
+    if (at < 0n || at >= BigInt(container.length)) return OUT_OF_RANGE;
+    return container[Number(at)] as CelValue;
+  }
+  if (isCelRecord(container)) return UNSUPPORTED_KEY;
+  return UNSUPPORTED_CONTAINER;
+}
+
+/** The value at a key, or the error a failed lookup is. */
+export function celRead(container: CelValue, key: CelValue, range?: SourceRange): CelValue | CelError {
+  const found = celLookup(container, key);
+  if (typeof found !== "symbol") return found;
+  return lookupError(found, key, range);
+}
+
+/** The error a refused lookup is. */
+export function lookupError(found: symbol, key: CelValue, range?: SourceRange): CelError {
+  if (found === MISSING) return celError("no_such_key", `no such key: ${describe(key)}`, range);
+  if (found === OUT_OF_RANGE) {
+    return celError("index_out_of_range", `index out of range: ${describe(key)}`, range);
+  }
+  if (found === UNSUPPORTED_KEY) {
+    return celError("unsupported_key_type", `${describe(key)} cannot name an entry of this value`, range);
+  }
+  return celError("unsupported_container", "this value holds no members", range);
+}
+
+/**
+ * Whether a key is there — `has(a.b)`. It asks about presence, so a missing key is
+ * `false` rather than the error a read would be; a container that holds no members at
+ * all is still a mistake in the question.
+ */
+export function celHas(container: CelValue, key: CelValue, range?: SourceRange): boolean | CelError {
+  const found = celLookup(container, key);
+  if (typeof found !== "symbol") return true;
+  if (found === MISSING || found === OUT_OF_RANGE) return false;
+  return lookupError(found, key, range);
+}
+
+/** The elements a comprehension ranges over: a list's items, a map's keys. */
+export function celIterable(container: CelValue, range?: SourceRange): CelValue[] | CelError {
+  if (Array.isArray(container)) return [...container];
+  if (isCelMap(container)) return celMapKeys(container);
+  if (isCelRecord(container)) return Object.keys(container);
+  return celError("unsupported_container", "a comprehension reads a list or a map", range);
+}
+
+function describe(key: CelValue): string {
+  if (typeof key === "string") return JSON.stringify(key);
+  if (isCelUint(key)) return `${key.value}`;
+  if (typeof key === "bigint") return `${key}`;
+  return String(key);
+}

package/src/namespace-resolution.ts

@@ -0,0 +1,167 @@
+/**
+ * Turning `Alias.fn(x)` into a qualified call.
+ *
+ * `Alias.fn(x)` and `obj.method(x)` are **the same syntax** — a call written on a
+ * receiver — so no parser can tell them apart, and only a set of names that denote
+ * namespaces rather than values can. That set comes from the host, which is why
+ * this is a separate total tree-to-tree pass rather than a parser rule: the parser
+ * has one input and this has two.
+ *
+ * The pass is total — it visits every node and rewrites every receiver call whose
+ * receiver is a bare identifier in the set, wherever it sits. It is also the only
+ * producer of `qcall`, and `cel` and `optional` can never be in the set, because
+ * the standard macros are written on them (`cel.bind(…)`, `optional.of(…)`) and a
+ * namespace would capture those calls instead.
+ *
+ * A resolved tree records the set it was resolved under, so a consumer given a tree
+ * can tell whether it was resolved under the set it is about to check it against —
+ * the alternative is a tree that looks resolved and silently is not.
+ */
+
+import { isIdentifierSpelling, isReservedWord } from "./reserved-words.js";
+import type { CelMapEntry, CelNode } from "./syntax-tree.js";
+
+/** Names that can never be registered as a namespace. */
+export const RESERVED_NAMESPACES: readonly string[] = ["cel", "optional"];
+
+/** A namespace set a host cannot have: the name is not a name, or is reserved. */
+export class CelNamespaceError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CelNamespaceError";
+  }
+}
+
+/**
+ * Validates a namespace set and puts it in a canonical order, so that two sets with
+ * the same names compare equal however the host listed them.
+ */
+export function normalizeNamespaces(names: Iterable<string>): readonly string[] {
+  const normalized: string[] = [];
+  for (const name of names) {
+    if (!isIdentifierSpelling(name)) {
+      throw new CelNamespaceError(`${JSON.stringify(name)} is not spelled as a name, so it names no namespace`);
+    }
+    if (isReservedWord(name)) {
+      throw new CelNamespaceError(`${JSON.stringify(name)} is a reserved word, so it names no namespace`);
+    }
+    if (RESERVED_NAMESPACES.includes(name)) {
+      throw new CelNamespaceError(
+        `${JSON.stringify(name)} is reserved: the standard macros are written on it, and a namespace would capture them`,
+      );
+    }
+    if (!normalized.includes(name)) normalized.push(name);
+  }
+  return normalized.sort();
+}
+
+export function namespaceSetsEqual(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((name, at) => name === right[at]);
+}
+
+/** Rewrites every call on a name of the set into a `qcall`. Total; shares what it does not change. */
+export function resolveNamespaces(root: CelNode, namespaces: readonly string[]): CelNode {
+  // With no namespaces the pass is the identity — nothing can match an empty set — so it
+  // answers without walking. Every site with no module names takes this path, which is why
+  // it is worth stating rather than leaving to the structural sharing below.
+  if (namespaces.length === 0) return root;
+  const resolved = mapChildren(root, (child) => resolveNamespaces(child, namespaces));
+  if (resolved.kind !== "receiverCall") return resolved;
+  const receiver = resolved.receiver;
+  // An absolute name denotes a value the environment declares, never a namespace: a
+  // namespaced call has exactly one spelling, and `.Alias.fn(x)` is not it.
+  if (receiver.kind !== "ident" || receiver.absolute || !namespaces.includes(receiver.name)) {
+    return resolved;
+  }
+  return {
+    kind: "qcall",
+    namespace: receiver.name,
+    namespaceRange: receiver.range,
+    name: resolved.name,
+    nameRange: resolved.nameRange,
+    args: resolved.args,
+    range: resolved.range,
+  };
+}
+
+/** Rebuilds a node from its mapped children, returning the original when none moved. */
+function mapChildren(node: CelNode, map: (child: CelNode) => CelNode): CelNode {
+  switch (node.kind) {
+    case "literal":
+    case "ident":
+    case "unparsed":
+      return node;
+    case "list": {
+      let moved = false;
+      const elements = node.elements.map((element) => {
+        const value = map(element.value);
+        if (value === element.value) return element;
+        moved = true;
+        return { ...element, value };
+      });
+      return moved ? { ...node, elements } : node;
+    }
+    case "map": {
+      let moved = false;
+      const entries: CelMapEntry[] = node.entries.map((entry) => {
+        const key = map(entry.key);
+        const value = map(entry.value);
+        if (key === entry.key && value === entry.value) return entry;
+        moved = true;
+        return { ...entry, key, value };
+      });
+      return moved ? { ...node, entries } : node;
+    }
+    case "select": {
+      const operand = map(node.operand);
+      return operand === node.operand ? node : { ...node, operand };
+    }
+    case "index": {
+      const operand = map(node.operand);
+      const index = map(node.index);
+      return operand === node.operand && index === node.index ? node : { ...node, operand, index };
+    }
+    case "call":
+    case "qcall": {
+      const args = mapList(node.args, map);
+      return args ? { ...node, args } : node;
+    }
+    case "receiverCall": {
+      const receiver = map(node.receiver);
+      const args = mapList(node.args, map);
+      if (receiver === node.receiver && !args) return node;
+      return { ...node, receiver, args: args ?? node.args };
+    }
+    case "unary": {
+      const operand = map(node.operand);
+      return operand === node.operand ? node : { ...node, operand };
+    }
+    case "binary": {
+      const left = map(node.left);
+      const right = map(node.right);
+      return left === node.left && right === node.right ? node : { ...node, left, right };
+    }
+    case "conditional": {
+      const condition = map(node.condition);
+      const whenTrue = map(node.whenTrue);
+      const whenFalse = map(node.whenFalse);
+      return condition === node.condition && whenTrue === node.whenTrue && whenFalse === node.whenFalse
+        ? node
+        : { ...node, condition, whenTrue, whenFalse };
+    }
+  }
+}
+
+/** The mapped list, or nothing when every element is the one it started as. */
+function mapList(
+  nodes: readonly CelNode[],
+  map: (child: CelNode) => CelNode,
+): readonly CelNode[] | undefined {
+  let moved = false;
+  const mapped = nodes.map((node) => {
+    const next = map(node);
+    if (next !== node) moved = true;
+    return next;
+  });
+  return moved ? mapped : undefined;
+}