@intentius/chant-lexicon-sql 0.121.1 → 0.123.0

package/dist/rules/sqlpg123.ts

@@ -0,0 +1,63 @@
+import { checkOf, indexesOf, tablesOf } from "./postgres-helpers";
+import { columnsOf, includeColumns, interpolatedTable, projectOf } from "./postgres-names";
+
+/**
+ * SQLPG123: a bare column name in a key, index or grant column list that the
+ * table does not declare.
+ *
+ * Doc: https://www.postgresql.org/docs/18/sql-createtable.html,
+ * https://www.postgresql.org/docs/18/sql-createindex.html,
+ * https://www.postgresql.org/docs/18/sql-grant.html. The server refuses
+ * `column "idd" named in key does not exist` (or `column "emial" does not
+ * exist`) at CREATE or GRANT. Checked: `PRIMARY KEY`, `UNIQUE` and their
+ * `INCLUDE`, a foreign key's own columns, an index's bare columns and
+ * `INCLUDE` on a `${}` table, and a `GRANT`/`REVOKE` column list on a `${}`
+ * table. An expression (an index expression, a CHECK, a generated column) is
+ * left to the server, as is a table whose columns come from somewhere the
+ * build cannot see (`LIKE`, `OF type`, a plain-text parent).
+ */
+export const sqlpg123 = checkOf({ id: "SQLPG123", description: "A key, index or grant column list names a column the table does not declare" }, (ctx, report) => {
+  const p = projectOf(ctx);
+  const verify = (entity: string, sqlName: string, where: string, tableName: string, names: readonly string[], cols: ReadonlyMap<string, unknown>) => {
+    for (const n of new Set(names)) {
+      if (cols.has(n)) continue;
+      report({ severity: "error", message: `${entity} (${sqlName}) ${where} names the column ${n}, which ${tableName} does not declare`, entity });
+    }
+  };
+  for (const t of tablesOf(ctx)) {
+    const cols = columnsOf(p, t);
+    if (!cols) continue;
+    if (t.primaryKey) {
+      verify(t.export, t.sqlName, "PRIMARY KEY", t.sqlName, t.primaryKey.columns, cols);
+      verify(t.export, t.sqlName, "PRIMARY KEY ... INCLUDE", t.sqlName, includeColumns(t.primaryKey.include), cols);
+    }
+    for (const u of t.uniques) {
+      verify(t.export, t.sqlName, "UNIQUE", t.sqlName, u.columns, cols);
+      verify(t.export, t.sqlName, "UNIQUE ... INCLUDE", t.sqlName, includeColumns(u.include), cols);
+    }
+    for (const fk of t.foreignKeys) verify(t.export, t.sqlName, `FOREIGN KEY to ${fk.refTable}`, t.sqlName, fk.columns, cols);
+  }
+  for (const i of indexesOf(ctx)) {
+    const t = interpolatedTable(p, i.table, i.tableName);
+    const cols = t && columnsOf(p, t);
+    if (!cols) continue;
+    verify(i.export, i.sqlName, `index on ${i.tableName}`, i.tableName, i.elements.flatMap((e) => (e.column ? [e.column] : [])), cols);
+    verify(i.export, i.sqlName, `index on ${i.tableName} INCLUDE`, i.tableName, includeColumns(i.include), cols);
+  }
+  for (const g of p.objects) {
+    if (g.type !== "Postgres::Grant" || g.on !== "table") continue;
+    const objects = (g.objects as unknown[]) ?? [];
+    const names = (g.objectNames as string[]) ?? [];
+    const privileges = (g.privileges as Array<{ privilege: string; columns?: string[] }>) ?? [];
+    objects.forEach((ref, n) => {
+      const t = interpolatedTable(p, ref, names[n]);
+      const cols = t && columnsOf(p, t);
+      if (!cols) return;
+      for (const priv of privileges) {
+        if (!priv.columns?.length) continue;
+        const action = g.action === "revoke" ? "REVOKE" : "GRANT";
+        verify(g.export, String(g.name), `${action} ${priv.privilege.toUpperCase()} on ${t!.sqlName}`, t!.sqlName, priv.columns, cols);
+      }
+    });
+  }
+});

package/dist/rules/sqlpg124.ts

