sqllens 1.8.0 → 1.8.1

package/dist/bigquery/parse.d.ts

@@ -9,3 +9,7 @@ export type { ParseResult } from "../parse-result.js";
  * only when SLL fails — same result LL alone would give, just faster on valid input.
  */
 export declare function parseBigQuery(sql: string): ParseResult;
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export declare const fragmentGrammar: import("../fragment-grammar.js").FragmentGrammar;

package/dist/bigquery/parse.js

@@ -1,6 +1,7 @@
-import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode } from "antlr4ng";
+import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode, Token as AntlrToken, } from "antlr4ng";
 import { GoogleSQLLexer } from "../generated/bigquery/GoogleSQLLexer.js";
 import { GoogleSQLParser } from "../generated/bigquery/GoogleSQLParser.js";
+import { defineFragmentGrammar, separatedList } from "../fragment-grammar.js";
 import { dotPathTokenSource } from "./dot-path.js";
 import { postParseDiagnostics } from "./post-validate.js";
 import { makeErrorCollector } from "../parse-diagnostics.js";
@@ -67,3 +68,28 @@ export function parseBigQuery(sql) {
         return withTokens({ tree, errors: diagnostics.length, diagnostics, sllFallback: true });
     }
 }
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export const fragmentGrammar = defineFragmentGrammar({
+    // The same token pipeline as parseBigQuery: the DOT_IDENTIFIER path rewrite and the
+    // literal-escape validation ride the lex; the post-parse tree checks ride each parse.
+    lex: (text) => {
+        const lexer = new GoogleSQLLexer(CharStream.fromString(text));
+        lexer.removeErrorListeners();
+        const { source, escapeDiagnostics } = dotPathTokenSource(text, lexer);
+        const stream = new CommonTokenStream(source);
+        stream.fill();
+        return { tokens: stream.getTokens().filter((t) => t.type !== AntlrToken.EOF), diagnostics: escapeDiagnostics };
+    },
+    newLexer: (input) => new GoogleSQLLexer(input),
+    newParser: (tokens) => new GoogleSQLParser(tokens),
+    postParse: postParseDiagnostics,
+    entries: {
+        statement: (p) => p.root(),
+        expression: (p) => p.expression(),
+        tableSource: (p) => p.from_clause_contents(),
+        cteList: separatedList((p) => p.with_clause_entry(), GoogleSQLLexer.COMMA_SYMBOL),
+        selectList: (p) => p.select_list(),
+    },
+});

package/dist/databricks/parse.d.ts

@@ -9,3 +9,7 @@ export type { ParseResult } from "../parse-result.js";
  * result LL alone would produce, so correctness is unchanged — just faster.
  */
 export declare function parseDatabricks(sql: string): ParseResult;
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`multiStatement`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export declare const fragmentGrammar: import("../fragment-grammar.js").FragmentGrammar;

package/dist/databricks/parse.js

@@ -1,6 +1,7 @@
 import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode, } from "antlr4ng";
 import { DatabricksLexer } from "../generated/databricks/DatabricksLexer.js";
 import { DatabricksParser } from "../generated/databricks/DatabricksParser.js";
+import { defineFragmentGrammar, separatedList } from "../fragment-grammar.js";
 import { makeErrorCollector } from "../parse-diagnostics.js";
 import { CONSUMED_AS_RULES, deriveConsumedAs } from "../token/consumed-as.js";
 import { mapTokens } from "../token/map.js";
@@ -72,3 +73,17 @@ function attachErrorCounter(lexer, parser, listener) {
     parser.removeErrorListeners();
     parser.addErrorListener(listener);
 }
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`multiStatement`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export const fragmentGrammar = defineFragmentGrammar({
+    newLexer: (input) => new DatabricksLexer(input),
+    newParser: (tokens) => new DatabricksParser(tokens),
+    entries: {
+        statement: (p) => p.multiStatement(),
+        expression: (p) => p.expression(),
+        tableSource: (p) => p.relation(),
+        cteList: separatedList((p) => p.namedQuery(), DatabricksLexer.COMMA),
+        selectList: (p) => p.namedExpressionSeq(),
+    },
+});

package/dist/duckdb/parse.d.ts

@@ -8,3 +8,7 @@ export type { ParseResult } from "../parse-result.js";
  * only when SLL fails — same result LL alone would give, just faster on valid input.
  */
 export declare function parseDuckdb(sql: string): ParseResult;
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export declare const fragmentGrammar: import("../fragment-grammar.js").FragmentGrammar;

