@telorun/cel 0.0.0-stage → 0.107.0

package/dist/nullable-access.js

@@ -0,0 +1,93 @@
+/**
+ * Which dereferences a guard has proven safe.
+ *
+ * A value whose declared type admits null is only safely dereferenced where something
+ * has proven it is not null, and **what counts as proof is exactly three constructs**:
+ * a ternary, `&&` and `||`. Not more, not less. That bound is not a simplification — a
+ * consumer switching engines must not newly accept an expression (which recognising
+ * another construct would do) nor newly reject one (which recognising fewer would do),
+ * and a guard written as a function call is deliberately not proof.
+ *
+ * The rules, over a condition `c`:
+ *
+ * - `chain != null` proves `chain` where `c` holds; `chain == null` proves it where `c`
+ *   fails. `null` may stand on either side of the comparison.
+ * - `!c` swaps the two.
+ * - `a && b` proves, where it holds, everything `a` and `b` prove; where it fails,
+ *   nothing, since either arm may be the one that failed.
+ * - `a || b` is the mirror: where it fails, both arms failed, so both their negative
+ *   proofs hold.
+ *
+ * A chain is a plain path of named members (`error.code`), which is what a proof can
+ * name: nothing proves anything about `xs[i].code`, because the index is not part of a
+ * name.
+ */
+/** The dotted path a node spells, if it is a plain chain of named members. */
+export function chainText(node) {
+    if (node.kind === "ident")
+        return node.name;
+    if (node.kind !== "select" || node.optional || node.field === "")
+        return undefined;
+    const operand = chainText(node.operand);
+    return operand === undefined ? undefined : `${operand}.${node.field}`;
+}
+/**
+ * The name a chain is rooted at, or nothing when it is not a chain of plain members over a
+ * name. It is what says whether the chain's subject is a name the EXPRESSION bound — a
+ * comprehension variable, a `cel.bind` name — rather than one the host declared.
+ */
+export function chainRoot(node) {
+    if (node.kind === "ident")
+        return node.name;
+    if (node.kind !== "select" || node.optional || node.field === "")
+        return undefined;
+    return chainRoot(node.operand);
+}
+/** The chains proven non-null where the condition holds. */
+export function provenWhereTrue(condition) {
+    switch (condition.kind) {
+        case "binary":
+            if (condition.operator === "!=")
+                return nullTest(condition);
+            if (condition.operator === "&&") {
+                return [...provenWhereTrue(condition.left), ...provenWhereTrue(condition.right)];
+            }
+            return [];
+        case "unary":
+            return condition.operator === "!" ? provenWhereFalse(condition.operand) : [];
+        default:
+            return [];
+    }
+}
+/** The chains proven non-null where the condition fails. */
+export function provenWhereFalse(condition) {
+    switch (condition.kind) {
+        case "binary":
+            if (condition.operator === "==")
+                return nullTest(condition);
+            if (condition.operator === "||") {
+                return [...provenWhereFalse(condition.left), ...provenWhereFalse(condition.right)];
+            }
+            return [];
+        case "unary":
+            return condition.operator === "!" ? provenWhereTrue(condition.operand) : [];
+        default:
+            return [];
+    }
+}
+/** The chain a comparison against `null` is about, either way round. */
+function nullTest(comparison) {
+    const { left, right } = comparison;
+    if (isNullLiteral(right)) {
+        const chain = chainText(left);
+        return chain === undefined ? [] : [chain];
+    }
+    if (isNullLiteral(left)) {
+        const chain = chainText(right);
+        return chain === undefined ? [] : [chain];
+    }
+    return [];
+}
+function isNullLiteral(node) {
+    return node.kind === "literal" && node.literal.type === "null";
+}

package/dist/parse-limits.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What the front end refuses to read because it is too big.
+ *
+ * An expression arrives from a manifest, from an editor buffer or over a wire, so
+ * the parser is a hostile-input boundary: without a bound, nesting alone exhausts
+ * the call stack of a recursive-descent parser, and a generated list exhausts
+ * memory. Each limit is reported as an ordinary ranged diagnostic — never a
+ * thrown error — so an editor keeps the prefix it could read.
+ *
+ * The defaults are the ones every already-written manifest was accepted under.
+ */
+export interface CelParseLimits {
+    /** Nodes in the tree. */
+    readonly maxNodes: number;
+    /** Nesting depth of the expression grammar. */
+    readonly maxDepth: number;
+    /** Elements in one list literal. */
+    readonly maxListElements: number;
+    /** Entries in one map literal. */
+    readonly maxMapEntries: number;
+    /** Arguments at one call. */
+    readonly maxCallArguments: number;
+}
+export declare const DEFAULT_PARSE_LIMITS: CelParseLimits;
+export declare function resolveParseLimits(limits?: Partial<CelParseLimits>): CelParseLimits;
+//# sourceMappingURL=parse-limits.d.ts.map

