@telorun/cel 0.0.0-stage → 0.107.0

package/src/syntax-tree.ts

@@ -0,0 +1,229 @@
+/**
+ * The canonical CEL syntax tree.
+ *
+ * Every node carries `range`, the half-open `[start, end)` span of UTF-16 code
+ * units it covers in the source it was parsed from, so a diagnostic, a hover or a
+ * rename can point at the text the author wrote. A tree built by hand carries
+ * ranges too — the serializer and the queries read them, and a node with none
+ * would make either answer silently wrong.
+ *
+ * Literals hold their decoded value in a tagged form rather than as a bare
+ * JavaScript value: CEL's `int` and `uint` are both arbitrary-magnitude integers,
+ * `1` and `1u` are different expressions, and a backend must be able to tell them
+ * apart without consulting a runtime value class.
+ *
+ * `qcall` is the one node the parser never produces — see `namespace-resolution.ts`.
+ */
+
+/** Half-open span of UTF-16 code units: `[start, end)`. */
+export type SourceRange = readonly [start: number, end: number];
+
+export type CelLiteral =
+  | { readonly type: "int"; readonly value: bigint }
+  | { readonly type: "uint"; readonly value: bigint }
+  | { readonly type: "double"; readonly value: number }
+  | { readonly type: "string"; readonly value: string }
+  | { readonly type: "bytes"; readonly value: Uint8Array }
+  | { readonly type: "bool"; readonly value: boolean }
+  | { readonly type: "null" };
+
+export type CelUnaryOperator = "!" | "-";
+
+export type CelBinaryOperator =
+  | "||"
+  | "&&"
+  | "=="
+  | "!="
+  | "<"
+  | "<="
+  | ">"
+  | ">="
+  | "in"
+  | "+"
+  | "-"
+  | "*"
+  | "/"
+  | "%";
+
+interface Ranged {
+  readonly range: SourceRange;
+}
+
+export interface CelLiteralNode extends Ranged {
+  readonly kind: "literal";
+  readonly literal: CelLiteral;
+}
+
+export interface CelIdentNode extends Ranged {
+  readonly kind: "ident";
+  readonly name: string;
+  /**
+   * `.y` — the name is resolved against the environment's own declarations, never
+   * against a name something inside the expression bound. It is the only spelling for
+   * the outer `request` where a comprehension variable is also called `request`.
+   */
+  readonly absolute: boolean;
+}
+
+/**
+ * One element of a list literal. `optional` marks `[?x]`: the element holds an
+ * `optional<T>` and contributes a `T`, and an absent one leaves no element behind.
+ */
+export interface CelListElement {
+  readonly value: CelNode;
+  readonly optional: boolean;
+}
+
+export interface CelListNode extends Ranged {
+  readonly kind: "list";
+  readonly elements: readonly CelListElement[];
+}
+
+/** One entry of a map literal. `optional` marks `{?k: v}`, as for a list element. */
+export interface CelMapEntry {
+  readonly key: CelNode;
+  readonly value: CelNode;
+  readonly optional: boolean;
+}
+
+export interface CelMapNode extends Ranged {
+  readonly kind: "map";
+  readonly entries: readonly CelMapEntry[];
+}
+
+/** `operand.field`, `operand.?field` when `optional`, `` operand.`field` `` when `quoted`. */
+export interface CelSelectNode extends Ranged {
+  readonly kind: "select";
+  readonly operand: CelNode;
+  /** The member's name, decoded: the text between the backticks for a quoted one. */
+  readonly field: string;
+  readonly fieldRange: SourceRange;
+  readonly optional: boolean;
+  /**
+   * Written between backticks, which is how a member whose name is not spelled as an
+   * identifier is read — `content-type`, `foo.txt`, `/api/v1`. It changes nothing about
+   * what is read: the name is looked up exactly as a plain member's is.
+   */
+  readonly quoted: boolean;
+}
+
+/** `operand[index]`, and `operand[?index]` when `optional`. */
+export interface CelIndexNode extends Ranged {
+  readonly kind: "index";
+  readonly operand: CelNode;
+  readonly index: CelNode;
+  readonly optional: boolean;
+}
+
+/** `name(args)`. */
+export interface CelCallNode extends Ranged {
+  readonly kind: "call";
+  readonly name: string;
+  readonly nameRange: SourceRange;
+  readonly args: readonly CelNode[];
+}
+
+/** `receiver.name(args)`, including every macro call — nothing expands one here. */
+export interface CelReceiverCallNode extends Ranged {
+  readonly kind: "receiverCall";
+  readonly receiver: CelNode;
+  readonly name: string;
+  readonly nameRange: SourceRange;
+  readonly args: readonly CelNode[];
+}
+
+/** `namespace.name(args)`, where `namespace` names a module rather than a value. */
+export interface CelQualifiedCallNode extends Ranged {
+  readonly kind: "qcall";
+  readonly namespace: string;
+  readonly namespaceRange: SourceRange;
+  readonly name: string;
+  readonly nameRange: SourceRange;
+  readonly args: readonly CelNode[];
+}
+
+export interface CelUnaryNode extends Ranged {
+  readonly kind: "unary";
+  readonly operator: CelUnaryOperator;
+  readonly operand: CelNode;
+}
+
+export interface CelBinaryNode extends Ranged {
+  readonly kind: "binary";
+  readonly operator: CelBinaryOperator;
+  readonly left: CelNode;
+  readonly right: CelNode;
+}
+
+export interface CelConditionalNode extends Ranged {
+  readonly kind: "conditional";
+  readonly condition: CelNode;
+  readonly whenTrue: CelNode;
+  readonly whenFalse: CelNode;
+}
+
+/**
+ * The hole error recovery leaves where an expression was expected and none could
+ * be read. It stands for text the parser could not make sense of, so the tree
+ * around it stays usable; it is never serializable and never evaluable.
+ */
+export interface CelUnparsedNode extends Ranged {
+  readonly kind: "unparsed";
+}
+
+export type CelNode =
+  | CelLiteralNode
+  | CelIdentNode
+  | CelListNode
+  | CelMapNode
+  | CelSelectNode
+  | CelIndexNode
+  | CelCallNode
+  | CelReceiverCallNode
+  | CelQualifiedCallNode
+  | CelUnaryNode
+  | CelBinaryNode
+  | CelConditionalNode
+  | CelUnparsedNode;
+
+/** Every child node, in source order. The single reader of a node's shape for traversal. */
+export function childNodes(node: CelNode): readonly CelNode[] {
+  switch (node.kind) {
+    case "literal":
+    case "ident":
+    case "unparsed":
+      return [];
+    case "list":
+      return node.elements.map((element) => element.value);
+    case "map":
+      return node.entries.flatMap((entry) => [entry.key, entry.value]);
+    case "select":
+      return [node.operand];
+    case "index":
+      return [node.operand, node.index];
+    case "call":
+      return node.args;
+    case "receiverCall":
+      return [node.receiver, ...node.args];
+    case "qcall":
+      return node.args;
+    case "unary":
+      return [node.operand];
+    case "binary":
+      return [node.left, node.right];
+    case "conditional":
+      return [node.condition, node.whenTrue, node.whenFalse];
+  }
+}
+
+/** Depth-first pre-order walk over the whole tree. */
+export function* walkTree(root: CelNode): Generator<CelNode> {
+  yield root;
+  for (const child of childNodes(root)) yield* walkTree(child);
+}
+
+/** Whether any node of the tree is an unparsed hole. */
+export function hasUnparsed(root: CelNode): boolean {
+  for (const node of walkTree(root)) if (node.kind === "unparsed") return true;
+  return false;
+}

