test(migrate-ts): close QA coverage gaps (introspect helpers, version gating, defaults, rename boundary)

Follow-on to the migration QA audit — closes the highest-value coverage gaps
the audit surfaced. All test-only (no behavior change); confirmed the audited
logic is correct as it stands.

- introspect-postgres-helpers: pure unit tests for pgTypeToSqlType +
  parsePgDefault (exported precisely for DB-free testing; previously only the
  MIGRATE_TS_PG_URL-gated round-trip exercised them, so pg-mem runs had zero
  coverage of the --from-db type/default mapping).
- emit-sqlite-version-gating: pins the native-vs-recreate thresholds —
  RENAME COLUMN >= 3.25.0, DROP COLUMN >= 3.35.0 — at the exact boundary, plus
  unparseable/absent version → treated as modern.
- diff-column-default: the change-column-default from/to payload matrix
  (literal swap, add, remove, expr-vs-literal kind, equal → no change).
- diff.test: strengthened five `.toBeDefined()`-only assertions to assert the
  change payload (kind/table/column/index/fk/view), so a contents regression
  can't pass.
- diff-rename-heuristic: the table-rename Jaccard boundary (== 0.8 inclusive vs
  0.75 excluded) and a table-level 'abort' throw.
- check-expr normalize: a guard that the IN↔ANY fold does not false-positive on
  a quoted literal containing the words "any array".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/migrate-ts/test/check-evolution/normalize.test.ts

@@ -35,6 +35,17 @@ describe("normalizeCheckExpr", () => {
     // but PG's post-literal `::text` cast (enum form) is still stripped
     expect(normalizeCheckExpr("'open'::text")).toBe("'open'");
   });
+  test("the IN↔ANY fold does not false-positive on a literal containing 'any array'", () => {
+    // The fold is anchored on `= any array` (the shape only PG's ARRAY rewrite
+    // produces after bracket-stripping). A quoted literal that merely contains
+    // the words must be left intact — a stray quote breaks the `=…any…array`
+    // adjacency, so there is no `in` rewrite.
+    expect(normalizeCheckExpr("note = 'pick any array item'")).toBe("note = 'pick any array item'");
+    expect(checkExprEquals(
+      "note = 'pick any array item'",
+      "note in 'pick', 'item'",
+    )).toBe(false);
+  });
   test("genuinely different expressions are not equal", () => {
     expect(checkExprEquals("col >= 0", "col >= 5")).toBe(false);
   });

