@intentius/chant-lexicon-sql 0.124.46 → 0.124.49

package/src/migrate/from-postgres/types.ts

@@ -0,0 +1,236 @@
+/**
+ * The Postgres to ClickHouse type map (#4399).
+ *
+ * A type either maps with no judgment (`note` absent) or carries a `note`
+ * naming what the map could not keep. Only the first kind is mechanical: the
+ * translator writes no diagnostic for it. A type this file does not know (an
+ * enum, a domain, an extension type) maps to `String` with a note, because a
+ * mirror still has to hold the value.
+ *
+ * Source types and defaults are from the Postgres data types chapter
+ * (https://www.postgresql.org/docs/current/datatype.html): `timestamp` and
+ * `time` take a precision of 0 to 6 and default to microseconds, `numeric`
+ * with no precision holds any value, `money` is a fixed-point type with a
+ * locale-set scale, `float(n)` is `real` for n up to 24 and `double
+ * precision` above.
+ *
+ * Target types are ClickHouse types of the pinned server (`../../spec/pin.ts`);
+ * `types.test.ts` checks every family this file writes against the generated
+ * catalog.
+ */
+
+export interface MappedType {
+  ok: true;
+  /** The ClickHouse type, before `Nullable`. */
+  type: string;
+  /** The declared maximum length of a character type, when it has one. */
+  maxLength?: number;
+  /** The column is `serial`, `bigserial` or `smallserial`: an integer with a sequence behind it. */
+  serial?: boolean;
+  /** The column is an array. ClickHouse cannot make an `Array` `Nullable`. */
+  array?: boolean;
+  /** Present when the map is a judgment: what was lost or chosen. */
+  note?: { message: string; evidence: string[] };
+}
+
+export type TypeMapping = MappedType;
+
+interface ParsedType {
+  /** Lower case words of the type, schema prefix and quotes removed: `timestamp with time zone`. */
+  base: string;
+  args: number[];
+  /** Array dimensions. */
+  dims: number;
+  raw: string;
+}
+
+/** Split a column type as written into its words, its parenthesised arguments and its array dimensions. */
+export function parseType(text: string): ParsedType {
+  let rest = text.trim();
+  let dims = 0;
+  for (;;) {
+    const m = /\s*\[\s*\d*\s*\]\s*$/.exec(rest);
+    if (!m) break;
+    rest = rest.slice(0, m.index);
+    dims++;
+  }
+  const arrayWord = /\s+array(\s*\[\s*\d*\s*\])?$/i.exec(rest);
+  if (arrayWord) {
+    rest = rest.slice(0, arrayWord.index);
+    dims++;
+  }
+  const args: number[] = [];
+  rest = rest.replace(/\(([^)]*)\)/g, (_all, inner: string) => {
+    for (const part of inner.split(",")) {
+      const n = Number(part.trim());
+      if (Number.isFinite(n)) args.push(n);
+    }
+    return " ";
+  });
+  const base = rest
+    .replace(/"/g, "")
+    .replace(/^pg_catalog\./i, "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase();
+  return { base, args, dims, raw: text.trim() };
+}
+
+const STRING_NOTE = (what: string, evidence: string[]) => ({ message: `${what} is read as String.`, evidence });
+
+function mapScalar(t: ParsedType): MappedType {
+  const { base, args } = t;
+  switch (base) {
+    case "smallint":
+    case "int2":
+      return { ok: true, type: "Int16" };
+    case "integer":
+    case "int":
+    case "int4":
+      return { ok: true, type: "Int32" };
+    case "bigint":
+    case "int8":
+      return { ok: true, type: "Int64" };
+    case "smallserial":
+    case "serial2":
+      return { ok: true, type: "Int16", serial: true };
+    case "serial":
+    case "serial4":
+      return { ok: true, type: "Int32", serial: true };
+    case "bigserial":
+    case "serial8":
+      return { ok: true, type: "Int64", serial: true };
+    case "real":
+    case "float4":
+      return { ok: true, type: "Float32" };
+    case "double precision":
+    case "float8":
+      return { ok: true, type: "Float64" };
+    case "float":
+      return { ok: true, type: (args[0] ?? 53) <= 24 ? "Float32" : "Float64" };
+    case "numeric":
+    case "decimal": {
+      if (args.length === 0) {
+        return {
+          ok: true,
+          type: "Decimal(38, 18)",
+          note: {
+            message: "numeric with no precision is read as Decimal(38, 18).",
+            evidence: ["Postgres stores up to 131072 digits before the point and 16383 after; a ClickHouse Decimal has a fixed precision and scale", "a value that does not fit fails the insert"],
+          },
+        };
+      }
+      const p = args[0]!;
+      const s = args[1] ?? 0;
+      if (p > 76 || s < 0 || s > p) {
+        return {
+          ok: true,
+          type: "Decimal(76, 38)",
+          note: { message: `numeric(${String(p)}, ${String(s)}) is read as Decimal(76, 38).`, evidence: ["ClickHouse Decimal holds at most 76 digits"] },
+        };
+      }
+      return { ok: true, type: `Decimal(${String(p)}, ${String(s)})` };
+    }
+    case "money":
+      return {
+        ok: true,
+        type: "Decimal(19, 2)",
+        note: { message: "money is read as Decimal(19, 2).", evidence: ["money takes its scale from the lc_monetary setting of the source server, and two decimals is the common one"] },
+      };
+    case "boolean":
+    case "bool":
+      return { ok: true, type: "Bool" };
+    case "text":
+    case "varchar":
+    case "character varying":
+    case "name":
+    case "citext":
+      return { ok: true, type: "String", ...(args[0] !== undefined ? { maxLength: args[0] } : {}) };
+    case "char":
+    case "character":
+    case "bpchar":
+      return {
+        ok: true,
+        type: "String",
+        ...(args[0] !== undefined ? { maxLength: args[0] } : {}),
+        ...(args[0] !== undefined && args[0] > 1 ? { note: STRING_NOTE("char(n)", ["Postgres pads a char(n) value with spaces to n characters; a String keeps the value as it is loaded"]) } : {}),
+      };
+    case "bytea":
+      return { ok: true, type: "String" };
+    case "uuid":
+      return { ok: true, type: "UUID" };
+    case "date":
+      return { ok: true, type: "Date32" };
+    case "time":
+    case "time without time zone":
+      return { ok: true, type: `Time64(${String(args[0] ?? 6)})` };
+    case "timetz":
+    case "time with time zone":
+      return { ok: true, type: "String", note: STRING_NOTE("timetz", ["a time of day with an offset has no ClickHouse type; the offset is kept in the text"]) };
+    case "timestamp":
+    case "timestamp without time zone":
+      return { ok: true, type: `DateTime64(${String(args[0] ?? 6)})` };
+    case "timestamptz":
+    case "timestamp with time zone":
+      return { ok: true, type: `DateTime64(${String(args[0] ?? 6)}, 'UTC')` };
+    case "interval":
+      return { ok: true, type: "String", note: STRING_NOTE("interval", ["a ClickHouse Interval type cannot be stored in a column", "the value is kept as Postgres prints it"]) };
+    case "json":
+    case "jsonb":
+      return { ok: true, type: "JSON" };
+    case "oid":
+      return { ok: true, type: "UInt32" };
+    case "inet":
+    case "cidr":
+      return {
+        ok: true,
+        type: "IPv6",
+        note: { message: `${base} is read as IPv6.`, evidence: ["an IPv6 column holds an IPv4 address in its mapped form", "the prefix length of a network is not kept"] },
+      };
+    case "xml":
+    case "macaddr":
+    case "macaddr8":
+    case "tsvector":
+    case "tsquery":
+    case "bit":
+    case "bit varying":
+    case "varbit":
+    case "point":
+    case "line":
+    case "lseg":
+    case "box":
+    case "path":
+    case "polygon":
+    case "circle":
+      return { ok: true, type: "String", note: STRING_NOTE(base, [`ClickHouse has no ${base} type`, "the value is kept as Postgres prints it"]) };
+    default:
+      return {
+        ok: true,
+        type: "String",
+        note: STRING_NOTE(t.raw, [`${t.raw} is not a built-in type chant maps (an enum, a domain, a composite or an extension type)`, "the value is kept as Postgres prints it; an enum could be an Enum8 or Enum16 once its labels are settled"]),
+      };
+  }
+}
+
+/** Map a column type as the declaration wrote it. */
+export function mapPostgresType(text: string): TypeMapping {
+  const t = parseType(text);
+  const inner = mapScalar(t);
+  if (t.dims === 0) return inner;
+  let type = inner.type;
+  for (let i = 0; i < t.dims; i++) type = `Array(${type})`;
+  return {
+    ok: true,
+    type,
+    array: true,
+    ...(inner.serial ? { serial: true } : {}),
+    note: {
+      message: `${t.raw} is read as ${type}.`,
+      evidence: [
+        ...(inner.note ? [inner.note.message] : []),
+        "ClickHouse cannot make an Array Nullable, so a NULL array is stored as an empty one",
+        "Postgres does not enforce the declared dimensions or lengths of an array",
+      ],
+    },
+  };
+}

package/src/migrate/from-postgres/validate.e2e.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Fourth Done-when box of #4399: `--validate` creates the translated example
+ * on the pinned ClickHouse server, as a bare table and as a `CdcMirror` call
+ * with its view, and reports a statement the server refuses by name.
+ *
+ * Needs Docker; skips cleanly without it. One throwaway container per call,
+ * removed afterwards even on failure. Written, not run, in the session that
+ * added it (no e2e and no Docker, by the brief).
+ */
+
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { dockerAvailable } from "../../clickhouse/container";
+import type { Declarable } from "@intentius/chant/declarable";
+import { transform } from "./index";
+import * as source from "../../../examples/postgres-cdc-source/src/shop";
+import { translatePostgres } from "./translate";
+
+const enabled = await dockerAvailable();
+const sourceFile = join(import.meta.dirname, "../../../examples/postgres-cdc-source");
+
+describe.skipIf(!enabled)("the emulator accepts the translated example", () => {
+  test.each([
+    ["bare tables", false],
+    ["CdcMirror calls and their views", true],
+  ])("every statement of %s is created", async (_name, useComposites) => {
+    const r = await transform("", { emit: "ts", useComposites, sourceFile });
+    const found = await r.validate!();
+    expect(found, found.map((d) => String(d.message)).join("\n")).toEqual([]);
+  }, 300_000);
+
+  test("a statement the server refuses is an error naming the table", async () => {
+    // A key column the table does not have is caught by the server, not by the translator.
+    const entities = new Map(Object.entries(source) as Array<[string, Declarable]>);
+    const t = translatePostgres(entities, { composite: false });
+    t.mirrors[0]!.primaryKey = ["no_such_column"];
+    const { validateOnEmulator } = await import("../../sqlserver/validate");
+    const { objectsToIR } = await import("../../clickhouse/import/ir");
+    const { mirrorObjects } = await import("./emit");
+    const found = await validateOnEmulator(objectsToIR(mirrorObjects(t.mirrors, false)));
+    expect(found).toHaveLength(1);
+    expect(found[0]).toMatchObject({ ruleId: "SQLRV012", severity: "error", entity: "customers" });
+  }, 300_000);
+});

package/src/migrate/from-postgres/workspace.e2e.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Third Done-when box of #4399, through `chant workspace check`: a workspace
+ * with the Postgres member `db` (the DDL of `examples/postgres-cdc-source`)
+ * and the ClickHouse member `mirror`. `chant migrate` writes the mirror and its
+ * links; dropping a mirrored column from the Postgres side then fails the
+ * check, naming the mirror, until the mirror follows.
+ *
+ * The unit version of the same facts, on the example's own declarations, is
+ * `example.test.ts`. This one reads a real declaration file and folds the
+ * member's `.sql` file the way `chant workspace check` does, so it is e2e
+ * under the 5 s unit budget (#2817). Written, not run, in the session that
+ * added it.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, afterEach, describe, expect, test, vi } from "vitest";
+import { runDeclarationChecks } from "@intentius/chant/workspace/checks";
+import { parseArgs } from "@intentius/chant/cli/parse-args";
+import { runMigrate } from "@intentius/chant/cli/handlers/migrate";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+afterEach(() => vi.restoreAllMocks());
+
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-4399-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const schema = (email: string) => `CREATE SCHEMA shop;
+
+CREATE TABLE shop.customers (
+  id         bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+${email}  country    text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE shop.orders (
+  id          bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  customer_id bigint NOT NULL REFERENCES shop.customers (id),
+  total       numeric(12, 2) NOT NULL,
+  status      text NOT NULL,
+  placed_at   timestamptz NOT NULL DEFAULT now()
+);
+`;
+
+const EMAIL = "  email      text NOT NULL,\n";
+const config = (dialect: string) => `import type { ChantConfig } from "@intentius/chant";\nexport default { lexicons: ["sql"], sql: { dialect: "${dialect}" } } satisfies ChantConfig;\n`;
+
+function shop(): string {
+  return repo({
+    "chant.workspace.json": `${JSON.stringify({ name: "shop", schema: 1, members: [{ name: "db", dir: "db", kind: "chant" }, { name: "mirror", dir: "mirror", kind: "chant" }] }, null, 2)}\n`,
+    "db/chant.config.ts": config("postgres"),
+    "db/schema.sql": schema(EMAIL),
+    "mirror/chant.config.ts": config("clickhouse"),
+  });
+}
+
+async function migrate(root: string): Promise<number> {
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  return runMigrate({
+    args: parseArgs(["migrate", join(root, "db/schema.sql"), "--from", "sql/postgres", "--to", "sql/clickhouse", "--use-composites", "--output", join(root, "mirror/src/mirrors.ts")]),
+    plugins: [],
+    serializers: [],
+  } as never);
+}
+
+describe("chant migrate links the mirror to the Postgres member, and chant workspace check holds them", () => {
+  test("the links resolve; dropping a mirrored column fails the check naming the mirror; unlinking it and migrating again passes", async () => {
+    const root = shop();
+    expect(await migrate(root)).toBe(0);
+    const declared = JSON.parse(readFileSync(join(root, "chant.workspace.json"), "utf8")) as { members: Array<{ name: string; links?: Array<{ member: string; output: string }> }> };
+    const links = declared.members.find((m) => m.name === "mirror")!.links!;
+    expect(links).toHaveLength(9);
+    expect(links).toContainEqual({ member: "db", output: "shop.customers.email" });
+
+    const ok = await runDeclarationChecks(root);
+    expect(ok.diagnostics.filter((d) => d.ruleId.startsWith("WSP09"))).toEqual([]);
+    expect(ok.links.filter((r) => r.origin === "declared" && r.status === "resolved")).toHaveLength(9);
+
+    // The Postgres side drops email.
+    writeFileSync(join(root, "db/schema.sql"), schema(""));
+    const failed = await runDeclarationChecks(root);
+    expect(failed.ok).toBe(false);
+    expect(failed.diagnostics.map((d) => `${d.ruleId}:${d.entity}`)).toEqual(["WSP093:mirror"]);
+    expect(failed.diagnostics[0]!.message).toContain("db has no output shop.customers.email");
+
+    // The mirror follows: the link goes with the column, and migrating again adds nothing it should not.
+    const edited = { ...declared, members: declared.members.map((m) => (m.name === "mirror" ? { ...m, links: m.links!.filter((l) => l.output !== "shop.customers.email") } : m)) };
+    writeFileSync(join(root, "chant.workspace.json"), `${JSON.stringify(edited, null, 2)}\n`);
+    expect(await migrate(root)).toBe(0);
+    const after = await runDeclarationChecks(root);
+    expect(after.diagnostics.filter((d) => d.ruleId.startsWith("WSP09"))).toEqual([]);
+  });
+
+  test("a renamed column with a previously hint tells the mirror where it went", async () => {
+    const root = shop();
+    await migrate(root);
+    writeFileSync(join(root, "db/schema.sql"), schema("  email_hash text NOT NULL, -- previously: email\n"));
+    const report = await runDeclarationChecks(root);
+    expect(report.diagnostics[0]!.message).toContain("it was renamed to shop.customers.email_hash, so link to that instead");
+  });
+});

package/src/migration-classify.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Classifying the migration files a pull request adds (#4407), for goose,
+ * golang-migrate, clickhouse-migrations and Flyway. Each fixture directory is
+ * an in-memory tree at the base commit and another at the head, with one
+ * file added; the answer is what the plan note lists. Offline: nothing here
+ * opens a server.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test, vi } from "vitest";
+import { LINK_READERS, type KindLinkRead } from "@intentius/chant/workspace/kind-link-readers";
+import { classifyNewMigrations, newMigrationGroups } from "@intentius/chant/workspace/new-migrations";
+import { renderMigrationLines } from "@intentius/chant/pr-migrations";
+import type { WorkspaceTree } from "@intentius/chant/workspace/tree";
+import { classifyMigrationFiles } from "./migration-classify";
+
+function memoryTree(files: Record<string, string>): WorkspaceTree {
+  const dirs = new Set([""]);
+  for (const f of Object.keys(files)) {
+    const parts = f.split("/");
+    for (let i = 1; i < parts.length; i++) dirs.add(parts.slice(0, i).join("/"));
+  }
+  return {
+    label: "",
+    stat: (p) => (p in files ? "file" : dirs.has(p) ? "dir" : undefined),
+    list(p) {
+      if (!dirs.has(p)) return undefined;
+      const prefix = p === "" ? "" : `${p}/`;
+      const seen = new Map<string, "file" | "dir">();
+      for (const f of Object.keys(files)) {
+        if (!f.startsWith(prefix)) continue;
+        const rest = f.slice(prefix.length);
+        seen.set(rest.split("/")[0]!, rest.includes("/") ? "dir" : "file");
+      }
+      return [...seen].map(([name, type]) => ({ name, type }));
+    },
+    read(p) {
+      if (!(p in files)) throw new Error(`no such file ${p}`);
+      return files[p]!;
+    },
+  };
+}
+
+const sql = { name: "sql", classifyMigrations: classifyMigrationFiles };
+
+/** The files the pull request adds, classified, as the plan note lists them. */
+async function classify(reader: keyof typeof LINK_READERS, fields: Record<string, string>, base: Record<string, string>, added: Record<string, string>) {
+  const head = memoryTree({ ...base, ...added });
+  const read = new Map<string, KindLinkRead>([["m", LINK_READERS[reader]({ member: { name: "m" } as never, dir: "db", fields: fields as never, tree: head })]]);
+  const groups = newMigrationGroups([{ name: "m", dir: "db" }], read, memoryTree(base));
+  return classifyNewMigrations(groups, head, [sql]);
+}
+
+const rules = (f: Awaited<ReturnType<typeof classify>>[number]) => f.statements.flatMap((s) => s.changes.map((c) => c.rule));
+
+describe("a new file in each migration directory kind appears with classes", () => {
+  test("goose: the Up section only", async () => {
+    const [f, ...rest] = await classify(
+      "goose-dir",
+      { dialect: "postgres" },
+      { "db/00001_init.sql": "-- +goose Up\nCREATE TABLE orders (id bigint PRIMARY KEY, status text);\n-- +goose Down\nDROP TABLE orders;\n" },
+      {
+        "db/00002_idx.sql":
+          "-- +goose Up\nCREATE INDEX orders_status_idx ON orders (status);\nALTER TABLE orders ADD COLUMN note text;\n-- +goose Down\nDROP INDEX orders_status_idx;\n",
+      },
+    );
+    expect(rest).toEqual([]);
+    expect(f).toMatchObject({ member: "m", reader: "goose-dir", file: "db/00002_idx.sql", dialect: "postgres" });
+    expect(rules(f!)).toEqual(["SQLPG241", "SQLPG201"]);
+    expect(f!.statements[0]!.changes[0]).toMatchObject({ class: "concurrently", lock: "SHARE" });
+  });
+
+  test("golang-migrate: the .up file, not the .down file", async () => {
+    const out = await classify(
+      "golang-migrate-dir",
+      { dialect: "postgres" },
+      { "db/000001_init.up.sql": "CREATE TABLE t (id bigint);", "db/000001_init.down.sql": "DROP TABLE t;" },
+      { "db/000002_fk.up.sql": "ALTER TABLE t ADD CONSTRAINT fk FOREIGN KEY (id) REFERENCES u (id) NOT VALID;", "db/000002_fk.down.sql": "ALTER TABLE t DROP CONSTRAINT fk;" },
+    );
+    expect(out.map((f) => f.file)).toEqual(["db/000002_fk.up.sql"]);
+    expect(rules(out[0]!)).toEqual(["SQLPG217"]);
+  });
+
+  test("clickhouse-migrations: a sort-key change is a rebuild", async () => {
+    const [f] = await classify(
+      "clickhouse-migrations-dir",
+      {},
+      { "db/1_events.sql": "CREATE TABLE events (user_id UInt64, ts DateTime) ENGINE = MergeTree ORDER BY ts;" },
+      { "db/2_key.sql": "ALTER TABLE events MODIFY ORDER BY (user_id, ts);" },
+    );
+    expect(f).toMatchObject({ dialect: "clickhouse" });
+    expect(f!.statements[0]).toMatchObject({ outcome: "classified", changes: [{ rule: "SQLCH220", class: "rebuild", label: "REBUILD" }] });
+  });
+
+  test("flyway: placeholders are substituted before the statements are read", async () => {
+    const [f] = await classify(
+      "flyway-dir",
+      { dialect: "postgres" },
+      { "db/V1__init.sql": "CREATE TABLE ${schema}.t (id bigint);", "db/flyway.conf": "flyway.locations=filesystem:.\nflyway.placeholders.schema=app\n" },
+      { "db/V2__idx.sql": "CREATE INDEX CONCURRENTLY i ON ${schema}.t (id);" },
+    );
+    expect(f).toMatchObject({ file: "db/V2__idx.sql", type: "versioned" });
+    expect(f!.statements[0]!.sql).toBe("CREATE INDEX CONCURRENTLY i ON app.t (id)");
+    expect(rules(f!)).toEqual(["SQLPG240"]);
+  });
+
+  test("flyway: a placeholder with no value is reported on the file, not thrown", async () => {
+    const [f] = await classify("flyway-dir", { dialect: "postgres" }, { "db/V1__init.sql": "SELECT 1;" }, { "db/V2__x.sql": "CREATE TABLE ${missing}.t (id bigint);" });
+    expect(f!.statements).toEqual([]);
+    expect(f!.error).toContain("missing");
+  });
+});
+
+describe("the plan note lines", () => {
+  test("a Postgres CREATE INDEX without CONCURRENTLY is listed with its lock", async () => {
+    const files = await classify("goose-dir", { dialect: "postgres" }, { "db/1_a.sql": "-- +goose Up\nSELECT 1;\n" }, { "db/2_b.sql": "-- +goose Up\nCREATE INDEX i ON orders (status);\n" });
+    const lines = renderMigrationLines(files).join("\n");
+    expect(lines).toContain("`db/2_b.sql` (member `m`, postgres)");
+    expect(lines).toContain("`CREATE INDEX i ON orders (status)`: needs CONCURRENTLY (SQLPG241, SHARE)");
+  });
+
+  test("a ClickHouse sort-key change is listed as a rebuild", async () => {
+    const files = await classify("clickhouse-migrations-dir", {}, { "db/1_a.sql": "SELECT 1;" }, { "db/2_b.sql": "ALTER TABLE events MODIFY ORDER BY (a, b);" });
+    expect(renderMigrationLines(files).join("\n")).toContain("REBUILD (SQLCH220)");
+  });
+
+  test("an undecided statement names both rules", async () => {
+    const files = await classify("clickhouse-migrations-dir", {}, { "db/1_a.sql": "SELECT 1;" }, { "db/2_b.sql": "ALTER TABLE events MODIFY COLUMN user_id UInt32;" });
+    expect(renderMigrationLines(files).join("\n")).toContain("undecided between SQLCH210 background rewrite and SQLCH211 REBUILD");
+  });
+});
+
+describe("offline", () => {
+  test("classifying contacts no server and starts no process", async () => {
+    const fetched = vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("network used"));
+    await classify("goose-dir", { dialect: "postgres" }, { "db/1_a.sql": "-- +goose Up\nSELECT 1;\n" }, { "db/2_b.sql": "-- +goose Up\nDROP TABLE t;\n" });
+    await classify("clickhouse-migrations-dir", {}, { "db/1_a.sql": "SELECT 1;" }, { "db/2_b.sql": "DROP TABLE t;" });
+    expect(fetched).not.toHaveBeenCalled();
+    fetched.mockRestore();
+  });
+
+  test("the classifier modules import no live binding, client or process API", () => {
+    for (const f of ["migration-classify.ts", "postgres/plan/statements.ts", "clickhouse/plan/statements.ts", "core/statement-class.ts"]) {
+      const src = readFileSync(join(import.meta.dirname, f), "utf8");
+      const imports = [...src.matchAll(/(?:from|import\()\s*["']([^"']+)["']/g)].map((m) => m[1]!);
+      for (const spec of imports) expect(spec, `${f} imports ${spec}`).not.toMatch(/\/live\/|\/apply\/|\/http$|child_process|node:net|node:http|node:https|\/bind$/);
+    }
+  });
+});

package/src/migration-classify.ts

@@ -0,0 +1,45 @@
+/**
+ * Classify the migration files a pull request adds (#4407), the lexicon's
+ * answer to core's `classifyMigrations` hook. The "check" adoption level:
+ * each new file's up statements are read and given the class the schema-diff
+ * classifier gives the same change, and nothing else happens. No server is
+ * contacted, no migration tool runs and nothing is applied, so it needs no
+ * environment binding (compare `chant sql replay`, which does).
+ *
+ * The up statements are the ones replay would run: goose's `-- +goose Up`
+ * section, the whole file for golang-migrate and clickhouse-migrations, and a
+ * Flyway file after placeholder substitution with the configuration's values.
+ */
+
+import type { MigrationFileClassification } from "@intentius/chant/pr-migrations";
+import { findFlywayConfig, readFlywayConfig, substitute } from "@intentius/chant/workspace/flyway-layout";
+import type { WorkspaceTree } from "@intentius/chant/workspace/tree";
+import { classifyClickHouseStatements } from "./clickhouse/plan/statements";
+import { gooseUpStatements, splitStatements } from "./migration-replay";
+import { classifyPgStatements } from "./postgres/plan/statements";
+
+export const MIGRATION_DIALECTS = ["postgres", "clickhouse"] as const;
+
+/** The reader names whose files this lexicon reads. */
+const READERS = new Set(["goose-dir", "golang-migrate-dir", "clickhouse-migrations-dir", "flyway-dir"]);
+
+export function classifyMigrationFiles(options: { reader: string; dialect: string; tree: WorkspaceTree; dir: string; files: string[] }): MigrationFileClassification[] {
+  const { reader, dialect, tree, dir, files } = options;
+  if (!READERS.has(reader) || !(MIGRATION_DIALECTS as readonly string[]).includes(dialect)) return [];
+  const classify = dialect === "postgres" ? classifyPgStatements : classifyClickHouseStatements;
+  let flyway: ReturnType<typeof readFlywayConfig> | undefined;
+  return files.map((file) => {
+    try {
+      const text = tree.read(file);
+      let statements: string[];
+      if (reader === "goose-dir") statements = gooseUpStatements(text);
+      else if (reader === "flyway-dir") {
+        flyway ??= readFlywayConfig(tree, findFlywayConfig(tree, dir), dir);
+        statements = splitStatements(substitute(text, file, flyway));
+      } else statements = splitStatements(text);
+      return { file, statements: classify(statements) };
+    } catch (err) {
+      return { file, statements: [], error: err instanceof Error ? err.message : String(err) };
+    }
+  });
+}