sqllens 1.1.0 → 1.2.0

package/dist/minijinja/apply-tags.js

@@ -1,32 +1,29 @@
 // ---------------------------------------------------------------------------
-// R3 — templated ref/source as first-class TableSource nodes (inc2).
+// R3: a templated call in a FROM slot as a first-class TableSource node (inc2).
 //
-// `{{ ref('x') }}` / `{{ source('a','b') }}` in a FROM/JOIN slot lowers, via the
-// placeholder mechanism, to an ordinary `TableSource` whose `name` is the raw
-// placeholder identifier (PLACEHOLDER_CHAR-filled runs like `jjj…` from segment.ts).
-// This POST-LOWER transform rewrites those sources so `name` carries the dbt-logical
-// model/source names, and attaches a `template` marker — so scope/qualify/lineage
-// see the model, not the placeholder (scope binds a TableSource purely by `name`,
-// so the whole downstream pipeline works UNCHANGED).
+// `{{ ref('x') }}` / `{{ source('a','b') }}` / a macro call in a FROM/JOIN slot lowers, via the
+// placeholder mechanism, to an ordinary `TableSource` whose `name` is the raw placeholder identifier
+// (PLACEHOLDER_CHAR-filled runs like `jjj…` from segment.ts). This POST-LOWER transform rewrites those
+// sources so `name` carries the provider-resolved relation name and attaches a `template` marker, so
+// scope/qualify/lineage see the relation, not the placeholder (scope binds a TableSource purely by
+// `name`, so the whole downstream pipeline works UNCHANGED).
 //
-// Correlation is by CONTAINMENT, not equality: a `TableSource` correlates with a
-// tag when the char offset of its FIRST NAME TOKEN (`cst.start.start`) lies inside
-// the tag's `tagSpan` [start, end). Containment (not equality) because a multi-line
-// expr tag fills ONE placeholder identifier per line — the name token covers only
-// the first line, but its offset still sits inside the whole-tag span.
+// Correlation is by CONTAINMENT, not equality: a `TableSource` correlates with a tag when the char
+// offset of its FIRST NAME TOKEN (`cst.start.start`) lies inside the tag's `tagSpan` [start, end).
+// Containment (not equality) because a multi-line expr tag fills ONE placeholder identifier per line,
+// so the name token covers only the first line but its offset still sits inside the whole-tag span.
 //
-// Substitution is LITERAL-ONLY (never-wrong): inc1's `directStringToken` guard
-// already guarantees a ref/source TagNode carries only literal names, so a `ref`
-// node's `model` and a `source` node's `sourceName`/`tableName` are real literals.
-// A macro (or computed) call in a FROM slot keeps its placeholder name and gets
-// `opaque: true` — its physical relation is undeterminable without the catalog;
-// we NEVER fabricate a name for it.
+// The tag AST is NEUTRAL (a call is a call), and so is the naming: this transform asks the
+// TemplateProvider for a call's relation (`provider.relationOf`) and carries no ref/source vocabulary
+// itself. The NEUTRAL provider answers nothing, so a bare parse leaves calls opaque; a
+// DbtTemplateProvider names ref/source. Naming is never-wrong: a resolved name comes from the call's
+// literal args, and a call whose relation the provider does not resolve keeps its placeholder name and
+// stays opaque. We NEVER fabricate a name.
 //
-// The IR is frozen after lower(); this transform REBUILDS with STRUCTURAL SHARING
-// (new objects only on changed paths — an unchanged subtree keeps its original,
-// already-frozen reference) and re-freezes the rebuilt tree. It NEVER mutates a
-// frozen node. Total: never throws — on any internal surprise it returns the input
-// `ast` unchanged.
+// The IR is frozen after lower(); this transform REBUILDS with STRUCTURAL SHARING (new objects only on
+// changed paths, an unchanged subtree keeps its original already-frozen reference) and re-freezes the
+// rebuilt tree. It NEVER mutates a frozen node. Total: never throws, on any internal surprise it
+// returns the input `ast` unchanged.
 // ---------------------------------------------------------------------------
 import { freezeIR } from "../ir/freeze.js";
 /** Record a freshly built node's correlation to the tag it came from, then return it unchanged
@@ -43,27 +40,23 @@ function attach(ctx, node, tag) {
     return node;
 }
 /**
- * Rewrite templated FROM/JOIN sources in `ast` to carry their dbt-logical name +
- * a `template` marker, correlating each source to a tag by span 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.
+ * Rewrite templated FROM/JOIN sources in `ast` to carry their provider-resolved name (when the
+ * provider resolves the call) plus a `template` marker, correlating each source to a tag by span
+ * 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.
  */
