@stacksjs/database 0.70.251 → 0.70.253

package/dist/index.d.ts

@@ -107,6 +107,10 @@ export * from './defaults';
 // Dialect classification for the committed migration corpus, so a corpus
 // emitted for one database fails loudly before a single statement runs.
 export * from './migration-dialect';
+// Ledger drift audit (stacksjs/stacks#2203) — compare the corpus on disk, the
+// `migrations` table, and the live schema, because regeneration renumbers files
+// and the ledger keys on the filename.
+export * from './migration-ledger';
 // Model resolution for the generator: userland + framework defaults, flattened
 // because bun-query-builder's loadModels reads only the top level of a dir.
 export * from './model-sources';

package/dist/index.js

@@ -30,6 +30,7 @@ export { migrateRbacTables } from "./rbac-tables";
 export * from "./sql-helpers";
 export * from "./defaults";
 export * from "./migration-dialect";
+export * from "./migration-ledger";
 export * from "./model-sources";
 export * from "./ensure-database";
 export { auditForeignKeys, findFkOrphans, getDeclaredFKs, getLiveFKs } from "./fk-audit";

package/dist/migration-ledger.d.ts

@@ -0,0 +1,189 @@
+import process from 'node:process';
+/**
+ * Strip a migration's SQL down to something safe to pattern-match.
+ *
+ * Blanks comments and single-quoted string literals while PRESERVING
+ * double-quoted identifiers, which is the opposite of what
+ * {@link stripSqlNoise} in `migration-dialect.ts` wants — that one is matching
+ * dialect markers and has no use for names, whereas every effect here IS a
+ * name. Blanking the literals still matters: without it a data migration whose
+ * payload happens to contain `CREATE TABLE "x"` would register as creating a
+ * table, and then be silently recorded as applied.
+ *
+ * Blanking preserves offsets and line count, so nothing downstream has to care.
+ */
+export declare function stripForEffects(sql: string): string;
+/**
+ * The migration's identity, independent of where it sits in the sequence.
+ *
+ * This is the whole basis for reconciliation: `0000000003-create-issues-table`
+ * and `0000000002-create-issues-table` are the same migration, and the ledger
+ * only failed to see that because it stored the ordinal.
+ */
+export declare function logicalName(file: string): string;
+/** Schema changes a migration file makes that the live database can confirm. */
+export declare function migrationEffects(sql: string): MigrationEffect[];
+/**
+ * Effects this dialect can actually confirm.
+ *
+ * SQLite has no named constraints reachable by introspection (foreign keys are
+ * inline on CREATE TABLE) and no user-defined types, and the runner
+ * deliberately records ADD CONSTRAINT / CREATE TYPE files as executed WITHOUT
+ * running them so a later `DB_CONNECTION` flip can replay the file
+ * (stacksjs/stacks#1916). Checking for those effects on SQLite would therefore
+ * report every such file as `reverted`, which is both wrong and loud. MySQL has
+ * no standalone enum type either.
+ */
+export declare function verifiableEffects(effects: MigrationEffect[], dialect: LedgerDialect): MigrationEffect[];
+/** Read the parts of the live schema an effect can be checked against. */
+export declare function readLiveSchema(dialect: LedgerDialect, runner?: SqlRunner): Promise<LiveSchema>;
+/** Whether a single effect can be found in the live schema. */
+export declare function effectPresent(effect: MigrationEffect, schema: LiveSchema): boolean;
+/**
+ * Decide what a single migration file's state actually is.
+ *
+ * Pure, so the interesting cases are testable without a database. The order
+ * matters: "no verifiable effects" has to be answered before "all present",
+ * because vacuously-all-present is exactly the wrong answer for a data
+ * migration — it is how a `DELETE FROM oauth_access_tokens` gets recorded as
+ * applied on the strength of having nothing to check.
+ */
+export declare function classifyMigration(recorded: boolean, present: MigrationEffect[], absent: MigrationEffect[]): MigrationStatus;
+/**
+ * Every filename the `migrations` table has recorded.
+ *
+ * An absent table is a legitimate state (nothing has ever migrated), so it
+ * reads as an empty ledger rather than an error.
+ */
+export declare function readLedger(runner?: SqlRunner): Promise<string[]>;
+/**
+ * Match ledger rows to disk files by logical name, so a renumbered corpus can
+ * have its bookkeeping rewritten instead of being re-run.
+ *
+ * Pure — takes the two lists and returns a plan. Refuses anything it cannot
+ * prove: a logical name appearing on more than one disk file, or two ledger
+ * rows converging on one file, are both reported as ambiguous rather than
+ * guessed at. A wrong remap silently un-applies a migration, which is the very
+ * failure this exists to fix.
+ */
+export declare function planLedgerRemap(ledger: string[], diskFiles: string[]): LedgerRemapPlan;
+/**
+ * Compare the migration corpus, the ledger, and the live schema.
+ *
+ * Read-only. Nothing here writes, so it is safe to run on production and safe
+ * to wire into `buddy doctor`.
+ */
+export declare function auditMigrationLedger(options?: {
+  dir?: string
+  /** Audit a specific dialect instead of the configured one. */
+  dialect?: LedgerDialect
+  /** Audit a database other than the process-wide one. */
+  run?: SqlRunner
+}): Promise<MigrationLedgerAudit>;
+/**
+ * Bring the ledger back in line with what the schema proves.
+ *
+ * Two operations, both conservative:
+ *
+ *   1. **Remap** a ledger row onto its renumbered file. Nothing runs; only the
+ *      recorded name changes. This is the direct undo of #2203.
+ *   2. **Record** a `stranded` file — one whose every effect is already in the
+ *      schema — so the runner stops treating it as pending.
+ *
+ * Everything else is refused and reported. `partial` files have half-applied
+ * effects and no safe automatic answer; `unverifiable` ones (pure DML, like the
+ * `DELETE FROM oauth_access_tokens` token revocation in the shipped corpus)
+ * leave no trace to check, and recording one on a hunch would skip a migration
+ * that never ran. Those are exactly the cases worth a human's attention, which
+ * is why they are listed rather than silently handled.
+ */
+export declare function reconcileMigrationLedger(options?: {
+  dir?: string
+  /** Report what would change without writing. */
+  dryRun?: boolean
+  /** Also record `partial` files. Off by default, and rarely right. */
+  includePartial?: boolean
+  /** Reconcile a specific dialect instead of the configured one. */
+  dialect?: LedgerDialect
+  /** Reconcile a database other than the process-wide one. */
+  run?: SqlRunner
+}): Promise<ReconcileResult>;
+/**
+ * A schema change a migration makes that can be confirmed by looking at the
+ * live database. Deliberately narrow: only effects whose presence is
+ * unambiguous. An `ALTER COLUMN ... TYPE`, an `UPDATE`, or a `DELETE` leaves no
+ * such trace, and guessing at those is how you end up recording a data
+ * migration that never ran.
+ */
+export declare interface MigrationEffect {
+  kind: 'table' | 'column' | 'index' | 'constraint' | 'enum'
+  table?: string
+  name: string
+}
+export declare interface MigrationLedgerEntry {
+  file: string
+  logical: string
+  recorded: boolean
+  status: MigrationStatus
+  effects: MigrationEffect[]
+  present: MigrationEffect[]
+  absent: MigrationEffect[]
+}
+export declare interface LedgerOrphan {
+  migration: string
+  renamedTo?: string
+}
+export declare interface MigrationLedgerAudit {
+  supported: boolean
+  dialect: LedgerDialect | 'other'
+  dir: string
+  entries: MigrationLedgerEntry[]
+  orphans: LedgerOrphan[]
+  counts: Record<MigrationStatus, number>
+  recordedCount: number
+  remapPlan: LedgerRemapPlan
+  drift: boolean
+}
+export declare interface LedgerRemap {
+  from: string
+  to: string
+}
+export declare interface LedgerRemapPlan {
+  remap: LedgerRemap[]
+  ambiguous: string[]
+  dropped: string[]
+}
+export declare interface LiveSchema {
+  tables: Set<string>
+  columns: Map<string, Set<string>>
+  indexes: Set<string>
+  constraints: Set<string>
+  enums: Set<string>
+}
+export declare interface ReconcileResult {
+  remapped: LedgerRemap[]
+  recorded: string[]
+  skipped: Array<{ file: string, reason: string }>
+}
+export type LedgerDialect = 'sqlite' | 'mysql' | 'postgres';
+export type MigrationStatus = | 'applied'
+  /** Not recorded, but every effect is already present — a renumber victim. */
+  | 'stranded'
+  /** Not recorded, and no effect is present — genuinely queued to run. */
+  | 'pending'
+  /** Not recorded, and only some effects are present — needs a human. */
+  | 'partial'
+  /** Nothing schema-visible to check (pure DML). Status cannot be inferred. */
+  | 'unverifiable'
+  /** Recorded, but effects are missing — the schema drifted away from history. */
+  | 'reverted';
+/**
+ * Runs one SQL string and returns its rows.
+ *
+ * Injectable for the same reason `ensure-database.ts` takes its own `connect`:
+ * everything here has to be exercisable against a database the caller controls.
+ * The default binds to the process-wide `db`, which is a single shared handle —
+ * fine in production, useless for a test that needs to build a specific
+ * drift state, and unable to audit a database other than the configured one.
+ */
+export type SqlRunner = (sql: string) => Promise<any[]>;

