@rehearsal-db/core 0.1.0-beta.1

package/scripts/lib/rehearsal/diagnostics.mjs

@@ -0,0 +1,193 @@
+/**
+ * Purpose: Provide stable Rehearsal result, failure, redaction, and rendering
+ * contracts for humans and automation. Do not run directly; this module is reusable
+ * script infrastructure.
+ */
+
+import { createHash } from "node:crypto";
+
+export const REHEARSAL_RESULT_VERSION = 1;
+export const REHEARSAL_VERSION = "0.1.0-beta.1";
+
+export const REHEARSAL_EXIT_CODES = Object.freeze({
+  success: 0,
+  configuration_invalid: 2,
+  unsafe_environment: 3,
+  baseline_invalid: 4,
+  baseline_checksum_mismatch: 5,
+  migration_candidate_failure: 6,
+  migration_verification_failure: 7,
+  application_proof_failure: 8,
+  runtime_dependency_failure: 9,
+  internal_failure: 10,
+});
+
+const SECRET_KEY_PATTERN =
+  /(?:authorization|cookie|credential|database[_-]?url|jwt|key|password|secret|service[_-]?role|token)/iu;
+const JWT_PATTERN =
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/gu;
+const CONNECTION_STRING_PATTERN =
+  /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?):\/\/[^\s"']+/giu;
+const BEARER_PATTERN = /\bBearer\s+[^\s"']+/giu;
+const SUPABASE_KEY_PATTERN = /\bsb_(?:publishable|secret)_[A-Za-z0-9_-]+\b/gu;
+
+const redactString = (value) =>
+  value
+    .replace(CONNECTION_STRING_PATTERN, "[REDACTED_CONNECTION_STRING]")
+    .replace(JWT_PATTERN, "[REDACTED_JWT]")
+    .replace(BEARER_PATTERN, "Bearer [REDACTED]")
+    .replace(SUPABASE_KEY_PATTERN, "[REDACTED_KEY]");
+
+export const redactDiagnosticValue = (value, key = "") => {
+  if (SECRET_KEY_PATTERN.test(key)) return "[REDACTED]";
+  if (typeof value === "string") return redactString(value);
+  if (Array.isArray(value)) {
+    return value.map((entry) => redactDiagnosticValue(entry));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([entryKey, entryValue]) => [
+        entryKey,
+        redactDiagnosticValue(entryValue, entryKey),
+      ]),
+    );
+  }
+  return value;
+};
+
+const diagnosticIdFor = ({ category, code, message }) =>
+  createHash("sha256")
+    .update(`${category}\0${code}\0${message}`)
+    .digest("hex")
+    .slice(0, 12);
+
+export class RehearsalError extends Error {
+  constructor({
+    category,
+    code,
+    message,
+    expected,
+    actual,
+    context,
+    refused,
+    suggestions = [],
+    cause,
+  }) {
+    super(message, { cause });
+    this.name = "RehearsalError";
+    if (!Object.hasOwn(REHEARSAL_EXIT_CODES, category)) {
+      throw new Error(`Unknown Rehearsal error category: ${category}.`);
+    }
+    this.category = category;
+    this.code = code;
+    this.expected = expected;
+    this.actual = actual;
+    this.context = context;
+    this.refused = refused;
+    this.suggestions = suggestions;
+    this.diagnosticId = diagnosticIdFor({ category, code, message });
+    this.exitCode = REHEARSAL_EXIT_CODES[category];
+  }
+}
+
+const inferCategory = (error) => {
+  const message = String(error?.message ?? error);
+  if (/checksum/iu.test(message)) return "baseline_checksum_mismatch";
+  if (/candidate|migration history diverges/iu.test(message)) {
+    return "migration_candidate_failure";
+  }
+  if (/baseline|artifact|generation/iu.test(message)) return "baseline_invalid";
+  if (/migration|ledger|replay/iu.test(message)) {
+    return "migration_verification_failure";
+  }
+  if (/config|unknown rehearsal|unsupported rehearsal/iu.test(message)) {
+    return "configuration_invalid";
+  }
+  if (/loopback|hosted|unsafe|credential|outbound/iu.test(message)) {
+    return "unsafe_environment";
+  }
+  if (/docker|supabase|runtime|command|enoent/iu.test(message)) {
+    return "runtime_dependency_failure";
+  }
+  return "internal_failure";
+};
+
+export const normalizeRehearsalError = (error, overrides = {}) => {
+  if (error instanceof RehearsalError) return error;
+  const message = String(error?.message ?? error);
+  const category = overrides.category ?? inferCategory(error);
+  return new RehearsalError({
+    category,
+    code: overrides.code ?? category.toUpperCase(),
+    message,
+    expected: overrides.expected,
+    actual: overrides.actual,
+    context: overrides.context,
+    refused:
+      overrides.refused ??
+      "Rehearsal stopped before performing the requested operation.",
+    suggestions: overrides.suggestions ?? [],
+    cause: error,
+  });
+};
+
+export const createRehearsalResult = ({
+  command,
+  status,
+  data,
+  warnings = [],
+  startedAt = new Date(),
+  durationMs = 0,
+}) =>
+  redactDiagnosticValue({
+    schemaVersion: REHEARSAL_RESULT_VERSION,
+    rehearsalVersion: REHEARSAL_VERSION,
+    command,
+    status,
+    startedAt: startedAt.toISOString(),
+    durationMs,
+    warnings,
+    data,
+  });
+
+export const serializeRehearsalError = (error, { debug = false } = {}) => {
+  const failure = normalizeRehearsalError(error);
+  return redactDiagnosticValue({
+    schemaVersion: REHEARSAL_RESULT_VERSION,
+    rehearsalVersion: REHEARSAL_VERSION,
+    status: "error",
+    error: {
+      category: failure.category,
+      code: failure.code,
+      message: failure.message,
+      expected: failure.expected,
+      actual: failure.actual,
+      context: failure.context,
+      refused: failure.refused,
+      suggestions: failure.suggestions,
+      diagnosticId: failure.diagnosticId,
+      ...(debug && failure.cause
+        ? { cause: String(failure.cause?.message ?? failure.cause) }
+        : {}),
+    },
+  });
+};
+
+const formatValue = (value) =>
+  typeof value === "string" ? value : JSON.stringify(value);
+
+export const renderHumanError = (error, { debug = false } = {}) => {
+  const { error: failure } = serializeRehearsalError(error, { debug });
+  return [
+    `Rehearsal stopped: ${failure.message}`,
+    failure.expected ? `Expected: ${formatValue(failure.expected)}` : null,
+    failure.actual ? `Actual: ${formatValue(failure.actual)}` : null,
+    failure.context ? `Context: ${formatValue(failure.context)}` : null,
+    failure.refused ? `Refused: ${failure.refused}` : null,
+    ...(failure.suggestions ?? []).map((value) => `Try: ${value}`),
+    `Diagnostic: ${failure.diagnosticId} (${failure.category})`,
+    debug && failure.cause ? `Cause: ${failure.cause}` : null,
+  ]
+    .filter(Boolean)
+    .join("\n");
+};