server/typescript/packages/migrate-ts/test/unit/diff-column-default.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Column-default drift: the offline diff must emit `change-column-default` with
+ * the right `from`/`to` payload (and omit the side that is absent), distinguish
+ * an `expr` default from a `literal` default of the same text, and emit NOTHING
+ * when the defaults are equal. Default drift is one of the most common real
+ * migrations, so this pins the diff contract end to end.
+ */
+import { test, expect, describe } from "bun:test";
+import { diff } from "../../src/diff/index.js";
+import type { ColumnDescriptor, SchemaSnapshot } from "../../src/types.js";
+
+function col(name: string, def?: ColumnDescriptor["default"]): ColumnDescriptor {
+  return { name, sqlType: { kind: "text" }, nullable: true, ...(def !== undefined ? { default: def } : {}) };
+}
+function table(c: ColumnDescriptor): SchemaSnapshot {
+  return { tables: [{ name: "t", columns: [c], indexes: [], foreignKeys: [], primaryKey: [], checks: [] }], views: [] };
+}
+function defaultChange(expected: ColumnDescriptor, actual: ColumnDescriptor) {
+  return diff(table(expected), table(actual)).then((r) =>
+    r.changes.find((x) => x.kind === "change-column-default"),
+  );
+}
+
+describe("diff — change-column-default", () => {
+  test("literal → different literal: from/to both present", async () => {
+    const c = await defaultChange(col("c", { kind: "literal", value: "1" }), col("c", { kind: "literal", value: "0" }));
+    expect(c).toMatchObject({
+      kind: "change-column-default",
+      column: "c",
+      from: { kind: "literal", value: "0" },
+      to: { kind: "literal", value: "1" },
+    });
+  });
+
+  test("adding a default (actual has none): `to` present, `from` omitted", async () => {
+    const c = await defaultChange(col("c", { kind: "literal", value: "1" }), col("c"));
+    expect(c).toMatchObject({ to: { kind: "literal", value: "1" } });
+    expect(c && "from" in c).toBe(false);
+  });
+
+  test("removing a default (expected has none): `from` present, `to` omitted", async () => {
+    const c = await defaultChange(col("c"), col("c", { kind: "literal", value: "1" }));
+    expect(c).toMatchObject({ from: { kind: "literal", value: "1" } });
+    expect(c && "to" in c).toBe(false);
+  });
+
+  test("same value but different kind (expr vs literal) IS a change", async () => {
+    const c = await defaultChange(col("c", { kind: "expr", value: "1" }), col("c", { kind: "literal", value: "1" }));
+    expect(c).toMatchObject({
+      from: { kind: "literal", value: "1" },
+      to: { kind: "expr", value: "1" },
+    });
+  });
+
+  test("identical defaults → NO change emitted", async () => {
+    const c = await defaultChange(col("c", { kind: "literal", value: "x" }), col("c", { kind: "literal", value: "x" }));
+    expect(c).toBeUndefined();
+  });
+
+  test("both sides have no default → NO change emitted", async () => {
+    const c = await defaultChange(col("c"), col("c"));
+    expect(c).toBeUndefined();
+  });
+});

server/typescript/packages/migrate-ts/test/unit/diff-rename-heuristic.test.ts

@@ -151,4 +151,50 @@ describe("rename-heuristic — table", () => {
     });
     expect(r.changes.find((c) => c.kind === "rename-column")).toBeUndefined();
   });
+
+  // Build a table whose columns are all text + nullable, so the column-set
+  // signature (name|kind|nullable) is driven purely by the column NAMES — which
+  // lets us dial the Jaccard overlap precisely for the threshold boundary.
+  function tableNamed(name: string, colNames: string[]) {
+    return {
+      name,
+      columns: colNames.map((n) => ({ name: n, sqlType: { kind: "text" as const }, nullable: true })),
+      indexes: [], foreignKeys: [], primaryKey: [], checks: [],
+    };
+  }
+
+  test("Jaccard overlap == 0.8 (boundary, inclusive) → rename candidate", async () => {
+    // drop posts {a,b,c,d} vs create articles {a,b,c,d,e}: |∩|=4, |∪|=5 → 0.8.
+    const expected = { tables: [tableNamed("articles", ["a", "b", "c", "d", "e"])], views: [] };
+    const actual = { tables: [tableNamed("posts", ["a", "b", "c", "d"])], views: [] };
+    const calls: AmbiguousChange[] = [];
+    const r = await diff({
+      expected, actual,
+      onAmbiguous: async (q) => { calls.push(q); return "rename"; },
+    });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({ kind: "possible-table-rename", columnOverlap: 0.8 });
+    expect(r.changes.find((c) => c.kind === "rename-table")).toMatchObject({ from: "posts", to: "articles" });
+  });
+
+  test("Jaccard overlap just below 0.8 → NOT a candidate (no callback)", async () => {
+    // drop posts {a,b,c} vs create articles {a,b,c,d}: |∩|=3, |∪|=4 → 0.75 < 0.8.
+    const expected = { tables: [tableNamed("articles", ["a", "b", "c", "d"])], views: [] };
+    const actual = { tables: [tableNamed("posts", ["a", "b", "c"])], views: [] };
+    const calls: AmbiguousChange[] = [];
+    await diff({
+      expected, actual, allow: { dropTable: true },
+      onAmbiguous: async (q) => { calls.push(q); return "rename"; },
+    });
+    expect(calls).toHaveLength(0);
+  });
+
+  test("table candidate with 'abort' resolution throws", async () => {
+    const expected = { tables: [table("articles")], views: [] };
+    const actual = { tables: [table("posts")], views: [] };
+    await expect(diff({
+      expected, actual,
+      onAmbiguous: async () => "abort",
+    })).rejects.toThrow(/possible rename posts → articles/);
+  });
 });

