@telorun/cel 0.0.0-stage → 0.108.0

package/dist/signatures/standard-library.json

@@ -0,0 +1,229 @@
+{
+    "generation": 1,
+    "description": "CEL's own standard library, as declarations. No implementation, no host vocabulary.",
+    "typeConstants": ["bool", "bytes", "double", "int", "list", "map", "null_type", "string", "type", "uint"],
+    "constants": [
+        {
+            "name": "google",
+            "type": "map<string, map<string, type>>",
+            "description": "The well-known type names, so that type(x) == google.protobuf.Timestamp can be written."
+        }
+    ],
+    "functions": [
+        { "signature": "bool(bool): bool" },
+        { "signature": "bool(string): bool" },
+        { "signature": "bytes(bytes): bytes" },
+        { "signature": "bytes(string): bytes" },
+        { "signature": "double(double): double" },
+        { "signature": "double(int): double" },
+        { "signature": "double(uint): double" },
+        { "signature": "double(string): double" },
+        { "signature": "duration(string): google.protobuf.Duration" },
+        { "signature": "duration(google.protobuf.Duration): google.protobuf.Duration" },
+        { "signature": "dyn(A): dyn" },
+        { "signature": "int(int): int" },
+        { "signature": "int(uint): int" },
+        { "signature": "int(double): int" },
+        { "signature": "int(string): int" },
+        { "signature": "int(google.protobuf.Timestamp): int" },
+        { "signature": "int(google.protobuf.Duration): int" },
+        { "signature": "matches(string, string): bool" },
+        { "signature": "size(string): int" },
+        { "signature": "size(bytes): int" },
+        { "signature": "size(list<A>): int" },
+        { "signature": "size(map<K, V>): int" },
+        { "signature": "string(string): string" },
+        { "signature": "string(bool): string" },
+        { "signature": "string(int): string" },
+        { "signature": "string(uint): string" },
+        { "signature": "string(double): string" },
+        { "signature": "string(bytes): string" },
+        { "signature": "string(google.protobuf.Timestamp): string" },
+        { "signature": "string(google.protobuf.Duration): string" },
+        { "signature": "timestamp(string): google.protobuf.Timestamp" },
+        { "signature": "timestamp(int): google.protobuf.Timestamp" },
+        { "signature": "timestamp(google.protobuf.Timestamp): google.protobuf.Timestamp" },
+        { "signature": "type(int): type" },
+        { "signature": "type(uint): type" },
+        { "signature": "type(double): type" },
+        { "signature": "type(bool): type" },
+        { "signature": "type(string): type" },
+        { "signature": "type(bytes): type" },
+        { "signature": "type(null): type" },
+        { "signature": "type(type): type" },
+        { "signature": "type(list<A>): type" },
+        { "signature": "type(map<K, V>): type" },
+        { "signature": "type(google.protobuf.Timestamp): type" },
+        { "signature": "type(google.protobuf.Duration): type" },
+        { "signature": "uint(uint): uint" },
+        { "signature": "uint(int): uint" },
+        { "signature": "uint(double): uint" },
+        { "signature": "uint(string): uint" },
+        { "signature": "string.size(): int" },
+        { "signature": "bytes.size(): int" },
+        { "signature": "list<A>.size(): int" },
+        { "signature": "map<K, V>.size(): int" },
+        { "signature": "string.startsWith(string): bool" },
+        { "signature": "string.endsWith(string): bool" },
+        { "signature": "string.contains(string): bool" },
+        { "signature": "string.matches(string): bool" },
+        { "signature": "string.lowerAscii(): string", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member differs from it: despite its name it lowercases every letter the host language's own casing lowercases, not the ASCII letters alone, so 'TacoC\u00c6t'.lowerAscii() answers 'tacoc\u00e6t' where the extension answers 'tacoc\u00c6t'. Kept, with that behaviour, for the manifests already written against it" },
+        { "signature": "string.upperAscii(): string", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member differs from it: despite its name it uppercases every letter the host language's own casing uppercases, not the ASCII letters alone. Kept, with that behaviour, for the manifests already written against it" },
+        { "signature": "string.trim(): string", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member differs from it: the characters it trims are the host language's own whitespace set, which is not the extension's (U+0085 is trimmed by one and not the other). Kept for the manifests already written against it" },
+        { "signature": "string.indexOf(string): int", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member differs from it: indices are UTF-16 CODE UNITS, not code points, so a string holding a character outside the basic plane is indexed differently than the extension indexes it \u2014 a port that read this member as the extension's would index by rune and silently change the answer of every manifest that cuts a string. Kept for the manifests already written against it" },
+        { "signature": "string.indexOf(string, int): int", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member differs from it: indices are UTF-16 CODE UNITS, not code points, so a string holding a character outside the basic plane is indexed differently than the extension indexes it \u2014 a port that read this member as the extension's would index by rune and silently change the answer of every manifest that cuts a string, and the index it takes is one too. Kept for the manifests already written against it" },
+        { "signature": "string.lastIndexOf(string): int", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member differs from it: indices are UTF-16 CODE UNITS, not code points, so a string holding a character outside the basic plane is indexed differently than the extension indexes it \u2014 a port that read this member as the extension's would index by rune and silently change the answer of every manifest that cuts a string. Kept for the manifests already written against it" },
+        { "signature": "string.lastIndexOf(string, int): int", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member differs from it: indices are UTF-16 CODE UNITS, not code points, so a string holding a character outside the basic plane is indexed differently than the extension indexes it \u2014 a port that read this member as the extension's would index by rune and silently change the answer of every manifest that cuts a string, and the index it takes is one too. Kept for the manifests already written against it" },
+        { "signature": "string.substring(int): string", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member differs from it: indices are UTF-16 CODE UNITS, not code points, so a string holding a character outside the basic plane is indexed differently than the extension indexes it \u2014 a port that read this member as the extension's would index by rune and silently change the answer of every manifest that cuts a string. Kept for the manifests already written against it \u2014 and because an index may fall between the halves of a surrogate pair, this member can build a string holding a lone surrogate, which is outside the CEL value domain and which the conformance encoding refuses by contract" },
+        { "signature": "string.substring(int, int): string", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member differs from it: indices are UTF-16 CODE UNITS, not code points, so a string holding a character outside the basic plane is indexed differently than the extension indexes it \u2014 a port that read this member as the extension's would index by rune and silently change the answer of every manifest that cuts a string. Kept for the manifests already written against it \u2014 and because an index may fall between the halves of a surrogate pair, this member can build a string holding a lone surrogate, which is outside the CEL value domain and which the conformance encoding refuses by contract" },
+        { "signature": "string.split(string): list<string>", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member differs from it: an empty separator splits into UTF-16 code units rather than code points, so a character outside the basic plane comes apart. Kept for the manifests already written against it" },
+        { "signature": "string.split(string, int): list<string>", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member differs from it as the one-argument form does, and a negative limit takes every part, zero takes none and a positive one keeps the remainder in the last. Kept for the manifests already written against it" },
+        { "signature": "list<string>.join(): string", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member computes what that equivalent computes, which is exactly why it is declared here: CEL defines no join, so a port must not take this one for CEL's. Kept for the manifests already written against it" },
+        { "signature": "list<string>.join(string): string", "spec": false, "reason": "cel-spec's standard definitions over strings are size, startsWith, endsWith, matches, contains and concatenation, and nothing else; the strings extension has an equivalent, which Telo does not ship. This member computes what that equivalent computes; CEL defines no join, so a port must not take this one for CEL's. Kept for the manifests already written against it" },
+        { "signature": "bytes.string(): string", "spec": false, "reason": "CEL converts bytes to text as string(bytes); this member form is the engine being replaced's own, kept for the manifests written against it" },
+        { "signature": "bytes.hex(): string", "spec": false, "reason": "no CEL library renders bytes as hexadecimal; kept for the manifests written against it" },
+        { "signature": "bytes.base64(): string", "spec": false, "reason": "CEL encodes base64 through its encoders extension, which this engine does not carry; kept for the manifests written against it" },
+        { "signature": "bytes.json(): dyn", "spec": false, "reason": "no CEL library parses JSON; kept for the manifests written against it", "deterministic": true },
+        { "signature": "bytes.at(int): int", "spec": false, "reason": "no CEL library indexes bytes by a member call; kept for the manifests written against it" },
+        { "signature": "google.protobuf.Timestamp.getDate(): int" },
+        { "signature": "google.protobuf.Timestamp.getDate(string): int" },
+        { "signature": "google.protobuf.Timestamp.getDayOfMonth(): int" },
+        { "signature": "google.protobuf.Timestamp.getDayOfMonth(string): int" },
+        { "signature": "google.protobuf.Timestamp.getDayOfWeek(): int" },
+        { "signature": "google.protobuf.Timestamp.getDayOfWeek(string): int" },
+        { "signature": "google.protobuf.Timestamp.getDayOfYear(): int" },
+        { "signature": "google.protobuf.Timestamp.getDayOfYear(string): int" },
+        { "signature": "google.protobuf.Timestamp.getFullYear(): int" },
+        { "signature": "google.protobuf.Timestamp.getFullYear(string): int" },
+        { "signature": "google.protobuf.Timestamp.getHours(): int" },
+        { "signature": "google.protobuf.Timestamp.getHours(string): int" },
+        { "signature": "google.protobuf.Timestamp.getMilliseconds(): int" },
+        { "signature": "google.protobuf.Timestamp.getMilliseconds(string): int" },
+        { "signature": "google.protobuf.Timestamp.getMinutes(): int" },
+        { "signature": "google.protobuf.Timestamp.getMinutes(string): int" },
+        { "signature": "google.protobuf.Timestamp.getMonth(): int" },
+        { "signature": "google.protobuf.Timestamp.getMonth(string): int" },
+        { "signature": "google.protobuf.Timestamp.getSeconds(): int" },
+        { "signature": "google.protobuf.Timestamp.getSeconds(string): int" },
+        { "signature": "google.protobuf.Duration.getHours(): int" },
+        { "signature": "google.protobuf.Duration.getMinutes(): int" },
+        { "signature": "google.protobuf.Duration.getSeconds(): int" },
+        { "signature": "google.protobuf.Duration.getMilliseconds(): int" }
+    ],
+    "optionalTypeConstants": ["optional_type"],
+    "optionalTypeOperators": [
+        { "operator": "==", "parameters": ["optional<A>", "optional<A>"], "returns": "bool" },
+        { "operator": "!=", "parameters": ["optional<A>", "optional<A>"], "returns": "bool" }
+    ],
+    "optionalTypeFunctions": [
+        { "signature": "type(optional<A>): type" },
+        { "signature": "optional<A>.hasValue(): bool" },
+        { "signature": "optional<A>.value(): A" },
+        { "signature": "optional<A>.or(optional<A>): optional<A>" },
+        { "signature": "optional<A>.orValue(A): A" }
+    ],
+    "operators": [
+        { "operator": "!", "parameters": ["bool"], "returns": "bool" },
+        { "operator": "-", "parameters": ["int"], "returns": "int" },
+        { "operator": "-", "parameters": ["double"], "returns": "double" },
+        { "operator": "+", "parameters": ["int", "int"], "returns": "int" },
+        { "operator": "+", "parameters": ["uint", "uint"], "returns": "uint" },
+        { "operator": "+", "parameters": ["double", "double"], "returns": "double" },
+        { "operator": "+", "parameters": ["string", "string"], "returns": "string" },
+        { "operator": "+", "parameters": ["bytes", "bytes"], "returns": "bytes" },
+        { "operator": "+", "parameters": ["list<A>", "list<A>"], "returns": "list<A>" },
+        {
+            "operator": "+",
+            "parameters": ["google.protobuf.Timestamp", "google.protobuf.Duration"],
+            "returns": "google.protobuf.Timestamp"
+        },
+        {
+            "operator": "+",
+            "parameters": ["google.protobuf.Duration", "google.protobuf.Timestamp"],
+            "returns": "google.protobuf.Timestamp"
+        },
+        {
+            "operator": "+",
+            "parameters": ["google.protobuf.Duration", "google.protobuf.Duration"],
+            "returns": "google.protobuf.Duration"
+        },
+        { "operator": "-", "parameters": ["int", "int"], "returns": "int" },
+        { "operator": "-", "parameters": ["uint", "uint"], "returns": "uint" },
+        { "operator": "-", "parameters": ["double", "double"], "returns": "double" },
+        {
+            "operator": "-",
+            "parameters": ["google.protobuf.Timestamp", "google.protobuf.Timestamp"],
+            "returns": "google.protobuf.Duration"
+        },
+        {
+            "operator": "-",
+            "parameters": ["google.protobuf.Timestamp", "google.protobuf.Duration"],
+            "returns": "google.protobuf.Timestamp"
+        },
+        {
+            "operator": "-",
+            "parameters": ["google.protobuf.Duration", "google.protobuf.Duration"],
+            "returns": "google.protobuf.Duration"
+        },
+        { "operator": "*", "parameters": ["int", "int"], "returns": "int" },
+        { "operator": "*", "parameters": ["uint", "uint"], "returns": "uint" },
+        { "operator": "*", "parameters": ["double", "double"], "returns": "double" },
+        { "operator": "/", "parameters": ["int", "int"], "returns": "int" },
+        { "operator": "/", "parameters": ["uint", "uint"], "returns": "uint" },
+        { "operator": "/", "parameters": ["double", "double"], "returns": "double" },
+        { "operator": "%", "parameters": ["int", "int"], "returns": "int" },
+        { "operator": "%", "parameters": ["uint", "uint"], "returns": "uint" },
+        { "operator": "in", "parameters": ["A", "list<A>"], "returns": "bool" },
+        { "operator": "in", "parameters": ["K", "map<K, V>"], "returns": "bool" }
+    ],
+    "symmetricOperators": [
+        {
+            "operators": ["==", "!="],
+            "types": [
+                "int",
+                "uint",
+                "double",
+                "bool",
+                "string",
+                "bytes",
+                "null",
+                "type",
+                "list<A>",
+                "map<K, V>",
+                "google.protobuf.Timestamp",
+                "google.protobuf.Duration"
+            ],
+            "returns": "bool",
+            "description": "Equality is declared per type: two values of unrelated types are not compared, and an optional is not compared at all."
+        },
+        {
+            "operators": ["<", "<=", ">", ">="],
+            "types": [
+                "int",
+                "uint",
+                "double",
+                "bool",
+                "string",
+                "bytes",
+                "google.protobuf.Timestamp",
+                "google.protobuf.Duration"
+            ],
+            "returns": "bool",
+            "description": "CEL orders every scalar type. A list and a map are comparable for equality alone."
+        }
+    ],
+    "crossNumericOperators": {
+        "operators": ["<", "<=", ">", ">="],
+        "pairs": [
+            ["int", "uint"],
+            ["int", "double"],
+            ["uint", "int"],
+            ["uint", "double"],
+            ["double", "int"],
+            ["double", "uint"]
+        ],
+        "returns": "bool",
+        "spec": false,
+        "reason": "CEL's checker is strict about the numeric types — its own suite writes dyn(1) < 2u precisely because of that — so ordering across them is an extension of what the language accepts at check time, kept because manifests rely on it. It never computes across them, and equality across them stays refused."
+    }
+}

package/dist/standard-library.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Loading CEL's standard library into an environment.
+ *
+ * The library is **data** (`signatures/standard-library.json`) read through the same
+ * registration surface a host uses, with no privileged path of any kind. That is what
+ * makes a standard signature replaceable and removable, which is the capability the
+ * package exists for: an engine whose library registers itself through a private door
+ * cannot have one of its signatures overridden, and an override is how a host gives
+ * `duration(string)` a type of its own.
+ *
+ * Nothing here is an implementation — the library's declarations and its behaviour are
+ * separate concerns, and a checker needs only the first.
+ */
+import type { CelType } from "./cel-type.js";
+import type { FunctionRegistry } from "./function-registry.js";
+import type { NominalResolver } from "./type-expression.js";
+export declare const STANDARD_LIBRARY_GENERATION: number;
+/** A constant the standard library declares: its name and the type it reads as. */
+export interface StandardConstant {
+    readonly name: string;
+    readonly type: CelType;
+    readonly description?: string;
+}
+/**
+ * Every name the library declares as a constant: the type names (`int`, `list`, …),
+ * each of type `type`, and `google`, through which the well-known type names are read.
+ */
+export declare function standardConstants(optionalTypes: boolean): readonly StandardConstant[];
+/** The value `google` reads as: the two well-known type names, as type values. */
+export declare function googleTypeNames(): ReadonlyMap<string, readonly string[]>;
+/**
+ * Registers the library onto a registry. `optionalTypes` adds the optional-type
+ * members, which exist only where the option enables them.
+ */
+export declare function registerStandardLibrary(registry: FunctionRegistry, options: {
+    optionalTypes: boolean;
+    resolveNominal?: NominalResolver;
+}): void;
+/** Every signature of the library as text, for a validator and for a docs listing. */
+export declare function standardLibrarySignatures(): readonly string[];
+//# sourceMappingURL=standard-library.d.ts.map

package/dist/standard-library.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-library.d.ts","sourceRoot":"","sources":["../src/standard-library.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AA6C5D,eAAO,MAAM,2BAA2B,QAAkB,CAAC;AAE3D,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,OAAO,GAAG,SAAS,gBAAgB,EAAE,CASrF;AAED,kFAAkF;AAClF,wBAAgB,eAAe,IAAI,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAExE;AAQD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE;IAAE,aAAa,EAAE,OAAO,CAAC;IAAC,cAAc,CAAC,EAAE,eAAe,CAAA;CAAE,GACpE,IAAI,CAwBN;AAcD,sFAAsF;AACtF,wBAAgB,yBAAyB,IAAI,SAAS,MAAM,EAAE,CAE7D"}

package/dist/standard-library.js

@@ -0,0 +1,85 @@
+/**
+ * Loading CEL's standard library into an environment.
+ *
+ * The library is **data** (`signatures/standard-library.json`) read through the same
+ * registration surface a host uses, with no privileged path of any kind. That is what
+ * makes a standard signature replaceable and removable, which is the capability the
+ * package exists for: an engine whose library registers itself through a private door
+ * cannot have one of its signatures overridden, and an override is how a host gives
+ * `duration(string)` a type of its own.
+ *
+ * Nothing here is an implementation — the library's declarations and its behaviour are
+ * separate concerns, and a checker needs only the first.
+ */
+import library from "./signatures/standard-library.json" with { type: "json" };
+import { TYPE } from "./cel-type.js";
+import { parseSignature } from "./signature.js";
+import { parseTypeExpression } from "./type-expression.js";
+const DATA = library;
+export const STANDARD_LIBRARY_GENERATION = DATA.generation;
+/**
+ * Every name the library declares as a constant: the type names (`int`, `list`, …),
+ * each of type `type`, and `google`, through which the well-known type names are read.
+ */
+export function standardConstants(optionalTypes) {
+    const names = [...DATA.typeConstants, ...(optionalTypes ? DATA.optionalTypeConstants : [])];
+    const types = names.map((name) => ({ name, type: TYPE }));
+    const named = DATA.constants.map((entry) => ({
+        name: entry.name,
+        type: parseTypeExpression(entry.type),
+        ...(entry.description === undefined ? {} : { description: entry.description }),
+    }));
+    return [...types, ...named];
+}
+/** The value `google` reads as: the two well-known type names, as type values. */
+export function googleTypeNames() {
+    return new Map([["protobuf", ["Duration", "Timestamp"]]]);
+}
+const metadataOf = (entry) => ({
+    deterministic: entry.deterministic ?? true,
+    origin: "standard-library",
+    ...(entry.description === undefined ? {} : { description: entry.description }),
+});
+/**
+ * Registers the library onto a registry. `optionalTypes` adds the optional-type
+ * members, which exist only where the option enables them.
+ */
+export function registerStandardLibrary(registry, options) {
+    for (const entry of DATA.functions) {
+        registry.register(parseSignature(entry.signature, options.resolveNominal), metadataOf(entry));
+    }
+    if (options.optionalTypes) {
+        for (const entry of DATA.optionalTypeFunctions) {
+            registry.register(parseSignature(entry.signature, options.resolveNominal), metadataOf(entry));
+        }
+        for (const entry of DATA.optionalTypeOperators)
+            registerOperatorData(registry, entry);
+    }
+    for (const entry of DATA.operators)
+        registerOperatorData(registry, entry);
+    for (const group of DATA.symmetricOperators) {
+        for (const operator of group.operators) {
+            for (const type of group.types) {
+                registerOperatorData(registry, { operator, parameters: [type, type], returns: group.returns });
+            }
+        }
+    }
+    const cross = DATA.crossNumericOperators;
+    for (const operator of cross.operators) {
+        for (const [left, right] of cross.pairs) {
+            registerOperatorData(registry, { operator, parameters: [left, right], returns: cross.returns });
+        }
+    }
+}
+function registerOperatorData(registry, entry) {
+    registry.register({
+        name: entry.operator,
+        form: "global",
+        parameters: entry.parameters.map((text) => parseTypeExpression(text)),
+        returns: parseTypeExpression(entry.returns),
+    }, { deterministic: true, origin: "standard-library" });
+}
+/** Every signature of the library as text, for a validator and for a docs listing. */
+export function standardLibrarySignatures() {
+    return [...DATA.functions, ...DATA.optionalTypeFunctions].map((entry) => entry.signature);
+}

package/dist/syntax-diagnostic.d.ts

@@ -0,0 +1,61 @@
+/**
+ * What the front end says when it cannot read the source.
+ *
+ * A syntax diagnostic is DATA, never a thrown error and never a sentence a
+ * consumer re-derives: it carries a code from the closed set below, the range of
+ * the offending text, and a message for a reader. Parsing reports **at most one**
+ * — the first thing it could not read — because the text after it is no longer
+ * trustworthy and a cascade of guesses is what makes a half-typed expression
+ * unusable in an editor. Everything the parser could read is still in the tree.
+ */
+export type CelSyntaxCode = 
+/** A character that begins no CEL token. */
+"unexpected_character"
+/** A token that cannot stand where it does. */
+ | "unexpected_token"
+/** The source ended with an expression unfinished. */
+ | "unexpected_end"
+/** A string or bytes literal that no quote closes. */
+ | "unterminated_string"
+/** A reserved word written where an identifier must be. */
+ | "reserved_identifier"
+/** A number literal that is not spelled as one. */
+ | "invalid_number"
+/** An integer literal outside the int64 range. */
+ | "invalid_integer"
+/** An unsigned integer literal outside the uint64 range. */
+ | "invalid_unsigned_integer"
+/** An escape sequence no string or bytes literal admits. */
+ | "invalid_escape_sequence"
+/** A `\\u`/`\\U` escape naming no Unicode code point. */
+ | "invalid_unicode_escape"
+/** A `\\u` escape naming a surrogate not paired with its partner. */
+ | "invalid_unicode_surrogate"
+/** A `\\x`/`\\X` escape with fewer than two hexadecimal digits. */
+ | "invalid_hex_escape"
+/** A `\\nnn` escape with fewer than three octal digits. */
+ | "invalid_octal_escape"
+/** A `\\nnn` escape naming a value above 255. */
+ | "octal_escape_out_of_range"
+/** A `\\u`/`\\U` escape inside a bytes literal, which holds bytes and not text. */
+ | "bytes_unicode_escape"
+/** One of the five input limits was reached. */
+ | "limit_exceeded";
+export interface CelSyntaxDiagnostic {
+    readonly code: CelSyntaxCode;
+    readonly message: string;
+    readonly range: readonly [start: number, end: number];
+}
+/**
+ * Collects the first diagnostic and ignores every later one.
+ *
+ * Shared by the lexer and the parser so that "the first thing that could not be
+ * read" is one fact rather than two components' opinions of it.
+ */
+export declare class FirstSyntaxDiagnostic {
+    private held;
+    report(code: CelSyntaxCode, message: string, start: number, end: number): void;
+    get reported(): boolean;
+    list(): readonly CelSyntaxDiagnostic[];
+}
+//# sourceMappingURL=syntax-diagnostic.d.ts.map

package/dist/syntax-diagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-diagnostic.d.ts","sourceRoot":"","sources":["../src/syntax-diagnostic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,aAAa;AACvB,4CAA4C;AAC1C,sBAAsB;AACxB,+CAA+C;GAC7C,kBAAkB;AACpB,sDAAsD;GACpD,gBAAgB;AAClB,sDAAsD;GACpD,qBAAqB;AACvB,2DAA2D;GACzD,qBAAqB;AACvB,mDAAmD;GACjD,gBAAgB;AAClB,kDAAkD;GAChD,iBAAiB;AACnB,4DAA4D;GAC1D,0BAA0B;AAC5B,4DAA4D;GAC1D,yBAAyB;AAC3B,yDAAyD;GACvD,wBAAwB;AAC1B,qEAAqE;GACnE,2BAA2B;AAC7B,mEAAmE;GACjE,oBAAoB;AACtB,2DAA2D;GACzD,sBAAsB;AACxB,iDAAiD;GAC/C,2BAA2B;AAC7B,mFAAmF;GACjF,sBAAsB;AACxB,gDAAgD;GAC9C,gBAAgB,CAAC;AAErB,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;CACvD;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,IAAI,CAAkC;IAE9C,MAAM,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAI9E,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,IAAI,SAAS,mBAAmB,EAAE;CAGvC"}

package/dist/syntax-diagnostic.js

@@ -0,0 +1,28 @@
+/**
+ * What the front end says when it cannot read the source.
+ *
+ * A syntax diagnostic is DATA, never a thrown error and never a sentence a
+ * consumer re-derives: it carries a code from the closed set below, the range of
+ * the offending text, and a message for a reader. Parsing reports **at most one**
+ * — the first thing it could not read — because the text after it is no longer
+ * trustworthy and a cascade of guesses is what makes a half-typed expression
+ * unusable in an editor. Everything the parser could read is still in the tree.
+ */
+/**
+ * Collects the first diagnostic and ignores every later one.
+ *
+ * Shared by the lexer and the parser so that "the first thing that could not be
+ * read" is one fact rather than two components' opinions of it.
+ */
+export class FirstSyntaxDiagnostic {
+    held;
+    report(code, message, start, end) {
+        this.held ??= { code, message, range: [start, end] };
+    }
+    get reported() {
+        return this.held !== undefined;
+    }
+    list() {
+        return this.held ? [this.held] : [];
+    }
+}

package/dist/syntax-tree.d.ts

@@ -0,0 +1,160 @@
+/**
+ * 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 declare function childNodes(node: CelNode): readonly CelNode[];
+/** Depth-first pre-order walk over the whole tree. */
+export declare function walkTree(root: CelNode): Generator<CelNode>;
+/** Whether any node of the tree is an unparsed hole. */
+export declare function hasUnparsed(root: CelNode): boolean;
+export {};
+//# sourceMappingURL=syntax-tree.d.ts.map

package/dist/syntax-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-tree.d.ts","sourceRoot":"","sources":["../src/syntax-tree.ts"],"names":[],"mappings":"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"}