package/dist/duckdb/parse.js

@@ -1,6 +1,7 @@
 import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode, } from "antlr4ng";
 import { DuckdbLexer } from "../generated/duckdb/DuckdbLexer.js";
 import { DuckdbParser } from "../generated/duckdb/DuckdbParser.js";
+import { defineFragmentGrammar } from "../fragment-grammar.js";
 import { makeErrorCollector } from "../parse-diagnostics.js";
 import { CONSUMED_AS_RULES, deriveConsumedAs } from "../token/consumed-as.js";
 import { mapTokens } from "../token/map.js";
@@ -63,3 +64,17 @@ function attachErrorCounter(lexer, parser, listener) {
     parser.removeErrorListeners();
     parser.addErrorListener(listener);
 }
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export const fragmentGrammar = defineFragmentGrammar({
+    newLexer: (input) => new DuckdbLexer(input),
+    newParser: (tokens) => new DuckdbParser(tokens),
+    entries: {
+        statement: (p) => p.root(),
+        expression: (p) => p.a_expr(),
+        tableSource: (p) => p.table_ref(),
+        cteList: (p) => p.cte_list(),
+        selectList: (p) => p.target_list(),
+    },
+});

package/dist/fragment-grammar.d.ts

@@ -0,0 +1,48 @@
+import { CharStream, CommonTokenStream, type Lexer, type Parser, type ParserRuleContext, Token as AntlrToken } from "antlr4ng";
+import { type SyntaxDiagnostic } from "./parse-diagnostics.js";
+/** What a fragment parses as. `statement` is the dialect's ordinary full-file entry. */
+export type FragmentKind = "statement" | "expression" | "tableSource" | "cteList" | "selectList";
+/** Every kind, in the order a macro body is tried: the most common reading first. */
+export declare const FRAGMENT_KINDS: readonly FragmentKind[];
+export interface FragmentLex {
+    /** Text-native tokens, trivia included, EOF excluded. */
+    tokens: AntlrToken[];
+    /** Token-derived diagnostics the dialect's statement entry would also report (bigquery's
+     *  literal-escape validation); positioned in the text's coordinates. */
+    diagnostics: SyntaxDiagnostic[];
+}
+export interface FragmentParse {
+    tree: ParserRuleContext;
+    /** Empty when the slice parsed clean as this kind (the rule is EOF-anchored). */
+    diagnostics: SyntaxDiagnostic[];
+}
+export interface FragmentGrammar {
+    /** Lex a whole text exactly as the dialect's statement entry does (same token rewrites). */
+    lex(text: string): FragmentLex;
+    /**
+     * Parse an already-lexed slice as `kind`. `bail` = SLL + bail strategy: returns undefined on
+     * the first syntax error (fast clean/not-clean probe); otherwise full LL with recovery and
+     * positioned diagnostics.
+     */
+    parse(slice: readonly AntlrToken[], kind: FragmentKind, bail: boolean): FragmentParse | undefined;
+}
+/** A fragment entry: drives one or more of the grammar's OWN rules over the parser. The grammar
+ *  is untouched (no `x EOF` wrapper rules: an extra caller widens a rule's SLL follow set and
+ *  flips prediction on unrelated input); the EOF anchor is checked by the driver instead. */
+export type FragmentEntry<P extends Parser> = (parser: P) => ParserRuleContext;
+export interface FragmentGrammarSpec<P extends Parser> {
+    /** Lex a whole text; defaults to the plain lexer with no diagnostics. */
+    lex?: (text: string) => FragmentLex;
+    newLexer: (input: CharStream) => Lexer;
+    newParser: (tokens: CommonTokenStream) => P;
+    entries: {
+        readonly [K in FragmentKind]: FragmentEntry<P>;
+    };
+    /** Tree-walking checks the dialect's statement entry runs after the parse (bigquery). */
+    postParse?: (tree: ParserRuleContext) => SyntaxDiagnostic[];
+}
+/** `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 declare function separatedList<P extends Parser>(item: FragmentEntry<P>, separator: number): FragmentEntry<P>;
+/** Bind a dialect's lexer, parser and fragment entry rules into a `FragmentGrammar`. */
+export declare function defineFragmentGrammar<P extends Parser>(spec: FragmentGrammarSpec<P>): FragmentGrammar;

