@intentius/chant-lexicon-sql 0.121.1 → 0.123.0

package/src/lint/rules/sqlch004.ts

@@ -0,0 +1,81 @@
+import type { LintContext, LintDiagnostic, LintRule } from "@intentius/chant/lint/rule";
+import { parseCreate, unquote } from "../../clickhouse/parser";
+import { isTrivia, SqlSyntaxError } from "../../clickhouse/tokens";
+import { findTemplates, tokensOf } from "./templates";
+import { declaredText, generatedNamesFor, nameAgrees, normalizedName, SQL_TYPES_FILE, typeArgumentName } from "./typed-names";
+
+const MODULE = "@intentius/chant-lexicon-sql/clickhouse";
+
+/**
+ * SQLCH004: a typed ClickHouse tag whose type argument does not name the
+ * object its template declares, or is not in the generated `sql-types.d.ts`.
+ *
+ * `table<"shop.events">\`CREATE TABLE shop.events ...\``, and the same for
+ * `view` and `dictionary`, types `.columns` from the generated file's
+ * `SqlSchema["shop.events"]`. tsc does not compare the argument with the
+ * template's text, and an argument the file does not list falls back to
+ * unchecked columns, so a typo checks nothing and says nothing. The rule reads
+ * the declared name from the template (a database supplied by an interpolation
+ * is not known to lint, and is left out of the comparison) and the listed
+ * names from the nearest `sql-types.d.ts` above the file. With no generated
+ * file, only the first check runs. A name missing from the file is a warning,
+ * since an object added since the last `chant sql types` is stale and
+ * `chant sql types --check` is what fails on it.
+ */
+export const sqlch004: LintRule = {
+  id: "SQLCH004",
+  severity: "error",
+  category: "correctness",
+  description: "A ClickHouse tag's type argument does not name the object its template declares, or is not in sql-types.d.ts",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const source = context.sourceFile;
+    const out: LintDiagnostic[] = [];
+    let listed: Set<string> | undefined | null = null;
+    for (const found of findTemplates(source)) {
+      if (found.tag !== "table" && found.tag !== "view" && found.tag !== "dictionary") continue;
+      const arg = typeArgumentName(found.node);
+      if (!arg) continue;
+      const at = (() => {
+        const { line, character } = source.getLineAndCharacterOfPosition(arg.node.getStart(source));
+        return { line: line + 1, column: character + 1 };
+      })();
+      let declared: string[] | undefined;
+      try {
+        const tokens = tokensOf(found);
+        const node = parseCreate(tokens);
+        if (node.statement === found.tag) {
+          declared = tokens
+            .slice(node.name.from, node.name.to)
+            .filter((t) => !isTrivia(t) && !(t.kind === "punct" && t.text === "."))
+            .map((t) => (t.kind === "ref" ? "" : unquote(t.text)));
+        }
+      } catch (err) {
+        if (err instanceof SqlSyntaxError) continue; // SQLCH001 reports it
+        throw err;
+      }
+      if (!declared) continue; // SQLCH001: the tag holds another statement
+      if (!nameAgrees(declared, arg.name)) {
+        out.push({
+          ruleId: "SQLCH004",
+          severity: "error",
+          message: `${found.tag}<"${arg.name}"> names another object than the template declares (${declaredText(declared)}); the type argument is the qualified name the build renders`,
+          file: context.filePath,
+          ...at,
+        });
+        continue;
+      }
+      if (listed === null) listed = generatedNamesFor(context.filePath, MODULE);
+      if (listed && !listed.has(normalizedName(arg.name))) {
+        out.push({
+          ruleId: "SQLCH004",
+          severity: "warning",
+          message: `"${arg.name}" is not in ${SQL_TYPES_FILE}, so its columns are unchecked; run \`chant sql types\` to add it`,
+          file: context.filePath,
+          ...at,
+        });
+      }
+    }
+    return out;
+  },
+};

