mandrel-platform 0.13.0 → 0.14.2

package/scripts/check-destructive-migration.mjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+/**
+ * check-destructive-migration.mjs
+ *
+ * Destructive-migration label guard (Story #111).
+ *
+ * Platformizes the destructive-migration guard that domio and athportal each
+ * hand-rolled and that swarm-os was missing entirely. A PR that introduces a
+ * destructive database migration (a `DROP`, an `ALTER ... DROP`, or a
+ * destructive drizzle-kit operation in a changed migration file) is BLOCKED
+ * unless a reviewer applies an explicit acknowledgement label
+ * (default: `migration:destructive-ok`).
+ *
+ * This is the static, PR-time half of the contract: it inspects the *changed
+ * migration files* for a destructive SQL/drizzle signal — it does NOT
+ * introspect a live database. The override is an explicit, human-applied PR
+ * label, so the destructive change still ships, but only with a deliberate
+ * acknowledgement on the record.
+ *
+ * Detection is a best-of-breed UNION of the two local guards it generalizes:
+ *   • `DROP TABLE` / `DROP COLUMN` / `DROP INDEX` / `DROP SCHEMA` / `DROP …`
+ *   • `ALTER TABLE … DROP COLUMN` / `ALTER TABLE … DROP CONSTRAINT`
+ *   • `TRUNCATE`
+ *   • drizzle-kit destructive ops emitted into a migration:
+ *       `.dropTable(` / `.dropColumn(` / `.dropIndex(` / `.dropConstraint(`
+ *   • a drizzle journal/breakpoint marker paired with a `DROP` statement
+ * Comment lines (`--`, `/* … *​/`, `//`) are stripped before matching so a
+ * `DROP` mentioned only in a comment does not trip the guard.
+ *
+ * The guard only inspects files whose path matches a migration glob (default
+ * `**​/migrations/**` and `**​/drizzle/**` plus a `*.sql` tail), so an
+ * unrelated source file mentioning `DROP` in a string never blocks a PR.
+ *
+ * --------------------------------------------------------------------------
+ * Usage (CLI — exit code is the gate):
+ *   node scripts/check-destructive-migration.mjs \
+ *     --changed-files <file-with-one-path-per-line> \
+ *     [--label-present] \
+ *     [--migration-glob '**​/migrations/**,**​/drizzle/**'] \
+ *     [--repo-root <dir>]
+ *
+ *   • --changed-files   Path to a newline-delimited list of PR-changed files
+ *                       (e.g. the output of `git diff --name-only base..head`).
+ *                       Use `-` to read the list from stdin.
+ *   • --label-present   Pass when the override acknowledgement label is on the
+ *                       PR. Overrides a destructive finding (exit 0 with a
+ *                       warning) instead of blocking.
+ *   • --migration-glob  Comma-separated migration path globs. Default
+ *                       `**​/migrations/**,**​/drizzle/**`.
+ *   • --repo-root       Root to resolve changed-file paths against. Default cwd.
+ *
+ * Exit codes:
+ *   0 — no destructive migration in the changed set, OR a destructive
+ *       migration is present AND the override label is applied.
+ *   1 — a destructive migration is present and the override label is absent
+ *       (the blocking case; the offending files + signals are named on stderr).
+ *   2 — a usage / IO error (bad args, unreadable file).
+ *
+ * The label name is part of the documented contract — see
+ * docs/reusable-workflows.md (`pr-quality.yml` → migration guard).
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// The override acknowledgement label. Documented in docs/reusable-workflows.md.
+export const DEFAULT_OVERRIDE_LABEL = "migration:destructive-ok";
+
+// Default migration path globs. A changed file must match one of these for the
+// destructive-signal scan to even look at it.
+export const DEFAULT_MIGRATION_GLOBS = ["**/migrations/**", "**/drizzle/**"];
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for the self-test)
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a restricted glob (supporting `**`, `*`, and literals) into a RegExp.
+ * `**` matches across path separators; `*` matches within a single segment.
+ *
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+export function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        // `**` → any chars including `/`. Consume an optional trailing slash so
+        // `**/migrations/**` matches `migrations/x` (no leading dir) too.
+        re += ".*";
+        i++;
+        if (glob[i + 1] === "/") i++;
+      } else {
+        // single `*` → any chars except `/`
+        re += "[^/]*";
+      }
+    } else if (".+?^${}()|[]\\".includes(c)) {
+      re += `\\${c}`;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * Is `filePath` a migration file per the supplied globs? A `.sql` file is also
+ * always treated as a migration candidate (drizzle/raw-SQL migrations land as
+ * `*.sql`), so a bare `0007_drop_users.sql` is covered even outside a
+ * `migrations/` directory.
+ *
+ * @param {string} filePath  Repo-relative path (forward slashes).
+ * @param {string[]} globs
+ * @returns {boolean}
+ */
+export function isMigrationFile(filePath, globs = DEFAULT_MIGRATION_GLOBS) {
+  const norm = filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (norm.endsWith(".sql")) return true;
+  return globs.some((g) => globToRegExp(g).test(norm));
+}
+
+/**
+ * Strip SQL / JS comments from a single line so a `DROP` that appears only in a
+ * comment does not trip the guard. Handles `--`, `//`, and a `/* … *​/` opened
+ * and closed on the same line. (Multi-line block comments are rare in migration
+ * files and conservatively left in — a false positive there is acknowledgeable
+ * via the override label.)
+ *
+ * @param {string} line
+ * @returns {string}
+ */
+export function stripComments(line) {
+  let out = line.replace(/\/\*.*?\*\//g, " ");
+  const dashIdx = out.indexOf("--");
+  if (dashIdx !== -1) out = out.slice(0, dashIdx);
+  const slashIdx = out.indexOf("//");
+  if (slashIdx !== -1) out = out.slice(0, slashIdx);
+  return out;
+}
+
+// The destructive-signal matchers. Each entry names the signal it detects so a
+// block message can tell the reviewer exactly what tripped the guard. Order is
+// most-specific-first only for readability; all are tested per line.
+const DESTRUCTIVE_PATTERNS = [
+  { signal: "ALTER TABLE … DROP", re: /\bALTER\s+TABLE\b[\s\S]*?\bDROP\b/i },
+  {
+    signal: "DROP statement",
+    // DROP TABLE/COLUMN/INDEX/SCHEMA/CONSTRAINT/VIEW/DATABASE/TYPE …
+    re: /\bDROP\s+(TABLE|COLUMN|INDEX|SCHEMA|CONSTRAINT|VIEW|DATABASE|TYPE|SEQUENCE|TRIGGER|FUNCTION)\b/i,
+  },
+  { signal: "TRUNCATE", re: /\bTRUNCATE\b/i },
+  {
+    signal: "drizzle destructive op",
+    re: /\.(dropTable|dropColumn|dropIndex|dropConstraint|dropForeignKey|dropPrimaryKey|dropUnique)\s*\(/,
+  },
+];
+
+/**
+ * Scan a single migration file's text for destructive signals.
+ *
+ * @param {string} text
+ * @returns {string[]}  De-duplicated list of signal names found (empty = clean).
+ */
+export function scanMigrationText(text) {
+  const found = new Set();
+  for (const rawLine of text.split("\n")) {
+    const line = stripComments(rawLine);
+    if (!line.trim()) continue;
+    for (const { signal, re } of DESTRUCTIVE_PATTERNS) {
+      if (re.test(line)) found.add(signal);
+    }
+  }
+  return [...found];
+}
+
+/**
+ * Core detection over a set of changed files. Pure: the caller supplies a
+ * `readFile` seam so the self-test never touches the filesystem.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.changedFiles   Repo-relative changed paths.
+ * @param {(path: string) => string} opts.readFile  Reads a file's text.
+ * @param {string[]} [opts.globs]        Migration path globs.
+ * @returns {{ destructive: boolean, findings: Array<{file: string, signals: string[]}> }}
+ */
+export function detectDestructiveMigrations({ changedFiles, readFile, globs = DEFAULT_MIGRATION_GLOBS }) {
+  const findings = [];
+  for (const file of changedFiles) {
+    if (!isMigrationFile(file, globs)) continue;
+    let text;
+    try {
+      text = readFile(file);
+    } catch {
+      // A deleted migration file shows up in the changed set but can't be read
+      // at head. Deleting a migration file is itself a destructive signal, so
+      // record it rather than silently passing.
+      findings.push({ file, signals: ["deleted migration file"] });
+      continue;
+    }
+    const signals = scanMigrationText(text);
+    if (signals.length > 0) findings.push({ file, signals });
+  }
+  return { destructive: findings.length > 0, findings };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = {
+    changedFiles: null,
+    labelPresent: false,
+    globs: DEFAULT_MIGRATION_GLOBS,
+    repoRoot: process.cwd(),
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--changed-files" && argv[i + 1]) {
+      opts.changedFiles = argv[++i];
+    } else if (a === "--label-present") {
+      opts.labelPresent = true;
+    } else if (a === "--migration-glob" && argv[i + 1]) {
+      opts.globs = argv[++i]
+        .split(",")
+        .map((g) => g.trim())
+        .filter(Boolean);
+    } else if (a === "--repo-root" && argv[i + 1]) {
+      opts.repoRoot = resolve(argv[++i]);
+    } else if (a === "--help" || a === "-h") {
+      opts.help = true;
+    }
+  }
+  return opts;
+}
+
+function readChangedList(source) {
+  const raw =
+    source === "-"
+      ? readFileSync(0, "utf8")
+      : readFileSync(resolve(source), "utf8");
+  return raw
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    process.stdout.write(
+      "Usage: node scripts/check-destructive-migration.mjs --changed-files <path|-> " +
+        "[--label-present] [--migration-glob <csv>] [--repo-root <dir>]\n"
+    );
+    process.exit(0);
+  }
+  if (!opts.changedFiles) {
+    process.stderr.write(
+      "[check-destructive-migration] ERROR: --changed-files <path|-> is required.\n"
+    );
+    process.exit(2);
+  }
+
+  let changedFiles;
+  try {
+    changedFiles = readChangedList(opts.changedFiles);
+  } catch (err) {
+    process.stderr.write(
+      `[check-destructive-migration] ERROR: cannot read changed-files list: ${err.message}\n`
+    );
+    process.exit(2);
+  }
+
+  const { destructive, findings } = detectDestructiveMigrations({
+    changedFiles,
+    globs: opts.globs,
+    readFile: (file) => readFileSync(resolve(opts.repoRoot, file), "utf8"),
+  });
+
+  if (!destructive) {
+    process.stdout.write(
+      "✅ No destructive migration detected in the changed files.\n"
+    );
+    process.exit(0);
+  }
+
+  const summary = findings
+    .map((f) => `  • ${f.file} → ${f.signals.join(", ")}`)
+    .join("\n");
+
+  if (opts.labelPresent) {
+    process.stdout.write(
+      `⚠️ Destructive migration detected, but the override label ` +
+        `'${DEFAULT_OVERRIDE_LABEL}' is applied — allowing.\n${summary}\n`
+    );
+    process.exit(0);
+  }
+
+  process.stderr.write(
+    `❌ Destructive migration detected and the override label ` +
+      `'${DEFAULT_OVERRIDE_LABEL}' is NOT applied — blocking.\n${summary}\n\n` +
+      `To proceed, a reviewer must apply the '${DEFAULT_OVERRIDE_LABEL}' label ` +
+      `to acknowledge the destructive change, then re-run this check.\n`
+  );
+  process.exit(1);
+}
+
+// Only run the CLI when invoked directly, not when imported by the self-test.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