package/dist/fragment-grammar.js

@@ -0,0 +1,93 @@
+// ---------------------------------------------------------------------------
+// Fragment grammar: the per-dialect entry set for parsing an SQL FRAGMENT — a
+// templated macro body that is not a statement (an expression, a FROM-slot
+// source, a CTE list pasted after WITH, a select list). Each dialect's parse.ts
+// binds its lexer, parser and the five EOF-anchored `*_fragment` rules through
+// `defineFragmentGrammar`; src/fragment.ts holds the registry and the driver.
+//
+// The parse runs over an already-lexed token slice (antlr4ng's ListTokenSource),
+// never over a re-lexed substring, so every token, span and diagnostic stays in
+// the coordinates of the text the tokens were lexed from.
+// ---------------------------------------------------------------------------
+import { BailErrorStrategy, CharStream, CommonTokenStream, ListTokenSource, PredictionMode, Token as AntlrToken, } from "antlr4ng";
+import { makeErrorCollector } from "./parse-diagnostics.js";
+/** Every kind, in the order a macro body is tried: the most common reading first. */
+export const FRAGMENT_KINDS = [
+    "statement",
+    "expression",
+    "tableSource",
+    "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) {
+            parser.inputStream.consume(); // between rules there is no context to attach the separator to
+            item(parser);
+        }
+        return first;
+    };
+}
+/** The EOF anchor: the entry returned but input remains — the same diagnostic shape ANTLR
+ *  emits for an EOF-anchored rule, positioned at the leftover token. */
+function trailingInput(parser) {
+    const tok = parser.inputStream.LT(1);
+    if (!tok || tok.type === AntlrToken.EOF)
+        return undefined;
+    const text = tok.text ?? "";
+    return {
+        message: `extraneous input '${text}' expecting <EOF>`,
+        line: tok.line,
+        column: tok.column,
+        offset: tok.start,
+        length: text.length || 1,
+    };
+}
+/** Bind a dialect's lexer, parser and fragment entry rules into a `FragmentGrammar`. */
+export function defineFragmentGrammar(spec) {
+    const { newLexer, newParser, entries, postParse } = spec;
+    const lex = spec.lex ??
+        ((text) => {
+            const lexer = newLexer(CharStream.fromString(text));
+            lexer.removeErrorListeners();
+            return { tokens: lexer.getAllTokens(), diagnostics: [] };
+        });
+    return {
+        lex,
+        parse(slice, kind, bail) {
+            const tokens = new CommonTokenStream(new ListTokenSource([...slice]));
+            const parser = newParser(tokens);
+            const collector = makeErrorCollector();
+            parser.removeErrorListeners();
+            parser.addErrorListener(collector.listener);
+            const sim = parser.interpreter;
+            if (bail) {
+                parser.errorHandler = new BailErrorStrategy();
+                sim.predictionMode = PredictionMode.SLL;
+                let tree;
+                try {
+                    tree = entries[kind](parser);
+                }
+                catch {
+                    return undefined;
+                }
+                // A grammar action can report through the listener without throwing (bigquery's
+                // join-balance check); that is not a clean parse either. Nor is leftover input.
+                if (collector.diagnostics.length > 0 || trailingInput(parser))
+                    return undefined;
+                const post = postParse?.(tree) ?? [];
+                return post.length === 0 ? { tree, diagnostics: [] } : undefined;
+            }
+            sim.predictionMode = PredictionMode.LL;
+            const tree = entries[kind](parser);
+            const trailing = trailingInput(parser);
+            return {
+                tree,
+                diagnostics: [...collector.diagnostics, ...(trailing ? [trailing] : []), ...(postParse?.(tree) ?? [])],
+            };
+        },
+    };
+}

package/dist/fragment.d.ts