package/src/lint/rules/sqlpg005.ts

@@ -0,0 +1,73 @@
+import type { LintContext, LintDiagnostic, LintRule } from "@intentius/chant/lint/rule";
+import { parseStatements, SqlSyntaxError } from "../../postgres/parser";
+import { findPostgresTemplates, postgresTokensOf } from "./postgres-templates";
+import { declaredText, generatedNamesFor, nameAgrees, normalizedName, SQL_TYPES_FILE, typeArgumentName } from "./typed-names";
+
+const MODULE = "@intentius/chant-lexicon-sql/postgres";
+
+/**
+ * SQLPG005: a typed Postgres tag whose type argument does not name the object
+ * its template declares, or is not in the generated `sql-types.d.ts`.
+ *
+ * `table<"shop.orders">\`CREATE TABLE shop.orders ...\`` types `.columns` from
+ * the generated file's `SqlSchema["shop.orders"]`. tsc does not compare the
+ * argument with the template's text, and an argument the file does not list
+ * falls back to unchecked columns, so a typo checks nothing and says nothing.
+ * The rule reads the declared name from the template (a schema supplied by an
+ * interpolation is not known to lint, and is left out of the comparison) and
+ * the listed names from the nearest `sql-types.d.ts` above the file. With no
+ * generated file, only the first check runs. A name missing from the file is
+ * a warning, since a table added since the last `chant sql types` is stale
+ * and `chant sql types --check` is what fails on it.
+ */
+export const sqlpg005: LintRule = {
+  id: "SQLPG005",
+  severity: "error",
+  category: "correctness",
+  description: "A Postgres tag's type argument does not name the object its template declares, or is not in sql-types.d.ts",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const source = context.sourceFile;
+    const out: LintDiagnostic[] = [];
+    let listed: Set<string> | undefined | null = null;
+    for (const found of findPostgresTemplates(source)) {
+      if (found.tag !== "table" && found.tag !== "view") continue;
+      const arg = typeArgumentName(found.node);
+      if (!arg) continue;
+      const at = (() => {
+        const { line, character } = source.getLineAndCharacterOfPosition(arg.node.getStart(source));
+        return { line: line + 1, column: character + 1 };
+      })();
+      let declared: string[] | undefined;
+      try {
+        const node = parseStatements(postgresTokensOf(found))[0];
+        if (node && (node.statement === "table" || node.statement === "view")) declared = node.name.pieces;
+      } catch (err) {
+        if (err instanceof SqlSyntaxError) continue; // SQLPG001 reports it
+        throw err;
+      }
+      if (!declared) continue; // SQLPG001: the tag holds another statement
+      if (!nameAgrees(declared, arg.name)) {
+        out.push({
+          ruleId: "SQLPG005",
+          severity: "error",
+          message: `${found.tag}<"${arg.name}"> names another object than the template declares (${declaredText(declared)}); the type argument is the qualified name the build renders`,
+          file: context.filePath,
+          ...at,
+        });
+        continue;
+      }
+      if (listed === null) listed = generatedNamesFor(context.filePath, MODULE);
+      if (listed && !listed.has(normalizedName(arg.name))) {
+        out.push({
+          ruleId: "SQLPG005",
+          severity: "warning",
+          message: `"${arg.name}" is not in ${SQL_TYPES_FILE}, so its columns are unchecked; run \`chant sql types\` to add it`,
+          file: context.filePath,
+          ...at,
+        });
+      }
+    }
+    return out;
+  },
+};

package/src/lint/rules/typed-names.test.ts