server/typescript/packages/migrate-ts/test/unit/diff.test.ts

@@ -58,7 +58,7 @@ describe("diff — per-table column-level", () => {
     const tableA = { name: "users", columns: [col("count", "text")], indexes: [], foreignKeys: [], primaryKey: [], checks: [] };
     const r = await diff(snapshot([tableE]), snapshot([tableA]));
     const c = r.changes.find((x) => x.kind === "change-column-type");
-    expect(c).toBeDefined();
+    expect(c).toMatchObject({ kind: "change-column-type", table: "users", column: "count" });
   });
 
   test("nullable mismatch → change-column-nullable", async () => {
@@ -74,7 +74,9 @@ describe("diff — per-table column-level", () => {
     const tableE = { name: "users", columns: [{ ...col("flag", "boolean"), default: { kind: "literal" as const, value: "true" } }], indexes: [], foreignKeys: [], primaryKey: [], checks: [] };
     const tableA = { name: "users", columns: [col("flag", "boolean")], indexes: [], foreignKeys: [], primaryKey: [], checks: [] };
     const r = await diff(snapshot([tableE]), snapshot([tableA]));
-    expect(r.changes.find((x) => x.kind === "change-column-default")).toBeDefined();
+    expect(r.changes.find((x) => x.kind === "change-column-default")).toMatchObject({
+      kind: "change-column-default", table: "users", column: "flag", to: { kind: "literal", value: "true" },
+    });
   });
 });
 
@@ -83,14 +85,18 @@ describe("diff — per-table index/FK", () => {
     const tableE = { name: "users", columns: [col("id", "integer"), col("email")], indexes: [{ name: "users_email_idx", columns: ["email"], unique: true }], foreignKeys: [], primaryKey: ["id"], checks: [] };
     const tableA = { name: "users", columns: [col("id", "integer"), col("email")], indexes: [], foreignKeys: [], primaryKey: ["id"], checks: [] };
     const r = await diff(snapshot([tableE]), snapshot([tableA]));
-    expect(r.changes.find((x) => x.kind === "add-index")).toBeDefined();
+    expect(r.changes.find((x) => x.kind === "add-index")).toMatchObject({
+      kind: "add-index", table: "users", index: { name: "users_email_idx", columns: ["email"], unique: true },
+    });
   });
 
   test("actual FK not in expected → drop-fk", async () => {
     const tableE = { name: "weeks", columns: [col("id", "integer"), col("program_id", "integer")], indexes: [], foreignKeys: [], primaryKey: ["id"], checks: [] };
     const tableA = { name: "weeks", columns: [col("id", "integer"), col("program_id", "integer")], indexes: [], foreignKeys: [{ name: "weeks_program_id_fk", columns: ["program_id"], refTable: "programs", refColumns: ["id"] }], primaryKey: ["id"], checks: [] };
     const r = await diff(snapshot([tableE]), snapshot([tableA]));
-    expect(r.changes.find((x) => x.kind === "drop-fk")).toBeDefined();
+    expect(r.changes.find((x) => x.kind === "drop-fk")).toMatchObject({
+      kind: "drop-fk", table: "weeks", fk: "weeks_program_id_fk",
+    });
   });
 });
 
@@ -117,7 +123,7 @@ describe("diff — view-body drift", () => {
     ]);
     const r = await diff(expected, actual);
     const viewChange = r.changes.find((c) => c.kind === "replace-view");