package/dist/migration-ledger.js

@@ -0,0 +1,382 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import process from "node:process";
+import { join } from "node:path";
+const SAFE_MIGRATION_FILE = /^[\w.-]+\.sql$/, IDENT = String.raw`["\`\[]?([A-Za-z_]\w*)["\`\]]?`;
+export function stripForEffects(sql) {
+  let out = "", i = 0;
+  const blank = (text) => text.replace(/[^\n]/g, " ");
+  while (i < sql.length) {
+    const rest = sql.slice(i), line = rest.match(/^--[^\n]*/);
+    if (line) {
+      out += blank(line[0]);
+      i += line[0].length;
+      continue;
+    }
+    if (rest.startsWith("/*")) {
+      const end = rest.indexOf("*/"), chunk = end === -1 ? rest : rest.slice(0, end + 2);
+      out += blank(chunk);
+      i += chunk.length;
+      continue;
+    }
+    if (rest[0] === "'") {
+      let j = 1;
+      while (j < rest.length && rest[j] !== "'")
+        j++;
+      const chunk = rest.slice(0, Math.min(j + 1, rest.length));
+      out += blank(chunk);
+      i += chunk.length;
+      continue;
+    }
+    out += sql[i];
+    i += 1;
+  }
+  return out;
+}
+function statementsOf(sql) {
+  return stripForEffects(sql).split(";").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+export function logicalName(file) {
+  return file.replace(/^\d+[-_]/, "").replace(/\.sql$/i, "");
+}
+export function migrationEffects(sql) {
+  const effects = [], seen = new Set, renamedAway = new Set, push = (effect) => {
+    const key = effectKey(effect);
+    if (seen.has(key))
+      return;
+    seen.add(key);
+    effects.push(effect);
+  };
+  for (const statement of statementsOf(sql)) {
+    const create = new RegExp(String.raw`^CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?${IDENT}`, "i").exec(statement);
+    if (create?.[1]) {
+      push({ kind: "table", name: create[1] });
+      continue;
+    }
+    const rename = new RegExp(String.raw`^ALTER\s+TABLE\s+${IDENT}\s+RENAME\s+TO\s+${IDENT}`, "i").exec(statement);
+    if (rename?.[2]) {
+      if (rename[1])
+        renamedAway.add(rename[1].toLowerCase());
+      push({ kind: "table", name: rename[2] });
+      continue;
+    }
+    const index = new RegExp(String.raw`^CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?${IDENT}`, "i").exec(statement);
+    if (index?.[1]) {
+      push({ kind: "index", name: index[1] });
+      continue;
+    }
+    const enumType = new RegExp(String.raw`^CREATE\s+TYPE\s+${IDENT}\s+AS\s+ENUM`, "i").exec(statement);
+    if (enumType?.[1]) {
+      push({ kind: "enum", name: enumType[1] });
+      continue;
+    }
+    const alter = new RegExp(String.raw`^ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?${IDENT}\s+(.*)$`, "is").exec(statement);
+    if (!alter?.[1] || !alter[2])
+      continue;
+    const table = alter[1], addColumn = new RegExp(String.raw`\bADD\s+COLUMN\s+(?:IF\s+NOT\s+EXISTS\s+)?${IDENT}`, "gi");
+    for (const m of alter[2].matchAll(addColumn))
+      if (m[1])
+        push({ kind: "column", table, name: m[1] });
+    const addConstraint = new RegExp(String.raw`\bADD\s+CONSTRAINT\s+(?:IF\s+NOT\s+EXISTS\s+)?${IDENT}`, "gi");
+    for (const m of alter[2].matchAll(addConstraint))
+      if (m[1])
+        push({ kind: "constraint", table, name: m[1] });
+    const addBare = new RegExp(String.raw`\bADD\s+(?!COLUMN\b|CONSTRAINT\b|INDEX\b|KEY\b|PRIMARY\b|UNIQUE\b|FOREIGN\b|FULLTEXT\b|SPATIAL\b|CHECK\b)${IDENT}\s+\w`, "gi");
+    for (const m of alter[2].matchAll(addBare))
+      if (m[1])
+        push({ kind: "column", table, name: m[1] });
+  }
+  if (renamedAway.size === 0)
+    return effects;
+  return effects.filter((effect) => {
+    const owner = (effect.kind === "table" ? effect.name : effect.table ?? "").toLowerCase();
+    return !renamedAway.has(owner);
+  });
+}
+function effectKey(effect) {
+  return `${effect.kind}:${(effect.table ?? "").toLowerCase()}.${effect.name.toLowerCase()}`;
+}
+export function verifiableEffects(effects, dialect) {
+  if (dialect === "postgres")
+    return effects;
+  if (dialect === "mysql")
+    return effects.filter((e) => e.kind !== "enum");
+  return effects.filter((e) => e.kind !== "constraint" && e.kind !== "enum");
+}
+function emptySchema() {
+  return { tables: new Set, columns: new Map, indexes: new Set, constraints: new Set, enums: new Set };
+}
+function rowsOf(result) {
+  return Array.isArray(result) ? result : [];
+}
+async function defaultRunner() {
+  const { db } = await import("./utils");
+  return async (sql) => rowsOf(await db.unsafe(sql).execute());
+}
+function pick(row, ...keys) {
+  for (const key of keys) {
+    const value = row?.[key] ?? row?.[key.toLowerCase()] ?? row?.[key.toUpperCase()];
+    if (typeof value === "string" && value.length > 0)
+      return value;
+  }
+  return "";
+}
+export async function readLiveSchema(dialect, runner) {
+  const schema = emptySchema(), run = runner ?? await defaultRunner();
+  if (dialect === "sqlite") {
+    for (const row of await run("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")) {
+      const name = pick(row, "name");
+      if (name)
+        schema.tables.add(name.toLowerCase());
+    }
+    for (const row of await run("SELECT name FROM sqlite_master WHERE type='index' AND name NOT LIKE 'sqlite_%'")) {
+      const name = pick(row, "name");
+      if (name)
+        schema.indexes.add(name.toLowerCase());
+    }
+    for (const table of schema.tables) {
+      if (!/^[a-z_]\w*$/i.test(table))
+        continue;
+      const cols = new Set;
+      for (const row of await run(`PRAGMA table_info("${table}")`)) {
+        const name = pick(row, "name");
+        if (name)
+          cols.add(name.toLowerCase());
+      }
+      schema.columns.set(table, cols);
+    }
+    return schema;
+  }
+  if (dialect === "mysql") {
+    for (const row of await run("SELECT TABLE_NAME AS name FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE()")) {
+      const name = pick(row, "name", "TABLE_NAME");
+      if (name)
+        schema.tables.add(name.toLowerCase());
+    }
+    for (const row of await run("SELECT TABLE_NAME, COLUMN_NAME FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE()")) {
+      const table = pick(row, "TABLE_NAME").toLowerCase(), column = pick(row, "COLUMN_NAME").toLowerCase();
+      if (!table || !column)
+        continue;
+      if (!schema.columns.has(table))
+        schema.columns.set(table, new Set);
+      schema.columns.get(table).add(column);
+    }
+    for (const row of await run("SELECT DISTINCT INDEX_NAME AS name FROM information_schema.STATISTICS WHERE TABLE_SCHEMA = DATABASE()")) {
+      const name = pick(row, "name", "INDEX_NAME");
+      if (name)
+        schema.indexes.add(name.toLowerCase());
+    }
+    for (const row of await run("SELECT CONSTRAINT_NAME AS name FROM information_schema.TABLE_CONSTRAINTS WHERE CONSTRAINT_SCHEMA = DATABASE()")) {
+      const name = pick(row, "name", "CONSTRAINT_NAME");
+      if (name)
+        schema.constraints.add(name.toLowerCase());
+    }
+    return schema;
+  }
+  for (const row of await run("SELECT tablename AS name FROM pg_tables WHERE schemaname = 'public'")) {
+    const name = pick(row, "name", "tablename");
+    if (name)
+      schema.tables.add(name.toLowerCase());
+  }
+  for (const row of await run("SELECT table_name, column_name FROM information_schema.columns WHERE table_schema = 'public'")) {
+    const table = pick(row, "table_name").toLowerCase(), column = pick(row, "column_name").toLowerCase();
+    if (!table || !column)
+      continue;
+    if (!schema.columns.has(table))
+      schema.columns.set(table, new Set);
+    schema.columns.get(table).add(column);
+  }
+  for (const row of await run("SELECT indexname AS name FROM pg_indexes WHERE schemaname = 'public'")) {
+    const name = pick(row, "name", "indexname");
+    if (name)
+      schema.indexes.add(name.toLowerCase());
+  }
+  for (const row of await run("SELECT c.conname AS name FROM pg_constraint c JOIN pg_namespace n ON n.oid = c.connamespace WHERE n.nspname = 'public'")) {
+    const name = pick(row, "name", "conname");
+    if (name)
+      schema.constraints.add(name.toLowerCase());
+  }
+  for (const row of await run("SELECT t.typname AS name FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace WHERE t.typtype = 'e' AND n.nspname = 'public'")) {
+    const name = pick(row, "name", "typname");
+    if (name)
+      schema.enums.add(name.toLowerCase());
+  }
+  return schema;
+}
+export function effectPresent(effect, schema) {
+  const name = effect.name.toLowerCase();
+  switch (effect.kind) {
+    case "table":
+      return schema.tables.has(name);
+    case "column":
+      return schema.columns.get((effect.table ?? "").toLowerCase())?.has(name) ?? !1;
+    case "index":
+      return schema.indexes.has(name);
+    case "constraint":
+      return schema.constraints.has(name);
+    case "enum":
+      return schema.enums.has(name);
+  }
+}
+export function classifyMigration(recorded, present, absent) {
+  const verifiable = present.length + absent.length;
+  if (recorded) {
+    if (verifiable === 0 || absent.length === 0)
+      return "applied";
+    return "reverted";
+  }
+  if (verifiable === 0)
+    return "unverifiable";
+  if (absent.length === 0)
+    return "stranded";
+  if (present.length === 0)
+    return "pending";
+  return "partial";
+}
+function migrationsDir(dir) {
+  return dir ?? join(process.cwd(), "database", "migrations");
+}
+function listMigrationFiles(dir) {
+  if (!existsSync(dir))
+    return [];
+  try {
+    return readdirSync(dir).filter((f) => f.toLowerCase().endsWith(".sql")).sort();
+  } catch {
+    return [];
+  }
+}
+async function currentDialect() {
+  const driver = ((await import("@stacksjs/env")).env?.DB_CONNECTION ?? "sqlite").toLowerCase();
+  if (driver === "sqlite" || driver === "mysql" || driver === "postgres")
+    return driver;
+  return "other";
+}
+export async function readLedger(runner) {
+  try {
+    return (await (runner ?? await defaultRunner())("SELECT migration FROM migrations")).map((row) => pick(row, "migration")).filter((name) => name.length > 0).sort();
+  } catch {
+    return [];
+  }
+}
+export function planLedgerRemap(ledger, diskFiles) {
+  const onDisk = new Set(diskFiles), byLogical = new Map;
+  for (const file of diskFiles) {
+    const key = logicalName(file);
+    if (!byLogical.has(key))
+      byLogical.set(key, []);
+    byLogical.get(key).push(file);
+  }
+  const claimed = new Set(ledger.filter((row) => onDisk.has(row))), remap = [], ambiguous = [], dropped = [], targets = new Map;
+  for (const row of ledger) {
+    if (onDisk.has(row))
+      continue;
+    const candidates = (byLogical.get(logicalName(row)) ?? []).filter((f) => !claimed.has(f));
+    if (candidates.length === 0) {
+      dropped.push(row);
+      continue;
+    }
+    if (candidates.length > 1) {
+      ambiguous.push(row);
+      continue;
+    }
+    const to = candidates[0];
+    if (!targets.has(to))
+      targets.set(to, []);
+    targets.get(to).push(row);
+    remap.push({ from: row, to });
+  }
+  const contested = new Set([...targets.entries()].filter(([, rows]) => rows.length > 1).flatMap(([, rows]) => rows));
+  if (contested.size === 0)
+    return { remap, ambiguous, dropped };
+  return {
+    remap: remap.filter((r) => !contested.has(r.from)),
+    ambiguous: [...ambiguous, ...contested].sort(),
+    dropped
+  };
+}
+export async function auditMigrationLedger(options = {}) {
+  const dir = migrationsDir(options.dir), dialect = options.dialect ?? await currentDialect(), files = listMigrationFiles(dir), counts = {
+    applied: 0,
+    stranded: 0,
+    pending: 0,
+    partial: 0,
+    unverifiable: 0,
+    reverted: 0
+  }, emptyPlan = { remap: [], ambiguous: [], dropped: [] };
+  if (dialect === "other")
+    return { supported: !1, dialect, dir, entries: [], orphans: [], counts, recordedCount: 0, remapPlan: emptyPlan, drift: !1 };
+  const run = options.run ?? await defaultRunner(), ledger = await readLedger(run), recorded = new Set(ledger), schema = await readLiveSchema(dialect, run), entries = [];
+  for (const file of files) {
+    let sql = "";
+    try {
+      sql = readFileSync(join(dir, file), "utf8");
+    } catch {
+      continue;
+    }
+    const effects = verifiableEffects(migrationEffects(sql), dialect), present = effects.filter((effect) => effectPresent(effect, schema)), absent = effects.filter((effect) => !effectPresent(effect, schema)), isRecorded = recorded.has(file), status = classifyMigration(isRecorded, present, absent);
+    counts[status] += 1;
+    entries.push({ file, logical: logicalName(file), recorded: isRecorded, status, effects, present, absent });
+  }
+  const readable = entries.map((entry) => entry.file), remapPlan = planLedgerRemap(ledger, readable), renamedTo = new Map(remapPlan.remap.map((r) => [r.from, r.to])), orphans = ledger.filter((row) => !readable.includes(row)).map((row) => ({ migration: row, renamedTo: renamedTo.get(row) })), drift = counts.stranded > 0 || counts.partial > 0 || counts.reverted > 0 || orphans.length > 0;
+  return { supported: !0, dialect, dir, entries, orphans, counts, recordedCount: ledger.length, remapPlan, drift };
+}
+async function ensureLedgerTable(dialect, run) {
+  await run(`CREATE TABLE IF NOT EXISTS migrations (${dialect === "postgres" ? "id SERIAL PRIMARY KEY" : dialect === "mysql" ? "id INT AUTO_INCREMENT PRIMARY KEY" : "id INTEGER PRIMARY KEY AUTOINCREMENT"}, migration VARCHAR(255) NOT NULL UNIQUE, executed_at ${dialect === "postgres" ? "TIMESTAMP" : "DATETIME"} DEFAULT CURRENT_TIMESTAMP)`);
+}
+export async function reconcileMigrationLedger(options = {}) {
+  const run = options.run ?? await defaultRunner(), audit = await auditMigrationLedger({ dir: options.dir, dialect: options.dialect, run }), result = { remapped: [], recorded: [], skipped: [] };
+  if (!audit.supported) {
+    result.skipped.push({ file: "*", reason: `dialect "${audit.dialect}" is not audited` });
+    return result;
+  }
+  const plan = audit.remapPlan;
+  for (const row of plan.ambiguous)
+    result.skipped.push({ file: row, reason: "ledger row matches more than one file by logical name" });
+  for (const row of plan.dropped)
+    result.skipped.push({ file: row, reason: "recorded migration no longer exists on disk" });
+  const toRecord = [];
+  for (const entry of audit.entries) {
+    if (entry.status === "stranded") {
+      toRecord.push(entry.file);
+      continue;
+    }
+    if (entry.status === "partial") {
+      if (options.includePartial) {
+        toRecord.push(entry.file);
+        continue;
+      }
+      result.skipped.push({
+        file: entry.file,
+        reason: `${entry.present.length}/${entry.effects.length} effects present \u2014 resolve by hand, or pass --include-partial`
+      });
+      continue;
+    }
+    if (entry.status === "reverted")
+      result.skipped.push({
+        file: entry.file,
+        reason: `recorded, but ${entry.absent.length} effect(s) are missing from the schema`
+      });
+  }
+  const unsafe = (file) => !SAFE_MIGRATION_FILE.test(file);
+  for (const { from, to } of plan.remap.filter((r) => unsafe(r.from) || unsafe(r.to)))
+    result.skipped.push({ file: unsafe(from) ? from : to, reason: "migration filename is not safe to write to the ledger" });
+  for (const file of toRecord.filter(unsafe))
+    result.skipped.push({ file, reason: "migration filename is not safe to write to the ledger" });
+  const remapped = plan.remap.filter((r) => !unsafe(r.from) && !unsafe(r.to)), recordable = toRecord.filter((file) => !unsafe(file) && !remapped.some((r) => r.to === file));
+  if (options.dryRun) {
+    result.remapped = remapped;
+    result.recorded = recordable;
+    return result;
+  }
+  await ensureLedgerTable(audit.dialect, run);
+  for (const { from, to } of remapped) {
+    await run(`UPDATE migrations SET migration = '${to}' WHERE migration = '${from}'`);
+    result.remapped.push({ from, to });
+  }
+  for (const file of recordable) {
+    if ((await run(`SELECT migration FROM migrations WHERE migration = '${file}'`)).length > 0)
+      continue;
+    await run(`INSERT INTO migrations (migration) VALUES ('${file}')`);
+    result.recorded.push(file);
+  }
+  return result;
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/database",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.251",
+  "version": "0.70.253",
   "description": "The Stacks database integration.",
   "author": "Chris Breuer",
   "contributors": [
@@ -58,15 +58,15 @@
     "dynamodb-tooling": "^0.3.2"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.70.251",
-    "@stacksjs/config": "0.70.251",
-    "@stacksjs/logging": "0.70.251",
-    "@stacksjs/router": "0.70.251",
+    "@stacksjs/cli": "0.70.253",
+    "@stacksjs/config": "0.70.253",
+    "@stacksjs/logging": "0.70.253",
+    "@stacksjs/router": "0.70.253",
     "better-dx": "^0.2.17",
-    "@stacksjs/path": "0.70.251",
-    "@stacksjs/query-builder": "0.70.251",
-    "@stacksjs/storage": "0.70.251",
-    "@stacksjs/strings": "0.70.251",
-    "@stacksjs/utils": "0.70.251"
+    "@stacksjs/path": "0.70.253",
+    "@stacksjs/query-builder": "0.70.253",
+    "@stacksjs/storage": "0.70.253",
+    "@stacksjs/strings": "0.70.253",
+    "@stacksjs/utils": "0.70.253"
   }
 }