@alexify/migronaut 1.0.0

package/src/core/audit.js

@@ -0,0 +1,152 @@
+const { errorText } = require('../utils/error.js');
+const { toLockInfo } = require('./lock.js');
+
+/** Changelog indexes ensureIndexes() creates — audit warns when any is absent */
+const EXPECTED_INDEXES = [
+  'name_unique',
+  'status_batch',
+  'batch',
+  'status_name',
+  'status_appliedAt_name',
+];
+
+/**
+ * Read-only health check of the setup: configuration, connectivity,
+ * transaction support, indexes, lock state and checksum drift.
+ *
+ * Fixes nothing — it reports, so an operator can see in one command why a
+ * migration would fail before running one. Every check is independent: a
+ * failure in one is recorded and the rest still run.
+ *
+ * Pure orchestration over capabilities the MigratorKit injects (`deps`), so it
+ * needs none of the kit's private state.
+ */
+async function runAudit(deps) {
+  const checks = [];
+  const record = (name, status, detail) => checks.push({ name, status, detail });
+
+  // 1. Configuration. Everything downstream depends on it, so a failure here
+  //    is fatal to the audit itself.
+  let config;
+  try {
+    config = await deps.ensureConfig();
+    record('config', 'pass', `Loaded (database "${config.dbName}")`);
+  } catch (error) {
+    record('config', 'fail', errorText(error));
+    return auditReport(checks);
+  }
+
+  // 2. Connectivity.
+  try {
+    await deps.connect();
+    record('connection', 'pass', config.client ? 'Using the injected client' : 'Connected');
+  } catch (error) {
+    record('connection', 'fail', errorText(error));
+    return auditReport(checks);
+  }
+
+  const db = deps.getDb();
+
+  // 3. Transactions need a replica set or a sharded cluster; on a standalone
+  //    server `useTransaction: true` fails at run time with a driver error
+  //    that says nothing about the configuration.
+  try {
+    const info = await db.admin().command({ hello: 1 });
+    const supportsTransactions = Boolean(info.setName) || info.msg === 'isdbgrid';
+    if (supportsTransactions) {
+      record('transactions', 'pass', info.setName ? `Replica set "${info.setName}"` : 'Sharded');
+    } else if (config.useTransaction) {
+      record('transactions', 'fail', 'useTransaction is on, but this is a standalone server');
+    } else {
+      record('transactions', 'warn', 'Standalone server — useTransaction is unavailable');
+    }
+  } catch (error) {
+    record('transactions', 'warn', `Could not determine topology: ${errorText(error)}`);
+  }
+
+  // 4. Indexes. Missing ones do not break correctness, only performance.
+  try {
+    const present = new Set();
+    for (const index of await db.collection(config.migrationsCollection).indexes()) {
+      present.add(index.name);
+    }
+    const missing = [];
+    for (const name of EXPECTED_INDEXES) {
+      if (!present.has(name)) missing.push(name);
+    }
+    if (missing.length === 0) record('indexes', 'pass', 'All changelog indexes present');
+    else record('indexes', 'warn', `Missing: ${missing.join(', ')}`);
+  } catch (error) {
+    record('indexes', 'warn', `Could not read indexes: ${errorText(error)}`);
+  }
+
+  // 5. Lock. A held lock is not itself a problem — a stale one is.
+  try {
+    const holder = toLockInfo(await deps.inspectLock());
+    if (!holder) {
+      record('lock', 'pass', 'No lock held');
+    } else {
+      const ageSeconds = Math.round((Date.now() - holder.lockedAt.getTime()) / 1000);
+      const stale = ageSeconds > config.lockTTLSeconds;
+      record(
+        'lock',
+        stale ? 'warn' : 'pass',
+        `Held by pid ${holder.pid} on ${holder.host} for ${ageSeconds}s` +
+          (stale ? ' — past its TTL, likely from a crashed run (migronaut unlock)' : ''),
+      );
+    }
+  } catch (error) {
+    record('lock', 'warn', `Could not read the lock: ${errorText(error)}`);
+  }
+
+  // 6. Checksum drift and missing files, from the same rows `status` renders.
+  try {
+    const rows = await deps.status();
+    // One pass over the rows collects both signals.
+    const drifted = [];
+    let pending = 0;
+    for (const row of rows) {
+      if (row.checksumOk === false) drifted.push(row.file);
+      if (row.status === 'pending') pending += 1;
+    }
+    if (drifted.length > 0) {
+      record('checksums', 'fail', `Edited after being applied: ${drifted.join(', ')}`);
+    } else {
+      record('checksums', 'pass', 'No drift among applied migrations');
+    }
+    record('pending', pending === 0 ? 'pass' : 'warn', `${pending} pending migration(s)`);
+  } catch (error) {
+    record('checksums', 'warn', `Could not read status: ${errorText(error)}`);
+  }
+
+  // 7. Runtime. TypeScript migrations need a runtime that can strip types.
+  // Feature detection instead of version parsing: it also catches a run
+  // under `--no-experimental-strip-types` on an otherwise capable Node.
+  const nodeVersion = process.versions.node;
+  const wantsTs = (config.fileExtensions ?? []).includes('.ts');
+  const stripsTypes = Boolean(process.features.typescript);
+  if (wantsTs && !stripsTypes) {
+    record(
+      'runtime',
+      'warn',
+      `Node ${nodeVersion} cannot import .ts here — type stripping is unavailable or disabled; re-enable it or use a loader such as tsx`,
+    );
+  } else {
+    record('runtime', 'pass', `Node ${nodeVersion}`);
+  }
+
+  return auditReport(checks);
+}
+
+/** Roll individual checks up into the report shape (one pass, both counters) */
+function auditReport(checks) {
+  let failed = 0;
+  let warnings = 0;
+  for (const check of checks) {
+    if (check.status === 'fail') failed += 1;
+    else if (check.status === 'warn') warnings += 1;
+  }
+  return { ok: failed === 0, failed, warnings, checks };
+}
+
+module.exports = { runAudit };