package/dist/parse-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-limits.d.ts","sourceRoot":"","sources":["../src/parse-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,kCAAkC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6BAA6B;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,eAAO,MAAM,oBAAoB,EAAE,cAMlC,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAEnF"}

package/dist/parse-limits.js

@@ -0,0 +1,21 @@
+/**
+ * What the front end refuses to read because it is too big.
+ *
+ * An expression arrives from a manifest, from an editor buffer or over a wire, so
+ * the parser is a hostile-input boundary: without a bound, nesting alone exhausts
+ * the call stack of a recursive-descent parser, and a generated list exhausts
+ * memory. Each limit is reported as an ordinary ranged diagnostic — never a
+ * thrown error — so an editor keeps the prefix it could read.
+ *
+ * The defaults are the ones every already-written manifest was accepted under.
+ */
+export const DEFAULT_PARSE_LIMITS = {
+    maxNodes: 100000,
+    maxDepth: 250,
+    maxListElements: 1000,
+    maxMapEntries: 1000,
+    maxCallArguments: 32,
+};
+export function resolveParseLimits(limits) {
+    return limits ? { ...DEFAULT_PARSE_LIMITS, ...limits } : DEFAULT_PARSE_LIMITS;
+}

package/dist/parser.d.ts

@@ -0,0 +1,48 @@
+/**
+ * CEL's grammar, read by recursive descent into the canonical tree.
+ *
+ * **Error recovery is the point.** Parsing never throws and never discards what it
+ * read: the first thing it cannot read becomes one ranged diagnostic, the reader
+ * stops there, and the tree holds the longest prefix it understood with an
+ * `unparsed` node where the rest would have been. That is what lets completion and
+ * hover work on an expression mid-token, and nothing downstream has to re-parse a
+ * shortened prefix to get an answer. A member left unnamed (`request.`) is a select
+ * with an **empty field name**, which is the shape completion after a dot reads; an
+ * aggregate or a call left open keeps the elements it read. Neither can be
+ * serialized, and the diagnostic is what says the tree is incomplete.
+ *
+ * **Nothing is expanded.** A macro call (`has(x)`, `xs.map(i, i)`, `cel.bind(…)`) is
+ * an ordinary call node: expanding it here would make the serializer unable to
+ * write the source back, and lowering it to a comprehension is the checker's and a
+ * backend's business. A qualified call is not produced here either — see
+ * `namespace-resolution.ts`.
+ *
+ * **A unary minus directly on a numeric literal folds into the literal.** That is
+ * how the int64 minimum is written at all, and it keeps `-0.0` a value rather than
+ * a negation of zero. A minus on a parenthesized literal does not fold, so the
+ * serializer can write a hand-built negation back without changing its shape.
+ */
+import { type CelParseLimits } from "./parse-limits.js";
+import type { CelSyntaxDiagnostic } from "./syntax-diagnostic.js";
+import type { CelNode } from "./syntax-tree.js";
+export interface ParseOptions {
+    readonly limits?: Partial<CelParseLimits>;
+    /**
+     * Whether the optional library's own syntax is read: `[?x]` and `{?k: v}`, whose entry
+     * holds an optional and contributes its value type. It follows the environment's
+     * `enableOptionalTypes`, because a syntax for a type that does not exist would parse to
+     * a tree nothing can check.
+     */
+    readonly optionalSyntax?: boolean;
+}
+export interface ParseResult {
+    readonly source: string;
+    readonly root: CelNode;
+    readonly diagnostics: readonly CelSyntaxDiagnostic[];
+}
+/**
+ * Reads one CEL expression. Always answers a tree; `diagnostics` holds at most one
+ * entry, and holds one exactly when the whole source could not be read.
+ */
+export declare function parseSyntax(source: string, options?: ParseOptions): ParseResult;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,KAAK,cAAc,EAAsB,MAAM,mBAAmB,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,KAAK,EAIV,OAAO,EAGR,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACtD;AA2eD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,CAK/E"}