sqllens 1.1.0 → 1.2.0

package/dist/completion/atn-walk.d.ts

@@ -1,4 +1,4 @@
-import { type Parser } from "antlr4ng";
+import { type ATN } from "antlr4ng";
 /**
  * What can legally come next at the caret:
  *  - `tokens`: candidate terminal token TYPES (keywords/punctuation/literals) collectable there.
@@ -9,6 +9,13 @@ export interface Candidates {
     tokens: Set<number>;
     rules: Set<number>;
 }
+/** The minimal token view the walk needs: each token's antlr type + channel, in source order. Both
+ *  antlr's `Token` and our neutral `Token` (src/token/token.ts) satisfy it, so the walk runs over
+ *  the document's OWN already-lexed token stream, never a re-parse. */
+export interface WalkToken {
+    type: number;
+    channel: number;
+}
 /**
  * Our own ATN candidate-collection walk — a reimplementation of antlr4-c3's
  * `CodeCompletionCore` (`collectCandidates` / `processRule` / `translateStackToRuleIndex`),
@@ -20,5 +27,9 @@ export interface Candidates {
  * (`tokenListIndex === caretListIndex`) every terminal transition's label contributes its token
  * types as candidates — unless the current rule call stack is inside a preferred (name/column)
  * rule, in which case we record that rule and suppress the raw tokens it subsumes.
+ *
+ * `atn` is the dialect's parser ATN (input-independent, a per-dialect static) and `tokens` is the
+ * document's own lexed token stream up to (at least) the caret; the walk consumes only their `type`
+ * and `channel`, so it reuses the already-parsed tokens rather than re-lexing the source.
  */
-export declare function collectCandidates(parser: Parser, startRuleIndex: number, caretTokenIndex: number, preferredRules: Set<number>, ignoredTokens: Set<number>): Candidates;
+export declare function collectCandidates(atn: ATN, startRuleIndex: number, tokens: readonly WalkToken[], caretTokenIndex: number, preferredRules: Set<number>, ignoredTokens: Set<number>): Candidates;

package/dist/completion/atn-walk.js