package/src/timestamp-value.ts

@@ -0,0 +1,294 @@
+/**
+ * Instants: reading one, writing one, and reading a field of one in a time zone.
+ *
+ * A timestamp is whole seconds plus nanoseconds in `[0, 1e9)`, because cel-spec's own
+ * rows carry nanosecond instants (`string(timestamp('9999-12-31T23:59:59.999999999Z'))`)
+ * and no host date type holds them. The range is cel-spec's: `0001-01-01T00:00:00Z`
+ * through `9999-12-31T23:59:59.999999999Z`, and an instant outside it is an error
+ * wherever it would be built — which is exactly the answer the vectors call
+ * domain-keeping where the engine being replaced returns a date beyond year 9999.
+ *
+ * **A zone is named, never computed here.** A getter takes an IANA name or a fixed
+ * `±HH:MM` offset; the rules behind a name are the host's data, which no release of this
+ * engine fixes, so the only thing this file decides is how a name is applied.
+ */
+
+import {
+  celError,
+  CEL_VALUE_TYPE,
+  isCelError,
+  type CelError,
+  type CelTimestamp,
+} from "./cel-value.js";
+import type { SourceRange } from "./syntax-tree.js";
+
+/** `0001-01-01T00:00:00Z` and `9999-12-31T23:59:59Z`, in seconds since the epoch. */
+export const MIN_TIMESTAMP_SECONDS = -62135596800n;
+export const MAX_TIMESTAMP_SECONDS = 253402300799n;
+
+const NANOS_PER_SECOND = 1_000_000_000n;
+
+/** An instant from seconds and nanoseconds of any sign, normalized, or the range error. */
+export function celTimestamp(
+  seconds: bigint,
+  nanos: bigint | number = 0,
+  range?: SourceRange,
+): CelTimestamp | CelError {
+  const total = BigInt(nanos);
+  let whole = seconds + total / NANOS_PER_SECOND;
+  let rest = total % NANOS_PER_SECOND;
+  if (rest < 0n) {
+    whole -= 1n;
+    rest += NANOS_PER_SECOND;
+  }
+  if (whole < MIN_TIMESTAMP_SECONDS || whole > MAX_TIMESTAMP_SECONDS) {
+    return celError("invalid_conversion", "timestamp out of range", range);
+  }
+  return { [CEL_VALUE_TYPE]: "google.protobuf.Timestamp", seconds: whole, nanos: Number(rest) };
+}
+
+/** The instant's nanoseconds since the epoch — what arithmetic and ordering compare. */
+export function timestampNanos(value: CelTimestamp): bigint {
+  return value.seconds * NANOS_PER_SECOND + BigInt(value.nanos);
+}
+
+const RFC_3339 =
+  /^(\d{4})-(\d{2})-(\d{2})[Tt ](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(?:[Zz]|([+-])(\d{2}):(\d{2}))$/;
+
+/** An instant from RFC 3339 text, with any offset and any fractional precision. */
+export function parseTimestamp(text: string, range?: SourceRange): CelTimestamp | CelError {
+  const parts = RFC_3339.exec(text);
+  if (!parts) {
+    return celError("invalid_conversion", `${JSON.stringify(text)} is not an RFC 3339 instant`, range);
+  }
+  const [, year, month, day, hour, minute, second, fraction, sign, offsetHours, offsetMinutes] = parts;
+  const fields = {
+    year: Number(year),
+    month: Number(month),
+    day: Number(day),
+    hour: Number(hour),
+    minute: Number(minute),
+    second: Number(second),
+  };
+  if (
+    fields.month < 1 ||
+    fields.month > 12 ||
+    fields.day < 1 ||
+    fields.day > daysInMonth(fields.year, fields.month) ||
+    fields.hour > 23 ||
+    fields.minute > 59 ||
+    fields.second > 59
+  ) {
+    return celError("invalid_conversion", `${JSON.stringify(text)} is not an instant`, range);
+  }
+  let seconds = secondsFromFields(fields);
+  if (sign) {
+    const offset = BigInt(Number(offsetHours) * 3600 + Number(offsetMinutes) * 60);
+    seconds += sign === "-" ? offset : -offset;
+  }
+  const nanos = fraction ? Number(`${fraction}000000000`.slice(0, 9)) : 0;
+  return celTimestamp(seconds, nanos, range);
+}
+
+/**
+ * RFC 3339 in UTC, with the fraction written to the precision it carries and omitted
+ * when the instant is whole — cel-spec's own spelling (`2009-02-13T23:31:30Z`).
+ */
+export function formatTimestamp(value: CelTimestamp): string {
+  const fields = utcFields(value.seconds);
+  const date = `${pad(fields.year, 4)}-${pad(fields.month, 2)}-${pad(fields.day, 2)}`;
+  const time = `${pad(fields.hour, 2)}:${pad(fields.minute, 2)}:${pad(fields.second, 2)}`;
+  return `${date}T${time}${fractionText(value.nanos)}Z`;
+}
+
+function fractionText(nanos: number): string {
+  if (nanos === 0) return "";
+  return `.${pad(nanos, 9).replace(/0+$/, "")}`;
+}
+
+function pad(value: number, width: number): string {
+  return String(value).padStart(width, "0");
+}
+
+// --- the calendar ----------------------------------------------------------
+
+export interface CivilFields {
+  readonly year: number;
+  readonly month: number;
+  readonly day: number;
+  readonly hour: number;
+  readonly minute: number;
+  readonly second: number;
+}
+
+function isLeapYear(year: number): boolean {
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+
+const MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+function daysInMonth(year: number, month: number): number {
+  return month === 2 && isLeapYear(year) ? 29 : MONTH_DAYS[month - 1]!;
+}
+
+/** Days from the epoch to a civil date, by Howard Hinnant's `days_from_civil`. */
+function daysFromCivil(year: number, month: number, day: number): number {
+  const shifted = month <= 2 ? year - 1 : year;
+  const era = Math.floor(shifted / 400);
+  const yearOfEra = shifted - era * 400;
+  const dayOfYear = Math.floor((153 * (month + (month > 2 ? -3 : 9)) + 2) / 5) + day - 1;
+  const dayOfEra = yearOfEra * 365 + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100) + dayOfYear;
+  return era * 146097 + dayOfEra - 719468;
+}
+
+/** The civil date a day count names, the inverse of `daysFromCivil`. */
+function civilFromDays(days: number): { year: number; month: number; day: number } {
+  const shifted = days + 719468;
+  const era = Math.floor(shifted / 146097);
+  const dayOfEra = shifted - era * 146097;
+  const yearOfEra = Math.floor(
+    (dayOfEra - Math.floor(dayOfEra / 1460) + Math.floor(dayOfEra / 36524) - Math.floor(dayOfEra / 146096)) / 365,
+  );
+  const year = yearOfEra + era * 400;
+  const dayOfYear = dayOfEra - (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100));
+  const monthPrime = Math.floor((5 * dayOfYear + 2) / 153);
+  const day = dayOfYear - Math.floor((153 * monthPrime + 2) / 5) + 1;
+  const month = monthPrime + (monthPrime < 10 ? 3 : -9);
+  return { year: month <= 2 ? year + 1 : year, month, day };
+}
+
+function secondsFromFields(fields: CivilFields): bigint {
+  const days = daysFromCivil(fields.year, fields.month, fields.day);
+  return BigInt(days) * 86400n + BigInt(fields.hour * 3600 + fields.minute * 60 + fields.second);
+}
+
+function utcFields(seconds: bigint): CivilFields {
+  const days = Number(floorDiv(seconds, 86400n));
+  const rest = Number(seconds - BigInt(days) * 86400n);
+  const date = civilFromDays(days);
+  return {
+    ...date,
+    hour: Math.floor(rest / 3600),
+    minute: Math.floor((rest % 3600) / 60),
+    second: rest % 60,
+  };
+}
+
+function floorDiv(value: bigint, by: bigint): bigint {
+  const quotient = value / by;
+  return value % by < 0n ? quotient - 1n : quotient;
+}
+
+// --- zones -----------------------------------------------------------------
+
+const FIXED_OFFSET = /^([+-]?)(\d{2}):(\d{2})$/;
+
+/**
+ * The civil fields of an instant in a zone. A zone is an IANA name, resolved by the
+ * host's own tz database, or a fixed `±HH:MM` offset, which is arithmetic; an unsigned
+ * offset is read as ahead of UTC, as cel-spec's own rows read it.
+ */
+export function zonedFields(
+  value: CelTimestamp,
+  zone: string | undefined,
+  range?: SourceRange,
+): CivilFields | CelError {
+  if (zone === undefined || zone === "UTC") return utcFields(value.seconds);
+  const fixed = FIXED_OFFSET.exec(zone);
+  if (fixed) {
+    const [, sign, hours, minutes] = fixed;
+    if (Number(hours) > 23 || Number(minutes) > 59) {
+      return celError("invalid_argument", `${JSON.stringify(zone)} is not a time zone`, range);
+    }
+    const offset = BigInt(Number(hours) * 3600 + Number(minutes) * 60);
+    return utcFields(value.seconds + (sign === "-" ? -offset : offset));
+  }
+  return namedZoneFields(value, zone, range);
+}
+
+/** The host's answer for an IANA zone. Its rules are the host's data, not this engine's. */
+function namedZoneFields(
+  value: CelTimestamp,
+  zone: string,
+  range?: SourceRange,
+): CivilFields | CelError {
+  let parts: Intl.DateTimeFormatPart[];
+  try {
+    const format = new Intl.DateTimeFormat("en-US", {
+      timeZone: zone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hourCycle: "h23",
+      era: "short",
+    });
+    parts = format.formatToParts(new Date(Number(value.seconds) * 1000));
+  } catch {
+    return celError("invalid_argument", `${JSON.stringify(zone)} is not a time zone`, range);
+  }
+  const read = (type: string) => Number(parts.find((part) => part.type === type)?.value ?? Number.NaN);
+  const era = parts.find((part) => part.type === "era")?.value;
+  const year = read("year");
+  return {
+    year: era === "BC" ? 1 - year : year,
+    month: read("month"),
+    day: read("day"),
+    hour: read("hour"),
+    minute: read("minute"),
+    second: read("second"),
+  };
+}
+
+/** Which field of an instant a getter answers. The names are cel-spec's. */
+export type TimestampField =
+  | "getFullYear"
+  | "getMonth"
+  | "getDayOfYear"
+  | "getDayOfMonth"
+  | "getDate"
+  | "getDayOfWeek"
+  | "getHours"
+  | "getMinutes"
+  | "getSeconds"
+  | "getMilliseconds";
+
+/**
+ * A field of an instant. `getMonth`, `getDayOfMonth` and `getDayOfYear` are **zero
+ * based** and `getDate` is one based, which is cel-spec's own split; `getDayOfWeek`
+ * counts from Sunday.
+ */
+export function timestampField(
+  value: CelTimestamp,
+  field: TimestampField,
+  zone?: string,
+  range?: SourceRange,
+): bigint | CelError {
+  if (field === "getMilliseconds") return BigInt(Math.floor(value.nanos / 1_000_000));
+  const civil = zonedFields(value, zone, range);
+  if (isCelError(civil)) return civil;
+  switch (field) {
+    case "getFullYear":
+      return BigInt(civil.year);
+    case "getMonth":
+      return BigInt(civil.month - 1);
+    case "getDayOfMonth":
+      return BigInt(civil.day - 1);
+    case "getDate":
+      return BigInt(civil.day);
+    case "getDayOfYear":
+      return BigInt(daysFromCivil(civil.year, civil.month, civil.day) - daysFromCivil(civil.year, 1, 1));
+    case "getDayOfWeek": {
+      const days = daysFromCivil(civil.year, civil.month, civil.day);
+      return BigInt(((days % 7) + 11) % 7);
+    }
+    case "getHours":
+      return BigInt(civil.hour);
+    case "getMinutes":
+      return BigInt(civil.minute);
+    case "getSeconds":
+      return BigInt(civil.second);
+  }
+}

