@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/lsp/postgres-catalog.js

@@ -0,0 +1,176 @@
+/**
+ * The Postgres catalogs the editor and the MCP tools read: the committed
+ * snapshots of the pinned servers (one per supported major), parsed once.
+ * No server is needed; the snapshots are what generation reads too.
+ *
+ * A name's availability is read straight off the snapshots: it is in a major
+ * when that major's snapshot lists it, so `since` and `until` here agree with
+ * the generated types' `@since` / `@until`.
+ */
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { parseCatalog } from "../spec/postgres-catalog.js";
+import { POSTGRES_LATEST_MAJOR, POSTGRES_MAJORS } from "../spec/postgres-pin.js";
+import { STORAGE_PARAMETER_TYPES } from "../postgres/overlays/storage.js";
+const SPEC = join(moduleSourceDir(import.meta.url), "..", "spec");
+let cached = null;
+/** Every supported major's catalog, or undefined when a snapshot cannot be read. */
+export function postgresCatalogs() {
+    if (cached)
+        return cached;
+    try {
+        const map = new Map();
+        for (const major of POSTGRES_MAJORS)
+            map.set(major, parseCatalog(readFileSync(join(SPEC, `postgres-catalog-${major}.snapshot.json`), "utf-8")));
+        cached = map;
+        return map;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const SECTIONS = ["types", "accessMethods", "functions", "keywords", "settings", "extensions", "storageParameters"];
+/** SQL spellings with no `pg_type` row of their own. */
+const SPELLINGS = {
+    int: "integer",
+    dec: "numeric",
+    decimal: "numeric",
+    float: "double precision",
+    serial: "integer",
+    bigserial: "bigint",
+    smallserial: "smallint",
+    serial4: "integer",
+    serial8: "bigint",
+    serial2: "smallint",
+};
+const unquote = (s) => (s.startsWith('"') ? s.slice(1, -1) : s);
+function rowsOf(section, catalog) {
+    switch (section) {
+        case "types": {
+            const out = [];
+            const have = new Set();
+            for (const t of catalog.types) {
+                if (t.kind === "p" || t.name.startsWith("_"))
+                    continue;
+                const sqlName = unquote(t.sqlName);
+                have.add(sqlName);
+                out.push({ key: sqlName, row: { sqlName, catalogName: t.name, kind: t.kind, category: t.category } });
+                if (t.name !== sqlName) {
+                    have.add(t.name);
+                    out.push({ key: t.name, row: { sqlName, catalogName: t.name, kind: t.kind, category: t.category, aliasOf: sqlName }, detail: `alias of ${sqlName}` });
+                }
+            }
+            for (const [alias, target] of Object.entries(SPELLINGS)) {
+                const base = out.find((o) => o.key === target)?.row;
+                if (base && !have.has(alias))
+                    out.push({ key: alias, row: { ...base, aliasOf: target }, detail: `alias of ${target}` });
+            }
+            return out;
+        }
+        case "accessMethods":
+            return catalog.accessMethods.map((a) => ({
+                key: a.name,
+                row: { name: a.name, type: a.type === "i" ? "index" : "table", properties: a.properties ?? [] },
+            }));
+        case "functions":
+            return catalog.functions.filter((f) => !f.internal).map((f) => ({ key: f.name, row: { name: f.name, kinds: f.kinds, overloads: f.overloads } }));
+        case "keywords":
+            return catalog.keywords.map((k) => ({ key: k.word, row: k }));
+        case "settings":
+            return catalog.settings.map((s) => ({ key: s.name, row: s }));
+        case "extensions":
+            return catalog.extensions.map((e) => ({ key: e.name, row: e }));
+        case "storageParameters": {
+            const by = new Map();
+            for (const [target, names] of Object.entries(catalog.storageParameters))
+                for (const n of names)
+                    by.set(n, [...(by.get(n) ?? []), target]);
+            return [...by].map(([name, targets]) => ({ key: name, row: { name, targets, type: STORAGE_PARAMETER_TYPES[name] } }));
+        }
+    }
+}
+const oldest = POSTGRES_MAJORS[0];
+/** `since`/`until` for the majors a name is in. */
+export function rangeOf(majors) {
+    const first = Math.min(...majors);
+    const last = Math.max(...majors);
+    return { ...(first > oldest ? { since: first } : {}), ...(last < POSTGRES_LATEST_MAJOR ? { until: last } : {}) };
+}
+/** "14 to 17", "16 and later" or "" when in every major. */
+export function describeRange(r) {
+    if (r.since !== undefined && r.until !== undefined)
+        return `Postgres ${r.since} to ${r.until}`;
+    if (r.since !== undefined)
+        return `Postgres ${r.since} and later`;
+    if (r.until !== undefined)
+        return `up to Postgres ${r.until}`;
+    return "";
+}
+const sections = new Map();
+/** A section across every major, one entry per name. */
+export function section(name) {
+    const hit = sections.get(name);
+    if (hit)
+        return hit;
+    const catalogs = postgresCatalogs();
+    if (!catalogs)
+        return undefined;
+    const map = new Map();
+    for (const major of POSTGRES_MAJORS) {
+        for (const { key, row, detail } of rowsOf(name, catalogs.get(major))) {
+            const e = map.get(key);
+            if (e) {
+                e.row = row;
+                e.majors.push(major);
+                if (detail)
+                    e.detail = detail;
+            }
+            else
+                map.set(key, { name: key, row, majors: [major], range: {}, ...(detail ? { detail } : {}) });
+        }
+    }
+    for (const e of map.values())
+        e.range = rangeOf(e.majors);
+    sections.set(name, map);
+    return map;
+}
+/** The entries of a section that exist at `major`. */
+export function entriesAt(name, major) {
+    const s = section(name);
+    return s ? [...s.values()].filter((e) => e.majors.includes(major)) : [];
+}
+/** The entry for `name` at `major`, matching case-insensitively for names Postgres folds. */
+export function entryAt(name, key, major) {
+    const s = section(name);
+    const e = s?.get(key) ?? s?.get(key.toLowerCase());
+    return e && e.majors.includes(major) ? e : undefined;
+}
+/** `postgresMajor` in the nearest `chant.config.*` above a file, when it names a supported one. */
+export function configuredMajor(fileName) {
+    let dir = dirname(resolve(fileName));
+    for (let i = 0; i < 12; i++) {
+        for (const name of ["chant.config.ts", "chant.config.json", "chant.config.mts", "chant.config.js", "chant.config.mjs"]) {
+            const file = join(dir, name);
+            if (!existsSync(file))
+                continue;
+            try {
+                const m = /["']?postgresMajor["']?\s*:\s*(\d+)/.exec(readFileSync(file, "utf-8"));
+                const major = m ? Number(m[1]) : undefined;
+                return major !== undefined && POSTGRES_MAJORS.includes(major) ? major : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const up = dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    return undefined;
+}
+/** The major a file is written for: the project's configured one, else the newest. */
+export function majorFor(fileName) {
+    return configuredMajor(fileName) ?? POSTGRES_LATEST_MAJOR;
+}

package/dist/lsp/postgres-template.js

@@ -0,0 +1,171 @@
+/**
+ * Finding where the cursor is inside a Postgres template, and what the SQL
+ * before it says should come next. Shares the template finder with the lint
+ * rules, so the editor and `chant lint` agree on which tags are Postgres's.
+ */
+import { ts } from "@intentius/chant/lint/typescript";
+import { isTrivia, tokenize } from "../postgres/tokens.js";
+import { parseStatements } from "../postgres/parser.js";
+import { POSTGRES_TEMPLATE_SOURCES, findPostgresTemplates } from "../lint/rules/postgres-templates.js";
+import { locateIn } from "../core/find-templates.js";
+/** The Postgres template the source offset `at` is inside, and where in it. */
+export function locatePostgres(content, at, fileName = "file.ts") {
+    return locateIn(content, at, POSTGRES_TEMPLATE_SOURCES, fileName);
+}
+/** Significant tokens of the template up to `offset` in `part`; undefined when the text before it does not tokenize. */
+export function postgresTokensBefore(found, part, offset) {
+    try {
+        const parts = [...found.parts.slice(0, part), found.parts[part].slice(0, offset)];
+        return tokenize(parts).filter((t) => !isTrivia(t));
+    }
+    catch {
+        return undefined;
+    }
+}
+const upper = (t) => (t?.kind === "ident" ? t.text.toUpperCase() : "");
+const isPunct = (t, text) => t?.kind === "punct" && t.text === text;
+const EXPRESSION_AFTER = new Set(["DEFAULT", "WHERE", "SELECT", "AND", "OR", "WHEN", "THEN", "ELSE", "HAVING", "BY", "ON", "NOT", "CHECK", "AS", "USING"]);
+const EXPRESSION_CONTEXT = new Set(["SELECT", "DEFAULT", "CHECK", "WHERE", "GENERATED", "HAVING"]);
+const NOT_A_COLUMN = new Set(["CONSTRAINT", "PRIMARY", "UNIQUE", "CHECK", "FOREIGN", "EXCLUDE", "LIKE"]);
+/** What the SQL before the cursor expects; undefined where a name of the user's own goes. */
+export function postgresExpectAfter(sig, tag) {
+    const last = sig[sig.length - 1];
+    if (!last)
+        return undefined;
+    const prev = sig[sig.length - 2];
+    if (tag === "extension" && (upper(last) === "EXTENSION" || upper(last) === "EXISTS"))
+        return "extension";
+    if (upper(last) === "USING") {
+        if (tag === "index" || upper(prev) === "EXCLUDE" || (prev === undefined ? false : sig.some((t) => upper(t) === "EXCLUDE")))
+            return "index-method";
+        return tag === "table" || tag === "view" ? "table-method" : undefined;
+    }
+    if (last.kind === "op" && last.text === "::")
+        return "type";
+    if ((tag === "domain" || tag === "sequence") && upper(last) === "AS")
+        return "type";
+    const open = [];
+    sig.forEach((t, i) => {
+        if (isPunct(t, "("))
+            open.push(i);
+        else if (isPunct(t, ")"))
+            open.pop();
+    });
+    const opener = open[open.length - 1];
+    const before = opener === undefined ? undefined : sig[opener - 1];
+    const afterOpenOrComma = isPunct(last, "(") || isPunct(last, ",");
+    if (afterOpenOrComma && opener !== undefined && upper(before) === "WITH")
+        return "storage-parameter";
+    // A table's column list: a name goes first, then a type.
+    const columnList = tag === "table" && open.length === 1 && opener === sig.findIndex((t) => isPunct(t, "("));
+    if (columnList) {
+        if (afterOpenOrComma)
+            return undefined;
+        if ((last.kind === "ident" || last.kind === "qident") && (isPunct(prev, "(") || isPunct(prev, ",")) && !NOT_A_COLUMN.has(upper(last)))
+            return "type";
+    }
+    if (EXPRESSION_AFTER.has(upper(last)))
+        return "function";
+    if ((afterOpenOrComma || last.kind === "op") && sig.some((t) => EXPRESSION_CONTEXT.has(upper(t))))
+        return "function";
+    if (afterOpenOrComma && !columnList)
+        return undefined;
+    if (last.kind === "ident" || last.kind === "qident" || isPunct(last, ")"))
+        return "keyword";
+    return undefined;
+}
+/** The storage-parameter target a template's `WITH (...)` is for. */
+export function storageTarget(sig, tag) {
+    if (tag === "index") {
+        const i = sig.findIndex((t) => upper(t) === "USING");
+        const method = i >= 0 && sig[i + 1]?.kind === "ident" ? sig[i + 1].text.toLowerCase() : "btree";
+        return `index:${method}`;
+    }
+    if (tag === "view")
+        return sig.some((t) => upper(t) === "MATERIALIZED") ? "materialized view" : "view";
+    return "table";
+}
+function spanText(found, tokens, span, source) {
+    if (!span || span.to <= span.from)
+        return undefined;
+    return tokens
+        .slice(span.from, span.to)
+        .map((t) => (t.kind === "ref" ? `\${${found.expressions[t.part]?.getText(source) ?? "..."}}` : t.text))
+        .join("")
+        .trim();
+}
+/** Every `const x = table\`...\`` (and the other tags) in the content that parses, by const name. */
+export function postgresDeclarations(content, fileName = "file.ts") {
+    const source = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true);
+    const out = [];
+    for (const found of findPostgresTemplates(source)) {
+        const decl = found.node.parent;
+        if (!decl || !ts.isVariableDeclaration(decl) || !ts.isIdentifier(decl.name))
+            continue;
+        try {
+            const tokens = tokenize(found.parts);
+            const node = parseStatements(tokens)[0];
+            if (!node)
+                continue;
+            const text = (span) => spanText(found, tokens, span, source);
+            let sqlName;
+            let kind = found.tag;
+            let columns = [];
+            switch (node.statement) {
+                case "table":
+                    sqlName = text(node.name.span);
+                    columns = node.columns.map((c) => ({ name: c.name || text(c.nameSpan) || "", ...(text(c.type) ? { type: text(c.type) } : {}) }));
+                    break;
+                case "view":
+                    sqlName = text(node.name.span);
+                    kind = node.materialized ? "materialized view" : "view";
+                    columns = node.columnNames.map((c) => ({ name: c.name || text(c.span) || "" }));
+                    break;
+                case "enum":
+                    sqlName = text(node.name.span);
+                    kind = "enum type";
+                    break;
+                case "composite":
+                case "range":
+                    sqlName = text(node.name.span);
+                    kind = `${node.statement} type`;
+                    break;
+                case "aggregate":
+                case "collation":
+                    sqlName = text(node.name.span);
+                    kind = node.statement;
+                    break;
+                case "eventTrigger":
+                    sqlName = text(node.name.span);
+                    kind = "event trigger";
+                    break;
+                case "index":
+                    sqlName = node.name ? text(node.name.span) : undefined;
+                    break;
+                case "schema":
+                    sqlName = node.name ? text(node.name.span) : undefined;
+                    break;
+                case "sequence":
+                case "domain":
+                case "extension":
+                    sqlName = text(node.name.span);
+                    break;
+                case "function":
+                case "procedure":
+                case "trigger":
+                case "policy":
+                case "role":
+                    sqlName = text(node.name.span);
+                    kind = node.statement;
+                    break;
+                default:
+                    continue;
+            }
+            out.push({ name: decl.name.text, tag: found.tag, kind, sqlName: sqlName ?? decl.name.text, columns });
+        }
+        catch {
+            // A template that does not parse is SQLPG001's to report; it has nothing to offer.
+        }
+    }
+    return out;
+}

package/dist/lsp/postgres.js

@@ -0,0 +1,266 @@
+/**
+ * Completions and hover inside Postgres templates (chant #3283). Words come
+ * from the committed catalogs of the pinned servers, limited to what the
+ * project's major has (`sql.postgresMajor`, else the newest). `${` offers the
+ * objects declared in the file and `${t.columns.` their columns with types.
+ *
+ * Both entry points return undefined when the cursor is not in a Postgres
+ * template, so the ClickHouse provider (and the generic registry one) answer.
+ */
+import { existsSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { ts } from "@intentius/chant/lint/typescript";
+import { describeRange, entriesAt, entryAt, majorFor, } from "./postgres-catalog.js";
+import { locatePostgres, postgresDeclarations, postgresExpectAfter, postgresTokensBefore, storageTarget, } from "./postgres-template.js";
+import { offsetAt, wordAround } from "../core/find-templates.js";
+const LIMIT = 200;
+const KEYWORD_CATEGORY = { U: "unreserved", C: "column name", T: "type or function name", R: "reserved" };
+const fileName = (uri) => (uri.startsWith("file://") ? decodeURIComponent(uri.slice(7)) : uri) || "file.ts";
+const code = (s) => `\`${s}\``;
+const matches = (name, prefix) => prefix === "" || name.toLowerCase().startsWith(prefix.toLowerCase());
+const note = (e) => {
+    const r = describeRange(e.range);
+    return r ? ` (${r})` : "";
+};
+/** Completions when the cursor is in a Postgres template; undefined when it is not. */
+export function postgresCompletions(ctx) {
+    const file = fileName(ctx.uri);
+    const at = offsetAt(ctx.content, ctx.position);
+    const where = locatePostgres(ctx.content, at, file);
+    if (!where)
+        return undefined;
+    const refs = referenceCompletions(ctx, where, file);
+    if (refs)
+        return refs;
+    if (where.part < 0)
+        return [];
+    const text = where.found.parts[where.part];
+    const word = wordAround(text, where.offset);
+    const sig = postgresTokensBefore(where.found, where.part, word.start);
+    if (!sig)
+        return [];
+    const expect = postgresExpectAfter(sig, where.found.tag);
+    if (!expect)
+        return [];
+    const prefix = text.slice(word.start, where.offset);
+    return fromCatalog(expect, prefix, majorFor(file), storageTarget(sig, where.found.tag));
+}
+function fromCatalog(expect, prefix, major, target) {
+    const items = [];
+    const add = (item) => {
+        if (items.length < LIMIT)
+            items.push(item);
+    };
+    switch (expect) {
+        case "type":
+            for (const e of entriesAt("types", major))
+                if (matches(e.name, prefix) && e.row.kind !== "m")
+                    add({ label: e.name, kind: "value", detail: (e.detail ?? `type, category ${e.row.category}`) + note(e) });
+            break;
+        case "index-method":
+        case "table-method": {
+            const want = expect === "index-method" ? "index" : "table";
+            for (const e of entriesAt("accessMethods", major))
+                if (e.row.type === want && matches(e.name, prefix))
+                    add({ label: e.name, kind: "value", detail: `${want} access method${note(e)}` });
+            break;
+        }
+        case "storage-parameter":
+            for (const e of entriesAt("storageParameters", major)) {
+                if (!e.row.targets.includes(target) || !matches(e.name, prefix))
+                    continue;
+                add({ label: e.name, insertText: `${e.name} = `, kind: "property", detail: storageType(e.row) + note(e) });
+            }
+            break;
+        case "extension":
+            for (const e of entriesAt("extensions", major))
+                if (matches(e.name, prefix))
+                    add({ label: e.name, kind: "value", detail: `extension ${e.row.defaultVersion}`, documentation: e.row.description ?? undefined });
+            break;
+        case "function":
+            if (prefix === "")
+                break;
+            for (const e of entriesAt("functions", major))
+                if (matches(e.name, prefix))
+                    add({ label: e.name, kind: "intrinsic", detail: functionKind(e.row) + note(e) });
+            break;
+        case "keyword":
+            if (prefix.length < 2)
+                break;
+            for (const e of entriesAt("keywords", major))
+                if (matches(e.name, prefix))
+                    add({ label: e.name.toUpperCase(), kind: "value", detail: `${KEYWORD_CATEGORY[e.row.code] ?? "key word"} key word${note(e)}`, documentation: e.row.description });
+            break;
+    }
+    return items;
+}
+function storageType(row) {
+    const t = row.type;
+    if (!t)
+        return "storage parameter";
+    if (t.kind === "enum")
+        return `enum: ${t.values?.join(", ")}`;
+    return t.range ? `${t.kind}, range ${t.range[0]}..${t.range[1]}` : t.kind;
+}
+function functionKind(row) {
+    const k = row.kinds;
+    const what = k.includes("a") ? "aggregate function" : k.includes("w") ? "window function" : k.includes("p") ? "procedure" : "function";
+    return row.overloads > 1 ? `${what}, ${row.overloads} overloads` : what;
+}
+/** `${` offers the file's declared objects; `${t.` offers `columns`; `${t.columns.` offers its columns with their types. */
+function referenceCompletions(ctx, where, file) {
+    const m = /\$\{\s*(?:([A-Za-z_$][\w$]*)\.(columns\.)?)?[\w$]*$/.exec(ctx.linePrefix);
+    if (!m)
+        return undefined;
+    const self = where.found.node.parent;
+    const selfName = self && ts.isVariableDeclaration(self) && ts.isIdentifier(self.name) ? self.name.text : undefined;
+    const declared = postgresDeclarations(ctx.content, file).filter((d) => d.name !== selfName);
+    const [, owner, columns] = m;
+    if (!owner) {
+        return declared.map((d) => ({
+            label: d.name,
+            kind: "resource",
+            detail: `${d.kind} ${d.sqlName}`,
+            documentation: d.columns.length ? `Columns: ${d.columns.map((c) => c.name).join(", ")}` : undefined,
+        }));
+    }
+    const entity = declared.find((d) => d.name === owner);
+    if (!entity)
+        return [];
+    if (!columns)
+        return entity.columns.length ? [{ label: "columns", kind: "property", detail: `columns of ${entity.sqlName}` }] : [];
+    return entity.columns.map((c) => ({ label: c.name, kind: "property", detail: c.type ?? "column" }));
+}
+// ── Hover ──────────────────────────────────────────────────────────────
+/** Hover when the cursor is in a Postgres template; undefined when it is not (or there is nothing to say). */
+export function postgresHover(ctx) {
+    const file = fileName(ctx.uri);
+    const where = locatePostgres(ctx.content, offsetAt(ctx.content, ctx.position), file);
+    if (!where)
+        return { handled: false };
+    if (where.part < 0) {
+        if (where.expression < 0)
+            return { handled: true };
+        const info = resolvePostgresReference(ctx.content, where.found.expressions[where.expression].getText(where.source), file);
+        return { handled: true, ...(info ? { info: { contents: info } } : {}) };
+    }
+    const contents = catalogHover(where, majorFor(file));
+    return { handled: true, ...(contents ? { info: { contents } } : {}) };
+}
+function catalogHover(where, major) {
+    const text = where.found.parts[where.part];
+    const word = wordAround(text, where.offset);
+    const name = text.slice(word.start, word.end);
+    if (!name)
+        return undefined;
+    const sig = postgresTokensBefore(where.found, where.part, word.start);
+    if (!sig)
+        return undefined;
+    const expect = postgresExpectAfter(sig, where.found.tag);
+    const after = text.slice(word.end);
+    const followedByParen = /^\s*\(/.test(after);
+    const type = () => {
+        const e = entryAt("types", name, major);
+        if (!e)
+            return undefined;
+        const alias = e.row.aliasOf ? `, alias of ${code(e.row.aliasOf)}` : "";
+        return `**${e.name}**: Postgres type${alias}${note(e)}\n\nCategory ${code(e.row.category)}, catalog name ${code(e.row.catalogName)}.`;
+    };
+    const method = () => {
+        const e = entryAt("accessMethods", name, major);
+        if (!e)
+            return undefined;
+        const props = e.row.properties.length ? `\n\nProperties: ${e.row.properties.join(", ")}.` : "";
+        return `**${e.name}**: ${e.row.type} access method${note(e)}${props}`;
+    };
+    const storage = () => {
+        const e = entryAt("storageParameters", name, major);
+        return e ? `**${e.name}**: storage parameter${note(e)}\n\n${storageType(e.row)}. Applies to: ${e.row.targets.join(", ")}.` : undefined;
+    };
+    const fn = () => {
+        const e = entryAt("functions", name, major);
+        return e && followedByParen ? `**${e.name}**: ${functionKind(e.row)}${note(e)}` : undefined;
+    };
+    const keyword = () => {
+        const e = entryAt("keywords", name, major);
+        return e ? `**${e.name.toUpperCase()}**: ${KEYWORD_CATEGORY[e.row.code] ?? "key word"} key word${note(e)}\n\n${e.row.description}` : undefined;
+    };
+    const extension = () => {
+        const e = entryAt("extensions", name, major);
+        return e ? `**${e.name}**: extension ${e.row.defaultVersion}${note(e)}${e.row.description ? `\n\n${e.row.description}` : ""}` : undefined;
+    };
+    const setting = () => {
+        const e = entryAt("settings", name, major);
+        if (!e)
+            return undefined;
+        const r = e.row;
+        const range = r.min !== null || r.max !== null ? `, range ${r.min ?? ""}..${r.max ?? ""}` : "";
+        return `**${e.name}**: server setting${note(e)}\n\nType ${code(r.type)}, default ${code(r.default ?? "")}${r.unit ? ` ${r.unit}` : ""}${range}, changed at ${r.context}.`;
+    };
+    switch (expect) {
+        case "type":
+            return type() ?? keyword();
+        case "index-method":
+        case "table-method":
+            return method();
+        case "storage-parameter":
+            return storage();
+        case "extension":
+            return extension();
+    }
+    if (/^\s*=(?!=)/.test(after)) {
+        const s = storage();
+        if (s)
+            return s;
+    }
+    return fn() ?? keyword() ?? setting();
+}
+// ── References ─────────────────────────────────────────────────────────
+function importedFrom(content, local, file) {
+    const source = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true);
+    for (const stmt of source.statements) {
+        if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier))
+            continue;
+        const spec = stmt.moduleSpecifier.text;
+        if (!spec.startsWith("."))
+            continue;
+        const named = stmt.importClause?.namedBindings;
+        if (!named || !ts.isNamedImports(named))
+            continue;
+        const el = named.elements.find((e) => e.name.text === local);
+        if (!el)
+            continue;
+        const base = resolve(dirname(file), spec);
+        for (const candidate of [`${base}.ts`, `${base}.tsx`, resolve(base, "index.ts"), base.replace(/\.js$/, ".ts")]) {
+            if (!existsSync(candidate))
+                continue;
+            const found = postgresDeclarations(readFileSync(candidate, "utf-8"), candidate).find((d) => d.name === (el.propertyName ?? el.name).text);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+const describe = (d) => {
+    const lines = [`**${d.name}**: Postgres ${d.kind} \`${d.sqlName}\``];
+    if (d.columns.length)
+        lines.push(`Columns: ${d.columns.map((c) => `\`${c.name}${c.type ? ` ${c.type}` : ""}\``).join(", ")}`);
+    return lines.join("\n\n");
+};
+/** Hover text for the expression written in a `${}`, or undefined when it is not a reference this can follow. */
+export function resolvePostgresReference(content, expression, file) {
+    const m = /^([A-Za-z_$][\w$]*)(?:\.columns(?:\.([A-Za-z_$][\w$]*)|\[\s*["'`]([^"'`]+)["'`]\s*\]))?$/.exec(expression.trim());
+    if (!m)
+        return undefined;
+    const [, owner, dotted, bracketed] = m;
+    const column = dotted ?? bracketed;
+    const declared = postgresDeclarations(content, file).find((d) => d.name === owner) ?? importedFrom(content, owner, file);
+    if (!declared)
+        return undefined;
+    if (!column)
+        return describe(declared);
+    const c = declared.columns.find((x) => x.name === column);
+    if (!c)
+        return `**${owner}.columns.${column}**: no column \`${column}\` in ${declared.sqlName}. Columns: ${declared.columns.map((x) => x.name).join(", ")}`;
+    return `**${owner}.columns.${column}**: column \`${c.name}\` of ${declared.kind} \`${declared.sqlName}\`${c.type ? `, type \`${c.type}\`` : ""}`;
+}

package/dist/lsp/refs.js

@@ -0,0 +1,60 @@
+/**
+ * What a `${...}` in a template points at: a table or view declared in the same
+ * file or imported from a relative path, or one of its columns. The answer is
+ * the hover text, from the source of the declaration.
+ */
+import { existsSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { ts } from "@intentius/chant/lint/typescript";
+import { declarations } from "./template.js";
+function importedFrom(content, local, fileName) {
+    const source = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true);
+    for (const stmt of source.statements) {
+        if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier))
+            continue;
+        const spec = stmt.moduleSpecifier.text;
+        if (!spec.startsWith("."))
+            continue;
+        const named = stmt.importClause?.namedBindings;
+        if (!named || !ts.isNamedImports(named))
+            continue;
+        const el = named.elements.find((e) => e.name.text === local);
+        if (!el)
+            continue;
+        const base = resolve(dirname(fileName), spec);
+        for (const candidate of [`${base}.ts`, `${base}.tsx`, resolve(base, "index.ts"), base.replace(/\.js$/, ".ts")]) {
+            if (!existsSync(candidate))
+                continue;
+            const found = declarations(readFileSync(candidate, "utf-8"), candidate).find((d) => d.name === (el.propertyName ?? el.name).text);
+            if (found)
+                return { declared: found, file: candidate };
+        }
+    }
+    return undefined;
+}
+const describe = (d) => {
+    const kind = d.materialized ? "materialized view" : d.tag;
+    const lines = [`**${d.name}**: ClickHouse ${kind} \`${d.sqlName}\``];
+    if (d.engine)
+        lines.push(`Engine: \`${d.engine}\``);
+    if (d.columns.length)
+        lines.push(`Columns: ${d.columns.map((c) => `\`${c.name}${c.type ? ` ${c.type}` : ""}\``).join(", ")}`);
+    return lines.join("\n\n");
+};
+/** Hover text for the expression written in a `${}`, or undefined when it is not a reference this can follow. */
+export function resolveReference(content, expression, fileName) {
+    const m = /^([A-Za-z_$][\w$]*)(?:\.columns(?:\.([A-Za-z_$][\w$]*)|\[\s*["'`]([^"'`]+)["'`]\s*\]))?$/.exec(expression.trim());
+    if (!m)
+        return undefined;
+    const [, owner, dotted, bracketed] = m;
+    const column = dotted ?? bracketed;
+    const declared = declarations(content, fileName).find((d) => d.name === owner) ?? importedFrom(content, owner, fileName)?.declared;
+    if (!declared)
+        return undefined;
+    if (!column)
+        return describe(declared);
+    const c = declared.columns.find((x) => x.name === column);
+    if (!c)
+        return `**${owner}.columns.${column}**: no column \`${column}\` in ${declared.sqlName}. Columns: ${declared.columns.map((x) => x.name).join(", ")}`;
+    return `**${owner}.columns.${column}**: column \`${c.name}\` of ${declared.tag} \`${declared.sqlName}\`${c.type ? `, type \`${c.type}\`` : ""}`;
+}

package/dist/lsp/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/lsp/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAqB,MAAM,wCAAwC,CAAC;AAMzF,sFAAsF;AACtF,wBAAgB,aAAa,IAAI,YAAY,CAU5C"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/lsp/registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAqB,MAAM,wCAAwC,CAAC;AAMzF,sFAAsF;AACtF,wBAAgB,aAAa,IAAI,YAAY,CAU5C"}