sqllens 1.9.1 → 1.10.1

package/dist/document/document.d.ts

@@ -158,15 +158,29 @@ export declare class SqlDocument {
      *  NOT replace the cache entry: the first occurrence keeps its stable cross-edit identity (the
      *  common case), and only intra-doc duplicates — rare — pay a re-parse per build. */
     private buildCell;
-    /** Build the ONE cell for a TEMPLATED document: span [0, text.length) — the templated build path
-     *  bypasses `splitStatements` entirely (one cell, whole text), and its products come from a single
-     *  `engine.parse(text, dialect, { provider })` call rather than the plain per-dialect `parse()`.
-     *  `r.tokens`/`r.diagnostics` are ALREADY document coordinates (the cell always starts at 0), so —
-     *  unlike `buildCell` — nothing is shifted. Mirrors `buildCell`'s CachedCell/StatementCell shapes
-     *  so every downstream consumer (analyze(), cellAt(), nodeAt()…) sees the same structure whether
-     *  the document is plain or templated. Cached in the SAME cross-edit `_cellCache` as plain cells,
-     *  under a prefixed key so a templated cell can never collide with a plain one for the same text. */
+    /** Build the WHOLE-TEXT cell of a TEMPLATED document: span [0, text.length), its products from a
+     *  single `engine.parse(text, dialect, { provider })` call rather than the plain per-dialect
+     *  `parse()`. It is the document's one cell when the placeholder splits into one statement (every
+     *  single-statement model), and the carrier of the engine result (`templated`) that a multi-cell
+     *  document's slices are built from. `r.tokens`/`r.diagnostics` are ALREADY document coordinates
+     *  (the cell always starts at 0), so, unlike `buildCell`, nothing is shifted. Mirrors
+     *  `buildCell`'s CachedCell/StatementCell shapes so every downstream consumer (analyze(), cellAt(),
+     *  nodeAt()…) sees the same structure whether the document is plain or templated. Cached in the SAME
+     *  cross-edit `_cellCache` as plain cells, under a prefixed key so a templated cell can never
+     *  collide with a plain one for the same text. */
     private buildTemplatedCell;
+    /** Build one statement cell of a MULTI-cell templated document for `span` (a `splitStatements`
+     *  span over the engine's placeholder). The cell is the plain parse of its placeholder slice,
+     *  cell-relative like a plain cell, with the whole-document tags correlated onto it by
+     *  `engine.parseCell` (provider-resolved source names + `template` markers, so the fill never
+     *  reaches scope/qualify). Cached across edits like a plain cell: the key is the placeholder
+     *  slice (what parsed) plus the raw slice (which tags sit inside it), the engine + provider
+     *  version (what the tags resolve to) and `setsKey` (the `{% set %}`/`{% macro %}`/`{% for %}`
+     *  tags anywhere in the text that steer a bare `{{ t }}` binding). The document-level products
+     *  are projected onto the cell by span rather than re-derived: `tokens` is the unified SQL+jinja
+     *  stream sliced, `diagnostics` the scrubbed set filtered (the last cell absorbs end-of-text),
+     *  `errors` that count. `handedOut` dedupes intra-document duplicates exactly as `buildCell` does. */
+    private buildTemplatedSlice;
     /** Build a document for `text` in `dialect`. Total: never throws, even on broken / mid-edit input.
      *  Starts a FRESH cell cache — cross-edit reuse comes from withText(), not create(). Pass
      *  `templating` to parse through an injected TemplateEngine (jinja-SQL etc.) instead of the plain
@@ -295,8 +309,7 @@ export declare class SqlDocument {
      *  subset, see `scopeOutputColumns`'s pipe doc comment. Falls through to this document's own
      *  (single-arm) answer when there are no variants; there is no pre-existing single-doc
      *  equivalent to delegate to, unlike unionSymbols/unionDiagnostics, so the no-variant case is
-     *  just the one-arm instance of the same algorithm. A MULTI-STATEMENT document (no variants: the
-     *  templated door always forces exactly one cell, so the two "multi" shapes never overlap) merges
+     *  just the one-arm instance of the same algorithm. A MULTI-STATEMENT document (or arm) merges
      *  every statement CELL's own CTEs instead, each shifted from cell-relative to DOCUMENT coordinates
      *  (the same shift `analyze()` already applies to symbols/diagnostics for a multi-cell document);
      *  the compound facade itself carries no CTEs, so cells are the real per-statement source. Memoized
@@ -315,13 +328,16 @@ export declare class SqlDocument {
         span: Span;
     }[];
     private buildUnionOutputColumns;
-    /** One "arm" `unionCtes`/`unionOutputColumns` aggregate over, unified across the two shapes that
-     *  can each independently make a document "multi" (never both at once: the templated door always
-     *  builds exactly one statement cell, see its own comment above): a templated document's real
-     *  variants (each a full arm SqlDocument, already in DOCUMENT coordinates, zero shift), or, for a
-     *  plain multi-statement document, each statement CELL (cell-relative scopes, shifted to document
-     *  coordinates by the cell's start, mirroring `buildAnalysis`'s per-cell shift). A single-cell,
-     *  non-templated document is the trivial one-arm case of the same shape (zero shift, this
-     *  document's own scopes/qualification). */
+    /** The "arms" `unionCtes`/`unionOutputColumns` aggregate over, unified across the two shapes that
+     *  make a document "multi", VARIANTS FIRST (ruled 2026-09-13): a templated document's real
+     *  variants are the unit, each arm SqlDocument (already in DOCUMENT coordinates, since a
+     *  realization is length-preserving) contributing its own statement cells through `ownArms`; a
+     *  document without variants contributes its own cells the same way. A region can span a cell
+     *  boundary, so cells-first (arms inside each cell) is not an option. */
     private armsData;
+    /** This document's own arms, variants ignored: each statement CELL of a multi-cell document
+     *  (cell-relative scopes, shifted to document coordinates by the cell's start, mirroring
+     *  `buildAnalysis`'s per-cell shift), or the single-cell document itself (zero shift, its own
+     *  scopes/qualification). */
+    private ownArms;
 }