@@ -10,13 +10,17 @@ import { AtomTransition, NotSetTransition, RangeTransition, RuleStopState, RuleT
  * (`tokenListIndex === caretListIndex`) every terminal transition's label contributes its token
  * types as candidates — unless the current rule call stack is inside a preferred (name/column)
  * rule, in which case we record that rule and suppress the raw tokens it subsumes.
+ *
+ * `atn` is the dialect's parser ATN (input-independent, a per-dialect static) and `tokens` is the
+ * document's own lexed token stream up to (at least) the caret; the walk consumes only their `type`
+ * and `channel`, so it reuses the already-parsed tokens rather than re-lexing the source.
  */
-export function collectCandidates(parser, startRuleIndex, caretTokenIndex, preferredRules, ignoredTokens) {
-    const walk = new CandidateWalk(parser, caretTokenIndex, preferredRules, ignoredTokens);
+export function collectCandidates(atn, startRuleIndex, tokens, caretTokenIndex, preferredRules, ignoredTokens) {
+    const walk = new CandidateWalk(atn, tokens, caretTokenIndex, preferredRules, ignoredTokens);
     return walk.run(startRuleIndex);
 }
 class CandidateWalk {
-    parser;
+    atn;
     preferredRules;
     ignoredTokens;
     tokens = { tokens: new Set(), rules: new Set() };
@@ -32,16 +36,15 @@ class CandidateWalk {
      * during a walk — that persistence is what kills the blowup.
      */
     shortcutMap = new Map();
-    constructor(parser, caretTokenIndex, preferredRules, ignoredTokens) {
-        this.parser = parser;
+    constructor(atn, tokens, caretTokenIndex, preferredRules, ignoredTokens) {
+        this.atn = atn;
         this.preferredRules = preferredRules;
         this.ignoredTokens = ignoredTokens;
         // Precompute the on-channel token types from 0 up to the caret token. The walk consumes
         // these to prune paths that cannot match what the user already typed. Mirrors c3's
         // `tokens` array built in `collectCandidates`.
-        const stream = this.parser.inputStream;
-        for (let i = 0; i <= caretTokenIndex; i++) {
-            const tok = stream.get(i);
+        for (let i = 0; i <= caretTokenIndex && i < tokens.length; i++) {
+            const tok = tokens[i];
             if (tok.channel !== Token.DEFAULT_CHANNEL)
                 continue;
             this.inputTypes.push(tok.type);
@@ -52,7 +55,7 @@ class CandidateWalk {
         this.caretListIndex = this.inputTypes.length - 1;
     }
     run(startRuleIndex) {
-        const startState = this.parser.atn.ruleToStartState[startRuleIndex];
+        const startState = this.atn.ruleToStartState[startRuleIndex];
         if (startState)
             this.processRule(startState, 0, []);
         return this.tokens;
@@ -204,7 +207,7 @@ class CandidateWalk {
         }
     }
     collectComplement(transition) {
-        const max = this.parser.atn.maxTokenType;
+        const max = this.atn.maxTokenType;
         // Cap the enumeration: a wide-open NotSet/Wildcard is not a useful keyword list.
         const COMPLEMENT_CAP = 64;
         const excluded = transition instanceof NotSetTransition && transition.label ? transition.label : null;

package/dist/completion/complete.d.ts

@@ -1,11 +1,12 @@
 import type { SqlDocument } from "../document/document.js";
 import type { SchemaProvider } from "../qualify/schema-provider.js";
 /** One completion candidate. The editor filters this list by the typed prefix and applies the
- *  chosen label at the caret; we only produce the labels, anchored at the caret offset. */
+ *  chosen label at the caret; we only produce the labels, anchored at the caret offset. The
+ *  `"template"` kind is a host candidate for a jinja call slot (a dbt model for a ref's arg). */
 export interface Completion {
     label: string;
-    kind: "keyword" | "column" | "table" | "function";
-    /** Extra display info — e.g. a column's type when the schema knows it. */
+    kind: "keyword" | "column" | "table" | "function" | "template";
+    /** Extra display info, e.g. a column's type when the schema knows it. */
     detail?: string;
 }
 /**

package/dist/completion/complete.js

@@ -2,9 +2,11 @@
 // completeAt() — scope-aware completion over a SqlDocument.
 //
 // The interactive editor feature that lives in the BROKEN-input world: the user
-// is mid-keystroke, so this runs its OWN error-tolerant lex+parse of the current
-// text (via makeParser), positions the ATN candidate walk at the caret, and turns
-// the raw {tokens, rules} the walk reports into editor completion items:
+// is mid-keystroke, so this drives an ATN candidate walk over the DOCUMENT'S OWN
+// already-lexed token stream (cell.tokens, reused not re-parsed; the document's
+// error-tolerant parse already ran, and for a templated document over the jinja
+// placeholder), positions it at the caret, and turns the raw {tokens, rules} the
+// walk reports into editor completion items:
 //   - keywords  — candidate token types whose grammar literal is a word (FROM, …)
 //   - tables    — schema table names, when the caret is at a relation-name slot
 //   - columns   — the scope's visible columns, when at a value/column slot
@@ -15,11 +17,13 @@
 // ---------------------------------------------------------------------------
 import { Token } from "antlr4ng";
 import { nodeAt } from "../document/node-at.js";
-import { displayName, foldIdentifier } from "../ident/fold.js";
-import { inferDialect } from "../infer/dialect.js";
+import { resolveBehavior } from "../dialect-behavior/registry.js";
+import { DefaultTemplateProvider } from "../qualify/template-provider.js";
+import { callOf } from "../minijinja/apply-tags.js";
 import { collectCandidates } from "./atn-walk.js";
+import { jinjaSlotAt } from "./jinja-slot.js";
 import { COMPLETION_CONFIG } from "./config.js";
-import { makeParser } from "./parser-factory.js";
+import { completionMeta } from "./parser-factory.js";
 /**
  * Completion candidates for the caret at `offset` in `doc`. Schema-aware when a `Schema` is given
  * (table names + column types). NEVER throws: on broken / mid-edit input it still returns the
@@ -38,24 +42,47 @@ export function completeAt(doc, offset, schema) {
 export const complete = completeAt;
 function collect(doc, offset, schema) {
     const dialect = doc.dialect;
+    // Inside a jinja tag ({{ ref('| }}, {% if | %}, {{ a ~ | }}) the caret is not in SQL at all, so SQL
+    // completion is wrong: the tag was blanked to a placeholder sitting in some SQL slot, so the walk
+    // would otherwise offer keywords/tables/columns inside the jinja. A recognized call slot answers the
+    // host's candidates through the template provider (the neutral provider offers none); any other
+    // position strictly inside a tag answers nothing. Only a caret outside every tag falls through to
+    // ordinary SQL completion below. Tags are reused from the document, never re-parsed.
+    const tags = doc.templated?.tags;
+    if (tags) {
+        const slot = jinjaSlotAt(tags, doc.text, offset);
+        if (slot)
+            return templateCompletions(slot, schema);
+        if (tags.some((t) => offset > t.tagSpan.start && offset < t.tagSpan.end))
+            return [];
+    }
     const cfg = COMPLETION_CONFIG[dialect];
-    // Route to the statement CELL owning the caret: the ATN walk parses that cell's text (with a
-    // cell-relative caret) and the visible-column lookup runs over that cell's own scope tree — so a
-    // caret in statement 2 of a multi-statement document completes through its real scope, not the
-    // compound facade. Single-cell: the cell IS the document, so this is identical to a whole-doc walk.
+    // Route to the statement CELL owning the caret: the visible-column lookup runs over that cell's
+    // own scope tree (cell-relative caret) and the ATN walk over that cell's own tokens, so a caret
+    // in statement 2 of a multi-statement document completes through its real scope, not the compound
+    // facade. Single-cell: the cell IS the document, so this is identical to a whole-doc walk.
     const cell = doc.cellAt(offset);
-    const cellText = cell ? cell.text : doc.text;
-    const cellOffset = cell ? offset - cell.span.start : offset;
     const cellScopes = cell ? cell.scopes : doc.scopes;
     const cellAst = cell ? cell.ast : doc.ast;
-    // Completion runs its own error-tolerant parse to position the walk (expected — the walk needs
-    // a parser whose ATN we DFS, not the document's valid-parse CST).
-    const m = makeParser(cellText, dialect);
-    // runEntry() first: the CommonTokenStream fills lazily, so the full token list (needed to find
-    // the caret token) only exists after the parse drives it.
-    m.runEntry();
-    const caretIdx = caretTokenIndex(m, cellOffset);
-    const cand = collectCandidates(m.parser, m.entryRuleIndex, caretIdx, cfg.preferredRules, cfg.ignoredTokens);
+    // Two coordinate spaces: the scope/column lookup is CELL-relative (cell.scopes/cell.ast carry
+    // cell-relative spans), the token walk is DOCUMENT-relative (cell.tokens are shifted to doc
+    // coordinates), so `offset` drives the walk and `cellOffset` the scope lookup.
+    const cellOffset = cell ? offset - cell.span.start : offset;
+    // The ATN walk reuses the DOCUMENT'S OWN already-lexed token stream instead of re-parsing the
+    // text. For a TEMPLATED document those tokens are the SQL-over-placeholder stream (the jinja tags
+    // are channel-2 tokens the walk skips), so completion sees real SQL at document-true offsets and
+    // never has to re-derive the placeholder; the raw `{{ }}` text that made a fresh lexer die from
+    // char 0 is never handed to a lexer again. A synthetic EOF closes the stream (mapTokens drops
+    // antlr's EOF sentinel), matching the entry rule's EOF anchor; its `start` past every real token
+    // keeps it the caret-index fallback for an end-of-input caret.
+    const meta = completionMeta(dialect);
+    const end = cell ? cell.span.end : doc.text.length;
+    const walkTokens = [
+        ...(cell ? cell.tokens : doc.tokens),
+        { type: Token.EOF, channel: Token.DEFAULT_CHANNEL, start: end, text: "" },
+    ];
+    const caretIdx = caretTokenIndex(walkTokens, offset);
+    const cand = collectCandidates(meta.atn, meta.entryRuleIndex, walkTokens, caretIdx, cfg.preferredRules, cfg.ignoredTokens);
     const out = [];
     const seen = new Set(); // dedup by `${kind}\0${label}`
     const add = (c) => {
@@ -67,7 +94,7 @@ function collect(doc, offset, schema) {
     };
     // keywords — from candidate token types whose grammar literal is a word.
     for (const type of cand.tokens) {
-        const label = keywordLabel(m, type);
+        const label = keywordLabel(meta.vocabulary, type);
         if (label)
             add({ label, kind: "keyword" });
     }
@@ -85,20 +112,34 @@ function collect(doc, offset, schema) {
         for (const c of visibleColumns(cellScopes, cellAst, dialect, cellOffset, schema))
             add(c);
         if (schema)
-            for (const c of fromRelationColumns(m, cfg, schema, dialect))
+            for (const c of fromRelationColumns(walkTokens, cfg, schema, dialect, doc.templated?.tags, doc.text))
                 add(c);
     }
     // functions — value/column slot: the dialect's inference-registry function names.
     if (atColumn) {
-        for (const fn of Object.keys(inferDialect(dialect).functions))
+        for (const fn of Object.keys(resolveBehavior(dialect).functions))
             add({ label: fn, kind: "function" });
     }
     return out;
 }
+/** The host's candidates for a jinja call slot, as completions. The template provider carries them,
+ *  so this reads the `schema` when it is one (a DbtTemplateProvider IS a SchemaProvider, and the host
+ *  already passes it here for column/table completion); the neutral provider offers none. A jinja slot
+ *  with no candidates still returns [], never SQL keywords, so a caret inside a tag never leaks SQL
+ *  completion. */
+function templateCompletions(slot, schema) {
+    if (!(schema instanceof DefaultTemplateProvider))
+        return [];
+    return schema.templateCandidates(slot.callee, slot.argIndex, slot.packageName).map((c) => ({
+        label: c.label,
+        kind: "template",
+        ...(c.detail !== undefined ? { detail: c.detail } : {}),
+    }));
+}
 /** The walk's caret token index: the first default-channel token whose `.start >= offset`; for an
- *  end-of-input caret that is the EOF token's index. Mirrors Task 10's tests' caret helper. */
-function caretTokenIndex(m, offset) {
-    const toks = m.tokenStream.getTokens();
+ *  end-of-input caret that is the EOF sentinel's index (last entry). Mirrors Task 10's tests' caret
+ *  helper. `toks` is the document's own token stream (doc coordinates) with the EOF sentinel appended. */
+function caretTokenIndex(toks, offset) {
     for (let i = 0; i < toks.length; i++) {
         const t = toks[i];
         if (!t || t.channel !== Token.DEFAULT_CHANNEL)
@@ -111,8 +152,8 @@ function caretTokenIndex(m, offset) {
 /** A candidate token type → a keyword label, or undefined if it is punctuation/operator or has no
  *  literal name. The grammar literal is single-quoted (`"'FROM'"`); strip the quotes and keep it
  *  only when it starts with a letter/underscore. */
-function keywordLabel(m, type) {
-    const literal = m.lexer.vocabulary.getLiteralName(type);
+function keywordLabel(vocabulary, type) {
+    const literal = vocabulary.getLiteralName(type);
     if (!literal)
         return undefined;
     const unquoted = literal.startsWith("'") && literal.endsWith("'") ? literal.slice(1, -1) : literal;
@@ -127,33 +168,47 @@ function intersects(a, b) {
     return false;
 }
 /**
- * Broken-input FROM-relation fallback. The grammar reads a mid-edit `SELECT ‹caret› FROM t` as
+ * Broken-input FROM-relation fallback. The grammar reads a mid-edit `SELECT <caret> FROM t` as
  * `SELECT FROM AS t` (FROM is a non-reserved identifier in Spark), so the document's scope has no
  * `t` source and scope-based columns come back empty. To still offer the FROM relation's columns,
  * scan the token stream for `<relationKeyword> <name>` (FROM/JOIN followed by an identifier) and
  * surface those tables' schema columns. Token-driven, so it survives the mis-parse; gated by config
- * token sets, so the core stays dialect-neutral.
+ * token sets, so the core stays dialect-neutral. A `{{ ref('orders') }}` FROM source blanks to a
+ * placeholder identifier, so that name token is resolved through the template provider first (see
+ * `columnsForName`), then the same schema lookup a plain table gets.
  */
-function fromRelationColumns(m, cfg, schema, dialect) {
+function fromRelationColumns(walkTokens, cfg, schema, dialect, tags, text) {
     if (cfg.relationKeywordTokens.size === 0)
         return [];
-    // Default-channel tokens only — hidden whitespace/comments sit between FROM and the name.
-    const toks = m.tokenStream.getTokens().filter((t) => t.channel === Token.DEFAULT_CHANNEL);
+    // Default-channel tokens only: hidden whitespace/comments sit between FROM and the name.
+    const toks = walkTokens.filter((t) => t.channel === Token.DEFAULT_CHANNEL);
     const out = [];
+    const emit = (cols) => {
+        if (cols)
+            for (const c of cols)
+                out.push({ label: c.name, kind: "column", detail: c.type });
+    };
     for (let i = 0; i + 1 < toks.length; i++) {
-        const t = toks[i];
-        const n = toks[i + 1];
-        if (!t || !n)
+        const kw = toks[i];
+        const next = toks[i + 1];
+        if (!kw || !next)
             continue;
-        if (!cfg.relationKeywordTokens.has(t.type))
+        if (!cfg.relationKeywordTokens.has(kw.type))
             continue;
-        if (!cfg.nameTokens.has(n.type))
+        // A templated source ({{ ref('orders') }}) blanks to a channel-2 tag the walk skips, so it sits
+        // in the gap between the relation keyword and the next SQL token (the alias, or the next clause).
+        // Resolve it through the provider: relationOf(call) -> name, then its columns come from the
+        // relation answer or the same schema.columnsFor a plain table gets. A plain schema / the neutral
+        // provider resolves nothing for it, so it contributes no fabricated columns.
+        const tag = tags?.find((t) => t.kind === "call" && t.tagSpan.start >= kw.start && t.tagSpan.start < next.start);
+        if (tag && schema instanceof DefaultTemplateProvider) {
+            const rel = schema.relationOf(callOf(tag, text));
+            emit(rel ? (rel.columns ?? schema.columnsFor(rel.nameParts, dialect)) : undefined);
             continue;
-        const cols = schema.columnsFor([n.text ?? ""], dialect);
-        if (!cols)
-            continue;
-        for (const c of cols)
-            out.push({ label: c.name, kind: "column", detail: c.type });
+        }
+        // Plain table: the next SQL token is the relation name.
+        if (cfg.nameTokens.has(next.type))
+            emit(schema.columnsFor([next.text ?? ""], dialect));
     }
     return out;
 }
@@ -164,16 +219,17 @@ function visibleColumns(scopes, ast, dialect, offset, schema) {
     const scope = enclosingScope(scopes, ast, offset);
     if (!scope)
         return [];
+    const behavior = resolveBehavior(dialect);
     const out = [];
     const seen = new Set();
     for (const src of scope.sources.values()) {
         for (const col of columnsOf(src, dialect, schema)) {
             // Dedup by folded IDENTITY (quoted/unquoted twins collapse); labels render via displayName.
-            const key = foldIdentifier(col.label, dialect);
+            const key = behavior.fold(col.label);
             if (seen.has(key))
                 continue;
             seen.add(key);
-            out.push({ ...col, label: displayName(col.label, dialect) });
+            out.push({ ...col, label: behavior.displayName(col.label) });
         }
     }
     return out;

package/dist/completion/jinja-slot.d.ts

@@ -0,0 +1,24 @@
+import type { TagNode } from "../minijinja/tag-ast.js";
+/** Where the caret sits inside a jinja call tag. NEUTRAL, the callee is a bare string; the dbt
+ *  meaning of the slot (ref arg0 = a model) is the consumer's to apply. */
+export interface JinjaSlot {
+    /** The callee name, e.g. `"ref"`, `"source"`, `"my_macro"`. */
+    callee: string;
+    /** Dotted package before the callee (`dbt_utils` in `dbt_utils.star(...)`). */
+    packageName?: string;
+    /** 0-based index of the positional arg the caret is in. The callee-name slot (caret still in the
+     *  callee identifier, `{{ my_mac|`) is `-1`. */
+    argIndex: number;
+    /** The already-typed text of this slot up to the caret, quote-stripped, the prefix a consumer
+     *  filters its candidates by. Empty when the slot is untyped (`{{ ref(|`). */
+    prefix: string;
+    /** True when the slot is unclosed / mid-typing (an `incomplete` call node, or a bare callee with no
+     *  open paren yet). */
+    incomplete: boolean;
+}
+/**
+ * The jinja completion slot at `offset`, or undefined when the caret is not in a completable jinja
+ * position. `tags` is `parseTemplated(...).tags` (or `doc.templated.tags`); `text` is the document
+ * source. Reuses the already-computed tags; never re-parses.
+ */
+export declare function jinjaSlotAt(tags: readonly TagNode[], text: string, offset: number): JinjaSlot | undefined;

package/dist/completion/jinja-slot.js

@@ -0,0 +1,126 @@
+// ---------------------------------------------------------------------------
+// jinjaSlotAt(), where the caret sits inside a jinja tag, for completion.
+//
+// The NEUTRAL half of jinja completion (anvil REQ1/REQ2): given the templated
+// document's tags + the caret offset, it says which call the caret is in and which
+// arg slot, `{{ ref('cu| }}` -> { callee: "ref", argIndex: 0, prefix: "cu" }. It
+// carries NO dbt vocabulary: it does not know that `ref`'s arg 0 is a model. A
+// consumer (a DbtTemplateProvider / the host) maps callee + argIndex to a role (ref
+// arg0 -> a model name) and supplies the candidates, exactly the way the SQL side
+// maps a grammar slot to a schema lookup.
+//
+// It finds the INNERMOST call covering the caret across every tag's call list, so a
+// nested `outer(inner(|))` reports `inner`, and a call embedded in a control tag
+// (`{% if is_incremental(| %}`) is found at all, not just a top-level `{{ call() }}`.
+// A caret on a bare leading identifier with no open paren yet (`{{ re`, still typing
+// the callee) is a callee-name slot too, read straight off the text.
+//
+// Reuses the parse: it reads the tags the document already produced, never re-parses.
+// Total: returns undefined off any jinja completion slot; never throws.
+// ---------------------------------------------------------------------------
+/**
+ * The jinja completion slot at `offset`, or undefined when the caret is not in a completable jinja
+ * position. `tags` is `parseTemplated(...).tags` (or `doc.templated.tags`); `text` is the document
+ * source. Reuses the already-computed tags; never re-parses.
+ */
+export function jinjaSlotAt(tags, text, offset) {
+    const hit = innermostCallAt(tags, offset);
+    if (hit)
+        return slotFromCall(hit, text, offset);
+    // No call covers the caret: a bare leading identifier being typed is still a callee-name slot.
+    return bareCalleeSlot(tags, text, offset);
+}
+/** The innermost call covering `offset`: the top-level call node of a `{{ call() }}` tag, plus every
+ *  nested call (`calls[1..]`) and every call embedded in a `{% … %}` control tag (`calls[]`). The
+ *  smallest covering extent wins, so `inner` beats `outer` and a control-tag call is reachable. */
+function innermostCallAt(tags, offset) {
+    let best;
+    const consider = (h) => {
+        if (offset < h.start || offset > h.end)
+            return;
+        if (!best || h.end - h.start < best.end - best.start)
+            best = h;
+    };
+    for (const t of tags) {
+        if (t.kind === "call") {
+            // The node's own top-level call carries the `incomplete` flag; its tag span is the extent so a
+            // caret in the tag's leading whitespace still resolves to it. `calls[0]` duplicates this
+            // top-level, so nested calls are `calls[1..]`.
+            consider({
+                name: t.name,
+                nameSpan: t.nameSpan,
+                ...(t.packageName !== undefined ? { packageName: t.packageName } : {}),
+                ...(t.argsSpan ? { argsSpan: t.argsSpan } : {}),
+                args: t.args,
+                incomplete: t.incomplete === true,
+                start: t.tagSpan.start,
+                end: t.tagSpan.end,
+            });
+            for (const c of t.calls.slice(1))
+                consider(macroHit(c));
+        }
+        else if (t.kind === "control") {
+            for (const c of t.calls)
+                consider(macroHit(c));
+        }
+    }
+    return best;
+}
+/** A nested / control-embedded MacroCall as a CallHit: its extent is the callee (with any package)
+ *  through the close paren, so it is tighter than the enclosing tag and wins the innermost pick. */
+function macroHit(c) {
+    return {
+        name: c.name,
+        nameSpan: c.nameSpan,
+        ...(c.packageName !== undefined ? { packageName: c.packageName } : {}),
+        ...(c.argsSpan ? { argsSpan: c.argsSpan } : {}),
+        args: c.args,
+        incomplete: false,
+        start: c.packageSpan?.start ?? c.nameSpan.start,
+        end: c.argsSpan?.end ?? c.nameSpan.end,
+    };
+}
+/** The slot for a caret inside a resolved call: the callee name, or the positional argument. */
+function slotFromCall(c, text, offset) {
+    const base = { callee: c.name, ...(c.packageName !== undefined ? { packageName: c.packageName } : {}) };
+    // Callee-name slot: the caret is still within (or right at the end of) the callee identifier,
+    // before the open paren, the user is typing the macro name itself.
+    if (offset <= c.nameSpan.end) {
+        return { ...base, argIndex: -1, prefix: text.slice(c.nameSpan.start, offset), incomplete: c.incomplete };
+    }
+    // Between the name and the open paren (e.g. whitespace) is no completable slot.
+    const parenStart = c.argsSpan?.start ?? Number.MAX_SAFE_INTEGER;
+    if (offset < parenStart)
+        return undefined;
+    // Inside the arguments. The arg whose span covers the caret; else the caret sits in a gap (after
+    // the open paren or a comma), so the slot is the next arg being typed = the count of args that
+    // already ended before the caret.
+    const inArg = c.args.findIndex((a) => offset >= a.span.start && offset <= a.span.end);
+    if (inArg >= 0) {
+        return { ...base, argIndex: inArg, prefix: stripQuote(text.slice(c.args[inArg].span.start, offset)), incomplete: c.incomplete };
+    }
+    const argIndex = c.args.filter((a) => a.span.end <= offset).length;
+    return { ...base, argIndex, prefix: "", incomplete: c.incomplete };
+}
+/** A bare leading identifier being typed in a `{{ }}` expression (`{{ re`, `{{ region`) as a
+ *  callee-name slot. The `other` tag drops the identifier, so read it off the text: only an
+ *  expression tag (opens `{{`), and only when the caret sits on a single leading identifier (nothing
+ *  but whitespace before it, no member access or operators). So a callee being typed toward a call
+ *  and a bare variable both offer the host's callee candidates, filtered by the prefix. */
+function bareCalleeSlot(tags, text, offset) {
+    const tag = tags.find((t) => t.kind === "other" && offset > t.tagSpan.start && offset <= t.tagSpan.end);
+    if (!tag)
+        return undefined;
+    if (text.slice(tag.tagSpan.start, tag.tagSpan.start + 2) !== "{{")
+        return undefined;
+    const before = text.slice(tag.tagSpan.start + 2, offset);
+    const m = /^\s*([A-Za-z_]\w*)$/.exec(before);
+    if (!m)
+        return undefined;
+    return { callee: m[1], argIndex: -1, prefix: m[1], incomplete: true };
+}
+/** Drop a single leading quote from a partial string arg (`'cu` -> `cu`) so the prefix is the value
+ *  the consumer filters by. Leaves a non-string arg untouched. */
+function stripQuote(raw) {
+    return raw.replace(/^['"]/, "");
+}

package/dist/completion/parser-factory.d.ts

@@ -1,4 +1,4 @@
-import { CommonTokenStream, type Lexer, type Parser, type ParserRuleContext } from "antlr4ng";
+import { type ATN, CommonTokenStream, type Lexer, type Parser, type ParserRuleContext, type Vocabulary } from "antlr4ng";
 import type { Dialect } from "../dialect.js";
 /**
  * A ready-to-walk parser for the completion engine: the lexer, the token stream, the entry
@@ -21,3 +21,15 @@ export interface MadeParser {
 }
 /** Build a fresh error-tolerant parser for `dialect`, lexing `sql`. */
 export declare function makeParser(sql: string, dialect: Dialect): MadeParser;
+/** The input-INDEPENDENT parser facts the ATN candidate walk needs: the dialect's parser ATN, the
+ *  lexer vocabulary (for keyword literal labels), and the batch entry rule's index. All three are
+ *  per-dialect statics (the ATN and vocabulary are shared across every parser/lexer instance), so
+ *  they are grabbed once from a throwaway empty-input factory and reused; no source is re-lexed. */
+export interface CompletionMeta {
+    atn: ATN;
+    vocabulary: Vocabulary;
+    entryRuleIndex: number;
+}
+/** The cached {@link CompletionMeta} for `dialect`, built once. Completion drives the walk over the
+ *  document's own token stream plus this meta, instead of re-parsing the source text. */
+export declare function completionMeta(dialect: Dialect): CompletionMeta;

package/dist/completion/parser-factory.js

@@ -191,3 +191,15 @@ const FACTORIES = {
 export function makeParser(sql, dialect) {
     return FACTORIES[dialect](sql);
 }
+const META_CACHE = new Map();
+/** The cached {@link CompletionMeta} for `dialect`, built once. Completion drives the walk over the
+ *  document's own token stream plus this meta, instead of re-parsing the source text. */
+export function completionMeta(dialect) {
+    let meta = META_CACHE.get(dialect);
+    if (!meta) {
+        const m = makeParser("", dialect);
+        meta = { atn: m.parser.atn, vocabulary: m.lexer.vocabulary, entryRuleIndex: m.entryRuleIndex };
+        META_CACHE.set(dialect, meta);
+    }
+    return meta;
+}

package/dist/databricks/behavior.d.ts

@@ -0,0 +1,2 @@
+import type { DialectBehavior } from "../dialect-behavior/behavior.js";
+export declare const databricksBehavior: DialectBehavior;

package/dist/databricks/behavior.js

@@ -0,0 +1,19 @@
+import { acceptsFor } from "../dialect-behavior/coerce-rules.js";
+import { likePatternToRegExp } from "../scope/like-pattern.js";
+import { SIGNATURES } from "../signature/signatures.js";
+import { displayName, fold, foldTableName, matchesSourceKey } from "./fold.js";
+import { databricksLiteral, databricksParseType, DATABRICKS_FUNCTION_RETURNS } from "./infer.js";
+export const databricksBehavior = {
+    fold,
+    displayName,
+    foldTableName,
+    matchesSourceKey,
+    likeMatch: (pattern, value) => likePatternToRegExp(pattern).test(value),
+    literal: databricksLiteral,
+    parseType: databricksParseType,
+    functions: DATABRICKS_FUNCTION_RETURNS,
+    division: "float",
+    signatures: SIGNATURES.databricks,
+    // Databricks implicit coercion: STRING containing a number coerces to numeric (STR_TO_NUM=true), no bool<->num (BOOL_NUM=false).
+    accepts: (argType, paramText) => acceptsFor(databricksParseType, true, false, argType, paramText),
+};

package/dist/databricks/fold.d.ts

@@ -0,0 +1,8 @@
+import { type FoldRule, type IdentKind } from "../ident/fold.js";
+export declare const DATABRICKS_FOLD_RULE: FoldRule;
+/** Fold an identifier to its Databricks identity key. */
+export declare function fold(raw: string, kind?: IdentKind): string;
+/** Presentation twin: strip delimiters, no case change. */
+export declare function displayName(raw: string): string;
+export declare function foldTableName(parts: string[]): string[];
+export declare function matchesSourceKey(key: string, rawPart: string): boolean;

package/dist/databricks/fold.js

@@ -0,0 +1,27 @@
+// Databricks identifier folding. The FoldRule plus its bound engine, colocated here because BOTH the
+// upstream lower() and the downstream DialectBehavior need it (the fold rule is the one dialect concern
+// used at two stages).
+// docs.databricks.com/en/sql/language-manual/sql-ref-identifiers.html — verified live:
+// "Identifiers are case-insensitive when referenced." Backtick escaping is doubling, not
+// case-quoting: "Use ` to escape ` itself" (example: `` `a``b` `` → `` a`b ``).
+import { displayWith, foldWith } from "../ident/fold.js";
+const BACKTICK = ["`", "`"];
+export const DATABRICKS_FOLD_RULE = {
+    delimiters: [BACKTICK],
+    unquoted: "lower",
+    quoted: "lower",
+};
+/** Fold an identifier to its Databricks identity key. */
+export function fold(raw, kind = "other") {
+    return foldWith(DATABRICKS_FOLD_RULE, raw, kind);
+}
+/** Presentation twin: strip delimiters, no case change. */
+export function displayName(raw) {
+    return displayWith(DATABRICKS_FOLD_RULE, raw);
+}
+export function foldTableName(parts) {
+    return parts.map((p) => fold(p, "table"));
+}
+export function matchesSourceKey(key, rawPart) {
+    return key === fold(rawPart) || key === fold(rawPart, "table");
+}

package/dist/databricks/index.d.ts

@@ -0,0 +1,7 @@
+import { lower } from "./lower.js";
+import { parseDatabricks } from "./parse.js";
+export declare const databricks: {
+    parse: typeof parseDatabricks;
+    lower: typeof lower;
+    behavior: import("../dialect-behavior/behavior.js").DialectBehavior;
+};

package/dist/databricks/index.js

@@ -0,0 +1,10 @@
+// The complete databricks dialect module: parse + lower (front end) and behavior (semantic knowledge).
+// The registry wires this; to understand everything sqllens does for databricks, read this folder.
+import { databricksBehavior } from "./behavior.js";
+import { lower } from "./lower.js";
+import { parseDatabricks } from "./parse.js";
+export const databricks = {
+    parse: parseDatabricks,
+    lower,
+    behavior: databricksBehavior,
+};

package/dist/databricks/infer.d.ts

@@ -0,0 +1,6 @@
+import { type FnRule } from "../infer/functions.js";
+import { type Type } from "../infer/types.js";
+export declare const DATABRICKS_FUNCTION_RETURNS: Record<string, FnRule>;
+/** Databricks/Spark literal forms. */
+export declare function databricksLiteral(text: string): Type;
+export declare function databricksParseType(text: string): Type;