package/src/core/changelog.js

@@ -0,0 +1,231 @@
+/**
+ * Reads and writes migration records in the changelog collection
+ * (`_migronaut_migrations` by default).
+ *
+ * Records are an append-mostly audit trail: reverting a migration updates its
+ * status to `'reverted'` and stamps `revertedAt` — it never deletes the record.
+ */
+class Changelog {
+  #collectionName;
+
+  constructor(collectionName) {
+    this.#collectionName = collectionName;
+  }
+
+  #coll(db) {
+    return db.collection(this.#collectionName);
+  }
+
+  /**
+   * Create the indexes the read paths actually use. Safe to call repeatedly.
+   *
+   * Beyond the unique `name` index: `{status, batch}` serves the highest-batch
+   * lookups (which would otherwise be a blocking in-memory sort, capped at
+   * 32 MB), `{batch}` serves rollback by batch, `{status, name}` makes the
+   * hottest query of all — the applied set, sorted by name, read on every
+   * `up`/`status`/health check — a covered, sort-free index scan, and
+   * `{status, appliedAt, name}` does the same for the newest-first ordering
+   * that `redo` and `down --steps` sort by.
+   */
+  async ensureIndexes(db) {
+    await this.#coll(db).createIndexes([
+      { key: { name: 1 }, name: 'name_unique', unique: true },
+      { key: { status: 1, batch: -1 }, name: 'status_batch' },
+      { key: { batch: 1 }, name: 'batch' },
+      { key: { status: 1, name: 1 }, name: 'status_name' },
+      { key: { status: 1, appliedAt: -1, name: -1 }, name: 'status_appliedAt_name' },
+    ]);
+  }
+
+  /**
+   * Read every raw document from a foreign collection (e.g. a migrate-mongo
+   * `changelog`). Returns untyped docs since the source schema differs from
+   * ours — the caller is responsible for validating and mapping them. Projected
+   * down to the fields the import mapping consumes, so adopting a large
+   * changelog does not pull every legacy payload into memory.
+   */
+  async getForeignDocs(db, collectionName) {
+    return db
+      .collection(collectionName)
+      .find()
+      .project({ fileName: 1, fileHash: 1, appliedAt: 1, migrationBlock: 1, _id: 0 })
+      .toArray();
+  }
+
+  /**
+   * Every record's `{name, batch}` only — what `import` needs to number new
+   * batches and detect a non-empty target without loading full documents.
+   */
+  async getNamesAndBatches(db) {
+    return this.#coll(db).find().project({ name: 1, batch: 1, _id: 0 }).toArray();
+  }
+
+  /**
+   * The most recently applied record (by `appliedAt`, name-desc tiebreak), or
+   * null. A server-side top-1 sort+limit — never the whole history in memory.
+   */
+  async getNewestApplied(db) {
+    const docs = await this.#coll(db)
+      .find({ status: 'applied' })
+      .sort({ appliedAt: -1, name: -1 })
+      .limit(1)
+      .toArray();
+    return docs[0] ?? null;
+  }
+
+  /** Return every changelog record, sorted by name ascending */
+  async getAll(db) {
+    return this.#coll(db).find().sort({ name: 1 }).toArray();
+  }
+
+  /** Return the names of all currently-applied migrations */
+  async getAppliedNames(db) {
+    const docs = await this.#coll(db)
+      .find({ status: 'applied' })
+      .sort({ name: 1 })
+      .project({ name: 1, _id: 0 })
+      .toArray();
+    const names = [];
+    for (const doc of docs) names.push(doc.name);
+    return names;
+  }
+
+  /** 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 */
+  async getApplied(db) {
+    return this.#coll(db).find({ status: 'applied' }).sort({ name: 1 }).toArray();
+  }
+
+  /**
+   * The last N applied records, newest first (by `appliedAt`, name-desc
+   * tiebreak) — the server-side counterpart of `down --steps`. A covered
+   * sort+limit on the `status_appliedAt_name` index: never the whole applied
+   * history transferred and re-sorted client-side just to slice N.
+   */
+  async getLastAppliedN(db, n) {
+    return this.#coll(db)
+      .find({ status: 'applied' })
+      .sort({ appliedAt: -1, name: -1 })
+      .limit(n)
+      .toArray();
+  }
+
+  /**
+   * Applied records named strictly after `name`, ascending — what `down --to`
+   * reverts. The predicate is pushed down onto the `status_name` index instead
+   * of filtering the full applied history in JS.
+   */
+  async getAppliedAfter(db, name) {
+    return this.#coll(db)
+      .find({ status: 'applied', name: { $gt: name } })
+      .sort({ name: 1 })
+      .toArray();
+  }
+
+  /** Return the highest batch number among currently-applied migrations, or null */
+  async getLastBatch(db) {
+    const docs = await this.#coll(db)
+      .find({ status: 'applied' })
+      .sort({ batch: -1 })
+      .limit(1)
+      .project({ batch: 1, _id: 0 })
+      .toArray();
+    return docs[0]?.batch ?? null;
+  }
+
+  /**
+   * Highest batch number ever used, including reverted records — the basis for
+   * the next batch, so numbers stay monotonic across rollbacks. An indexed
+   * sort+limit, not a full scan.
+   */
+  async getMaxBatch(db) {
+    const docs = await this.#coll(db)
+      .find({})
+      .sort({ batch: -1 })
+      .limit(1)
+      .project({ batch: 1, _id: 0 })
+      .toArray();
+    return docs[0]?.batch ?? 0;
+  }
+
+  /** Return all records belonging to a given batch */
+  async getByBatch(db, batch) {
+    return this.#coll(db).find({ batch }).sort({ name: 1 }).toArray();
+  }
+
+  /**
+   * 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.
+   *
+   * 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 } : {}) },
+    );
+  }
+
+  /**
+   * Bulk counterpart of {@link markApplied}: one unordered bulkWrite instead of
+   * one round trip per record. Identical upsert-on-name semantics; the
+   * operations are independent (unique `name` keys), so unordered is safe and
+   * lets the server parallelize. Used by `import`, whose record count is set by
+   * whatever legacy changelog is being adopted.
+   */
+  async markAppliedBulk(db, records) {
+    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: '' },
+          },
+          upsert: true,
+        },
+      };
+    }
+    await this.#coll(db).bulkWrite(ops, { ordered: false });
+  }
+
+  /**
+   * Mark a migration as reverted. Sets `status='reverted'` and `revertedAt=now`.
+   * Never deletes the record — preserves the full audit history.
+   *
+   * Pass `session` to commit this together with the migration's `down()`.
+   *
+   * Returns the driver's update result: `matchedCount === 0` means the record
+   * 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) {
+    return this.#coll(db).updateOne(
+      { name, status: 'applied' },
+      { $set: { status: 'reverted', revertedAt: new Date() } },
+      session ? { session } : {},
+    );
+  }
+}
+
+module.exports = { Changelog };