SMOODEV-045397: integrate differ promotions + docs

brentrager · brentrager · commit 4635e2fe9bd4 · 2026-06-27T21:39:33.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -49,9 +49,9 @@ follows [Keep a Changelog](https://keepachangelog.com/); the project adheres to
   rename detection vs. drop+add). Covers tables, columns, checks, enums, generated
   & identity columns, RLS policies, roles, sequences, and views.
 - **Differ conformance corpus** (`tests/differ_corpus.rs`): a conformance corpus
-  of Postgres schema-diff scenarios — 258 cases, 198 asserted
-  (snapshot-in → expected-DDL-out under normalized comparison), 60 tracked as
-  `Skip` for features outside the snapshot IR (see ROADMAP follow-ups).
+  of Postgres schema-diff scenarios — 258 cases, 249 asserted
+  (snapshot-in → expected-DDL-out under normalized comparison), 9 tracked as
+  `Skip` for behaviour outside the snapshot IR (see ROADMAP follow-ups).
 - **Deferred-corpus promotion** (phase 2): the previously-`Skip`'d differ
   categories are now asserted end-to-end —
     - **Views**: `WITH (...)` storage options, materialized-view `TABLESPACE`,
@@ -75,6 +75,12 @@ follows [Keep a Changelog](https://keepachangelog.com/); the project adheres to
       `SchemaSnapshotBuilder::ind_policy`, `DdlStatement::{Create,Drop,Alter,Rename}IndPolicy`,
       an `ind_policy:` rename-hint tag, and dedicated `Plan` buckets ordered
       alongside their table-policy counterparts.
+- **Deferred-corpus promotion** (phase 3): the `tables` and `columns` categories
+  are now asserted end-to-end against rendered SQL (26 cases flipped
+  `Skip` → `Supported`) — `CREATE`/`DROP TABLE`, `ALTER TABLE … RENAME`,
+  `ALTER TABLE … SET SCHEMA`, multi-table creates, composite-PK add/rename
+  (breakpoint-delimited DROP+ADD), `ADD COLUMN`, `RENAME COLUMN`, and column-level
+  composite-PK changes. The corpus is now 249 asserted / 9 `Skip`.
 - **Migrations** (`feature = "migrate"`): forward-only `run_migrations` over a
   `*.sql` directory with a `__pg_migrations` bookkeeping table (idempotent re-runs),
   `split_sql_statements` (`--> statement-breakpoint` aware), and
@@ -106,18 +112,17 @@ follows [Keep a Changelog](https://keepachangelog.com/); the project adheres to
   and the journal types `MigrationJournal` / `MigrationJournalEntry`. The on-disk
   layout is unchanged (`meta/_journal.json`, `--> statement-breakpoint` markers).
 
-### Follow-ups (tracked as corpus `Skip`s, deferred to later phases)
+### Follow-ups (the remaining 9 corpus `Skip`s, in 3 clusters)
 
-- **Columns category** (the bulk of the remaining `Skip`s): column add / default
-  add / data-type change cases — including every enum↔standard and enum↔enum
-  data-type-change variant — are deferred to a dedicated columns-promotion pass.
-- Multi-construct **ordering** mismatches vs. the corpus's insertion order:
-  FK/index emission for multi-table creates (declaration order vs.
-  `BTreeMap`-sorted), composite-PK DROP+ADD joined into one breakpoint-delimited
-  string, and multi-policy creation order (BTreeMap name-sorted vs. insertion order).
-- **Tables/schema** "statements-only encoding" goldens (add/drop/move table,
-  multiproject schema) whose corpus scenarios assert the structured statement
-  encoding only, not rendered SQL.
-- Enum **schema rename** (`ALTER SCHEMA`) — schemas are not modeled as renameable
-  IR entities.
-- Error-case fixtures (duplicate view / constraint names that Postgres rejects).
+- **Schema-level renames** (`ALTER SCHEMA … RENAME TO`) — 3 cases (`change schema
+  with tables #1`, `change table schema #6`, `enums #5`). Schemas are not modeled
+  as renameable IR entities, so a schema rename degrades to a data-losing
+  drop+create; we deliberately do not bless that as supported output.
+- **Enum quoting in column ops** — 3 cases (`enums #20`, `enums #21`, `column is
+  enum type … add default`). `ADD COLUMN` emits a bare enum type name
+  (`my_enum` / `my_enum[]`) instead of the quoted `"my_enum"`, and `SET DEFAULT`
+  emits a bare enum literal (`value3`) instead of `'value3'`. Needs the lowering
+  to resolve user-defined types/defaults against the enum registry.
+- **Error-case fixtures** — 3 cases (`create checks with same names`, plus the
+  duplicate view / materialized-view name cases). Postgres rejects these; the
+  differ does not yet model rejection, so there is no SQL contract to assert.
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -26,13 +26,18 @@ public crate carries no SmooAI specifics.
   enums, RLS policies, roles, sequences, and views. _Cargo feature: `differ`
   (default)._
 - ✅ Conformance corpus of Postgres schema-diff scenarios
-  (snapshot-in → expected-DDL-out): **258 cases, 198 asserted, 60
-  tracked `Skip`** (deferred categories below).
+  (snapshot-in → expected-DDL-out): **258 cases, 249 asserted, 9
+  tracked `Skip`** (remaining clusters below).
 - ✅ **Phase-2 deferred-corpus promotion**: views (`WITH` options / `TABLESPACE`
   / `USING` / `SET SCHEMA` / `.existing()` reference / DROP-before-CREATE
   recreate), enum recreate cascade, sequences, identity (custom sequence name +
   `START WITH` → `MINVALUE` fallback), FK alter (DROP+ADD), index drop
   (`public`-implicit), and independent (schema-level) policies (`SnapIndPolicy`).
+- ✅ **Phase-3 deferred-corpus promotion**: the **`tables`** and **`columns`**
+  categories now assert rendered SQL end-to-end (26 cases `Skip` → `Supported`) —
+  `CREATE`/`DROP TABLE`, `ALTER TABLE … RENAME` / `SET SCHEMA`, multi-table
+  creates, composite-PK add/rename (breakpoint-delimited DROP+ADD), `ADD COLUMN`,
+  `RENAME COLUMN`, and column-level composite-PK changes.
 - ✅ **Non-`public` schema support**: `CREATE SCHEMA` / `DROP SCHEMA` generation
   (`SchemaSnapshot.schemas`, ordered first/last), the schema-qualify fix
   (`to_create_table_sql` + all emitters share `qualify_relation`: `public`
@@ -67,23 +72,22 @@ public crate carries no SmooAI specifics.
   plus TS types + Zod (`emit_ts_module`, a `createSelectSchema` replacement) for
   polyglot consumers.
 
-## Deferred — differ corpus `Skip`s (next promotion passes)
+## Deferred — the 9 remaining differ corpus `Skip`s
 
-Tracked by the 60 remaining `Skip` cases in `tests/differ_corpus.rs`:
+Three clusters in `tests/differ_corpus.rs` (3 cases each):
 
-- **Columns category** (the largest remaining cluster): column add / default add /
-  data-type change — including every enum↔standard and enum↔enum data-type-change
-  variant — deferred to a dedicated columns-promotion pass.
-- Multi-construct **ordering** mismatches vs the corpus's insertion order:
-  multi-table-create FK/index emission (declaration order vs `BTreeMap`-sorted),
-  composite-PK DROP+ADD joined into one breakpoint-delimited string, and multi-policy
-  creation order (name-sorted vs insertion order).
-- **Tables/schema** "statements-only encoding" goldens (add/drop/move table,
-  multiproject schema) whose scenarios assert the structured statement encoding,
-  not rendered SQL.
-- Enum **schema rename** (`ALTER SCHEMA`) — schemas not modeled as renameable IR
-  entities.
-- Error-case fixtures (duplicate view / constraint names Postgres rejects).
+- **Schema-level renames** (`ALTER SCHEMA … RENAME TO`) — schemas are not modeled
+  as renameable IR entities, so a schema rename degrades to a data-losing
+  drop+create; not blessed as supported output. (`change schema with tables #1`,
+  `change table schema #6`, `enums #5`.)
+- **Enum quoting in column ops** — `ADD COLUMN` emits a bare enum type name
+  (`my_enum` / `my_enum[]`) instead of `"my_enum"`, and `SET DEFAULT` emits a bare
+  enum literal (`value3`) instead of `'value3'`; needs the lowering to resolve
+  user-defined types/defaults against the enum registry. (`enums #20`, `enums #21`,
+  `column is enum type … add default`.)
+- **Error-case fixtures** — duplicate check-constraint / view / materialized-view
+  names that Postgres rejects; the differ does not yet model rejection, so there is
+  no SQL contract to assert.
 
 ## Non-goals (for now)
 
diff --git a/crates/postgres-kit/tests/corpus/columns.rs b/crates/postgres-kit/tests/corpus/columns.rs
@@ -5,10 +5,8 @@
 //! rename hints into [`DiffCase::renames`], and the asserted statement output into
 //! [`DiffCase::expected_sql`].
 //!
-//! Some scenarios in this file assert only a structured statement encoding (never
-//! the rendered SQL), so they are recorded as [`Status::Skip`] with reason
-//! `"statements-only encoding"` — the schemas are still translated faithfully so
-//! the differ agent can promote them later by supplying the expected SQL.
+//! Every scenario in this file asserts the rendered SQL the differ emits for the
+//! `from`/`to` pair under normalized comparison.
 
 use postgres_kit::differ::ir::{
     SchemaSnapshot, SnapColumn, SnapCompositePk, SnapForeignKey, SnapTable,
@@ -34,8 +32,8 @@ pub fn cases() -> Vec<DiffCase> {
                 )
                 .build(),
             renames: &[],
-            expected_sql: &[],
-            status: Status::Skip("statements-only encoding"),
+            expected_sql: &["ALTER TABLE \"users\" ADD COLUMN \"name\" text;"],
+            status: Status::Supported,
         },
         // ---- add columns #2 ----
         // schema1: users { id serial primaryKey }
@@ -54,8 +52,11 @@ pub fn cases() -> Vec<DiffCase> {
                 )
                 .build(),
             renames: &[],
-            expected_sql: &[],
-            status: Status::Skip("statements-only encoding"),
+            expected_sql: &[
+                "ALTER TABLE \"users\" ADD COLUMN \"email\" text;",
+                "ALTER TABLE \"users\" ADD COLUMN \"name\" text;",
+            ],
+            status: Status::Supported,
         },
         // ---- alter column change name #1 ----
         // schema1: users { id serial primaryKey, name text('name') }
@@ -77,8 +78,8 @@ pub fn cases() -> Vec<DiffCase> {
                 )
                 .build(),
             renames: &["public.users.name->public.users.name1"],
-            expected_sql: &[],
-            status: Status::Skip("statements-only encoding"),
+            expected_sql: &["ALTER TABLE \"users\" RENAME COLUMN \"name\" TO \"name1\";"],
+            status: Status::Supported,
         },
         // ---- alter column change name #2 ----
         // schema1: users { id serial primaryKey, name text('name') }
@@ -101,8 +102,11 @@ pub fn cases() -> Vec<DiffCase> {
                 )
                 .build(),
             renames: &["public.users.name->public.users.name1"],
-            expected_sql: &[],
-            status: Status::Skip("statements-only encoding"),
+            expected_sql: &[
+                "ALTER TABLE \"users\" RENAME COLUMN \"name\" TO \"name1\";",
+                "ALTER TABLE \"users\" ADD COLUMN \"email\" text;",
+            ],
+            status: Status::Supported,
         },
         // ---- alter table add composite pk ----
         // schema1: table { id1 integer, id2 integer }
