@intentius/chant-lexicon-sql 0.121.1 → 0.123.0

package/src/postgres/overlays/extension-objects.ts

@@ -0,0 +1,100 @@
+/**
+ * What the common extensions add, for lint: the types, functions, index
+ * access methods and operator classes a declaration may name once the project
+ * declares the extension. The pinned catalogs are read from a server with no
+ * extension installed, so none of these are in them.
+ *
+ * The list is not exhaustive. A name the core catalog does not have and no
+ * entry here covers is reported as a warning when the project declares any
+ * extension (it may come from one), and as an error when it declares none.
+ * A name an entry here covers, used without that extension declared, is an
+ * error that names the extension.
+ *
+ * Sources: the reference page of each contrib module
+ * (https://www.postgresql.org/docs/18/contrib.html), PostGIS
+ * (https://postgis.net/docs/reference.html) and pgvector
+ * (https://github.com/pgvector/pgvector#reference).
+ */
+
+export interface ExtensionObjects {
+  types?: readonly string[];
+  functions?: readonly string[];
+  /** Function name prefixes the extension owns (`st_` for PostGIS). */
+  functionPrefixes?: readonly string[];
+  accessMethods?: readonly string[];
+  /** Operator classes by access method. */
+  opclasses?: Readonly<Record<string, readonly string[]>>;
+}
+
+const BTREE_GIN = [
+  "int2_ops", "int4_ops", "int8_ops", "float4_ops", "float8_ops", "money_ops", "oid_ops", "timestamp_ops", "timestamptz_ops",
+  "time_ops", "timetz_ops", "date_ops", "interval_ops", "macaddr_ops", "macaddr8_ops", "inet_ops", "cidr_ops", "text_ops",
+  "varchar_ops", "char_ops", "bytea_ops", "bit_ops", "varbit_ops", "numeric_ops", "enum_ops", "uuid_ops", "name_ops",
+  "bool_ops", "bpchar_ops",
+];
+const BTREE_GIST = [
+  "gist_int2_ops", "gist_int4_ops", "gist_int8_ops", "gist_float4_ops", "gist_float8_ops", "gist_numeric_ops", "gist_oid_ops",
+  "gist_timestamp_ops", "gist_timestamptz_ops", "gist_time_ops", "gist_timetz_ops", "gist_date_ops", "gist_interval_ops",
+  "gist_cash_ops", "gist_macaddr_ops", "gist_macaddr8_ops", "gist_text_ops", "gist_bpchar_ops", "gist_bytea_ops", "gist_bit_ops",
+  "gist_vbit_ops", "gist_inet_ops", "gist_cidr_ops", "gist_uuid_ops", "gist_enum_ops", "gist_bool_ops",
+];
+const VECTOR_OPS = ["vector_l2_ops", "vector_ip_ops", "vector_cosine_ops", "vector_l1_ops", "halfvec_l2_ops", "halfvec_ip_ops", "halfvec_cosine_ops", "halfvec_l1_ops", "sparsevec_l2_ops", "sparsevec_ip_ops", "sparsevec_cosine_ops", "sparsevec_l1_ops", "bit_hamming_ops", "bit_jaccard_ops"];
+
+export const EXTENSION_OBJECTS: Readonly<Record<string, ExtensionObjects>> = {
+  bloom: { accessMethods: ["bloom"], opclasses: { bloom: ["int4_ops", "text_ops"] } },
+  btree_gin: { opclasses: { gin: BTREE_GIN } },
+  btree_gist: { opclasses: { gist: BTREE_GIST } },
+  citext: { types: ["citext"], opclasses: { btree: ["citext_ops", "citext_pattern_ops"], hash: ["citext_ops"] } },
+  cube: { types: ["cube"], functions: ["cube", "cube_dim", "cube_ll_coord", "cube_ur_coord", "cube_is_point", "cube_enlarge", "cube_subset", "cube_union", "cube_inter", "cube_size", "cube_distance"], opclasses: { gist: ["gist_cube_ops"] } },
+  earthdistance: { types: ["earth"], functions: ["earth", "earth_distance", "earth_box", "ll_to_earth", "latitude", "longitude", "sec_to_gc", "gc_to_sec"] },
+  fuzzystrmatch: { functions: ["soundex", "difference", "levenshtein", "levenshtein_less_equal", "metaphone", "dmetaphone", "dmetaphone_alt", "daitch_mokotoff"] },
+  hstore: {
+    types: ["hstore"],
+    functions: ["hstore", "akeys", "avals", "skeys", "svals", "hstore_to_array", "hstore_to_matrix", "hstore_to_json", "hstore_to_jsonb", "hstore_to_json_loose", "hstore_to_jsonb_loose", "slice", "exist", "defined", "delete", "each", "populate_record"],
+    opclasses: { gist: ["gist_hstore_ops"], gin: ["gin_hstore_ops"], btree: ["btree_hstore_ops"], hash: ["hash_hstore_ops"] },
+  },
+  intarray: {
+    functions: ["icount", "sort", "sort_asc", "sort_desc", "uniq", "idx", "subarray", "intset"],
+    opclasses: { gist: ["gist__int_ops", "gist__intbig_ops"], gin: ["gin__int_ops"] },
+  },
+  isn: { types: ["ean13", "isbn", "isbn13", "ismn", "ismn13", "issn", "issn13", "upc"], functions: ["isn_weak", "make_valid", "is_valid"] },
+  ltree: {
+    types: ["ltree", "lquery", "ltxtquery"],
+    functions: ["subltree", "subpath", "nlevel", "index", "text2ltree", "ltree2text", "lca"],
+    opclasses: { gist: ["gist_ltree_ops", "gist__ltree_ops"], btree: ["ltree_ops"], hash: ["hash_ltree_ops"] },
+  },
+  pg_trgm: {
+    functions: ["similarity", "word_similarity", "strict_word_similarity", "show_trgm", "show_limit", "set_limit"],
+    opclasses: { gin: ["gin_trgm_ops"], gist: ["gist_trgm_ops"] },
+  },
+  pgcrypto: {
+    functions: [
+      "digest", "hmac", "crypt", "gen_salt", "gen_random_bytes", "gen_random_uuid", "encrypt", "decrypt", "encrypt_iv", "decrypt_iv",
+      "pgp_sym_encrypt", "pgp_sym_encrypt_bytea", "pgp_sym_decrypt", "pgp_sym_decrypt_bytea", "pgp_pub_encrypt", "pgp_pub_encrypt_bytea",
+      "pgp_pub_decrypt", "pgp_pub_decrypt_bytea", "pgp_key_id", "armor", "dearmor", "pgp_armor_headers",
+    ],
+  },
+  postgis: {
+    types: ["geometry", "geography", "box2d", "box3d"],
+    functionPrefixes: ["st_", "postgis_"],
+    opclasses: {
+      gist: ["gist_geometry_ops_2d", "gist_geometry_ops_nd", "gist_geography_ops"],
+      brin: ["brin_geometry_inclusion_ops_2d", "brin_geometry_inclusion_ops_3d", "brin_geometry_inclusion_ops_4d", "brin_geography_inclusion_ops"],
+      spgist: ["spgist_geometry_ops_2d", "spgist_geometry_ops_3d", "spgist_geometry_ops_nd", "spgist_geography_ops_nd"],
+      btree: ["btree_geometry_ops", "btree_geography_ops"],
+      hash: ["hash_geometry_ops"],
+    },
+  },
+  seg: { types: ["seg"], opclasses: { gist: ["gist_seg_ops"] } },
+  tablefunc: { functions: ["crosstab", "normal_rand", "connectby"] },
+  unaccent: { functions: ["unaccent"] },
+  "uuid-ossp": {
+    functions: ["uuid_generate_v1", "uuid_generate_v1mc", "uuid_generate_v3", "uuid_generate_v4", "uuid_generate_v5", "uuid_nil", "uuid_ns_dns", "uuid_ns_url", "uuid_ns_oid", "uuid_ns_x500"],
+  },
+  vector: {
+    types: ["vector", "halfvec", "sparsevec"],
+    functions: ["l2_distance", "inner_product", "cosine_distance", "l1_distance", "vector_dims", "vector_norm", "l2_norm", "l2_normalize", "binary_quantize", "subvector", "hamming_distance", "jaccard_distance"],
+    accessMethods: ["hnsw", "ivfflat"],
+    opclasses: { hnsw: VECTOR_OPS, ivfflat: VECTOR_OPS.filter((o) => !o.startsWith("sparsevec") && !o.endsWith("l1_ops") && o !== "bit_jaccard_ops") },
+  },
+};

