@telorun/cel 0.0.0-stage → 0.108.0

package/src/reserved-words.ts

@@ -0,0 +1,94 @@
+/**
+ * The words no CEL identifier may be: cel-spec's `RESERVED` production, which its
+ * `IDENT` production excludes. All 21 of them.
+ *
+ * The set is frozen deliberately: a word added here stops a manifest that uses it as
+ * a variable or a function name from parsing, so it is widened only with a
+ * deprecation behind it.
+ *
+ * **Three of the 21 are refused by being read as something else**, and the
+ * distinction is the lexer's whole policy about words, so it lives here rather than
+ * there. `true`, `false` and `null` are literals; `in` is the membership operator.
+ * Neither reading can be reached from a name position, which is why cel-spec needs
+ * them in `RESERVED` and why an engine must not quietly accept one as a name — doing
+ * so breaks the premise every consumer of the set is written against.
+ *
+ * **A reserved word is refused as an IDENTIFIER, not as a member name.** CEL's own
+ * conformance suite reads `{'let': 1}.let` and `a.while()`; `a.in` and `a.true` are
+ * the same position, and read for the same reason. A member name is a name of a
+ * value's entry, not a name in the expression's scope.
+ *
+ * **No host's property names are here.** A member *name* is written by the author; a
+ * member *key* can come from a request (`a[request.query.k]`), so a word list cannot
+ * be what keeps a host's property out of a CEL value — it does not touch the computed
+ * form at all. That guarantee belongs to the member-read operation, which resolves
+ * every form against the value's own entries and never performs a host property read.
+ * `constructor` never being on any such list is the same point made by its absence.
+ *
+ * `cel` and `optional` are legal identifiers, reserved only against being registered
+ * as a namespace (`namespace-resolution.ts`), because the standard macros are written
+ * on them (`cel.bind`, `optional.of`).
+ */
+
+export const RESERVED_WORDS: readonly string[] = [
+  "as",
+  "break",
+  "const",
+  "continue",
+  "else",
+  "false",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "let",
+  "loop",
+  "namespace",
+  "null",
+  "package",
+  "return",
+  "true",
+  "var",
+  "void",
+  "while",
+];
+
+/** The reserved words that are a literal where they stand. */
+export const LITERAL_WORDS: readonly string[] = ["true", "false", "null"];
+
+/** The reserved words that are an operator where they stand. */
+export const OPERATOR_WORDS: readonly string[] = ["in"];
+
+const RESERVED = new Set(RESERVED_WORDS);
+const LITERALS = new Set(LITERAL_WORDS);
+const OPERATORS = new Set(OPERATOR_WORDS);
+
+/** How a word is read where an expression begins. */
+export type WordReading =
+  /** An ordinary identifier. */
+  | "name"
+  /** A literal value: `true`, `false`, `null`. */
+  | "literal"
+  /** An operator written as a word: `in`. */
+  | "operator"
+  /** Reserved, with no other reading — refused wherever a name is read. */
+  | "refused";
+
+export function wordReading(text: string): WordReading {
+  if (LITERALS.has(text)) return "literal";
+  if (OPERATORS.has(text)) return "operator";
+  return RESERVED.has(text) ? "refused" : "name";
+}
+
+/** Whether the word is one cel-spec reserves, however it is read. */
+export function isReservedWord(name: string): boolean {
+  return RESERVED.has(name);
+}
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Whether the text is spelled as a CEL identifier, reserved or not. */
+export function isIdentifierSpelling(text: string): boolean {
+  return IDENTIFIER.test(text);
+}

package/src/resolved-call.ts

@@ -0,0 +1,47 @@
+/**
+ * Which function each call in an expression resolved to.
+ *
+ * A host needs this for policy the engine cannot know: whether a non-deterministic call
+ * sits in a field evaluated once at startup, whether a call reaches the host at all,
+ * which error codes a call can fail with. All three are properties of the **resolved**
+ * signature, not of the name written — two overloads of one name can differ in every
+ * one of them — so the answer has to come from the checker, which is what resolved it.
+ *
+ * **It is the checker's lowering, not the tree.** A macro is not a dispatch and is not
+ * listed: `xs.map(i, i)` becomes a comprehension and reaches no function, while the
+ * calls written inside it are listed where they are written. A list read off the tree
+ * would instead report whatever the reader's parser happened to expand.
+ */
+
+import type { CallForm } from "./signature.js";
+import type { SourceRange } from "./syntax-tree.js";
+
+export interface ResolvedCall {
+  /** The name as written — `<namespace>.<name>` for a namespaced call. */
+  readonly name: string;
+  readonly form: CallForm;
+  /** Set only for a namespaced call. */
+  readonly namespace?: string;
+  readonly arity: number;
+  readonly range: SourceRange;
+  /** The signature it resolved to, absent where nothing resolved. */
+  readonly signature?: string;
+  /** The type the call answers here, with type parameters substituted. */
+  readonly returns?: string;
+  readonly deterministic?: boolean;
+  readonly hostBacked?: boolean;
+  readonly throws?: readonly string[];
+  /**
+   * Each argument's own type, for a NAMESPACED call only.
+   *
+   * The host judges such a call against its own, richer signature grammar — a JSON Schema
+   * per parameter, an optional trailing parameter — so it needs what was actually passed.
+   * It cannot re-derive it: checking an argument's subtree on its own loses whatever the
+   * expression bound around it, so an argument inside a comprehension (`xs.map(i,
+   * Billing.total(i))`) would type as `dyn` and the host's argument check would silently
+   * stop asking. Here the types come from the same pass that typed the call.
+   *
+   * Absent for a call the registry resolved: its parameter types are the signature's.
+   */
+  readonly argumentTypes?: readonly string[];
+}