@@ -0,0 +1,29 @@
+import type { ParserRuleContext } from "antlr4ng";
+import type { Dialect } from "./dialect.js";
+import { type FragmentKind } from "./fragment-grammar.js";
+import type { SyntaxDiagnostic } from "./parse-diagnostics.js";
+export type { FragmentKind } from "./fragment-grammar.js";
+/** A half-open [start, end) offset range of the lexed text (a `PartSpan` fits). */
+export interface FragmentRange {
+    start: number;
+    end: number;
+}
+export interface FragmentResult {
+    /** The kind the ranges parsed as; when `clean` is false, the kind that got furthest. */
+    kind: FragmentKind;
+    /** True when the ranges parsed with zero syntax errors as `kind`. */
+    clean: boolean;
+    tree: ParserRuleContext;
+    /** Positioned in the text's coordinates. Empty when clean. */
+    diagnostics: SyntaxDiagnostic[];
+}
+export interface FragmentSession {
+    /**
+     * Parse the tokens inside `ranges` (a token counts when it starts inside one) as a fragment.
+     * Returns undefined when the ranges hold no default-channel token (nothing to parse; no
+     * verdict). Never throws: every attempt runs a recovering parser over a fixed kind list.
+     */
+    parse(ranges: readonly FragmentRange[], kinds?: readonly FragmentKind[]): FragmentResult | 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

@@ -0,0 +1,76 @@
+// ---------------------------------------------------------------------------
+// Fragment parsing: parse RANGES of a text as an SQL fragment, trying each
+// FragmentKind in order until one parses clean. The consumer is the minijinja
+// front end (a `{% macro %}` body is whatever gets pasted at the call site: a
+// statement, an expression, a FROM-slot source, a CTE list, a select list); the
+// statement entry is right for a model file and wrong for most macro bodies.
+//
+// The text is lexed ONCE (`openFragments`) and every parse cuts its token slice
+// from that lex, so the tokens (and every diagnostic they position) stay in the
+// text's own coordinates: no remap. A fast SLL+bail probe per kind finds the
+// clean reading; when none is clean the kinds are re-run with recovery and the
+// reading that got furthest before its first error supplies the diagnostics —
+// a heuristic for the broken-input case only (the reading closest to what was
+// meant), never a claim: `clean` is false and the region carries no verdict.
+// ---------------------------------------------------------------------------
+import { FRAGMENT_KINDS } from "./fragment-grammar.js";
+import { fragmentGrammar as bigquery } from "./bigquery/parse.js";
+import { fragmentGrammar as databricks } from "./databricks/parse.js";
+import { fragmentGrammar as duckdb } from "./duckdb/parse.js";
+import { fragmentGrammar as mysql } from "./mysql/parse.js";
+import { fragmentGrammar as postgres } from "./postgres/parse.js";
+import { fragmentGrammar as redshift } from "./redshift/parse.js";
+import { fragmentGrammar as snowflake } from "./snowflake/parse.js";
+import { fragmentGrammar as sqlite } from "./sqlite/parse.js";
+import { fragmentGrammar as trino } from "./trino/parse.js";
+import { fragmentGrammar as tsql } from "./tsql/parse.js";
+const FRAGMENT_GRAMMARS = {
+    databricks,
+    tsql,
+    snowflake,
+    bigquery,
+    redshift,
+    postgres,
+    duckdb,
+    trino,
+    sqlite,
+    mysql,
+};
+/** Lex `text` once with `dialect`'s statement-entry token pipeline; parse ranges of it after. */
+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);
+    return {
+        parse(ranges, kinds = FRAGMENT_KINDS) {
+            const slice = lexed.tokens.filter((t) => inRanges(t.start, ranges));
+            if (!slice.some((t) => t.channel === 0))
+                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));
+            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: [] };
+                }
+            }
+            let best;
+            let bestAt = -1;
+            for (const kind of kinds) {
+                const attempt = grammar.parse(slice, kind, false);
+                if (!attempt)
+                    continue;
+                const diagnostics = [...lexDiags, ...attempt.diagnostics];
+                if (diagnostics.length === 0)
+                    return { kind, clean: true, tree: attempt.tree, diagnostics };
+                const at = attempt.diagnostics[0]?.offset ?? Number.MAX_SAFE_INTEGER;
+                if (at > bestAt) {
+                    bestAt = at;
+                    best = { kind, clean: false, tree: attempt.tree, diagnostics };
+                }
+            }
+            return best;
+        },
+    };
+}

package/dist/minijinja/parse.js

@@ -47,6 +47,7 @@ import { CharStream, CommonTokenStream, ListTokenSource, Token as AntlrToken } f
 import { parse } from "../api.js";
 import { debugRethrow } from "../debug.js";
 import { MinijinjaLexer } from "../generated/minijinja/MinijinjaLexer.js";