@@ -0,0 +1,151 @@
+import * as ts from "typescript";
+import { mkdirSync, mkdtempSync, realpathSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import type { LintContext } from "@intentius/chant/lint/rule";
+import { sqlch004 } from "./sqlch004";
+import { sqlpg005 } from "./sqlpg005";
+import { nameAgrees, namesInGenerated, normalizedName, splitQualified } from "./typed-names";
+
+const PG = "@intentius/chant-lexicon-sql/postgres";
+const CH = "@intentius/chant-lexicon-sql/clickhouse";
+
+const ctx = (code: string, filePath = "schema.ts"): LintContext => ({
+  sourceFile: ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest, true),
+  entities: [],
+  filePath,
+});
+
+const generated = (module: string, names: string[]): string =>
+  `// Generated by chant — do not edit directly.\nimport type { Column } from "${module}";\n\ndeclare module "${module}" {\n  interface SqlSchema {\n` +
+  names.map((n) => `    /** src/schema.ts */\n    ${JSON.stringify(n)}: { columns: { id: Column<"bigint", { ts: string; nullable: false; cmp: "N" }> } };\n`).join("") +
+  "  }\n}\n";
+
+/** A project directory with the generated file in src/ and a source file under src/db/. */
+function project(module: string, names: string[] | undefined): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-3751-")));
+  mkdirSync(join(root, "src", "db"), { recursive: true });
+  writeFileSync(join(root, "chant.config.json"), "{}");
+  if (names) writeFileSync(join(root, "src", "sql-types.d.ts"), generated(module, names));
+  return join(root, "src", "db", "schema.ts");
+}
+
+describe("typed-names helpers", () => {
+  test("splitQualified takes quotes off and splits outside them", () => {
+    expect(splitQualified('shop."Order.Items"')).toEqual(["shop", "Order.Items"]);
+    expect(splitQualified("orders")).toEqual(["orders"]);
+    expect(normalizedName('"shop"."orders"')).toBe(normalizedName("shop.orders"));
+  });
+
+  test("nameAgrees compares from the last piece and skips interpolations", () => {
+    expect(nameAgrees(["shop", "orders"], "shop.orders")).toBe(true);
+    expect(nameAgrees(["orders"], "shop.orders")).toBe(true);
+    expect(nameAgrees(["", "orders"], "shop.orders")).toBe(true);
+    expect(nameAgrees(["shop", "orders"], "orders")).toBe(false);
+    expect(nameAgrees(["shop", "orders"], "shop.ordrs")).toBe(false);
+    expect(nameAgrees(["other", "orders"], "shop.orders")).toBe(false);
+  });
+
+  test("namesInGenerated reads only the module's SqlSchema", () => {
+    const text = generated(PG, ["shop.orders", "shop.users"]);
+    expect(namesInGenerated(text, PG)).toEqual(new Set([normalizedName("shop.orders"), normalizedName("shop.users")]));
+    expect(namesInGenerated(text, CH)).toBeUndefined();
+  });
+});
+
+const PGX = `import { table, view } from "${PG}";\n`;
+const CHX = `import { table, view, dictionary } from "${CH}";\n`;
+
+describe("SQLPG005: a typed Postgres tag's type argument", () => {
+  test("a name that agrees with the template, with no generated file, is clean", () => {
+    const code = `${PGX}export const o = table<"shop.orders">\`CREATE TABLE shop.orders (id bigint)\`;`;
+    expect(sqlpg005.check(ctx(code))).toEqual([]);
+  });
+
+  test("a different name is an error, at the type argument", () => {
+    const code = `${PGX}export const o = table<"shop.ordrs">\`CREATE TABLE shop.orders (id bigint)\`;`;
+    const [d, ...rest] = sqlpg005.check(ctx(code));
+    expect(rest).toEqual([]);
+    expect(d).toMatchObject({ ruleId: "SQLPG005", severity: "error", line: 2, column: 24 });
+    expect(d!.message).toContain("shop.orders");
+  });
+
+  test("a schema that is an interpolation is left out of the comparison", () => {
+    const ok = `${PGX}import { shopSchema } from "./s";\nexport const o = table<"shop.orders">\`CREATE TABLE \${shopSchema}.orders (id bigint)\`;`;
+    expect(sqlpg005.check(ctx(ok))).toEqual([]);
+    const bad = ok.replace("shop.orders", "shop.items");
+    expect(sqlpg005.check(ctx(bad))).toHaveLength(1);
+  });
+
+  test("a view is read too, and quoting and case folding follow Postgres", () => {
+    const ok = `${PGX}export const v = view<"app.order_totals">\`CREATE VIEW App."order_totals" AS SELECT 1\`;`;
+    expect(sqlpg005.check(ctx(ok))).toEqual([]);
+    const bad = `${PGX}export const v = view<"app.Order_Totals">\`CREATE VIEW app.order_totals AS SELECT 1\`;`;
+    expect(sqlpg005.check(ctx(bad))).toHaveLength(1);
+  });
+
+  test("a tag with no type argument, or a non-literal one, is not read", () => {
+    expect(sqlpg005.check(ctx(`${PGX}export const o = table\`CREATE TABLE shop.orders (id bigint)\`;`))).toEqual([]);
+    expect(sqlpg005.check(ctx(`${PGX}export const o = table<string>\`CREATE TABLE shop.orders (id bigint)\`;`))).toEqual([]);
+  });
+
+  test("a tag from another module, or the ClickHouse tag, is not read", () => {
+    expect(sqlpg005.check(ctx(`import { table } from "./mine";\nexport const o = table<"x.y">\`not sql\`;`))).toEqual([]);
+    expect(sqlpg005.check(ctx(`${CHX}export const o = table<"a.b">\`CREATE TABLE c.d (id UInt64) ENGINE = Log\`;`))).toEqual([]);
+  });
+
+  test("a template that does not parse is SQLPG001's to report", () => {
+    expect(sqlpg005.check(ctx(`${PGX}export const o = table<"a.b">\`CREATE TABLE\`;`))).toEqual([]);
+  });
+
+  test("a name the generated file lacks is a warning; one it lists is clean", () => {
+    const file = project(PG, ["shop.users"]);
+    const code = `${PGX}export const o = table<"shop.orders">\`CREATE TABLE shop.orders (id bigint)\`;\nexport const u = table<"shop.users">\`CREATE TABLE shop.users (id bigint)\`;`;
+    const diags = sqlpg005.check(ctx(code, file));
+    expect(diags).toHaveLength(1);
+    expect(diags[0]).toMatchObject({ ruleId: "SQLPG005", severity: "warning", line: 2 });
+    expect(diags[0]!.message).toMatch(/not in sql-types\.d\.ts.*chant sql types/);
+  });
+
+  test("a generated file with no block for the dialect is silent", () => {
+    const file = project(CH, ["shop.events"]);
+    const code = `${PGX}export const o = table<"shop.orders">\`CREATE TABLE shop.orders (id bigint)\`;`;
+    expect(sqlpg005.check(ctx(code, file))).toEqual([]);
+  });
+});
+
+describe("SQLCH004: a typed ClickHouse tag's type argument", () => {
+  const ddl = (db: string) => `CREATE TABLE ${db}.events (id UInt64) ENGINE = Log`;
+
+  test("a name that agrees is clean; a different one is an error", () => {
+    expect(sqlch004.check(ctx(`${CHX}export const e = table<"shop.events">\`${ddl("shop")}\`;`))).toEqual([]);
+    const [d] = sqlch004.check(ctx(`${CHX}export const e = table<"shop.event">\`${ddl("shop")}\`;`));
+    expect(d).toMatchObject({ ruleId: "SQLCH004", severity: "error", line: 2 });
+  });
+
+  test("a database that is an interpolation is left out, and a name differing in case is a different name", () => {
+    expect(sqlch004.check(ctx(`${CHX}import { db } from "./d";\nexport const e = table<"shop.events">\`${ddl("${db}")}\`;`))).toEqual([]);
+    expect(sqlch004.check(ctx(`${CHX}export const e = table<"shop.Events">\`${ddl("shop")}\`;`))).toHaveLength(1);
+  });
+
+  test("a dictionary and a view are read", () => {
+    const dict = `${CHX}export const d = dictionary<"shop.codes">\`CREATE DICTIONARY shop.codes (id UInt64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'c')) LAYOUT(FLAT()) LIFETIME(0)\`;`;
+    expect(sqlch004.check(ctx(dict))).toEqual([]);
+    expect(sqlch004.check(ctx(dict.replace("shop.codes\"", "shop.cods\"")))).toHaveLength(1);
+    const view = `${CHX}export const v = view<"shop.v1">\`CREATE VIEW shop.v2 AS SELECT 1\`;`;
+    expect(sqlch004.check(ctx(view))).toHaveLength(1);
+  });
+
+  test("a name the generated file lacks is a warning", () => {
+    const file = project(CH, ["shop.other"]);
+    const [d] = sqlch004.check(ctx(`${CHX}export const e = table<"shop.events">\`${ddl("shop")}\`;`, file));
+    expect(d).toMatchObject({ ruleId: "SQLCH004", severity: "warning" });
+    expect(sqlch004.check(ctx(`${CHX}export const e = table<"shop.other">\`CREATE TABLE shop.other (id UInt64) ENGINE = Log\`;`, file))).toEqual([]);
+  });
+
+  test("without a generated file only the name comparison runs", () => {
+    const file = project(CH, undefined);
+    expect(sqlch004.check(ctx(`${CHX}export const e = table<"shop.events">\`${ddl("shop")}\`;`, file))).toEqual([]);
+  });
+});