-    expect(viewChange).toBeDefined();
+    expect(viewChange).toMatchObject({ kind: "replace-view", view: { name: "order_summary" } });
     // No spurious create/drop pair when the view exists on both sides.
     expect(r.changes.find((c) => c.kind === "create-view")).toBeUndefined();
     expect(r.changes.find((c) => c.kind === "drop-view")).toBeUndefined();
@@ -126,6 +132,8 @@ describe("diff — view-body drift", () => {
   test("expected view absent from actual → create-view (unchanged)", async () => {
     const expected = withViews([{ name: "order_summary", sql: "SELECT id FROM orders" }]);
     const r = await diff(expected, { tables: [], views: [] });
-    expect(r.changes.find((c) => c.kind === "create-view")).toBeDefined();
+    expect(r.changes.find((c) => c.kind === "create-view")).toMatchObject({
+      kind: "create-view", view: { name: "order_summary" },
+    });
   });
 });

server/typescript/packages/migrate-ts/test/unit/emit-sqlite-version-gating.test.ts

@@ -0,0 +1,82 @@
+/**
+ * SQLite emits native ALTER for column rename/drop only on new-enough engines,
+ * and falls back to recreate-and-copy on older ones. The version boundaries are
+ * load-bearing — pick the wrong DDL and the migration fails on the target
+ * engine. These tests pin the exact thresholds:
+ *   - native RENAME COLUMN: SQLite >= 3.25.0
+ *   - native DROP COLUMN:   SQLite >= 3.35.0
+ * and that an unparseable/absent version is treated as modern.
+ */
+import { test, expect, describe } from "bun:test";
+import { emit } from "../../src/emit/index.js";
+import type { Change } from "../../src/types.js";
+import type { SchemaSnapshot } from "../../src/types.js";
+
+const TABLE: SchemaSnapshot = {
+  tables: [{
+    name: "t",
+    columns: [{ name: "a", sqlType: { kind: "text" }, nullable: true }],
+    indexes: [],
+    foreignKeys: [],
+    primaryKey: [],
+    checks: [],
+  }],
+  views: [],
+};
+
+function emitSqlite(changes: Change[], sqliteVersion?: string) {
+  return emit(changes, {
+    dialect: "sqlite",
+    expectedSchema: TABLE,
+    // Omit actualMeta entirely when no version (exactOptionalPropertyTypes
+    // forbids assigning `undefined` to the optional property).
+    ...(sqliteVersion !== undefined ? { actualMeta: { sqliteVersion } } : {}),
+  });
+}
+
+const renameChange: Change[] = [{ kind: "rename-column", status: { state: "allowed" }, table: "t", from: "a", to: "b" }];
+const dropChange: Change[] = [{ kind: "drop-column", status: { state: "allowed" }, table: "t", column: "a" }];
+
+describe("SQLite rename-column version gating (>= 3.25.0 native)", () => {
+  test("3.25.0 → native ALTER … RENAME COLUMN (no recreate)", () => {
+    const r = emitSqlite(renameChange, "3.25.0");
+    expect(r.up).toContain("RENAME COLUMN");
+    expect([...r.recreatedTables]).toEqual([]);
+  });
+
+  test("3.24.0 (one patch below) → recreate-and-copy", () => {
+    const r = emitSqlite(renameChange, "3.24.0");
+    expect(r.up).not.toMatch(/RENAME COLUMN/);
+    expect(r.up).toContain("CREATE TABLE");
+    expect([...r.recreatedTables]).toEqual(["t"]);
+  });
+});
+
+describe("SQLite drop-column version gating (>= 3.35.0 native)", () => {
+  test("3.35.0 → native ALTER … DROP COLUMN (no recreate)", () => {
+    const r = emitSqlite(dropChange, "3.35.0");
+    expect(r.up).toMatch(/DROP COLUMN/i);
+    expect([...r.recreatedTables]).toEqual([]);
+  });
+
+  test("3.34.0 (one minor below) → recreate-and-copy", () => {
+    const r = emitSqlite(dropChange, "3.34.0");
+    expect(r.up).not.toMatch(/DROP COLUMN/i);
+    expect(r.up).toContain("CREATE TABLE");
+    expect([...r.recreatedTables]).toEqual(["t"]);
+  });
+});
+
+describe("SQLite version parsing fallback", () => {
+  test("an unparseable version string is treated as modern (native DDL)", () => {
+    const r = emitSqlite(dropChange, "garbage");
+    expect(r.up).toMatch(/DROP COLUMN/i);
+    expect([...r.recreatedTables]).toEqual([]);
+  });
+
+  test("an absent version (no actualMeta) is treated as modern (native DDL)", () => {
+    const r = emitSqlite(dropChange, undefined);
+    expect(r.up).toMatch(/DROP COLUMN/i);
+    expect([...r.recreatedTables]).toEqual([]);
+  });
+});

