@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.1

package/src/lsp/postgres.ts

@@ -0,0 +1,270 @@
+/**
+ * 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 * as ts from "typescript";
+import type { CompletionContext, CompletionItem, HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import {
+  describeRange,
+  entriesAt,
+  entryAt,
+  majorFor,
+  type Entry,
+  type FunctionRow,
+  type KeywordRow,
+  type MethodRow,
+  type SettingRow,
+  type StorageRow,
+  type TypeRow,
+  type ExtensionRow,
+} from "./postgres-catalog";
+import {
+  locatePostgres,
+  postgresDeclarations,
+  postgresExpectAfter,
+  postgresTokensBefore,
+  storageTarget,
+  type PostgresDeclared,
+  type PostgresExpect,
+  type PostgresLocated,
+} from "./postgres-template";
+import { offsetAt, wordAround } from "../core/find-templates";
+
+const LIMIT = 200;
+const KEYWORD_CATEGORY: Record<string, string> = { U: "unreserved", C: "column name", T: "type or function name", R: "reserved" };
+
+const fileName = (uri: string): string => (uri.startsWith("file://") ? decodeURIComponent(uri.slice(7)) : uri) || "file.ts";
+const code = (s: string) => `\`${s}\``;
+const matches = (name: string, prefix: string): boolean => prefix === "" || name.toLowerCase().startsWith(prefix.toLowerCase());
+const note = (e: Entry<unknown>): string => {
+  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: CompletionContext): CompletionItem[] | undefined {
+  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: PostgresExpect, prefix: string, major: number, target: string): CompletionItem[] {
+  const items: CompletionItem[] = [];
+  const add = (item: CompletionItem) => {
+    if (items.length < LIMIT) items.push(item);
+  };
+  switch (expect) {
+    case "type":
+      for (const e of entriesAt<TypeRow>("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<MethodRow>("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<StorageRow>("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<ExtensionRow>("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<FunctionRow>("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<KeywordRow>("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: StorageRow): string {
+  const t = row.type as { kind: string; range?: readonly number[]; values?: readonly string[] } | undefined;
+  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: FunctionRow): string {
+  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: CompletionContext, where: PostgresLocated, file: string): CompletionItem[] | undefined {
+  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" as const,
+      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" as const, 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: HoverContext): { handled: boolean; info?: HoverInfo } {
+  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: PostgresLocated, major: number): string | undefined {
+  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<TypeRow>("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<MethodRow>("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<StorageRow>("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<FunctionRow>("functions", name, major);
+    return e && followedByParen ? `**${e.name}**: ${functionKind(e.row)}${note(e)}` : undefined;
+  };
+  const keyword = () => {
+    const e = entryAt<KeywordRow>("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<ExtensionRow>("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<SettingRow>("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: string, local: string, file: string): PostgresDeclared | undefined {
+  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: PostgresDeclared): string => {
+  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: string, expression: string, file: string): string | undefined {
+  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/src/lsp/refs.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 * as ts from "typescript";
+import { declarations, type Declared } from "./template";
+
+function importedFrom(content: string, local: string, fileName: string): { declared: Declared; file: string } | undefined {
+  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: Declared): string => {
+  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: string, expression: string, fileName: string): string | undefined {
+  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/src/lsp/registry.ts

@@ -0,0 +1,19 @@
+import { createRequire } from "module";
+import { LexiconIndex, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+
+const require = createRequire(import.meta.url);
+
+let cached: LexiconIndex | null = null;
+
+/** The generated entity registry, indexed once. Empty when generation has not run. */
+export function registryIndex(): LexiconIndex {
+  if (cached) return cached;
+  let data: Record<string, LexiconEntry> = {};
+  try {
+    data = require("../generated/lexicon-sql.json") as Record<string, LexiconEntry>;
+  } catch {
+    // No src/generated/ yet (a fresh clone before `npm run generate`): nothing to complete.
+  }
+  cached = new LexiconIndex(data);
+  return cached;
+}

package/src/lsp/template.ts