@@ -0,0 +1,47 @@
+import { checkOf, tablesOf } from "./postgres-helpers";
+import { columnsOf, interpolatedTable, projectOf, typeIdentity } from "./postgres-names";
+
+/**
+ * SQLPG124: a foreign key to a `${}` table that names a column the table does
+ * not declare, or pairs columns whose types do not compare.
+ *
+ * Doc: https://www.postgresql.org/docs/18/ddl-constraints.html#DDL-CONSTRAINTS-FK
+ * and https://www.postgresql.org/docs/18/catalog-pg-type.html#CATALOG-TYPCATEGORY-TABLE.
+ * The server refuses `column "idd" referenced in foreign key constraint does
+ * not exist` and `Key columns "customer_id" and "id" are of incompatible
+ * types: text and bigint`. Types compare by their catalog category: `integer`
+ * to `bigint` (both numeric) passes, `text` to `bigint` fails. The
+ * user-defined category (`uuid`, `bytea`, `jsonb`...) compares by type; a
+ * domain by its base type; an enum by itself. A key to a table named in plain
+ * text, or a type outside the project, is left to the server.
+ */
+export const sqlpg124 = checkOf({ id: "SQLPG124", description: "A foreign key names a column the referenced table lacks, or one of another type category" }, (ctx, report) => {
+  const p = projectOf(ctx);
+  for (const t of tablesOf(ctx)) {
+    const own = columnsOf(p, t);
+    for (const fk of t.foreignKeys) {
+      const ref = interpolatedTable(p, (fk as { references?: unknown }).references, fk.refTable);
+      const refCols = ref && columnsOf(p, ref);
+      if (!ref || !refCols) continue;
+      const targets = fk.refColumns.length > 0 ? fk.refColumns : (ref.primaryKey?.columns ?? []);
+      const missing = targets.filter((c) => !refCols.has(c));
+      for (const c of missing) {
+        report({ severity: "error", message: `${t.export} (${t.sqlName}) has a foreign key on (${fk.columns.join(", ")}) to ${ref.sqlName} (${c}), which ${ref.sqlName} does not declare`, entity: t.export });
+      }
+      if (missing.length > 0 || !own || targets.length !== fk.columns.length) continue;
+      fk.columns.forEach((c, n) => {
+        const mine = own.get(c);
+        const theirs = refCols.get(targets[n]!);
+        if (!mine || !theirs) return;
+        const a = typeIdentity(p, mine.type);
+        const b = typeIdentity(p, theirs.type);
+        if (a === undefined || b === undefined || a === b) return;
+        report({
+          severity: "error",
+          message: `${t.export} (${t.sqlName}) has a foreign key from ${c} (${mine.type}) to ${ref.sqlName} (${targets[n]}) (${theirs.type}); the types do not compare, so Postgres refuses the key`,
+          entity: t.export,
+        });
+      });
+    }
+  }
+});

package/dist/rules/sqlpg125.ts

@@ -0,0 +1,40 @@
+import { checkOf, indexesOf } from "./postgres-helpers";
+import { parseIndexElement, projectOf, resolveMethod, resolveOpClass } from "./postgres-names";
+
+/**
+ * SQLPG125: an index access method or operator class the target major does
+ * not have, or an operator class that is not for the index's method.
+ *
+ * Doc: https://www.postgresql.org/docs/18/sql-createindex.html and
+ * https://www.postgresql.org/docs/18/indexes-opclass.html. The server refuses
+ * `access method "btreee" does not exist` and `operator class "numeric_opz"
+ * does not exist for access method "btree"` at CREATE. Methods and operator
+ * classes come from the target major's catalog (`pg_am`, `pg_opclass`). The
+ * ones an extension adds (`gin_trgm_ops` from pg_trgm, `hnsw` from vector)
+ * pass when the project declares that extension and are an error naming it
+ * when it does not; one neither the catalog nor the extension overlay knows is
+ * a warning when the project declares any extension. An operator class
+ * qualified with a schema the project does not declare is left alone.
+ */
+export const sqlpg125 = checkOf({ id: "SQLPG125", description: "An index access method or operator class the target major does not have, or not for that method" }, (ctx, report) => {
+  const p = projectOf(ctx);
+  for (const i of indexesOf(ctx)) {
+    const method = i.method ?? "btree";
+    const m = resolveMethod(p, method);
+    if (!m.ok) {
+      report({ severity: m.miss.severity, message: `${i.export} (${i.sqlName}) uses the index access method ${method}, which Postgres ${p.major} does not have${m.miss.note}`, entity: i.export });
+      continue;
+    }
+    for (const e of i.elements) {
+      const opclass = parseIndexElement(e.expr)?.opclass;
+      if (!opclass) continue;
+      const r = resolveOpClass(p, method, opclass);
+      if (r.ok) continue;
+      const label = `${opclass.schema ? `${opclass.schema}.` : ""}${opclass.name}`;
+      const message = r.otherMethods
+        ? `${i.export} (${i.sqlName}) uses the operator class ${label}, which is for ${r.otherMethods.join(", ")}, not ${method}`
+        : `${i.export} (${i.sqlName}) uses the operator class ${label}, which Postgres ${p.major} does not have for ${method}${r.miss.note}`;
+      report({ severity: r.miss.severity, message, entity: i.export });
+    }
+  }
+});

