sqllens 1.8.1 → 1.9.0

package/dist/bigquery/parse.js

@@ -85,6 +85,7 @@ export const fragmentGrammar = defineFragmentGrammar({
     newLexer: (input) => new GoogleSQLLexer(input),
     newParser: (tokens) => new GoogleSQLParser(tokens),
     postParse: postParseDiagnostics,
+    separator: GoogleSQLLexer.COMMA_SYMBOL,
     entries: {
         statement: (p) => p.root(),
         expression: (p) => p.expression(),

package/dist/databricks/parse.js

@@ -79,6 +79,7 @@ function attachErrorCounter(lexer, parser, listener) {
 export const fragmentGrammar = defineFragmentGrammar({
     newLexer: (input) => new DatabricksLexer(input),
     newParser: (tokens) => new DatabricksParser(tokens),
+    separator: DatabricksLexer.COMMA,
     entries: {
         statement: (p) => p.multiStatement(),
         expression: (p) => p.expression(),

package/dist/duckdb/parse.js

@@ -70,6 +70,7 @@ function attachErrorCounter(lexer, parser, listener) {
 export const fragmentGrammar = defineFragmentGrammar({
     newLexer: (input) => new DuckdbLexer(input),
     newParser: (tokens) => new DuckdbParser(tokens),
+    separator: DuckdbLexer.COMMA,
     entries: {
         statement: (p) => p.root(),
         expression: (p) => p.a_expr(),

package/dist/fragment-grammar.d.ts

@@ -38,6 +38,9 @@ export interface FragmentGrammarSpec<P extends Parser> {
     entries: {
         readonly [K in FragmentKind]: FragmentEntry<P>;
     };
+    /** The list separator token type (COMMA). A list body (`cteList`/`selectList`) may end with
+     *  one: a macro's CTE list often ends `),` because the caller appends more CTEs. */
+    separator: number;
     /** Tree-walking checks the dialect's statement entry runs after the parse (bigquery). */
     postParse?: (tree: ParserRuleContext) => SyntaxDiagnostic[];
 }

package/dist/fragment-grammar.js

@@ -19,12 +19,14 @@ export const FRAGMENT_KINDS = [
     "cteList",
     "selectList",
 ];
+const LIST_KINDS = new Set(["cteList", "selectList"]);
 /** `item (sep item)*` driven from outside the grammar, for dialects without a list rule
  *  (a CTE list without its WITH, a select list). The tree is the FIRST item's. */
 export function separatedList(item, separator) {
     return (parser) => {
         const first = item(parser);
-        while (parser.inputStream.LA(1) === separator) {
+        // A separator followed by EOF is a trailing one (`run` consumes it), not another item.
+        while (parser.inputStream.LA(1) === separator && parser.inputStream.LA(2) !== AntlrToken.EOF) {
             parser.inputStream.consume(); // between rules there is no context to attach the separator to
             item(parser);
         }
@@ -48,7 +50,15 @@ function trailingInput(parser) {
 }
 /** Bind a dialect's lexer, parser and fragment entry rules into a `FragmentGrammar`. */
 export function defineFragmentGrammar(spec) {
-    const { newLexer, newParser, entries, postParse } = spec;
+    const { newLexer, newParser, entries, separator, postParse } = spec;
+    /** The entry, then a trailing separator on a list body is consumed rather than left over. */
+    const run = (parser, kind) => {
+        const tree = entries[kind](parser);
+        const input = parser.inputStream;
+        if (LIST_KINDS.has(kind) && input.LA(1) === separator && input.LA(2) === AntlrToken.EOF)
+            input.consume();
+        return tree;
+    };
     const lex = spec.lex ??
         ((text) => {
             const lexer = newLexer(CharStream.fromString(text));
@@ -69,7 +79,7 @@ export function defineFragmentGrammar(spec) {
                 sim.predictionMode = PredictionMode.SLL;
                 let tree;
                 try {
-                    tree = entries[kind](parser);
+                    tree = run(parser, kind);
                 }
                 catch {
                     return undefined;
@@ -82,7 +92,7 @@ export function defineFragmentGrammar(spec) {
                 return post.length === 0 ? { tree, diagnostics: [] } : undefined;
             }
             sim.predictionMode = PredictionMode.LL;
-            const tree = entries[kind](parser);
+            const tree = run(parser, kind);
             const trailing = trailingInput(parser);
             return {
                 tree,

package/dist/fragment.d.ts

@@ -24,6 +24,9 @@ export interface FragmentSession {
      * verdict). Never throws: every attempt runs a recovering parser over a fixed kind list.
      */
     parse(ranges: readonly FragmentRange[], kinds?: readonly FragmentKind[]): FragmentResult | undefined;
+    /** The first kind the ranges parse clean as, or undefined (no token, or no clean reading).
+     *  Probes only (SLL + bail); never a diagnostic. */
+    verdict(ranges: readonly FragmentRange[], kinds?: readonly FragmentKind[]): FragmentKind | undefined;
 }
 /** Lex `text` once with `dialect`'s statement-entry token pipeline; parse ranges of it after. */
 export declare function openFragments(text: string, dialect: Dialect): FragmentSession;

package/dist/fragment.js

@@ -41,19 +41,36 @@ export function openFragments(text, dialect) {
     const grammar = FRAGMENT_GRAMMARS[dialect];
     const lexed = grammar.lex(text);
     const inRanges = (offset, ranges) => ranges.some((r) => offset >= r.start && offset < r.end);
+    const sliceOf = (ranges) => {
+        const slice = lexed.tokens.filter((t) => inRanges(t.start, ranges));
+        return slice.some((t) => t.channel === 0) ? slice : undefined;
+    };
+    // Token-derived diagnostics of a slice (bigquery literal escapes) hold under every reading.
+    const lexDiagsOf = (ranges) => lexed.diagnostics.filter((d) => d.offset !== undefined && inRanges(d.offset, ranges));
+    const probe = (slice, kinds) => {
+        for (const kind of kinds) {
+            const clean = grammar.parse(slice, kind, true);
+            if (clean)
+                return { kind, clean: true, tree: clean.tree, diagnostics: [] };
+        }
+        return undefined;
+    };
     return {
+        verdict(ranges, kinds = FRAGMENT_KINDS) {
+            const slice = sliceOf(ranges);
+            if (!slice || lexDiagsOf(ranges).length > 0)
+                return undefined;
+            return probe(slice, kinds)?.kind;
+        },
         parse(ranges, kinds = FRAGMENT_KINDS) {
-            const slice = lexed.tokens.filter((t) => inRanges(t.start, ranges));
-            if (!slice.some((t) => t.channel === 0))
+            const slice = sliceOf(ranges);
+            if (!slice)
                 return undefined;
-            // Token-derived diagnostics of the slice (bigquery literal escapes) hold under every reading.
-            const lexDiags = lexed.diagnostics.filter((d) => d.offset !== undefined && inRanges(d.offset, ranges));
+            const lexDiags = lexDiagsOf(ranges);
             if (lexDiags.length === 0) {
-                for (const kind of kinds) {
-                    const clean = grammar.parse(slice, kind, true);
-                    if (clean)
-                        return { kind, clean: true, tree: clean.tree, diagnostics: [] };
-                }
+                const clean = probe(slice, kinds);
+                if (clean)
+                    return clean;
             }
             let best;
             let bestAt = -1;

package/dist/minijinja/index.d.ts

@@ -1,5 +1,6 @@
 export { minijinja } from "./engine.js";
-export { parseTemplated, tokenizeTemplated } from "./parse.js";
+export { parseTemplated, tokenizeTemplated, shapesForCall } from "./parse.js";
+export type { MacroShape } from "../template/engine.js";
 export type { TemplatedParseResult, TemplatedParseOptions } from "../template/engine.js";
 export type { TagNode, MacroCall } from "./parse.js";
 export { templateRegions, templateSymbols } from "./regions.js";

package/dist/minijinja/index.js

@@ -3,6 +3,6 @@
 // canonically declared in src/template/engine.ts and re-exported both there
 // and here.
 export { minijinja } from "./engine.js";
-export { parseTemplated, tokenizeTemplated } from "./parse.js";
+export { parseTemplated, tokenizeTemplated, shapesForCall } from "./parse.js";
 export { templateRegions, templateSymbols } from "./regions.js";
 export { templateVariants } from "./variants.js";

package/dist/minijinja/parse.d.ts

@@ -1,10 +1,20 @@
 import type { Dialect } from "../dialect.js";
 import type { Token } from "../token/token.js";
-import type { TemplatedParseOptions, TemplatedParseResult } from "../template/engine.js";
+import type { MacroShape, TemplatedParseOptions, TemplatedParseResult } from "../template/engine.js";
+import type { ExpansionShape } from "../qualify/template-provider.js";
+import type { TemplateCall } from "../ir/ir.js";
 export type { TagNode, MacroCall } from "./tag-ast.js";
 export type { TemplateRegion, TemplateArm, TemplateSymbol } from "./regions.js";
 export { templateRegions, templateSymbols } from "./regions.js";
-export type { TemplatedParseOptions, TemplatedParseResult } from "../template/engine.js";
+export type { MacroShape, TemplatedParseOptions, TemplatedParseResult } from "../template/engine.js";
+/**
+ * The shapes a specific CALL of a macro takes: `macro.shapes`, with the keyword-parameter hole
+ * (if any) resolved from the call's own literal argument (positional or keyword) or the
+ * parameter's default. A call whose keyword is not a literal, or names a word that opens no
+ * known clause, resolves to nothing for that hole (never-wrong). Pure: definition text + call
+ * text, no project knowledge; a host's `shapeOf(call)` is `shapesForCall(index.get(call.name), call)`.
+ */
+export declare function shapesForCall(macro: MacroShape, call: TemplateCall): ExpansionShape[];
 /**
  * Parse raw jinja-SQL: one whole-document jinja lex (segment()), the untouched
  * per-dialect SQL parse over the resulting placeholder, a per-tag jinja parse over

package/dist/minijinja/parse.js

@@ -202,28 +202,49 @@ function parseSliceTag(slice) {
     const tree = parser.tag();
     return { tree, diagnostics: collector.diagnostics };
 }
+/** A pure placeholder-fill run: `j` + up to two base-35 ordinal chars + `j` padding (segment.ts). */
+const FILL_RUN = /^j[0-9a-ik-z]{0,2}j*$/;
 /**
- * Scrub placeholder gibberish out of SQL syntax diagnostics. A diagnostic whose
- * offending token starts inside a tag range is really complaining about the TAG:
- * rewrite every occurrence of the placeholder token's text in the message with the
- * tag's original source text, and widen offset/length (+ line/column) to the whole
- * tag. Diagnostics outside every tag pass through untouched. `bySegment` carries the
- * widened diagnostics keyed by the owning tag segment — build() maps that back to a
- * TagNode for `diagnosticsOf`.
+ * Scrub placeholder gibberish out of SQL syntax diagnostics. Two parts:
+ *   - every message: each placeholder FILL RUN of any tag is rewritten to that tag's original
+ *     source text. ANTLR's "no viable alternative at input '…'" quotes a whole token RANGE, so a
+ *     fill can sit inside a message whose offending token is plain SQL far away; fills are
+ *     ordinal-unique, so plain substring replacement (longest fill first, a shorter fill can be
+ *     a prefix of a longer one) is exact;
+ *   - a diagnostic whose offending token starts inside a tag range is really complaining about
+ *     the TAG: its offset/length (+ line/column) widen to the whole tag.
+ * `bySegment` carries the widened diagnostics keyed by the owning tag segment — build() maps
+ * that back to a TagNode for `diagnosticsOf`.
  */
 function scrubPlaceholderDiagnostics(diags, tagRanges, text, placeholder) {
     const bySegment = new Map();
     if (tagRanges.length === 0)
         return { diagnostics: diags, bySegment };
+    // fill run → the tag's source text, longest fill first.
+    const fills = [];
+    for (const tag of tagRanges) {
+        const tagText = text.slice(tag.start, tag.end);
+        for (const run of placeholder.slice(tag.start, tag.end).split(/\s+/)) {
+            if (run.length >= 3 && FILL_RUN.test(run))
+                fills.push([run, tagText]);
+        }
+    }
+    fills.sort((a, b) => b[0].length - a[0].length);
+    const scrubMessage = (message) => {
+        for (const [run, tagText] of fills)
+            if (message.includes(run))
+                message = message.split(run).join(tagText);
+        return message;
+    };
     const diagnostics = diags.map((d) => {
-        if (d.offset === undefined)
-            return d;
-        const tag = tagRanges.find((s) => d.offset >= s.start && d.offset < s.end);
-        if (!tag)
-            return d;
+        const tag = d.offset === undefined ? undefined : tagRanges.find((s) => d.offset >= s.start && d.offset < s.end);
+        if (!tag) {
+            const message = scrubMessage(d.message);
+            return message === d.message ? d : { ...d, message };
+        }
         const seen = placeholder.slice(d.offset, d.offset + d.length);
         const tagText = text.slice(tag.start, tag.end);
-        const message = seen.length > 0 ? d.message.split(`'${seen}'`).join(`'${tagText}'`) : d.message;
+        const message = scrubMessage(seen.length > 0 ? d.message.split(`'${seen}'`).join(`'${tagText}'`) : d.message);
         const pos = docPosAt(text, tag.start);
         const widened = {
             ...d,
@@ -247,10 +268,12 @@ function scrubPlaceholderDiagnostics(diags, tagRanges, text, placeholder) {
  * diagnostics are replaced wholesale: they are recovery noise once a body has derailed it
  * (a body that is a CASE expression leaves "missing 'CASE' at EOF" far outside itself).
  * What replaces them: the text OUTSIDE the macro bodies read as a statement batch (a model
- * file that also defines a macro keeps its real errors), plus each body's own fragment
- * read. Lexer diagnostics (offset-less) are kept as they are. Each region learns what its
- * body is (`body`); a body with no SQL token gets no verdict and no diagnostic. Mutates the
- * regions' `body` field only. Files without a macro region are untouched.
+ * file that also defines a macro keeps its real errors). Lexer diagnostics (offset-less)
+ * are kept as they are. Each region learns what its body is (`body`); a body that reads
+ * clean as none of the kinds carries NO diagnostic and no verdict: a body is whatever gets
+ * pasted at the call site (a clause tail led by a keyword hole has no reading and never
+ * will), so "matches no known shape" is not evidence of invalid SQL (never-wrong). Mutates
+ * the regions' `body` field only. Files without a macro region are untouched.
  */
 function reparseMacroBodies(regions, diagnostics, placeholder, dialect) {
     const macros = [];
@@ -270,7 +293,6 @@ function reparseMacroBodies(regions, diagnostics, placeholder, dialect) {
         return diagnostics;
     const fragments = openFragments(placeholder, dialect);
     const bodies = [];
-    const own = [];
     for (const region of macros) {
         const arm = region.arms[0];
         if (!arm)
@@ -282,12 +304,9 @@ function reparseMacroBodies(regions, diagnostics, placeholder, dialect) {
         if (body.end <= body.start)
             continue;
         bodies.push(body);
-        const fragment = fragments.parse([body]);
-        if (!fragment)
-            continue;
-        own.push(...fragment.diagnostics);
-        if (fragment.clean)
-            region.body = fragment.kind;
+        const verdict = fragments.verdict([body]);
+        if (verdict)
+            region.body = verdict;
     }
     // The remainder: everything between the bodies, as the statement batch it always was.
     const remainder = [];
@@ -300,7 +319,153 @@ function reparseMacroBodies(regions, diagnostics, placeholder, dialect) {
     if (at < placeholder.length)
         remainder.push({ start: at, end: placeholder.length });
     const rest = fragments.parse(remainder, ["statement"]);
-    return [...diagnostics.filter((d) => d.offset === undefined), ...(rest?.diagnostics ?? []), ...own];
+    return [...diagnostics.filter((d) => d.offset === undefined), ...(rest?.diagnostics ?? [])];
+}
+/** Insert a hidden WS-shaped token over every gap in the source-ordered stream whose original text
+ *  is not pure whitespace (see the call site). Mutates `tokens` in place, keeping it sorted. */
+function fillDeadGaps(tokens, text) {
+    const out = [];
+    let at = 0;
+    const fill = (start, end) => {
+        const slice = text.slice(start, end);
+        if (slice.trim().length === 0)
+            return;
+        const pos = docPosAt(text, start);
+        const endPos = endPosition(pos.line, pos.column, slice);
+        out.push({
+            type: 0, // antlr's INVALID_TYPE: no lexer rule produced this token
+            name: "WS",
+            text: slice,
+            start,
+            stop: end - 1,
+            line: pos.line,
+            column: pos.column,
+            endLine: endPos.endLine,
+            endColumn: endPos.endColumn,
+            channel: 1,
+            role: "whitespace",
+        });
+    };
+    for (const tok of tokens) {
+        if (tok.start > at)
+            fill(at, tok.start);
+        out.push(tok);
+        at = Math.max(at, tok.stop + 1);
+    }
+    if (at < text.length)
+        fill(at, text.length);
+    if (out.length !== tokens.length)
+        tokens.splice(0, tokens.length, ...out);
+}
+/** Fragment verdict → the provider's shape vocabulary (`MacroShape.shapes`). */
+const VERDICT_SHAPE = {
+    statement: "statement",
+    expression: "expr",
+    tableSource: "relation",
+    cteList: "cte-definition",
+    selectList: "column-list",
+};
+/** The keyword a leading hole's jinja `default('…')` filter names → the clause shape it opens. */
+const DEFAULT_KEYWORD_SHAPE = {
+    where: "where-clause",
+    and: "conjunct",
+    or: "conjunct",
+};
+/**
+ * `MacroShape` for every macro region, read from the text alone. Three sources, all in-text:
+ *   1. the body's fragment verdict (`region.body`), mapped 1:1;
+ *   2. a body led by a `{{ x|default('where') }}`-style hole: the default literal is the
+ *      keyword the body opens with (`where` → where-clause, `and`/`or` → conjunct);
+ *   3. control flow: when every SQL byte of the body sits under `if` regions that have no
+ *      `else` arm, the macro can render to nothing → `nothing`, last.
+ * Anything else stays out (never-wrong): a hole with no visible default, a return-only body.
+ */
+function macroShapesOf(regions, tags, text, placeholder) {
+    const out = [];
+    const visit = (list) => {
+        for (const region of list) {
+            if (region.kind !== "macro") {
+                for (const arm of region.arms)
+                    visit(arm.children);
+                continue;
+            }
+            const arm = region.arms[0];
+            const open = tags.find((t) => t.kind === "control" && t.keyword === "macro" && t.tagSpan.start === region.span.start);
+            if (!arm || !open?.name || !open.nameSpan)
+                continue;
+            const shapes = [];
+            let keywordParam;
+            if (region.body)
+                shapes.push(VERDICT_SHAPE[region.body]);
+            else {
+                // A body opening with a hole: `{{ name }}` / `{{ name|default('kw') }}`, `name` one of
+                // the macro's declared parameters (the signature's args are bare identifiers).
+                const lead = leadingHole(arm.bodySpan, tags, placeholder);
+                const holeText = lead ? text.slice(lead.tagSpan.start, lead.tagSpan.end) : "";
+                const bound = /^\{\{-?\s*([A-Za-z_]\w*)\s*(?:\||-?\}\})/.exec(holeText)?.[1];
+                const params = (open.calls[0]?.args ?? []).map((a) => text.slice(a.span.start, a.span.end).trim());
+                const index = bound === undefined ? -1 : params.indexOf(bound);
+                const fallback = /\|\s*default\(\s*['"](\w+)['"]\s*\)/.exec(holeText)?.[1];
+                if (bound !== undefined && index >= 0) {
+                    keywordParam = { name: bound, index, ...(fallback !== undefined ? { default: fallback } : {}) };
+                }
+                const clause = fallback ? DEFAULT_KEYWORD_SHAPE[fallback.toLowerCase()] : undefined;
+                if (clause)
+                    shapes.push(clause);
+            }
+            if ((shapes.length > 0 || keywordParam) && rendersToNothing(arm, placeholder))
+                shapes.push("nothing");
+            out.push({
+                name: open.name,
+                nameSpan: open.nameSpan,
+                span: region.span,
+                shapes,
+                ...(keywordParam ? { keywordParam } : {}),
+            });
+        }
+    };
+    visit(regions);
+    return out;
+}
+/**
+ * The shapes a specific CALL of a macro takes: `macro.shapes`, with the keyword-parameter hole
+ * (if any) resolved from the call's own literal argument (positional or keyword) or the
+ * parameter's default. A call whose keyword is not a literal, or names a word that opens no
+ * known clause, resolves to nothing for that hole (never-wrong). Pure: definition text + call
+ * text, no project knowledge; a host's `shapeOf(call)` is `shapesForCall(index.get(call.name), call)`.
+ */
+export function shapesForCall(macro, call) {
+    const kp = macro.keywordParam;
+    if (!kp)
+        return macro.shapes;
+    const kwarg = call.kwargs?.find((k) => k.name === kp.name)?.value;
+    const positional = call.args[kp.index];
+    const word = (kwarg ?? positional ?? kp.default)?.toLowerCase();
+    const clause = word !== undefined ? DEFAULT_KEYWORD_SHAPE[word] : undefined;
+    const rest = macro.shapes.filter((s) => s !== "where-clause" && s !== "conjunct");
+    return clause ? [clause, ...rest] : rest;
+}
+/** The expression tag at the very start of a body (only whitespace, comments and control tags
+ *  before it in the placeholder), or undefined when the body opens with SQL. */
+function leadingHole(body, tags, placeholder) {
+    const first = placeholder.slice(body.start, body.end).search(/\S/);
+    if (first === -1)
+        return undefined;
+    const at = body.start + first;
+    return tags.find((t) => (t.kind === "call" || t.kind === "other") && t.tagSpan.start <= at && at < t.tagSpan.end);
+}
+/** True when every non-whitespace placeholder byte of the arm's body lies inside an `if` child
+ *  region that has no `else` arm: nothing outside such regions, so the macro can render empty. */
+function rendersToNothing(arm, placeholder) {
+    const optional = arm.children.filter((c) => c.kind === "if" && !c.arms.some((a) => a.keyword === "else"));
+    if (optional.length === 0)
+        return false;
+    const chars = placeholder.slice(arm.bodySpan.start, arm.bodySpan.end).split("");
+    for (const c of optional) {
+        for (let k = c.span.start; k < c.span.end; k++)
+            chars[k - arm.bodySpan.start] = " ";
+    }
+    return chars.join("").trim().length === 0;
 }
 /** The core build — total by construction (every composed piece is total). */
 function build(text, dialect, provider) {
@@ -365,6 +530,12 @@ function build(text, dialect, provider) {
     // disjoint (tag-contained SQL tokens were dropped), so a stable sort by start
     // (stop as tiebreak) tiles the source.
     const tokens = [...sqlTokens, ...jinjaTokens].sort((a, b) => a.start - b.start || a.stop - b.stop);
+    // Dead text with no carrier: the statically-dead loop arm above rides as trivia ONLY when an SQL
+    // token covers its blanked span. A dialect whose whitespace rule is `-> skip` (tsql) lexes no
+    // token over an all-space span, so the arm's true text (`union all`, a trailing `,`) would fall
+    // out of the stream. Every uncovered gap holding non-whitespace source text gets a synthesized
+    // hidden trivia token carrying that text, the same shape the carrier token takes elsewhere.
+    fillDeadGaps(tokens, text);
     // Diagnostics: SQL + jinja, both already in document coordinates, source-ordered
     // so squiggles line up with the merged stream. SQL diagnostics whose offending
     // token is a placeholder fill are scrubbed first — the message quotes the ORIGINAL
@@ -385,6 +556,7 @@ function build(text, dialect, provider) {
     // the statement parse reported inside that body. The IR and tokens stay the whole-file
     // parse's: the fragment verdict rides the region as `body`.
     const sqlDiagnostics = reparseMacroBodies(regions, sqlResult.diagnostics, placeholder, dialect);
+    const macros = macroShapesOf(regions, tags, text, placeholder);
     const { diagnostics: scrubbed, bySegment } = scrubPlaceholderDiagnostics(sqlDiagnostics, tagRanges, text, placeholder);
     // Fold the scrubbed SQL diagnostics into the same per-tag map as the jinja ones
     // (Task 10) — a tag's diagnostics are its own jinja parse errors PLUS whatever
@@ -407,6 +579,7 @@ function build(text, dialect, provider) {
         tags,
         regions,
         symbols,
+        macros,
         diagnostics,
         placeholder,
         tagOf: (node) => correlation.byNode.get(node),
@@ -436,6 +609,7 @@ export function parseTemplated(text, dialect, opts) {
             tags: [],
             regions: [],
             symbols: [],
+            macros: [],
             diagnostics: sql.diagnostics,
             placeholder: text,
             degraded: true,

package/dist/minijinja/segment.js

@@ -568,7 +568,11 @@ export function segment(text, provider) {
         // ONE provider consult per tag — the uniform seam. stmt/comment tags are pure
         // jinja control text and always whitespace-fill (no consult needed).
         const exp = seg.tagKind === "expr" && info.call ? provider.expansion(info.call) : undefined;
-        const shape = exp?.shape;
+        // Candidate shapes, most specific first. The first one the slot admits fills the tag;
+        // `nothing`/`expr` never fail admission, so a list ends with one of them or falls through
+        // to the identifier fill like a single unadmitted shape does.
+        const candidates = exp?.shapes ?? (exp?.shape !== undefined ? [exp.shape] : []);
+        let shape = candidates[0];
         // Fusion boundary (anvil torture-corpus, 2026-07-06): a tag GLUED to a preceding SQL
         // clause/operator keyword (`from{{ ref('x') }}` — dbt compiles it because the rendered
         // relation opens with a quote char) must not fuse with the fill into one token: the old
@@ -595,19 +599,25 @@ export function segment(text, provider) {
         // comma is omitted. Anything else — another CTE name, or "" (ambiguous) — keeps it, which
         // is exactly the already-working "another CTE follows" behavior, unchanged.
         let shaped;
-        if (shape === "cte-definition") {
-            if (info.isCall && cteDefinitionSlotAdmits(slot)) {
-                const needsComma = !QUERY_START_WORDS.has(followingSlot(chars, seg.end));
-                shaped = fitWindow(seg, `${PLACEHOLDER_CHAR}${ordinalFill(ordinal)} as (select 1)${needsComma ? "," : ""}`);
+        for (const candidate of candidates) {
+            shape = candidate;
+            if (candidate === "cte-definition") {
+                if (info.isCall && cteDefinitionSlotAdmits(slot)) {
+                    const needsComma = !QUERY_START_WORDS.has(followingSlot(chars, seg.end));
+                    shaped = fitWindow(seg, `${PLACEHOLDER_CHAR}${ordinalFill(ordinal)} as (select 1)${needsComma ? "," : ""}`);
+                }
+                else {
+                    shaped = undefined;
+                }
+                if (shaped !== undefined)
+                    ordinal += 1;
             }
             else {
-                shaped = undefined;
+                shaped = fragmentFill(seg, candidate, info.isCall, slot);
             }
-            if (shaped !== undefined)
-                ordinal += 1;
-        }
-        else {
-            shaped = shape !== undefined ? fragmentFill(seg, shape, info.isCall, slot) : undefined;
+            // Admitted (a fragment landed), or a shape whose fill is positional and never refused.
+            if (shaped !== undefined || candidate === "nothing" || candidate === "expr")
+                break;
         }
         if (shaped !== undefined) {
             // Fragment fill: at the fit window's start (`at` — tag start for a one-line tag, the

package/dist/mysql/parse.js

@@ -76,6 +76,7 @@ function attachErrorCounter(lexer, parser, listener) {
 export const fragmentGrammar = defineFragmentGrammar({
     newLexer: (input) => new MysqlLexer(input),
     newParser: (tokens) => new MysqlParser(tokens),
+    separator: MysqlLexer.COMMA,
     entries: {
         statement: (p) => p.root(),
         expression: (p) => p.expression(),

package/dist/postgres/parse.js

@@ -75,6 +75,7 @@ function attachErrorCounter(lexer, parser, listener) {
 export const fragmentGrammar = defineFragmentGrammar({
     newLexer: (input) => new PostgresLexer(input),
     newParser: (tokens) => new PostgresParser(tokens),
+    separator: PostgresLexer.COMMA,
     entries: {
         statement: (p) => p.root(),
         expression: (p) => p.a_expr(),

package/dist/qualify/template-provider.d.ts

@@ -48,8 +48,13 @@ export interface TemplateCandidate {
 /** Everything known about one call's expansion. Every field optional; `undefined` = unknown. */
 export interface ResolvedExpansion {
     /** Parse-time shape. When absent, derived from the strongest present field:
-     *  relation → "relation", columns → "column-list", value → "expr" (an explicit shape always wins). */
+     *  relation → "relation", columns → "column-list", value → "expr" (an explicit shape always wins).
+     *  With `shapes` present this is `shapes[0]`. */
     shape?: ExpansionShape;
+    /** Every shape the call can take, most specific first (a macro whose body is an `if` arm with
+     *  no `else` is `["conjunct", "nothing"]`). The segmenter takes the first one the slot admits;
+     *  `nothing` and `expr` are always admitted, so they belong last. Absent = `shape` alone. */
+    shapes?: ExpansionShape[];
     /** A relation-producing call (ref, source, a TVF-like macro). */
     relation?: ResolvedRelation;
     /** A scalar value — `{{ var('x') }}`, `{{ env_var('Y') }}`, a scalar macro. */
@@ -100,7 +105,7 @@ export declare class DefaultTemplateProvider implements SchemaProvider {
     /** The rendered-output shape of a call. Neutral floor: unknown (the engine derives a shape from
      *  stronger fields, or falls back to its positional fill). The dbt no-output builtins → "nothing"
      *  is `DbtTemplateProvider` knowledge. */
-    shapeOf(_call: TemplateCall): ExpansionShape | undefined;
+    shapeOf(_call: TemplateCall): ExpansionShape | readonly ExpansionShape[] | undefined;
     /** The columns a column-list-producing macro emits. Default: unknown. */
     columnsOf(_call: TemplateCall): Column[] | undefined;
     /** The items a loop collection holds. Default: unknown (loops analyze one representative pass). */
@@ -167,7 +172,7 @@ export declare class DbtTemplateProvider extends DefaultTemplateProvider {
     valueOf(call: TemplateCall): {
         type: ValueType;
     } | undefined;
-    shapeOf(call: TemplateCall): ExpansionShape | undefined;
+    shapeOf(call: TemplateCall): ExpansionShape | readonly ExpansionShape[] | undefined;
 }
 /** The provider type the engine consults — the shipped base (or any subclass of it, e.g.
  *  `DbtTemplateProvider`). */

package/dist/qualify/template-provider.js

@@ -152,7 +152,10 @@ export class DefaultTemplateProvider {
      * undefined when nothing at all is known (the engine's zero-knowledge floor).
      */
     expansion(call) {
-        const shape = this.shapeOf(call);
+        const answered = this.shapeOf(call);
+        // A list answer keeps its order; an empty list is no answer at all.
+        const shapes = Array.isArray(answered) ? (answered.length > 0 ? [...answered] : undefined) : undefined;
+        const shape = shapes ? shapes[0] : answered;
         const relation = this.relationOf(call);
         const value = this.valueOf(call);
         const columns = this.columnsOf(call);
@@ -162,6 +165,7 @@ export class DefaultTemplateProvider {
             return undefined;
         return {
             ...(derived !== undefined ? { shape: derived } : {}),
+            ...(shapes && shapes.length > 1 ? { shapes } : {}),
             ...(relation ? { relation } : {}),
             ...(value ? { value } : {}),
             ...(columns ? { columns } : {}),

package/dist/redshift/parse.js

@@ -76,6 +76,7 @@ function attachErrorCounter(lexer, parser, listener) {
 export const fragmentGrammar = defineFragmentGrammar({
     newLexer: (input) => new RedshiftLexer(input),
     newParser: (tokens) => new RedshiftParser(tokens),
+    separator: RedshiftLexer.COMMA,
     entries: {
         statement: (p) => p.root(),
         expression: (p) => p.a_expr(),

package/dist/snowflake/parse.js

@@ -76,6 +76,7 @@ function attachErrorCounter(lexer, parser, listener) {
 export const fragmentGrammar = defineFragmentGrammar({
     newLexer: (input) => new SnowflakeLexer(input),
     newParser: (tokens) => new SnowflakeParser(tokens),
+    separator: SnowflakeLexer.COMMA,
     entries: {
         statement: (p) => p.snowflake_file(),
         expression: (p) => p.expr(),

package/dist/sqlite/parse.js

@@ -76,6 +76,7 @@ function attachErrorCounter(lexer, parser, listener) {
 export const fragmentGrammar = defineFragmentGrammar({
     newLexer: (input) => new SqliteLexer(input),
     newParser: (tokens) => new SqliteParser(tokens),
+    separator: SqliteLexer.COMMA,
     entries: {
         statement: (p) => p.parse(),
         expression: (p) => p.expr(),

package/dist/template/engine.d.ts

@@ -1,8 +1,9 @@
 import type { Dialect } from "../dialect.js";
+import type { PartSpan } from "../ir/part-span.js";
 import type { ParseResultIR } from "../api.js";
 import type { SyntaxDiagnostic } from "../parse-diagnostics.js";
 import type { Token } from "../token/token.js";
-import type { TemplateProvider } from "../qualify/template-provider.js";
+import type { ExpansionShape, TemplateProvider } from "../qualify/template-provider.js";
 import type { TagNode } from "../minijinja/tag-ast.js";
 import type { TemplateRegion, TemplateSymbol } from "../minijinja/regions.js";
 import type { TemplateVariant } from "../minijinja/variants.js";
@@ -13,6 +14,39 @@ export type { TemplateVariant } from "../minijinja/variants.js";
 export interface TemplatedParseOptions {
     provider?: TemplateProvider;
 }
+/**
+ * What a `{% macro %}` definition's body can stand in for at a call site, read from the
+ * definition text alone (no project, no rendering): the body's fragment verdict mapped onto the
+ * provider's shape vocabulary, plus what its control flow adds. A host answers `shapeOf(call)`
+ * for a call by looking the macro up by name and returning `shapes` as they are.
+ */
+export interface MacroShape {
+    /** The declared macro name (`{% macro name(...) %}`). */
+    name: string;
+    nameSpan: PartSpan;
+    /** The whole block, opening tag through `{% endmacro %}`. */
+    span: PartSpan;
+    /**
+     * Every shape the body can take, most specific first; empty when nothing can be established
+     * (never-wrong). `expression` → `expr`, `cteList` → `cte-definition`, `selectList` →
+     * `column-list`, `tableSource` → `relation`, `statement` → `statement`; a body led by a hole
+     * whose jinja `default('where')` / `default('and')` is visible → `where-clause` / `conjunct`;
+     * a body whose SQL all sits under an `if` with no `else` adds `nothing` last.
+     */
+    shapes: ExpansionShape[];
+    /**
+     * Present when the body OPENS with a hole bound to one of the macro's own parameters
+     * (`{{ stat|default('where') }} {{ col }} = 0`): the clause keyword the body starts with is
+     * whatever the caller passes for that parameter (or `default` when the caller passes
+     * nothing). `shapesForCall` resolves it per call; `shapes` above carries only the default's
+     * shape (or nothing when there is no default).
+     */
+    keywordParam?: {
+        name: string;
+        index: number;
+        default?: string;
+    };
+}
 /** The unified result of parsing raw jinja-SQL: one token stream + the SQL parse + tags. */
 export interface TemplatedParseResult {
     /** ONE source-ordered stream: SQL tokens (channel 0) + jinja tokens (channel 2, role "minijinja"). */
@@ -25,6 +59,9 @@ export interface TemplatedParseResult {
     regions: TemplateRegion[];
     /** R4 go-to-def template symbols (set targets / macro names). */
     symbols: TemplateSymbol[];
+    /** Every `{% macro %}` definition in the text with the shapes its body can take (see
+     *  `MacroShape`). Empty when the text defines no macro. */
+    macros: MacroShape[];
     /** SQL diagnostics (+ jinja diagnostics from Task 4), positioned in original coordinates. */
     diagnostics: SyntaxDiagnostic[];
     /**

package/dist/trino/parse.js

@@ -73,6 +73,7 @@ function attachErrorCounter(lexer, parser, listener) {
 export const fragmentGrammar = defineFragmentGrammar({
     newLexer: (input) => new TrinoLexer(input),
     newParser: (tokens) => new TrinoParser(tokens),
+    separator: TrinoLexer.COMMA,
     entries: {
         statement: (p) => p.root(),
         expression: (p) => p.expression(),

package/dist/tsql/parse.js

@@ -80,6 +80,7 @@ function attachErrorCounter(lexer, parser, listener) {
 export const fragmentGrammar = defineFragmentGrammar({
     newLexer: (input) => new TSqlLexer(input),
     newParser: (tokens) => new TSqlParser(tokens),
+    separator: TSqlLexer.COMMA,
     entries: {
         statement: (p) => p.tsql_file(),
         expression: (p) => p.expression(),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sqllens",
-	"version": "1.8.1",
+	"version": "1.9.0",
 	"description": "A TypeScript SQL parser and static analyzer: parse, resolve names, infer types, and trace column lineage across many SQL dialects (Databricks, T-SQL, Snowflake, BigQuery, Redshift, PostgreSQL, DuckDB, Trino, SQLite, MySQL).",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",