+import { openFragments } from "../fragment.js";
 import { endPosition } from "../ir/span.js";
 import { MinijinjaParser } from "../generated/minijinja/MinijinjaParser.js";
 import { makeErrorCollector } from "../parse-diagnostics.js";
@@ -241,6 +242,66 @@ function scrubPlaceholderDiagnostics(diags, tagRanges, text, placeholder) {
     });
     return { diagnostics, bySegment };
 }
+/**
+ * Re-read every `{% macro %}` body as an SQL fragment. The whole-file statement parse's
+ * 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.
+ */
+function reparseMacroBodies(regions, diagnostics, placeholder, dialect) {
+    const macros = [];
+    // Macros can sit under an if/for (a guarded definition); a macro inside a macro body is
+    // covered by the outer body's read and not visited on its own.
+    const visit = (list) => {
+        for (const region of list) {
+            if (region.kind === "macro")
+                macros.push(region);
+            else
+                for (const arm of region.arms)
+                    visit(arm.children);
+        }
+    };
+    visit(regions);
+    if (macros.length === 0)
+        return diagnostics;
+    const fragments = openFragments(placeholder, dialect);
+    const bodies = [];
+    const own = [];
+    for (const region of macros) {
+        const arm = region.arms[0];
+        if (!arm)
+            continue;
+        // An unclosed macro (mid-edit, no endmacro yet) closes at its own opening tag with an empty
+        // body; its SQL runs to the end of the text, so that is what gets read.
+        const unclosed = arm.bodySpan.end <= arm.bodySpan.start && region.span.end === arm.tagSpan.end;
+        const body = unclosed ? { start: arm.tagSpan.end, end: placeholder.length } : arm.bodySpan;
+        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;
+    }
+    // The remainder: everything between the bodies, as the statement batch it always was.
+    const remainder = [];
+    let at = 0;
+    for (const body of [...bodies].sort((a, b) => a.start - b.start)) {
+        if (body.start > at)
+            remainder.push({ start: at, end: body.start });
+        at = Math.max(at, body.end);
+    }
+    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];
+}
 /** The core build — total by construction (every composed piece is total). */
 function build(text, dialect, provider) {
     const { segments, placeholder, tagTokens } = segment(text, provider);
@@ -313,7 +374,18 @@ function build(text, dialect, provider) {
     // surface a consumer naturally reads — and the raw fill-quoting messages are
     // engine-internal, never public (the gold__vendor F5 leak, 2026-07-06: the raw
     // "mismatched input 'jjjj…'" reached a user's screen through sql.diagnostics).
-    const { diagnostics: scrubbed, bySegment } = scrubPlaceholderDiagnostics(sqlResult.diagnostics, tagRanges, text, placeholder);
+    // Step 6 (R4): pair the control tags into regions + extract set/macro symbols.
+    // Both are total; they ride inside build()'s caller try/catch for totality.
+    const regions = templateRegions(tags, text);
+    const symbols = templateSymbols(tags);
+    // Macro bodies (issue #48): a `{% macro %}` body is whatever gets pasted at the call site,
+    // so the whole-file statement parse is the wrong reading for most of them. Each top-level
+    // macro body is re-read from the placeholder as a fragment (statement, expression, FROM-slot
+    // source, CTE list, select list; src/fragment.ts) and its own diagnostics replace whatever
+    // 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 { 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
     // SQL diagnostics the scrubber widened onto it.
@@ -329,10 +401,6 @@ function build(text, dialect, provider) {
     }
     const finalSql = { ...sqlResult, diagnostics: scrubbed };
     const diagnostics = [...scrubbed, ...jinjaDiagnostics].sort((a, b) => (a.offset ?? 0) - (b.offset ?? 0));
-    // Step 6 (R4): pair the control tags into regions + extract set/macro symbols.
-    // Both are total; they ride inside build()'s caller try/catch for totality.
-    const regions = templateRegions(tags, text);
-    const symbols = templateSymbols(tags);
     return {
         tokens,
         sql: finalSql,

package/dist/minijinja/regions.d.ts

@@ -1,3 +1,4 @@
+import type { FragmentKind } from "../fragment-grammar.js";
 import type { PartSpan } from "../ir/part-span.js";
 import type { TagNode } from "./tag-ast.js";
 /** One arm of a control region — an `if`/`elif`/`else` branch, or the single body of a `for`/`macro`. */
@@ -18,6 +19,12 @@ export interface TemplateRegion {
     arms: TemplateArm[];
     /** Opening tag start → closing tag end (or the last known tag end when unbalanced). */
     span: PartSpan;
+    /**
+     * `macro` regions only: what the body parsed clean as — a statement, an expression, a
+     * FROM-slot source, a CTE list (pasted after WITH), or a select list. Absent when the body
+     * holds no SQL or parsed clean as none of them (the diagnostics then say where it broke).
+     */
+    body?: FragmentKind;
 }
 /** A go-to-def template symbol — a `{% set %}` target or a `{% macro %}` name. */
 export interface TemplateSymbol {

package/dist/mysql/parse.d.ts

@@ -8,3 +8,7 @@ export type { ParseResult } from "../parse-result.js";
  * only when SLL fails — same result LL alone would give, just faster on valid input.
  */
 export declare function parseMysql(sql: string): ParseResult;
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export declare const fragmentGrammar: import("../fragment-grammar.js").FragmentGrammar;

package/dist/mysql/parse.js

@@ -1,6 +1,7 @@
 import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode, } from "antlr4ng";
 import { MysqlLexer } from "../generated/mysql/MysqlLexer.js";
 import { MysqlParser } from "../generated/mysql/MysqlParser.js";
+import { defineFragmentGrammar } from "../fragment-grammar.js";
 import { makeErrorCollector } from "../parse-diagnostics.js";
 import { CONSUMED_AS_RULES, deriveConsumedAs } from "../token/consumed-as.js";
 import { mapTokens } from "../token/map.js";
@@ -69,3 +70,17 @@ function attachErrorCounter(lexer, parser, listener) {
     parser.removeErrorListeners();
     parser.addErrorListener(listener);
 }
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export const fragmentGrammar = defineFragmentGrammar({
+    newLexer: (input) => new MysqlLexer(input),
+    newParser: (tokens) => new MysqlParser(tokens),
+    entries: {
+        statement: (p) => p.root(),
+        expression: (p) => p.expression(),
+        tableSource: (p) => p.tableSource(),
+        cteList: (p) => p.commonTableExpressions(),
+        selectList: (p) => p.selectElements(),
+    },
+});

package/dist/postgres/parse.d.ts

@@ -8,3 +8,7 @@ export type { ParseResult } from "../parse-result.js";
  * only when SLL fails — same result LL alone would give, just faster on valid input.
  */
 export declare function parsePostgres(sql: string): ParseResult;
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export declare const fragmentGrammar: import("../fragment-grammar.js").FragmentGrammar;

package/dist/postgres/parse.js

@@ -1,6 +1,7 @@
 import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode, } from "antlr4ng";
 import { PostgresLexer } from "../generated/postgres/PostgresLexer.js";
 import { PostgresParser } from "../generated/postgres/PostgresParser.js";
+import { defineFragmentGrammar } from "../fragment-grammar.js";
 import { makeErrorCollector } from "../parse-diagnostics.js";
 import { CONSUMED_AS_RULES, deriveConsumedAs } from "../token/consumed-as.js";
 import { mapTokens } from "../token/map.js";
@@ -68,3 +69,17 @@ function attachErrorCounter(lexer, parser, listener) {
     parser.removeErrorListeners();
     parser.addErrorListener(listener);
 }
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export const fragmentGrammar = defineFragmentGrammar({
+    newLexer: (input) => new PostgresLexer(input),
+    newParser: (tokens) => new PostgresParser(tokens),
+    entries: {
+        statement: (p) => p.root(),
+        expression: (p) => p.a_expr(),
+        tableSource: (p) => p.table_ref(),
+        cteList: (p) => p.cte_list(),
+        selectList: (p) => p.target_list(),
+    },
+});

package/dist/redshift/parse.d.ts

@@ -8,3 +8,7 @@ export type { ParseResult } from "../parse-result.js";
  * only when SLL fails — same result LL alone would give, just faster on valid input.
  */
 export declare function parseRedshift(sql: string): ParseResult;
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export declare const fragmentGrammar: import("../fragment-grammar.js").FragmentGrammar;

package/dist/redshift/parse.js

@@ -1,6 +1,7 @@
 import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode, } from "antlr4ng";
 import { RedshiftLexer } from "../generated/redshift/RedshiftLexer.js";
 import { RedshiftParser } from "../generated/redshift/RedshiftParser.js";
+import { defineFragmentGrammar } from "../fragment-grammar.js";
 import { makeErrorCollector } from "../parse-diagnostics.js";
 import { CONSUMED_AS_RULES, deriveConsumedAs } from "../token/consumed-as.js";
 import { mapTokens } from "../token/map.js";
@@ -69,3 +70,17 @@ function attachErrorCounter(lexer, parser, listener) {
     parser.removeErrorListeners();
     parser.addErrorListener(listener);
 }
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export const fragmentGrammar = defineFragmentGrammar({
+    newLexer: (input) => new RedshiftLexer(input),
+    newParser: (tokens) => new RedshiftParser(tokens),
+    entries: {
+        statement: (p) => p.root(),
+        expression: (p) => p.a_expr(),
+        tableSource: (p) => p.table_ref(),
+        cteList: (p) => p.cte_list(),
+        selectList: (p) => p.target_list(),
+    },
+});

package/dist/snowflake/parse.d.ts

@@ -8,3 +8,7 @@ export type { ParseResult } from "../parse-result.js";
  * only when SLL fails — same result LL alone would give, just faster on valid input.
  */
 export declare function parseSnowflake(sql: string): ParseResult;
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`snowflake_file`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export declare const fragmentGrammar: import("../fragment-grammar.js").FragmentGrammar;

package/dist/snowflake/parse.js

@@ -1,6 +1,7 @@
 import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode, } from "antlr4ng";
 import { SnowflakeLexer } from "../generated/snowflake/SnowflakeLexer.js";
 import { SnowflakeParser } from "../generated/snowflake/SnowflakeParser.js";