package/src/root-references.ts

@@ -0,0 +1,126 @@
+/**
+ * What an expression reads from its environment.
+ *
+ * The answer is the first identifier of every access chain — `request` in
+ * `request.query.limit`, `xs` in `xs[0].id` — with three exclusions, each of which
+ * would otherwise invent a dependency the expression does not have:
+ *
+ * - a name a comprehension or `cel.bind` binds, which the expression supplies itself;
+ * - the namespace of a qualified call, which names a module rather than a value;
+ * - the receiver of a call on a reserved namespace (`cel.bind(…)`, `optional.of(…)`),
+ *   for the same reason.
+ *
+ * A function name is not an identifier node at all, so no call name can be mistaken
+ * for a read. Field names are not nodes either, which is why only the root of a
+ * chain is answered.
+ *
+ * The result is sorted and deduplicated: it is a set of names, and a consumer that
+ * compares two expressions' reads must not see an ordering difference.
+ */
+
+import { namespaceMacroBinding, receiverMacroBinding } from "./comprehension-bindings.js";
+import { RESERVED_NAMESPACES } from "./namespace-resolution.js";
+import type { CelNode } from "./syntax-tree.js";
+
+class BoundNames {
+  private readonly depth = new Map<string, number>();
+
+  bind(name: string): void {
+    this.depth.set(name, (this.depth.get(name) ?? 0) + 1);
+  }
+
+  unbind(name: string): void {
+    const held = this.depth.get(name)!;
+    if (held === 1) this.depth.delete(name);
+    else this.depth.set(name, held - 1);
+  }
+
+  has(name: string): boolean {
+    return this.depth.has(name);
+  }
+}
+
+/** Every name the expression reads from its environment, sorted. */
+export function rootReferences(root: CelNode): readonly string[] {
+  const found = new Set<string>();
+  collect(root, new BoundNames(), found);
+  return [...found].sort();
+}
+
+function collect(node: CelNode, bound: BoundNames, found: Set<string>): void {
+  switch (node.kind) {
+    case "ident":
+      // An absolute name reads past every binding by construction, so a binding of the
+      // same name says nothing about it.
+      if (node.absolute || !bound.has(node.name)) found.add(node.name);
+      return;
+    case "literal":
+    case "unparsed":
+      return;
+    case "receiverCall":
+      collectCall(node, bound, found);
+      return;
+    case "list":
+      for (const element of node.elements) collect(element.value, bound, found);
+      return;
+    case "map":
+      for (const entry of node.entries) {
+        collect(entry.key, bound, found);
+        collect(entry.value, bound, found);
+      }
+      return;
+    case "select":
+      collect(node.operand, bound, found);
+      return;
+    case "index":
+      collect(node.operand, bound, found);
+      collect(node.index, bound, found);
+      return;
+    case "call":
+    case "qcall":
+      for (const argument of node.args) collect(argument, bound, found);
+      return;
+    case "unary":
+      collect(node.operand, bound, found);
+      return;
+    case "binary":
+      collect(node.left, bound, found);
+      collect(node.right, bound, found);
+      return;
+    case "conditional":
+      collect(node.condition, bound, found);
+      collect(node.whenTrue, bound, found);
+      collect(node.whenFalse, bound, found);
+      return;
+  }
+}
+
+function collectCall(
+  node: Extract<CelNode, { kind: "receiverCall" }>,
+  bound: BoundNames,
+  found: Set<string>,
+): void {
+  const receiver = node.receiver;
+  const onNamespace = receiver.kind === "ident" && RESERVED_NAMESPACES.includes(receiver.name);
+  const binding = onNamespace
+    ? namespaceMacroBinding((receiver as { name: string }).name, node.name, node.args.length)
+    : receiverMacroBinding(node.name, node.args.length);
+  if (!onNamespace) collect(receiver, bound, found);
+
+  const variable = binding ? node.args[binding.variableArgument] : undefined;
+  if (!binding || variable?.kind !== "ident") {
+    for (const argument of node.args) collect(argument, bound, found);
+    return;
+  }
+
+  for (const [at, argument] of node.args.entries()) {
+    if (at === binding.variableArgument || binding.scopedArguments.includes(at)) continue;
+    collect(argument, bound, found);
+  }
+  bound.bind(variable.name);
+  for (const at of binding.scopedArguments) {
+    const argument = node.args[at];
+    if (argument) collect(argument, bound, found);
+  }
+  bound.unbind(variable.name);
+}