@@ -145,8 +149,11 @@ pub fn cases() -> Vec<DiffCase> {
                 "public.users->public.users1",
                 "public.users1.id->public.users1.id1",
             ],
-            expected_sql: &[],
-            status: Status::Skip("statements-only encoding"),
+            expected_sql: &[
+                "ALTER TABLE \"users\" RENAME TO \"users1\";",
+                "ALTER TABLE \"users1\" RENAME COLUMN \"id\" TO \"id1\";",
+            ],
+            status: Status::Supported,
         },
         // ---- with composite pks #1 ----
         // schema1: users { id1, id2, pk(id1,id2 name=compositePK) }
@@ -171,8 +178,8 @@ pub fn cases() -> Vec<DiffCase> {
                 )
                 .build(),
             renames: &[],
-            expected_sql: &[],
-            status: Status::Skip("statements-only encoding"),
+            expected_sql: &["ALTER TABLE \"users\" ADD COLUMN \"text\" text;"],
+            status: Status::Supported,
         },
         // ---- with composite pks #2 ----
         // schema1: users { id1, id2 }
@@ -195,8 +202,10 @@ pub fn cases() -> Vec<DiffCase> {
                 )
                 .build(),
             renames: &[],
-            expected_sql: &[],
-            status: Status::Skip("statements-only encoding"),
+            expected_sql: &[
+                "ALTER TABLE \"users\" ADD CONSTRAINT \"compositePK\" PRIMARY KEY(\"id1\",\"id2\");",
+            ],
+            status: Status::Supported,
         },
         // ---- with composite pks #3 ----
         // schema1: users { id1, id2, pk(id1,id2 name=compositePK) }