+import { defineFragmentGrammar, separatedList } from "../fragment-grammar.js";
 import { makeErrorCollector } from "../parse-diagnostics.js";
 import { CONSUMED_AS_RULES, deriveConsumedAs } from "../token/consumed-as.js";
 import { mapTokens } from "../token/map.js";
@@ -69,3 +70,17 @@ function attachErrorCounter(lexer, parser, listener) {
     parser.removeErrorListeners();
     parser.addErrorListener(listener);
 }
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`snowflake_file`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export const fragmentGrammar = defineFragmentGrammar({
+    newLexer: (input) => new SnowflakeLexer(input),
+    newParser: (tokens) => new SnowflakeParser(tokens),
+    entries: {
+        statement: (p) => p.snowflake_file(),
+        expression: (p) => p.expr(),
+        tableSource: (p) => p.table_source(),
+        cteList: separatedList((p) => p.common_table_expression(), SnowflakeLexer.COMMA),
+        selectList: (p) => p.select_list(),
+    },
+});

package/dist/sqlite/parse.d.ts

@@ -8,3 +8,7 @@ export type { ParseResult } from "../parse-result.js";
  * only when SLL fails — same result LL alone would give, just faster on valid input.
  */
 export declare function parseSqlite(sql: string): ParseResult;
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`parse`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export declare const fragmentGrammar: import("../fragment-grammar.js").FragmentGrammar;