package/src/postgres/overlays/types.ts

@@ -54,3 +54,28 @@ export const SERIAL_TYPES: Record<string, string> = {
 
 /** An array suffix: `integer[]`, `text[3]`, `ARRAY`. Dimensions are documentation only to the server. */
 export const ARRAY_SUFFIX = { brackets: "[]", dimensioned: "[n]", keyword: "ARRAY" } as const;
+
+/**
+ * Spellings the grammar accepts that neither `pg_type` nor {@link TYPE_SPELLINGS}
+ * lists, and the canonical name each stands for (gram.y, `Numeric`,
+ * `Character`, `ConstDatetime`). Lint reads them beside the catalog so every
+ * spelling Postgres accepts resolves. `float(p)` is `real` for p up to 24 and
+ * `double precision` above; lint reads the precision.
+ */
+export const GRAMMAR_TYPE_SPELLINGS: Record<string, string> = {
+  dec: "numeric",
+  "char varying": "character varying",
+  "national character": "character",
+  "national char": "character",
+  nchar: "character",
+  "national character varying": "character varying",
+  "national char varying": "character varying",
+  "nchar varying": "character varying",
+};
+
+/** The serial spellings with a width suffix, beside {@link SERIAL_TYPES}. */
+export const SERIAL_WIDTH_SPELLINGS: Record<string, string> = {
+  serial2: "smallint",
+  serial4: "integer",
+  serial8: "bigint",
+};

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");
+  });
+});

