@impetik/xeer-mcp 0.2.5 → 0.2.6

package/vendor/spec/sql-expression.js

@@ -0,0 +1,650 @@
+/**
+ * The SQL text primitives every generated statement is built out of, and the one place an
+ * author-written expression is allowed to become SQL.
+ *
+ * A manifest may carry expressions — a table CHECK, a generated column, a partial index's WHERE, an
+ * index over `lower(title)`. There is no way to bind those as parameters: they are DDL, not values,
+ * so they reach SQLite as text. That makes them the only part of the manifest that could smuggle
+ * syntax into a statement, and the reason this module exists is to make "expression" a closed
+ * vocabulary rather than a passthrough.
+ *
+ * The expression is lexed into tokens and re-emitted from them. Nothing survives that the lexer did
+ * not recognize, which buys three things at once:
+ *
+ *   - **Escaping.** A column reference is re-emitted through {@link sqlIdentifier} and a string
+ *     through {@link sqlStringLiteral}, so quoting is structural rather than a rule someone has to
+ *     remember. There is no path by which raw author text reaches the statement.
+ *   - **Scope.** Every bare word is either a keyword, an allowlisted function, or a column of *this*
+ *     table. A statement separator, a comment, a bind parameter, a qualified `other.column`, and the
+ *     word `SELECT` all have no token, so a subquery cannot be written at all.
+ *   - **Determinism.** Whitespace and keyword case are normalized on the way out, so the same
+ *     expression always produces byte-identical DDL.
+ *
+ * The function allowlist holds only *deterministic* functions. That is not caution: SQLite refuses a
+ * non-deterministic function in a CHECK, a generated column, and an index, so `datetime('now')` in
+ * any of those positions is an error at CREATE time. Rejecting it here turns a failure when the
+ * schema is applied into a diagnostic when it is written.
+ */
+/** Every function an expression may call. Deterministic only — see the module comment. */
+export const SQL_EXPRESSION_FUNCTIONS = Object.freeze([
+    'abs', 'char', 'coalesce', 'concat', 'concat_ws', 'format', 'hex', 'ifnull', 'iif', 'instr',
+    'json_array_length', 'json_extract', 'json_quote', 'json_type', 'json_valid', 'length',
+    'likelihood', 'likely', 'lower', 'ltrim', 'max', 'min', 'nullif', 'printf', 'quote', 'replace',
+    'round', 'rtrim', 'sign', 'substr', 'substring', 'trim', 'typeof', 'unhex', 'unicode', 'unlikely',
+    'upper', 'zeroblob',
+]);
+/**
+ * How many arguments each allowlisted function takes, as `[minimum, maximum]`.
+ *
+ * SQLite reports a bad count as `wrong number of arguments to function lower()` when the statement
+ * is prepared, which for DDL means when the schema is applied rather than when it is written. The
+ * table is exhaustive over {@link SQL_EXPRESSION_FUNCTIONS} and a test holds it that way, because a
+ * function reachable without an entry would be a function nobody counts.
+ *
+ * `max` and `min` are the reason this is not merely tidiness. Both are scalar with two or more
+ * arguments and *aggregates* with one, and SQLite answers the aggregate form with `misuse of
+ * aggregate function max()` in a CHECK, a generated column and an index alike. Requiring two
+ * arguments keeps `max(position, 0)` and turns `max(position)` into a diagnostic.
+ */
+export const SQL_FUNCTION_ARITY = Object.freeze({
+    abs: [1, 1],
+    char: [0, Number.POSITIVE_INFINITY],
+    coalesce: [2, Number.POSITIVE_INFINITY],
+    concat: [1, Number.POSITIVE_INFINITY],
+    concat_ws: [2, Number.POSITIVE_INFINITY],
+    format: [1, Number.POSITIVE_INFINITY],
+    hex: [1, 1],
+    ifnull: [2, 2],
+    iif: [3, 3],
+    instr: [2, 2],
+    json_array_length: [1, 2],
+    json_extract: [2, Number.POSITIVE_INFINITY],
+    json_quote: [1, 1],
+    json_type: [1, 2],
+    json_valid: [1, 2],
+    length: [1, 1],
+    likelihood: [2, 2],
+    likely: [1, 1],
+    lower: [1, 1],
+    ltrim: [1, 2],
+    max: [2, Number.POSITIVE_INFINITY],
+    min: [2, Number.POSITIVE_INFINITY],
+    nullif: [2, 2],
+    printf: [1, Number.POSITIVE_INFINITY],
+    quote: [1, 1],
+    replace: [3, 3],
+    round: [1, 2],
+    rtrim: [1, 2],
+    sign: [1, 1],
+    substr: [2, 3],
+    substring: [2, 3],
+    trim: [1, 2],
+    typeof: [1, 1],
+    unhex: [1, 2],
+    unicode: [1, 1],
+    unlikely: [1, 1],
+    upper: [1, 1],
+    zeroblob: [1, 1],
+});
+/**
+ * Words that are grammar rather than data. A field that happens to be named `end` or `text` is
+ * reachable — as `"end"` — but only when written quoted, because an unquoted one is grammar here.
+ */
+const KEYWORDS = new Set([
+    'AND', 'AS', 'BETWEEN', 'BINARY', 'BLOB', 'CASE', 'CAST', 'COLLATE', 'ELSE', 'END', 'ESCAPE',
+    'FALSE', 'GLOB', 'IN', 'INTEGER', 'IS', 'ISNULL', 'LIKE', 'MATCH', 'NOCASE', 'NOT', 'NOTNULL',
+    'NULL', 'NUMERIC', 'OR', 'REAL', 'RTRIM', 'TEXT', 'THEN', 'TRUE', 'WHEN',
+]);
+/**
+ * Words that open a statement or a subquery. They would otherwise be read as column references and
+ * rejected with a message about an unknown column, which describes the symptom rather than the rule.
+ */
+const BANNED_WORDS = new Set([
+    'ALTER', 'ATTACH', 'CREATE', 'DELETE', 'DETACH', 'DROP', 'EXISTS', 'FROM', 'GROUP', 'INSERT',
+    'JOIN', 'LIMIT', 'ORDER', 'PRAGMA', 'RAISE', 'SELECT', 'TABLE', 'UNION', 'UPDATE', 'VACUUM',
+    'VALUES', 'WHERE', 'WITH',
+]);
+/** Longest first, so `<=` is never lexed as `<` followed by `=`. */
+const OPERATORS = Object.freeze([
+    '||', '<<', '>>', '<=', '>=', '<>', '!=', '==',
+    '+', '-', '*', '/', '%', '&', '|', '<', '>', '=', '~',
+]);
+/**
+ * The longest expression a manifest may declare. An expression is copied verbatim into the schema
+ * hash, the DDL, and every diagnostic that quotes it, so it is bounded for the same reason a field
+ * name is.
+ */
+export const SQL_EXPRESSION_MAX_LENGTH = 1_000;
+/**
+ * The most interior nodes an expression may build.
+ *
+ * Cloudflare's SQLite refuses an expression tree deeper than 100. Measured in workerd by bisection:
+ * a chain of 100 bare terms — that is, 99 `AND` operators — parses, and 101 terms (100 operators)
+ * fails with "Expression tree is too large (maximum depth 100)". The limit counts operators rather
+ * than terms. The character cap does not stand in for it: 1000 characters buys well over 100 terms,
+ * so without a node budget a manifest could pass `xeer check` and then fail to apply.
+ *
+ * Every interior node of the tree is built by exactly one operator, function call, or grammar
+ * keyword, and a root-to-leaf path visits each of its nodes once — so depth never exceeds the count
+ * of those tokens. Counting them is therefore a sound upper bound, and one that stays cheap: it
+ * needs no parser, only the tokens the lexer already produced.
+ *
+ * What is deliberately *not* counted is anything that costs no depth. An `IN` list is a single node
+ * however many values it holds — 2000 of them parse, and 1000 of them still reject a non-member —
+ * so a long enum is free.
+ * Parentheses are free too: workerd parsed 200 nested ones without complaint.
+ */
+export const SQL_EXPRESSION_MAX_NODES = 90;
+export class SqlExpressionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SqlExpressionError';
+    }
+}
+/** SQLite stores text as NUL-terminated internally, so a NUL truncates the value it appears in. */
+const NUL = String.fromCharCode(0);
+function refuseNul(value, what) {
+    if (value.includes(NUL))
+        throw new SqlExpressionError(`A SQL ${what} may not contain a NUL character.`);
+}
+/** `title` → `"title"`. Doubling the quote is the whole of SQLite's identifier escaping. */
+export function sqlIdentifier(name) {
+    refuseNul(name, 'identifier');
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/** `O'Brien` → `'O''Brien'`. Doubling the apostrophe is the whole of SQLite's string escaping. */
+export function sqlStringLiteral(value) {
+    refuseNul(value, 'string literal');
+    return `'${value.replaceAll("'", "''")}'`;
+}
+/** `00ff` → `X'00ff'`. Lowercase hex only, so one byte sequence has exactly one spelling. */
+export function sqlBlobLiteral(hex) {
+    if (!/^(?:[0-9a-f]{2})*$/.test(hex)) {
+        throw new SqlExpressionError(`A SQL blob literal must be an even number of lowercase hex digits; received ${JSON.stringify(hex)}.`);
+    }
+    return `X'${hex}'`;
+}
+/** SQL has no spelling for NaN or an infinity, so a number that is not finite has no literal. */
+export function sqlNumberLiteral(value) {
+    if (!Number.isFinite(value)) {
+        throw new SqlExpressionError(`A SQL number literal must be finite; received ${String(value)}.`);
+    }
+    return Object.is(value, -0) ? '0' : String(value);
+}
+const IDENTIFIER_START = /[A-Za-z_]/;
+const IDENTIFIER_BODY = /[A-Za-z0-9_]/;
+const NUMBER = /^(?:0[xX][0-9a-fA-F]+|(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)/;
+function lex(source) {
+    const tokens = [];
+    let depth = 0;
+    let at = 0;
+    const fail = (message) => {
+        throw new SqlExpressionError(`${message} in expression ${JSON.stringify(source)}.`);
+    };
+    /** The next character that is not whitespace, used to tell `lower(x)` from a column named `lower`. */
+    const peekNonSpace = (from) => {
+        let index = from;
+        while (index < source.length && /\s/.test(source[index]))
+            index += 1;
+        return source[index] ?? '';
+    };
+    while (at < source.length) {
+        const char = source[at];
+        if (/\s/.test(char)) {
+            at += 1;
+            continue;
+        }
+        if (char === '-' && source[at + 1] === '-')
+            fail('A comment is not allowed');
+        if (char === '/' && source[at + 1] === '*')
+            fail('A comment is not allowed');
+        if (char === ';')
+            fail('A statement separator is not allowed');
+        if (char === '?' || char === ':' || char === '@' || char === '$')
+            fail('A bind parameter is not allowed');
+        if (char === '[' || char === ']' || char === '`')
+            fail('Only double quotes may quote an identifier');
+        // A dot is a qualified name unless a digit follows it, in which case it opens `.5`.
+        if (char === '.' && !/\d/.test(source[at + 1] ?? '')) {
+            fail('A qualified name is not allowed; an expression may only read its own table');
+        }
+        if (char === "'") {
+            let value = '';
+            let index = at + 1;
+            for (;;) {
+                if (index >= source.length)
+                    fail('A string literal is unterminated');
+                if (source[index] === "'") {
+                    if (source[index + 1] !== "'")
+                        break;
+                    value += "'";
+                    index += 2;
+                    continue;
+                }
+                value += source[index];
+                index += 1;
+            }
+            tokens.push({ kind: 'literal', text: sqlStringLiteral(value) });
+            at = index + 1;
+            continue;
+        }
+        if (char === '"') {
+            let name = '';
+            let index = at + 1;
+            for (;;) {
+                if (index >= source.length)
+                    fail('A quoted identifier is unterminated');
+                if (source[index] === '"') {
+                    if (source[index + 1] !== '"')
+                        break;
+                    name += '"';
+                    index += 2;
+                    continue;
+                }
+                name += source[index];
+                index += 1;
+            }
+            if (name === '')
+                fail('A quoted identifier is empty');
+            tokens.push({ kind: 'column', text: name });
+            at = index + 1;
+            continue;
+        }
+        // `x'00ff'` is a blob literal, not the column `x` beside a string.
+        if ((char === 'x' || char === 'X') && source[at + 1] === "'") {
+            const end = source.indexOf("'", at + 2);
+            if (end < 0)
+                fail('A blob literal is unterminated');
+            tokens.push({ kind: 'literal', text: sqlBlobLiteral(source.slice(at + 2, end)) });
+            at = end + 1;
+            continue;
+        }
+        if (IDENTIFIER_START.test(char)) {
+            let index = at;
+            while (index < source.length && IDENTIFIER_BODY.test(source[index]))
+                index += 1;
+            const word = source.slice(at, index);
+            const upper = word.toUpperCase();
+            at = index;
+            if (peekNonSpace(index) === '(') {
+                // A parenthesis after a word usually means a call, but not always: `IN (…)` and `NOT (…)` are
+                // grammar, and `CAST(x AS INTEGER)` only wears a call's shape. The allowlist is consulted
+                // first so `rtrim(x)` stays a function while a bare `COLLATE RTRIM` stays a collation name.
+                if (BANNED_WORDS.has(upper))
+                    fail(`A subquery or statement keyword (${upper}) is not allowed`);
+                if (upper !== 'CAST' && SQL_EXPRESSION_FUNCTIONS.includes(word.toLowerCase())) {
+                    tokens.push({ kind: 'function', text: word.toLowerCase() });
+                    continue;
+                }
+                if (KEYWORDS.has(upper)) {
+                    tokens.push({ kind: 'keyword', text: upper });
+                    continue;
+                }
+                fail(`Function ${JSON.stringify(word)} is not one an expression may call`);
+            }
+            if (BANNED_WORDS.has(upper))
+                fail(`A subquery or statement keyword (${upper}) is not allowed`);
+            if (KEYWORDS.has(upper)) {
+                tokens.push({ kind: 'keyword', text: upper });
+                continue;
+            }
+            tokens.push({ kind: 'column', text: word });
+            continue;
+        }
+        const number = NUMBER.exec(source.slice(at));
+        if (number) {
+            tokens.push({ kind: 'literal', text: number[0] });
+            at += number[0].length;
+            continue;
+        }
+        if (char === '(') {
+            depth += 1;
+            tokens.push({ kind: 'open', text: '(' });
+            at += 1;
+            continue;
+        }
+        if (char === ')') {
+            depth -= 1;
+            if (depth < 0)
+                fail('Parentheses are unbalanced');
+            tokens.push({ kind: 'close', text: ')' });
+            at += 1;
+            continue;
+        }
+        if (char === ',') {
+            tokens.push({ kind: 'comma', text: ',' });
+            at += 1;
+            continue;
+        }
+        const operator = OPERATORS.find((candidate) => source.startsWith(candidate, at));
+        if (operator) {
+            tokens.push({ kind: 'operator', text: operator });
+            at += operator.length;
+            continue;
+        }
+        fail(`Character ${JSON.stringify(char)} is not allowed`);
+    }
+    if (depth !== 0)
+        throw new SqlExpressionError(`Parentheses are unbalanced in expression ${JSON.stringify(source)}.`);
+    if (tokens.length === 0)
+        throw new SqlExpressionError('An expression may not be empty.');
+    return tokens;
+}
+/** Collation names, which are the only words that may follow COLLATE. */
+const COLLATION_NAMES = new Set(['BINARY', 'NOCASE', 'RTRIM']);
+/** Type names, which are the only words that may follow `CAST(x AS`. */
+const TYPE_NAMES = new Set(['BLOB', 'INTEGER', 'NUMERIC', 'REAL', 'TEXT']);
+/** Keywords that are values in their own right rather than grammar joining two others. */
+const VALUE_KEYWORDS = new Set(['FALSE', 'NULL', 'TRUE']);
+const PREFIX_OPERATORS = new Set(['+', '-', '~']);
+/** The comparisons `NOT` may negate, as in `x NOT LIKE y` and `x NOT BETWEEN a AND b`. */
+const NEGATABLE = new Set(['BETWEEN', 'GLOB', 'IN', 'LIKE', 'MATCH']);
+/**
+ * Binding power per infix operator. Only the *relative* order matters here: this validates a token
+ * sequence rather than building a tree, and every precedence assignment that is internally
+ * consistent accepts the same language. It follows SQLite's own order anyway, so that a reader
+ * comparing the two is not asked to hold a second one in their head.
+ */
+const BINARY_PRECEDENCE = Object.freeze({
+    OR: 1,
+    AND: 2,
+    // `NOT` as a prefix sits between AND and comparison; see NOT_PRECEDENCE.
+    '=': 4, '==': 4, '!=': 4, '<>': 4, IS: 4, IN: 4, LIKE: 4, GLOB: 4, MATCH: 4, BETWEEN: 4,
+    '<': 5, '<=': 5, '>': 5, '>=': 5,
+    '&': 6, '|': 6, '<<': 6, '>>': 6,
+    '+': 7, '-': 7,
+    '*': 8, '/': 8, '%': 8,
+    '||': 9,
+});
+const NOT_PRECEDENCE = 3;
+/**
+ * Refuse a token sequence that is not a well-formed expression.
+ *
+ * The lexer decides which tokens may appear; it says nothing about their order, so it accepted
+ * `"title" AND`, `lower()` and `title, slug` as readily as a real predicate. Those generate DDL that
+ * SQLite then refuses — `near ")": syntax error`, `wrong number of arguments to function lower()` —
+ * which turns a repairable diagnostic into a failure when the schema is applied. This is the pass
+ * that makes the module's promise true rather than nearly true.
+ *
+ * It is a validator, not a parser: nothing is built and nothing is evaluated. It walks the tokens by
+ * precedence climbing and throws at the first sequence no expression could have produced.
+ */
+function validateGrammar(tokens, source, columns) {
+    let at = 0;
+    // A declaration rather than an arrow, so its `never` return narrows the code after every call.
+    function fail(message) {
+        throw new SqlExpressionError(`${message} in expression ${JSON.stringify(source)}.`);
+    }
+    const peek = (offset = 0) => tokens[at + offset];
+    const describe = (token) => (token === undefined ? 'the end of the expression' : JSON.stringify(token.text));
+    const at_ = (word, offset = 0) => {
+        const token = peek(offset);
+        return token?.kind === 'keyword' && token.text === word;
+    };
+    const expect = (word, what) => {
+        if (!at_(word))
+            fail(`${what} needs ${word} but found ${describe(peek())}`);
+        at += 1;
+    };
+    const arguments_ = (close) => {
+        let count = 0;
+        if (peek()?.kind !== 'close') {
+            for (;;) {
+                parseExpression(0);
+                count += 1;
+                if (peek()?.kind === 'comma') {
+                    at += 1;
+                    continue;
+                }
+                break;
+            }
+        }
+        if (peek()?.kind !== 'close')
+            fail(`${close} is not closed`);
+        at += 1;
+        return count;
+    };
+    function parseCase() {
+        if (at_('END'))
+            fail('CASE needs at least one WHEN branch');
+        if (!at_('WHEN'))
+            parseExpression(0);
+        if (!at_('WHEN'))
+            fail(`CASE needs at least one WHEN branch but found ${describe(peek())}`);
+        while (at_('WHEN')) {
+            at += 1;
+            parseExpression(0);
+            expect('THEN', 'A CASE branch');
+            parseExpression(0);
+        }
+        if (at_('ELSE')) {
+            at += 1;
+            parseExpression(0);
+        }
+        expect('END', 'CASE');
+    }
+    function parseCast() {
+        if (peek()?.kind !== 'open')
+            fail(`CAST needs a parenthesized expression but found ${describe(peek())}`);
+        at += 1;
+        parseExpression(0);
+        expect('AS', 'CAST');
+        const type = peek();
+        if (type?.kind !== 'keyword' || !TYPE_NAMES.has(type.text)) {
+            fail(`CAST needs a type name (${[...TYPE_NAMES].join(', ')}) but found ${describe(type)}`);
+        }
+        at += 1;
+        if (peek()?.kind !== 'close')
+            fail('A CAST is not closed');
+        at += 1;
+    }
+    function parsePrimary() {
+        const token = peek();
+        if (token === undefined)
+            fail('An expression is incomplete');
+        if (token.kind === 'literal' || token.kind === 'column') {
+            at += 1;
+            return;
+        }
+        if (token.kind === 'function') {
+            at += 1;
+            if (peek()?.kind !== 'open')
+                fail(`Function ${JSON.stringify(token.text)} needs an argument list`);
+            at += 1;
+            checkArity(token.text, arguments_(`The argument list of ${JSON.stringify(token.text)}`), source);
+            return;
+        }
+        if (token.kind === 'open') {
+            at += 1;
+            parseExpression(0);
+            if (peek()?.kind === 'comma') {
+                fail('A comma may only separate the arguments of a function call or the values of an IN list');
+            }
+            if (peek()?.kind !== 'close')
+                fail(`A parenthesized expression is not closed; found ${describe(peek())}`);
+            at += 1;
+            return;
+        }
+        if (token.kind === 'keyword') {
+            if (VALUE_KEYWORDS.has(token.text)) {
+                at += 1;
+                return;
+            }
+            if (token.text === 'CASE') {
+                at += 1;
+                parseCase();
+                return;
+            }
+            if (token.text === 'CAST') {
+                at += 1;
+                parseCast();
+                return;
+            }
+        }
+        if (token.kind === 'operator')
+            fail(`Operator ${JSON.stringify(token.text)} is missing an operand`);
+        // A field may be named `text` or `end`, which the lexer reads as grammar rather than as a column.
+        // Saying only that it cannot start an expression describes the symptom; the author needs the fix.
+        if (token.kind === 'keyword') {
+            const shadowed = columns.find((column) => column.toLowerCase() === token.text.toLowerCase());
+            if (shadowed !== undefined) {
+                fail(`${JSON.stringify(shadowed)} is a SQL keyword here, so it reads as grammar rather than as the `
+                    + `field of that name; write it quoted as ${JSON.stringify(`"${shadowed}"`)}`);
+            }
+        }
+        fail(`${describe(token)} cannot start an expression`);
+    }
+    /** `x ISNULL`, `x NOTNULL`, `x NOT NULL` and `x COLLATE NOCASE` all bind to the value before them. */
+    function parsePostfix() {
+        for (;;) {
+            if (at_('ISNULL') || at_('NOTNULL')) {
+                at += 1;
+                continue;
+            }
+            if (at_('NOT') && at_('NULL', 1)) {
+                at += 2;
+                continue;
+            }
+            if (at_('COLLATE')) {
+                at += 1;
+                const name = peek();
+                if (name?.kind !== 'keyword' || !COLLATION_NAMES.has(name.text)) {
+                    fail(`COLLATE needs a collation name (${[...COLLATION_NAMES].join(', ')}) but found ${describe(name)}`);
+                }
+                at += 1;
+                continue;
+            }
+            return;
+        }
+    }
+    function parseUnary() {
+        const token = peek();
+        if (token?.kind === 'operator' && PREFIX_OPERATORS.has(token.text)) {
+            at += 1;
+            parseUnary();
+            return;
+        }
+        if (at_('NOT')) {
+            at += 1;
+            parseExpression(NOT_PRECEDENCE);
+            return;
+        }
+        parsePrimary();
+        parsePostfix();
+    }
+    function parseExpression(minimum) {
+        parseUnary();
+        for (;;) {
+            let token = peek();
+            let negated = false;
+            if (token?.kind === 'keyword' && token.text === 'NOT') {
+                const following = peek(1);
+                if (following?.kind !== 'keyword' || !NEGATABLE.has(following.text))
+                    return;
+                negated = true;
+                token = following;
+            }
+            if (token === undefined || (token.kind !== 'operator' && token.kind !== 'keyword'))
+                return;
+            const precedence = BINARY_PRECEDENCE[token.text];
+            if (precedence === undefined || precedence < minimum)
+                return;
+            const word = token.text;
+            at += negated ? 2 : 1;
+            if (word === 'IS') {
+                if (at_('NOT'))
+                    at += 1;
+                parseExpression(precedence + 1);
+                continue;
+            }
+            if (word === 'IN') {
+                if (peek()?.kind !== 'open')
+                    fail(`IN needs a parenthesized list of values but found ${describe(peek())}`);
+                at += 1;
+                arguments_('An IN list');
+                continue;
+            }
+            if (word === 'BETWEEN') {
+                // The bounds are parsed above AND's precedence so the `AND` that separates them is not
+                // swallowed as an ordinary conjunction — which is what makes a missing one detectable.
+                parseExpression(BINARY_PRECEDENCE.AND + 1);
+                if (!at_('AND'))
+                    fail(`BETWEEN needs AND between its two bounds but found ${describe(peek())}`);
+                at += 1;
+                parseExpression(BINARY_PRECEDENCE.AND + 1);
+                continue;
+            }
+            parseExpression(precedence + 1);
+            if ((word === 'LIKE' || word === 'GLOB' || word === 'MATCH') && at_('ESCAPE')) {
+                at += 1;
+                parseExpression(precedence + 1);
+            }
+        }
+    }
+    parseExpression(0);
+    const trailing = peek();
+    if (trailing !== undefined) {
+        if (trailing.kind === 'comma') {
+            fail('A comma may only separate the arguments of a function call or the values of an IN list');
+        }
+        fail(`${describe(trailing)} needs an operator before it`);
+    }
+}
+function checkArity(name, count, source) {
+    const arity = SQL_FUNCTION_ARITY[name];
+    // Unreachable while the allowlist and the arity table agree, which a test enforces.
+    if (arity === undefined) {
+        throw new SqlExpressionError(`Function ${JSON.stringify(name)} has no declared argument count.`);
+    }
+    const [minimum, maximum] = arity;
+    const plural = (count_) => (count_ === 1 ? '1 argument' : `${count_} arguments`);
+    if (count < minimum) {
+        throw new SqlExpressionError(`Function ${JSON.stringify(name)} takes at least ${plural(minimum)} but was given ${count} `
+            + `in expression ${JSON.stringify(source)}.`);
+    }
+    if (count > maximum) {
+        throw new SqlExpressionError(`Function ${JSON.stringify(name)} takes at most ${plural(maximum)} but was given ${count} `
+            + `in expression ${JSON.stringify(source)}.`);
+    }
+}
+/** Single spaces everywhere except where SQL reads better — and always the same way. */
+function joinTokens(tokens) {
+    return tokens.reduce((sql, token, index) => {
+        if (index === 0)
+            return token.text;
+        const previous = tokens[index - 1];
+        const tight = previous.kind === 'open'
+            || token.kind === 'close' || token.kind === 'comma'
+            || (token.kind === 'open' && (previous.kind === 'function'
+                || (previous.kind === 'keyword' && previous.text === 'CAST')));
+        return tight ? sql + token.text : `${sql} ${token.text}`;
+    }, '');
+}
+/**
+ * Validate an author-written expression against the columns it is allowed to read, and return the
+ * canonical SQL for it. Throws {@link SqlExpressionError} with a message naming the rule it broke.
+ */
+export function compileSqlExpression(source, columns) {
+    if (source.length > SQL_EXPRESSION_MAX_LENGTH) {
+        throw new SqlExpressionError(`An expression may be at most ${SQL_EXPRESSION_MAX_LENGTH} characters; received ${source.length}, which is too long.`);
+    }
+    const tokens = lex(source);
+    const nodes = tokens.filter((token) => token.kind === 'operator' || token.kind === 'function' || token.kind === 'keyword').length;
+    if (nodes > SQL_EXPRESSION_MAX_NODES) {
+        throw new SqlExpressionError(`Expression ${JSON.stringify(source)} is too deeply nested: it builds ${nodes} operations and the limit is `
+            + `${SQL_EXPRESSION_MAX_NODES}, above which SQLite refuses to parse it. Split it into separate constraints.`);
+    }
+    validateGrammar(tokens, source, columns);
+    const declared = new Set(columns);
+    const referenced = new Set();
+    const emitted = tokens.map((token) => {
+        if (token.kind !== 'column')
+            return token;
+        if (!declared.has(token.text)) {
+            throw new SqlExpressionError(`Expression ${JSON.stringify(source)} references unknown column ${JSON.stringify(token.text)}.`);
+        }
+        referenced.add(token.text);
+        return { kind: 'column', text: sqlIdentifier(token.text) };
+    });
+    return { sql: joinTokens(emitted), columns: [...referenced].sort() };
+}