package/dist/sqlite/parse.js

@@ -1,6 +1,7 @@
 import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode, } from "antlr4ng";
 import { SqliteLexer } from "../generated/sqlite/SqliteLexer.js";
 import { SqliteParser } from "../generated/sqlite/SqliteParser.js";
+import { defineFragmentGrammar, separatedList } from "../fragment-grammar.js";
 import { makeErrorCollector } from "../parse-diagnostics.js";
 import { CONSUMED_AS_RULES, deriveConsumedAs } from "../token/consumed-as.js";
 import { mapTokens } from "../token/map.js";
@@ -69,3 +70,17 @@ function attachErrorCounter(lexer, parser, listener) {
     parser.removeErrorListeners();
     parser.addErrorListener(listener);
 }
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`parse`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export const fragmentGrammar = defineFragmentGrammar({
+    newLexer: (input) => new SqliteLexer(input),
+    newParser: (tokens) => new SqliteParser(tokens),
+    entries: {
+        statement: (p) => p.parse(),
+        expression: (p) => p.expr(),
+        tableSource: (p) => p.join_clause(),
+        cteList: separatedList((p) => p.common_table_expression(), SqliteLexer.COMMA),
+        selectList: separatedList((p) => p.result_column(), SqliteLexer.COMMA),
+    },
+});

package/dist/symbols/symbols.js

