@alexify/migronaut 1.0.0 → 2.1.0

package/src/cli/table.js

@@ -247,6 +247,109 @@ function renderImportTable(rows) {
   return renderTable(head, cells);
 }
 
+/** Longest index or collection name rendered before it is ellipsized */
+const MAX_NAME_WIDTH = 48;
+
+/** Longest converge detail rendered before it is ellipsized */
+const MAX_DETAIL_WIDTH = 72;
+
+/** Render a converge action cell: what changes stands out, what does not recedes */
+function convergeActionCell(colors, action) {
+  switch (action) {
+    case 'create':
+      return colors.green(action);
+    case 'modify':
+      return colors.cyan(action);
+    case 'recreate':
+    case 'drop':
+      return colors.yellow(action);
+    case 'conflict':
+      return colors.red(action);
+    default:
+      return colors.dim(action);
+  }
+}
+
+/** The detail column: what differs, or why the row is what it is */
+function convergeDetail(action) {
+  if (action.reason === 'name' && action.liveName !== undefined) {
+    return `renamed from "${action.liveName}"`;
+  }
+  return action.reason ?? '';
+}
+
+/**
+ * Render a converge plan (or result) as a table plus a one-line summary.
+ * Rows that need nothing are folded into the summary unless `all` — a large
+ * schema would otherwise bury its two changes under fifty "unchanged" lines.
+ */
+function renderConvergeTable(result, { all = false } = {}) {
+  const colors = palette();
+  const cells = [];
+  const counts = { change: 0, destructive: 0, conflict: 0, keep: 0, unchanged: 0, touched: 0 };
+  for (const collection of result.collections) {
+    let changes = 0;
+    for (const action of collection.actions) {
+      if (action.action === 'unchanged') counts.unchanged += 1;
+      else if (action.action === 'keep') counts.keep += 1;
+      else if (action.action === 'conflict') counts.conflict += 1;
+      else changes += 1;
+      if (action.target === 'index' && (action.action === 'drop' || action.action === 'recreate')) {
+        counts.destructive += 1;
+      }
+      if (action.action === 'unchanged' && !all) continue;
+      cells.push([
+        truncate(sanitize(collection.name), MAX_NAME_WIDTH),
+        action.target,
+        action.target === 'index' ? truncate(sanitize(action.name), MAX_NAME_WIDTH) : '',
+        convergeActionCell(colors, action.action),
+        truncate(sanitize(convergeDetail(action)), MAX_DETAIL_WIDTH),
+      ]);
+    }
+    counts.change += changes;
+    if (changes > 0) counts.touched += 1;
+  }
+  const collections = result.collections.length;
+  let summary;
+  if (counts.change === 0 && counts.conflict === 0) {
+    summary = `✔ ${collections} collection(s) match their declarations`;
+  } else {
+    const verb = result.dryRun ? 'Would make' : 'Made';
+    summary =
+      `${verb} ${counts.change} change(s) in ${counts.touched} of ${collections} ` +
+      'collection(s)';
+  }
+  const parts = [summary];
+  if (counts.destructive > 0) parts.push(`${counts.destructive} drop/rebuild`);
+  if (counts.conflict > 0) parts.push(colors.red(`${counts.conflict} conflict(s)`));
+  if (counts.keep > 0) parts.push(`${counts.keep} undeclared index(es) kept`);
+  if (counts.unchanged > 0 && !all) parts.push(`${counts.unchanged} unchanged`);
+  const line = parts.join(' · ');
+  if (cells.length === 0) return line;
+  return `${renderTable(['Collection', 'Target', 'Index', 'Action', 'Detail'], cells)}\n${line}`;
+}
+
+/**
+ * Render the converge history: one line per converge that changed something
+ * or failed, newest first — the audit view (`migronaut converge --history`).
+ */
+function renderConvergeHistory(entries) {
+  if (entries.length === 0) return 'No converge has changed anything yet';
+  const colors = palette();
+  const cells = entries.map((entry) => [
+    entry.startedAt instanceof Date ? entry.startedAt.toISOString() : String(entry.startedAt),
+    entry.trigger,
+    entry.success ? colors.green('ok') : colors.red('failed'),
+    String(entry.changed),
+    truncate(sanitize(entry.requestedBy ?? entry.executedBy ?? ''), MAX_NAME_WIDTH),
+    truncate(
+      sanitize(entry.reason ?? (entry.success ? '' : (entry.error ?? ''))),
+      MAX_DETAIL_WIDTH,
+    ),
+  ]);
+  return renderTable(['When', 'Trigger', 'Result', 'Changes', 'Who', 'Why'], cells);
+}
+
 module.exports = {
   charWidth,
   sanitize,
@@ -256,4 +359,6 @@ module.exports = {
   renderStatusTable,
   renderImportTable,
   renderRowsOrEmpty,
+  renderConvergeTable,
+  renderConvergeHistory,
 };

package/src/core/audit.js

@@ -99,15 +99,20 @@ async function runAudit(deps) {
     record('lock', 'warn', `Could not read the lock: ${errorText(error)}`);
   }
 
-  // 6. Checksum drift and missing files, from the same rows `status` renders.
+  // 6. Checksum drift, missing files, pending count and ordering, from the
+  //    same rows `status` renders.
   try {
     const rows = await deps.status();
-    // One pass over the rows collects both signals.
+    // One pass over the rows collects every signal.
     const drifted = [];
+    const outOfOrder = [];
     let pending = 0;
     for (const row of rows) {
       if (row.checksumOk === false) drifted.push(row.file);
-      if (row.status === 'pending') pending += 1;
+      // A recorded failed attempt still counts as pending work — the file
+      // will be retried by the next `up`.
+      if (row.status === 'pending' || row.status === 'failed') pending += 1;
+      if (row.outOfOrder) outOfOrder.push(row.file);
     }
     if (drifted.length > 0) {
       record('checksums', 'fail', `Edited after being applied: ${drifted.join(', ')}`);
@@ -115,6 +120,15 @@ async function runAudit(deps) {
       record('checksums', 'pass', 'No drift among applied migrations');
     }
     record('pending', pending === 0 ? 'pass' : 'warn', `${pending} pending migration(s)`);
+    if (outOfOrder.length > 0) {
+      record(
+        'ordering',
+        'warn',
+        `Pending but older than the newest applied migration: ${outOfOrder.join(', ')}`,
+      );
+    } else {
+      record('ordering', 'pass', 'No out-of-order pending migrations');
+    }
   } catch (error) {
     record('checksums', 'warn', `Could not read status: ${errorText(error)}`);
   }

package/src/core/baseline.js

@@ -0,0 +1,80 @@
+const { computeChecksum } = require('../utils/checksum.js');
+const { mapLimit } = require('../utils/concurrency.js');
+
+/** Simultaneous file hashes — same EMFILE bound as every other multi-file path */
+const FS_CONCURRENCY = 16;
+
+/**
+ * Adopt an existing database with no prior migration tool: mark migration
+ * files on disk as applied — checksums taken from disk, one shared batch,
+ * `origin: 'baseline'` — without executing anything. The database is assumed
+ * to already be in the state those files describe (they were applied by hand,
+ * by a home-grown script, or reconstructed after the fact).
+ *
+ * Forward-only: baselined records were never executed by migronaut, so
+ * `down`/`redo` refuse them (the same `origin` preflight import uses).
+ * Idempotent: already-applied names are skipped, so a partial baseline can
+ * simply be re-run.
+ *
+ * Pure orchestration over capabilities the MigratorKit injects (`deps`):
+ * `{db, changelog, logger, fields, filepath, listMigrationFiles, nextBatch,
+ * truncateAtTarget, environment, executedBy, runId, assertNotAborted}`.
+ */
+async function runBaseline(deps, options, signal) {
+  const { db, changelog, logger } = deps;
+
+  const files = await deps.listMigrationFiles();
+  const applied = new Set(await changelog.getAppliedNames(db));
+  let targets = [];
+  for (const file of files) {
+    if (!applied.has(file)) targets.push(file);
+  }
+  if (options.to !== undefined) {
+    targets = deps.truncateAtTarget(targets, files, options.to);
+  }
+  const skipped = files.length - targets.length;
+
+  if (targets.length === 0) {
+    logger.info('Nothing to baseline', deps.fields({ skipped }));
+    return { baselined: [], skipped, batch: null };
+  }
+
+  // Checksums come from the files as they are NOW — that is the contract: the
+  // baseline asserts "the database already matches these exact files", and
+  // later drift checks police edits against this snapshot.
+  const checksums = await mapLimit(targets, FS_CONCURRENCY, (name) =>
+    computeChecksum(deps.filepath(name)),
+  );
+
+  const batch = await deps.nextBatch();
+  const records = new Array(targets.length);
+  for (let i = 0; i < targets.length; i++) {
+    records[i] = {
+      name: targets[i],
+      batch,
+      status: 'applied',
+      // No appliedAt: the changelog stamps it in server time.
+      duration: 0,
+      checksum: checksums[i],
+      environment: deps.environment(),
+      executedBy: deps.executedBy(),
+      origin: 'baseline',
+      ...(deps.runId() ? { runId: deps.runId() } : {}),
+    };
+  }
+
+  // One write, checked against the abort signal first: a baseline is all
+  // bookkeeping, so there is no safe partial point worth resuming from — and
+  // markAppliedBulk's upsert-by-name makes a re-run after any failure
+  // idempotent anyway.
+  deps.assertNotAborted(signal);
+  await changelog.markAppliedBulk(db, records);
+
+  logger.info(
+    `✔ Baselined ${records.length} migration(s) as applied (batch ${batch})`,
+    deps.fields({ baselined: records.length, skipped, batch }),
+  );
+  return { baselined: targets, skipped, batch };
+}
+
+module.exports = { runBaseline };

package/src/core/changelog.js

@@ -1,3 +1,5 @@
+const { actorFields } = require('../utils/actor.js');
+
 /**
  * Reads and writes migration records in the changelog collection
  * (`_migronaut_migrations` by default).
@@ -90,14 +92,40 @@ class Changelog {
     return names;
   }
 
+  /**
+   * Which of `names` carry a `'failed'` trace — what tells a migration that
+   * failed (the line is stopped) from one that simply has not run yet (it may
+   * be in flight elsewhere). Served by the `status_name` index.
+   */
+  async getFailedNames(db, names) {
+    if (names.length === 0) return [];
+    const docs = await this.#coll(db)
+      .find({ status: 'failed', name: { $in: names } })
+      .sort({ name: 1 })
+      .project({ name: 1, _id: 0 })
+      .toArray();
+    const failed = [];
+    for (const doc of docs) failed.push(doc.name);
+    return failed;
+  }
+
   /** Return a single record by migration name, or null */
   async getByName(db, name) {
     return this.#coll(db).findOne({ name });
   }
 
-  /** Return every currently-applied record, sorted by name ascending */
+  /**
+   * Every currently-applied record's `{name, checksum}`, sorted by name
+   * ascending — exactly what the strict bulk drift check consumes (the name
+   * doubles as the applied-set key). Projected like the module's other reads;
+   * widen the projection if a new caller needs more.
+   */
   async getApplied(db) {
-    return this.#coll(db).find({ status: 'applied' }).sort({ name: 1 }).toArray();
+    return this.#coll(db)
+      .find({ status: 'applied' })
+      .sort({ name: 1 })
+      .project({ _id: 0, name: 1, checksum: 1 })
+      .toArray();
   }
 
   /**
@@ -126,6 +154,29 @@ class Changelog {
       .toArray();
   }
 
+  /**
+   * Applied records that were applied *after* `record`, newest first — the
+   * revert order `down --steps` uses (`appliedAt`, name-desc tiebreak). An
+   * `ordered` rollback refuses while any exist: undoing effects is only safe in
+   * reverse of the order they were made. A record with no `appliedAt` (a
+   * hand-edited or legacy document) treats every other applied record as
+   * newer — the conservative answer.
+   */
+  async getAppliedNewerThan(db, { appliedAt, name }) {
+    const filter =
+      appliedAt instanceof Date
+        ? {
+            status: 'applied',
+            $or: [{ appliedAt: { $gt: appliedAt } }, { appliedAt, name: { $gt: name } }],
+          }
+        : { status: 'applied', name: { $ne: name } };
+    return this.#coll(db)
+      .find(filter)
+      .sort({ appliedAt: -1, name: -1 })
+      .project({ _id: 0, name: 1, appliedAt: 1, batch: 1 })
+      .toArray();
+  }
+
   /** Return the highest batch number among currently-applied migrations, or null */
   async getLastBatch(db) {
     const docs = await this.#coll(db)
@@ -157,29 +208,66 @@ class Changelog {
     return this.#coll(db).find({ batch }).sort({ name: 1 }).toArray();
   }
 
+  /**
+   * The update document shared by markApplied and markAppliedBulk.
+   *
+   * `appliedAt` is stamped in **server time** (`$currentDate`) when the record
+   * does not carry one — the same clock discipline the lock's `$$NOW` uses:
+   * `redo` and `down --steps` sort by `appliedAt`, and a client-stamped value
+   * lets a skewed host mis-order the revert selection. An explicit `appliedAt`
+   * (import adopting a legacy changelog's historical timestamps) is written
+   * verbatim. `firstAppliedAt` is audit-only metadata, never sorted on, so its
+   * client-clock `$setOnInsert` fallback is acceptable ($setOnInsert cannot
+   * express server time).
+   */
+  static #appliedUpdate(record) {
+    // `name` comes from the filter on insert, so it must not also appear in an
+    // update operator (MongoDB rejects the conflicting path).
+    const { name, appliedAt, ...fields } = record;
+    const update = {
+      $set: fields,
+      // A re-apply clears the stale revert marker (and who asked for the
+      // revert, and why) — and the failure trace a markFailed() from an earlier
+      // crashed attempt may have left.
+      $unset: {
+        revertedAt: '',
+        revertRequestedBy: '',
+        revertReason: '',
+        failedAt: '',
+        error: '',
+      },
+    };
+    // Who asked for this apply, and why — or nobody said: then the previous
+    // apply's answer must not linger as if it were this one's.
+    for (const key of ['requestedBy', 'reason']) {
+      if (fields[key] === undefined) update.$unset[key] = '';
+    }
+    if (appliedAt !== undefined) {
+      update.$set.appliedAt = appliedAt;
+      update.$setOnInsert = { firstAppliedAt: appliedAt };
+    } else {
+      update.$currentDate = { appliedAt: true };
+      update.$setOnInsert = { firstAppliedAt: new Date() };
+    }
+    return update;
+  }
+
   /**
    * Record a migration as applied. Upserts on `name` so re-applying a
    * previously-reverted migration (e.g. via `redo`) cannot violate the unique
    * index. Uses `$set` rather than a whole-document replace so audit fields
    * survive a re-apply: `firstAppliedAt` is stamped once, and the stale
-   * `revertedAt` from an earlier rollback is cleared.
+   * `revertedAt` from an earlier rollback is cleared. `appliedAt` is stamped
+   * server-side unless the record carries one — see {@link #appliedUpdate}.
    *
    * Pass `session` to make this write part of the migration's transaction, so
    * the migration and its changelog record commit together.
    */
   async markApplied(db, record, session) {
-    // `name` comes from the filter on insert, so it must not also appear in an
-    // update operator (MongoDB rejects the conflicting path).
-    const { name, ...fields } = record;
-    await this.#coll(db).updateOne(
-      { name },
-      {
-        $set: fields,
-        $setOnInsert: { firstAppliedAt: record.appliedAt },
-        $unset: { revertedAt: '' },
-      },
-      { upsert: true, ...(session ? { session } : {}) },
-    );
+    await this.#coll(db).updateOne({ name: record.name }, Changelog.#appliedUpdate(record), {
+      upsert: true,
+      ...(session ? { session } : {}),
+    });
   }
 
   /**
@@ -193,15 +281,10 @@ class Changelog {
     if (records.length === 0) return;
     const ops = new Array(records.length);
     for (let i = 0; i < records.length; i++) {
-      const { name, ...fields } = records[i];
       ops[i] = {
         updateOne: {
-          filter: { name },
-          update: {
-            $set: fields,
-            $setOnInsert: { firstAppliedAt: records[i].appliedAt },
-            $unset: { revertedAt: '' },
-          },
+          filter: { name: records[i].name },
+          update: Changelog.#appliedUpdate(records[i]),
           upsert: true,
         },
       };
@@ -219,13 +302,46 @@ class Changelog {
    * was no longer `'applied'` (a concurrent peer got there first) — the caller
    * decides what to do with that, since this module stays logger-free.
    */