package/scripts/lib/rehearsal/migration_history.mjs

@@ -0,0 +1,220 @@
+/**
+ * Purpose: Build and compare content-addressed application migration histories for
+ * Rehearsal without trusting timestamp-only migration alignment. Do not run directly;
+ * this module is reusable script infrastructure.
+ */
+
+import { createHash } from "node:crypto";
+import { readFile, readdir } from "node:fs/promises";
+
+const migrationNamePattern = /^(\d{14})_(.+)\.sql$/u;
+
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+
+const canonicalJson = (value) => `${JSON.stringify(value, null, "\t")}\n`;
+
+const normalizeStatement = (statement) => {
+  if (typeof statement !== "string") {
+    throw new Error("A Rehearsal migration ledger statement is not text.");
+  }
+  return statement.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+};
+
+const assertOrderedUniqueHistory = (entries, label) => {
+  const seen = new Set();
+  let previous = null;
+  for (const entry of entries) {
+    if (!/^\d{14}$/u.test(entry.version)) {
+      throw new Error(
+        `${label} has an invalid migration version: ${entry.version}`,
+      );
+    }
+    if (seen.has(entry.version)) {
+      throw new Error(
+        `${label} contains duplicate migration ${entry.version}.`,
+      );
+    }
+    if (previous !== null && entry.version <= previous) {
+      throw new Error(
+        `${label} is not in strictly increasing migration order at ${entry.version}.`,
+      );
+    }
+    seen.add(entry.version);
+    previous = entry.version;
+  }
+  return entries;
+};
+
+export const readMigrationFileInventory = async (directory) => {
+  const names = (await readdir(directory))
+    .filter((name) => name.endsWith(".sql"))
+    .sort();
+  const entries = [];
+  for (const filename of names) {
+    const match = migrationNamePattern.exec(filename);
+    if (!match) {
+      throw new Error(
+        `Invalid migration filename in ${directory}: ${filename}`,
+      );
+    }
+    const bytes = await readFile(new URL(filename, directory));
+    entries.push({
+      version: match[1],
+      name: match[2],
+      filename,
+      fileSha256: sha256(bytes),
+    });
+  }
+  return assertOrderedUniqueHistory(entries, "Migration files");
+};
+
+export const readMigrationSourceBundle = async ({
+  directory,
+  sourceLedger,
+}) => {
+  assertOrderedUniqueHistory(sourceLedger, "Source migration ledger");
+  const inventory = await readMigrationFileInventory(directory);
+  if (sourceLedger.length > inventory.length) {
+    throw new Error(
+      "The source migration history contains a version absent from local migration source.",
+    );
+  }
+  const bundle = [];
+  for (let index = 0; index < sourceLedger.length; index += 1) {
+    const source = sourceLedger[index];
+    const file = inventory[index];
+    if (source.version !== file.version || source.name !== file.name) {
+      throw new Error(
+        `Source migration ${source.version}_${source.name} does not match local file ${file.filename}.`,
+      );
+    }
+    bundle.push({
+      ...file,
+      content: await readFile(new URL(file.filename, directory), "utf8"),
+    });
+  }
+  return bundle;
+};
+
+export const buildMigrationLedgerInventory = (
+  rows,
+  label = "Migration ledger",
+) => {
+  if (!Array.isArray(rows) || rows.length === 0) {
+    throw new Error(`${label} is empty or unavailable.`);
+  }
+  const entries = rows.map((row) => {
+    if (!row || typeof row !== "object" || typeof row.name !== "string") {
+      throw new Error(`${label} contains an invalid row.`);
+    }
+    if (!Array.isArray(row.statements) || row.statements.length === 0) {
+      throw new Error(
+        `${label} migration ${row.version ?? "unknown"} has no applied statements.`,
+      );
+    }
+    const statements = row.statements.map(normalizeStatement);
+    return {
+      version: String(row.version),
+      name: row.name,
+      statementCount: statements.length,
+      statementSha256: sha256(JSON.stringify(statements)),
+    };
+  });
+  return assertOrderedUniqueHistory(entries, label);
+};
+
+export const createMigrationReplayReceipt = ({ files, ledger }) => {
+  assertOrderedUniqueHistory(files, "Migration files");
+  assertOrderedUniqueHistory(ledger, "Replayed migration ledger");
+  if (files.length !== ledger.length) {
+    throw new Error(
+      `Migration replay length mismatch: ${files.length} files but ${ledger.length} applied ledger rows.`,
+    );
+  }
+  const entries = files.map((file, index) => {
+    const applied = ledger[index];
+    if (file.version !== applied.version || file.name !== applied.name) {
+      throw new Error(
+        `Migration replay mismatch at ${file.filename}: ledger contains ${applied.version}_${applied.name}.`,
+      );
+    }
+    return {
+      version: file.version,
+      name: file.name,
+      filename: file.filename,
+      fileSha256: file.fileSha256,
+      statementCount: applied.statementCount,
+      statementSha256: applied.statementSha256,
+    };
+  });
+  return {
+    entries,
+    historySha256: sha256(canonicalJson(entries)),
+  };
+};
+
+export const compareSourceToReplay = ({
+  sourceLedger,
+  replayReceipt,
+  snapshotSchemaSha256,
+}) => {
+  assertOrderedUniqueHistory(sourceLedger, "Source migration ledger");
+  if (!replayReceipt?.entries?.length || !replayReceipt.historySha256) {
+    throw new Error("The migration replay receipt is missing or invalid.");
+  }
+  if (sourceLedger.length > replayReceipt.entries.length) {
+    throw new Error(
+      "The source migration history contains a version absent from the reviewed replay.",
+    );
+  }
+  const snapshotBacked = snapshotSchemaSha256 !== undefined;
+  if (snapshotBacked && !/^[a-f0-9]{64}$/u.test(snapshotSchemaSha256)) {
+    throw new Error("The production schema snapshot receipt is invalid.");
+  }
+  let historicalStatementDifferences = 0;
+  for (let index = 0; index < sourceLedger.length; index += 1) {
+    const source = sourceLedger[index];
+    const replayed = replayReceipt.entries[index];
+    if (source.version !== replayed.version || source.name !== replayed.name) {
+      throw new Error(
+        `Source migration history is not an exact replay prefix at ${source.version}_${source.name}.`,
+      );
+    }
+    if (
+      source.statementCount !== replayed.statementCount ||
+      source.statementSha256 !== replayed.statementSha256
+    ) {
+      if (!snapshotBacked) {
+        throw new Error(
+          `Applied statement content differs for migration ${source.version}_${source.name}.`,
+        );
+      }
+      historicalStatementDifferences += 1;
+    }
+  }
+  const candidates = replayReceipt.entries.slice(sourceLedger.length);
+  return {
+    cutoff: sourceLedger.at(-1).version,
+    candidates,
+    candidateSha256: sha256(canonicalJson(candidates)),
+    historicalStatementDifferences,
+    snapshotSchemaSha256: snapshotBacked ? snapshotSchemaSha256 : null,
+  };
+};
+
+export const assertNoCrossDatabaseMigrationVersions = ({
+  applicationFiles,
+  apiFiles,
+}) => {
+  const applicationVersions = new Set(
+    applicationFiles.map((entry) => entry.version),
+  );
+  const collisions = apiFiles
+    .map((entry) => entry.version)
+    .filter((version) => applicationVersions.has(version));
+  if (collisions.length) {
+    throw new Error(
+      `Primary and secondary database migration versions collide: ${collisions.join(", ")}.`,
+    );
+  }
+};