@telorun/cel 0.0.0-stage → 0.108.0

package/src/serializer.ts

@@ -0,0 +1,262 @@
+/**
+ * The tree back to CEL source.
+ *
+ * The contract is round-trip: serializing any tree the parser produced yields text
+ * that parses to an **equal** tree (`tree-equality.ts`), and a `qcall` writes back
+ * as the `Alias.fn(x)` it was read from. That is what makes a tree, rather than the
+ * author's text, something a tool may hold and hand back — a rewrite, a quick fix,
+ * a stored expression.
+ *
+ * Parentheses are placed from precedence alone, never kept from the source: the
+ * tree records structure, and the source's own parentheses are not structure.
+ *
+ * It refuses rather than guesses. A tree that cannot be written as CEL — an
+ * `unparsed` hole left by error recovery, a `NaN` double, an integer outside its
+ * type's range, a name that is not a name — throws, because text that does not
+ * parse back would make every later answer about it wrong.
+ */
+
+import { MAX_INT, MAX_UINT, MIN_INT } from "./lexer.js";
+import { isIdentifierSpelling, isReservedWord } from "./reserved-words.js";
+import type { CelLiteral, CelNode } from "./syntax-tree.js";
+
+export class CelSerializeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CelSerializeError";
+  }
+}
+
+/** Binding strength, loosest first; a child is wrapped when it binds more loosely than its slot needs. */
+const PRECEDENCE = {
+  conditional: 0,
+  or: 1,
+  and: 2,
+  relation: 3,
+  additive: 4,
+  multiplicative: 5,
+  unary: 6,
+  postfix: 7,
+  primary: 8,
+} as const;
+
+const BINARY_PRECEDENCE: Record<string, number> = {
+  "||": PRECEDENCE.or,
+  "&&": PRECEDENCE.and,
+  "==": PRECEDENCE.relation,
+  "!=": PRECEDENCE.relation,
+  "<": PRECEDENCE.relation,
+  "<=": PRECEDENCE.relation,
+  ">": PRECEDENCE.relation,
+  ">=": PRECEDENCE.relation,
+  in: PRECEDENCE.relation,
+  "+": PRECEDENCE.additive,
+  "-": PRECEDENCE.additive,
+  "*": PRECEDENCE.multiplicative,
+  "/": PRECEDENCE.multiplicative,
+  "%": PRECEDENCE.multiplicative,
+};
+
+function isNegativeNumber(literal: CelLiteral): boolean {
+  if (literal.type === "int") return literal.value < 0n;
+  if (literal.type === "double") return literal.value < 0 || Object.is(literal.value, -0);
+  return false;
+}
+
+/** A literal written with a leading `-` binds as loosely as a negation does. */
+function precedenceOf(node: CelNode): number {
+  switch (node.kind) {
+    case "literal":
+      return isNegativeNumber(node.literal) ? PRECEDENCE.unary : PRECEDENCE.primary;
+    case "ident":
+    case "list":
+    case "map":
+      return PRECEDENCE.primary;
+    case "select":
+    case "index":
+    case "call":
+    case "receiverCall":
+    case "qcall":
+      return PRECEDENCE.postfix;
+    case "unary":
+      return PRECEDENCE.unary;
+    case "binary":
+      return BINARY_PRECEDENCE[node.operator]!;
+    case "conditional":
+      return PRECEDENCE.conditional;
+    case "unparsed":
+      throw new CelSerializeError("an unparsed expression has no source to write");
+  }
+}
+
+function name(text: string, what: string): string {
+  if (!isIdentifierSpelling(text) || isReservedWord(text)) {
+    throw new CelSerializeError(`${JSON.stringify(text)} is not a name, so it cannot be written as a ${what}`);
+  }
+  return text;
+}
+
+/** A member or a called function may be named by any word, reserved or not. */
+function memberName(text: string, what: string): string {
+  if (!isIdentifierSpelling(text)) {
+    throw new CelSerializeError(`${JSON.stringify(text)} is not a name, so it cannot be written as a ${what}`);
+  }
+  return text;
+}
+
+/**
+ * A member name, between backticks where it needs them. A name that is not spelled as an
+ * identifier is quoted whether or not it was written that way, because that is the only
+ * spelling it has; a backtick inside one has none at all, so it is refused.
+ */
+function fieldName(text: string, quoted: boolean): string {
+  if (!quoted && isIdentifierSpelling(text)) return text;
+  if (text.includes("`") || text.includes("\n") || text === "") {
+    throw new CelSerializeError(`${JSON.stringify(text)} cannot be written as a member name`);
+  }
+  return `\`${text}\``;
+}
+
+function writeDouble(value: number): string {
+  if (Number.isNaN(value)) {
+    throw new CelSerializeError("a double that is not a number cannot be written as a literal");
+  }
+  if (value === Number.POSITIVE_INFINITY) return "1e999";
+  if (value === Number.NEGATIVE_INFINITY) return "-1e999";
+  const sign = value < 0 || Object.is(value, -0) ? "-" : "";
+  const text = String(Math.abs(value));
+  return `${sign}${/[.e]/.test(text) ? text : `${text}.0`}`;
+}
+
+/**
+ * A string literal, always in double quotes.
+ *
+ * **One spelling, chosen rather than remembered.** The tree records a string's VALUE and not
+ * the quote the author typed — the source's own formatting is not structure, which is the
+ * same rule that makes the serializer drop redundant parentheses — so a round trip
+ * normalizes `'x'` to `"x"`. Both are CEL and the parser reads either.
+ *
+ * The cost lands on a quick fix, which is written by rewriting the tree and serializing it
+ * back **into a YAML scalar**: a double-quoted CEL literal inside a double-quoted scalar has
+ * to be escaped, so a repair reads `!cel "a.startsWith(\"x\")"` where the author wrote
+ * `'x'`. Choosing the quote here cannot fix that — a single-quoted YAML scalar wants the
+ * opposite choice, and this engine does not know which scalar the text will land in. Picking
+ * the YAML quoting that needs no escaping is the EDITOR's, which has both halves in hand.
+ */
+function writeString(value: string): string {
+  const quote = '"';
+  let text = quote;
+  for (const unit of value) {
+    const code = unit.codePointAt(0)!;
+    if (unit === "\\") text += "\\\\";
+    else if (unit === quote) text += `\\${quote}`;
+    else if (unit === "\n") text += "\\n";
+    else if (unit === "\r") text += "\\r";
+    else if (unit === "\t") text += "\\t";
+    else if (code < 0x20 || code === 0x7f) text += `\\x${code.toString(16).padStart(2, "0")}`;
+    else text += unit;
+  }
+  return `${text}${quote}`;
+}
+
+function writeBytes(value: Uint8Array): string {
+  let text = 'b"';
+  for (const byte of value) {
+    if (byte === 0x5c) text += "\\\\";
+    else if (byte === 0x22) text += '\\"';
+    else if (byte >= 0x20 && byte <= 0x7e) text += String.fromCharCode(byte);
+    else text += `\\x${byte.toString(16).padStart(2, "0")}`;
+  }
+  return `${text}"`;
+}
+
+function writeLiteral(literal: CelLiteral): string {
+  switch (literal.type) {
+    case "int":
+      if (literal.value < MIN_INT || literal.value > MAX_INT) {
+        throw new CelSerializeError(`${literal.value} is outside the range of a 64-bit integer`);
+      }
+      return `${literal.value}`;
+    case "uint":
+      if (literal.value < 0n || literal.value > MAX_UINT) {
+        throw new CelSerializeError(`${literal.value} is outside the range of an unsigned 64-bit integer`);
+      }
+      return `${literal.value}u`;
+    case "double":
+      return writeDouble(literal.value);
+    case "string":
+      return writeString(literal.value);
+    case "bytes":
+      return writeBytes(literal.value);
+    case "bool":
+      return literal.value ? "true" : "false";
+    case "null":
+      return "null";
+  }
+}
+
+/** Writes `node` for a slot that binds at least as tightly as `needs`. */
+function write(node: CelNode, needs: number): string {
+  const text = writeNode(node);
+  return precedenceOf(node) < needs ? `(${text})` : text;
+}
+
+function writeNode(node: CelNode): string {
+  switch (node.kind) {
+    case "literal":
+      return writeLiteral(node.literal);
+    case "ident":
+      return `${node.absolute ? "." : ""}${name(node.name, "name")}`;
+    case "list":
+      return `[${node.elements
+        .map((element) => `${element.optional ? "?" : ""}${write(element.value, PRECEDENCE.conditional)}`)
+        .join(", ")}]`;
+    case "map":
+      return `{${node.entries
+        .map(
+          (entry) =>
+            `${entry.optional ? "?" : ""}${write(entry.key, PRECEDENCE.conditional)}: ${write(entry.value, PRECEDENCE.conditional)}`,
+        )
+        .join(", ")}}`;
+    case "select":
+      return `${write(node.operand, PRECEDENCE.postfix)}.${node.optional ? "?" : ""}${fieldName(node.field, node.quoted)}`;
+    case "index":
+      return `${write(node.operand, PRECEDENCE.postfix)}[${node.optional ? "?" : ""}${write(node.index, PRECEDENCE.conditional)}]`;
+    case "call":
+      return `${name(node.name, "function name")}(${writeArguments(node.args)})`;
+    case "receiverCall":
+      return `${write(node.receiver, PRECEDENCE.postfix)}.${memberName(node.name, "function name")}(${writeArguments(node.args)})`;
+    case "qcall":
+      return `${name(node.namespace, "namespace")}.${memberName(node.name, "function name")}(${writeArguments(node.args)})`;
+    case "unary":
+      return `${node.operator}${writeUnaryOperand(node.operator, node.operand)}`;
+    case "binary":
+      return `${write(node.left, BINARY_PRECEDENCE[node.operator]!)} ${node.operator} ${write(node.right, BINARY_PRECEDENCE[node.operator]! + 1)}`;
+    case "conditional":
+      return `${write(node.condition, PRECEDENCE.or)} ? ${write(node.whenTrue, PRECEDENCE.conditional)} : ${write(node.whenFalse, PRECEDENCE.conditional)}`;
+    case "unparsed":
+      throw new CelSerializeError("an unparsed expression has no source to write");
+  }
+}
+
+/**
+ * A minus directly on a non-negative numeric literal would read back as part of the
+ * literal, so it is parenthesized: `-(1)` stays a negation of one.
+ */
+function writeUnaryOperand(operator: string, operand: CelNode): string {
+  if (operator === "-" && operand.kind === "literal" && !isNegativeNumber(operand.literal)) {
+    if (operand.literal.type === "int" || operand.literal.type === "double") {
+      return `(${writeLiteral(operand.literal)})`;
+    }
+  }
+  return write(operand, PRECEDENCE.unary);
+}
+
+function writeArguments(args: readonly CelNode[]): string {
+  return args.map((argument) => write(argument, PRECEDENCE.conditional)).join(", ");
+}
+
+/** The CEL source of a tree. Throws on a tree that has none. */
+export function serializeTree(root: CelNode): string {
+  return write(root, PRECEDENCE.conditional);
+}

