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

package/src/lsp/completions.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "vitest";
+import { completions } from "./completions";
+
+const ctx = (linePrefix: string, wordAtCursor = "") => ({
+  uri: "file:///schema.ts",
+  content: linePrefix,
+  position: { line: 0, character: linePrefix.length },
+  wordAtCursor,
+  linePrefix,
+});
+
+describe("sql completions", () => {
+  test("offer nothing outside a constructor position", () => {
+    expect(completions(ctx("const x = 42"))).toEqual([]);
+  });
+
+  test("return a list after new", () => {
+    expect(Array.isArray(completions(ctx("new ")))).toBe(true);
+  });
+});
+
+const IMPORT = 'import { table, view, database } from "@intentius/chant-lexicon-sql/clickhouse";\n';
+
+/** A source with `|` marking the cursor. */
+function at(source: string) {
+  const content = IMPORT + source;
+  const offset = content.indexOf("|");
+  const text = content.replace("|", "");
+  const before = text.slice(0, offset).split("\n");
+  const line = before.length - 1;
+  const linePrefix = before[line]!;
+  return {
+    uri: "file:///schema.ts",
+    content: text,
+    position: { line, character: linePrefix.length },
+    wordAtCursor: /\w*$/.exec(linePrefix)![0],
+    linePrefix,
+  };
+}
+const labels = (source: string) => completions(at(source)).map((i) => i.label);
+
+describe("sql completions inside a template", () => {
+  test("engines after ENGINE =", () => {
+    const l = labels("export const t = table`CREATE TABLE t (a UInt8) ENGINE = Repl|`;");
+    expect(l).toContain("ReplacingMergeTree");
+    expect(l).not.toContain("MergeTree");
+  });
+
+  test("database engines in a database template", () => {
+    const l = labels("export const d = database`CREATE DATABASE d ENGINE = |`;");
+    expect(l).toContain("Atomic");
+    expect(l).not.toContain("MergeTree");
+  });
+
+  test("type families where a column's type goes", () => {
+    expect(labels("export const t = table`CREATE TABLE t (id UU|`;")).toContain("UUID");
+    expect(labels("export const t = table`CREATE TABLE t (id UInt8, kind Low|`;")).toContain("LowCardinality");
+  });
+
+  test("types inside a wrapper", () => {
+    expect(labels("export const t = table`CREATE TABLE t (kind LowCardinality(Str|`;")).toContain("String");
+  });
+
+  test("no type completion while a column name is being typed", () => {
+    expect(labels("export const t = table`CREATE TABLE t (id UInt8, ki|`;")).toEqual([]);
+  });
+
+  test("codecs inside CODEC()", () => {
+    expect(labels("export const t = table`CREATE TABLE t (a UInt8 CODEC(ZS|`;")).toContain("ZSTD");
+  });
+
+  test("skip index types after TYPE", () => {
+    expect(labels("export const t = table`CREATE TABLE t (a UInt8, INDEX i a TYPE bloom|`;")).toContain("bloom_filter");
+  });
+
+  test("MergeTree settings after SETTINGS, with insert text", () => {
+    const items = completions(at("export const t = table`CREATE TABLE t (a UInt8) ENGINE = MergeTree ORDER BY a SETTINGS index_gran|`;"));
+    const item = items.find((i) => i.label === "index_granularity");
+    expect(item?.insertText).toBe("index_granularity = ");
+    expect(item?.detail).toMatch(/UInt64/);
+  });
+
+  test("query settings after the SELECT of a view", () => {
+    const l = labels("export const v = view`CREATE VIEW v AS SELECT 1 SETTINGS max_thre|`;");
+    expect(l).toContain("max_threads");
+  });
+
+  test("functions in a view's select", () => {
+    expect(labels("export const v = view`CREATE VIEW v AS SELECT toStartOfH|`;")).toContain("toStartOfHour");
+  });
+
+  test("functions after DEFAULT", () => {
+    expect(labels("export const t = table`CREATE TABLE t (a DateTime DEFAULT now|`;")).toContain("now");
+  });
+});
+
+describe("sql completions inside ${}", () => {
+  const events = 'export const events = table`CREATE TABLE events (user_id UUID, kind String) ENGINE = Log`;\n';
+
+  test("offer the tables and views declared in the file", () => {
+    const items = completions(at(events + "export const v = view`CREATE VIEW v AS SELECT 1 FROM ${|}`;"));
+    expect(items.map((i) => i.label)).toEqual(["events"]);
+    expect(items[0]!.documentation).toContain("user_id");
+  });
+
+  test("offer columns for an entity", () => {
+    expect(labels(events + "export const v = view`CREATE VIEW v AS SELECT ${events.|}`;")).toEqual(["columns"]);
+    const items = completions(at(events + "export const v = view`CREATE VIEW v AS SELECT ${events.columns.|}`;"));
+    expect(items.map((i) => [i.label, i.detail])).toEqual([["user_id", "UUID"], ["kind", "String"]]);
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,128 @@
+import * as ts from "typescript";
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+import { catalogIndex, type CatalogIndex } from "./catalog";
+import { postgresCompletions } from "./postgres";
+import { registryIndex } from "./registry";
+import { declarations, expectAfter, locate, offsetAt, tokensBefore, wordAround, type Expect } from "./template";
+import type { SqlTag } from "../lint/rules/templates";
+
+const LIMIT = 200;
+
+/**
+ * Completions for the sql lexicon.
+ *
+ * Inside a `table`, `view` or `database` template they come from the catalog of
+ * the pinned ClickHouse server: engines after `ENGINE =`, type families where a
+ * column's type goes, codecs inside `CODEC(...)`, skip index types after `TYPE`,
+ * settings after `SETTINGS`, functions in expressions. Inside `${` they are the
+ * tables and views declared in the file and their columns. Anywhere else, the
+ * entity classes from the generated registry.
+ */
+export function completions(ctx: CompletionContext): CompletionItem[] {
+  const pg = postgresCompletions(ctx);
+  if (pg) return pg;
+  const refs = interpolationCompletions(ctx);
+  if (refs) return refs;
+
+  const at = offsetAt(ctx.content, ctx.position);
+  const where = locate(ctx.content, at, fileName(ctx.uri));
+  if (where && where.part >= 0) {
+    const index = catalogIndex();
+    if (!index) return [];
+    const text = where.found.parts[where.part]!;
+    const word = wordAround(text, where.offset);
+    const sig = tokensBefore(where.found, where.part, word.start);
+    if (!sig) return [];
+    const expect = expectAfter(sig, where.found.tag);
+    if (!expect) return [];
+    const prefix = text.slice(word.start, where.offset);
+    return fromCatalog(index, expect, where.found.tag, prefix);
+  }
+  if (where) return [];
+  return lexiconCompletions(ctx, registryIndex(), "sql entity");
+}
+
+const fileName = (uri: string): string => (uri.startsWith("file://") ? decodeURIComponent(uri.slice(7)) : uri) || "file.ts";
+
+const matches = (name: string, prefix: string, fold: boolean): boolean =>
+  prefix === "" || (fold ? name.toLowerCase().startsWith(prefix.toLowerCase()) : name.startsWith(prefix));
+
+function fromCatalog(index: CatalogIndex, expect: Expect, tag: SqlTag, prefix: string): CompletionItem[] {
+  const items: CompletionItem[] = [];
+  const add = (item: CompletionItem) => {
+    if (items.length < LIMIT) items.push(item);
+  };
+  const { catalog } = index;
+  switch (expect) {
+    case "engine":
+      if (tag === "database") {
+        for (const e of catalog.databaseEngines)
+          if (matches(e.name, prefix, true)) add({ label: e.name, kind: "value", detail: e.syntax, documentation: e.summary });
+      } else {
+        for (const e of catalog.tableEngines)
+          if (matches(e.name, prefix, true)) add({ label: e.name, kind: "value", detail: e.syntax, documentation: e.summary });
+      }
+      break;
+    case "type":
+      for (const t of catalog.typeFamilies)
+        if (matches(t.name, prefix, t.caseInsensitive))
+          add({ label: t.name, kind: "value", detail: t.aliasOf ? `alias of ${t.aliasOf}` : "type family" });
+      break;
+    case "codec":
+      for (const c of catalog.codecs)
+        if (matches(c.name, prefix, true)) add({ label: c.name, kind: "value", detail: codecKind(c), documentation: c.summary });
+      break;
+    case "index-type":
+      for (const i of catalog.skipIndexTypes)
+        if (matches(i.name, prefix, false)) add({ label: i.name, kind: "value", detail: i.syntax, documentation: i.summary });
+      break;
+    case "merge-tree-setting":
+    case "query-setting": {
+      const rows = expect === "merge-tree-setting" ? catalog.mergeTreeSettings : catalog.querySettings;
+      for (const s of rows) {
+        if (s.obsolete || !matches(s.name, prefix, false)) continue;
+        add({ label: s.name, insertText: `${s.name} = `, kind: "property", detail: `${s.type}, default ${s.default || "''"}`, documentation: s.summary });
+      }
+      break;
+    }
+    case "function":
+      if (prefix === "") break;
+      for (const f of catalog.functions)
+        if (!f.aliasOf && matches(f.name, prefix, f.caseInsensitive))
+          add({ label: f.name, kind: "intrinsic", detail: f.aggregate ? "aggregate function" : "function" });
+      break;
+  }
+  return items;
+}
+
+function codecKind(c: { compression: boolean; encryption: boolean; timeseries: boolean }): string {
+  return c.encryption ? "encryption codec" : c.timeseries ? "time series codec" : c.compression ? "compression codec" : "codec";
+}
+
+/** `${` offers the file's tables and views; `${t.` offers `columns`; `${t.columns.` offers its columns. */
+function interpolationCompletions(ctx: CompletionContext): CompletionItem[] | undefined {
+  const before = ctx.content.slice(0, offsetAt(ctx.content, ctx.position));
+  if (!before.includes("chant-lexicon-sql") && !ctx.content.includes("chant-lexicon-sql")) return undefined;
+  const m = /\$\{\s*(?:([A-Za-z_$][\w$]*)\.(columns\.)?)?[\w$]*$/.exec(ctx.linePrefix);
+  if (!m) return undefined;
+  // Inside a template: an odd number of backticks before the cursor.
+  if ((before.match(/`/g)?.length ?? 0) % 2 === 0) return undefined;
+  // The template being written is not something it can refer to.
+  const self = locate(ctx.content, offsetAt(ctx.content, ctx.position), fileName(ctx.uri))?.found.node.parent;
+  const selfName = self && ts.isVariableDeclaration(self) && ts.isIdentifier(self.name) ? self.name.text : undefined;
+  const declared = declarations(ctx.content, fileName(ctx.uri)).filter((d) => d.name !== selfName);
+  const [, owner, columns] = m;
+  if (!owner) {
+    return declared.map((d) => ({
+      label: d.name,
+      kind: "resource" as const,
+      detail: `${d.materialized ? "materialized view" : d.tag} ${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" }));
+}

package/src/lsp/diagnostics.test.ts

@@ -0,0 +1,26 @@
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { describe, expect, test } from "vitest";
+import { runLint } from "@intentius/chant/lint/engine";
+import { toLspDiagnostics } from "@intentius/chant/cli/lsp/diagnostics";
+import { sqlPlugin } from "../plugin";
+
+/** The editor's diagnostics are the lint rules' (chant serve lsp runs `lintRules()`), so a parse error shows at the token. */
+describe("sql diagnostics in the editor", () => {
+  test("DDL that does not parse is an error at the token", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "sql-lsp-"));
+    try {
+      const file = join(dir, "schema.ts");
+      writeFileSync(
+        file,
+        'import { table } from "@intentius/chant-lexicon-sql/clickhouse";\nexport const t = table`CREATE TABLE t (\n  a Strin g\n) ENGINE = Log`;\n',
+      );
+      const { diagnostics } = await runLint([file], sqlPlugin.lintRules!());
+      const [d] = toLspDiagnostics(diagnostics.filter((x) => x.ruleId === "SQLCH001"));
+      expect(d).toMatchObject({ code: "SQLCH001", severity: 1, range: { start: { line: 2, character: 10 } } });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/lsp/hover.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "vitest";
+import { hover } from "./hover";
+
+const ctx = (word: string) => ({
+  uri: "file:///schema.ts",
+  content: word,
+  position: { line: 0, character: 0 },
+  word,
+  lineText: word,
+});
+
+describe("sql hover", () => {
+  test("says nothing about a word that is not an entity class", () => {
+    expect(hover(ctx("NotAnEntity"))).toBeUndefined();
+  });
+
+  test("says nothing about an empty word", () => {
+    expect(hover(ctx(""))).toBeUndefined();
+  });
+});
+
+const IMPORT = 'import { table, view, database } from "@intentius/chant-lexicon-sql/clickhouse";\n';
+
+/** A source with `|` marking the cursor. */
+function over(source: string) {
+  const content = IMPORT + source;
+  const offset = content.indexOf("|");
+  const text = content.replace("|", "");
+  const before = text.slice(0, offset).split("\n");
+  const line = before.length - 1;
+  const lineText = text.split("\n")[line]!;
+  const character = before[line]!.length;
+  const word = (/\w*$/.exec(lineText.slice(0, character))![0] + /^\w*/.exec(lineText.slice(character))![0]);
+  return { uri: "file:///schema.ts", content: text, position: { line, character }, word, lineText };
+}
+const hoverText = (source: string) => hover(over(source))?.contents;
+
+describe("sql hover inside a template", () => {
+  test("an engine shows its usage line and summary", () => {
+    const h = hoverText("export const t = table`CREATE TABLE t (a UInt8) ENGINE = Replacing|MergeTree ORDER BY a`;");
+    expect(h).toContain("ReplacingMergeTree");
+    expect(h).toContain("ENGINE = ReplacingMergeTree(");
+  });
+
+  test("a type family", () => {
+    expect(hoverText("export const t = table`CREATE TABLE t (id UU|ID)`;")).toContain("type family");
+  });
+
+  test("an alias type names what it stands for", () => {
+    expect(hoverText("export const t = table`CREATE TABLE t (id BIG|INT)`;")).toContain("Int64");
+  });
+
+  test("a MergeTree setting shows type, default and description", () => {
+    const h = hoverText("export const t = table`CREATE TABLE t (a UInt8) ENGINE = MergeTree ORDER BY a SETTINGS index_gran|ularity = 8192`;");
+    expect(h).toContain("MergeTree setting");
+    expect(h).toContain("UInt64");
+  });
+
+  test("a function followed by a call", () => {
+    expect(hoverText("export const v = view`CREATE VIEW v AS SELECT cou|nt() FROM t`;")).toContain("aggregate function");
+  });
+
+  test("a codec", () => {
+    expect(hoverText("export const t = table`CREATE TABLE t (a UInt8 CODEC(ZS|TD(3)))`;")).toContain("codec");
+  });
+
+  test("a column name is not a catalog word", () => {
+    expect(hoverText("export const t = table`CREATE TABLE t (us|er_id UInt8)`;")).toBeUndefined();
+  });
+});
+
+describe("sql hover on a ${ref}", () => {
+  const events = 'export const events = table`CREATE TABLE events (user_id UUID, kind String) ENGINE = Log`;\n';
+
+  test("a table shows its name, engine and columns", () => {
+    const h = hoverText(events + "export const v = view`CREATE VIEW v AS SELECT 1 FROM ${ev|ents}`;");
+    expect(h).toContain("table `events`");
+    expect(h).toContain("user_id UUID");
+    expect(h).toContain("Log");
+  });
+
+  test("a column shows its type", () => {
+    const h = hoverText(events + "export const v = view`CREATE VIEW v AS SELECT ${events.columns.user|_id} FROM events`;");
+    expect(h).toContain("type `UUID`");
+  });
+
+  test("a column that does not exist says so", () => {
+    expect(hoverText(events + "export const v = view`CREATE VIEW v AS SELECT ${events.columns.nope|}`;")).toContain("no column");
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,113 @@
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+import { catalogIndex } from "./catalog";
+import { postgresHover } from "./postgres";
+import { registryIndex } from "./registry";
+import { resolveReference } from "./refs";
+import { expectAfter, locate, offsetAt, tokensBefore, wordAround } from "./template";
+
+/**
+ * Hover for the sql lexicon.
+ *
+ * Inside a template, a word is looked up in the catalog where the SQL before it
+ * says what kind of word it is (an engine after `ENGINE =`, a type where a type
+ * goes, a setting after `SETTINGS`), and a function when it is followed by `(`.
+ * A `${ref}` shows the table, view or column it points at, with its type.
+ * Anywhere else, the entity classes from the generated registry.
+ */
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  const pg = postgresHover(ctx);
+  if (pg.handled) return pg.info;
+  const at = offsetAt(ctx.content, ctx.position);
+  const where = locate(ctx.content, at, fileName(ctx.uri));
+  if (where) {
+    if (where.part < 0) return where.expression < 0 ? undefined : reference(ctx, where.expression, where);
+    return catalogHover(where);
+  }
+  return lexiconHover(ctx, registryIndex(), entityHover);
+}
+
+const fileName = (uri: string): string => (uri.startsWith("file://") ? decodeURIComponent(uri.slice(7)) : uri) || "file.ts";
+
+function entityHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  const [dialect] = entry.resourceType.split("::");
+  return { contents: `**${className}**\n\n${dialect} type: \`${entry.resourceType}\`` };
+}
+
+function reference(ctx: HoverContext, expression: number, where: NonNullable<ReturnType<typeof locate>>): HoverInfo | undefined {
+  const expr = where.found.expressions[expression]!;
+  const info = resolveReference(ctx.content, expr.getText(where.source), fileName(ctx.uri));
+  return info ? { contents: info } : undefined;
+}
+
+function catalogHover(where: NonNullable<ReturnType<typeof locate>>): HoverInfo | undefined {
+  const index = catalogIndex();
+  if (!index) return 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 = tokensBefore(where.found, where.part, word.start);
+  if (!sig) return undefined;
+  const expect = expectAfter(sig, where.found.tag);
+  const followedByParen = /^\s*\(/.test(text.slice(word.end));
+  const code = (s: string) => `\`${s}\``;
+  let contents: string | undefined;
+
+  const function_ = () => {
+    const f = index.functions.get(name) ?? index.functions.get(name.toLowerCase());
+    if (!f || !followedByParen) return undefined;
+    const alias = f.aliasOf ? `\n\nAlias of ${code(f.aliasOf)}.` : "";
+    return `**${f.name}**: ${f.aggregate ? "aggregate function" : "function"}${f.caseInsensitive ? ", case-insensitive" : ""}${alias}`;
+  };
+
+  switch (expect) {
+    case "engine": {
+      const e = where.found.tag === "database" ? index.databaseEngines.get(name) : index.engines.get(name);
+      if (e) {
+        const caps = where.found.tag === "database" ? [] : Object.entries(index.engines.get(name)!.capabilities).filter(([, on]) => on).map(([k]) => k);
+        contents = `**${e.name}** engine\n\n${code(e.syntax)}\n\n${e.summary}${caps.length ? `\n\nSupports: ${caps.join(", ")}.` : ""}`;
+      }
+      break;
+    }
+    case "type": {
+      const t = index.types.get(name) ?? index.types.get(name.toLowerCase());
+      if (t) {
+        contents = `**${t.name}**: ClickHouse type family${t.aliasOf ? `, alias of ${code(t.aliasOf)}` : ""}${t.caseInsensitive ? ", case-insensitive" : ""}`;
+      }
+      break;
+    }
+    case "codec": {
+      const c = index.codecs.get(name);
+      if (c) contents = `**${c.name}** codec${c.experimental ? " (experimental)" : ""}\n\n${c.summary}`;
+      break;
+    }
+    case "index-type": {
+      const i = index.indexTypes.get(name);
+      if (i) contents = `**${i.name}** skip index\n\n${code(i.syntax)}\n\n${i.summary}`;
+      break;
+    }
+    case "merge-tree-setting":
+    case "query-setting":
+      contents = settingHover(index, name, expect === "merge-tree-setting");
+      break;
+    case "function":
+      contents = function_();
+      break;
+  }
+  // A later setting in a list follows its value, not a comma-or-SETTINGS: look it up by name when it is followed by `=`.
+  if (!contents && /^\s*=(?!=)/.test(text.slice(word.end))) contents = settingHover(index, name, where.found.tag !== "view");
+  if (!contents) contents = function_();
+  return contents ? { contents } : undefined;
+}
+
+function settingHover(index: NonNullable<ReturnType<typeof catalogIndex>>, name: string, mergeTreeFirst: boolean): string | undefined {
+  const row = mergeTreeFirst
+    ? (index.mergeTreeSettings.get(name) ?? index.querySettings.get(name))
+    : (index.querySettings.get(name) ?? index.mergeTreeSettings.get(name));
+  if (!row) return undefined;
+  const scope = index.mergeTreeSettings.get(name) === row ? "MergeTree setting" : "query setting";
+  const range = row.min !== undefined || row.max !== undefined ? `, range ${row.min ?? ""}..${row.max ?? ""}` : "";
+  const flags = [row.obsolete ? "obsolete" : "", row.readonly ? "read-only" : "", row.tier !== "Production" ? row.tier.toLowerCase() : ""].filter(Boolean);
+  return `**${row.name}**: ${scope}\n\nType \`${row.type}\`, default \`${row.default || "''"}\`${range}${flags.length ? ` (${flags.join(", ")})` : ""}\n\n${row.summary}`;
+}