-export function applyTemplateTags(ast, tags, text) {
+export function applyTemplateTags(ast, tags, text, provider) {
     const byNode = new WeakMap();
     const byTag = new Map();
     try {
-        // config is a no-output tag (whitespace-filled) — it can never yield a table
-        // source, so it stays out of the correlation set even though ExprTag admits it.
-        const relTags = tags.filter((t) => t.kind === "ref" ||
-            t.kind === "source" ||
-            t.kind === "macro" ||
-            t.kind === "var" ||
-            t.kind === "env_var" ||
-            t.kind === "other");
+        // 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 };
-        const ctx = { relTags, sets: resolveSets(tags, text), text, byNode, byTag };
+        const ctx = { relTags, sets: resolveSets(tags, text, provider), text, provider, byNode, byTag };
         const next = transformQuery(ast, ctx);
         // Scalar-slot marking: every column-shaped node whose token is a tag's placeholder
         // fill gets a `template` marker (span + provider key), so inference resolves it
@@ -79,23 +72,12 @@ export function applyTemplateTags(ast, tags, text) {
  *  its provider key — ref/source from their literal names, macro from its call fields,
  *  var/env_var lexically, a bare set-bound variable from its RHS call. */
 function exprInfoOf(tag, ctx) {
-    if (tag.kind === "ref")
-        return { span: tag.tagSpan, call: { name: "ref", args: [tag.model] } };
-    if (tag.kind === "source") {
-        return { span: tag.tagSpan, call: { name: "source", args: [tag.sourceName, tag.tableName] } };
-    }
-    if (tag.kind === "macro")
+    // 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) };
-    if (tag.kind === "var" || tag.kind === "env_var") {
-        const m = VALUE_CALL_TAG.exec(sliceSpan(ctx.text, tag.tagSpan));
-        if (m) {
-            const args = [m[3]];
-            if (m[4] !== undefined)
-                args.push(null); // further args present but not extracted — computed
-            return { span: tag.tagSpan, call: { name: m[1], args } };
-        }
-        return { span: tag.tagSpan };
-    }
+    // 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)
@@ -175,14 +157,6 @@ const LITERAL_ARG = /^(['"])([^'"\\]*)\1$/;
 function sliceSpan(text, span) {
     return text.slice(span.start, span.end);
 }
-/** The literal string value of a MacroCall argument, or undefined when computed. */
-function literalArg(text, call, i) {
-    const arg = call.args[i];
-    if (!arg)
-        return undefined;
-    const m = LITERAL_ARG.exec(sliceSpan(text, arg.span).trim());
-    return m ? m[2] : undefined;
-}
 /** A kwarg's raw text split: `name = rest`, with `rest`'s literal (or null when computed). */
 const KWARG_RE = /^([A-Za-z_][A-Za-z0-9_]*)\s*=(?!=)([\s\S]*)$/;
 /**
@@ -190,7 +164,7 @@ const KWARG_RE = /^([A-Za-z_][A-Za-z0-9_]*)\s*=(?!=)([\s\S]*)$/;
  * carried separately (the channel-agreed TemplateCall contract: quote-stripped, escapes
  * NOT resolved, computed arguments null, kwargs never dropped).
  */
-function callOf(mc, text) {
+export function callOf(mc, text) {
     const args = [];
     const kwargs = [];
     for (const arg of mc.args) {
@@ -217,11 +191,11 @@ function callOf(mc, text) {
  * Requires the tag's call list to be exactly one call that IS the ENTIRE RHS: the
  * text between the declared name and the call is exactly `=`, and the text after
  * the call runs straight to the tag close (whitespace + optional `-%}`).
- * `ref('a') ~ '_x'` or `ref('a').identifier` therefore do not resolve. A literal
- * ref/source RHS resolves with its NAME (scope binds the real model); any other
- * single-call RHS resolves as a macro identity (the provider may know its relation).
+ * `ref('a') ~ '_x'` or `ref('a').identifier` therefore do not resolve. When the provider resolves the
+ * call's relation, the set carries that NAME (scope binds the real relation); otherwise it carries the
+ * call identity only, and the provider may still resolve its relation at the use site.
  */
-function setResolution(tag, text) {
+function setResolution(tag, text, provider) {
     if (tag.calls.length !== 1 || !tag.nameSpan)
         return undefined;
     const call = tag.calls[0];
@@ -234,19 +208,11 @@ function setResolution(tag, text) {
     if (!/^\s*-?%\}$/.test(text.slice(callEnd, tag.tagSpan.end)))
         return undefined;
     const tCall = callOf(call, text);
-    if (call.packageName === undefined && call.name === "ref" && call.args.length === 1) {
-        const model = literalArg(text, call, 0);
-        return model !== undefined ? { kind: "ref", name: [model], call: tCall } : undefined;
-    }
-    if (call.packageName === undefined && call.name === "source" && call.args.length === 2) {
-        const src = literalArg(text, call, 0);
-        const tbl = literalArg(text, call, 1);
-        return src !== undefined && tbl !== undefined ? { kind: "source", name: [src, tbl], call: tCall } : undefined;
-    }
-    return { kind: "macro", call: tCall };
+    const rel = provider.relationOf(tCall);
+    return rel ? { name: [...rel.nameParts], call: tCall } : { call: tCall };
 }
 /** The template-wide map of resolvable set variables (empty when any guard trips globally). */
-function resolveSets(tags, text) {
+function resolveSets(tags, text, provider) {
     const empty = new Map();
     const controls = tags.filter((t) => t.kind === "control");
     if (controls.some((c) => c.keyword === "macro"))
@@ -258,7 +224,7 @@ function resolveSets(tags, text) {
         if (c.keyword !== "set" || !c.name)
             continue;
         counts.set(c.name, (counts.get(c.name) ?? 0) + 1);
-        const r = setResolution(c, text);
+        const r = setResolution(c, text, provider);
         if (r)
             out.set(c.name, r);
     }
@@ -433,51 +399,30 @@ function transformTableSource(src, ctx) {
     const aliasTok = src.aliasCst?.start;
     const base = aliasTok != null && inSpan(aliasTok.start, tag.tagSpan) ? withoutAlias(src) : src;
     // NOTE: `template.span` intentionally aliases `tag.tagSpan` BY REFERENCE. freezeIR
-    // therefore also freezes the TagNode.tagSpan object returned in `.tags` — benign,
-    // since spans are read-only. Every marker with a resolvable identity carries its
-    // `call` — the provider key the semantic layer consults (relation-columns.ts).
-    if (tag.kind === "ref") {
-        const call = { name: "ref", args: [tag.model] };
-        const template = { kind: "ref", span: tag.tagSpan, call };
-        return attach(ctx, { ...base, name: [tag.model], template }, tag);
-    }
-    if (tag.kind === "source") {
-        const call = { name: "source", args: [tag.sourceName, tag.tableName] };
-        const template = { kind: "source", span: tag.tagSpan, call };
-        return attach(ctx, { ...base, name: [tag.sourceName, tag.tableName], template }, tag);
+    // 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).
+    if (tag.kind === "call") {
+        const call = callOf(tag, ctx.text);
+        const rel = ctx.provider.relationOf(call);
+        // A call in a FROM slot (ref/source/a TVF-like macro). When the provider resolves its
+        // relation, carry the resolved name; otherwise keep the placeholder name (never fabricated).
+        // 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 ? { ...base, name: [...rel.nameParts] } : base;
+        const template = { kind: "call", span: tag.tagSpan, call };
+        return attach(ctx, { ...named, template }, tag);
     }
-    if (tag.kind === "macro") {
-        // A macro in a FROM slot keeps the placeholder name (never fabricated) but is no
-        // longer a dead end: its `call` lets a provider resolve the relation it produces
-        // (a TVF-like macro). Without a provider answer it behaves exactly like the old
-        // opaque marker (exemption, no diagnostics).
-        const template = { kind: "macro", span: tag.tagSpan, call: callOf(tag, ctx.text) };
-        return attach(ctx, { ...base, template }, tag);
-    }
-    // Non-call expression tag (var / env_var / other) in a FROM slot. A bare `{{ t }}`
-    // resolving through a `{% set t = … %}` single-call RHS binds the real model
-    // (ref/source) or carries the call identity (macro); everything else gets the opaque
-    // "expr" marker — either way the placeholder name stops posing as a real table.
+    // Non-call expression tag (var / env_var / other) in a FROM slot. A bare `{{ t }}` resolving
+    // through a `{% set t = … %}` single-call RHS carries the resolved relation name (when the
+    // provider resolved it) or the call identity alone; every other case gets the opaque "expr"
+    // marker, so the placeholder name stops posing as a real table.
     const ident = tag.kind === "other" ? bareIdentOf(tag, ctx.text) : undefined;
     const resolved = ident !== undefined ? ctx.sets.get(ident) : undefined;
-    if (resolved && resolved.kind !== "macro") {
-        const template = {
-            kind: resolved.kind,
-            span: tag.tagSpan,
-            indirect: true,
-            call: resolved.call,
-        };
-        return attach(ctx, { ...base, name: [...resolved.name], template }, tag);
-    }
     if (resolved) {
-        // set-var bound to a non-ref/source call: macro semantics at the use site.
-        const template = {
-            kind: "macro",
-            span: tag.tagSpan,
-            indirect: true,
-            call: resolved.call,
-        };
-        return attach(ctx, { ...base, template }, tag);
+        const named = resolved.name ? { ...base, name: [...resolved.name] } : base;
+        const template = { kind: "call", span: tag.tagSpan, indirect: true, call: resolved.call };
+        return attach(ctx, { ...named, template }, tag);
     }
     const template = { kind: "expr", span: tag.tagSpan, opaque: true };
     return attach(ctx, { ...base, template }, tag);

package/dist/minijinja/parse.js

@@ -282,7 +282,7 @@ function build(text, dialect, provider) {
             jinjaTokens.push(mapSliceToken(tok));
         }
         const { tree, diagnostics } = parseSliceTag(slice);
-        const tag = tagNodesOf(seg, tree);
+        const tag = tagNodesOf(seg, tree, slice);
         if (tag) {
             tags.push(tag);
             segToTag.set(seg, tag);
@@ -292,12 +292,12 @@ function build(text, dialect, provider) {
         jinjaDiagnostics.push(...diagnostics);
     }
     // Step 5b (R3): rewrite templated FROM/JOIN sources onto first-class TableSource
-    // nodes carrying the dbt-logical model/source name + a `template` marker, so
-    // scope/qualify/lineage bind the real model rather than the `jjj…` placeholder.
+    // nodes carrying the provider-resolved relation name and a `template` marker, so
+    // scope/qualify/lineage bind the real relation rather than the `jjj…` placeholder.
     // Total (returns the input ast on any surprise); the reassignment stays inside
     // build()'s caller try/catch so parseTemplated's totality holds. `correlation`
-    // carries the Task 10 tag↔IR-node join collected while rebuilding.
-    const correlation = applyTemplateTags(sql.ast, tags, text);
+    // carries the Task 10 tag to IR-node join collected while rebuilding.
+    const correlation = applyTemplateTags(sql.ast, tags, text, provider);
     const sqlResult = { ...sql, ast: correlation.ast };
     // Step 4c: merge into one source-ordered stream. SQL and jinja token spans are
     // disjoint (tag-contained SQL tokens were dropped), so a stable sort by start

package/dist/minijinja/tag-ast.d.ts

@@ -1,14 +1,27 @@
-import { ParserRuleContext } from "antlr4ng";
-import { CallExprContext } from "../generated/minijinja/MinijinjaParser.js";
+import { ParserRuleContext, Token as AntlrToken } from "antlr4ng";
 import type { PartSpan } from "../ir/part-span.js";
 import { type Segment } from "./segment.js";
 /** A tag segment (the `kind: "tag"` arm of Segment). */
 type TagSegment = Extract<Segment, {
     kind: "tag";
 }>;
+/**
+ * One argument of a call, in the same spirit as a SQL function-call's args. `span` is the WHOLE
+ * argument (quote-included: `'orders'`, or `model='orders'` for a kwarg). `value` is the literal
+ * value quote-stripped (`orders`), or `null` for a computed arg (`ref(var('x'))`, `'a' ~ b`), never
+ * fabricated. `valueSpan` is the quote-EXCLUDED span of that literal value (covers `orders`, not
+ * `'orders'`), present only when there's a literal value. So a consumer that knows a call's arg roles
+ * (e.g. dbt: `ref`'s model is the last arg) reads the value + valueSpan straight off here, exactly
+ * how the old `ref.model`/`modelSpan` read.
+ */
+export interface TagArg {
+    value: string | null;
+    span: PartSpan;
+    valueSpan?: PartSpan;
+}
 /**
  * The reusable call fields the extension consumes for signature-help / hover — the
- * macro TagNode's fields minus `kind`/`tagSpan`. A `{{ }}` macro node IS a
+ * call TagNode's fields minus `kind`/`tagSpan`. A `{{ }}` call node IS a
  * MacroCall + kind/tagSpan; a `{% %}` control tag carries an array of them
  * (`calls`). Every field comes only from real identifier tokens (never-wrong): a
  * computed / dynamic callee yields no MacroCall.
@@ -19,9 +32,7 @@ export interface MacroCall {
     packageName?: string;
     packageSpan?: PartSpan;
     argsSpan?: PartSpan;
-    args: {
-        span: PartSpan;
-    }[];
+    args: TagArg[];
 }
 /**
  * R2 tag-AST node. The ref/source/macro arms carry the span contract the
@@ -30,31 +41,16 @@ export interface MacroCall {
  * 0-based offsets — sqllens convention).
  */
 export type TagNode = {
-    kind: "ref";
-    model: string;
-    modelSpan: PartSpan;
-    callSpan: PartSpan;
-    tagSpan: PartSpan;
-} | {
-    kind: "source";
-    sourceName: string;
-    tableName: string;
-    sourceNameSpan: PartSpan;
-    tableNameSpan: PartSpan;
-    /** Span of the whole `source(…)` call — the sibling of `ref`'s `callSpan`; the extension hit-tests the bare `source` identifier / call on it. */
-    callSpan: PartSpan;
-    tagSpan: PartSpan;
-} | {
-    kind: "macro";
+    kind: "call";
     name: string;
     nameSpan: PartSpan;
     packageName?: string;
     packageSpan?: PartSpan;
+    /** The whole call `name(args)` (name/package through the close paren). */
+    callSpan: PartSpan;
     tagSpan: PartSpan;
     argsSpan?: PartSpan;
-    args: {
-        span: PartSpan;
-    }[];
+    args: TagArg[];
     /**
      * Every macro CALL in the expression, in source order, EACH as its own
      * MacroCall — symmetric to `control.calls` (C1). A NESTED `outer(inner())`
@@ -66,6 +62,12 @@ export type TagNode = {
      * uniformly for control AND macro nodes.
      */
     calls: MacroCall[];
+    /** Present (true) when the call is UNCLOSED / mid-typing (`{{ ref('cu`) and was recovered
+     *  from the raw tokens because the parser could not build a complete call node. Its args are
+     *  best-effort (a partial string arg has `value: null`); a consumer knows not to treat it as
+     *  a confirmed reference, and completion uses it to place the caret's arg slot. Absent on a
+     *  normally-parsed (closed) call. */
+    incomplete?: true;
 } | {
     kind: "control";
     tagSpan: PartSpan;
@@ -85,18 +87,9 @@ export type TagNode = {
      */
     calls: MacroCall[];
 } | {
-    kind: "var" | "env_var" | "config" | "other";
+    kind: "other";
     tagSpan: PartSpan;
 };
-/**
- * Extract a CallExprContext into the reusable MacroCall fields — name/nameSpan +
- * optional package via `decomposeCallee`, args[] + argsSpan via `argInfo`. Returns
- * undefined when the callee is not a real, locatable identifier (decomposeCallee
- * undefined, or no nameSpan): a computed / dynamic callee is skipped, never
- * fabricated (never-wrong). The `{{ }}` macro node and the `{% %}` control tag both
- * build from this, so a call surfaces identically wherever it appears.
- */
-export declare function callToMacroCall(call: CallExprContext): MacroCall | undefined;
 /**
  * Build the R2 tag-AST node for ONE tag. `seg` carries the tag's document range
  * (`seg.start`/`seg.end`, used for `tagSpan`'s offsets — its own line/column come
@@ -105,5 +98,5 @@ export declare function callToMacroCall(call: CallExprContext): MacroCall | unde
  * offset/anchor composition anywhere in this file). Returns undefined only for an
  * empty/degenerate tree (never throws).
  */
-export declare function tagNodesOf(seg: TagSegment, tree: ParserRuleContext): TagNode | undefined;
+export declare function tagNodesOf(seg: TagSegment, tree: ParserRuleContext, tokens?: readonly AntlrToken[]): TagNode | undefined;
 export {};