package/src/tree-equality.ts

@@ -0,0 +1,130 @@
+/**
+ * Whether two trees are the same expression.
+ *
+ * Ranges are **not** compared: two trees of the same expression written with
+ * different spacing or parentheses hold different offsets, and the round-trip
+ * contract (`serializer.ts`) is exactly that serializing and re-parsing gives back
+ * the same expression — not the same text.
+ *
+ * Numbers compare by identity rather than by `==`, so `-0.0` is not `0.0` and a
+ * `NaN` equals itself: both are distinct literals a round-trip must preserve.
+ */
+
+import type { CelLiteral, CelNode } from "./syntax-tree.js";
+
+function literalsEqual(left: CelLiteral, right: CelLiteral): boolean {
+  if (left.type !== right.type) return false;
+  switch (left.type) {
+    case "null":
+      return true;
+    case "int":
+    case "uint":
+      return left.value === (right as typeof left).value;
+    case "double":
+      return Object.is(left.value, (right as typeof left).value);
+    case "bool":
+    case "string":
+      return left.value === (right as typeof left).value;
+    case "bytes": {
+      const other = (right as typeof left).value;
+      return left.value.length === other.length && left.value.every((byte, at) => byte === other[at]);
+    }
+  }
+}
+
+function listsEqual(left: readonly CelNode[], right: readonly CelNode[]): boolean {
+  return left.length === right.length && left.every((node, at) => treesEqual(node, right[at]!));
+}
+
+/** Whether the two trees are the same expression, their ranges aside. */
+export function treesEqual(left: CelNode, right: CelNode): boolean {
+  if (left.kind !== right.kind) return false;
+  switch (left.kind) {
+    case "literal":
+      return literalsEqual(left.literal, (right as typeof left).literal);
+    case "ident": {
+      const other = right as typeof left;
+      // Absolute changes what the name resolves against, so it is part of the expression;
+      // whether a member was written between backticks is not.
+      return left.name === other.name && left.absolute === other.absolute;
+    }
+    case "unparsed":
+      return true;
+    case "list": {
+      const other = (right as typeof left).elements;
+      return (
+        left.elements.length === other.length &&
+        left.elements.every(
+          (element, at) =>
+            element.optional === other[at]!.optional && treesEqual(element.value, other[at]!.value),
+        )
+      );
+    }
+    case "map": {
+      const other = (right as typeof left).entries;
+      return (
+        left.entries.length === other.length &&
+        left.entries.every(
+          (entry, at) =>
+            entry.optional === other[at]!.optional &&
+            treesEqual(entry.key, other[at]!.key) &&
+            treesEqual(entry.value, other[at]!.value),
+        )
+      );
+    }
+    case "select": {
+      const other = right as typeof left;
+      return (
+        left.field === other.field &&
+        left.optional === other.optional &&
+        treesEqual(left.operand, other.operand)
+      );
+    }
+    case "index": {
+      const other = right as typeof left;
+      return (
+        left.optional === other.optional &&
+        treesEqual(left.operand, other.operand) &&
+        treesEqual(left.index, other.index)
+      );
+    }
+    case "call": {
+      const other = right as typeof left;
+      return left.name === other.name && listsEqual(left.args, other.args);
+    }
+    case "receiverCall": {
+      const other = right as typeof left;
+      return (
+        left.name === other.name &&
+        treesEqual(left.receiver, other.receiver) &&
+        listsEqual(left.args, other.args)
+      );
+    }
+    case "qcall": {
+      const other = right as typeof left;
+      return (
+        left.namespace === other.namespace && left.name === other.name && listsEqual(left.args, other.args)
+      );
+    }
+    case "unary": {
+      const other = right as typeof left;
+      return left.operator === other.operator && treesEqual(left.operand, other.operand);
+    }
+    case "binary": {
+      const other = right as typeof left;
+      return (
+        left.operator === other.operator &&
+        treesEqual(left.left, other.left) &&
+        treesEqual(left.right, other.right)
+      );
+    }
+    case "conditional": {
+      const other = right as typeof left;
+      return (
+        treesEqual(left.condition, other.condition) &&
+        treesEqual(left.whenTrue, other.whenTrue) &&
+        treesEqual(left.whenFalse, other.whenFalse)
+      );
+    }
+  }
+}