@syncular/typegen 0.5.1 → 0.7.0

package/dist/syql.js

@@ -1,1141 +0,0 @@
-/**
- * The `.syql` frontend (DESIGN-queries.md §3–§7): a functional CONTAINER —
- * GraphQL-style signatures + SQLDelight-style inference — around SQL
- * expressions. A file holds any number of `query` and `fragment`
- * declarations:
- *
- * ```text
- * fragment visibleIn(listId) {
- *   list_id = :listId and archived_at is null
- * }
- *
- * query listTodos(listId, status?, from+to?, unassigned?: flag)
- *   orderBy position | created_at | title default position
- *   limit max 200 default 50
- * {
- *   select id, title, done, created_at
- *   from todos
- *   where @visibleIn(:listId)
- *     and status = :status
- *     and created_at between :from and :to
- *     and if (:unassigned) { assignee_id is null }
- * }
- * ```
- *
- * Everything composes at GENERATE time: fragments splice textually (values
- * only — args are `:param` refs), optional params lower to §7 neutralization
- * guards (`:p IS NULL OR (…)`), knobs lower to a checked allowlist
- * (orderBy) and a bound+clamped param (limit), and the result is ONE plain
- * SQL statement that rides the exact same SQLite-check + naming-lowering
- * pipeline as the `.sql` tier. Nothing below the produced `AnalyzedQuery`
- * knows which frontend a query came from (§1).
- *
- * Conditional rules (§4, recommendation B with A as primitive):
- * - AUTO-GUARD: a top-level WHERE conjunct that mentions optional params
- *   applies only when ALL of them are provided.
- * - B1: an optional param outside a top-level conjunct (projection, FROM,
- *   subquery, or under an OR inside its conjunct) is a loud error telling
- *   the author to write an explicit `if` guard or make it required.
- * - B2: `if (:p, …) { predicate }` is the explicit primitive — required for
- *   flag params (which never appear in a predicate as written).
- */
-import { TypegenError } from './errors.js';
-import { snakeToCamel } from './naming.js';
-import { analyzeStatement, toPositionalSql, validateOverrideName, } from './query.js';
-const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-// ---------------------------------------------------------------------------
-// File parser
-// ---------------------------------------------------------------------------
-/** Cursor over the file with comment/whitespace skipping. */
-class Cursor {
-    src;
-    file;
-    i = 0;
-    constructor(src, file) {
-        this.src = src;
-        this.file = file;
-    }
-    fail(message) {
-        const line = this.src.slice(0, this.i).split('\n').length;
-        throw new TypegenError(`${this.file}:${line}`, message);
-    }
-    /** Skip whitespace and `--`/`/* *​/` comments. */
-    skip() {
-        for (;;) {
-            while (this.i < this.src.length && /\s/.test(this.src[this.i]))
-                this.i += 1;
-            if (this.src.startsWith('--', this.i)) {
-                const nl = this.src.indexOf('\n', this.i);
-                this.i = nl === -1 ? this.src.length : nl + 1;
-            }
-            else if (this.src.startsWith('/*', this.i)) {
-                const end = this.src.indexOf('*/', this.i + 2);
-                this.i = end === -1 ? this.src.length : end + 2;
-            }
-            else {
-                return;
-            }
-        }
-    }
-    atEnd() {
-        this.skip();
-        return this.i >= this.src.length;
-    }
-    /** Read one identifier-shaped word. */
-    word(what) {
-        this.skip();
-        const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(this.src.slice(this.i));
-        if (m === null)
-            this.fail(`expected ${what}`);
-        this.i += m[0].length;
-        return m[0];
-    }
-    /** Peek the next identifier-shaped word without consuming. */
-    peekWord() {
-        this.skip();
-        const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(this.src.slice(this.i));
-        return m === null ? null : m[0];
-    }
-    /** Consume one exact character. */
-    expect(ch) {
-        this.skip();
-        if (this.src[this.i] !== ch) {
-            this.fail(`expected ${JSON.stringify(ch)}`);
-        }
-        this.i += 1;
-    }
-    peekChar() {
-        this.skip();
-        return this.src[this.i];
-    }
-    /** Read a non-negative integer literal. */
-    int(what) {
-        this.skip();
-        const m = /^\d+/.exec(this.src.slice(this.i));
-        if (m === null)
-            this.fail(`expected ${what} (an integer)`);
-        this.i += m[0].length;
-        return Number.parseInt(m[0], 10);
-    }
-    /** Read a balanced `{ … }` block (string/comment aware); returns the
-     * INNER text. */
-    braceBlock() {
-        this.expect('{');
-        const start = this.i;
-        let depth = 1;
-        while (this.i < this.src.length) {
-            const ch = this.src[this.i];
-            if (ch === "'") {
-                this.i += 1;
-                while (this.i < this.src.length) {
-                    if (this.src[this.i] === "'") {
-                        if (this.src[this.i + 1] === "'")
-                            this.i += 2;
-                        else {
-                            this.i += 1;
-                            break;
-                        }
-                    }
-                    else
-                        this.i += 1;
-                }
-            }
-            else if (this.src.startsWith('--', this.i)) {
-                const nl = this.src.indexOf('\n', this.i);
-                this.i = nl === -1 ? this.src.length : nl + 1;
-            }
-            else if (this.src.startsWith('/*', this.i)) {
-                const end = this.src.indexOf('*/', this.i + 2);
-                this.i = end === -1 ? this.src.length : end + 2;
-            }
-            else if (ch === '{') {
-                depth += 1;
-                this.i += 1;
-            }
-            else if (ch === '}') {
-                depth -= 1;
-                this.i += 1;
-                if (depth === 0)
-                    return this.src.slice(start, this.i - 1);
-            }
-            else {
-                this.i += 1;
-            }
-        }
-        this.fail('unterminated { … } block');
-    }
-}
-function parseSignature(cur, owner) {
-    cur.expect('(');
-    const params = [];
-    const seen = new Set();
-    const push = (p) => {
-        if (!IDENT_RE.test(p.name)) {
-            cur.fail(`${owner}: invalid param name ${JSON.stringify(p.name)}`);
-        }
-        if (seen.has(p.name)) {
-            cur.fail(`${owner}: duplicate param ${JSON.stringify(p.name)}`);
-        }
-        seen.add(p.name);
-        params.push(p);
-    };
-    cur.skip();
-    if (cur.peekChar() === ')') {
-        cur.expect(')');
-        return params;
-    }
-    for (;;) {
-        const first = cur.word(`${owner}: param name`);
-        cur.skip();
-        if (cur.peekChar() === '+') {
-            // `from+to?` — an optional GROUP: both provided or both omitted.
-            cur.expect('+');
-            const second = cur.word(`${owner}: second param of the ${first}+ group`);
-            cur.skip();
-            if (cur.peekChar() !== '?') {
-                cur.fail(`${owner}: a ${first}+${second} group must be optional — write ${first}+${second}?`);
-            }
-            cur.expect('?');
-            const group = first;
-            push({ name: first, optional: true, group, flag: false });
-            push({ name: second, optional: true, group, flag: false });
-        }
-        else {
-            let optional = false;
-            if (cur.peekChar() === '?') {
-                cur.expect('?');
-                optional = true;
-            }
-            let flag = false;
-            cur.skip();
-            if (cur.peekChar() === ':') {
-                cur.expect(':');
-                const anno = cur.word(`${owner}: param annotation`);
-                if (anno !== 'flag') {
-                    cur.fail(`${owner}: unknown annotation ${JSON.stringify(anno)} — \`: flag\` is the only param annotation (§3); every other type is inferred`);
-                }
-                if (!optional) {
-                    cur.fail(`${owner}: a flag param is a guard — write ${first}?: flag`);
-                }
-                flag = true;
-            }
-            push({ name: first, optional, flag });
-        }
-        cur.skip();
-        if (cur.peekChar() === ',') {
-            cur.expect(',');
-            continue;
-        }
-        cur.expect(')');
-        return params;
-    }
-}
-function parseKnobs(cur, owner) {
-    let orderBy;
-    let limit;
-    let variants;
-    const depends = [];
-    const windows = [];
-    let keyBy;
-    const paramList = (label) => {
-        const out = [cur.word(`${owner}: ${label} param`)];
-        while (cur.peekChar() === '|') {
-            cur.expect('|');
-            out.push(cur.word(`${owner}: ${label} param`));
-        }
-        return out;
-    };
-    for (;;) {
-        const word = cur.peekWord();
-        if (word === 'variants') {
-            if (variants === true)
-                cur.fail(`${owner}: duplicate variants knob`);
-            cur.word('variants');
-            variants = true;
-        }
-        else if (word === 'depends') {
-            cur.word('depends');
-            const table = cur.word(`${owner}: dependency table`);
-            const on = cur.word(`${owner}: dependency \`on\``);
-            if (on !== 'on')
-                cur.fail(`${owner}: depends syntax is \`depends <table> on <scope> = <param>\``);
-            const variable = cur.word(`${owner}: dependency scope variable`);
-            cur.expect('=');
-            depends.push({ table, variable, params: paramList('dependency') });
-        }
-        else if (word === 'window') {
-            cur.word('window');
-            const table = cur.word(`${owner}: window table`);
-            const by = cur.word(`${owner}: window \`by\``);
-            if (by !== 'by')
-                cur.fail(`${owner}: window syntax is \`window <table> by <scope> = <param>\``);
-            const variable = cur.word(`${owner}: window scope variable`);
-            cur.expect('=');
-            const units = paramList('window unit');
-            const fixedScopes = [];
-            if (cur.peekWord() === 'fixed') {
-                cur.word('fixed');
-                for (;;) {
-                    const fixedVariable = cur.word(`${owner}: fixed scope variable`);
-                    cur.expect('=');
-                    const param = cur.word(`${owner}: fixed scope param`);
-                    fixedScopes.push({ variable: fixedVariable, param });
-                    if (cur.peekChar() !== ',')
-                        break;
-                    cur.expect(',');
-                }
-            }
-            windows.push({ table, variable, units, fixedScopes });
-        }
-        else if (word === 'key') {
-            if (keyBy !== undefined)
-                cur.fail(`${owner}: duplicate key by declaration`);
-            cur.word('key');
-            const by = cur.word(`${owner}: key \`by\``);
-            if (by !== 'by')
-                cur.fail(`${owner}: key syntax is \`key by <result-column>\``);
-            keyBy = paramList('key column');
-        }
-        else if (word === 'orderBy') {
-            if (orderBy !== undefined)
-                cur.fail(`${owner}: duplicate orderBy knob`);
-            cur.word('orderBy');
-            const allowed = [];
-            allowed.push(cur.word(`${owner}: orderBy column`));
-            cur.skip();
-            while (cur.peekChar() === '|') {
-                cur.expect('|');
-                allowed.push(cur.word(`${owner}: orderBy column`));
-                cur.skip();
-            }
-            const kw = cur.word(`${owner}: orderBy default`);
-            if (kw !== 'default') {
-                cur.fail(`${owner}: orderBy needs \`default <column>\` after the allowlist`);
-            }
-            const defaultColumn = cur.word(`${owner}: orderBy default column`);
-            if (!allowed.includes(defaultColumn)) {
-                cur.fail(`${owner}: orderBy default ${JSON.stringify(defaultColumn)} is not in the allowlist (${allowed.join(' | ')})`);
-            }
-            let defaultDir = 'asc';
-            const dir = cur.peekWord();
-            if (dir === 'asc' || dir === 'desc') {
-                cur.word('direction');
-                defaultDir = dir;
-            }
-            const dup = new Set();
-            for (const col of allowed) {
-                if (dup.has(col)) {
-                    cur.fail(`${owner}: orderBy lists ${JSON.stringify(col)} twice`);
-                }
-                dup.add(col);
-            }
-            orderBy = { allowed, defaultColumn, defaultDir };
-        }
-        else if (word === 'limit') {
-            if (limit !== undefined)
-                cur.fail(`${owner}: duplicate limit knob`);
-            cur.word('limit');
-            let max;
-            let def;
-            for (;;) {
-                const part = cur.peekWord();
-                if (part === 'max' && max === undefined) {
-                    cur.word('max');
-                    max = cur.int(`${owner}: limit max`);
-                }
-                else if (part === 'default' && def === undefined) {
-                    cur.word('default');
-                    def = cur.int(`${owner}: limit default`);
-                }
-                else {
-                    break;
-                }
-            }
-            if (max === undefined && def === undefined) {
-                cur.fail(`${owner}: limit needs \`max <n>\` and/or \`default <n>\``);
-            }
-            if (max !== undefined && def !== undefined && def > max) {
-                cur.fail(`${owner}: limit default ${def} exceeds max ${max}`);
-            }
-            limit = {
-                ...(max !== undefined ? { max } : {}),
-                ...(def !== undefined ? { default: def } : {}),
-            };
-        }
-        else {
-            return {
-                ...(orderBy !== undefined ? { orderBy } : {}),
-                ...(limit !== undefined ? { limit } : {}),
-                ...(variants !== undefined ? { variants } : {}),
-                ...(depends.length > 0 ? { depends } : {}),
-                ...(windows.length > 0 ? { windows } : {}),
-                ...(keyBy !== undefined ? { keyBy } : {}),
-            };
-        }
-    }
-}
-/** Parse one `.syql` file into its declarations (no lowering yet). */
-export function parseSyqlFile(file, content) {
-    const cur = new Cursor(content, file);
-    const fragments = [];
-    const queries = [];
-    const names = new Set();
-    while (!cur.atEnd()) {
-        cur.skip();
-        const offset = cur.i;
-        const kw = cur.word('`query` or `fragment`');
-        if (kw !== 'query' && kw !== 'fragment') {
-            cur.fail(`expected \`query\` or \`fragment\`, found ${JSON.stringify(kw)}`);
-        }
-        const name = cur.word(`${kw} name`);
-        validateOverrideName(name, file);
-        if (names.has(name)) {
-            cur.fail(`duplicate declaration ${JSON.stringify(name)} in ${file}`);
-        }
-        names.add(name);
-        const owner = `${kw} ${name}`;
-        const params = parseSignature(cur, owner);
-        if (kw === 'fragment') {
-            cur.skip();
-            const body = cur.braceBlock().trim();
-            if (body.length === 0)
-                cur.fail(`${owner}: empty fragment body`);
-            fragments.push({ name, params, body, offset });
-        }
-        else {
-            const knobs = parseKnobs(cur, owner);
-            cur.skip();
-            const body = cur.braceBlock().trim();
-            if (body.length === 0)
-                cur.fail(`${owner}: empty query body`);
-            queries.push({ name, params, ...knobs, body, offset });
-        }
-    }
-    return { fragments, queries };
-}
-// ---------------------------------------------------------------------------
-// SQL-shape scanning helpers (string/comment aware)
-// ---------------------------------------------------------------------------
-/** Blank out strings and comments (preserving length) so scans are safe. */
-function blank(sql) {
-    let out = '';
-    let i = 0;
-    while (i < sql.length) {
-        const ch = sql[i];
-        if (sql.startsWith('--', i)) {
-            const nl = sql.indexOf('\n', i);
-            const end = nl === -1 ? sql.length : nl;
-            out += ' '.repeat(end - i);
-            i = end;
-        }
-        else if (sql.startsWith('/*', i)) {
-            const close = sql.indexOf('*/', i + 2);
-            const end = close === -1 ? sql.length : close + 2;
-            out += ' '.repeat(end - i);
-            i = end;
-        }
-        else if (ch === "'") {
-            let j = i + 1;
-            for (;;) {
-                if (j >= sql.length)
-                    break;
-                if (sql[j] === "'") {
-                    if (sql[j + 1] === "'")
-                        j += 2;
-                    else {
-                        j += 1;
-                        break;
-                    }
-                }
-                else
-                    j += 1;
-            }
-            out += ' '.repeat(j - i);
-            i = j;
-        }
-        else {
-            out += ch;
-            i += 1;
-        }
-    }
-    return out;
-}
-/** All `:param` names in `text` (strings/comments already blanked). */
-function scanParams(text) {
-    const out = [];
-    for (const m of blank(text).matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)) {
-        const name = m[1];
-        if (!out.includes(name))
-            out.push(name);
-    }
-    return out;
-}
-const CLAUSE_ENDERS = new Set(['group', 'having', 'order', 'limit', 'window']);
-/** Locate the MAIN statement's WHERE clause at paren depth 0. */
-function findWhere(body) {
-    const b = blank(body);
-    let depth = 0;
-    let i = 0;
-    let kwStart = -1;
-    let start = -1;
-    while (i < b.length) {
-        const ch = b[i];
-        if (ch === '(')
-            depth += 1;
-        else if (ch === ')')
-            depth -= 1;
-        else if (/[A-Za-z_]/.test(ch)) {
-            let j = i + 1;
-            while (j < b.length && /[A-Za-z0-9_]/.test(b[j]))
-                j += 1;
-            const word = b.slice(i, j).toLowerCase();
-            if (depth === 0) {
-                if (start === -1 && word === 'where') {
-                    kwStart = i;
-                    start = j;
-                }
-                else if (start !== -1 && CLAUSE_ENDERS.has(word)) {
-                    return { kwStart, start, end: i };
-                }
-            }
-            i = j;
-            continue;
-        }
-        i += 1;
-    }
-    return start === -1 ? null : { kwStart, start, end: body.length };
-}
-/**
- * Split a WHERE expression into top-level conjuncts on `AND` — paren-aware,
- * and BETWEEN-aware (the `AND` closing a `BETWEEN` is not a conjunction).
- */
-function splitConjuncts(expr) {
-    const b = blank(expr);
-    const parts = [];
-    let depth = 0;
-    let braceDepth = 0;
-    let pendingBetween = 0;
-    let start = 0;
-    let i = 0;
-    while (i < b.length) {
-        const ch = b[i];
-        if (ch === '(')
-            depth += 1;
-        else if (ch === ')')
-            depth -= 1;
-        else if (ch === '{')
-            braceDepth += 1;
-        else if (ch === '}')
-            braceDepth -= 1;
-        else if (/[A-Za-z_]/.test(ch)) {
-            let j = i + 1;
-            while (j < b.length && /[A-Za-z0-9_]/.test(b[j]))
-                j += 1;
-            const word = b.slice(i, j).toLowerCase();
-            if (depth === 0 && braceDepth === 0) {
-                if (word === 'between')
-                    pendingBetween += 1;
-                else if (word === 'and') {
-                    if (pendingBetween > 0)
-                        pendingBetween -= 1;
-                    else {
-                        parts.push(expr.slice(start, i));
-                        start = j;
-                    }
-                }
-            }
-            i = j;
-            continue;
-        }
-        i += 1;
-    }
-    parts.push(expr.slice(start));
-    return parts.map((p) => p.trim()).filter((p) => p.length > 0);
-}
-// ---------------------------------------------------------------------------
-// Lowering
-// ---------------------------------------------------------------------------
-const FRAGMENT_REF_RE = /@([A-Za-z_][A-Za-z0-9_]*)\s*\(([^)]*)\)/;
-/**
- * Splice `@fragment(:arg, …)` refs (iteratively — fragments may use other
- * fragments; cycles are caught by a depth cap). Fragment params rename to
- * the caller's arg names; a fragment's OPTIONAL params propagate their
- * optionality into `paramInfo` (GraphQL-fragment variable propagation, §3)
- * unless the query declares the arg itself (the declaration wins).
- */
-function spliceFragments(body, fragments, paramInfo, location) {
-    let out = body;
-    for (let round = 0;; round += 1) {
-        if (round > 10) {
-            throw new TypegenError(location, 'fragment expansion exceeded depth 10 — fragments must not reference each other cyclically');
-        }
-        const blanked = blank(out);
-        const m = FRAGMENT_REF_RE.exec(blanked);
-        if (m === null)
-            return out;
-        const [, name, argText] = m;
-        const fragment = fragments.get(name);
-        if (fragment === undefined) {
-            throw new TypegenError(location, `unknown fragment @${name} — fragments are declared in the same .syql file`);
-        }
-        const args = argText
-            .split(',')
-            .map((a) => a.trim())
-            .filter((a) => a.length > 0);
-        if (args.length !== fragment.params.length) {
-            throw new TypegenError(location, `@${name} takes ${fragment.params.length} arg(s) (${fragment.params.map((p) => p.name).join(', ')}), got ${args.length}`);
-        }
-        const rename = new Map();
-        fragment.params.forEach((param, index) => {
-            const arg = args[index];
-            const argMatch = /^:([A-Za-z_][A-Za-z0-9_]*)$/.exec(arg);
-            if (argMatch === null) {
-                throw new TypegenError(location, `@${name}: arg ${index + 1} must be a \`:param\` reference (values only, I1), got ${JSON.stringify(arg)}`);
-            }
-            const argName = argMatch[1];
-            rename.set(param.name, argName);
-            // Propagate the fragment param's optionality unless the query
-            // declared this param itself.
-            const existing = paramInfo.get(argName);
-            if (existing === undefined) {
-                paramInfo.set(argName, {
-                    optional: param.optional,
-                    flag: param.flag,
-                    declared: false,
-                    ...(param.group !== undefined
-                        ? { group: `${name}.${param.group}` }
-                        : {}),
-                });
-            }
-            else if (!existing.declared && param.optional && !existing.optional) {
-                existing.optional = true;
-            }
-        });
-        // Substitute the fragment body's params, then splice parenthesized.
-        let pred = fragment.body;
-        const fragmentParams = new Set(fragment.params.map((p) => p.name));
-        for (const used of scanParams(pred)) {
-            if (!fragmentParams.has(used)) {
-                throw new TypegenError(location, `fragment ${name} uses :${used}, which is not among its params (${[...fragmentParams].join(', ')}) — fragments are closed over their signature`);
-            }
-        }
-        pred = pred.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (whole, p) => {
-            const to = rename.get(p);
-            return to === undefined ? whole : `:${to}`;
-        });
-        out = `${out.slice(0, m.index)}(${pred})${out.slice(m.index + m[0].length)}`;
-    }
-}
-const IF_GUARD_RE = /^if\s*\(([^)]*)\)\s*\{([\s\S]*)\}$/;
-/** Guard SQL for one param: value params test provision; flags test truth. */
-function guardTerm(name, info) {
-    if (info?.flag === true)
-        return `coalesce(:${name}, 0) = 0`;
-    return `:${name} is null`;
-}
-/**
- * Lower one query body: splice fragments, auto-guard optional conjuncts,
- * expand `if` guards, enforce B1. Returns plain SQL (knob tails are the
- * caller's job).
- */
-export function lowerSyqlBody(decl, fragments, location) {
-    const paramInfo = new Map();
-    for (const p of decl.params) {
-        paramInfo.set(p.name, {
-            optional: p.optional,
-            flag: p.flag,
-            declared: true,
-            ...(p.group !== undefined ? { group: p.group } : {}),
-        });
-    }
-    if (blank(decl.body).includes(';')) {
-        throw new TypegenError(location, 'a query body is exactly one SELECT statement — remove the `;`');
-    }
-    const spliced = spliceFragments(decl.body, fragments, paramInfo, location);
-    const isOptional = (name) => paramInfo.get(name)?.optional === true;
-    const where = findWhere(spliced);
-    const conjuncts = [];
-    const structured = [];
-    let loweredWhere = '';
-    if (where !== null) {
-        const expr = spliced.slice(where.start, where.end);
-        for (const conjunct of splitConjuncts(expr)) {
-            const ifMatch = IF_GUARD_RE.exec(conjunct);
-            if (ifMatch !== null) {
-                // B2 — the explicit primitive: if (:a, :b) { predicate }.
-                const guardParams = ifMatch[1]
-                    .split(',')
-                    .map((a) => a.trim())
-                    .filter((a) => a.length > 0)
-                    .map((a) => {
-                    const pm = /^:([A-Za-z_][A-Za-z0-9_]*)$/.exec(a);
-                    if (pm === null) {
-                        throw new TypegenError(location, `if (…) guards take \`:param\` refs, got ${JSON.stringify(a)}`);
-                    }
-                    return pm[1];
-                });
-                if (guardParams.length === 0) {
-                    throw new TypegenError(location, 'if () needs at least one :param');
-                }
-                const pred = ifMatch[2].trim();
-                if (pred.length === 0) {
-                    throw new TypegenError(location, 'if (…) { } has an empty predicate');
-                }
-                for (const g of guardParams) {
-                    const info = paramInfo.get(g);
-                    if (info === undefined) {
-                        throw new TypegenError(location, `if (:${g}): param ${g} is not declared in the signature`);
-                    }
-                    if (!info.optional) {
-                        throw new TypegenError(location, `if (:${g}): ${g} is required — an if-guard on a required param never varies; drop the guard or mark the param optional (${g}?)`);
-                    }
-                }
-                const guards = guardParams
-                    .map((g) => guardTerm(g, paramInfo.get(g)))
-                    .join(' or ');
-                conjuncts.push(`(${guards} or (${pred}))`);
-                structured.push({ pred, governing: guardParams });
-                continue;
-            }
-            const used = scanParams(conjunct);
-            const optionals = used.filter(isOptional);
-            const flags = used.filter((p) => paramInfo.get(p)?.flag === true);
-            if (flags.length > 0) {
-                throw new TypegenError(location, `flag param :${flags[0]} cannot appear in a predicate (§3 — it never binds as written). Use \`if (:${flags[0]}) { … }\`.`);
-            }
-            if (optionals.length === 0) {
-                conjuncts.push(conjunct);
-                structured.push({ pred: conjunct, governing: [] });
-                continue;
-            }
-            // B1 placement validator: inside its conjunct, an optional param must
-            // not sit under an OR or inside a subquery — semantics get murky;
-            // demand the explicit primitive.
-            const blankedConjunct = blank(conjunct).toLowerCase();
-            if (/\bor\b/.test(blankedConjunct)) {
-                throw new TypegenError(location, `optional param :${optionals[0]} sits under an OR — auto-guarding a disjunction is ambiguous (B1). Write \`if (:${optionals[0]}) { … }\` or make the param required.`);
-            }
-            if (/\bselect\b/.test(blankedConjunct)) {
-                throw new TypegenError(location, `optional param :${optionals[0]} sits inside a subquery — auto-guarding cannot see through it (B1). Write \`if (:${optionals[0]}) { … }\` or make the param required.`);
-            }
-            // Auto-guard (§4 B): the conjunct applies iff ALL its optional params
-            // (including every member of a touched group) are provided.
-            const governing = new Set(optionals);
-            for (const p of optionals) {
-                const group = paramInfo.get(p)?.group;
-                if (group !== undefined) {
-                    for (const [other, info] of paramInfo) {
-                        if (info.group === group)
-                            governing.add(other);
-                    }
-                }
-            }
-            const guards = [...governing]
-                .map((g) => guardTerm(g, paramInfo.get(g)))
-                .join(' or ');
-            conjuncts.push(`(${guards} or (${conjunct}))`);
-            structured.push({ pred: conjunct, governing: [...governing] });
-        }
-        loweredWhere = conjuncts.join(' and ');
-    }
-    // B1 (rest of statement): optional params may ONLY live in the WHERE.
-    const outsideWhere = where === null
-        ? spliced
-        : spliced.slice(0, where.start) + spliced.slice(where.end);
-    for (const used of scanParams(outsideWhere)) {
-        if (isOptional(used)) {
-            throw new TypegenError(location, `optional param :${used} appears outside the WHERE clause (B1) — optional params only guard top-level WHERE conjuncts; make it required or restructure`);
-        }
-    }
-    // Declared params must actually be used (flags are used by their guards —
-    // which splice into the WHERE — so this covers them too).
-    const usedAnywhere = new Set(scanParams(spliced));
-    for (const p of decl.params) {
-        if (!usedAnywhere.has(p.name)) {
-            throw new TypegenError(location, `param ${p.name} is declared but never used in the body`);
-        }
-    }
-    const sql = where === null
-        ? spliced
-        : `${spliced.slice(0, where.start)} ${loweredWhere}${spliced.slice(where.end).length > 0 ? ` ${spliced.slice(where.end).trimStart()}` : ''}`;
-    const prefix = (where === null ? spliced : spliced.slice(0, where.kwStart)).replace(/\s+/g, ' ');
-    const suffix = (where === null ? '' : spliced.slice(where.end)).replace(/\s+/g, ' ');
-    return {
-        sql: sql.replace(/\s+/g, ' ').trim(),
-        paramInfo,
-        prefix: prefix.trim(),
-        suffix: suffix.trim(),
-        conjuncts: structured.map((c) => ({
-            pred: c.pred.replace(/\s+/g, ' ').trim(),
-            governing: c.governing,
-        })),
-    };
-}
-// ---------------------------------------------------------------------------
-// Analysis (parse → lower → the shared SQLite-check pipeline)
-// ---------------------------------------------------------------------------
-function checkedReactiveMetadata(decl, base, params, ir, location) {
-    if (decl.depends === undefined &&
-        decl.windows === undefined &&
-        decl.keyBy === undefined) {
-        return base.reactive;
-    }
-    const paramByName = new Map(params.map((param) => [param.name, param]));
-    const explicitScopes = new Map();
-    const explicitTables = new Set();
-    const tableAndScope = (tableName, variable) => {
-        if (!base.tables.includes(tableName)) {
-            throw new TypegenError(location, `reactive declaration names table ${JSON.stringify(tableName)}, but the query does not read it`);
-        }
-        const table = ir.tables.find((candidate) => candidate.name === tableName);
-        if (table === undefined) {
-            throw new TypegenError(location, `unknown reactive table ${JSON.stringify(tableName)}`);
-        }
-        const scope = table.scopes.find((candidate) => candidate.variable === variable);
-        if (scope === undefined) {
-            throw new TypegenError(location, `table ${tableName} has no scope variable ${JSON.stringify(variable)}`);
-        }
-        return { table, scope };
-    };
-    const checkedParam = (tableName, variable, name) => {
-        const param = paramByName.get(name);
-        if (param === undefined) {
-            throw new TypegenError(location, `reactive declaration references undeclared param :${name}`);
-        }
-        if (param.optional === true) {
-            throw new TypegenError(location, `reactive scope ${tableName}.${variable} cannot use optional param :${name}; an absent value is not a window unit`);
-        }
-        const { table, scope } = tableAndScope(tableName, variable);
-        const column = table.columns.find((candidate) => candidate.name === scope.column);
-        if (column === undefined || column.type !== param.type) {
-            throw new TypegenError(location, `reactive param :${name} has type ${param.type}, incompatible with ${tableName}.${scope.column} (${column?.type ?? 'unknown'})`);
-        }
-        return param;
-    };
-    const addScope = (table, variable, names) => {
-        const { scope } = tableAndScope(table, variable);
-        explicitTables.add(table);
-        let byVariable = explicitScopes.get(table);
-        if (byVariable === undefined) {
-            byVariable = new Map();
-            explicitScopes.set(table, byVariable);
-        }
-        let binding = byVariable.get(variable);
-        if (binding === undefined) {
-            binding = { pattern: scope.pattern, params: new Set() };
-            byVariable.set(variable, binding);
-        }
-        for (const name of names) {
-            checkedParam(table, variable, name);
-            binding.params.add(name);
-        }
-    };
-    for (const dependency of decl.depends ?? []) {
-        addScope(dependency.table, dependency.variable, dependency.params);
-    }
-    const coverage = [];
-    const seenWindows = new Set();
-    for (const window of decl.windows ?? []) {
-        const key = `${window.table}\0${window.variable}`;
-        if (seenWindows.has(key)) {
-            throw new TypegenError(location, `duplicate window declaration for ${window.table}.${window.variable}`);
-        }
-        seenWindows.add(key);
-        const { table } = tableAndScope(window.table, window.variable);
-        addScope(window.table, window.variable, window.units);
-        const fixedByVariable = new Map();
-        for (const fixed of window.fixedScopes) {
-            if (fixed.variable === window.variable) {
-                throw new TypegenError(location, `window ${window.table}.${window.variable} repeats its unit scope as fixed`);
-            }
-            if (fixedByVariable.has(fixed.variable)) {
-                throw new TypegenError(location, `window ${window.table} repeats fixed scope ${fixed.variable}`);
-            }
-            checkedParam(window.table, fixed.variable, fixed.param);
-            fixedByVariable.set(fixed.variable, fixed.param);
-            addScope(window.table, fixed.variable, [fixed.param]);
-        }
-        const missing = table.scopes
-            .map((scope) => scope.variable)
-            .filter((variable) => variable !== window.variable && !fixedByVariable.has(variable));
-        if (missing.length > 0) {
-            throw new TypegenError(location, `window ${window.table}.${window.variable} must fix the remaining scope variables: ${missing.join(', ')}`);
-        }
-        coverage.push({
-            table: window.table,
-            variable: window.variable,
-            units: window.units,
-            fixedScopes: table.scopes
-                .filter((scope) => scope.variable !== window.variable)
-                .map((scope) => ({
-                variable: scope.variable,
-                params: [fixedByVariable.get(scope.variable)],
-            })),
-        });
-    }
-    const dependencies = base.reactive.dependencies.map((dependency) => {
-        if (!explicitTables.has(dependency.table))
-            return dependency;
-        const scopes = [...(explicitScopes.get(dependency.table)?.entries() ?? [])]
-            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-            .map(([variable, binding]) => ({
-            table: dependency.table,
-            variable,
-            pattern: binding.pattern,
-            params: [...binding.params],
-        }));
-        return { table: dependency.table, scopes };
-    });
-    let rowKey = base.reactive.rowKey;
-    if (decl.keyBy !== undefined) {
-        const fields = decl.keyBy.map((name) => {
-            const column = base.columns.find((candidate) => candidate.name === name || candidate.langName === name);
-            if (column === undefined) {
-                throw new TypegenError(location, `key by column ${JSON.stringify(name)} is not projected by the query`);
-            }
-            return column.langName;
-        });
-        if (new Set(fields).size !== fields.length) {
-            throw new TypegenError(location, 'key by contains a duplicate result column');
-        }
-        rowKey = fields;
-    }
-    return {
-        dependencies,
-        coverage: decl.windows === undefined
-            ? base.reactive.coverage
-            : [
-                ...base.reactive.coverage.filter((item) => !seenWindows.has(`${item.table}\0${item.variable}`)),
-                ...coverage,
-            ],
-        ...(rowKey !== undefined ? { rowKey } : {}),
-    };
-}
-/** Analyze every query of one `.syql` file into `AnalyzedQuery` units —
- * byte-compatible with the `.sql` frontend's output (§1: nothing below the
- * IR knows the frontend). */
-export function analyzeSyqlFile(relPath, content, ir, db, naming) {
-    const parsed = parseSyqlFile(relPath, content);
-    const fragments = new Map(parsed.fragments.map((f) => [f.name, f]));
-    if (parsed.queries.length === 0 && parsed.fragments.length > 0) {
-        throw new TypegenError(relPath, 'this .syql file declares only fragments — fragments are file-scoped, so at least one query must use them here');
-    }
-    return parsed.queries.map((decl) => {
-        const location = `${relPath} (query ${decl.name})`;
-        const lowered = lowerSyqlBody(decl, fragments, location);
-        const blanked = blank(lowered.sql).toLowerCase();
-        // Knob preconditions on the BODY (the knob owns the tail).
-        if (decl.orderBy !== undefined && /\border\s+by\b/.test(blanked)) {
-            throw new TypegenError(location, 'the body has an ORDER BY and the query declares an orderBy knob — one or the other');
-        }
-        if (decl.limit !== undefined && /\blimit\b/.test(blanked)) {
-            throw new TypegenError(location, 'the body has a LIMIT and the query declares a limit knob — one or the other');
-        }
-        if ((decl.limit !== undefined || decl.orderBy !== undefined) &&
-            lowered.paramInfo.has('limit')) {
-            throw new TypegenError(location, 'a query with a limit/orderBy knob cannot also declare a param named `limit`');
-        }
-        // Check every orderBy allowlist column against the schema FIRST (each
-        // variant is a real prepared statement — §6) so a bad column errors as
-        // "orderBy column …", not as the default-tail check.
-        if (decl.orderBy !== undefined) {
-            for (const column of decl.orderBy.allowed) {
-                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(column)) {
-                    throw new TypegenError(location, `orderBy column ${JSON.stringify(column)} is not a plain identifier`);
-                }
-                try {
-                    db.analyze(`${lowered.sql} order by ${column} asc`);
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    throw new TypegenError(location, `orderBy column ${JSON.stringify(column)} rejected by SQLite: ${message}`);
-                }
-            }
-        }
-        // Assemble the checked statement: default knob tails baked in, `-- param`
-        // headers typing what inference cannot see (flags, the limit bind). The
-        // limit's default + clamp live IN the SQL (`min(coalesce(:limit, d), m)`)
-        // so an absent runtime value is a no-op — the same neutralization idea
-        // as the §7 guards — and every emitter just binds `limit ?? null`.
-        const headers = [];
-        for (const [name, info] of lowered.paramInfo) {
-            if (info.flag)
-                headers.push(`-- param :${name} boolean`);
-        }
-        let limitTail = '';
-        if (decl.limit !== undefined) {
-            const fallback = decl.limit.default ?? decl.limit.max;
-            const inner = `coalesce(:limit, ${fallback})`;
-            limitTail = ` limit ${decl.limit.max !== undefined
-                ? `min(${inner}, ${decl.limit.max})`
-                : inner}`;
-            headers.push('-- param :limit integer');
-        }
-        let sqlWithTails = lowered.sql;
-        if (decl.orderBy !== undefined) {
-            sqlWithTails += ` order by ${decl.orderBy.defaultColumn} ${decl.orderBy.defaultDir}`;
-        }
-        sqlWithTails += limitTail;
-        const statementText = [...headers, sqlWithTails].join('\n');
-        const base = analyzeStatement(decl.name, location, statementText, ir, db, naming);
-        // Attach optionality/group/flag + knob metadata to the checked unit.
-        const params = base.params.map((param) => {
-            if (param.name === 'limit' && decl.limit !== undefined) {
-                return { ...param, optional: true };
-            }
-            const info = lowered.paramInfo.get(param.name);
-            if (info === undefined)
-                return param;
-            return {
-                ...param,
-                ...(info.optional ? { optional: true } : {}),
-                ...(info.group !== undefined ? { group: info.group } : {}),
-                ...(info.flag ? { flag: true } : {}),
-            };
-        });
-        const mode = naming?.naming ?? 'camel';
-        const mapCol = (name) => mode === 'preserve' ? name : snakeToCamel(name);
-        const reactive = checkedReactiveMetadata(decl, base, params, ir, location);
-        const orderBy = decl.orderBy === undefined
-            ? undefined
-            : {
-                allowed: decl.orderBy.allowed.map((name) => ({
-                    name,
-                    langName: mapCol(name),
-                })),
-                defaultColumn: decl.orderBy.defaultColumn,
-                defaultDir: decl.orderBy.defaultDir,
-            };
-        // The static base (positional) emitters compose dynamic tails onto:
-        // positionalSql minus the default tails we appended above. Sliced from
-        // the positional form itself so `?` vs `?N` numbering is preserved
-        // (the appended tails are by construction the LAST clauses).
-        let positionalSqlBase;
-        let positionalLimitTail;
-        if (decl.orderBy !== undefined) {
-            const orderIdx = base.positionalSql.lastIndexOf(' order by ');
-            if (orderIdx === -1) {
-                throw new TypegenError(location, 'internal: lowered SQL lost its appended order-by tail');
-            }
-            positionalSqlBase = base.positionalSql.slice(0, orderIdx);
-            if (decl.limit !== undefined) {
-                const limitIdx = base.positionalSql.lastIndexOf(' limit ');
-                if (limitIdx <= orderIdx) {
-                    throw new TypegenError(location, 'internal: lowered SQL lost its appended limit tail');
-                }
-                positionalLimitTail = base.positionalSql.slice(limitIdx);
-            }
-        }
-        // Drop the internal `-- param` typing headers from the exposed
-        // (projection-lowered) SQL.
-        const exposedSql = base.sql
-            .replace(/^(?:\s*-- param :[^\n]*\n)+/, '')
-            .trimStart();
-        // §7 variant-enumeration backend: opt-in per query (`variants`), or
-        // selected by the manifest's queryBackend heuristic — `auto` enumerates
-        // when the combination count is trivially small (N ≤ 2 groups → ≤ 4
-        // statements, perfect index use for free), `variants` enumerates
-        // whenever the query is eligible. Assembled by swapping the WHERE
-        // clause of the (projection-lowered) neutralization statement, so the
-        // two backends differ ONLY in guard mechanics — semantically identical
-        // by construction.
-        const optionalGroupCount = (() => {
-            const keys = new Set();
-            for (const [name, info] of lowered.paramInfo) {
-                if (info.optional)
-                    keys.add(info.group ?? name);
-            }
-            return keys.size;
-        })();
-        const backend = naming?.backend ?? 'neutralize';
-        const wantVariants = decl.variants === true ||
-            (decl.orderBy === undefined &&
-                optionalGroupCount > 0 &&
-                (backend === 'variants' ||
-                    (backend === 'auto' && optionalGroupCount <= 2)));
-        let variants;
-        let variantGroups;
-        if (wantVariants) {
-            if (decl.orderBy !== undefined) {
-                throw new TypegenError(location, 'the variants backend and the orderBy knob both multiply statements — they cannot combine (yet); drop one');
-            }
-            const groupList = [];
-            for (const [name, info] of lowered.paramInfo) {
-                if (!info.optional)
-                    continue;
-                const key = info.group ?? name;
-                const existing = groupList.find((g) => g.key === key);
-                if (existing !== undefined)
-                    existing.params.push(name);
-                else
-                    groupList.push({ key, params: [name], flag: info.flag });
-            }
-            const n = groupList.length;
-            if (n === 0) {
-                throw new TypegenError(location, 'the variants backend needs at least one optional param — a fully static query has exactly one variant already');
-            }
-            if (n > 8) {
-                throw new TypegenError(location, `${n} optional groups would enumerate ${2 ** n} statements — a query with nine independent optional filters is a design smell, not a codegen challenge (§7); split the query or drop \`variants\``);
-            }
-            if (n > 4) {
-                console.warn(`${location}: variants enumerates ${2 ** n} statements (${n} optional groups) — consider the default neutralization backend`);
-            }
-            const w = findWhere(exposedSql);
-            if (w === null)
-                throw new Error('unreachable: optional params ⇒ WHERE');
-            const before = exposedSql.slice(0, w.kwStart).trimEnd();
-            const after = exposedSql.slice(w.end).trim();
-            const groupOf = (param) => lowered.paramInfo.get(param)?.group ?? param;
-            const out = [];
-            for (let mask = 0; mask < 2 ** n; mask++) {
-                const provided = new Set(groupList.filter((_, i) => ((mask >> i) & 1) === 1).map((g) => g.key));
-                const included = lowered.conjuncts.filter((c) => c.governing.every((p) => provided.has(groupOf(p))));
-                const whereSql = included.map((c) => c.pred).join(' and ');
-                const sqlV = [
-                    before,
-                    ...(whereSql.length > 0 ? [`where ${whereSql}`] : []),
-                    ...(after.length > 0 ? [after] : []),
-                ]
-                    .join(' ')
-                    .replace(/\s+/g, ' ')
-                    .trim();
-                try {
-                    db.analyze(sqlV);
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    throw new TypegenError(location, `variant [${[...provided].join('+') || 'none'}] rejected by SQLite: ${message}`);
-                }
-                out.push({
-                    when: groupList
-                        .filter((_, i) => ((mask >> i) & 1) === 1)
-                        .map((g) => g.key),
-                    sql: sqlV,
-                    positionalSql: toPositionalSql(sqlV),
-                    params: scanParams(sqlV),
-                });
-            }
-            variants = out;
-            variantGroups = groupList.map((g) => ({
-                key: g.key,
-                params: g.params,
-                flag: g.flag,
-            }));
-        }
-        return {
-            ...base,
-            sourceSql: decl.body.trim(),
-            sql: exposedSql,
-            params,
-            reactive,
-            ...(orderBy !== undefined ? { orderBy } : {}),
-            ...(decl.limit !== undefined ? { limit: decl.limit } : {}),
-            ...(positionalSqlBase !== undefined ? { positionalSqlBase } : {}),
-            ...(positionalLimitTail !== undefined && decl.orderBy !== undefined
-                ? { positionalLimitTail }
-                : {}),
-            ...(variants !== undefined ? { variants } : {}),
-            ...(variantGroups !== undefined ? { variantGroups } : {}),
-        };
-    });
-}