mega-framework 0.1.6 → 0.1.7

package/src/core/migration/differ.js

@@ -0,0 +1,456 @@
+// @ts-check
+/**
+ * 스키마 diff 엔진 (ADR-204) — 직전 snapshot 의 모델 record 와 현재 record 를 비교해
+ * 변경 연산(op) 목록을 산출한다. SQL 렌더는 dialect({@link module:core/migration/dialects/postgres})
+ * 책임 — 본 모듈은 dialect 비의존 연산만 만든다(인덱스 이름 계산만 주입식).
+ *
+ * # rename 감지 (자동 추론 금지 — P1)
+ *   같은 테이블에서 컬럼 drop + add 가 동시에 보이면 rename 인지 기계적으로 알 수 없다(이름만으로
+ *   구분 불가 — drop+add 로 처리하면 데이터 손실). 그래서 두 단계로 푼다:
+ *   1) `diffModels(...)` 가 `renameCandidates` 를 함께 반환 — 호출자(CLI)가 사용자에게 확인
+ *      (interactive prompt 또는 `--renames "old:new"`).
+ *   2) 확정 매핑을 `renames` 로 다시 넘기면 drop+add 쌍이 `renameColumn` 으로 합성되고,
+ *      rename 후 정의 차이(타입·제약)는 추가 op 로 이어진다.
+ *
+ * # op 순서 (up 기준 — down 은 dialect 가 역순 렌더)
+ *   제약/인덱스 해제 → 컬럼 drop → 테이블 drop → 테이블 create → rename → 컬럼 변경 →
+ *   컬럼 add → 제약 add(FK 는 모든 테이블 생성 뒤) → 인덱스 add. FK 를 createTable 과 분리해
+ *   같은 마이그레이션 안의 상호 참조 테이블 생성 순서 문제를 제거한다.
+ *
+ * @module core/migration/differ
+ */
+import { MegaConfigError } from '../../errors/config-error.js'
+import * as postgresDialect from './dialects/postgres.js'
+
+/** up 적용 순서 phase — 숫자가 작을수록 먼저. */
+const PHASE = {
+  dropIndex: 0,
+  dropFk: 1,
+  dropCheck: 2,
+  dropUnique: 2,
+  dropPk: 2,
+  dropColumn: 3,
+  dropTable: 4,
+  createTable: 5,
+  renameColumn: 6,
+  renameFk: 6,
+  alterType: 7,
+  setNotNull: 7,
+  dropNotNull: 7,
+  setDefault: 7,
+  dropDefault: 7,
+  setComment: 7,
+  changePk: 7,
+  rebuildTable: 7,
+  addColumn: 8,
+  addPk: 9,
+  addUnique: 9,
+  addCheck: 9,
+  addFk: 10,
+  addIndex: 11,
+}
+
+/**
+ * `dependsOnRebuild` dialect(sqlite)에서 테이블 재생성이 필요한 변경 종류 — sqlite 의 ALTER 가
+ * 표현하지 못하는 연산들. 이 중 하나라도 있으면 그 테이블의 모든 op 를 `rebuildTable` 1개로
+ * 수렴한다(재생성이 to-스키마 전체·인덱스를 재구성하므로 부분 op 는 무의미).
+ */
+const REBUILD_TRIGGER_KINDS = new Set([
+  'alterType', 'setNotNull', 'dropNotNull', 'setDefault', 'dropDefault',
+  'addCheck', 'dropCheck', 'addFk', 'dropFk', 'renameFk', 'addPk', 'dropPk', 'changePk', 'dropColumn',
+])
+
+/** @param {unknown} a @param {unknown} b @returns {boolean} 구조 동등 비교(JSON 직렬화 기준 — record 는 plain). */
+function isEqual(a, b) {
+  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null)
+}
+
+/**
+ * 컬럼 def 의 "타입 시그니처" — 타입 식별 필드만 (제약 제외). enum values 의 소속은 dialect 의
+ * `enumStrategy` 가 정한다: 'check'(postgres/sqlite)면 CHECK 제약(값 변경 = 제약 교체),
+ * 'enum-type'(maria 의 native ENUM)이면 타입의 일부(값 변경 = MODIFY COLUMN = alterType).
+ * @param {Record<string, any>} def @param {Record<string, any>} dialect @returns {any}
+ */
+function typeSignature(def, dialect) {
+  return {
+    type: def.type,
+    length: def.length ?? null,
+    precision: def.precision ?? null,
+    scale: def.scale ?? null,
+    values: dialect.enumStrategy === 'enum-type' && def.type === 'enum' ? def.values : null,
+    // mongo 의 중첩 구조(object shape / array items)는 타입의 일부 — 변경이 op 로 잡혀야
+    // validator 교체가 생성된다. SQL dialect 에선 항상 null(영향 0).
+    shape: def.shape ?? null,
+    items: def.items ?? null,
+    uniqueItems: def.uniqueItems ?? null,
+  }
+}
+
+/**
+ * 컬럼의 CHECK 제약(명시 check + enum 값 제약) 정규화 — enum 은 values 를 그대로 둔다.
+ * **SQL 식은 만들지 않는다** — 렌더(식별자 인용 포함)는 전적으로 dialect 책임이라, op 에는
+ * expr(명시 check 의 raw 식) 또는 values(enum)만 싣는다. enum-type 전략 dialect 에선 enum 이
+ * 타입 소속이라 CHECK 로 취급하지 않는다.
+ * @param {string} table @param {string} col @param {Record<string, any>} def
+ * @param {Record<string, any>} dialect
+ * @returns {{ name: string, expr: string } | { name: string, values: string[] } | null}
+ */
+function checkOf(table, col, def, dialect) {
+  if (def.check !== undefined) return { name: def.check.name ?? dialect.checkName(table, col), expr: def.check.expr }
+  if (def.type === 'enum' && dialect.enumStrategy !== 'enum-type') return { name: def.enumName ?? dialect.checkName(table, col), values: def.values }
+  return null
+}
+
+/**
+ * UNIQUE 제약 정규화 — { name } | null.
+ * @param {string} table @param {string} col @param {Record<string, any>} def
+ * @param {Record<string, any>} dialect
+ * @returns {{ name: string } | null}
+ */
+function uniqueOf(table, col, def, dialect) {
+  if (def.unique === undefined) return null
+  return { name: def.unique === true ? dialect.uniqueName(table, col) : def.unique.name }
+}
+
+/**
+ * PK 정규화 — 복합(t.primary)=명시 명명(pkName), CREATE TABLE 인라인 단일 .primary() 는
+ * 서버 자동 명명(inlinePkName — dialect 별 상이).
+ * @param {Record<string, any>} record
+ * @param {Record<string, any>} dialect
+ * @returns {{ columns: string[], name: string } | null}
+ */
+function pkOf(record, dialect) {
+  if (record.primaryKey !== undefined) return { columns: record.primaryKey, name: dialect.pkName(record.table) }
+  const single = Object.entries(record.columns).find(([, def]) => def.primary === true)
+  if (single !== undefined) return { columns: [single[0]], name: dialect.inlinePkName(record.table) }
+  return null
+}
+
+/** SERIAL 계열 — 타입이 아니라 SEQUENCE+DEFAULT 합성이라 ALTER TYPE 전환이 불가능하다. */
+const SERIAL_TYPES = new Set(['serial', 'bigSerial'])
+
+/**
+ * FK 의 실 DB 제약 이름 확정 — 명시 name 우선, 없으면 **그 시점의 컬럼명**으로 합성한 기본 이름.
+ * prev 상태의 FK 를 드롭할 때 반드시 prev 컬럼명 기준 이름을 써야 한다(rename 이후 드리프트 방지).
+ * @param {string} table @param {string} col @param {Record<string, any>} ref
+ * @param {Record<string, any>} dialect
+ * @returns {Record<string, any>} name 이 확정된 ref 사본.
+ */
+function refWithName(table, col, ref, dialect) {
+  return { ...ref, name: ref.name ?? dialect.fkName(table, col, ref.table) }
+}
+
+/**
+ * 한 테이블(모델) 내부의 컬럼·인덱스·PK diff → ops 누적.
+ * @param {any} prev - 이전 record. @param {any} curr - 현재 record.
+ * @param {Record<string, string>} tableRenames - 이 테이블의 old→new 컬럼 매핑.
+ * @param {Array<Record<string, any>>} ops - 누적 대상.
+ * @param {Array<{ table: string, dropped: string[], added: string[] }>} candidates - rename 후보 누적.
+ * @param {Record<string, any>} dialect - 명명·렌더 능력의 정본(dialects/README.md contract).
+ */
+function diffTable(prev, curr, tableRenames, ops, candidates, dialect) {
+  const table = curr.table
+  const prevCols = prev.columns
+  const currCols = curr.columns
+  const prevNames = Object.keys(prevCols)
+  const currNames = Object.keys(currCols)
+
+  /** @type {string[]} */
+  const dropped = prevNames.filter((n) => currCols[n] === undefined)
+  /** @type {string[]} */
+  const added = currNames.filter((n) => prevCols[n] === undefined)
+
+  // rename 합성 — 확정 매핑이 있는 쌍은 renameColumn + (정의 차이는 아래 공통 비교로).
+  /** @type {Array<[string, string]>} 확정된 [old, new]. */
+  const renamedPairs = []
+  for (const [oldName, newName] of Object.entries(tableRenames)) {
+    if (dropped.includes(oldName) && added.includes(newName)) {
+      renamedPairs.push([oldName, newName])
+      dropped.splice(dropped.indexOf(oldName), 1)
+      added.splice(added.indexOf(newName), 1)
+      ops.push({ kind: 'renameColumn', table, from: oldName, to: newName })
+      // FK 기본 이름(fk_<table>_<col>_<ref>) 동기화 — 컬럼만 rename 하면 실 DB 제약은 옛 이름으로
+      // 남아 이후 FK 변경 마이그레이션이 못 찾는다. 명시 name 이면 드리프트가 없어 불필요.
+      // ALTER 로 FK 를 못 다루는 dialect(sqlite — supportsAlterAddFk=false)는 FK 가 인라인 정의라
+      // RENAME COLUMN 시 스키마가 자동 갱신되고 이름 추적 자체가 없어 동기화가 불필요하다.
+      const pRef = prevCols[oldName].references
+      const cRef = currCols[newName].references
+      if (dialect.supportsAlterAddFk !== false && pRef !== undefined && cRef !== undefined && pRef.name === undefined && cRef.name === undefined) {
+        const from = dialect.fkName(table, oldName, pRef.table)
+        const to = dialect.fkName(table, newName, cRef.table)
+        if (from !== to && isEqual(pRef, cRef)) {
+          if (dialect.supportsRenameConstraint === true) {
+            ops.push({ kind: 'renameFk', table, column: newName, from, to })
+          } else {
+            // RENAME CONSTRAINT 미지원 dialect — DROP+ADD 로 동기화(contract 의 대체 패턴).
+            // dropFk 는 prev 컬럼명 — down 의 재-ADD 가 rename 원복 후 실행되기 때문(아래 drop-측 주석).
+            ops.push({ kind: 'dropFk', table, column: oldName, ref: { ...pRef, name: from } })
+            ops.push({ kind: 'addFk', table, column: newName, ref: { ...cRef, name: to } })
+          }
+        }
+      }
+    }
+  }
+
+  // 남은 drop+add 동시 발생은 rename 후보로 보고(호출자가 확인 후 재호출).
+  if (dropped.length > 0 && added.length > 0) {
+    candidates.push({ table, dropped: [...dropped], added: [...added] })
+  }
+
+  for (const name of dropped) {
+    // 컬럼 drop 은 부속 제약을 함께 제거(postgres 의존 객체 cascade) — 단 InnoDB(maria)는 FK 가
+    // 걸린 컬럼의 DROP 을 거부한다(1553 — FK 인덱스 요구). 그런 dialect 는 dropFk 를 선행 발행하고
+    // dropColumn 의 def 에서 references 를 떼어 down 의 FK 재-ADD 가 dropFk.down 과 중복되지 않게
+    // 한다(down 역순: dropColumn.down 의 ADD COLUMN → dropFk.down 의 ADD CONSTRAINT — 순서 정합).
+    let def = prevCols[name]
+    if (def.references !== undefined && dialect.requiresDropFkBeforeDropColumn === true) {
+      ops.push({ kind: 'dropFk', table, column: name, ref: refWithName(table, name, def.references, dialect) })
+      def = { ...def }
+      delete def.references
+    }
+    ops.push({ kind: 'dropColumn', table, column: name, def })
+  }
+  for (const name of added) {
+    ops.push({ kind: 'addColumn', table, column: name, def: currCols[name] })
+    // FK 를 ALTER 로 추가하는 dialect 만 별도 op — sqlite 는 ADD COLUMN 절에 인라인 REFERENCES.
+    if (currCols[name].references !== undefined && dialect.supportsAlterAddFk !== false) {
+      ops.push({ kind: 'addFk', table, column: name, ref: currCols[name].references })
+    }
+  }
+
+  // 공통 컬럼(+rename 쌍) 정의 비교.
+  /** @type {Array<[string, string]>} [prevName, currName]. */
+  const commonPairs = currNames.filter((n) => prevCols[n] !== undefined).map((n) => /** @type {[string, string]} */ ([n, n]))
+  commonPairs.push(...renamedPairs)
+  for (const [pn, cn] of commonPairs) {
+    const p = prevCols[pn]
+    const c = currCols[cn]
+
+    if (!isEqual(typeSignature(p, dialect), typeSignature(c, dialect))) {
+      // SERIAL 전환은 ALTER TYPE 으로 표현되지 않는다(시퀀스+DEFAULT 합성) — silent no-op SQL 을
+      // 만드느니 명시 거부하고 raw 마이그레이션을 안내한다.
+      if (SERIAL_TYPES.has(p.type) !== SERIAL_TYPES.has(c.type)) {
+        throw new MegaConfigError(
+          'migration.unsupported_change',
+          `table '${table}' 컬럼 '${cn}': ${p.type} → ${c.type} 전환은 자동 생성이 불가능합니다 — SERIAL 은 타입이 아니라 ` +
+            'SEQUENCE+DEFAULT 합성이라 ALTER TYPE 으로 표현되지 않습니다. SEQUENCE 생성/OWNED BY/DEFAULT 변경을 ' +
+            'raw SQL 마이그레이션(mega generate migration)으로 작성하세요.',
+          { details: { table, column: cn, from: p.type, to: c.type } },
+        )
+      }
+      ops.push({ kind: 'alterType', table, column: cn, from: p, to: c })
+    }
+    // def 동반 — maria 의 NOT NULL 토글은 MODIFY COLUMN(전체 정의 필수)이라 대상 def 가 필요하다.
+    if ((p.notNull === true) !== (c.notNull === true)) {
+      ops.push({ kind: c.notNull === true ? 'setNotNull' : 'dropNotNull', table, column: cn, def: c })
+    }
+    if (!isEqual(p.default, c.default)) {
+      if (c.default === undefined) ops.push({ kind: 'dropDefault', table, column: cn, prev: p.default, def: c })
+      else ops.push({ kind: 'setDefault', table, column: cn, value: c.default, prev: p.default, def: c })
+    }
+
+    // drop-측 제약 op 는 **prev 컬럼명(pn)** 을 싣는다 — up 에서는 rename(phase 6) **전**(phase 1–2)에
+    // 이름으로 드롭하고, down 에서는 rename 원복 **후** 재-ADD 가 실행되므로 그 시점의 컬럼명은 pn 이다.
+    // cn 을 실으면 rename 동반 시 down 이 존재하지 않는 새 이름을 참조하는 invalid SQL 이 된다.
+    // add-측(phase 9–10)은 반대로 rename 이후/원복 이전에 실행돼 cn 이 정본.
+    const pu = uniqueOf(table, pn, p, dialect)
+    const cu = uniqueOf(table, cn, c, dialect)
+    if (!isEqual(pu, cu)) {
+      if (pu !== null) ops.push({ kind: 'dropUnique', table, column: pn, name: pu.name })
+      if (cu !== null) ops.push({ kind: 'addUnique', table, column: cn, name: cu.name })
+    }
+
+    const pc = checkOf(table, pn, p, dialect)
+    const cc = checkOf(table, cn, c, dialect)
+    if (!isEqual(pc, cc)) {
+      // expr/values 를 그대로 싣는다 — SQL 식 합성(식별자 인용 포함)은 dialect 의 renderOp 책임.
+      if (pc !== null) ops.push({ kind: 'dropCheck', table, column: pn, ...pc })
+      if (cc !== null) ops.push({ kind: 'addCheck', table, column: cn, ...cc })
+    }
+
+    if (!isEqual(p.references, c.references)) {
+      // prev FK 의 실 DB 이름은 prev 컬럼명 기준 — rename 동반 시에도 정확한 이름으로 드롭한다.
+      if (p.references !== undefined) ops.push({ kind: 'dropFk', table, column: pn, ref: refWithName(table, pn, p.references, dialect) })
+      if (c.references !== undefined) ops.push({ kind: 'addFk', table, column: cn, ref: c.references })
+    }
+
+    if (!isEqual(p.comment, c.comment)) {
+      ops.push({ kind: 'setComment', table, column: cn, comment: c.comment ?? null, prev: p.comment, def: c, prevDef: p })
+    }
+  }
+
+  // PK 변경 — 인라인 단일(서버 자동 명명) vs 명시 명명(pk_<table>) 출처를 정규화가 흡수.
+  // 교체(drop+add 동시)는 changePk 1개로 — InnoDB 는 FK 인덱스를 겸하는 PK 의 단독 DROP 을
+  // 거부하므로(errno 150) maria 가 한 문장(DROP PRIMARY KEY, ADD PRIMARY KEY)으로 묶어야 한다.
+  const ppk = pkOf(prev, dialect)
+  const cpk = pkOf(curr, dialect)
+  if (!isEqual(ppk, cpk)) {
+    if (ppk !== null && cpk !== null) {
+      ops.push({ kind: 'changePk', table, from: ppk, to: cpk })
+    } else if (ppk !== null) {
+      ops.push({ kind: 'dropPk', table, columns: ppk.columns, name: ppk.name })
+    } else if (cpk !== null) {
+      ops.push({ kind: 'addPk', table, columns: cpk.columns, name: cpk.name })
+    }
+  }
+
+  // 인덱스 — 유효 이름으로 식별, 같은 이름의 정의 변경은 drop+add.
+  /** @type {Map<string, any>} */
+  const prevIx = new Map((prev.indexes ?? []).map((/** @type {any} */ ix) => [dialect.resolveIndexName(table, ix), ix]))
+  /** @type {Map<string, any>} */
+  const currIx = new Map((curr.indexes ?? []).map((/** @type {any} */ ix) => [dialect.resolveIndexName(table, ix), ix]))
+  for (const [name, ix] of prevIx) {
+    const now = currIx.get(name)
+    if (now === undefined) ops.push({ kind: 'dropIndex', table, index: ix })
+    else if (!isEqual(ix, now)) {
+      ops.push({ kind: 'dropIndex', table, index: ix })
+      ops.push({ kind: 'addIndex', table, index: now })
+    }
+  }
+  for (const [name, ix] of currIx) {
+    if (!prevIx.has(name)) ops.push({ kind: 'addIndex', table, index: ix })
+  }
+}
+
+/**
+ * 한 adapter 그룹의 모델 목록 diff.
+ *
+ * @param {Array<{ name: string, table: string, record: any }>} prevModels - 직전 snapshot 의 모델.
+ * @param {Array<{ name: string, table: string, record: any }>} currModels - 현재 스캔 모델.
+ * @param {{ renames?: Record<string, Record<string, string>>, dialect?: Record<string, any> }} [opts]
+ *   - renames: `{ [table]: { old: new } }` 확정 rename 매핑(미지정 시 drop+add 로 두고 후보만 보고).
+ *   - dialect: 명명·능력 contract(기본 postgres — 호출자는 driver 별 dialect 를 주입).
+ * @returns {{ ops: Array<Record<string, any>>, renameCandidates: Array<{ table: string, dropped: string[], added: string[] }> }}
+ */
+export function diffModels(prevModels, currModels, { renames = {}, dialect = postgresDialect } = {}) {
+  /** @type {Array<Record<string, any>>} */
+  const ops = []
+  /** @type {Array<{ table: string, dropped: string[], added: string[] }>} */
+  const renameCandidates = []
+
+  const prevByName = new Map(prevModels.map((m) => [m.name, m]))
+  const currByName = new Map(currModels.map((m) => [m.name, m]))
+
+  /**
+   * 테이블 제거 — 보유 FK 의 dropFk 를 **선행 발행**(phase 1 < dropTable 4)한다. FK 로 얽힌
+   * 테이블들을 함께 제거할 때 DROP 순서(이름순)에 의존하면 피참조 테이블이 먼저 떨어져
+   * "cannot drop table … depend on it" 으로 실패한다 — FK 를 전부 끊고 나면 순서 무관.
+   * 상호/순환 참조도 같은 이유로 안전하다(위상 정렬 불요).
+   * ALTER 로 FK 를 못 다루는 dialect(sqlite)는 dropFk 자체가 불가능 — dialect 의 dropTable 렌더가
+   * 트랜잭션 내 `PRAGMA defer_foreign_keys` 로 순서 문제를 흡수한다.
+   * @param {{ table: string, record: any }} prev
+   */
+  const dropTableWithFks = (prev) => {
+    if (dialect.supportsAlterAddFk !== false) {
+      for (const [col, def] of Object.entries(prev.record.columns)) {
+        const ref = /** @type {any} */ (def).references
+        if (ref !== undefined) {
+          ops.push({ kind: 'dropFk', table: prev.table, column: col, ref: refWithName(prev.table, col, ref, dialect) })
+        }
+      }
+    }
+    ops.push({ kind: 'dropTable', table: prev.table, record: prev.record })
+  }
+
+  /**
+   * 테이블 생성 — FK 분리 가능 dialect 는 모든 createTable 뒤 phase 의 addFk 로(상호 참조 안전),
+   * sqlite 는 인라인 FK(스키마에 forward reference 허용 — 적용은 DML 시점)라 분리 op 없음.
+   * @param {{ table: string, record: any }} curr
+   */
+  const createTableWithFks = (curr) => {
+    ops.push({ kind: 'createTable', table: curr.table, record: curr.record })
+    if (dialect.supportsAlterAddFk !== false) {
+      for (const [col, def] of Object.entries(curr.record.columns)) {
+        if (/** @type {any} */ (def).references !== undefined) {
+          ops.push({ kind: 'addFk', table: curr.table, column: col, ref: /** @type {any} */ (def).references })
+        }
+      }
+    }
+    for (const ix of curr.record.indexes ?? []) {
+      ops.push({ kind: 'addIndex', table: curr.table, index: ix })
+    }
+  }
+
+  for (const [name, prev] of prevByName) {
+    if (!currByName.has(name)) {
+      dropTableWithFks(prev)
+    }
+  }
+  for (const [name, curr] of currByName) {
+    const prev = prevByName.get(name)
+    if (prev === undefined) {
+      createTableWithFks(curr)
+      continue
+    }
+    if (prev.table !== curr.table) {
+      // 테이블 이름 변경은 모델 단위 drop+create 로 본다(데이터 이전은 자동화 범위 밖 — escape hatch).
+      dropTableWithFks(prev)
+      createTableWithFks(curr)
+      continue
+    }
+    // 테이블 내부 diff — rebuild dialect(sqlite)는 ALTER 로 표현 못하는 변경이 하나라도 있으면
+    // 그 테이블의 모든 op 를 rebuildTable 1개로 수렴한다(12-step 재생성이 to-스키마 전체를 재구성).
+    /** @type {Array<Record<string, any>>} */
+    const tableOps = []
+    const tableRenames = renames[curr.table] ?? {}
+    diffTable(prev.record, curr.record, tableRenames, tableOps, renameCandidates, dialect)
+    // 수렴 트리거는 dialect 가 확장할 수 있다 — mongo 는 validator 가 통짜라 addColumn/renameColumn
+    // 등 모든 컬럼 수준 변경이 수렴 대상(rebuildTriggerKinds, ADR-209). 기본은 sqlite 집합.
+    const triggerKinds = dialect.rebuildTriggerKinds instanceof Set ? dialect.rebuildTriggerKinds : REBUILD_TRIGGER_KINDS
+    if (dialect.dependsOnRebuild === true && tableOps.some((op) => triggerKinds.has(op.kind))) {
+      ops.push({ kind: 'rebuildTable', table: curr.table, from: prev.record, to: curr.record, renames: tableRenames })
+    } else {
+      ops.push(...tableOps)
+    }
+  }
+
+  // phase 정렬(stable) — 같은 phase 안에서는 산출 순서 유지.
+  const phaseOf = (/** @type {any} */ op) => /** @type {Record<string, number>} */ (PHASE)[op.kind]
+  const sorted = ops.map((op, i) => ({ op, i })).sort((a, b) => (phaseOf(a.op) - phaseOf(b.op)) || (a.i - b.i)).map((x) => x.op)
+  return { ops: sorted, renameCandidates }
+}
+
+/**
+ * `--renames "old:new,old2:new2"` 문자열을 테이블별 매핑으로 펼친다 — 후보 테이블의 dropped/added
+ * 에 해당 쌍이 있을 때만 그 테이블에 적용(테이블 간 동명 컬럼 오적용 방지).
+ *
+ * **어떤 후보와도 매치되지 않는 쌍은 fail-fast** 한다(`migration.rename_unmatched`) — 오타를
+ * 조용히 버리면 사용자는 rename 을 명시했다고 믿는 채 무경고 DROP COLUMN(데이터 손실) 마이그레이션이
+ * 생성된다(P1 보호의 입구).
+ *
+ * @param {string} spec - `old:new[,old:new...]`.
+ * @param {Array<{ table: string, dropped: string[], added: string[] }>} candidates
+ * @returns {Record<string, Record<string, string>>}
+ * @throws {MegaConfigError} `migration.rename_invalid` - 형식 오류. `migration.rename_unmatched` - 후보 불일치.
+ */
+export function parseRenamesSpec(spec, candidates) {
+  /** @type {Record<string, Record<string, string>>} */
+  const out = {}
+  for (const pair of spec.split(',').map((s) => s.trim()).filter((s) => s.length > 0)) {
+    const idx = pair.indexOf(':')
+    const oldName = idx === -1 ? '' : pair.slice(0, idx).trim()
+    const newName = idx === -1 ? '' : pair.slice(idx + 1).trim()
+    if (oldName.length === 0 || newName.length === 0) {
+      throw new MegaConfigError('migration.rename_invalid', `--renames 형식 오류: '${pair}' — "old:new[,old2:new2]" 형식이어야 합니다.`, {
+        details: { pair, spec },
+      })
+    }
+    let matched = false
+    for (const c of candidates) {
+      if (c.dropped.includes(oldName) && c.added.includes(newName)) {
+        out[c.table] = { ...(out[c.table] ?? {}), [oldName]: newName }
+        matched = true
+      }
+    }
+    if (!matched) {
+      throw new MegaConfigError(
+        'migration.rename_unmatched',
+        `--renames 매핑 '${oldName}:${newName}' 이 어떤 rename 후보와도 맞지 않습니다. ` +
+          `후보: ${candidates.map((c) => `${c.table}(drop: [${c.dropped.join(', ')}], add: [${c.added.join(', ')}])`).join(' / ') || '(없음)'}. ` +
+          '매핑의 오타를 수정하거나, 정말 drop+add 의도라면 해당 쌍을 매핑에서 제거하세요.',
+        { details: { pair: `${oldName}:${newName}`, candidates } },
+      )
+    }
+  }
+  return out
+}