-  async markReverted(db, name, session) {
+  async markReverted(db, name, session, actor = {}) {
+    const update = {
+      $set: {
+        status: 'reverted',
+        ...actorFields(actor, 'revert'),
+      },
+      // Server time, like markApplied's appliedAt — one clock for the whole trail.
+      $currentDate: { revertedAt: true },
+    };
+    const unset = {};
+    if (actor.requestedBy === undefined) unset.revertRequestedBy = '';
+    if (actor.reason === undefined) unset.revertReason = '';
+    if (Object.keys(unset).length > 0) update.$unset = unset;
     return this.#coll(db).updateOne(
       { name, status: 'applied' },
-      { $set: { status: 'reverted', revertedAt: new Date() } },
+      update,
       session ? { session } : {},
     );
   }
+
+  /**
+   * Best-effort trace of a failed `up` attempt, so a crash-and-restart leaves
+   * DB-side evidence of what was in flight ("did the crashed run start X?")
+   * instead of depending on process logs that may not have been captured.
+   *
+   * The filter excludes `'applied'` records: a forced re-run's failure must
+   * never demote a migration the changelog says is applied — the upsert then
+   * collides on the unique `name` index, and the caller swallows that. Every
+   * read path filters on `status: 'applied'`, so a `'failed'` record never
+   * changes what runs; the next successful apply overwrites it (and clears
+   * `failedAt`/`error`).
+   */
+  async markFailed(db, record) {
+    const { name, ...fields } = record;
+    await this.#coll(db).updateOne(
+      { name, status: { $ne: 'applied' } },
+      { $set: { ...fields, status: 'failed' }, $currentDate: { failedAt: true } },
+      { upsert: true },
+    );
+  }
 }
 
 module.exports = { Changelog };