package/dist/document/document.js

@@ -155,12 +155,35 @@ export class SqlDocument {
         this._provider = opts.provider;
         let cells;
         let backing;
+        let templated;
         if (opts.templating) {
-            // The templated door: ONE cell spanning the whole text, bypassing splitStatements —
-            // its products come from the engine, not the plain per-dialect parse (see buildTemplatedCell).
-            const built = this.buildTemplatedCell(text, opts.templating, opts.provider);
-            cells = [built.cell];
-            backing = [built.cached];
+            // The templated door: the engine runs ONCE over the whole text (buildTemplatedCell), then the
+            // placeholder it saw is split into statement cells exactly like a plain document's text. The
+            // fill is length- and newline-preserving, so the spans are document coordinates already, and
+            // each cell is the plain parse of its placeholder slice with the whole-document tags
+            // correlated onto it by the engine (buildTemplatedSlice). One span (every single-statement
+            // model, or a tiling failure) keeps the whole-text cell itself: byte-identical products,
+            // same cache entry as before cells existed on this door.
+            const whole = this.buildTemplatedCell(text, opts.templating, opts.provider);
+            const r = whole.cached.templated;
+            const spans = opts.templating.parseCell ? splitStatements(r.placeholder, dialect) : [whole.cell.span];
+            if (spans.length === 1) {
+                cells = [whole.cell];
+                backing = [whole.cached];
+                templated = r;
+            }
+            else {
+                const setsKey = setResolutionKey(r, text);
+                const handedOut = new Set();
+                cells = [];
+                backing = [];
+                for (const span of spans) {
+                    const built = this.buildTemplatedSlice(span, r, opts.templating, opts.provider, setsKey, handedOut);
+                    cells.push(built.cell);
+                    backing.push(built.cached);
+                }
+                templated = withCellCorrelation(r, cells, backing);
+            }
         }
         else {
             // Split into per-statement cells and parse each independently, reusing unchanged cells from
@@ -178,7 +201,7 @@ export class SqlDocument {
         }
         this.statements = Object.freeze(cells);
         this._cells = backing;
-        this.templated = opts.templating ? backing[0].templated : undefined;
+        this.templated = templated;
         // Whole-document facade. tokens/diagnostics/errors are the cheap concat/sum across cells.
         this.tokens = cells.flatMap((c) => c.tokens);
         this.diagnostics = cells.flatMap((c) => c.diagnostics);
@@ -254,14 +277,16 @@ export class SqlDocument {
         });
         return { cell, cached };
     }
-    /** Build the ONE cell for a TEMPLATED document: span [0, text.length) — the templated build path
-     *  bypasses `splitStatements` entirely (one cell, whole text), and its products come from a single
-     *  `engine.parse(text, dialect, { provider })` call rather than the plain per-dialect `parse()`.
-     *  `r.tokens`/`r.diagnostics` are ALREADY document coordinates (the cell always starts at 0), so —
-     *  unlike `buildCell` — nothing is shifted. Mirrors `buildCell`'s CachedCell/StatementCell shapes
-     *  so every downstream consumer (analyze(), cellAt(), nodeAt()…) sees the same structure whether
-     *  the document is plain or templated. Cached in the SAME cross-edit `_cellCache` as plain cells,
-     *  under a prefixed key so a templated cell can never collide with a plain one for the same text. */
+    /** Build the WHOLE-TEXT cell of a TEMPLATED document: span [0, text.length), its products from a
+     *  single `engine.parse(text, dialect, { provider })` call rather than the plain per-dialect
+     *  `parse()`. It is the document's one cell when the placeholder splits into one statement (every
+     *  single-statement model), and the carrier of the engine result (`templated`) that a multi-cell
+     *  document's slices are built from. `r.tokens`/`r.diagnostics` are ALREADY document coordinates
+     *  (the cell always starts at 0), so, unlike `buildCell`, nothing is shifted. Mirrors
+     *  `buildCell`'s CachedCell/StatementCell shapes so every downstream consumer (analyze(), cellAt(),
+     *  nodeAt()…) sees the same structure whether the document is plain or templated. Cached in the SAME
+     *  cross-edit `_cellCache` as plain cells, under a prefixed key so a templated cell can never
+     *  collide with a plain one for the same text. */
     buildTemplatedCell(text, engine, provider) {
         const span = { start: 0, end: text.length };
         // Collision-proofed against a plain cell's `dialect + " " + text` key by the "templated "
@@ -301,6 +326,67 @@ export class SqlDocument {
         });
         return { cell, cached };
     }
