@telorun/cel 0.0.0-stage → 0.108.0

package/dist/nominal-type.js

@@ -0,0 +1,98 @@
+/**
+ * Named types a host registers — the one mechanism, with none of the vocabulary.
+ *
+ * A nominal type is a name over a base type, with its own operators, comparisons,
+ * conversions and member functions, and with named **invariant** type parameters. It
+ * is not its base: a value of the base does not stand where the named type is wanted,
+ * and only what the definition declares applies to it. That is what makes a named type
+ * worth having — a slot that wants one refuses a plain value of the base, which is
+ * exactly what an engine typing by wrapper class cannot express.
+ *
+ * Invariance is deliberate: `Holder<string>` and `Holder<int>` are unrelated, so a
+ * type argument that differs is a mistake with its own diagnostic rather than a silent
+ * widening to the base.
+ *
+ * `Self` inside a definition names the type being defined, with its own parameters
+ * applied, so a member can answer its own type without repeating it.
+ */
+import { parameterOf } from "./cel-type.js";
+import { parseTypeExpression } from "./type-expression.js";
+const NAME = /^[A-Za-z_][A-Za-z0-9_.]*$/;
+const PARAMETER = /^[A-Z]$/;
+const LANGUAGE_NAMES = new Set([
+    "dyn",
+    "int",
+    "uint",
+    "double",
+    "bool",
+    "string",
+    "bytes",
+    "null",
+    "null_type",
+    "type",
+    "list",
+    "map",
+    "optional",
+    "timestamp",
+    "duration",
+]);
+export class CelTypeRegistrationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CelTypeRegistrationError";
+    }
+}
+export function validateTypeName(name) {
+    if (!NAME.test(name)) {
+        throw new CelTypeRegistrationError(`${JSON.stringify(name)} is not spelled as a type name`);
+    }
+    if (LANGUAGE_NAMES.has(name)) {
+        throw new CelTypeRegistrationError(`${JSON.stringify(name)} is a type of the language and cannot be redefined`);
+    }
+    if (PARAMETER.test(name)) {
+        throw new CelTypeRegistrationError(`${JSON.stringify(name)} is a single capital letter, which a signature reads as a type parameter`);
+    }
+}
+/**
+ * Builds the registered form of a definition. `resolveNominal` resolves names the
+ * definition's own base or members mention, including itself through `Self`.
+ */
+export function buildRegisteredType(definition, resolveNominal) {
+    validateTypeName(definition.name);
+    const parameters = definition.parameters ?? [];
+    for (const parameter of parameters) {
+        if (!PARAMETER.test(parameter)) {
+            throw new CelTypeRegistrationError(`type parameter ${JSON.stringify(parameter)} of ${definition.name} must be a single capital letter`);
+        }
+    }
+    const self = {
+        kind: "nominal",
+        name: definition.name,
+        base: { kind: "dyn" },
+        args: parameters.map(parameterOf),
+    };
+    const withSelf = (name, args) => name === "Self" || name === definition.name
+        ? { ...self, args: args.length > 0 ? args : self.args }
+        : resolveNominal(name, args);
+    let base;
+    try {
+        base = parseTypeExpression(definition.base, withSelf);
+    }
+    catch (cause) {
+        throw new CelTypeRegistrationError(`the base of ${definition.name} does not read as a type: ${cause.message}`);
+    }
+    return { definition, base, parameters, self: { ...self, base } };
+}
+/** The signatures a definition declares, as text, in registration order. */
+export function nominalSignatures(definition) {
+    return [...(definition.conversions ?? []), ...(definition.members ?? [])];
+}
+/** The operator declarations a definition implies, its comparisons expanded. */
+export function nominalOperators(definition) {
+    const comparisons = (definition.comparisons ?? []).map((operator) => ({
+        operator,
+        parameters: ["Self", "Self"],
+        returns: "bool",
+    }));
+    return [...(definition.operators ?? []), ...comparisons];
+}

package/dist/nullable-access.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+import type { CelNode } from "./syntax-tree.js";
+/** The dotted path a node spells, if it is a plain chain of named members. */
+export declare function chainText(node: CelNode): string | undefined;
+/**
+ * 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 declare function chainRoot(node: CelNode): string | undefined;
+/** The chains proven non-null where the condition holds. */
+export declare function provenWhereTrue(condition: CelNode): readonly string[];
+/** The chains proven non-null where the condition fails. */
+export declare function provenWhereFalse(condition: CelNode): readonly string[];
+//# sourceMappingURL=nullable-access.d.ts.map

package/dist/nullable-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nullable-access.d.ts","sourceRoot":"","sources":["../src/nullable-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAK3D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI3D;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAarE;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAatE"}

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"}