package/src/sha256.ts

@@ -0,0 +1,112 @@
+/**
+ * SHA-256, in this package's own code.
+ *
+ * A cache key decides which emitted module is loaded, so its hash must be
+ * collision-resistant: a collision serves another expression set's code, which is the one
+ * failure here that no retry undoes. So it is a cryptographic digest rather than a cheap
+ * checksum.
+ *
+ * It is implemented here rather than taken from a platform because of what this package
+ * is allowed to reach. `node:crypto` is a Node built-in, which the browser-safety gate
+ * refuses; `crypto.subtle.digest` is **asynchronous**, and emission happens on a path that
+ * is synchronous end to end. Sixty lines of arithmetic is the price of keeping both
+ * properties, and the digest is held to the published test vectors
+ * (`tests/emitted-module.test.ts`).
+ */
+
+import { textToBytes } from "./value-text.js";
+
+/** The first 32 bits of the cube roots of the first 64 primes. */
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const HEX = "0123456789abcdef";
+
+function rotateRight(value: number, by: number): number {
+  return (value >>> by) | (value << (32 - by));
+}
+
+/** The digest of bytes, as 64 lowercase hexadecimal characters. */
+export function sha256Hex(input: Uint8Array): string {
+  const length = input.length;
+  // The message, a 0x80 byte, zero padding to 56 mod 64, then the bit length as 64 bits.
+  const padded = new Uint8Array(((length + 72) >> 6) << 6);
+  padded.set(input);
+  padded[length] = 0x80;
+  const bits = BigInt(length) * 8n;
+  for (let at = 0; at < 8; at += 1) {
+    padded[padded.length - 1 - at] = Number((bits >> BigInt(8 * at)) & 0xffn);
+  }
+
+  const state = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  const schedule = new Uint32Array(64);
+
+  for (let block = 0; block < padded.length; block += 64) {
+    for (let at = 0; at < 16; at += 1) {
+      const from = block + at * 4;
+      schedule[at] =
+        ((padded[from]! << 24) | (padded[from + 1]! << 16) | (padded[from + 2]! << 8) | padded[from + 3]!) >>> 0;
+    }
+    for (let at = 16; at < 64; at += 1) {
+      const a = schedule[at - 15]!;
+      const b = schedule[at - 2]!;
+      const s0 = rotateRight(a, 7) ^ rotateRight(a, 18) ^ (a >>> 3);
+      const s1 = rotateRight(b, 17) ^ rotateRight(b, 19) ^ (b >>> 10);
+      schedule[at] = (schedule[at - 16]! + s0 + schedule[at - 7]! + s1) >>> 0;
+    }
+
+    let a = state[0]!;
+    let b = state[1]!;
+    let c = state[2]!;
+    let d = state[3]!;
+    let e = state[4]!;
+    let f = state[5]!;
+    let g = state[6]!;
+    let h = state[7]!;
+    for (let at = 0; at < 64; at += 1) {
+      const s1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+      const choose = (e & f) ^ (~e & g);
+      const one = (h + s1 + choose + K[at]! + schedule[at]!) >>> 0;
+      const s0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+      const majority = (a & b) ^ (a & c) ^ (b & c);
+      const two = (s0 + majority) >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = (d + one) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (one + two) >>> 0;
+    }
+    state[0] = (state[0]! + a) >>> 0;
+    state[1] = (state[1]! + b) >>> 0;
+    state[2] = (state[2]! + c) >>> 0;
+    state[3] = (state[3]! + d) >>> 0;
+    state[4] = (state[4]! + e) >>> 0;
+    state[5] = (state[5]! + f) >>> 0;
+    state[6] = (state[6]! + g) >>> 0;
+    state[7] = (state[7]! + h) >>> 0;
+  }
+
+  let out = "";
+  for (const word of state) {
+    for (let shift = 28; shift >= 0; shift -= 4) out += HEX[(word >>> shift) & 0xf];
+  }
+  return out;
+}
+
+/** The digest of text, read as UTF-8 — what every key and digest in the emitter is over. */
+export function sha256OfText(text: string): string {
+  return sha256Hex(textToBytes(text));
+}