+    /** Build one statement cell of a MULTI-cell templated document for `span` (a `splitStatements`
+     *  span over the engine's placeholder). The cell is the plain parse of its placeholder slice,
+     *  cell-relative like a plain cell, with the whole-document tags correlated onto it by
+     *  `engine.parseCell` (provider-resolved source names + `template` markers, so the fill never
+     *  reaches scope/qualify). Cached across edits like a plain cell: the key is the placeholder
+     *  slice (what parsed) plus the raw slice (which tags sit inside it), the engine + provider
+     *  version (what the tags resolve to) and `setsKey` (the `{% set %}`/`{% macro %}`/`{% for %}`
+     *  tags anywhere in the text that steer a bare `{{ t }}` binding). The document-level products
+     *  are projected onto the cell by span rather than re-derived: `tokens` is the unified SQL+jinja
+     *  stream sliced, `diagnostics` the scrubbed set filtered (the last cell absorbs end-of-text),
+     *  `errors` that count. `handedOut` dedupes intra-document duplicates exactly as `buildCell` does. */
+    buildTemplatedSlice(span, r, engine, provider, setsKey, handedOut) {
+        const rawText = this.text.slice(span.start, span.end);
+        const placeholderText = r.placeholder.slice(span.start, span.end);
+        const providerVersion = provider?.version ?? 0;
+        // `setsKey` is length-prefixed and the two slices are equal-length (the fill is
+        // length-preserving), so the plain concatenation is unambiguous without a separator byte.
+        const key = `templated-cell ${engine.name}@${providerVersion} ${this.dialect} ${setsKey.length}:${setsKey}${placeholderText}${rawText}`;
+        let cached = this._cellCache.get(key);
+        if (cached !== undefined && handedOut.has(cached))
+            cached = undefined; // intra-doc duplicate
+        if (cached === undefined) {
+            const c = engine.parseCell(r, span, this.text, this.dialect, { provider });
+            cached = {
+                text: rawText,
+                category: c.sql.ast.statement ?? "other",
+                ast: c.sql.ast,
+                cst: c.sql.cst,
+                // Resolve scopes from the already-lowered (marker-carrying) ast: never re-parse.
+                scopes: toScopes(c.sql.ast, { dialect: this.dialect }),
+                tokens: c.sql.tokens,
+                errors: c.sql.errors,
+                diagnostics: c.sql.diagnostics,
+                analysis: new WeakMap(),
+                correlation: {
+                    tagStartOf: new Map(c.links.map((l) => [l.node, l.tagStart])),
+                    primaryAt: new Map(c.links.filter((l) => l.primary).map((l) => [l.tagStart, l.node])),
+                },
+            };
+            // Cache only the FIRST product for a key (see buildCell: duplicates stay uncached).
+            if (this._cellCache.get(key) === undefined)
+                this._cellCache.set(key, cached);
+        }
+        handedOut.add(cached);
+        const last = span.end === this.text.length;
+        const inCell = (offset) => offset >= span.start && (offset < span.end || last);
+        const tokens = r.tokens.filter((t) => inCell(t.start));
+        const diagnostics = r.diagnostics.filter((d) => inCell(d.offset ?? this.lines.offsetAt(d.line - 1, d.column)));
+        const cell = Object.freeze({
+            span,
+            text: cached.text,
+            category: cached.category,
+            ast: cached.ast,
+            cst: cached.cst,
+            scopes: cached.scopes,
+            tokens,
+            errors: diagnostics.length,
+            diagnostics,
+        });
+        return { cell, cached };
+    }
     /** Build a document for `text` in `dialect`. Total: never throws, even on broken / mid-edit input.
      *  Starts a FRESH cell cache — cross-edit reuse comes from withText(), not create(). Pass
      *  `templating` to parse through an injected TemplateEngine (jinja-SQL etc.) instead of the plain
@@ -716,8 +802,7 @@ export class SqlDocument {
      *  subset, see `scopeOutputColumns`'s pipe doc comment. Falls through to this document's own
      *  (single-arm) answer when there are no variants; there is no pre-existing single-doc
      *  equivalent to delegate to, unlike unionSymbols/unionDiagnostics, so the no-variant case is
-     *  just the one-arm instance of the same algorithm. A MULTI-STATEMENT document (no variants: the
-     *  templated door always forces exactly one cell, so the two "multi" shapes never overlap) merges
+     *  just the one-arm instance of the same algorithm. A MULTI-STATEMENT document (or arm) merges
      *  every statement CELL's own CTEs instead, each shifted from cell-relative to DOCUMENT coordinates
      *  (the same shift `analyze()` already applies to symbols/diagnostics for a multi-cell document);
      *  the compound facade itself carries no CTEs, so cells are the real per-statement source. Memoized
@@ -783,27 +868,23 @@ export class SqlDocument {
         }
         return order.map((name) => ({ name, span: byName.get(name) }));
     }
-    /** One "arm" `unionCtes`/`unionOutputColumns` aggregate over, unified across the two shapes that
-     *  can each independently make a document "multi" (never both at once: the templated door always
-     *  builds exactly one statement cell, see its own comment above): a templated document's real
-     *  variants (each a full arm SqlDocument, already in DOCUMENT coordinates, zero shift), or, for a
-     *  plain multi-statement document, each statement CELL (cell-relative scopes, shifted to document
-     *  coordinates by the cell's start, mirroring `buildAnalysis`'s per-cell shift). A single-cell,
-     *  non-templated document is the trivial one-arm case of the same shape (zero shift, this
-     *  document's own scopes/qualification). */
+    /** The "arms" `unionCtes`/`unionOutputColumns` aggregate over, unified across the two shapes that
+     *  make a document "multi", VARIANTS FIRST (ruled 2026-09-13): a templated document's real
+     *  variants are the unit, each arm SqlDocument (already in DOCUMENT coordinates, since a
+     *  realization is length-preserving) contributing its own statement cells through `ownArms`; a
+     *  document without variants contributes its own cells the same way. A region can span a cell
+     *  boundary, so cells-first (arms inside each cell) is not an option. */
     armsData(s) {
+        if (this.variants.length > 0)
+            return this.variants.flatMap((v) => v.doc().ownArms(s));
+        return this.ownArms(s);
+    }
+    /** This document's own arms, variants ignored: each statement CELL of a multi-cell document
+     *  (cell-relative scopes, shifted to document coordinates by the cell's start, mirroring
+     *  `buildAnalysis`'s per-cell shift), or the single-cell document itself (zero shift, its own
+     *  scopes/qualification). */
+    ownArms(s) {
         const ZERO = { line: 0, col: 0, offset: 0 };
-        if (this.variants.length > 0) {
-            return this.variants.map((v) => {
-                const doc = v.doc();
-                return {
-                    scopeRoot: doc.scopes.root,
-                    qualification: doc.analyze(s).qualification,
-                    dialect: doc.dialect,
-                    base: ZERO,
-                };
-            });
-        }
         if (this.statements.length > 1) {
             return this.statements.map((cell, i) => {
                 const p = this.lines.positionAt(cell.span.start);
@@ -825,6 +906,52 @@ export class SqlDocument {
         ];
     }
 }
+/** The cache-key component of a templated cell's tag correlation that the cell's own text does not
+ *  determine: the raw text of every `{% set %}` / `{% macro %}` / `{% for %}` tag in the document. A
+ *  bare `{{ t }}` source binds through a literal `{% set t = ref(...) %}` declared ANYWHERE, and an
+ *  inline macro or a `for` target anywhere disables that binding (apply-tags' `resolveSets`), so a
+ *  change to any of them must miss every cell. */
+function setResolutionKey(r, text) {
+    const parts = [];
+    for (const t of r.tags) {
+        if (t.kind !== "control")
+            continue;
+        if (t.keyword === "set" || t.keyword === "macro" || t.keyword === "for")
+            parts.push(text.slice(t.tagSpan.start, t.tagSpan.end));
+    }
+    // A control tag's own text never contains a tag boundary, so a newline join is unambiguous.
+    return parts.join("\n");
+}
+/** The `templated` facade of a MULTI-cell templated document: the whole-text engine result with
+ *  `tagOf`/`nodeOf` answering from the CELLS' own correlations (the per-statement IR consumers reach
+ *  through `statements`/`cellAt`/`nodeAt`), never from the whole-text parse, whose nodes a multi-cell
+ *  document does not expose (its `ast` is the compound facade). A cell's join names its tag by
+ *  cell-relative start, so the answer is always one of THIS parse's TagNodes, whichever parse the
+ *  cached cell was built under. Everything else is the engine's. */
+function withCellCorrelation(r, cells, backing) {
+    const tagAt = new Map(r.tags.map((t) => [t.tagSpan.start, t]));
+    return {
+        ...r,
+        tagOf: (node) => {
+            for (let i = 0; i < backing.length; i++) {
+                const rel = backing[i].correlation?.tagStartOf.get(node);
+                if (rel !== undefined)
+                    return tagAt.get(cells[i].span.start + rel);
+            }
+            return undefined;
+        },
+        nodeOf: (tag) => {
+            for (let i = 0; i < backing.length; i++) {
+                const span = cells[i].span;
+                if (tag.tagSpan.start < span.start || tag.tagSpan.start >= span.end)
+                    continue;
+                return backing[i].correlation?.primaryAt.get(tag.tagSpan.start - span.start);
+            }
+            return undefined;
+        },
+        diagnosticsOf: (tag) => r.diagnosticsOf(tag),
+    };
+}
 /** Dedup `items` by a string key, keeping the FIRST occurrence of each key — arm/document order, so
  *  the "first live arm wins" representative-data rule falls out of plain array order. */
 function dedupBy(items, keyOf) {

package/dist/document/split.d.ts

@@ -2,7 +2,8 @@ import type { Dialect } from "../dialect.js";
 export interface StatementCellSpan {
     /** doc offset, inclusive — cell text includes leading trivia. */
     start: number;
-    /** doc offset, exclusive — includes the trailing separator (`;` / GO line). */
+    /** doc offset, exclusive — includes the trailing separator (`;` / GO line); the document's last
+     *  cell also includes whatever trivia follows its separator, up to `text.length`. */
     end: number;
 }
 /**

package/dist/document/split.js

@@ -26,7 +26,10 @@ const NON_OPENER_END_SUFFIXES = new Set(["IF", "WHILE", "FOR", "LOOP", "REPEAT"]
 function wholeDoc(text) {
     return [{ start: 0, end: text.length }];
 }
-/** Every offset in `text` where a top-level separator ends (exclusive), in ascending order. */
+/** Every offset in `text` where a top-level separator ends (exclusive), in ascending order. A
+ *  separator that no channel-0 token follows (only whitespace, comments, the final newline) is not
+ *  a split end: the trivia after it belongs to the cell it terminates, so a single terminated
+ *  statement is one cell rather than a statement plus a token-less tail cell. */
 function findSplitEnds(text, tokens, dialect) {
     const channel0 = tokens.filter((t) => t.channel === 0);
     const ends = [];
@@ -80,6 +83,11 @@ function findSplitEnds(text, tokens, dialect) {
             }
         }
     }
+    // Tokens are in source order, so the last channel-0 token decides whether anything real follows
+    // the last separator.
+    const lastReal = channel0[channel0.length - 1];
+    if (ends.length > 0 && (lastReal === undefined || lastReal.start < ends[ends.length - 1]))
+        ends.pop();
     return ends;
 }
 /** Turn ascending split-end offsets into contiguous cells tiling `[0, text.length)`. A doc

package/dist/minijinja/apply-tags.d.ts

@@ -1,6 +1,13 @@
 import type { QueryExpr } from "../ir/ir.js";
 import type { TemplateCall, TemplateProvider } from "../qualify/template-provider.js";
 import type { MacroCall, TagNode } from "./tag-ast.js";
+/** A statement cell's start in the document: 0-based line, 0-based column, char offset (the shape
+ *  `LineIndex.positionAt` answers). Zero = the whole-text parse. */
+export interface CellBase {
+    line: number;
+    column: number;
+    offset: number;
+}
 /** The rebuilt AST plus the tag↔node correlations collected while building it. */
 export interface TagCorrelation {
     ast: QueryExpr;
@@ -8,6 +15,12 @@ export interface TagCorrelation {
     byNode: WeakMap<object, TagNode>;
     /** TagNode → the IR node it became (undefined-by-absence for tags with no IR presence). */
     byTag: Map<TagNode, object>;
+    /** Every attached (node, tag) pair in attach order: the enumerable form of `byNode`, for a
+     *  caller that must re-key the join to another parse's TagNodes (a cached statement cell). */
+    links: {
+        node: object;
+        tag: TagNode;
+    }[];
 }
 /**
  * Rewrite templated FROM/JOIN sources in `ast` to carry their provider-resolved name (when the
@@ -15,8 +28,13 @@ export interface TagCorrelation {
  * containment. Returns the SAME `ast` reference when nothing correlates (structural sharing);
  * returns a re-frozen rebuilt tree otherwise. Total, never throws; the correlation maps are empty
  * (not absent) on the no-op and error paths.
+ *
+ * `base` is the cell's start position when `ast` is ONE STATEMENT CELL's parse of the placeholder
+ * (`parseTemplatedCell`): the node offsets are cell-relative while `tags` and `text` are the whole
+ * document's, so containment compares `offset + base.offset`, and every span this transform writes
+ * into the IR is rebased to cell coordinates. Zero (the default) is the whole-text parse.
  */
-export declare function applyTemplateTags(ast: QueryExpr, tags: TagNode[], text: string, provider: TemplateProvider): TagCorrelation;
+export declare function applyTemplateTags(ast: QueryExpr, tags: TagNode[], text: string, provider: TemplateProvider, base?: CellBase): TagCorrelation;
 /**
  * The provider key of a tag-AST MacroCall — name + package + literal args, with kwargs
  * carried separately (the channel-agreed TemplateCall contract: quote-stripped, escapes

package/dist/minijinja/apply-tags.js

@@ -30,6 +30,7 @@ import { debugRethrow } from "../debug.js";
 import { freezeIR } from "../ir/freeze.js";
 import { qualifiedNameOf, synthesizedQualifiedName } from "../ir/qualified-name.js";
 import { resolveBehavior } from "../dialect-behavior/registry.js";
+const ZERO_BASE = { line: 0, column: 0, offset: 0 };
 /** Record a freshly built node's correlation to the tag it came from, then return it unchanged
  *  (a passthrough so call sites stay expression-shaped). A scalar-slot tag lowers to BOTH a
  *  column Expr (`kind: "column"`) and a parallel ColumnRef record (`kind: "columnref"`, same
@@ -38,6 +39,7 @@ import { resolveBehavior } from "../dialect-behavior/registry.js";
  *  of which one this walk visits first. */
 function attach(ctx, node, tag) {
     ctx.byNode.set(node, tag);
+    ctx.links.push({ node, tag });
     const existing = ctx.byTag.get(tag);
     if (existing?.kind !== "column")
         ctx.byTag.set(tag, node);
@@ -49,25 +51,33 @@ function attach(ctx, node, tag) {
  * containment. Returns the SAME `ast` reference when nothing correlates (structural sharing);
  * returns a re-frozen rebuilt tree otherwise. Total, never throws; the correlation maps are empty
  * (not absent) on the no-op and error paths.
+ *
+ * `base` is the cell's start position when `ast` is ONE STATEMENT CELL's parse of the placeholder
+ * (`parseTemplatedCell`): the node offsets are cell-relative while `tags` and `text` are the whole
+ * document's, so containment compares `offset + base.offset`, and every span this transform writes
+ * into the IR is rebased to cell coordinates. Zero (the default) is the whole-text parse.
  */
-export function applyTemplateTags(ast, tags, text, provider) {
+export function applyTemplateTags(ast, tags, text, provider, base = ZERO_BASE) {
     const byNode = new WeakMap();
     const byTag = new Map();
+    const links = [];
     try {
         // config is a no-output tag (whitespace-filled), so it can never yield a table
         // source and stays out of the correlation set even though ExprTag admits it.
         // An incomplete/mid-typing call (`{{ ref('cu`) is NOT a resolved source, so skip it.
         const relTags = tags.filter((t) => (t.kind === "call" && !t.incomplete) || t.kind === "other");
         if (relTags.length === 0)
-            return { ast, byNode, byTag };
+            return { ast, byNode, byTag, links };
         const nameConfig = ast.dialect !== undefined ? resolveBehavior(ast.dialect).nameConfig : undefined;
         const ctx = {
             relTags,
             sets: resolveSets(tags, text, provider),
             text,
             provider,
+            base,
             byNode,
             byTag,
+            links,
             ...(nameConfig ? { nameConfig } : {}),
         };
         const next = transformQuery(ast, ctx);
@@ -75,11 +85,11 @@ export function applyTemplateTags(ast, tags, text, provider) {
         // fill gets a `template` marker (span + provider key), so inference resolves it
         // through the provider and qualify never checks the placeholder as a real column.
         const marked = markTemplateExprs(next, ctx);
-        return { ast: marked === ast ? ast : freezeIR(marked), byNode, byTag };
+        return { ast: marked === ast ? ast : freezeIR(marked), byNode, byTag, links };
     }
     catch (e) {
         debugRethrow(e);
-        return { ast, byNode: new WeakMap(), byTag: new Map() };
+        return { ast, byNode: new WeakMap(), byTag: new Map(), links: [] };
     }
 }
 /** The TemplateExprInfo for a scalar-slot tag: its span + (when an identity is extractable)
@@ -89,14 +99,14 @@ function exprInfoOf(tag, ctx) {
     // A call tag (ref/source/var/env_var/a macro) carries its provider key straight off the call,
     // callOf reads name + literal args from the source, uniform across every callee.
     if (tag.kind === "call")
-        return { span: tag.tagSpan, call: callOf(tag, ctx.text) };
+        return { span: cellSpan(tag.tagSpan, ctx), call: callOf(tag, ctx.text) };
     // A non-call `other` tag: a bare `{{ t }}` resolving through a single-call `{% set t = … %}`
     // carries that RHS call; anything else is opaque.
     const ident = bareIdentOf(tag, ctx.text);
     const resolved = ident !== undefined ? ctx.sets.get(ident) : undefined;
     if (resolved)
-        return { span: tag.tagSpan, call: resolved.call };
-    return { span: tag.tagSpan };
+        return { span: cellSpan(tag.tagSpan, ctx), call: resolved.call };
+    return { span: cellSpan(tag.tagSpan, ctx) };
 }
 /** `{{ var('x') }}` / `{{ env_var('Y', …) }}` — the name + first literal arg, lexically. */
 const VALUE_CALL_TAG = /^\{\{-?\s*(var|env_var)\s*\(\s*(['"])([^'"\\]*)\2\s*(,[\s\S]*?)?\)\s*(?:\|[\s\S]*)?-?\}\}$/;
@@ -129,7 +139,7 @@ function markTemplateExprs(node, ctx) {
     if ((isColumnExpr || isColumnRef) && rec.template === undefined) {
         const start = rec.cst?.start?.start;
         if (start !== undefined) {
-            const tag = containingTag(ctx.relTags, start);
+            const tag = containingTag(ctx.relTags, start + ctx.base.offset);
             if (tag)
                 return attach(ctx, { ...rec, template: exprInfoOf(tag, ctx) }, tag);
         }
@@ -280,6 +290,22 @@ function containingTag(tags, offset) {
     }
     return undefined;
 }
+/** A document-coordinate tag span rebased to the cell's coordinates (the inverse of
+ *  src/document/shift.ts's `shiftPartSpan`): a span on the cell's first line also loses the cell's
+ *  start column. The whole-text parse (zero base) keeps the span object itself. */
+function cellSpan(p, ctx) {
+    const b = ctx.base;
+    if (b.offset === 0 && b.line === 0 && b.column === 0)
+        return p;
+    return {
+        start: p.start - b.offset,
+        end: p.end - b.offset,
+        line: p.line - b.line,
+        column: p.line === b.line + 1 ? p.column - b.column : p.column,
+        endLine: p.endLine - b.line,
+        endColumn: p.endLine === b.line + 1 ? p.endColumn - b.column : p.endColumn,
+    };
+}
 function transformQuery(q, ctx) {
     const ctes = mapShared(q.ctes, (c) => transformCte(c, ctx));
     const body = transformBody(q.body, ctx);
@@ -401,7 +427,7 @@ function transformTableSource(src, ctx) {
     const startTok = src.cst?.start;
     if (!startTok)
         return src;
-    const tag = containingTag(ctx.relTags, startTok.start);
+    const tag = containingTag(ctx.relTags, startTok.start + ctx.base.offset);
     if (!tag)
         return src;
     // A placeholder-fill alias sits INSIDE the tag span: a multi-line tag fills one
@@ -414,7 +440,7 @@ function transformTableSource(src, ctx) {
     // fill limitation, out of apply-tags' reach); making it `undefined` here is honest,
     // where `jjj…` was a fabrication.
     const aliasTok = src.aliasCst?.start;
-    const base = aliasTok != null && inSpan(aliasTok.start, tag.tagSpan) ? withoutAlias(src) : src;
+    const base = aliasTok != null && inSpan(aliasTok.start + ctx.base.offset, tag.tagSpan) ? withoutAlias(src) : src;
     // An unresolved source's name is the RAW TAG TEXT — the bytes the user actually wrote. The
     // placeholder fill is scaffolding this library invented so the grammar parses; letting it
     // escape as a relation name (scope sources, lineage dependencies, go-to-def) is fabrication
@@ -432,7 +458,8 @@ function transformTableSource(src, ctx) {
             : qualifiedNameOf(parts, ctx.nameConfig);
         return { ...b, relation };
     };
-    // NOTE: `template.span` intentionally aliases `tag.tagSpan` BY REFERENCE. freezeIR
+    // NOTE: on the whole-text parse `template.span` intentionally aliases `tag.tagSpan` BY
+    // REFERENCE (a statement cell's parse gets a rebased copy, see `cellSpan`). freezeIR
     // therefore also freezes the TagNode.tagSpan object returned in `.tags`, benign
     // since spans are read-only. Every call marker carries its `call`, the provider key
     // the semantic layer resolves the relation and its columns through (relation-columns.ts).
@@ -444,7 +471,7 @@ function transformTableSource(src, ctx) {
         // Either way the `call` keeps it consultable, so an unresolved call is not a dead end: a
         // provider added later resolves it. ref vs source is not stored here, it is call.name.
         const named = rel ? renamed(base, [...rel.nameParts], true) : renamed(base, rawTagName, false);
-        const template = { kind: "call", span: tag.tagSpan, call };
+        const template = { kind: "call", span: cellSpan(tag.tagSpan, ctx), call };
         return attach(ctx, { ...named, template }, tag);
     }
     // Non-call expression tag (var / env_var / other) in a FROM slot. A bare `{{ t }}` resolving
@@ -455,9 +482,14 @@ function transformTableSource(src, ctx) {
     const resolved = ident !== undefined ? ctx.sets.get(ident) : undefined;
     if (resolved) {
         const named = resolved.name ? renamed(base, [...resolved.name], true) : renamed(base, rawTagName, false);
-        const template = { kind: "call", span: tag.tagSpan, indirect: true, call: resolved.call };
+        const template = {
+            kind: "call",
+            span: cellSpan(tag.tagSpan, ctx),
+            indirect: true,
+            call: resolved.call,
+        };
         return attach(ctx, { ...named, template }, tag);
     }
-    const template = { kind: "expr", span: tag.tagSpan, opaque: true };
+    const template = { kind: "expr", span: cellSpan(tag.tagSpan, ctx), opaque: true };
     return attach(ctx, { ...renamed(base, rawTagName, false), template }, tag);
 }

package/dist/minijinja/engine.js

@@ -1,4 +1,4 @@
-import { parseTemplated } from "./parse.js";
+import { parseTemplated, parseTemplatedCell } from "./parse.js";
 import { templateVariants } from "./variants.js";
 /** The minijinja template engine (the Rust engine dbt Fusion uses — the grammar
  *  oracle for what we accept). The shipped, and only, TemplateEngine. */
@@ -7,5 +7,6 @@ export function minijinja() {
         name: "minijinja",
         parse: (text, dialect, opts) => parseTemplated(text, dialect, opts),
         variants: (text, dialect) => templateVariants(text, dialect),
+        parseCell: (whole, span, text, dialect, opts) => parseTemplatedCell(whole, span, text, dialect, opts),
     };
 }

package/dist/minijinja/parse.d.ts

@@ -1,6 +1,6 @@
 import type { Dialect } from "../dialect.js";
 import type { Token } from "../token/token.js";
-import type { MacroShape, TemplatedParseOptions, TemplatedParseResult } from "../template/engine.js";
+import type { MacroShape, TemplatedCellResult, 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";
@@ -28,3 +28,18 @@ export declare function parseTemplated(text: string, dialect: Dialect, opts?: Te
  * of parseTemplated. Total — never throws.
  */
 export declare function tokenizeTemplated(text: string, dialect: Dialect, opts?: TemplatedParseOptions): Token[];
+/**
+ * One statement cell of a templated document (`TemplateEngine.parseCell`): the plain per-dialect
+ * parse of the placeholder slice `[span.start, span.end)`, the same batch-of-one path a plain
+ * document's cells take, so IR / CST / tokens / diagnostics are CELL-relative, with `whole`'s tags
+ * correlated onto it by DOCUMENT offset (a node's cell offset plus the cell's start). The cell's
+ * sources then carry their provider-resolved names and `template` markers exactly as the
+ * whole-text parse's do, never the fill; a marker's `span` is rebased to cell coordinates like
+ * every other span in the cell IR, and the tag↔node join is returned as cell-relative `links`
+ * so a cached cell re-keys it to whatever parse it is later reused under.
+ * Total: `applyTemplateTags` leaves the plain parse in place on any internal surprise.
+ */
+export declare function parseTemplatedCell(whole: TemplatedParseResult, span: {
+    start: number;
+    end: number;
+}, text: string, dialect: Dialect, opts?: TemplatedParseOptions): TemplatedCellResult;

package/dist/minijinja/parse.js

@@ -651,3 +651,40 @@ export function parseTemplated(text, dialect, opts) {
 export function tokenizeTemplated(text, dialect, opts) {
     return parseTemplated(text, dialect, opts).tokens;
 }
+/**
+ * One statement cell of a templated document (`TemplateEngine.parseCell`): the plain per-dialect
+ * parse of the placeholder slice `[span.start, span.end)`, the same batch-of-one path a plain
+ * document's cells take, so IR / CST / tokens / diagnostics are CELL-relative, with `whole`'s tags
+ * correlated onto it by DOCUMENT offset (a node's cell offset plus the cell's start). The cell's
+ * sources then carry their provider-resolved names and `template` markers exactly as the
+ * whole-text parse's do, never the fill; a marker's `span` is rebased to cell coordinates like
+ * every other span in the cell IR, and the tag↔node join is returned as cell-relative `links`
+ * so a cached cell re-keys it to whatever parse it is later reused under.
+ * Total: `applyTemplateTags` leaves the plain parse in place on any internal surprise.
+ */
+export function parseTemplatedCell(whole, span, text, dialect, opts) {
+    const sql = parse(whole.placeholder.slice(span.start, span.end), dialect);
+    const provider = opts?.provider ?? OPEN_PROVIDER;
+    const correlation = applyTemplateTags(sql.ast, whole.tags, text, provider, cellBaseOf(text, span.start));
+    return {
+        sql: { ...sql, ast: correlation.ast },
+        links: correlation.links.map(({ node, tag }) => ({
+            node,
+            tagStart: tag.tagSpan.start - span.start,
+            primary: correlation.byTag.get(tag) === node,
+        })),
+    };
+}
+/** The cell start's 0-based line / column / char offset in `text` (`\n` is the line break, the
+ *  convention every span in the pipeline follows; a `\r` is an ordinary column). */
+function cellBaseOf(text, offset) {
+    let line = 0;
+    let lineStart = 0;
+    for (let i = 0; i < offset; i++) {
+        if (text.charCodeAt(i) === 10) {
+            line++;
+            lineStart = i + 1;
+        }
+    }
+    return { line, column: offset - lineStart, offset };
+}

package/dist/template/engine.d.ts

@@ -88,6 +88,29 @@ export interface TemplatedParseResult {
      *  scrubber widened to it. Empty array when none. */
     diagnosticsOf(tag: TagNode): SyntaxDiagnostic[];
 }
+/** One template-marked node of a statement cell's IR and the tag it came from, the tag named by
+ *  its CELL-relative start offset rather than by object: a cell is cached across edits and reused
+ *  under a later parse whose TagNodes are fresh objects, so the join is re-keyed to that parse's
+ *  tag at the same offset. `primary` marks the tag's one answer (a scalar-slot tag marks both a
+ *  column expression and its column-ref record; the expression is primary). */
+export interface TemplatedCellLink {
+    node: object;
+    /** `tag.tagSpan.start - cell.span.start`. */
+    tagStart: number;
+    primary: boolean;
+}
+/** One statement CELL of a templated document (`TemplateEngine.parseCell`): the plain per-dialect
+ *  parse of the cell's placeholder slice, in CELL-relative coordinates like a plain document's
+ *  cells, with the whole-document tags correlated onto it (provider-resolved source names,
+ *  `template` markers, and the two-spine join). */
+export interface TemplatedCellResult {
+    /** The cell's SQL parse over its placeholder slice (ast / cst / tokens / errors / diagnostics),
+     *  every span cell-relative. A `template` marker's span is cell-relative too. */
+    sql: ParseResultIR;
+    /** The tag↔node join over THIS cell's IR, position- and identity-independent (see
+     *  `TemplatedCellLink`). Empty when nothing correlates. */
+    links: TemplatedCellLink[];
+}
 /** A template engine: the syntax front end for one templating language over
  *  SQL. `parse` must satisfy the engine contract the conformance suite
  *  checks — tokens tile the source byte-for-byte, every span in original
@@ -99,4 +122,13 @@ export interface TemplateEngine {
     parse(text: string, dialect: Dialect, opts?: TemplatedParseOptions): TemplatedParseResult;
     /** Optional: coherent per-branch variant enumeration, for engines with control-flow arms. */
     variants?(text: string, dialect: Dialect): TemplateVariant[];
+    /** Optional: the products of ONE statement cell of a templated document, the plain parse of
+     *  `whole.placeholder`'s slice `[span.start, span.end)` (cell-relative) with `whole`'s tags
+     *  correlated onto it. `whole` is this engine's own `parse` result for the full `text`, `span`
+     *  a `splitStatements` span over that placeholder. An engine without it keeps the templated
+     *  `SqlDocument` door at one whole-text cell. */
+    parseCell?(whole: TemplatedParseResult, span: {
+        start: number;
+        end: number;
+    }, text: string, dialect: Dialect, opts?: TemplatedParseOptions): TemplatedCellResult;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sqllens",
-	"version": "1.9.1",
+	"version": "1.10.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",