@vibeorm/migrate 1.2.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeorm/migrate",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Migration, introspection, and schema diff toolkit for VibeORM",
   "license": "MIT",
   "keywords": [
@@ -37,6 +37,6 @@
     "bun": ">=1.1.0"
   },
   "dependencies": {
-    "@vibeorm/parser": "1.2.0"
+    "@vibeorm/parser": "1.3.1"
   }
 }

package/src/ddl-builder.ts

@@ -8,6 +8,7 @@
 import type { Schema, Model, Field, ScalarField, EnumField, RelationField, DefaultValue, Enum, EnumValue } from "@vibeorm/parser";
 import { PRISMA_TO_PG } from "@vibeorm/parser";
 import { buildFkActionClause } from "./cascade-actions.ts";
+import { detectImplicitM2MPairs } from "./relation-utils.ts";
 
 export type DDLResult = {
   /** The full DDL SQL wrapped in BEGIN/COMMIT */
@@ -298,68 +299,38 @@ type ImplicitManyToMany = {
 
 function detectImplicitManyToMany(params: { schema: Schema }): ImplicitManyToMany[] {
   const { schema } = params;
-  const result: ImplicitManyToMany[] = [];
-  const seen = new Set<string>();
 
-  for (const model of schema.models) {
-    for (const field of model.fields) {
-      if (field.kind !== "relation") continue;
-      if (!field.isList) continue;
-      if (field.relation.isForeignKey) continue;
-      if (field.relation.fields.length > 0) continue;
-
-      // Check if the other side is also a list with no FK fields
-      const relatedModel = schema.models.find((m) => m.name === field.relatedModel);
-      if (!relatedModel) continue;
-
-      const backRef = relatedModel.fields.find(
-        (f) =>
-          f.kind === "relation" &&
-          f.relatedModel === model.name &&
-          f.isList &&
-          !f.relation.isForeignKey &&
-          f.relation.fields.length === 0
-      );
-      if (!backRef) continue;
-
-      // Sort alphabetically for consistent naming
-      const sorted = [model.name, relatedModel.name].sort();
-      const nameA = sorted[0]!;
-      const nameB = sorted[1]!;
-      const key = `${nameA}_${nameB}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-
-      const modelADef = schema.models.find((m) => m.name === nameA)!;
-      const modelBDef = schema.models.find((m) => m.name === nameB)!;
-
-      const pkFieldA = modelADef.primaryKey.fields[0]!;
-      const pkFieldB = modelBDef.primaryKey.fields[0]!;
-
-      const pkFieldDefA = modelADef.fields.find((f) => f.name === pkFieldA);
-      const pkFieldDefB = modelBDef.fields.find((f) => f.name === pkFieldB);
-
-      const pkTypeA = pkFieldDefA && pkFieldDefA.kind === "scalar"
-        ? resolveBaseColumnType({ field: pkFieldDefA })
-        : "INTEGER";
-      const pkTypeB = pkFieldDefB && pkFieldDefB.kind === "scalar"
-        ? resolveBaseColumnType({ field: pkFieldDefB })
-        : "INTEGER";
-
-      result.push({
-        modelA: nameA,
-        modelB: nameB,
-        tableA: getDbName({ model: modelADef }),
-        tableB: getDbName({ model: modelBDef }),
-        pkFieldA,
-        pkFieldB,
-        pkTypeA,
-        pkTypeB,
-      });
-    }
-  }
-
-  return result;
+  // Detection lives in the shared helper (single source of truth with the
+  // schema differ); here we only resolve the per-table DDL details (PK column
+  // names + types) for each detected pair.
+  return detectImplicitM2MPairs({ schema }).map((pair) => {
+    const modelADef = schema.models.find((m) => m.name === pair.modelA)!;
+    const modelBDef = schema.models.find((m) => m.name === pair.modelB)!;
+
+    const pkFieldA = modelADef.primaryKey.fields[0]!;
+    const pkFieldB = modelBDef.primaryKey.fields[0]!;
+
+    const pkFieldDefA = modelADef.fields.find((f) => f.name === pkFieldA);
+    const pkFieldDefB = modelBDef.fields.find((f) => f.name === pkFieldB);
+
+    const pkTypeA = pkFieldDefA && pkFieldDefA.kind === "scalar"
+      ? resolveBaseColumnType({ field: pkFieldDefA })
+      : "INTEGER";
+    const pkTypeB = pkFieldDefB && pkFieldDefB.kind === "scalar"
+      ? resolveBaseColumnType({ field: pkFieldDefB })
+      : "INTEGER";
+
+    return {
+      modelA: pair.modelA,
+      modelB: pair.modelB,
+      tableA: getDbName({ model: modelADef }),
+      tableB: getDbName({ model: modelBDef }),
+      pkFieldA,
+      pkFieldB,
+      pkTypeA,
+      pkTypeB,
+    };
+  });
 }
 
 function buildJoinTableStatements(params: { joinTable: ImplicitManyToMany }): string[] {

package/src/introspector.ts

@@ -447,7 +447,7 @@ export async function introspect(params: { executor: SqlExecutor }): Promise<Sch
       const isUnique = uniqueColumns.has(`${tableName}.${col.columnName}`);
       const parsedDefault = parseDefault({ columnDefault: col.columnDefault, dataType: col.dataType });
 
-      // Check if this is an enum column
+      // Branch 1: scalar enum column (data_type=USER-DEFINED, udt_name=EnumName).
       if (col.dataType === "USER-DEFINED" && enumNames.has(col.udtName)) {
         const enumField: EnumField = {
           kind: "enum",
@@ -462,8 +462,33 @@ export async function introspect(params: { executor: SqlExecutor }): Promise<Sch
           documentation: undefined,
         };
         fields.push(enumField);
-      } else {
-        // Map PG type to Prisma type
+      }
+      // Branch 2: enum-array column. Postgres reports the underlying array type
+      // as `_EnumName` (the leading underscore is the array-type naming convention),
+      // and `data_type` is `ARRAY`. Without this branch the field would be parsed
+      // as `String[]` and the round-trip drift differ would always want to ALTER it.
+      // Bug 2 — see .ai/bug-report-2026-05-24.md.
+      else if (
+        col.dataType === "ARRAY" &&
+        col.udtName.startsWith("_") &&
+        enumNames.has(col.udtName.slice(1))
+      ) {
+        const enumField: EnumField = {
+          kind: "enum",
+          name: col.columnName,
+          dbName: col.columnName,
+          enumName: col.udtName.slice(1),
+          isRequired: !col.isNullable,
+          isList: true,
+          isId,
+          isUnique,
+          default: parsedDefault,
+          documentation: undefined,
+        };
+        fields.push(enumField);
+      }
+      // Branch 3: scalar / scalar-array fallback.
+      else {
         const pgType = col.dataType === "ARRAY" ? col.udtName.replace(/^_/, "") : col.udtName;
         const prismaType = PG_TO_PRISMA[pgType] ?? PG_TO_PRISMA[col.dataType] ?? "String";
         const isArray = col.dataType === "ARRAY";

package/src/relation-utils.ts

@@ -0,0 +1,79 @@
+/**
+ * Relation utilities — shared implicit many-to-many detection.
+ *
+ * Single source of truth for "which model pairs are joined by an implicit
+ * many-to-many table". Both the DDL builder (initial create / `migrate
+ * generate`) and the schema differ (`db push` / migration diffs) consume this
+ * so they can never drift apart — the previous divergence between those two
+ * copies was the root cause of phantom join tables for 1:N self-relations and
+ * for two separate 1:N relations between the same pair of models.
+ */
+
+import type { Schema, RelationField } from "@vibeorm/parser";
+
+/**
+ * A detected implicit many-to-many relation, identified by its two endpoint
+ * model names sorted alphabetically (matching Prisma's `_AToB` join-table
+ * naming convention). For a self-relation both names are equal.
+ */
+export type ImplicitM2MPair = {
+  readonly modelA: string;
+  readonly modelB: string;
+};
+
+/**
+ * Detect every implicit many-to-many relation in a schema.
+ *
+ * Pairing rule (kept in lock-step with the parser's `resolveRelationType`):
+ * two relation fields form an implicit M:N **iff** both are lists with no
+ * foreign key, they are **distinct fields** (self-relation safe), and their
+ * relation names match **symmetrically** — both unnamed, or both the same name.
+ *
+ * Detection is purely structural (it does not read `relation.type`), so it
+ * works for both parsed schemas (where each side carries `type: "manyToMany"`)
+ * and introspected schemas (where a real join table round-trips as two unnamed
+ * `oneToMany` list fields). That keeps the differ stable across round-trips.
+ */
+export function detectImplicitM2MPairs(params: { schema: Schema }): ImplicitM2MPair[] {
+  const { schema } = params;
+  const result: ImplicitM2MPair[] = [];
+  const seen = new Set<string>();
+
+  for (const model of schema.models) {
+    for (const field of model.fields) {
+      if (field.kind !== "relation") continue;
+      if (!field.isList) continue;
+      if (field.relation.isForeignKey) continue;
+      if (field.relation.fields.length > 0) continue;
+
+      const relatedModel = schema.models.find((m) => m.name === field.relatedModel);
+      if (!relatedModel) continue;
+
+      const backRef = relatedModel.fields.find(
+        (f): f is RelationField =>
+          f.kind === "relation" &&
+          // Self-exclusion: a list field must never pair with itself, otherwise
+          // every 1:N self-relation would be mistaken for an M:N self-relation.
+          f !== field &&
+          f.relatedModel === model.name &&
+          f.isList &&
+          !f.relation.isForeignKey &&
+          f.relation.fields.length === 0 &&
+          // Symmetric relation-name match — see doc comment above.
+          (f.relation.name ?? undefined) === (field.relation.name ?? undefined),
+      );
+      if (!backRef) continue;
+
+      const sorted = [model.name, relatedModel.name].sort();
+      const nameA = sorted[0]!;
+      const nameB = sorted[1]!;
+      const key = `${nameA}_${nameB}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      result.push({ modelA: nameA, modelB: nameB });
+    }
+  }
+
+  return result;
+}

package/src/schema-differ.ts

@@ -18,6 +18,7 @@ import type {
 } from "@vibeorm/parser";
 import { PRISMA_TO_PG } from "@vibeorm/parser";
 import { buildFkActionClause, fkActionFingerprint } from "./cascade-actions.ts";
+import { detectImplicitM2MPairs } from "./relation-utils.ts";
 
 // ─── Types ────────────────────────────────────────────────────────
 
@@ -72,8 +73,11 @@ function getRelationFields(params: { model: Model }): RelationField[] {
 function resolveColumnType(params: { field: ScalarField | EnumField; enums: Enum[] }): string {
   const { field, enums } = params;
   if (field.kind === "enum") {
+    // Enum lists must emit `EnumName[]`, not the scalar enum type. Mirrors
+    // `ddl-builder.ts:135-141`. Bug 2 — see .ai/bug-report-2026-05-24.md.
     const enumDef = enums.find((e) => e.name === field.enumName);
-    return q({ name: enumDef?.dbName ?? field.enumName });
+    const enumType = q({ name: enumDef?.dbName ?? field.enumName });
+    return field.isList ? `${enumType}[]` : enumType;
   }
   if (field.default?.kind === "autoincrement") {
     return field.prismaType === "BigInt" ? "BIGSERIAL" : "SERIAL";
@@ -87,8 +91,10 @@ function resolveColumnType(params: { field: ScalarField | EnumField; enums: Enum
 function resolveBaseColumnType(params: { field: ScalarField | EnumField; enums: Enum[] }): string {
   const { field, enums } = params;
   if (field.kind === "enum") {
+    // Same enum-list handling as resolveColumnType (Bug 2).
     const enumDef = enums.find((e) => e.name === field.enumName);
-    return q({ name: enumDef?.dbName ?? field.enumName });
+    const enumType = q({ name: enumDef?.dbName ?? field.enumName });
+    return field.isList ? `${enumType}[]` : enumType;
   }
   if (field.nativeType) return field.nativeType.toLowerCase();
   if (field.isList) return `${PRISMA_TO_PG[field.prismaType]}[]`;
@@ -201,45 +207,14 @@ type JoinTableInfo = {
 
 function detectImplicitManyToMany(params: { schema: Schema }): JoinTableInfo[] {
   const { schema } = params;
-  const result: JoinTableInfo[] = [];
-  const seen = new Set<string>();
-
-  for (const model of schema.models) {
-    for (const field of model.fields) {
-      if (field.kind !== "relation") continue;
-      if (!field.isList) continue;
-      if (field.relation.isForeignKey) continue;
-      if (field.relation.fields.length > 0) continue;
-
-      const relatedModel = schema.models.find((m: Model) => m.name === field.relatedModel);
-      if (!relatedModel) continue;
-
-      const backRef = relatedModel.fields.find(
-        (f: Field) =>
-          f.kind === "relation" &&
-          f.relatedModel === model.name &&
-          f.isList &&
-          !f.relation.isForeignKey &&
-          f.relation.fields.length === 0
-      );
-      if (!backRef) continue;
-
-      const sorted = [model.name, relatedModel.name].sort();
-      const nameA = sorted[0]!;
-      const nameB = sorted[1]!;
-      const key = `${nameA}_${nameB}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-
-      result.push({
-        modelA: nameA,
-        modelB: nameB,
-        tableName: `_${nameA}To${nameB}`,
-      });
-    }
-  }
 
-  return result;
+  // Detection lives in the shared helper (single source of truth with the DDL
+  // builder); here we only attach the `_AToB` join-table name to each pair.
+  return detectImplicitM2MPairs({ schema }).map((pair) => ({
+    modelA: pair.modelA,
+    modelB: pair.modelB,
+    tableName: `_${pair.modelA}To${pair.modelB}`,
+  }));
 }
 
 // ─── Main Differ ──────────────────────────────────────────────────
@@ -556,11 +531,25 @@ export function diffSchemas(params: { previous: Schema; current: Schema }): Diff
 
       // Type change — reverse is setting back to the previous type
       if (prevType !== currType) {
+        // Detect scalar -> array transition of same base type. PG can't implicit-cast,
+        // so we add a USING clause that wraps the existing value in a 1-element array
+        // (or NULL if the column is NULL). This heals databases broken by an earlier
+        // enum-array bug (Bug 2) where the column was created as the scalar type.
+        // We intentionally do NOT handle the reverse direction (array -> scalar) — that
+        // is lossy and the user must decide which element to keep.
+        const isScalarToArray =
+          currType.endsWith("[]") && !prevType.endsWith("[]") &&
+          currType.slice(0, -2) === prevType;
+
+        const usingClause = isScalarToArray
+          ? ` USING CASE WHEN ${q({ name: colName })} IS NULL THEN NULL ELSE ARRAY[${q({ name: colName })}] END`
+          : "";
+
         ops.push({
           type: "alterColumnType",
-          sql: `ALTER TABLE ${q({ name: tableName })} ALTER COLUMN ${q({ name: colName })} SET DATA TYPE ${currType};`,
+          sql: `ALTER TABLE ${q({ name: tableName })} ALTER COLUMN ${q({ name: colName })} SET DATA TYPE ${currType}${usingClause};`,
           downSql: `ALTER TABLE ${q({ name: tableName })} ALTER COLUMN ${q({ name: colName })} SET DATA TYPE ${prevType};`,
-          isDestructive: true,
+          isDestructive: !isScalarToArray, // scalar -> array is non-destructive (data preserved as 1-element arrays)
           isReversible: true,
           description: `Change type of "${fieldName}" in "${name}" from ${prevType} to ${currType}`,
         });