@telorun/cel 0.0.0-stage → 0.107.0

package/dist/lexer.js

@@ -0,0 +1,458 @@
+/**
+ * CEL's tokens.
+ *
+ * The lexer decodes literals as it reads them — a string token carries its text
+ * with every escape resolved, a bytes token its bytes, an integer its magnitude as
+ * a `bigint` — so nothing downstream re-reads source text to learn a value.
+ *
+ * It stops at the first thing it cannot read, reporting one diagnostic and ending
+ * the token stream there. The parser then builds whatever the tokens before it
+ * support, which is what leaves a half-typed expression usable.
+ *
+ * Three readings are deliberate, each pinned by the conformance vectors:
+ *
+ * - **Only a single-letter prefix** introduces a string: `r`, `R`, `b`, `B`. `br'x'`
+ *   is the identifier `br` followed by a string, which no expression admits.
+ * - **A raw string still lets a backslash take the next character with it**, keeping
+ *   both as written, so `r'\''` is a backslash and a quote rather than an unclosed
+ *   string.
+ * - **A bytes literal holds the UTF-8 of its text.** `b'ÿ'` is `0xC3 0xBF`, two bytes,
+ *   and an escape (`\xff`, `\303`) is the one byte it names. cel-spec's own answer, and
+ *   the only reading under which `b'ÿ' == b'\303\277'` — a row — holds.
+ *
+ * A number never begins with `.`: `.5` is a dot and a number, and no expression
+ * admits that either.
+ */
+import { wordReading } from "./reserved-words.js";
+import { FirstSyntaxDiagnostic } from "./syntax-diagnostic.js";
+export const MAX_INT = 9223372036854775807n;
+export const MIN_INT = -9223372036854775808n;
+export const MAX_UINT = 18446744073709551615n;
+const PUNCTUATION = new Set(["(", ")", "[", "]", "{", "}", ".", ",", ":", "?", "!", "+", "-", "*", "/", "%"]);
+const SIMPLE_ESCAPES = new Map([
+    ["\\", 0x5c],
+    ["'", 0x27],
+    ['"', 0x22],
+    ["`", 0x60],
+    ["?", 0x3f],
+    ["a", 0x07],
+    ["b", 0x08],
+    ["f", 0x0c],
+    ["n", 0x0a],
+    ["r", 0x0d],
+    ["t", 0x09],
+    ["v", 0x0b],
+]);
+function isDigit(ch) {
+    return ch >= "0" && ch <= "9";
+}
+function isHexDigit(ch) {
+    return isDigit(ch) || (ch >= "a" && ch <= "f") || (ch >= "A" && ch <= "F");
+}
+function isOctalDigit(ch) {
+    return ch >= "0" && ch <= "7";
+}
+function isIdentStart(ch) {
+    return ch === "_" || (ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z");
+}
+function isIdentPart(ch) {
+    return isIdentStart(ch) || isDigit(ch);
+}
+/**
+ * What a word before a quote makes of the literal.
+ *
+ * cel-spec nests the two markers — `BYTES_LIT: [bB] STRING_LIT` over
+ * `STRING_LIT: [rR]? (…)` — so the bytes marker comes first and `rb'…'` is not a
+ * literal at all: it is the name `rb` beside a string, which no expression admits.
+ */
+function stringPrefix(text) {
+    const lower = text.toLowerCase();
+    if (lower === "r")
+        return { raw: true, bytes: false };
+    if (lower === "b")
+        return { raw: false, bytes: true };
+    if (lower === "br")
+        return { raw: true, bytes: true };
+    return undefined;
+}
+function isSpace(ch) {
+    return ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === "\f" || ch === "\v";
+}
+export class Lexer {
+    source;
+    diagnostics;
+    at = 0;
+    constructor(source, diagnostics) {
+        this.source = source;
+        this.diagnostics = diagnostics;
+    }
+    /** Every token up to the end of the source, or up to the first unreadable text. */
+    tokenize() {
+        const tokens = [];
+        for (;;) {
+            this.skipIgnored();
+            if (this.at >= this.source.length) {
+                tokens.push(this.eof());
+                return tokens;
+            }
+            const token = this.next();
+            if (!token) {
+                tokens.push(this.eof());
+                return tokens;
+            }
+            tokens.push(token);
+        }
+    }
+    eof() {
+        return { type: "eof", start: this.at, end: this.at, text: "" };
+    }
+    skipIgnored() {
+        while (this.at < this.source.length) {
+            const ch = this.source[this.at];
+            if (isSpace(ch)) {
+                this.at += 1;
+                continue;
+            }
+            if (ch === "/" && this.source[this.at + 1] === "/") {
+                while (this.at < this.source.length && this.source[this.at] !== "\n")
+                    this.at += 1;
+                continue;
+            }
+            return;
+        }
+    }
+    next() {
+        const start = this.at;
+        const ch = this.source[start];
+        if (ch === "'" || ch === '"')
+            return this.readQuoted(start, start, false, false);
+        if (isIdentStart(ch))
+            return this.readWord(start);
+        if (isDigit(ch))
+            return this.readNumber(start);
+        // A double may begin with its point: cel-spec's FLOAT_LIT is `DIGIT* . DIGIT+`.
+        if (ch === "." && isDigit(this.source[start + 1] ?? ""))
+            return this.readNumber(start);
+        if (ch === "`")
+            return this.readQuotedIdentifier(start);
+        return this.readPunctuation(start, ch);
+    }
+    readPunctuation(start, ch) {
+        const pair = this.source.slice(start, start + 2);
+        if (pair === "==" || pair === "!=" || pair === "<=" || pair === ">=" || pair === "&&" || pair === "||") {
+            this.at = start + 2;
+            return { type: "punct", start, end: this.at, text: pair };
+        }
+        if (ch === "<" || ch === ">" || PUNCTUATION.has(ch)) {
+            this.at = start + 1;
+            return { type: "punct", start, end: this.at, text: ch };
+        }
+        this.diagnostics.report("unexpected_character", `unexpected character ${JSON.stringify(ch)}`, start, start + 1);
+        this.at = start;
+        return undefined;
+    }
+    /**
+     * A member name between backticks. cel-spec's `ESCAPED_IDENTIFIER` takes no escapes
+     * and cannot hold a backtick, so the text between them is the name as written.
+     */
+    readQuotedIdentifier(start) {
+        const close = this.source.indexOf("`", start + 1);
+        if (close === -1 || this.source.slice(start + 1, close).includes("\n")) {
+            this.diagnostics.report("unterminated_string", "a quoted member name ends at its closing backtick", start, close === -1 ? this.source.length : close);
+            return undefined;
+        }
+        this.at = close + 1;
+        return { type: "quotedIdent", start, end: this.at, text: this.source.slice(start + 1, close) };
+    }
+    /** An identifier, a literal word, or the prefix of a string literal. */
+    readWord(start) {
+        let at = start;
+        while (at < this.source.length && isIdentPart(this.source[at]))
+            at += 1;
+        const text = this.source.slice(start, at);
+        const prefix = stringPrefix(text);
+        if (prefix && (this.source[at] === "'" || this.source[at] === '"')) {
+            return this.readQuoted(start, at, prefix.raw, prefix.bytes);
+        }
+        this.at = at;
+        const reading = wordReading(text);
+        const type = reading === "operator" ? "keyword" : reading === "refused" ? "reserved" : "ident";
+        return { type, start, end: at, text };
+    }
+    readNumber(start) {
+        const source = this.source;
+        let at = start;
+        let kind = "int";
+        let digits;
+        let radix = 10;
+        if (source[at] === "0" && (source[at + 1] === "x" || source[at + 1] === "X")) {
+            at += 2;
+            const from = at;
+            while (at < source.length && isHexDigit(source[at]))
+                at += 1;
+            if (at === from)
+                return this.invalidNumber(start, at);
+            digits = source.slice(from, at);
+            radix = 16;
+        }
+        else {
+            const from = at;
+            while (at < source.length && isDigit(source[at]))
+                at += 1;
+            if (source[at] === "." && isDigit(source[at + 1] ?? "")) {
+                kind = "double";
+                at += 1;
+                while (at < source.length && isDigit(source[at]))
+                    at += 1;
+            }
+            if (source[at] === "e" || source[at] === "E") {
+                let exponent = at + 1;
+                if (source[exponent] === "+" || source[exponent] === "-")
+                    exponent += 1;
+                if (isDigit(source[exponent] ?? "")) {
+                    kind = "double";
+                    at = exponent;
+                    while (at < source.length && isDigit(source[at]))
+                        at += 1;
+                }
+            }
+            digits = source.slice(from, at);
+        }
+        const unsigned = source[at] === "u" || source[at] === "U";
+        if (unsigned)
+            at += 1;
+        if (at < source.length && isIdentPart(source[at]))
+            return this.invalidNumber(start, at);
+        this.at = at;
+        if (kind === "double") {
+            if (unsigned)
+                return this.invalidNumber(start, at);
+            return { type: "double", start, end: at, text: source.slice(start, at), double: Number(digits) };
+        }
+        const magnitude = radix === 16 ? BigInt(`0x${digits}`) : BigInt(digits);
+        if (unsigned) {
+            if (magnitude > MAX_UINT) {
+                this.diagnostics.report("invalid_unsigned_integer", `${source.slice(start, at)} is outside the range of an unsigned 64-bit integer`, start, at);
+                return undefined;
+            }
+            return { type: "uint", start, end: at, text: source.slice(start, at), int: magnitude };
+        }
+        if (magnitude > -MIN_INT) {
+            this.diagnostics.report("invalid_integer", `${source.slice(start, at)} is outside the range of a 64-bit integer`, start, at);
+            return undefined;
+        }
+        return {
+            type: "int",
+            start,
+            end: at,
+            text: source.slice(start, at),
+            int: magnitude,
+            ...(magnitude === -MIN_INT ? { atIntBoundary: true } : {}),
+        };
+    }
+    invalidNumber(start, at) {
+        let end = at;
+        while (end < this.source.length && isIdentPart(this.source[end]))
+            end += 1;
+        this.diagnostics.report("invalid_number", `${this.source.slice(start, end)} is not a number`, start, end);
+        return undefined;
+    }
+    /**
+     * A string or bytes literal. `start` is the literal's own start (its prefix, when
+     * it has one) and `quoteAt` the opening quote.
+     */
+    readQuoted(start, quoteAt, raw, bytes) {
+        const quote = this.source[quoteAt];
+        const triple = this.source.slice(quoteAt, quoteAt + 3) === quote.repeat(3);
+        const terminator = triple ? quote.repeat(3) : quote;
+        const decoded = raw
+            ? this.scanRaw(quoteAt + terminator.length, terminator, triple, bytes)
+            : this.scanEscaped(quoteAt + terminator.length, terminator, triple, bytes);
+        if (!decoded)
+            return undefined;
+        this.at = decoded.end;
+        const text = this.source.slice(start, decoded.end);
+        if (bytes) {
+            return { type: "bytes", start, end: decoded.end, text, bytes: Uint8Array.from(decoded.units) };
+        }
+        return { type: "string", start, end: decoded.end, text, string: textOf(decoded.units) };
+    }
+    unterminated(start, at) {
+        this.diagnostics.report("unterminated_string", "unterminated string", start, at);
+        return undefined;
+    }
+    /** A raw literal: a backslash takes the next character with it, both kept as written. */
+    scanRaw(from, terminator, triple, bytes) {
+        const source = this.source;
+        const units = [];
+        let at = from;
+        while (at < source.length) {
+            if (source.startsWith(terminator, at))
+                return { units, end: at + terminator.length };
+            const ch = source[at];
+            if (!triple && ch === "\n")
+                break;
+            if (ch === "\\" && at + 1 < source.length) {
+                units.push(0x5c);
+                at += 1 + this.literalCharacter(at + 1, bytes, units);
+                continue;
+            }
+            at += this.literalCharacter(at, bytes, units);
+        }
+        return this.unterminated(from - terminator.length, at);
+    }
+    /**
+     * One character of a literal's text, as the literal holds it: a code unit in a string,
+     * the character's UTF-8 bytes in a bytes literal. Answers how many code units it read,
+     * since a character outside the basic plane is written as a surrogate pair.
+     */
+    literalCharacter(at, bytes, units) {
+        if (!bytes) {
+            units.push(this.source.charCodeAt(at));
+            return 1;
+        }
+        const point = this.source.codePointAt(at);
+        pushUtf8(units, point);
+        return point > 0xffff ? 2 : 1;
+    }
+    scanEscaped(from, terminator, triple, bytes) {
+        const source = this.source;
+        const units = [];
+        let at = from;
+        while (at < source.length) {
+            if (source.startsWith(terminator, at))
+                return { units, end: at + terminator.length };
+            const ch = source[at];
+            if (!triple && ch === "\n")
+                break;
+            if (ch !== "\\") {
+                at += this.literalCharacter(at, bytes, units);
+                continue;
+            }
+            const next = this.readEscape(at, bytes, units);
+            if (next === undefined)
+                return undefined;
+            at = next;
+        }
+        return this.unterminated(from - terminator.length, at);
+    }
+    /** Decodes one escape sequence onto `units`, answering where it ends. */
+    readEscape(at, bytes, units) {
+        const source = this.source;
+        const ch = source[at + 1];
+        if (ch === undefined) {
+            this.diagnostics.report("invalid_escape_sequence", "the escape has no character", at, at + 1);
+            return undefined;
+        }
+        const simple = SIMPLE_ESCAPES.get(ch);
+        if (simple !== undefined) {
+            units.push(simple);
+            return at + 2;
+        }
+        if (ch === "x" || ch === "X")
+            return this.readHexEscape(at, units);
+        if (ch === "u" || ch === "U") {
+            if (bytes) {
+                this.diagnostics.report("bytes_unicode_escape", `\\${ch} names text, which a bytes literal cannot hold — write the bytes with \\x`, at, at + 2);
+                return undefined;
+            }
+            return this.readUnicodeEscape(at, ch === "u" ? 4 : 8, units);
+        }
+        if (isOctalDigit(ch))
+            return this.readOctalEscape(at, units);
+        this.diagnostics.report("invalid_escape_sequence", `\\${ch} is not an escape sequence`, at, at + 2);
+        return undefined;
+    }
+    readHexEscape(at, units) {
+        const digits = this.source.slice(at + 2, at + 4);
+        if (digits.length < 2 || !isHexDigit(digits[0]) || !isHexDigit(digits[1])) {
+            this.diagnostics.report("invalid_hex_escape", "a \\x escape takes two hexadecimal digits", at, at + 4);
+            return undefined;
+        }
+        units.push(Number.parseInt(digits, 16));
+        return at + 4;
+    }
+    readOctalEscape(at, units) {
+        const digits = this.source.slice(at + 1, at + 4);
+        if (digits.length < 3 || ![...digits].every(isOctalDigit)) {
+            this.diagnostics.report("invalid_octal_escape", "an octal escape takes three octal digits", at, at + 4);
+            return undefined;
+        }
+        const value = Number.parseInt(digits, 8);
+        if (value > 0xff) {
+            this.diagnostics.report("octal_escape_out_of_range", `\\${digits} is above 255`, at, at + 4);
+            return undefined;
+        }
+        units.push(value);
+        return at + 4;
+    }
+    readUnicodeEscape(at, width, units) {
+        const digits = this.source.slice(at + 2, at + 2 + width);
+        if (digits.length < width || ![...digits].every(isHexDigit)) {
+            this.diagnostics.report("invalid_unicode_escape", `a \\${width === 4 ? "u" : "U"} escape takes ${width} hexadecimal digits`, at, at + 2 + width);
+            return undefined;
+        }
+        const point = Number.parseInt(digits, 16);
+        const end = at + 2 + width;
+        if (point > 0x10ffff) {
+            this.diagnostics.report("invalid_unicode_escape", `U+${digits} is not a code point`, at, end);
+            return undefined;
+        }
+        if (point >= 0xdc00 && point <= 0xdfff) {
+            this.diagnostics.report("invalid_unicode_surrogate", `U+${digits} is a trailing surrogate`, at, end);
+            return undefined;
+        }
+        if (point >= 0xd800 && point <= 0xdbff)
+            return this.readSurrogatePair(at, end, point, units);
+        if (point > 0xffff) {
+            units.push(0xd800 + ((point - 0x10000) >> 10), 0xdc00 + ((point - 0x10000) & 0x3ff));
+            return end;
+        }
+        units.push(point);
+        return end;
+    }
+    /** A leading surrogate stands only beside the trailing one that completes it. */
+    readSurrogatePair(at, end, lead, units) {
+        const follows = this.source.slice(end, end + 6);
+        const trail = /^\\u([0-9a-fA-F]{4})$/.exec(follows);
+        const point = trail ? Number.parseInt(trail[1], 16) : 0;
+        if (!trail || point < 0xdc00 || point > 0xdfff) {
+            this.diagnostics.report("invalid_unicode_surrogate", "a leading surrogate must be followed by a trailing surrogate escape", at, end);
+            return undefined;
+        }
+        units.push(lead, point);
+        return end + 6;
+    }
+}
+/** The UTF-8 bytes of one code point, which is what a bytes literal holds of its text. */
+function pushUtf8(units, point) {
+    if (point < 0x80) {
+        units.push(point);
+        return;
+    }
+    if (point < 0x800) {
+        units.push(0xc0 | (point >> 6), 0x80 | (point & 0x3f));
+        return;
+    }
+    if (point < 0x10000) {
+        units.push(0xe0 | (point >> 12), 0x80 | ((point >> 6) & 0x3f), 0x80 | (point & 0x3f));
+        return;
+    }
+    units.push(0xf0 | (point >> 18), 0x80 | ((point >> 12) & 0x3f), 0x80 | ((point >> 6) & 0x3f), 0x80 | (point & 0x3f));
+}
+/** Code units to text, in chunks so that a long literal does not exhaust the stack. */
+function textOf(units) {
+    if (units.length <= 4096)
+        return String.fromCharCode(...units);
+    let text = "";
+    for (let at = 0; at < units.length; at += 4096) {
+        text += String.fromCharCode(...units.slice(at, at + 4096));
+    }
+    return text;
+}
+/** Every token of the source, with at most one diagnostic for where it stopped. */
+export function tokenize(source) {
+    const diagnostics = new FirstSyntaxDiagnostic();
+    const tokens = new Lexer(source, diagnostics).tokenize();
+    return { tokens, diagnostics };
+}

package/dist/macro-check.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Typing the macros — the constructs that are written as calls and are not functions.
+ *
+ * A macro binds a name, or inspects the shape of its argument, so it cannot be a
+ * registered signature: `xs.map(i, i + 1)` has no argument type for `i`, and `has(a.b)`
+ * is about whether `b` is there rather than about its value. The parser deliberately
+ * leaves each one an ordinary call node (expanding it would make the source unwritable
+ * from the tree), so this is where the comprehension appears — in the checker's own
+ * lowering, which is also why a macro is **not** a dispatched call in the call listing.
+ *
+ * Which arguments a macro binds a name over is declared once, in
+ * `comprehension-bindings.ts`, and read both here and by the free-variable query. Two
+ * tables would be two answers to "what does this macro bind".
+ */
+import type { CelType } from "./cel-type.js";
+import type { CelCheckCode } from "./check-diagnostic.js";
+import type { CelNode, SourceRange } from "./syntax-tree.js";
+/** What a macro needs of the checker around it. */
+export interface MacroHost {
+    /** The type of a subexpression, in the scope that holds here. */
+    typeOf(node: CelNode): CelType;
+    /** The type of a subexpression with extra names in scope. */
+    typeOfBinding(node: CelNode, bindings: ReadonlyMap<string, CelType>): CelType;
+    report(code: CelCheckCode, message: string, range: SourceRange): void;
+}
+/** Whether a call is a macro at all — asked before any overload is looked for. */
+export declare function isMacroCall(node: CelNode): boolean;
+/**
+ * The type of a macro call. `isMacroCall` has already said it is one; anything this
+ * cannot type reports its own diagnostic and answers `dyn`, so one mistake stays one.
+ */
+export declare function checkMacro(node: CelNode, host: MacroHost): CelType;
+//# sourceMappingURL=macro-check.d.ts.map

package/dist/macro-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"macro-check.d.ts","sourceRoot":"","sources":["../src/macro-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE7D,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IAC/B,6DAA6D;IAC7D,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IAC9E,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;CACvE;AAWD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAQlD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAalE"}

package/dist/macro-check.js

@@ -0,0 +1,162 @@
+/**
+ * Typing the macros — the constructs that are written as calls and are not functions.
+ *
+ * A macro binds a name, or inspects the shape of its argument, so it cannot be a
+ * registered signature: `xs.map(i, i + 1)` has no argument type for `i`, and `has(a.b)`
+ * is about whether `b` is there rather than about its value. The parser deliberately
+ * leaves each one an ordinary call node (expanding it would make the source unwritable
+ * from the tree), so this is where the comprehension appears — in the checker's own
+ * lowering, which is also why a macro is **not** a dispatched call in the call listing.
+ *
+ * Which arguments a macro binds a name over is declared once, in
+ * `comprehension-bindings.ts`, and read both here and by the free-variable query. Two
+ * tables would be two answers to "what does this macro bind".
+ */
+import { BOOL, DYN, formatType, isDyn, listOf, optionalOf, parameterOf } from "./cel-type.js";
+import { namespaceMacroBinding, receiverMacroBinding } from "./comprehension-bindings.js";
+/** The reserved namespaces a macro is written on, and the macros on each. */
+const NAMESPACE_MACROS = {
+    cel: ["bind"],
+    optional: ["of", "none", "ofNonZeroValue"],
+};
+/** The optional library's two name-binding members, which no signature can state. */
+const OPTIONAL_BINDING_MACROS = new Set(["optMap", "optFlatMap"]);
+/** Whether a call is a macro at all — asked before any overload is looked for. */
+export function isMacroCall(node) {
+    if (node.kind === "call")
+        return node.name === "has" && node.args.length === 1;
+    if (node.kind !== "receiverCall")
+        return false;
+    if (receiverMacroBinding(node.name, node.args.length))
+        return true;
+    const receiver = node.receiver;
+    if (receiver.kind !== "ident")
+        return false;
+    const on = NAMESPACE_MACROS[receiver.name];
+    return on !== undefined && on.includes(node.name);
+}
+/**
+ * The type of a macro call. `isMacroCall` has already said it is one; anything this
+ * cannot type reports its own diagnostic and answers `dyn`, so one mistake stays one.
+ */
+export function checkMacro(node, host) {
+    if (node.kind === "call")
+        return checkHas(node, host);
+    if (node.kind !== "receiverCall")
+        return DYN;
+    const receiver = node.receiver;
+    if (receiver.kind === "ident" && NAMESPACE_MACROS[receiver.name]) {
+        return receiver.name === "cel"
+            ? checkBind(node, host)
+            : checkOptionalNamespace(node, host);
+    }
+    if (OPTIONAL_BINDING_MACROS.has(node.name) && node.args.length === 2) {
+        return checkOptionalBinding(node, host);
+    }
+    return checkComprehension(node, host);
+}
+/**
+ * `opt.optMap(v, expr)` and `opt.optFlatMap(v, expr)`: the held value under a name, for
+ * one expression. `optMap` wraps what that expression answers; `optFlatMap` takes an
+ * optional from it and does not wrap it again.
+ */
+function checkOptionalBinding(node, host) {
+    const receiver = host.typeOf(node.receiver);
+    const name = node.args[0];
+    if (name.kind !== "ident")
+        return DYN;
+    let held = DYN;
+    if (receiver.kind === "optional")
+        held = receiver.value;
+    else if (!isDyn(receiver) && receiver.kind !== "parameter") {
+        host.report("CEL_TYPE_ERROR", `${node.name} reads an optional, and ${formatType(receiver)} is not one`, node.receiver.range);
+    }
+    const result = host.typeOfBinding(node.args[1], new Map([[name.name, held]]));
+    if (node.name === "optMap")
+        return optionalOf(result);
+    if (result.kind === "optional" || isDyn(result) || result.kind === "parameter")
+        return result;
+    host.report("CEL_TYPE_ERROR", `optFlatMap's expression must answer an optional, and it answers ${formatType(result)}`, node.args[1].range);
+    return optionalOf(DYN);
+}
+/** `has(a.b)` — a question about presence. Its shape is already validated. */
+function checkHas(node, host) {
+    const argument = node.args[0];
+    if (argument.kind === "select")
+        host.typeOf(argument);
+    return BOOL;
+}
+/** `cel.bind(name, value, body)` — a name for one value, in scope in the body alone. */
+function checkBind(node, host) {
+    const binding = namespaceMacroBinding("cel", node.name, node.args.length);
+    if (!binding) {
+        host.report("CEL_INVALID_ARGUMENT", "cel.bind(name, value, body) takes three arguments: a name, its value, and the expression that reads it", node.range);
+        return DYN;
+    }
+    const name = node.args[binding.variableArgument];
+    if (name.kind !== "ident")
+        return DYN;
+    const value = host.typeOf(node.args[1]);
+    return host.typeOfBinding(node.args[2], new Map([[name.name, value]]));
+}
+/** `optional.of(v)`, `optional.ofNonZeroValue(v)` and `optional.none()`. */
+function checkOptionalNamespace(node, host) {
+    if (node.name === "none") {
+        if (node.args.length !== 0) {
+            host.report("CEL_INVALID_ARGUMENT", "optional.none() takes no argument", node.range);
+        }
+        return optionalOf(parameterOf("T"));
+    }
+    if (node.args.length !== 1) {
+        host.report("CEL_INVALID_ARGUMENT", `optional.${node.name}(value) takes one argument`, node.range);
+        return optionalOf(DYN);
+    }
+    return optionalOf(host.typeOf(node.args[0]));
+}
+/** `all`, `exists`, `exists_one`, `filter` and `map` over a list or a map. */
+function checkComprehension(node, host) {
+    const binding = receiverMacroBinding(node.name, node.args.length);
+    const receiver = host.typeOf(node.receiver);
+    const element = iterationType(receiver, node, host);
+    const name = node.args[binding.variableArgument];
+    if (name.kind !== "ident")
+        return DYN;
+    const bindings = new Map([[name.name, element]]);
+    const scoped = binding.scopedArguments.map((at) => ({
+        node: node.args[at],
+        type: host.typeOfBinding(node.args[at], bindings),
+    }));
+    if (node.name === "all" || node.name === "exists" || node.name === "exists_one") {
+        requireBool(scoped[0], node.name, host);
+        return BOOL;
+    }
+    if (node.name === "filter") {
+        requireBool(scoped[0], node.name, host);
+        return listOf(element);
+    }
+    // `map` in both arities: the last scoped argument is the transform, and a third
+    // argument makes the one before it a filter.
+    if (scoped.length === 2)
+        requireBool(scoped[0], node.name, host);
+    return listOf(scoped.at(-1).type);
+}
+function requireBool(scoped, name, host) {
+    if (isDyn(scoped.type) || scoped.type.kind === "parameter")
+        return;
+    if (scoped.type.kind === "primitive" && scoped.type.name === "bool")
+        return;
+    host.report("CEL_TYPE_ERROR", `${name}'s test must be bool, and it is ${formatType(scoped.type)}`, scoped.node.range);
+}
+/** What one element of a comprehension's receiver is: a list's element, a map's key. */
+function iterationType(receiver, node, host) {
+    if (isDyn(receiver) || receiver.kind === "parameter")
+        return DYN;
+    if (receiver.kind === "list")
+        return receiver.element;
+    if (receiver.kind === "map")
+        return receiver.key;
+    if (receiver.kind === "record")
+        return { kind: "primitive", name: "string" };
+    host.report("CEL_TYPE_ERROR", `a comprehension reads a list or a map, and ${formatType(receiver)} is neither`, node.kind === "receiverCall" ? node.receiver.range : node.range);
+    return DYN;
+}

package/dist/macro-shape.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether each macro call is shaped like one at all, judged before any type is read.
+ *
+ * A macro's own arguments are not values: `xs.map(i, …)` declares the name `i`, and
+ * `has(a.b)` asks about the member `b` of a chain of names. Neither is something a type
+ * can be wrong about — they are either written in the shape the macro takes, or the call
+ * is not that macro. So this is a **structural** pass over the whole tree, and it runs
+ * first: a macro written wrongly is reported before anything inside it is typed, because
+ * the typing of its body depends on a name the call failed to declare.
+ *
+ * The walk is **post-order**, so the innermost mistake is the one reported first. Nesting
+ * macros is how a generated expression goes wrong, and the inner call is the one a reader
+ * has to fix.
+ */
+import type { CelCheckCode } from "./check-diagnostic.js";
+import type { CelNode, SourceRange } from "./syntax-tree.js";
+export interface MacroShapeFinding {
+    readonly code: CelCheckCode;
+    readonly message: string;
+    readonly range: SourceRange;
+}
+/** Every macro call whose own arguments are not the shape it takes, innermost first. */
+export declare function macroShapeFindings(root: CelNode): readonly MacroShapeFinding[];
+//# sourceMappingURL=macro-shape.d.ts.map