package/src/sql-types.test.ts

@@ -0,0 +1,132 @@
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import type { Declarable } from "@intentius/chant/declarable";
+import { COLUMN_TYPES } from "./generated/postgres";
+import { TYPE_FAMILIES } from "./generated/clickhouse";
+import { POSTGRES_ROW_TYPES } from "./postgres/row-types";
+import { CLICKHOUSE_ROW_TYPES, clickhouseRowType } from "./clickhouse/row-types";
+import * as pg from "./postgres/entities";
+import * as ch from "./clickhouse/entities";
+import { getTypedSlots, relationKey } from "./core/typed";
+import { sqlSerializer } from "./serializer";
+import { renderSqlTypes } from "./sql-types";
+import { runTypes, shadowingSource } from "./sql-types-command";
+
+const entities = (o: Record<string, unknown>) => new Map(Object.entries(o)) as Map<string, Declarable>;
+
+describe("the row type mapping covers the pinned catalogs", () => {
+  test("every Postgres built-in type of every supported major has a row type, and nothing else does", () => {
+    expect(Object.keys(POSTGRES_ROW_TYPES).sort()).toEqual(Object.keys(COLUMN_TYPES).sort());
+  });
+
+  test("every ClickHouse type family has a row type, and nothing else does", () => {
+    const families = [...new Set(Object.values(TYPE_FAMILIES).map((f) => f.canonical))].sort();
+    expect(Object.keys(CLICKHOUSE_ROW_TYPES).sort()).toEqual(families);
+  });
+
+  test("ClickHouse wrappers and containers compose; an alias reads as its family", () => {
+    expect(clickhouseRowType("Nullable(UInt64)")).toEqual({ ts: "string", nullable: true });
+    expect(clickhouseRowType("LowCardinality(Nullable(String))")).toEqual({ ts: "string", nullable: true });
+    expect(clickhouseRowType("Array(Nullable(Int32))").ts).toBe("(number | null)[]");
+    expect(clickhouseRowType("Map(String, Array(UInt8))").ts).toBe("Record<string, number[]>");
+    expect(clickhouseRowType("Tuple(String, UInt8)").ts).toBe("[string, number]");
+    expect(clickhouseRowType("Enum8('a' = 1, 'it''s' = 2)").ts).toBe('"a" | "it\'s"');
+    expect(clickhouseRowType("BIGINT UNSIGNED").ts).toBe("string");
+    expect(clickhouseRowType("SimpleAggregateFunction(sum, Float64)").ts).toBe("number");
+    expect(clickhouseRowType("NoSuchType").ts).toBe("unknown");
+  });
+});
+
+describe("the slots a tag records", () => {
+  test("a Postgres foreign key's interpolated referenced column, paired with the referencing column, off the output", () => {
+    const s = pg.schema`CREATE SCHEMA shop`;
+    const a = pg.table`CREATE TABLE ${s}.a (id bigint PRIMARY KEY, code text UNIQUE)`;
+    const b = pg.table<"shop.b">`
+      CREATE TABLE ${s}.b (
+        a_id bigint REFERENCES ${a} (${a.columns.id}),
+        a_code text,
+        FOREIGN KEY (a_code) REFERENCES ${a} (${a.columns.code}),
+        other bigint REFERENCES ${a}
+      )`;
+    expect(getTypedSlots(b)).toEqual([
+      { index: 2, kind: "references", column: "a_id" },
+      { index: 4, kind: "references", column: "a_code" },
+    ]);
+    expect(Object.getOwnPropertySymbols(b).some((k) => Object.getOwnPropertyDescriptor(b, k)!.enumerable)).toBe(false);
+    const out = sqlSerializer.serialize(entities({ s, a, b })) as { primary: string };
+    expect(out.primary).not.toContain("references\", \"column");
+  });
+
+  test("a ClickHouse sort key's bare interpolated columns, and nothing inside an expression", () => {
+    const db = ch.database`CREATE DATABASE shop`;
+    const e = ch.table`CREATE TABLE ${db}.e (k String, c Nullable(String), n UInt8) ENGINE = MergeTree ORDER BY k`;
+    const v = ch.view`
+      CREATE MATERIALIZED VIEW ${db}.v ENGINE = MergeTree
+      ORDER BY (${e.columns.k}, ifNull(${e.columns.c}, ''))
+      PRIMARY KEY ${e.columns.k}
+      AS SELECT ${e.columns.k}, ${e.columns.c} FROM ${e}`;
+    expect(getTypedSlots(v)).toEqual([
+      { index: 1, kind: "sortKey" },
+      { index: 3, kind: "sortKey" },
+    ]);
+  });
+});
+
+describe("renderSqlTypes", () => {
+  test("keys are qualified and folded, a view passes its column through, slots stop at the last checked one", () => {
+    const s = pg.schema`CREATE SCHEMA Shop`;
+    const users = pg.table`CREATE TABLE ${s}.Users (Id serial PRIMARY KEY, mood text, born date NOT NULL)`;
+    const posts = pg.table`CREATE TABLE ${s}.posts (author integer REFERENCES ${users} (${users.columns.id}), body text)`;
+    const feed = pg.view`CREATE VIEW ${s}.feed AS SELECT p.${posts.columns.body}, upper(p.${posts.columns.body}) AS loud FROM ${posts} p`;
+    const text = renderSqlTypes(entities({ s, users, posts, feed }), { projectDir: "/" });
+    expect(text.split("\n")[0]).toContain("Generated by chant");
+    expect(text).toContain('import type { Column, KeyColumn } from "@intentius/chant-lexicon-sql/postgres";');
+    expect(text).toContain('"shop.users": {');
+    expect(text).toContain('id: Column<"integer", { ts: number; nullable: false; cmp: "N" }>;');
+    expect(text).toContain('born: Column<"date", { ts: Date; nullable: false; cmp: "D" }>;');
+    expect(text).toContain("slots: [unknown, unknown, KeyColumn<\"N\">];");
+    expect(text).toContain('body: Column<"text", { ts: string; nullable: true; cmp: "S" }>;');
+    expect(text).toContain('loud: Column<"unknown", { ts: unknown; nullable: never; cmp: never }>;');
+    expect(text.indexOf('"shop.feed"')).toBeLessThan(text.indexOf('"shop.posts"'));
+  });
+
+  test("with nothing declared, a module that augments nothing", () => {
+    expect(renderSqlTypes(new Map(), { config: { sql: { dialect: "postgres" } } })).toBe(
+      [
+        "// Generated by chant — do not edit directly. `chant sql types` writes it from the build's entities.",
+        'import type {} from "@intentius/chant-lexicon-sql/postgres";',
+        "",
+        'declare module "@intentius/chant-lexicon-sql/postgres" {',
+        "  interface SqlSchema {}",
+        "}",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  test("relationKey: qualified when the DDL qualifies it", () => {
+    expect(relationKey({ schema: "app", name: "users" })).toBe("app.users");
+    expect(relationKey({ database: "shop", name: "events" })).toBe("shop.events");
+    expect(relationKey({ name: "events" })).toBe("events");
+  });
+});
+
+describe("chant sql types", () => {
+  test("refuses to write beside a sql-types.ts, which tsc would read instead", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "sql-types-"));
+    writeFileSync(join(dir, "sql-types.ts"), "export {};\n");
+    expect(shadowingSource(join(dir, "sql-types.d.ts"))).toBe(join(dir, "sql-types.ts"));
+    expect(shadowingSource(join(dir, "other.d.ts"))).toBeUndefined();
+    const cwd = process.cwd();
+    process.chdir(dir);
+    try {
+      expect(await runTypes({ verb: "types", rawArgs: ["--output", "sql-types.d.ts"] })).toBe(1);
+      expect(await runTypes({ verb: "types", rawArgs: ["--bogus"] })).toBe(1);
+    } finally {
+      process.chdir(cwd);
+    }
+    expect(readFileSync(join(dir, "sql-types.ts"), "utf8")).toBe("export {};\n");
+  });
+});