millas 0.2.12-beta → 0.2.12-beta-2

package/src/orm/migration/MigrationWriter.js

@@ -0,0 +1,463 @@
+'use strict';
+
+/**
+ * MigrationWriter
+ *
+ * Diffs two ProjectState objects and produces a list of Operations,
+ * then renders them as a clean, Django-style migration file.
+ *
+ * Generated file format mirrors Django closely:
+ *
+ *   // Generated by Millas 0.2.12 on 2026-03-17 14:30
+ *   const { migrations, fields } = require('millas/core/db');
+ *
+ *   module.exports = class Migration {
+ *     static initial = true;           // first migration only
+ *     static dependencies = [
+ *       ['system', '0001_users'],
+ *     ];
+ *     static operations = [
+ *       migrations.CreateModel({
+ *         name: 'Student',
+ *         fields: [
+ *           ['id',    fields.id()],
+ *           ['name',  fields.string({ max: 100 })],
+ *           ['age',   fields.integer()],
+ *         ],
+ *       }),
+ *       migrations.AddField({
+ *         modelName: 'student',
+ *         name: 'slug',
+ *         field: fields.string({ max: 255 }),
+ *         preserveDefault: false,
+ *       }),
+ *     ];
+ *   };
+ */
+
+const { fieldsEqual } = require('./utils');
+
+const MILLAS_VERSION = (() => {
+  try { return require('../../..').version || require('../../../package.json').version; } catch {}
+  try { return require('../../../package.json').version; } catch {}
+  return '0.x';
+})();
+
+// Tables created by system migrations — never appear in app migrations.
+// NOTE: 'users' is intentionally absent — the app owns its own user table
+// by defining a User model that extends AuthUser (abstract). Same as Django's
+// AUTH_USER_MODEL pattern where AbstractUser creates no table.
+const SYSTEM_TABLES = new Set([
+  'millas_admin_log',
+  'millas_sessions',
+  'millas_migrations',
+]);
+
+class MigrationWriter {
+
+  // ─── Diff ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Diff history state vs current state → list of operation descriptors.
+   */
+  diff(historyState, currentState) {
+    const ops     = [];
+    const histSch = historyState.toSchema();
+    const currSch = currentState.toSchema();
+
+    // New tables
+    const newTableOps = [];
+    for (const table of Object.keys(currSch)) {
+      if (SYSTEM_TABLES.has(table)) continue;
+      if (!histSch[table]) {
+        newTableOps.push({ type: 'CreateModel', table, fields: currSch[table] });
+      }
+    }
+
+    // Topologically sort new CreateModel ops so that if Post has a FK → users,
+    // CreateModel(users) appears before CreateModel(posts) in the migration file.
+    // Cycles are detected and noted — the two-pass FK creation in Operations.js
+    // handles them safely at migrate time.
+    ops.push(...this._sortCreateModels(newTableOps));
+
+    // Dropped tables
+    for (const table of Object.keys(histSch)) {
+      if (SYSTEM_TABLES.has(table)) continue;
+      if (!currSch[table]) {
+        ops.push({ type: 'DeleteModel', table, fields: histSch[table] });
+      }
+    }
+
+    // Column-level changes
+    for (const table of Object.keys(currSch)) {
+      if (SYSTEM_TABLES.has(table)) continue;
+      if (!histSch[table]) continue;
+
+      const curr = currSch[table];
+      const prev = histSch[table];
+
+      for (const col of Object.keys(curr)) {
+        if (!prev[col]) {
+          const field = curr[col];
+          const isDangerous = !field.nullable &&
+                              (field.default === null || field.default === undefined) &&
+                              field.type !== 'id' &&
+                              !!histSch[table];
+          ops.push({ type: 'AddField', table, column: col, field, _needsDefault: isDangerous });
+        } else if (!this._fieldsEqual(curr[col], prev[col])) {
+          ops.push({ type: 'AlterField', table, column: col, field: curr[col], previousField: prev[col] });
+        }
+      }
+
+      for (const col of Object.keys(prev)) {
+        if (!curr[col]) {
+          ops.push({ type: 'RemoveField', table, column: col, field: prev[col] });
+        }
+      }
+    }
+
+    return ops;
+  }
+
+  // ─── Render ────────────────────────────────────────────────────────────────
+
+  /**
+   * Render a complete migration file as JavaScript source.
+   *
+   * @param {Array<object>}  ops          — from diff(), already resolved
+   * @param {Array<Array>}   dependencies — [[source, migName], ...]
+   * @param {string}         name         — snake_case migration name
+   * @param {object}         meta         — { initial?, number, date }
+   */
+  render(ops, dependencies, name, meta = {}) {
+    const date     = meta.date || new Date().toISOString().replace('T', ' ').slice(0, 16);
+    const isInitial = meta.initial || false;
+
+    // ── Header ────────────────────────────────────────────────────────────────
+    const header = `// Generated by Millas ${MILLAS_VERSION} on ${date}`;
+
+    // ── Dependencies ──────────────────────────────────────────────────────────
+    const depsCode = dependencies.length > 0
+      ? `[\n${dependencies.map(([s, n]) => `    ['${s}', '${n}'],`).join('\n')}\n  ]`
+      : '[]';
+
+    // ── Operations ────────────────────────────────────────────────────────────
+    const opsCode = ops.map(op => '    ' + this._renderOp(op)).join(',\n\n');
+
+    // ── initial flag ─────────────────────────────────────────────────────────
+    const initialLine = isInitial ? '\n  static initial = true;\n' : '';
+
+    return `${header}
+
+const { migrations, fields } = require('millas/core/db');
+
+module.exports = class Migration {
+  static dependencies = ${depsCode};
+${initialLine}
+  static operations = [
+${opsCode},
+  ];
+};
+`;
+  }
+
+  // ─── Operation rendering ──────────────────────────────────────────────────
+
+  _renderOp(op) {
+    switch (op.type) {
+
+      case 'CreateModel':
+        return `migrations.CreateModel({\n` +
+               `      name: '${this._modelName(op.table)}',\n` +
+               `      fields: [\n` +
+               Object.entries(op.fields)
+                 .map(([col, def]) => `        ['${col}', ${this._renderField(def)}],`)
+                 .join('\n') + '\n' +
+               `      ],\n` +
+               `    })`;
+
+      case 'DeleteModel':
+        // Django omits fields= — not needed in the migration file
+        return `migrations.DeleteModel({\n` +
+               `      name: '${this._modelName(op.table)}',\n` +
+               `    })`;
+
+      case 'AddField': {
+        const lines = [
+          `      modelName: '${op.table}',`,
+          `      name: '${op.column}',`,
+          `      field: ${this._renderField(op.field)},`,
+        ];
+        if (op.oneOffDefault !== undefined) {
+          lines.push(`      oneOffDefault: ${this._renderDefault(op.oneOffDefault)},`);
+          lines.push(`      preserveDefault: false,`);
+        }
+        return `migrations.AddField({\n${lines.join('\n')}\n    })`;
+      }
+
+      case 'RemoveField':
+        // Django omits field= — it's not needed in the migration file
+        return `migrations.RemoveField({\n` +
+               `      modelName: '${op.table}',\n` +
+               `      name: '${op.column}',\n` +
+               `    })`;
+
+      case 'AlterField':
+        return `migrations.AlterField({\n` +
+               `      modelName: '${op.table}',\n` +
+               `      name: '${op.column}',\n` +
+               `      field: ${this._renderField(op.field)},\n` +
+               `    })`;
+
+      case 'RenameField':
+        return `migrations.RenameField({\n` +
+               `      modelName: '${op.table}',\n` +
+               `      oldName: '${op.oldColumn}',\n` +
+               `      newName: '${op.newColumn}',\n` +
+               `    })`;
+
+      case 'RenameModel':
+        return `migrations.RenameModel({\n` +
+               `      oldName: '${op.oldTable}',\n` +
+               `      newName: '${op.newTable}',\n` +
+               `    })`;
+
+      case 'RunSQL':
+        return `migrations.RunSQL({\n` +
+               `      sql: ${JSON.stringify(op.sql)},\n` +
+               (op.reverseSql ? `      reverseSql: ${JSON.stringify(op.reverseSql)},\n` : '') +
+               `    })`;
+
+      default:
+        return `/* unknown: ${JSON.stringify(op)} */`;
+    }
+  }
+
+  /**
+   * Render a field definition as a readable `fields.xxx(...)` call.
+   * This is the key readability improvement over JSON.stringify.
+   *
+   * Examples:
+   *   fields.id()
+   *   fields.string({ max: 100 })
+   *   fields.string({ max: 255, unique: true })
+   *   fields.integer({ nullable: true })
+   *   fields.boolean({ default: false })
+   *   fields.decimal(10, 4)
+   *   fields.decimal(10, 4, { default: 0 })
+   *   fields.enum(['admin', 'user'], { default: 'user' })
+   *   fields.timestamp({ nullable: true })
+   */
+  _renderField(def) {
+    if (!def) return 'fields.string()';
+
+    // ── ForeignKey / OneToOne ─────────────────────────────────────────────────
+    // Both are stored as type:'integer' with _isForeignKey:true after normalisation.
+    // Render as fields.ForeignKey('table', {...}) / fields.OneToOne('table', {...})
+    // so the generated migration file is human-readable and round-trips correctly.
+    if (def._isForeignKey && def.references) {
+      const fn    = def._isOneToOne ? 'OneToOne' : 'ForeignKey';
+      const table = def.references.table;
+      const opts  = {};
+      if (def.nullable)                                          opts.nullable  = true;
+      const onDelete = def._fkOnDelete ?? def.references.onDelete ?? 'CASCADE';
+      if (onDelete !== 'CASCADE')                                opts.onDelete  = onDelete;
+      const toField = def.references.column ?? 'id';
+      if (toField !== 'id')                                      opts.toField   = toField;
+      if (def._fkRelatedName)                                    opts.relatedName = def._fkRelatedName;
+      const optsStr = Object.keys(opts).length
+        ? `, ${this._renderOpts(opts)}`
+        : '';
+      return `fields.${fn}('${table}'${optsStr})`;
+    }
+
+    const type = def.type || 'string';
+
+    // ── decimal: positional args (precision, scale, options) ─────────────────
+    // fields.decimal() signature is decimal(precision=8, scale=2, options={})
+    // We must NOT pass precision/scale in the options object — they are positional.
+    if (type === 'decimal') {
+      const precision = def.precision ?? 8;
+      const scale     = def.scale     ?? 2;
+      const isDefaultPrecision = precision === 8;
+      const isDefaultScale     = scale === 2;
+
+      // Extra options (anything besides precision/scale)
+      const extraOpts = {};
+      if (def.nullable === true)                               extraOpts.nullable = true;
+      if (def.unique   === true)                               extraOpts.unique   = true;
+      if (def.default  !== null && def.default !== undefined)  extraOpts.default  = def.default;
+
+      const hasExtra = Object.keys(extraOpts).length > 0;
+
+      if (isDefaultPrecision && isDefaultScale && !hasExtra) {
+        // fields.decimal()
+        return 'fields.decimal()';
+      }
+      if (isDefaultPrecision && isDefaultScale && hasExtra) {
+        // fields.decimal(8, 2, { default: 0 }) — but since 8,2 are defaults, omit them
+        // Actually we must pass them explicitly so the reader gets correct positional args
+        return `fields.decimal(8, 2, ${this._renderOpts(extraOpts)})`;
+      }
+      if (!hasExtra) {
+        // fields.decimal(10, 4)
+        return `fields.decimal(${precision}, ${scale})`;
+      }
+      // fields.decimal(10, 4, { default: 0 })
+      return `fields.decimal(${precision}, ${scale}, ${this._renderOpts(extraOpts)})`;
+    }
+
+    // Collect non-default options only — keeps output clean
+    const opts = {};
+    if (def.nullable  === true)                          opts.nullable  = true;
+    if (def.unique    === true)                          opts.unique    = true;
+    if (def.unsigned  === true)                          opts.unsigned  = true;
+    if (def.default   !== null && def.default !== undefined) opts.default = def.default;
+    if (def.max       !== null && def.max !== undefined && type !== 'id') opts.max = def.max;
+    if (def.references) opts.references = def.references;
+
+    switch (type) {
+      case 'id':
+        return 'fields.id()';
+
+      case 'enum': {
+        const vals = JSON.stringify(def.enumValues || []);
+        const optsStr = Object.keys(opts).length
+          ? `, ${this._renderOpts(opts)}`
+          : '';
+        return `fields.enum(${vals}${optsStr})`;
+      }
+
+      default: {
+        const optsStr = Object.keys(opts).length
+          ? `(${this._renderOpts(opts)})`
+          : '()';
+        return `fields.${type}${optsStr}`;
+      }
+    }
+  }
+
+  _renderOpts(opts) {
+    if (Object.keys(opts).length === 0) return '';
+    const entries = Object.entries(opts).map(([k, v]) => `${k}: ${JSON.stringify(v)}`);
+    return `{ ${entries.join(', ')} }`;
+  }
+
+  /**
+   * Render a oneOffDefault descriptor.
+   * Callable → readable expression string reference.
+   * Literal  → the value itself.
+   */
+  _renderDefault(descriptor) {
+    if (descriptor === null || descriptor === undefined) return 'null';
+    if (typeof descriptor === 'object' && 'kind' in descriptor) {
+      if (descriptor.kind === 'callable') return descriptor.expression;
+      if (descriptor.kind === 'literal')  return JSON.stringify(descriptor.value);
+    }
+    return JSON.stringify(descriptor); // legacy
+  }
+
+  // ─── Naming helpers ───────────────────────────────────────────────────────
+
+  /**
+   * Return the table name as-is for use in migration files.
+   * We write the actual table name (e.g. 'landlord_verification') directly
+   * so that _tableFromName() in the migrations proxy gets back the exact
+   * same string — no lossy PascalCase round-trip.
+   */
+  _modelName(table) {
+    return table;
+  }
+
+  /**
+   * Topologically sort a list of CreateModel ops by their FK dependencies.
+   *
+   * If Post has a FK → users, CreateModel(users) must come before
+   * CreateModel(posts). This makes the generated migration file readable
+   * and correct for most cases.
+   *
+   * Circular references (A → B → A) are detected. The sort still completes —
+   * cycles are broken arbitrarily and a warning is emitted. The two-pass
+   * FK creation in Operations.CreateModel.up() handles the actual DB safety.
+   *
+   * @param {Array<object>} createOps  — CreateModel op descriptors
+   * @returns {Array<object>}           — same ops, dependency-first order
+   */
+  _sortCreateModels(createOps) {
+    if (createOps.length <= 1) return createOps;
+
+    // Build a set of tables being created in this batch
+    const newTables = new Set(createOps.map(op => op.table));
+
+    // Build adjacency: table → Set of tables it depends on (via FK).
+    // Only track deps within this batch — cross-migration deps are handled
+    // by migration-level dependencies[], not op ordering.
+    const deps = new Map();
+    for (const op of createOps) {
+      const opDeps = new Set();
+      for (const def of Object.values(op.fields)) {
+        const ref = def.references;
+        if (ref && ref.table && newTables.has(ref.table) && ref.table !== op.table) {
+          opDeps.add(ref.table);
+        }
+      }
+      deps.set(op.table, opDeps);
+    }
+
+    // Kahn's algorithm — processes cycles gracefully without recursion
+    // in-degree here means: how many tables in this batch must be created
+    // BEFORE this table (i.e. how many tables does this table depend on).
+    const inDegree = new Map();
+    for (const op of createOps) inDegree.set(op.table, 0);
+    for (const [table, tableDeps] of deps) {
+      // table depends on each dep → table's in-degree increases by 1 per dep
+      inDegree.set(table, (inDegree.get(table) || 0) + tableDeps.size);
+    }
+
+    // Tables with no in-edges (nothing depends on them yet) go first
+    const queue = createOps
+      .filter(op => inDegree.get(op.table) === 0)
+      .map(op => op.table)
+      .sort(); // sort for determinism
+
+    const tableIndex = new Map(createOps.map(op => [op.table, op]));
+    const sorted     = [];
+    const remaining  = new Set(createOps.map(op => op.table));
+
+    while (queue.length > 0) {
+      queue.sort(); // deterministic pick among ready nodes
+      const table = queue.shift();
+      remaining.delete(table);
+      sorted.push(tableIndex.get(table));
+
+      // Reduce in-degree for every table that depended on the one we just placed
+      for (const [candidate, candidateDeps] of deps) {
+        if (candidateDeps.has(table)) {
+          const newDeg = (inDegree.get(candidate) || 0) - 1;
+          inDegree.set(candidate, newDeg);
+          if (newDeg === 0 && remaining.has(candidate)) queue.push(candidate);
+        }
+      }
+    }
+
+    // Any remaining nodes are part of a cycle — append with a warning.
+    // Operations.CreateModel.up() handles them safely via deferred FK constraints.
+    if (remaining.size > 0) {
+      const cycleList = [...remaining].sort().join(', ');
+      process.stderr.write(
+        `[millas] Warning: circular FK reference detected between tables: ${cycleList}.\n` +
+        `  Tables will still be created safely (FK constraints applied after all tables exist),\n` +
+        `  but you should review the relationship design.\n`
+      );
+      for (const table of [...remaining].sort()) {
+        sorted.push(tableIndex.get(table));
+      }
+    }
+
+    return sorted;
+  }
+
+  _fieldsEqual(a, b) { return fieldsEqual(a, b); }
+}
+
+module.exports = MigrationWriter;