package/src/lint/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/src/op/__snapshots__/watch-pipeline.test.ts.snap

@@ -15,7 +15,7 @@ concurrency:
 jobs:
   schema-watch:
     runs-on: docker
-    container: node:22-slim
+    container: node:22
     env:
       CLICKHOUSE_READER_USER: chant_reader
       CLICKHOUSE_READER_PASSWORD: '\${{ secrets.CLICKHOUSE_READER_PASSWORD }}'
@@ -47,7 +47,7 @@ permissions:
 jobs:
   schema-watch:
     runs-on: ubuntu-latest
-    container: node:22-slim
+    container: node:22
     env:
       CLICKHOUSE_READER_USER: chant_reader
       CLICKHOUSE_READER_PASSWORD: '\${{ secrets.CLICKHOUSE_READER_PASSWORD }}'
@@ -78,7 +78,7 @@ stages:
 
 schema-watch:
   stage: ops
-  image: node:22-slim
+  image: node:22
   resource_group: schema-watch
   variables:
     CLICKHOUSE_READER_USER: chant_reader

package/src/postgres/entities.ts

@@ -62,11 +62,13 @@ import { feed, lineage, spanText as text, splice as spliceWith, templateSyntaxEr
 import { SqlObject, isColumnRefOf, isSqlObjectOf, makeSqlEntity } from "../core/entity";
 import type { LineageEdge } from "../core/references";
 import { SqlLiteral, SqlTemplateError, describeValue as describe, stripUnset, 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 } from "../core/template";
 export { quoteIdent } from "./keywords";
+export type { AnyColumn, Column, ColumnTraits, KeyColumn, Named, NotNullColumn, UncheckedColumn, Unnamed } from "../core/typed";
 
 export { POSTGRES_ENTITY_TYPES, type PostgresEntityType } from "./entity-types";
 import { POSTGRES_ENTITY_TYPES, type PostgresEntityType } from "./entity-types";
@@ -431,18 +433,31 @@ export interface PostgresSchema extends PostgresObject {
   readonly props: SchemaProps;
 }
 
-/** A table or a view: something with columns that SQL can reference. */
-export interface PostgresRelation extends PostgresObject {
+/**
+ * Every Postgres table and view the project declares, keyed by its qualified
+ * name (`shop.orders`). 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.orders">`...` ``):
+ * its columns are then the generated declarations' entry for that name.
+ */
+export interface PostgresRelation<N extends string = string> extends PostgresObject, Named<N> {
   /** One reference per column, by its folded name: `${users.columns.email}`. */
-  readonly columns: Readonly<Record<string, AttrRef>>;
+  readonly columns: ColumnsIn<SqlSchema, N>;
 }
 
-export interface PostgresTable extends PostgresRelation {
+export interface PostgresTable<N extends string = string> extends PostgresRelation<N> {
   readonly entityType: "Postgres::Table";
   readonly props: TableProps;
 }
 
-export interface PostgresView extends PostgresRelation {
+export interface PostgresView<N extends string = string> extends PostgresRelation<N> {
   readonly entityType: "Postgres::View" | "Postgres::MaterializedView";
   readonly props: ViewProps;
 }
@@ -502,6 +517,13 @@ export interface PostgresGrant extends PostgresObject {
   readonly props: GrantProps | DefaultPrivilegesProps;
 }
 
+/**
+ * A declared table's or view's row, for application code: `RowOf<typeof orders>`
+ * 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 isPostgresObject(value: unknown): value is PostgresObject {
   return isSqlObjectOf(value, "Postgres::");
 }
@@ -816,6 +838,23 @@ function foreignKeyDef(ctx: Ctx, c: ConstraintNode, columns: string[]): ForeignK
   );
 }
 
+/**
+ * The `${}` in a foreign key's referenced column list that each name one
+ * column, paired with the referencing column at the same position (#3751).
+ * `chant sql types` types each as a column comparing like that one.
+ */
+function referenceSlots(ctx: Ctx, c: ConstraintNode, columns: readonly string[]): TypedSlot[] {
+  const out: TypedSlot[] = [];
+  c.references!.columns.forEach((x, n) => {
+    const column = columns[n];
+    if (x.name || column === undefined) return;
+    const sig = ctx.tokens.slice(x.span.from, x.span.to).filter((t) => !isTrivia(t));
+    const t = sig[0];
+    if (sig.length === 1 && t?.kind === "ref" && isColumnRef(ctx.values[t.part])) out.push({ index: t.part, kind: "references", column });
+  });
+  return out;
+}
+
 function exclusionDef(ctx: Ctx, c: ConstraintNode): ExclusionDef {
   return stripUnset({
     name: c.name,
@@ -1142,6 +1181,7 @@ function build(tag: PostgresTag, strings: TemplateStringsArray | readonly string
   const ddl = untokenize(tokens, (i) => render(values[i], i)).trim().replace(/;\s*$/, "");
   const source = { strings: rawParts };
   const dependsOn = [...new Set([...values, ...(joined?.refs ?? [])].filter((v) => isPostgresObject(v) || isColumnRef(v)))];
+  const slots: TypedSlot[] = [];
   const make = <T extends PostgresObject>(type: PostgresEntityType, q: { schema?: string; name: string }, props: object, columnNames?: readonly string[]): T => {
     const entity = makeSqlEntity(PostgresObject.prototype as PostgresObject, type, sqlNameOf(q), props, columnNames, dependsOn) as T;
     const fed = ctx.fed.map((paths) => [...paths].sort());
@@ -1152,6 +1192,7 @@ function build(tag: PostgresTag, strings: TemplateStringsArray | readonly string
       joined.original.forEach((orig, i) => (byOriginal[orig] = fed[i]!));
       setInterpolationFields(entity, byOriginal);
     }
+    setTypedSlots(entity, slots);
     return entity;
   };
 
@@ -1264,7 +1305,10 @@ function build(tag: PostgresTag, strings: TemplateStringsArray | readonly string
       const foreignKeys: ForeignKeyDef[] = [];
       const exclusions: ExclusionDef[] = [];
       const file = (c: ConstraintNode, cols: string[]) => {
-        if (c.kind === "FOREIGN KEY") foreignKeys.push(foreignKeyDef(ctx, c, cols));
+        if (c.kind === "FOREIGN KEY") {
+          foreignKeys.push(foreignKeyDef(ctx, c, cols));
+          slots.push(...referenceSlots(ctx, c, cols));
+        }
         else if (c.kind === "PRIMARY KEY") {
           if (primaryKey) throw new SqlTemplateError(tag, `${sqlNameOf(q)} declares more than one primary key`, 0, 0);
           primaryKey = keyDef(ctx, c, cols, "primaryKey");
@@ -1554,9 +1598,14 @@ export function schema(strings: TemplateStringsArray, ...values: unknown[]): Pos
   return build("schema", strings, values) as PostgresSchema;
 }
 
-/** `` table`CREATE TABLE ...` ``: one Postgres table with its columns and constraints, parsed at build time. */
-export function table(strings: TemplateStringsArray, ...values: unknown[]): PostgresTable {
-  return build("table", strings, values) as PostgresTable;
+/**
+ * `` table`CREATE TABLE ...` ``: one Postgres table with its columns and
+ * constraints, parsed at build time. Given its qualified name as the type
+ * argument (`` table<"shop.orders">`...` ``), 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>): PostgresTable<N> {
+  return build("table", strings, values) as PostgresTable<N>;
 }
 
 /** `` index`CREATE [UNIQUE] INDEX [CONCURRENTLY] name ON ...` ``: one named index. */
@@ -1564,9 +1613,13 @@ export function index(strings: TemplateStringsArray, ...values: unknown[]): Post
   return build("index", strings, values) as PostgresIndex;
 }
 
-/** `` view`CREATE [MATERIALIZED] VIEW ...` ``: one view or materialized view, with what it reads and its column lineage. */
-export function view(strings: TemplateStringsArray, ...values: unknown[]): PostgresView {
-  return build("view", strings, values) as PostgresView;
+/**
+ * `` view`CREATE [MATERIALIZED] VIEW ...` ``: one view or materialized view,
+ * with what it reads and its column lineage. Takes its qualified name as the
+ * type argument, as {@link table} does.
+ */
+export function view<const N extends string = Unnamed>(strings: TemplateStringsArray, ...values: SlotsIn<SqlSchema, N>): PostgresView<N> {
+  return build("view", strings, values) as PostgresView<N>;
 }
 
 /** `` sequence`CREATE SEQUENCE ...` ``: one sequence. Reference it as `nextval(${seq})`. */

package/src/postgres/import/generator.ts

@@ -21,6 +21,7 @@
  * references cross schemas freely.
  */
 
+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";
@@ -233,6 +234,11 @@ const indent = (body: string) =>
     .map((l, i) => (i === 0 || l.length === 0 ? l : `  ${l}`))
     .join("\n");
 
+const RELATIONS = new Set<string>([POSTGRES_ENTITY_TYPES.table, POSTGRES_ENTITY_TYPES.view, POSTGRES_ENTITY_TYPES.materializedView]);
+
+/** A table's or view'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 PostgresGenerator implements TypeScriptGenerator {
   readonly ownsLayout = true;
 
@@ -256,7 +262,7 @@ export class PostgresGenerator implements TypeScriptGenerator {
     const lines: string[] = [];
     if (this.header) lines.push(...this.header.split("\n").map((l) => `// ${l}`), "");
     lines.push(`import { ${tags.join(", ")} } from "@intentius/chant-lexicon-sql/postgres";`, "");
-    for (const it of order) lines.push(`export const ${it.exportName} = ${TAG[it.type]}\`\n  ${indent(bodyText(bodies.get(it.exportName)!))}\`;`, "");
+    for (const it of order) lines.push(`export const ${it.exportName} = ${TAG[it.type]}${typeArgument(it)}\`\n  ${indent(bodyText(bodies.get(it.exportName)!))}\`;`, "");
     return [{ path: "schema.ts", content: `${lines.join("\n").trimEnd()}\n` }];
   }
 }