@intentius/chant-lexicon-sql 0.122.0 → 0.123.0

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` }];
   }
 }

package/src/postgres/row-types.ts

@@ -0,0 +1,111 @@
+/**
+ * What a Postgres column's value is in TypeScript, for `RowOf` (#3751): the
+ * value node-postgres (`pg`, the driver the lexicon itself uses) hands back
+ * with its default type parsers. `bigint` and `numeric` are strings, since a
+ * JavaScript number cannot hold every value; `integer`, `smallint`, `real`
+ * and `double precision` are numbers; dates and timestamps are `Date`s;
+ * `json` and `jsonb` are parsed, so their shape is the application's
+ * (`unknown`); everything the driver does not parse is its text form.
+ *
+ * The table names every built-in type of every supported major's catalog
+ * (`COLUMN_TYPES`), and a test fails on one it does not, so a type a new
+ * catalog adds is a decision rather than a silent `unknown`.
+ */
+
+import type { TypeSqlName } from "../generated/postgres-types";
+
+const NUMBER = "number";
+const STRING = "string";
+const DATE = "Date";
+
+/** The TypeScript type of each built-in type's value, by its `format_type()` name. */
+export const POSTGRES_ROW_TYPES: Readonly<Record<TypeSqlName, string>> = {
+  // Numbers the driver parses; the 64-bit and arbitrary-precision ones stay text.
+  smallint: NUMBER,
+  integer: NUMBER,
+  real: NUMBER,
+  "double precision": NUMBER,
+  oid: NUMBER,
+  bigint: STRING,
+  numeric: STRING,
+  money: STRING,
+  regclass: STRING,
+  regcollation: STRING,
+  regconfig: STRING,
+  regdictionary: STRING,
+  regnamespace: STRING,
+  regoper: STRING,
+  regoperator: STRING,
+  regproc: STRING,
+  regprocedure: STRING,
+  regrole: STRING,
+  regtype: STRING,
+  boolean: "boolean",
+  // Strings.
+  text: STRING,
+  "character varying": STRING,
+  character: STRING,
+  name: STRING,
+  '"char"': STRING,
+  uuid: STRING,
+  xml: STRING,
+  bit: STRING,
+  "bit varying": STRING,
+  cidr: STRING,
+  inet: STRING,
+  macaddr: STRING,
+  macaddr8: STRING,
+  tsvector: STRING,
+  tsquery: STRING,
+  jsonpath: STRING,
+  pg_lsn: STRING,
+  pg_snapshot: STRING,
+  txid_snapshot: STRING,
+  refcursor: STRING,
+  aclitem: STRING,
+  cid: STRING,
+  tid: STRING,
+  xid: STRING,
+  xid8: STRING,
+  int2vector: STRING,
+  oidvector: STRING,
+  gtsvector: STRING,
+  pg_brin_bloom_summary: STRING,
+  pg_brin_minmax_multi_summary: STRING,
+  pg_dependencies: STRING,
+  pg_mcv_list: STRING,
+  pg_ndistinct: STRING,
+  pg_node_tree: STRING,
+  // Dates and times: the driver parses dates and timestamps, not times of day.
+  date: DATE,
+  "timestamp without time zone": DATE,
+  "timestamp with time zone": DATE,
+  "time without time zone": STRING,
+  "time with time zone": STRING,
+  interval: "{ years?: number; months?: number; days?: number; hours?: number; minutes?: number; seconds?: number; milliseconds?: number }",
+  // Ranges and multiranges arrive as their text form.
+  int4range: STRING,
+  int8range: STRING,
+  numrange: STRING,
+  tsrange: STRING,
+  tstzrange: STRING,
+  daterange: STRING,
+  int4multirange: STRING,
+  int8multirange: STRING,
+  nummultirange: STRING,
+  tsmultirange: STRING,
+  tstzmultirange: STRING,
+  datemultirange: STRING,
+  // Geometry: the driver parses a point and a circle.
+  point: "{ x: number; y: number }",
+  circle: "{ x: number; y: number; radius: number }",
+  line: STRING,
+  lseg: STRING,
+  box: STRING,
+  path: STRING,
+  polygon: STRING,
+  // Parsed, so the application's own shape.
+  json: "unknown",
+  jsonb: "unknown",
+  bytea: "Uint8Array",
+};

package/src/postgres.ts

@@ -69,6 +69,16 @@ export {
   type DefaultPrivilegesProps,
   type PrivilegeDef,
   type LineageEdge,
+  type SqlSchema,
+  type RowOf,
+  type Column,
+  type ColumnTraits,
+  type AnyColumn,
+  type UncheckedColumn,
+  type KeyColumn,
+  type NotNullColumn,
+  type Named,
+  type Unnamed,
 } from "./postgres/entities";
 
 export {

package/src/sql-types-command.ts

@@ -0,0 +1,99 @@
+/**
+ * `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 { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import type { CommandGroupContext } from "@intentius/chant/cli/command-group";
+import { renderSqlTypes, SQL_TYPES_FILE } from "./sql-types";
+
+const USAGE = "usage: chant sql types [--output <path>] [--check]";
+
+/** The `--output` value, or an error message. */
+function parseArgs(args: readonly string[]): { output?: string; check: boolean } | { error: string } {
+  let output: string | undefined;
+  let check = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--output") {
+      output = args[++i];
+      if (!output) return { error: "--output needs a path" };
+    } else if (a === "--check") check = true;
+    else if (a.startsWith("--output=")) output = a.slice("--output=".length);
+    else return { error: `unknown argument ${a}` };
+  }
+  return output === undefined ? { check } : { output, check };
+}
+
+/** The file tsc would read instead of `path`: `sql-types.ts` beside `sql-types.d.ts`. */
+export function shadowingSource(path: string): string | undefined {
+  if (!path.endsWith(".d.ts")) return undefined;
+  const source = `${path.slice(0, -".d.ts".length)}.ts`;
+  return existsSync(source) ? source : undefined;
+}
+
+export async function runTypes(ctx: CommandGroupContext): Promise<number> {
+  const args = parseArgs(ctx.rawArgs);
+  if ("error" in args) {
+    console.error(`${args.error}\n${USAGE}`);
+    return 1;
+  }
+  const cwd = process.cwd();
+  const { loadChantConfigUpward } = await import("@intentius/chant/config");
+  const { config, configPath } = await loadChantConfigUpward(cwd);
+  const projectDir = configPath ? dirname(configPath) : cwd;
+  const sourceDir = resolve(projectDir, config.sourceDir ?? ".");
+  const output = args.output !== undefined ? resolve(cwd, args.output) : join(sourceDir, SQL_TYPES_FILE);
+  const shadow = shadowingSource(output);
+  if (shadow) {
+    console.error(`chant sql types: ${relative(cwd, shadow) || basename(shadow)} sits beside ${relative(cwd, output) || basename(output)}, and tsc reads it instead of the declarations; rename one`);
+    return 1;
+  }
+
+  const { build } = await import("@intentius/chant/build");
+  const { resolveBuildModes, resolveProjectBuildOptions } = await import("@intentius/chant/cli/build-options");
+  const { loadPlugins, resolveProjectLexicons } = await import("@intentius/chant/cli/plugins");
+  const { sqlSerializer } = await import("./serializer");
+  const plugins = await loadPlugins(await resolveProjectLexicons(projectDir, { lexicon: "sql" }));
+  // The fold build's entities: what `chant build` declares, `.sql` files and composite members included.
+  const options = resolveProjectBuildOptions({ config, configDir: projectDir, plugins, modes: resolveBuildModes(config, { fold: true }) });
+  const result = await build(sourceDir, [sqlSerializer], undefined, options);
+  if (result.errors.length > 0) {
+    for (const e of result.errors) console.error(e instanceof Error ? e.message : String(e));
+    console.error("chant sql types: the build failed, so nothing was written");
+    return 1;
+  }
+  const text = renderSqlTypes(result.entities, { projectDir, config: config as unknown as Record<string, unknown> });
+  const shown = relative(cwd, output);
+  const named = shown && !shown.startsWith("..") ? shown : output;
+  if (args.check) {
+    // Compares only; the file is never written.
+    const onDisk = existsSync(output) ? readFileSync(output, "utf8") : undefined;
+    if (onDisk === text) {
+      console.log(`${named} is current`);
+      return 0;
+    }
+    console.error(
+      onDisk === undefined
+        ? `chant sql types: ${named} does not exist; run \`chant sql types\` to write it`
+        : `chant sql types: ${named} differs from what the build declares; run \`chant sql types\` to rewrite it`,
+    );
+    return 1;
+  }
+  mkdirSync(dirname(output), { recursive: true });
+  writeFileSync(output, text);
+  const count = (text.match(/^ {4}"/gm) ?? []).length;
+  console.log(`wrote ${named}: ${count} relation${count === 1 ? "" : "s"}`);
+  return 0;
+}

package/src/sql-types-staleness.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Keeping `sql-types.d.ts` current (#3751): `chant sql types --check` and the
+ * SQL102 post-synth check, over a scratch project. The project imports the
+ * workspace's sql lexicon through a `node_modules` link, as an installed
+ * project would.
+ */
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { lintCommand } from "@intentius/chant/cli/commands/lint";
+import { runTypes } from "./sql-types-command";
+import { sqlTypesPath } from "./sql-types";
+import { sql102 } from "./lint/post-synth/sql102";
+
+const repoNodeModules = resolve(fileURLToPath(new URL(".", import.meta.url)), "../../../node_modules");
+
+const schema = (amount: string) =>
+  'import { schema, table } from "@intentius/chant-lexicon-sql/postgres";\n' +
+  "export const shop = schema`CREATE SCHEMA shop`;\n" +
+  'export const orders = table<"shop.orders">`CREATE TABLE ${shop}.orders (id bigint PRIMARY KEY, ' +
+  `amount ${amount})\`;\n`;
+
+describe("sql-types.d.ts staleness", () => {
+  let root: string;
+  let cwd: string;
+  let errors: string[];
+
+  const write = (amount: string) => writeFileSync(join(root, "src", "schema.ts"), schema(amount));
+  const types = async (...args: string[]) => {
+    process.chdir(root);
+    return runTypes({ verb: "types", rawArgs: args });
+  };
+
+  beforeEach(() => {
+    cwd = process.cwd();
+    root = realpathSync(mkdtempSync(join(tmpdir(), "chant-3751-stale-")));
+    mkdirSync(join(root, "src"), { recursive: true });
+    symlinkSync(repoNodeModules, join(root, "node_modules"), "dir");
+    writeFileSync(join(root, "chant.config.json"), JSON.stringify({ lexicons: ["sql"], sourceDir: "src", sql: { dialect: "postgres" } }));
+    write("numeric(12,2)");
+    errors = [];
+    vi.spyOn(console, "error").mockImplementation((m: unknown) => void errors.push(String(m)));
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    process.env.NO_COLOR = "1";
+  });
+
+  afterEach(() => {
+    process.chdir(cwd);
+    vi.restoreAllMocks();
+    delete process.env.NO_COLOR;
+  });
+
+  test("--check exits 0 on a current file, and 1 naming it once the schema changes", async () => {
+    expect(await types()).toBe(0);
+    const file = join(root, "src", "sql-types.d.ts");
+    const written = readFileSync(file, "utf8");
+    expect(await types("--check")).toBe(0);
+
+    write("bigint");
+    expect(await types("--check")).toBe(1);
+    expect(errors.join("\n")).toContain("src/sql-types.d.ts differs");
+    expect(readFileSync(file, "utf8")).toBe(written);
+  });
+
+  test("--check on a missing file exits 1 and writes nothing", async () => {
+    expect(await types("--check")).toBe(1);
+    expect(errors.join("\n")).toContain("src/sql-types.d.ts does not exist");
+    expect(() => readFileSync(join(root, "src", "sql-types.d.ts"))).toThrow();
+  });
+
+  test("--check honours --output", async () => {
+    expect(await types("--output", "out/types.d.ts")).toBe(0);
+    expect(await types("--check", "--output", "out/types.d.ts")).toBe(0);
+    write("bigint");
+    expect(await types("--check", "--output", "out/types.d.ts")).toBe(1);
+    expect(errors.join("\n")).toContain("out/types.d.ts");
+  });
+
+  test("lint reports SQL102 for a stale file, and nothing for a current or missing one", async () => {
+    const ids = async () => (await lintCommand({ path: root, format: "stylish" })).diagnostics.map((d) => d.ruleId);
+    expect(await ids()).not.toContain("SQL102");
+
+    expect(await types()).toBe(0);
+    expect(await ids()).not.toContain("SQL102");
+
+    write("bigint");
+    const result = await lintCommand({ path: root, format: "stylish" });
+    const diag = result.diagnostics.find((d) => d.ruleId === "SQL102");
+    expect(diag, result.output).toBeDefined();
+    expect(diag!.severity).toBe("error");
+    expect(diag!.message).toContain("sql-types.d.ts");
+
+    expect(await types()).toBe(0);
+    expect(await ids()).not.toContain("SQL102");
+  });
+});
+
+describe("SQL102 on a hand-built context", () => {
+  test("is silent without a project directory", () => {
+    const ctx = { outputs: new Map(), entities: new Map(), buildResult: { outputs: new Map(), entities: new Map(), warnings: [], errors: [], sourceFileCount: 0 } };
+    expect(sql102.check(ctx)).toEqual([]);
+  });
+
+  test("the default path is the source directory, else the project root", () => {
+    expect(sqlTypesPath("/p", { sourceDir: "src" })).toBe("/p/src/sql-types.d.ts");
+    expect(sqlTypesPath("/p", {})).toBe("/p/sql-types.d.ts");
+  });
+});