server/typescript/packages/migrate-ts/test/unit/introspect-postgres-helpers.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Pure-unit coverage for the Postgres introspection helpers. These are exported
+ * precisely so they can be tested WITHOUT a live database — the pg-mem-backed
+ * tests can't exercise them (pg-mem returns null for column_default and type
+ * metadata), and the real-Postgres round-trip tests are gated on
+ * MIGRATE_TS_PG_URL. This file pins the `--from-db` type/default mapping that
+ * migration correctness rides on.
+ */
+import { test, expect, describe } from "bun:test";
+import { pgTypeToSqlType, parsePgDefault } from "../../src/introspect/postgres.js";
+
+describe("pgTypeToSqlType", () => {
+  test("integer family maps to the modeled bit width (smallint folds into 32)", () => {
+    expect(pgTypeToSqlType("bigint")).toEqual({ kind: "integer", bits: 64 });
+    expect(pgTypeToSqlType("int8")).toEqual({ kind: "integer", bits: 64 });
+    expect(pgTypeToSqlType("bigserial")).toEqual({ kind: "integer", bits: 64 });
+    expect(pgTypeToSqlType("integer")).toEqual({ kind: "integer", bits: 32 });
+    expect(pgTypeToSqlType("serial")).toEqual({ kind: "integer", bits: 32 });
+    expect(pgTypeToSqlType("smallint")).toEqual({ kind: "integer", bits: 32 });
+  });
+
+  test("varchar carries maxLength inline or from the separate column", () => {
+    expect(pgTypeToSqlType("character varying(255)")).toEqual({ kind: "text", maxLength: 255 });
+    expect(pgTypeToSqlType("varchar(64)")).toEqual({ kind: "text", maxLength: 64 });
+    // bare varchar + separate maxLength column
+    expect(pgTypeToSqlType("character varying", 100)).toEqual({ kind: "text", maxLength: 100 });
+    // bare varchar with no length info → plain text
+    expect(pgTypeToSqlType("character varying")).toEqual({ kind: "text" });
+    expect(pgTypeToSqlType("text")).toEqual({ kind: "text" });
+  });
+
+  test("numeric carries precision/scale when present", () => {
+    expect(pgTypeToSqlType("numeric(10,2)")).toEqual({ kind: "numeric", precision: 10, scale: 2 });
+    expect(pgTypeToSqlType("numeric(8)")).toEqual({ kind: "numeric", precision: 8 });
+    expect(pgTypeToSqlType("numeric")).toEqual({ kind: "numeric" });
+    expect(pgTypeToSqlType("decimal(12,4)")).toEqual({ kind: "numeric", precision: 12, scale: 4 });
+  });
+
+  test("floating point distinguishes single vs double precision", () => {
+    expect(pgTypeToSqlType("real")).toEqual({ kind: "real4" });
+    expect(pgTypeToSqlType("float4")).toEqual({ kind: "real4" });
+    expect(pgTypeToSqlType("double precision")).toEqual({ kind: "real" });
+    expect(pgTypeToSqlType("float8")).toEqual({ kind: "real" });
+  });
+
+  test("temporal types carry timezone awareness", () => {
+    expect(pgTypeToSqlType("date")).toEqual({ kind: "date" });
+    expect(pgTypeToSqlType("timestamp without time zone")).toEqual({ kind: "timestamp", withTimezone: false });
+    expect(pgTypeToSqlType("timestamptz")).toEqual({ kind: "timestamp", withTimezone: true });
+    expect(pgTypeToSqlType("timestamp with time zone")).toEqual({ kind: "timestamp", withTimezone: true });
+  });
+
+  test("boolean, json, binary, uuid", () => {
+    expect(pgTypeToSqlType("boolean")).toEqual({ kind: "boolean" });
+    expect(pgTypeToSqlType("jsonb")).toEqual({ kind: "json" });
+    expect(pgTypeToSqlType("json")).toEqual({ kind: "json" });
+    expect(pgTypeToSqlType("bytea")).toEqual({ kind: "blob" });
+    expect(pgTypeToSqlType("uuid")).toEqual({ kind: "uuid" });
+  });
+
+  test("unknown / user-defined types fall back to text (don't blow up)", () => {
+    expect(pgTypeToSqlType("citext")).toEqual({ kind: "text" });
+    expect(pgTypeToSqlType("ltree")).toEqual({ kind: "text" });
+    expect(pgTypeToSqlType("my_custom_enum")).toEqual({ kind: "text" });
+  });
+
+  test("type matching is case-insensitive and trims", () => {
+    expect(pgTypeToSqlType("  BIGINT ")).toEqual({ kind: "integer", bits: 64 });
+    expect(pgTypeToSqlType("TIMESTAMPTZ")).toEqual({ kind: "timestamp", withTimezone: true });
+  });
+});
+
+describe("parsePgDefault", () => {
+  test("absent default → undefined", () => {
+    expect(parsePgDefault(null)).toBeUndefined();
+    expect(parsePgDefault(undefined)).toBeUndefined();
+    expect(parsePgDefault("")).toBeUndefined();
+  });
+
+  test("function/keyword expressions are kind=expr (verbatim)", () => {
+    expect(parsePgDefault("now()")).toEqual({ kind: "expr", value: "now()" });
+    expect(parsePgDefault("CURRENT_TIMESTAMP")).toEqual({ kind: "expr", value: "CURRENT_TIMESTAMP" });
+    expect(parsePgDefault("CURRENT_DATE")).toEqual({ kind: "expr", value: "CURRENT_DATE" });
+    expect(parsePgDefault("nextval('users_id_seq'::regclass)")).toEqual({
+      kind: "expr",
+      value: "nextval('users_id_seq'::regclass)",
+    });
+  });
+
+  test("quoted literals strip the ::type cast and the surrounding quotes", () => {
+    expect(parsePgDefault("'hi'::text")).toEqual({ kind: "literal", value: "hi" });
+    expect(parsePgDefault("'true'::boolean")).toEqual({ kind: "literal", value: "true" });
+    expect(parsePgDefault("'42'::integer")).toEqual({ kind: "literal", value: "42" });
+    // no trailing cast
+    expect(parsePgDefault("'plain'")).toEqual({ kind: "literal", value: "plain" });
+  });
+
+  test("a bare non-quoted value with a :: cast is a complex expression", () => {
+    expect(parsePgDefault("NULL::text")).toEqual({ kind: "expr", value: "NULL::text" });
+    expect(parsePgDefault("ARRAY[]::text[]")).toEqual({ kind: "expr", value: "ARRAY[]::text[]" });
+  });
+
+  test("a bare literal with no quotes and no cast is kind=literal", () => {
+    expect(parsePgDefault("42")).toEqual({ kind: "literal", value: "42" });
+  });
+});