@@ -383,6 +383,11 @@ function emitColumns(scope, frame, out, schema, sourceSyms, expandStarOf) {
     // recovered from an unmodelled `other` node) honestly gets no node.
     const columnNodes = columnExprsByCst(body);
     for (const ref of body.columns) {
+        // A template hole in a scalar slot (`select {{ my_macro() }}`) is not a column reference:
+        // its `parts` is the placeholder fill, and a symbol named after it (bound to whatever source
+        // the single-source rule picks) is a wrong claim. Consumers reach the tag through `tags`.
+        if (ref.template)
+            continue;
         const res = resolveColumnRef(scope, ref, schema);
         const modifiers = ["reference"];
         // A reference that binds to a source outside this scope is correlated.

package/dist/trino/parse.d.ts

@@ -8,3 +8,7 @@ export type { ParseResult } from "../parse-result.js";
  * only when SLL fails — same result LL alone would give, just faster on valid input.
  */
 export declare function parseTrino(sql: string): ParseResult;
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export declare const fragmentGrammar: import("../fragment-grammar.js").FragmentGrammar;

package/dist/trino/parse.js

@@ -1,6 +1,7 @@
 import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode, } from "antlr4ng";
 import { TrinoLexer } from "../generated/trino/TrinoLexer.js";
 import { TrinoParser } from "../generated/trino/TrinoParser.js";
+import { defineFragmentGrammar, separatedList } from "../fragment-grammar.js";
 import { makeErrorCollector } from "../parse-diagnostics.js";
 import { CONSUMED_AS_RULES, deriveConsumedAs } from "../token/consumed-as.js";
 import { mapTokens } from "../token/map.js";
@@ -66,3 +67,17 @@ function attachErrorCounter(lexer, parser, listener) {
     parser.removeErrorListeners();
     parser.addErrorListener(listener);
 }
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`root`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export const fragmentGrammar = defineFragmentGrammar({
+    newLexer: (input) => new TrinoLexer(input),
+    newParser: (tokens) => new TrinoParser(tokens),
+    entries: {
+        statement: (p) => p.root(),
+        expression: (p) => p.expression(),
+        tableSource: (p) => p.relation(),
+        cteList: separatedList((p) => p.namedQuery(), TrinoLexer.COMMA),
+        selectList: separatedList((p) => p.selectItem(), TrinoLexer.COMMA),
+    },
+});

package/dist/tsql/parse.d.ts

@@ -10,3 +10,7 @@ export type { ParseResult } from "../parse-result.js";
  * on the first conflict), fall back to full LL only when SLL fails — same result LL alone would give.
  */
 export declare function parseTSql(sql: string): ParseResult;
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`tsql_file`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export declare const fragmentGrammar: import("../fragment-grammar.js").FragmentGrammar;

package/dist/tsql/parse.js

@@ -1,6 +1,7 @@
 import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode, } from "antlr4ng";
 import { TSqlLexer } from "../generated/tsql/TSqlLexer.js";
 import { TSqlParser } from "../generated/tsql/TSqlParser.js";
+import { defineFragmentGrammar, separatedList } from "../fragment-grammar.js";
 import { makeErrorCollector } from "../parse-diagnostics.js";
 import { CONSUMED_AS_RULES, deriveConsumedAs } from "../token/consumed-as.js";
 import { mapTokens } from "../token/map.js";
@@ -73,3 +74,17 @@ function attachErrorCounter(lexer, parser, listener) {
     parser.removeErrorListeners();
     parser.addErrorListener(listener);
 }
+/** The fragment entries (src/fragment.ts): the grammar's own rules for a statement batch
+ *  (`tsql_file`), an expression, a FROM-slot source, a CTE list (no WITH) and a select list;
+ *  the driver anchors each at EOF. For templated macro bodies. */
+export const fragmentGrammar = defineFragmentGrammar({
+    newLexer: (input) => new TSqlLexer(input),
+    newParser: (tokens) => new TSqlParser(tokens),
+    entries: {
+        statement: (p) => p.tsql_file(),
+        expression: (p) => p.expression(),
+        tableSource: (p) => p.table_source(),
+        cteList: separatedList((p) => p.common_table_expression(), TSqlLexer.COMMA),
+        selectList: (p) => p.select_list(),
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sqllens",
-	"version": "1.8.0",
+	"version": "1.8.1",
 	"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",