package/scripts/check-destructive-migration.test.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * check-destructive-migration.test.mjs — node:test suite for the platformized
+ * destructive-migration label guard (Story #111).
+ *
+ * The guard's detection core (`detectDestructiveMigrations`) takes an injected
+ * `readFile` seam, so the whole signal-detection pipeline is exercised offline
+ * with in-memory fixtures — no filesystem, no `git`, no `gh`. This is the
+ * "validated via self-test" half of the Story's acceptance contract; the
+ * cross-repo smoke (pr-quality.yml consumed by the smoke repo) is the
+ * end-to-end half.
+ *
+ * Run: node scripts/check-destructive-migration.test.mjs  (or `node --test scripts/`)
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  DEFAULT_MIGRATION_GLOBS,
+  DEFAULT_OVERRIDE_LABEL,
+  detectDestructiveMigrations,
+  globToRegExp,
+  isMigrationFile,
+  scanMigrationText,
+  stripComments,
+} from "./check-destructive-migration.mjs";
+
+// Build a readFile seam from an in-memory { path: text } map.
+function fakeReader(files) {
+  return (path) => {
+    if (!(path in files)) {
+      const err = new Error(`ENOENT: ${path}`);
+      err.code = "ENOENT";
+      throw err;
+    }
+    return files[path];
+  };
+}
+
+// ── globToRegExp / isMigrationFile ─────────────────────────────────────────
+
+test("globToRegExp: `**` crosses path separators, `*` does not", () => {
+  assert.ok(globToRegExp("**/migrations/**").test("apps/db/migrations/0001.sql"));
+  assert.ok(globToRegExp("**/migrations/**").test("migrations/0001.sql"));
+  assert.ok(!globToRegExp("*.sql").test("db/x.sql")); // single * stays in-segment
+  assert.ok(globToRegExp("*.sql").test("x.sql"));
+});
+
+test("isMigrationFile: matches migration globs and any .sql tail", () => {
+  assert.ok(isMigrationFile("apps/api/migrations/0007_drop.ts"));
+  assert.ok(isMigrationFile("drizzle/0001_init.sql"));
+  assert.ok(isMigrationFile("0007_drop_users.sql")); // bare .sql counts
+  assert.ok(!isMigrationFile("src/services/user.ts"));
+  assert.ok(!isMigrationFile("README.md"));
+});
+
+test("isMigrationFile: honours a custom glob set", () => {
+  const globs = ["**/db/changes/**"];
+  assert.ok(isMigrationFile("pkg/db/changes/x.ts", globs));
+  assert.ok(!isMigrationFile("pkg/migrations/x.ts", globs)); // default glob not in set
+});
+
+// ── stripComments ──────────────────────────────────────────────────────────
+
+test("stripComments: removes -- , // and inline /* */ comments", () => {
+  assert.equal(stripComments("CREATE TABLE x; -- DROP TABLE y").trim(), "CREATE TABLE x;");
+  assert.equal(stripComments("ok(); // DROP TABLE y").trim(), "ok();");
+  assert.equal(stripComments("a /* DROP TABLE y */ b").replace(/\s+/g, " ").trim(), "a b");
+});
+
+// ── scanMigrationText: the destructive signal union ────────────────────────
+
+test("scanMigrationText: detects DROP TABLE / COLUMN / INDEX / etc.", () => {
+  assert.deepEqual(scanMigrationText("DROP TABLE users;"), ["DROP statement"]);
+  assert.deepEqual(scanMigrationText("drop  column email"), ["DROP statement"]);
+  assert.deepEqual(scanMigrationText("DROP INDEX idx_users_email;"), ["DROP statement"]);
+});
+
+test("scanMigrationText: detects ALTER TABLE … DROP", () => {
+  const signals = scanMigrationText("ALTER TABLE users DROP COLUMN legacy_id;");
+  assert.ok(signals.includes("ALTER TABLE … DROP"));
+});
+
+test("scanMigrationText: detects TRUNCATE", () => {
+  assert.deepEqual(scanMigrationText("TRUNCATE audit_log;"), ["TRUNCATE"]);
+});
+
+test("scanMigrationText: detects drizzle destructive ops", () => {
+  assert.deepEqual(
+    scanMigrationText("await db.schema.dropColumn('users', 'legacy');"),
+    ["drizzle destructive op"]
+  );
+  assert.deepEqual(
+    scanMigrationText("table.dropConstraint('fk_x')"),
+    ["drizzle destructive op"]
+  );
+});
+
+test("scanMigrationText: clean migration yields no signals", () => {
+  assert.deepEqual(
+    scanMigrationText("CREATE TABLE users (id INTEGER PRIMARY KEY);\nADD COLUMN email TEXT;"),
+    []
+  );
+});
+
+test("scanMigrationText: a DROP only in a comment does NOT trip the guard", () => {
+  assert.deepEqual(scanMigrationText("-- DROP TABLE users; (rolled back)"), []);
+  assert.deepEqual(scanMigrationText("// dropTable('users')"), []);
+});
+
+test("scanMigrationText: de-duplicates repeated signals", () => {
+  const signals = scanMigrationText("DROP TABLE a;\nDROP TABLE b;");
+  assert.deepEqual(signals, ["DROP statement"]);
+});
+
+// ── detectDestructiveMigrations: end-to-end over a changed set ─────────────
+
+test("detect: flags a destructive migration file", () => {
+  const files = { "db/migrations/0007_drop.sql": "DROP TABLE users;" };
+  const res = detectDestructiveMigrations({
+    changedFiles: Object.keys(files),
+    readFile: fakeReader(files),
+  });
+  assert.equal(res.destructive, true);
+  assert.equal(res.findings.length, 1);
+  assert.deepEqual(res.findings[0].signals, ["DROP statement"]);
+});
+
+test("detect: ignores non-migration files even if they mention DROP", () => {
+  const files = {
+    "src/sql-builder.ts": "const q = 'DROP TABLE foo';",
+    "docs/notes.md": "We will DROP COLUMN later.",
+  };
+  const res = detectDestructiveMigrations({
+    changedFiles: Object.keys(files),
+    readFile: fakeReader(files),
+  });
+  assert.equal(res.destructive, false);
+  assert.deepEqual(res.findings, []);
+});
+
+test("detect: clean migration passes", () => {
+  const files = { "db/migrations/0008_add.sql": "ALTER TABLE users ADD COLUMN nickname TEXT;" };
+  const res = detectDestructiveMigrations({
+    changedFiles: Object.keys(files),
+    readFile: fakeReader(files),
+  });
+  assert.equal(res.destructive, false);
+});
+
+test("detect: a deleted migration file is itself a destructive signal", () => {
+  const res = detectDestructiveMigrations({
+    changedFiles: ["db/migrations/0005_old.sql"],
+    readFile: () => {
+      throw new Error("ENOENT");
+    },
+  });
+  assert.equal(res.destructive, true);
+  assert.deepEqual(res.findings[0].signals, ["deleted migration file"]);
+});
+
+test("detect: mixed set reports only the destructive migration", () => {
+  const files = {
+    "db/migrations/0009_add.sql": "ALTER TABLE x ADD COLUMN y TEXT;",
+    "db/migrations/0010_drop.sql": "ALTER TABLE x DROP COLUMN z;",
+    "src/app.ts": "doStuff();",
+  };
+  const res = detectDestructiveMigrations({
+    changedFiles: Object.keys(files),
+    readFile: fakeReader(files),
+  });
+  assert.equal(res.destructive, true);
+  assert.equal(res.findings.length, 1);
+  assert.equal(res.findings[0].file, "db/migrations/0010_drop.sql");
+});
+
+// ── Contract constants ─────────────────────────────────────────────────────
+
+test("override label and default globs are the documented contract values", () => {
+  assert.equal(DEFAULT_OVERRIDE_LABEL, "migration:destructive-ok");
+  assert.deepEqual(DEFAULT_MIGRATION_GLOBS, ["**/migrations/**", "**/drizzle/**"]);
+});