@@ -0,0 +1,166 @@
+/**
+ * Finding where the cursor is inside a `database`, `table` or `view` 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 what a template
+ * is and which module's tags count.
+ */
+
+import * as ts from "typescript";
+import { isTrivia, tokenize, type Token } from "../clickhouse/tokens";
+import { parseCreate, type Span } from "../clickhouse/parser";
+import { CLICKHOUSE_TEMPLATE_SOURCE, findTemplates, type FoundTemplate, type SqlTag } from "../lint/rules/templates";
+import { locateIn, type Located as CoreLocated } from "../core/find-templates";
+
+export { offsetAt, wordAround } from "../core/find-templates";
+
+export type Located = CoreLocated<SqlTag>;
+
+/** The ClickHouse template the source offset `at` is inside, and where in it. */
+export function locate(content: string, at: number, fileName = "file.ts"): Located | undefined {
+  return locateIn(content, at, [CLICKHOUSE_TEMPLATE_SOURCE], fileName);
+}
+
+/** Significant tokens of the template up to `offset` in `part`; undefined when the text before it does not tokenize. */
+export function tokensBefore(found: FoundTemplate, part: number, offset: number): Token[] | undefined {
+  try {
+    const parts = [...found.parts.slice(0, part), found.parts[part]!.slice(0, offset)];
+    return tokenize(parts).filter((t) => !isTrivia(t));
+  } catch {
+    return undefined;
+  }
+}
+
+/** What the SQL before the cursor expects. */
+export type Expect =
+  | "engine"
+  | "type"
+  | "codec"
+  | "index-type"
+  | "merge-tree-setting"
+  | "query-setting"
+  | "function";
+
+const upper = (t: Token | undefined): string => (t?.kind === "ident" ? t.text.toUpperCase() : "");
+const isPunct = (t: Token | undefined, text: string): boolean => t?.kind === "punct" && t.text === text;
+
+/** Words that end a SETTINGS list, or start something that is not one. */
+const CLAUSE = new Set([
+  "ENGINE", "ORDER", "PARTITION", "PRIMARY", "SAMPLE", "TTL", "AS", "SELECT", "COMMENT", "FROM", "WHERE", "GROUP",
+  "HAVING", "LIMIT", "UNION", "TO", "POPULATE", "REFRESH", "WITH",
+]);
+/** Words after which an expression is written. */
+const EXPRESSION_AFTER = new Set(["DEFAULT", "MATERIALIZED", "ALIAS", "TTL", "BY", "CHECK", "ASSUME", "SELECT", "WHERE", "HAVING", "ON", "AND", "OR", "WHEN", "THEN", "ELSE"]);
+const TYPE_WRAPPERS = new Set(["NULLABLE", "ARRAY", "LOWCARDINALITY", "MAP", "TUPLE", "NESTED"]);
+const NOT_A_COLUMN = new Set(["INDEX", "PROJECTION", "CONSTRAINT", "PRIMARY"]);
+
+export function expectAfter(sig: readonly Token[], tag: SqlTag): Expect | undefined {
+  const last = sig[sig.length - 1];
+  if (!last) return undefined;
+  const prev = sig[sig.length - 2];
+  if (upper(last) === "ENGINE" || (isPunct(last, "=") && upper(prev) === "ENGINE")) return "engine";
+  if (upper(last) === "TYPE") return "index-type";
+
+  // The innermost open parenthesis, and the word before it.
+  const open: number[] = [];
+  sig.forEach((t, i) => {
+    if (isPunct(t, "(")) open.push(i);
+    else if (isPunct(t, ")")) open.pop();
+  });
+  const opener = open[open.length - 1];
+  const fn = opener === undefined ? undefined : sig[opener - 1];
+  const afterOpenOrComma = isPunct(last, "(") || isPunct(last, ",");
+
+  if (afterOpenOrComma && opener !== undefined && upper(fn) === "CODEC") return "codec";
+  if (isPunct(last, "(") && TYPE_WRAPPERS.has(upper(fn))) return "type";
+
+  // A column's type: `(name |` in the column list, which is the first parenthesis of a table or view.
+  if (tag !== "database" && open.length === 1 && (last.kind === "ident" || last.kind === "qident")) {
+    const inColumnList = !sig.some((t) => upper(t) === "ENGINE" || upper(t) === "AS") && opener === firstParen(sig);
+    if (inColumnList && (isPunct(prev, "(") || isPunct(prev, ",")) && !NOT_A_COLUMN.has(upper(last))) return "type";
+  }
+
+  // SETTINGS name = value, name = value: a name goes first, or after a comma.
+  if (tag !== "database") {
+    let depth = 0;
+    for (let i = sig.length - 1; i >= 0; i--) {
+      const t = sig[i]!;
+      if (isPunct(t, ")")) depth++;
+      else if (isPunct(t, "(")) {
+        if (depth === 0) break;
+        depth--;
+      } else if (depth === 0) {
+        const w = upper(t);
+        if (w === "SETTINGS") {
+          if (i === sig.length - 1 || isPunct(last, ",")) {
+            return sig.slice(0, i).some((x) => upper(x) === "SELECT") ? "query-setting" : "merge-tree-setting";
+          }
+          break;
+        }
+        if (CLAUSE.has(w)) break;
+      }
+    }
+  }
+
+  if (EXPRESSION_AFTER.has(upper(last))) return "function";
+  if (sig.some((t) => upper(t) === "SELECT") && (afterOpenOrComma || last.kind === "op")) return "function";
+  return undefined;
+}
+
+function firstParen(sig: readonly Token[]): number {
+  return sig.findIndex((t) => isPunct(t, "("));
+}
+
+// ── Declarations in a file ─────────────────────────────────────────────
+
+export interface Declared {
+  /** The const the template is bound to. */
+  name: string;
+  tag: SqlTag;
+  /** The name the DDL gives the object, interpolations written back as `${...}`. */
+  sqlName: string;
+  materialized: boolean;
+  columns: Array<{ name: string; type?: string }>;
+  engine?: string;
+}
+
+function spanText(found: FoundTemplate, tokens: Token[], span: Span | undefined, source: ts.SourceFile): string | undefined {
+  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\`...\`` in the content that parses, by const name. */
+export function declarations(content: string, fileName = "file.ts"): Declared[] {
+  const source = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true);
+  const out: Declared[] = [];
+  for (const found of findTemplates(source)) {
+    const decl = found.node.parent;
+    if (!decl || !ts.isVariableDeclaration(decl) || !ts.isIdentifier(decl.name)) continue;
+    try {
+      const tokens = tokenize(found.parts);
+      const node = parseCreate(tokens);
+      const columns =
+        node.statement === "database"
+          ? []
+          : node.columns.map((c) => ({
+              name: c.name || spanText(found, tokens, c.nameSpan, source) || "",
+              ...(spanText(found, tokens, c.type, source) ? { type: spanText(found, tokens, c.type, source)! } : {}),
+            }));
+      const engine = node.engine?.name || spanText(found, tokens, node.engine?.nameSpan, source);
+      out.push({
+        name: decl.name.text,
+        tag: found.tag,
+        sqlName: spanText(found, tokens, node.name, source) ?? decl.name.text,
+        materialized: node.statement === "view" && node.materialized,
+        columns,
+        ...(engine ? { engine } : {}),
+      });
+    } catch {
+      // A template that does not parse is SQLCH001's to report; it has no columns to offer.
+    }
+  }
+  return out;
+}