package/dist/rules/sqlpg126.ts

@@ -0,0 +1,37 @@
+import { checkOf } from "./postgres-helpers";
+import { callsIn, expressionsOf, projectOf, resolveCall } from "./postgres-names";
+
+/**
+ * SQLPG126: a call to a function the target major does not have, in a column
+ * `DEFAULT`, a generated column, a `CHECK` (a table's or a domain's), or an
+ * index expression.
+ *
+ * Doc: https://www.postgresql.org/docs/18/functions.html. The server refuses
+ * `function noww() does not exist` at CREATE. A name counts when it is in
+ * the target major's `pg_proc`, a function or procedure the project declares,
+ * a type name used as a cast (`int4(x)`), or qualified with a schema the
+ * project does not declare. Only a name directly followed by `(`, outside
+ * string literals, is a call; the grammar's own constructs that read like
+ * calls (`COALESCE`, `NULLIF`, `GREATEST`, `LEAST`, `CAST`, `EXTRACT`, `ROW`,
+ * `ARRAY`, `EXISTS`, `IN`, `ANY`, `ALL`, `SOME`, and the key word forms of
+ * `OVERLAY`, `POSITION`, `SUBSTRING` and `TRIM`) are reserved or column-name
+ * key words, not `pg_proc` names, and are skipped by their key word category.
+ * An error, or a warning when the project declares an extension.
+ */
+export const sqlpg126 = checkOf({ id: "SQLPG126", description: "An expression calls a function the target major does not have" }, (ctx, report) => {
+  const p = projectOf(ctx);
+  for (const o of p.objects) {
+    const seen = new Set<string>();
+    for (const { where, expr } of expressionsOf(o)) {
+      for (const c of callsIn(expr)) {
+        const label = `${c.schema ? `${c.schema}.` : ""}${c.name}`;
+        if (seen.has(`${where}\0${label}`)) continue;
+        seen.add(`${where}\0${label}`);
+        const r = resolveCall(p, c);
+        if (r.ok) continue;
+        const why = r.since !== undefined ? `, which needs Postgres ${r.since}; Postgres ${p.major} does not have it` : r.until !== undefined ? `, which Postgres removed after ${r.until}` : `, which Postgres ${p.major} does not have`;
+        report({ severity: r.miss.severity, message: `${o.export} (${o.sqlName as string}) ${where} calls ${label}()${why}${r.miss.note}`, entity: o.export });
+      }
+    }
+  }
+});

package/dist/rules/typed-names.ts