@@ -220,8 +229,11 @@ pub fn cases() -> Vec<DiffCase> {
                 )
                 .build(),
             renames: &["public.users.id2->public.users.id3"],
-            expected_sql: &[],
-            status: Status::Skip("statements-only encoding"),
+            expected_sql: &[
+                "ALTER TABLE \"users\" RENAME COLUMN \"id2\" TO \"id3\";",
+                "ALTER TABLE \"users\" DROP CONSTRAINT \"compositePK\";\n--> statement-breakpoint\nALTER TABLE \"users\" ADD CONSTRAINT \"compositePK\" PRIMARY KEY(\"id1\",\"id3\");",
+            ],
+            status: Status::Supported,
         },
         // ---- add multiple constraints #1 ----
         // Adds onDelete actions to three FKs across three referenced tables.
diff --git a/crates/postgres-kit/tests/corpus/enums.rs b/crates/postgres-kit/tests/corpus/enums.rs
@@ -273,7 +273,9 @@ pub fn cases() -> Vec<DiffCase> {
                 "ALTER TABLE \"table\" ADD COLUMN \"col1\" \"my_enum\";",
                 "ALTER TABLE \"table\" ADD COLUMN \"col2\" integer;",
             ],
-            status: Status::Skip("column add — columns category"),
+            status: Status::Skip(
+                "follow-up: ADD COLUMN does not quote enum type names (emits bare my_enum)",
+            ),
         },
         // enums #21 — add array columns (enum array + integer array) to a table.
         DiffCase {
@@ -296,7 +298,9 @@ pub fn cases() -> Vec<DiffCase> {
                 "ALTER TABLE \"table\" ADD COLUMN \"col1\" \"my_enum\"[];",
                 "ALTER TABLE \"table\" ADD COLUMN \"col2\" integer[];",
             ],
-            status: Status::Skip("array column add — columns category"),
+            status: Status::Skip(
+                "follow-up: ADD COLUMN does not quote enum array type names (emits bare my_enum[])",
+            ),
         },
         // drop enum value — value removal recreates the type (no dependent columns).
         DiffCase {
@@ -528,7 +532,9 @@ pub fn cases() -> Vec<DiffCase> {
             to: enum_table("enum", &["value1", "value3"], "table", "column", "enum", Some("value3")),
             renames: &[],
             expected_sql: &["ALTER TABLE \"table\" ALTER COLUMN \"column\" SET DEFAULT 'value3';"],
-            status: Status::Skip("column default add — columns category"),
+            status: Status::Skip(
+                "follow-up: SET DEFAULT does not quote enum literal (emits bare value3)",
+            ),
         },
         // change data type from standart type to enum.
         DiffCase {
diff --git a/crates/postgres-kit/tests/corpus/tables.rs b/crates/postgres-kit/tests/corpus/tables.rs