package/src/signature.ts

@@ -0,0 +1,127 @@
+/**
+ * A function's declared shape: `size(string): int`, `string.startsWith(string): bool`.
+ *
+ * One spelling serves registration, the signature data a port reads, and the
+ * definition listing a host prints, so a signature that round-trips through text is
+ * the signature it started as.
+ *
+ * **The dispatch key excludes the return type.** That is what makes "register,
+ * override exactly, or remove" one mechanism rather than three: registering
+ * `duration(string): Money` replaces `duration(string): google.protobuf.Duration`
+ * because both answer the same call, and the engine being replaced refuses exactly
+ * this as an overlapping overload — which is why its standard library cannot be
+ * changed at all.
+ */
+
+import type { CelType } from "./cel-type.js";
+import type { CelValue } from "./cel-value.js";
+import { formatType } from "./cel-type.js";
+import type { CelImplementation } from "./runtime-library.js";
+import type { NominalResolver } from "./type-expression.js";
+import { CelTypeExpressionError, parseTypeExpression } from "./type-expression.js";
+
+export type CallForm = "global" | "receiver";
+
+export interface CelSignature {
+  readonly name: string;
+  readonly form: CallForm;
+  /** The type the call is written on, for a receiver call. */
+  readonly receiver?: CelType;
+  readonly parameters: readonly CelType[];
+  readonly returns: CelType;
+}
+
+const SIGNATURE = /^(?:(.+)\.)?([A-Za-z_][A-Za-z0-9_]*)\(([^)]*)\)\s*:\s*(.+)$/;
+
+export function parseSignature(text: string, resolveNominal?: NominalResolver): CelSignature {
+  const parts = SIGNATURE.exec(text.trim());
+  if (!parts) {
+    throw new CelTypeExpressionError(
+      `${JSON.stringify(text)} is not a signature — write 'name(a, b): r' or 'Receiver.name(a): r'`,
+    );
+  }
+  const [, receiverText, name, parameterText, returnText] = parts;
+  const parameters = splitParameters(parameterText!).map((part) =>
+    parseTypeExpression(part, resolveNominal),
+  );
+  return {
+    name: name!,
+    form: receiverText === undefined ? "global" : "receiver",
+    ...(receiverText === undefined ? {} : { receiver: parseTypeExpression(receiverText, resolveNominal) }),
+    parameters,
+    returns: parseTypeExpression(returnText!, resolveNominal),
+  };
+}
+
+/** The parameter list, split at its own commas — `map<K, V>` holds one of its own. */
+function splitParameters(text: string): string[] {
+  if (!text.trim()) return [];
+  const parts: string[] = [];
+  let depth = 0;
+  let from = 0;
+  for (let at = 0; at < text.length; at += 1) {
+    const ch = text[at];
+    if (ch === "<") depth += 1;
+    else if (ch === ">") depth -= 1;
+    else if (ch === "," && depth === 0) {
+      parts.push(text.slice(from, at));
+      from = at + 1;
+    }
+  }
+  parts.push(text.slice(from));
+  return parts;
+}
+
+export function formatSignature(signature: CelSignature): string {
+  return `${signatureKey(signature)}: ${formatType(signature.returns)}`;
+}
+
+/** What two registrations of the same call share: the name, the form and the parameters. */
+export function signatureKey(signature: CelSignature): string {
+  const on = signature.receiver ? `${formatType(signature.receiver)}.` : "";
+  return `${on}${signature.name}(${signature.parameters.map((type) => formatType(type)).join(", ")})`;
+}
+
+/**
+ * Checking the arguments a call wrote as LITERALS, where a type cannot say enough.
+ *
+ * A signature constrains types, so a guard over a VALUE — an unparseable format
+ * specifier, a decimal count out of range, an unknown time zone, a pattern the regular
+ * expression engine refuses — would otherwise fire only when the expression is evaluated,
+ * which puts a defect the source states in plain sight behind a run. A registration that
+ * carries one is asked at the call site the checker has just resolved, and a refusal is
+ * `CEL_INVALID_ARGUMENT` with the call's own range.
+ *
+ * `literals[at]` is the value of argument `at` where it was written as a literal — the
+ * receiver first, for a call written on a value, so the positions are the ones the
+ * implementation sees — and `undefined` where the argument is an expression whose value
+ * is not statically known, which a guard must SKIP rather than judge. The answer is the
+ * refusal, or nothing where there is none. A guard runs the same code the evaluation
+ * runs, so the static and dynamic answers cannot drift into disagreement.
+ */
+export type LiteralArgumentCheck = (
+  literals: readonly (CelValue | undefined)[],
+) => string | undefined;
+
+/** What a host declares about a function beyond its types. */
+export interface FunctionMetadata {
+  /**
+   * What the function does. The standard library's behaviour is looked up by dispatch
+   * key instead (`runtime-library.ts`), so a registration carries one only where the
+   * host supplies it; a call that resolves to a registration with neither is
+   * `unbound_function` at evaluation. The type is not thenable, so an implementation
+   * that answers asynchronously does not compile.
+   */
+  readonly implementation?: CelImplementation;
+  /** A guard over the arguments written as literals, asked where the checker resolves the call. */
+  readonly checkArguments?: LiteralArgumentCheck;
+  /** Whether two calls with the same arguments answer the same thing. Default true. */
+  readonly deterministic?: boolean;
+  /** Whether the implementation is supplied by the host rather than the engine. */
+  readonly hostBacked?: boolean;
+  /** The error codes a call may fail with. */
+  readonly throws?: readonly string[];
+  readonly description?: string;
+  /** Where the registration came from, for a listing a human reads. */
+  readonly origin?: string;
+}