@@ -0,0 +1,120 @@
+/**
+ * What the typed-column rules (SQLPG005, SQLCH004; chant #3751) share: reading
+ * a tag's type argument, comparing it with the name the template declares, and
+ * reading the names the generated `sql-types.d.ts` lists.
+ *
+ * The type argument is `table<"shop.orders">\`CREATE TABLE ...\``. tsc checks
+ * that it names an entry of the generated file's `SqlSchema` only when the
+ * argument is a constraint, and an unlisted name falls back to unchecked
+ * columns, so a mistyped argument is silent without these rules.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import * as ts from "typescript";
+
+/** The generated file's name, beside the source (`chant sql types`). */
+export const SQL_TYPES_FILE = "sql-types.d.ts";
+
+/** A tag's type argument, when it is a string literal: `table<"shop.orders">`. */
+export function typeArgumentName(node: ts.TaggedTemplateExpression): { name: string; node: ts.LiteralTypeNode } | undefined {
+  const arg = node.typeArguments?.[0];
+  if (!arg || node.typeArguments!.length !== 1) return undefined;
+  if (!ts.isLiteralTypeNode(arg) || !ts.isStringLiteral(arg.literal)) return undefined;
+  return { name: arg.literal.text, node: arg };
+}
+
+/** Split a dotted name outside quotes and take the quotes off: `shop."Order Items"` is `shop`, `Order Items`. */
+export function splitQualified(name: string): string[] {
+  const pieces: string[] = [];
+  let cur = "";
+  let quote: string | undefined;
+  for (let i = 0; i < name.length; i++) {
+    const c = name[i]!;
+    if (quote) {
+      if (c === quote && name[i + 1] === quote) {
+        cur += c;
+        i++;
+      } else if (c === quote) quote = undefined;
+      else cur += c;
+    } else if (c === '"' || c === "`") quote = c;
+    else if (c === ".") {
+      pieces.push(cur);
+      cur = "";
+    } else cur += c;
+  }
+  pieces.push(cur);
+  return pieces;
+}
+
+/**
+ * Whether the declared name (an empty piece is an interpolation, which lint
+ * cannot read) can be the type argument's. Compared from the last piece back.
+ * A template that does not qualify its name takes the argument's schema, since
+ * the build qualifies it with the schema or database the project sets; one
+ * that does qualify it must agree with the argument.
+ */
+export function nameAgrees(declared: readonly string[], argument: string): boolean {
+  const given = splitQualified(argument);
+  if (declared.length === 0) return true;
+  if (declared.length > given.length) return false;
+  for (let i = 1; i <= declared.length; i++) {
+    const d = declared[declared.length - i]!;
+    if (d === "") continue;
+    if (d !== given[given.length - i]) return false;
+  }
+  return true;
+}
+
+/** The text of a declared name for a message; an interpolation is `${...}`. */
+export const declaredText = (declared: readonly string[]): string => declared.map((p) => (p === "" ? "${...}" : p)).join(".");
+
+/** A qualified name with quoting taken off, so `"shop"."orders"` and `shop.orders` compare equal. */
+export const normalizedName = (name: string): string => splitQualified(name).join("\0");
+
+/** The names (normalized, see {@link normalizedName}) a `declare module "<module>"` block in a generated file augments `SqlSchema` with. */
+export function namesInGenerated(content: string, module: string): Set<string> | undefined {
+  const source = ts.createSourceFile(SQL_TYPES_FILE, content, ts.ScriptTarget.Latest, true);
+  let names: Set<string> | undefined;
+  for (const stmt of source.statements) {
+    if (!ts.isModuleDeclaration(stmt) || !ts.isStringLiteral(stmt.name) || stmt.name.text !== module) continue;
+    if (!stmt.body || !ts.isModuleBlock(stmt.body)) continue;
+    for (const inner of stmt.body.statements) {
+      if (!ts.isInterfaceDeclaration(inner) || inner.name.text !== "SqlSchema") continue;
+      names ??= new Set();
+      for (const member of inner.members) {
+        const n = member.name;
+        if (n && (ts.isStringLiteral(n) || ts.isIdentifier(n))) names.add(normalizedName(n.text));
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * The generated file nearest above a source file, up to the directory that
+ * holds the project's config. `chant sql types` writes it in `sourceDir` (or
+ * the project root), so the walk finds it from any file below.
+ */
+export function findGeneratedFile(filePath: string): string | undefined {
+  let dir = dirname(resolve(filePath));
+  for (;;) {
+    const candidate = join(dir, SQL_TYPES_FILE);
+    if (existsSync(candidate)) return candidate;
+    if (existsSync(join(dir, "chant.config.ts")) || existsSync(join(dir, "chant.config.json"))) return undefined;
+    const up = dirname(dir);
+    if (up === dir) return undefined;
+    dir = up;
+  }
+}
+
+/** The names the generated file lists for a dialect's module, or undefined when there is no file or it has no such block. */
+export function generatedNamesFor(filePath: string, module: string): Set<string> | undefined {
+  const found = findGeneratedFile(filePath);
+  if (!found) return undefined;
+  try {
+    return namesInGenerated(readFileSync(found, "utf8"), module);
+  } catch {
+    return undefined;
+  }
+}

package/dist/sql-types-command.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `chant sql types [--output <path>] [--check]` (#3751): build the project the way
+ * `chant build` does, folded, and write the declarations
+ * {@link renderSqlTypes} renders from its entities, so a tag given its
+ * qualified name as the type argument has typed columns.
+ *
+ * The file goes to `<sourceDir>/sql-types.d.ts` (the project root when
+ * `sourceDir` is unset), where any tsconfig that includes the schema includes
+ * it too. `--output` puts it elsewhere, as a workspace `generated` entry's
+ * generator does. The command refuses to write beside a `sql-types.ts`: tsc
+ * resolves the `.ts` first and would drop the declarations. `chant build`
+ * never writes the file. `--check` renders the same text and compares it with
+ * the file instead of writing it: exit 1, naming the file, when they differ.
+ */
+import type { CommandGroupContext } from "@intentius/chant/cli/command-group";
+/** The file tsc would read instead of `path`: `sql-types.ts` beside `sql-types.d.ts`. */
+export declare function shadowingSource(path: string): string | undefined;
+export declare function runTypes(ctx: CommandGroupContext): Promise<number>;
+//# sourceMappingURL=sql-types-command.d.ts.map

package/dist/sql-types-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-types-command.d.ts","sourceRoot":"","sources":["../src/sql-types-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAqB9E,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIhE;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqDxE"}

package/dist/sql-types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The declarations `chant sql types` writes (#3751): one `sql-types.d.ts`
+ * that augments the dialect's `SqlSchema` with every table, view and
+ * dictionary the build declares, keyed by qualified name.
+ *
+ * {@link renderSqlTypes} is pure: the entities of a build in, the file's text
+ * out. It reads the objects as the serializer writes them, so a `.sql`
+ * file's objects and a composite's members are covered exactly as the build
+ * covers them, and it reads each template's slot record (`core/typed.ts`) for
+ * the `${}` positions a foreign key or a sort key consumes.
+ *
+ * Each column is a `Column<sqlType, { ts, nullable, cmp }>`:
+ *
+ * - `sqlType` is the type as the catalog spells it (`bigint`,
+ *   `timestamp(3) with time zone`, `Nullable(String)`);
+ * - `ts` is its value in application code (`./postgres/row-types.ts`,
+ *   `./clickhouse/row-types.ts`);
+ * - `nullable` is whether the value can be NULL. A Postgres view's columns
+ *   always can, as the server's own catalog says; a column whose type the
+ *   generator cannot tell is `never`, which fits every slot;
+ * - `cmp` is how it compares in a key: SQLPG124's type identity in Postgres
+ *   (`./lint/post-synth/postgres-names.ts`'s `typeIdentity`), the type
+ *   family in ClickHouse; `never` when it cannot be told.
+ *
+ * A view's column that is one column reference (`${t.columns.c}`, `o.${t.columns.c}`)
+ * is that column's type; any other expression is `unknown`.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+import type { SqlDialect } from "./dialects.js";
+/** The file `chant sql types` writes, in the project's source directory. */
+export declare const SQL_TYPES_FILE = "sql-types.d.ts";
+/**
+ * Where `chant sql types` writes the file by default: the project's
+ * `sourceDir`, or the project root when it is unset.
+ */
+export declare function sqlTypesPath(projectDir: string, config: Record<string, unknown> | undefined): string;
+/** The file on disk against what the build's entities render: `missing`, `stale` or `current`. */
+export declare function sqlTypesState(entities: ReadonlyMap<string, Declarable>, file: string, opts?: RenderSqlTypesOptions): "missing" | "stale" | "current";
+/** The module each dialect's `SqlSchema` is augmented in. */
+export declare const SQL_TYPES_MODULE: Readonly<Record<SqlDialect, string>>;
+export interface RenderSqlTypesOptions {
+    /** The directory each declaration's source file is named relative to. Default: the working directory. */
+    projectDir?: string;
+    /** The project's config: `sql.postgresMajor` for the catalog, `sql.dialect` when nothing is declared. */
+    config?: Record<string, unknown>;
+}
+/**
+ * The `sql-types.d.ts` for a build's entities: one module that augments the
+ * dialect's `SqlSchema` with each table, view and dictionary, in key order.
+ * Pure, so a check can render it in memory and compare it with the file.
+ */
+export declare function renderSqlTypes(entities: ReadonlyMap<string, Declarable>, opts?: RenderSqlTypesOptions): string;
+//# sourceMappingURL=sql-types.d.ts.map

package/dist/sql-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-types.d.ts","sourceRoot":"","sources":["../src/sql-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAW9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAQ7C,4EAA4E;AAC5E,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAGpG;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,EACzC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,qBAA0B,GAC/B,SAAS,GAAG,OAAO,GAAG,SAAS,CASjC;AAED,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAGjE,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,yGAAyG;IACzG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yGAAyG;IACzG,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAiOD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,IAAI,GAAE,qBAA0B,GAAG,MAAM,CAiClH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-sql",
-  "version": "0.121.1",
+  "version": "0.123.0",
   "description": "SQL lexicon for chant — database schema as typed declarations, one dialect at a time; ClickHouse first, with types read from a pinned server's catalog",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -70,7 +70,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.121.1",
+    "@intentius/chant": "^0.123.0",
     "typescript": "^5.9.3"
   }
 }

package/src/clickhouse/catalog-types.ts

@@ -56,6 +56,15 @@ export interface TypeFamilySpec {
   caseInsensitive: boolean;
 }
 
+/** A function the server has: \`system.functions\`. */
+export interface FunctionSpec {
+  aggregate: boolean;
+  /** The server resolves the name in any case. */
+  caseInsensitive: boolean;
+  /** The function this name is an alias of. */
+  aliasOf?: string;
+}
+
 export interface CodecSpec {
   compression: boolean;
   generic: boolean;

package/src/clickhouse/dictionary.test.ts

@@ -171,7 +171,7 @@ describe("importing a dictionary", () => {
     ]);
     const [file] = new ClickHouseGenerator().generate(ir);
     expect(file!.content).toContain('import { database, dictionary } from "@intentius/chant-lexicon-sql/clickhouse";');
-    expect(file!.content).toContain("export const ratesDict = dictionary`");
+    expect(file!.content).toContain(`export const ratesDict = dictionary<"shop.rates_dict">\``);
     expect(file!.content).toContain("CREATE DICTIONARY ${shopDb}.rates_dict");
   });
 });

package/src/clickhouse/entities.ts

@@ -46,10 +46,12 @@ import { feed, lineage, spanText as text, splice as spliceWith, templateSyntaxEr
 import { SQL_LEXICON, SqlObject, isColumnRefOf, isSqlObjectOf, makeSqlEntity } from "../core/entity";
 import type { LineageEdge } from "../core/references";
 import { SqlLiteral, SqlTemplateError, describeValue as describe, stripUnset as strip, templateParts } from "../core/template";
+import { setTypedSlots, type ColumnsIn, type Named, type RowIn, type SlotsIn, type TypedSlot, type Unnamed } from "../core/typed";
 
 export { SQL_LEXICON } from "../core/entity";
 export type { LineageEdge } from "../core/references";
 export { SqlLiteral, SqlTemplateError, templateParts, unescapeTemplateDelimiters } from "../core/template";
+export type { AnyColumn, Column, ColumnTraits, KeyColumn, Named, NotNullColumn, UncheckedColumn, Unnamed } from "../core/typed";
 
 export const CLICKHOUSE_ENTITY_TYPES = {
   database: "ClickHouse::Database",
@@ -198,18 +200,31 @@ export interface ClickHouseDatabase extends ClickHouseObject {
   readonly props: DatabaseProps;
 }
 
-/** A table or a view: something with columns that SQL can reference. */
-export interface ClickHouseRelation extends ClickHouseObject {
+/**
+ * Every ClickHouse table, view and dictionary the project declares, keyed by
+ * its qualified name (`shop.events`). Empty here; the `sql-types.d.ts` that
+ * `chant sql types` writes augments it, and a tag given the name as its type
+ * argument reads its columns from there.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmented by the generated declarations
+export interface SqlSchema {}
+
+/**
+ * A table or a view: something with columns that SQL can reference. `N` is
+ * its qualified name when its tag was given one (`` table<"shop.events">`...` ``):
+ * its columns are then the generated declarations' entry for that name.
+ */
+export interface ClickHouseRelation<N extends string = string> extends ClickHouseObject, Named<N> {
   /** One reference per column, by name: `${events.columns.user_id}`. */
-  readonly columns: Readonly<Record<string, AttrRef>>;
+  readonly columns: ColumnsIn<SqlSchema, N>;
 }
 
-export interface ClickHouseTable extends ClickHouseRelation {
+export interface ClickHouseTable<N extends string = string> extends ClickHouseRelation<N> {
   readonly entityType: "ClickHouse::Table";
   readonly props: TableProps;
 }
 
-export interface ClickHouseView extends ClickHouseRelation {
+export interface ClickHouseView<N extends string = string> extends ClickHouseRelation<N> {
   readonly entityType: "ClickHouse::View" | "ClickHouse::MaterializedView";
   readonly props: ViewProps;
 }
@@ -312,7 +327,7 @@ export interface ClickHouseGrant extends ClickHouseObject {
 }
 
 /** A dictionary: its attributes are columns `dictGet` reads, so SQL can reference them. */
-export interface ClickHouseDictionary extends ClickHouseRelation {
+export interface ClickHouseDictionary<N extends string = string> extends ClickHouseRelation<N> {
   readonly entityType: "ClickHouse::Dictionary";
   readonly props: DictionaryProps;
 }
@@ -327,6 +342,14 @@ function makeEntity(
   return makeSqlEntity(ClickHouseObject.prototype as ClickHouseObject, entityType, sqlName, props, columnNames, dependsOn);
 }
 
+/**
+ * A declared table's, view's or dictionary's row, for application code:
+ * `RowOf<typeof events>` for a declaration given its name, or
+ * `RowOf<"shop.users">` by name, which also covers an object only a `.sql`
+ * file declares.
+ */
+export type RowOf<T extends keyof SqlSchema | Named<keyof SqlSchema & string>> = RowIn<SqlSchema, T>;
+
 export function isClickHouseObject(value: unknown): value is ClickHouseObject {
   return isSqlObjectOf(value, "ClickHouse::");
 }
@@ -444,6 +467,42 @@ function qualified(ctx: Ctx, span: Span): { database?: string; name: string } {
   return pieces.length >= 2 ? { database: pieces[pieces.length - 2], name: pieces[pieces.length - 1]! } : { name: pieces[0] ?? "" };
 }
 
+/**
+ * The `${}` that stand alone as an element of a sort key (`ORDER BY ${t.columns.a}`,
+ * `ORDER BY (${t.columns.a}, b)`), each a column that must not be Nullable
+ * (#3751). An element inside an expression (`ifNull(${...}, '')`) is not one.
+ */
+function sortKeySlots(ctx: Ctx, span: Span | undefined): TypedSlot[] {
+  if (!span) return [];
+  let sig = ctx.tokens.slice(span.from, span.to).filter((t) => !isTrivia(t));
+  const isPunct = (i: number, p: string) => sig[i]?.kind === "punct" && sig[i]!.text === p;
+  if (isPunct(0, "(") && isPunct(sig.length - 1, ")")) {
+    let depth = 0;
+    let closesAt = -1;
+    for (let i = 0; i < sig.length && closesAt < 0; i++) {
+      if (isPunct(i, "(")) depth++;
+      else if (isPunct(i, ")") && --depth === 0) closesAt = i;
+    }
+    if (closesAt === sig.length - 1) sig = sig.slice(1, -1);
+  }
+  const out: TypedSlot[] = [];
+  let depth = 0;
+  let element: typeof sig = [];
+  const flush = () => {
+    const t = element[0];
+    if (element.length === 1 && t?.kind === "ref" && isColumnRef(ctx.values[t.part])) out.push({ index: t.part, kind: "sortKey" });
+    element = [];
+  };
+  for (const t of sig) {
+    if (t.kind === "punct" && t.text === "(") depth++;
+    else if (t.kind === "punct" && t.text === ")") depth--;
+    if (depth === 0 && t.kind === "punct" && t.text === ",") flush();
+    else element.push(t);
+  }
+  flush();
+  return out;
+}
+
 type Expect = "database" | "table" | "view" | "dictionary" | "func";
 
 function build(tag: Expect, strings: TemplateStringsArray | readonly string[], values: readonly unknown[]): ClickHouseObject {
@@ -484,6 +543,7 @@ function build(tag: Expect, strings: TemplateStringsArray | readonly string[], v
   };
   const done = <T extends ClickHouseObject>(entity: T): T => {
     setInterpolationFields(entity, ctx.fed.map((paths) => [...paths].sort()));
+    if (node.statement === "table" || node.statement === "view") setTypedSlots(entity, [...sortKeySlots(ctx, node.orderBy), ...sortKeySlots(ctx, node.primaryKey)]);
     return entity;
   };
 
@@ -625,17 +685,22 @@ export function database(strings: TemplateStringsArray, ...values: unknown[]): C
   return build("database", strings, values) as ClickHouseDatabase;
 }
 
-/** `` table`CREATE TABLE ...` ``: one ClickHouse table, parsed at build time. */
-export function table(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseTable {
-  return build("table", strings, values) as ClickHouseTable;
+/**
+ * `` table`CREATE TABLE ...` ``: one ClickHouse table, parsed at build time.
+ * Given its qualified name as the type argument (`` table<"shop.events">`...` ``),
+ * its columns are the ones `chant sql types` declared for that name.
+ */
+export function table<const N extends string = Unnamed>(strings: TemplateStringsArray, ...values: SlotsIn<SqlSchema, N>): ClickHouseTable<N> {
+  return build("table", strings, values) as ClickHouseTable<N>;
 }
 
 /**
  * `` view`CREATE [MATERIALIZED] VIEW ...` ``: one view or materialized view,
- * with the tables it reads and its column lineage.
+ * with the tables it reads and its column lineage. Takes its qualified name
+ * as the type argument, as {@link table} does.
  */
-export function view(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseView {
-  return build("view", strings, values) as ClickHouseView;
+export function view<const N extends string = Unnamed>(strings: TemplateStringsArray, ...values: SlotsIn<SqlSchema, N>): ClickHouseView<N> {
+  return build("view", strings, values) as ClickHouseView<N>;
 }
 
 /**
@@ -643,8 +708,8 @@ export function view(strings: TemplateStringsArray, ...values: unknown[]): Click
  * key, source, layout and lifetime, parsed at build time (#3682). Its
  * attributes are columns: `${rates.columns.rate}`.
  */
-export function dictionary(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseDictionary {
-  return build("dictionary", strings, values) as ClickHouseDictionary;
+export function dictionary<const N extends string = Unnamed>(strings: TemplateStringsArray, ...values: SlotsIn<SqlSchema, N>): ClickHouseDictionary<N> {
+  return build("dictionary", strings, values) as ClickHouseDictionary<N>;
 }
 
 /**

package/src/clickhouse/import/generator.ts

@@ -6,6 +6,7 @@
  * without import cycles.
  */
 
+import { relationKey } from "../../core/typed";
 import type { GeneratedFile, TypeScriptGenerator } from "@intentius/chant/import/generator";
 import type { TemplateIR } from "@intentius/chant/import/parser";
 import { isTrivia, tokenizeText, type Token } from "../tokens";
@@ -162,6 +163,11 @@ function indent(body: string): string {
   return lines.map((l, i) => (i === 0 || l.length === 0 ? l : `  ${l}`)).join("\n");
 }
 
+const RELATIONS = new Set<string>([CLICKHOUSE_ENTITY_TYPES.table, CLICKHOUSE_ENTITY_TYPES.view, CLICKHOUSE_ENTITY_TYPES.materializedView, CLICKHOUSE_ENTITY_TYPES.dictionary]);
+
+/** A table's, view's or dictionary's qualified name as its tag's type argument (#3751), so its columns are typed once `chant sql types` has run. */
+const typeArgument = (it: Item): string => (RELATIONS.has(it.type) ? `<${JSON.stringify(relationKey(it))}>` : "");
+
 export class ClickHouseGenerator implements TypeScriptGenerator {
   readonly ownsLayout = true;
 
@@ -186,7 +192,7 @@ export class ClickHouseGenerator implements TypeScriptGenerator {
     if (this.header) lines.push(...this.header.split("\n").map((l) => `// ${l}`), "");
     lines.push(`import { ${tags.join(", ")} } from "@intentius/chant-lexicon-sql/clickhouse";`, "");
     for (const it of order) {
-      lines.push(`export const ${it.exportName} = ${CLICKHOUSE_TAG_OF[it.type]}\`\n  ${indent(bodyText(bodies.get(it.exportName)!))}\`;`, "");
+      lines.push(`export const ${it.exportName} = ${CLICKHOUSE_TAG_OF[it.type]}${typeArgument(it)}\`\n  ${indent(bodyText(bodies.get(it.exportName)!))}\`;`, "");
     }
     return [{ path: "schema.ts", content: `${lines.join("\n").trimEnd()}\n` }];
   }

package/src/clickhouse/import/roundtrip.test.ts

@@ -64,7 +64,7 @@ describe("import, build, import again", () => {
       "ClickHouse::View",
       "ClickHouse::Table",
     ]);
-    expect(file!.content).toContain("export const events = table`");
+    expect(file!.content).toContain(`export const events = table<"analytics.events">\``);
   });
 
   test("the declarations build back to one statement per object, dependencies first", async () => {