mandrel-platform 0.20.1 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.20.1",
+  "version": "0.24.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

package/scripts/check-ci-required-aggregator.test.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * check-ci-required-aggregator.test.mjs — regression guard for the
+ * self-maintaining `ci-required` aggregators (Story #234).
+ *
+ * Both `ci-required` aggregator jobs — `.github/workflows/pr-quality.yml`
+ * (the fleet-wide reusable PR gate) and `.github/workflows/ci.yml` (this
+ * repo's own gate) — previously required hand-maintained triple bookkeeping:
+ * the `needs:` array, a per-job `env:` block, and a bash loop over hardcoded
+ * job names. A job added to `needs:` but forgotten in the env/loop silently
+ * passed on a red run — on the platform's sole required branch-protection
+ * context.
+ *
+ * Story #234 replaced both with a `toJSON(needs)`-driven check. This suite
+ * pins that design against regression:
+ *
+ *   1. STRUCTURE — each aggregator's `steps:` derive results from
+ *      `toJSON(needs)` and contain NO hardcoded reference to any job named in
+ *      its own `needs:` array (the "no hardcoded tier-name list" AC).
+ *   2. PARITY — the two aggregators' `steps:` blocks are textually identical,
+ *      so a fix to one cannot drift from the other.
+ *   3. SEMANTICS — the shared run script passes on `success`/`skipped` and
+ *      fails on anything else, INCLUDING `cancelled` (load-bearing for #223's
+ *      fail-fast design), while naming the failing jobs and their results.
+ *      Executed against real bash+jq; skipped when jq is unavailable locally
+ *      (CI's ubuntu runner always has it).
+ *
+ * Run: node --test scripts/check-ci-required-aggregator.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readFileSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const AGGREGATOR_FILES = [
+  ".github/workflows/pr-quality.yml",
+  ".github/workflows/ci.yml",
+];
+
+// ---------------------------------------------------------------------------
+// Minimal indentation-based extraction (dependency-free, mirrors the
+// line-oriented approach of check-workflow-portability.mjs). Both workflows
+// declare jobs at 2-space indent, so the `ci-required` job block runs from
+// its `  ci-required:` line to the next non-blank line at indent <= 2.
+// ---------------------------------------------------------------------------
+
+function extractJobBlock(content, jobId) {
+  const lines = content.split("\n");
+  const start = lines.findIndex((l) => l === `  ${jobId}:`);
+  assert.notEqual(start, -1, `job \`${jobId}\` not found`);
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) continue;
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent <= 2) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+/** The `- <name>` entries under the job's `needs:` key. */
+function extractNeeds(jobBlock) {
+  const lines = jobBlock.split("\n");
+  const start = lines.findIndex((l) => l === "    needs:");
+  assert.notEqual(start, -1, "`needs:` block not found");
+  const names = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const m = lines[i].match(/^\s+-\s+([A-Za-z0-9_-]+)\s*$/);
+    if (!m) break;
+    names.push(m[1]);
+  }
+  assert.ok(names.length > 0, "`needs:` list is empty");
+  return names;
+}
+
+/** Everything from `    steps:` to the end of the job block. */
+function extractSteps(jobBlock) {
+  const idx = jobBlock.indexOf("    steps:");
+  assert.notEqual(idx, -1, "`steps:` block not found");
+  return jobBlock.slice(idx);
+}
+
+/** The dedented body of the (single) `run: |` block scalar in the steps. */
+function extractRunScript(steps) {
+  const lines = steps.split("\n");
+  const start = lines.findIndex((l) => /^\s+run:\s*\|\s*$/.test(l));
+  assert.notEqual(start, -1, "`run: |` block not found");
+  const runIndent = lines[start].match(/^(\s*)/)[1].length;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) {
+      body.push("");
+      continue;
+    }
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent <= runIndent) break;
+    body.push(lines[i].slice(runIndent + 2));
+  }
+  return body.join("\n");
+}
+
+const blocks = AGGREGATOR_FILES.map((rel) => {
+  const content = readFileSync(join(repoRoot, rel), "utf8");
+  const job = extractJobBlock(content, "ci-required");
+  return { rel, job, needs: extractNeeds(job), steps: extractSteps(job) };
+});
+
+// ---------------------------------------------------------------------------
+// 1. STRUCTURE — toJSON(needs)-driven, no hardcoded tier-name list
+// ---------------------------------------------------------------------------
+
+for (const { rel, needs, steps } of blocks) {
+  test(`${rel}: aggregator derives results from toJSON(needs)`, () => {
+    assert.match(
+      steps,
+      /\$\{\{\s*toJSON\(needs\)\s*\}\}/,
+      "the aggregator steps must consume `${{ toJSON(needs) }}`"
+    );
+  });
+
+  test(`${rel}: aggregator steps contain no hardcoded tier/job name`, () => {
+    // Strip YAML comments — prose may legitimately mention a job; only the
+    // executable env/run surface must stay name-free.
+    const executable = steps
+      .split("\n")
+      .filter((l) => !/^\s*#/.test(l))
+      .join("\n");
+    for (const name of needs) {
+      const re = new RegExp(
+        `(?<![A-Za-z0-9_-])${name.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&")}(?![A-Za-z0-9_-])`
+      );
+      assert.doesNotMatch(
+        executable,
+        re,
+        `steps hardcode \`${name}\` — adding a job to \`needs:\` must be the only edit; ` +
+          `never reintroduce the per-job env/loop bookkeeping`
+      );
+    }
+    assert.ok(
+      !/needs\.[A-Za-z0-9_-]+\.result/.test(executable),
+      "steps must not read per-job `needs.<id>.result` expressions"
+    );
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 2. PARITY — the two implementations are textually identical
+// ---------------------------------------------------------------------------
+
+test("pr-quality.yml and ci.yml aggregator steps are textually identical", () => {
+  assert.equal(
+    blocks[0].steps,
+    blocks[1].steps,
+    "the two `ci-required` steps blocks must not drift — apply every change to both"
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 3. SEMANTICS — pass on success/skipped, fail (naming jobs) on anything else
+// ---------------------------------------------------------------------------
+
+function jqAvailable() {
+  try {
+    execFileSync("jq", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runAggregator(needsResults) {
+  const script = extractRunScript(blocks[0].steps);
+  const dir = mkdtempSync(join(tmpdir(), "ci-required-"));
+  try {
+    const file = join(dir, "aggregate.sh");
+    writeFileSync(file, script);
+    const needsJson = Object.fromEntries(
+      Object.entries(needsResults).map(([k, result]) => [k, { result, outputs: {} }])
+    );
+    return spawnSync("bash", [file], {
+      encoding: "utf8",
+      env: { ...process.env, NEEDS_JSON: JSON.stringify(needsJson) },
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const semantics = { skip: jqAvailable() ? false : "jq not available on this host" };
+
+test("run script: all success → exit 0", semantics, () => {
+  const r = runAggregator({ lint: "success", unit: "success" });
+  assert.equal(r.status, 0, r.stderr);
+});
+
+test("run script: skipped counts as a pass", semantics, () => {
+  const r = runAggregator({ lint: "success", e2e: "skipped" });
+  assert.equal(r.status, 0, r.stderr);
+});
+
+test("run script: failure fails and names the job(result)", semantics, () => {
+  const r = runAggregator({ lint: "success", unit: "failure" });
+  assert.equal(r.status, 1);
+  assert.match(r.stderr, /unit\(failure\)/);
+});
+
+test("run script: cancelled fails (load-bearing for fail-fast, #223)", semantics, () => {
+  const r = runAggregator({ lint: "success", e2e: "cancelled" });
+  assert.equal(r.status, 1);
+  assert.match(r.stderr, /e2e\(cancelled\)/);
+});
+
+test("run script: every non-passing job is named", semantics, () => {
+  const r = runAggregator({ lint: "failure", unit: "cancelled", e2e: "success" });
+  assert.equal(r.status, 1);
+  assert.match(r.stderr, /lint\(failure\)/);
+  assert.match(r.stderr, /unit\(cancelled\)/);
+  assert.doesNotMatch(r.stderr, /e2e/);
+});

package/scripts/check-coverage-threshold.test.mjs

@@ -481,63 +481,46 @@ test("formatVerdict renders a skip line for the disabled gate", () => {
 });
 
 // ---------------------------------------------------------------------------
-// pr-quality.yml Coverage threshold gate — inline step regression (#163)
+// pr-quality.yml Coverage threshold gate — workflow-step parity (#163, #230)
 //
-// The workflow step embeds its OWN copy of the discovery logic (it must stay
-// dependency-free for consumer checkouts that have not adopted
-// check-coverage-threshold.mjs). #158 fixed only the standalone script; this
-// suite's `findCoverageSummaries` tests above cannot catch a regression in the
-// workflow file's embedded JS. These tests extract that embedded node script
-// straight out of pr-quality.yml and run it against real fixture trees, so the
-// exact #163 bug (matching a directory literally named `coverage`, missing
-// `coverage/<workspace>/coverage-summary.json`) cannot survive a refactor.
+// The workflow's "Coverage threshold gate" step no longer embeds a copy of
+// this script (Story #230): it sparse-side-checkouts mandrel-platform at
+// `github.job_workflow_sha` into `_mandrel-platform-scripts/` and runs
+// `scripts/check-coverage-threshold.mjs` directly. These tests exercise that
+// exact invocation shape — the real script, run from the side-checkout path,
+// with the workflow's `--threshold` / `--metric` args and the consumer
+// checkout as cwd — against real fixture trees, so the original #163 bug
+// (matching a directory literally named `coverage`, missing
+// `coverage/<workspace>/coverage-summary.json`) still cannot regress, and a
+// drift between "what the workflow runs" and "what these tests run" is
+// structurally impossible.
 // ---------------------------------------------------------------------------
 
-// Pull the embedded `node --input-type=module - <<'NODE' … NODE` script body
-// out of the "Coverage threshold gate" step, de-indenting the YAML block
-// scalar so it runs as a standalone ES module.
-function extractGateScript() {
-  const yaml = readFileSync(
-    join(__dirname, "..", ".github", "workflows", "pr-quality.yml"),
-    "utf8",
-  );
-  const lines = yaml.split(/\r?\n/);
-  const startIdx = lines.findIndex((l) =>
-    /node --input-type=module - <<'NODE'\s*$/.test(l),
-  );
-  assert.ok(
-    startIdx !== -1,
-    "expected an embedded `<<'NODE'` heredoc in pr-quality.yml",
-  );
-  // The heredoc opener carries the block-scalar indent; every body line shares
-  // at least that indent, and the closing `NODE` sentinel sits at the same
-  // indent. Strip it uniformly.
-  const indent = lines[startIdx].match(/^(\s*)/)[1];
-  const body = [];
-  for (let i = startIdx + 1; i < lines.length; i += 1) {
-    if (lines[i].trim() === "NODE") return body.join("\n");
-    body.push(
-      lines[i].startsWith(indent) ? lines[i].slice(indent.length) : lines[i],
-    );
-  }
-  throw new Error("unterminated `NODE` heredoc in pr-quality.yml gate step");
-}
+const WORKFLOW_FILE = join(__dirname, "..", ".github", "workflows", "pr-quality.yml");
+const GATE_SCRIPT = join(__dirname, "check-coverage-threshold.mjs");
 
-// Run the extracted gate script with COVERAGE_THRESHOLD / COVERAGE_METRIC set
-// and cwd pointed at `treeRoot`. Returns { status, stdout, stderr }.
+// Mirror the workflow step: materialize the side-checkout layout
+// (`_mandrel-platform-scripts/scripts/check-coverage-threshold.mjs`) inside
+// the fixture tree, then run the script exactly as the workflow does.
 function runGateStep(treeRoot, { threshold = "0", metric = "lines" } = {}) {
-  const scriptPath = join(treeRoot, "__gate-step.mjs");
-  writeFileSync(scriptPath, extractGateScript());
+  const sideCheckout = join(treeRoot, "_mandrel-platform-scripts", "scripts");
+  mkdirSync(sideCheckout, { recursive: true });
+  writeFileSync(
+    join(sideCheckout, "check-coverage-threshold.mjs"),
+    readFileSync(GATE_SCRIPT, "utf8"),
+  );
   try {
-    const stdout = execFileSync("node", [scriptPath], {
-      cwd: treeRoot,
-      env: {
-        ...process.env,
-        COVERAGE_THRESHOLD: threshold,
-        COVERAGE_METRIC: metric,
-      },
-      encoding: "utf8",
-    });
+    const stdout = execFileSync(
+      "node",
+      [
+        join("_mandrel-platform-scripts", "scripts", "check-coverage-threshold.mjs"),
+        "--threshold",
+        threshold,
+        "--metric",
+        metric,
+      ],
+      { cwd: treeRoot, env: { ...process.env }, encoding: "utf8" },
+    );
     return { status: 0, stdout, stderr: "" };
   } catch (err) {
     return {
@@ -548,6 +531,28 @@ function runGateStep(treeRoot, { threshold = "0", metric = "lines" } = {}) {
   }
 }
 
+test("pr-quality.yml runs the side-checkout script — no inline coverage heredoc remains (#230)", () => {
+  const yaml = readFileSync(WORKFLOW_FILE, "utf8");
+  // The gate step invokes the platform script from the side-checkout…
+  assert.match(
+    yaml,
+    /node _mandrel-platform-scripts\/scripts\/check-coverage-threshold\.mjs/,
+    "the Coverage threshold gate must run scripts/check-coverage-threshold.mjs from the side-checkout",
+  );
+  // …and the migration guard does the same.
+  assert.match(
+    yaml,
+    /node _mandrel-platform-scripts\/scripts\/check-destructive-migration\.mjs/,
+    "the migration guard must run scripts/check-destructive-migration.mjs from the side-checkout",
+  );
+  // The old inlined coverage-discovery copy (the #163 drift class) is gone.
+  assert.doesNotMatch(
+    yaml,
+    /findCoverageSummaries|intentionally duplicated|keep the two in sync/i,
+    "no inlined copy of the coverage gate may remain in pr-quality.yml",
+  );
+});
+
 test("pr-quality gate step discovers a per-workspace coverage/<ws>/ layout (#163 regression)", () => {
   const dir = mkdtempSync(join(tmpdir(), "gate-step-fanout-"));
   try {

package/scripts/check-destructive-migration.mjs

@@ -36,6 +36,7 @@
  *   node scripts/check-destructive-migration.mjs \
  *     --changed-files <file-with-one-path-per-line> \
  *     [--label-present] \
+ *     [--override-label <name>] \
  *     [--migration-glob '**​/migrations/**,**​/drizzle/**'] \
  *     [--repo-root <dir>]
  *
@@ -45,10 +46,18 @@
  *   • --label-present   Pass when the override acknowledgement label is on the
  *                       PR. Overrides a destructive finding (exit 0 with a
  *                       warning) instead of blocking.
+ *   • --override-label  The acknowledgement label NAME to cite in messages and
+ *                       the step summary (behaviour is still driven solely by
+ *                       --label-present). Default `migration:destructive-ok`.
  *   • --migration-glob  Comma-separated migration path globs. Default
  *                       `**​/migrations/**,**​/drizzle/**`.
  *   • --repo-root       Root to resolve changed-file paths against. Default cwd.
  *
+ * When `GITHUB_STEP_SUMMARY` is set (i.e. running inside a GitHub Actions
+ * step) and a destructive finding exists, a markdown summary block (ALLOWED
+ * via override / BLOCKED) is appended to that file — the same job-summary
+ * surface the previous in-workflow bash implementation wrote.
+ *
  * Exit codes:
  *   0 — no destructive migration in the changed set, OR a destructive
  *       migration is present AND the override label is applied.
@@ -60,7 +69,7 @@
  * docs/reusable-workflows.md (`pr-quality.yml` → migration guard).
  */
 
-import { readFileSync } from "node:fs";
+import { appendFileSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 // The override acknowledgement label. Documented in docs/reusable-workflows.md.
@@ -205,14 +214,47 @@ export function detectDestructiveMigrations({ changedFiles, readFile, globs = DE
   return { destructive: findings.length > 0, findings };
 }
 
+/**
+ * Render the GitHub job-summary markdown block for a destructive finding —
+ * the same summary surface the previous in-workflow bash implementation
+ * appended to `GITHUB_STEP_SUMMARY`. Only called when findings exist.
+ *
+ * @param {object} opts
+ * @param {Array<{file: string, signals: string[]}>} opts.findings
+ * @param {boolean} opts.labelPresent
+ * @param {string} opts.overrideLabel
+ * @returns {string}  Markdown, trailing-newline-terminated.
+ */
+export function formatStepSummary({ findings, labelPresent, overrideLabel }) {
+  const list = findings
+    .map((f) => `  • ${f.file} → ${f.signals.join(", ")}`)
+    .join("\n");
+  if (labelPresent) {
+    return (
+      "### Destructive-migration guard — ALLOWED via override\n\n" +
+      `Override label \`${overrideLabel}\` is present. Findings:\n\n` +
+      `${list}\n`
+    );
+  }
+  return (
+    "### ❌ Destructive-migration guard — BLOCKED\n\n" +
+    "A destructive migration was detected and the override label\n" +
+    `\`${overrideLabel}\` is NOT applied. Findings:\n\n` +
+    `${list}\n\n` +
+    `A reviewer must apply the \`${overrideLabel}\` label to\n` +
+    "acknowledge the destructive change, then re-run this check.\n"
+  );
+}
+
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
 
-function parseArgs(argv) {
+export function parseArgs(argv) {
   const opts = {
     changedFiles: null,
     labelPresent: false,
+    overrideLabel: DEFAULT_OVERRIDE_LABEL,
     globs: DEFAULT_MIGRATION_GLOBS,
     repoRoot: process.cwd(),
   };
@@ -222,6 +264,8 @@ function parseArgs(argv) {
       opts.changedFiles = argv[++i];
     } else if (a === "--label-present") {
       opts.labelPresent = true;
+    } else if (a === "--override-label" && argv[i + 1]) {
+      opts.overrideLabel = argv[++i];
     } else if (a === "--migration-glob" && argv[i + 1]) {
       opts.globs = argv[++i]
         .split(",")
@@ -252,7 +296,8 @@ function main() {
   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"
+        "[--label-present] [--override-label <name>] [--migration-glob <csv>] " +
+        "[--repo-root <dir>]\n"
     );
     process.exit(0);
   }
@@ -290,18 +335,35 @@ function main() {
     .map((f) => `  • ${f.file} → ${f.signals.join(", ")}`)
     .join("\n");
 
+  // Inside a GitHub Actions step, mirror the finding onto the job summary —
+  // the same surface the previous in-workflow bash implementation wrote.
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    try {
+      appendFileSync(
+        process.env.GITHUB_STEP_SUMMARY,
+        formatStepSummary({
+          findings,
+          labelPresent: opts.labelPresent,
+          overrideLabel: opts.overrideLabel,
+        })
+      );
+    } catch {
+      // Best-effort: the exit code below is the gate, the summary is cosmetic.
+    }
+  }
+
   if (opts.labelPresent) {
     process.stdout.write(
       `⚠️ Destructive migration detected, but the override label ` +
-        `'${DEFAULT_OVERRIDE_LABEL}' is applied — allowing.\n${summary}\n`
+        `'${opts.overrideLabel}' 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 ` +
+      `'${opts.overrideLabel}' is NOT applied — blocking.\n${summary}\n\n` +
+      `To proceed, a reviewer must apply the '${opts.overrideLabel}' label ` +
       `to acknowledge the destructive change, then re-run this check.\n`
   );
   process.exit(1);

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

@@ -14,18 +14,27 @@
  */
 
 import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 import { test } from "node:test";
 
 import {
   DEFAULT_MIGRATION_GLOBS,
   DEFAULT_OVERRIDE_LABEL,
   detectDestructiveMigrations,
+  formatStepSummary,
   globToRegExp,
   isMigrationFile,
+  parseArgs,
   scanMigrationText,
   stripComments,
 } from "./check-destructive-migration.mjs";
 
+const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "check-destructive-migration.mjs");
+
 // Build a readFile seam from an in-memory { path: text } map.
 function fakeReader(files) {
   return (path) => {
@@ -181,3 +190,140 @@ 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/**"]);
 });
+
+// ── parseArgs: the CLI surface pr-quality.yml drives ───────────────────────
+
+test("parseArgs: defaults", () => {
+  const opts = parseArgs([]);
+  assert.equal(opts.changedFiles, null);
+  assert.equal(opts.labelPresent, false);
+  assert.equal(opts.overrideLabel, DEFAULT_OVERRIDE_LABEL);
+  assert.deepEqual(opts.globs, DEFAULT_MIGRATION_GLOBS);
+});
+
+test("parseArgs: --override-label, --label-present, --migration-glob, --changed-files", () => {
+  const opts = parseArgs([
+    "--changed-files", "-",
+    "--label-present",
+    "--override-label", "db:drop-ok",
+    "--migration-glob", "**/db/changes/**, **/sql/**",
+  ]);
+  assert.equal(opts.changedFiles, "-");
+  assert.equal(opts.labelPresent, true);
+  assert.equal(opts.overrideLabel, "db:drop-ok");
+  assert.deepEqual(opts.globs, ["**/db/changes/**", "**/sql/**"]);
+});
+
+// ── formatStepSummary: the job-summary block parity contract ────────────────
+
+test("formatStepSummary: blocked shape names the override label and findings", () => {
+  const md = formatStepSummary({
+    findings: [{ file: "db/migrations/0010_drop.sql", signals: ["DROP statement"] }],
+    labelPresent: false,
+    overrideLabel: "migration:destructive-ok",
+  });
+  assert.ok(md.includes("### ❌ Destructive-migration guard — BLOCKED"));
+  assert.ok(md.includes("`migration:destructive-ok`"));
+  assert.ok(md.includes("db/migrations/0010_drop.sql → DROP statement"));
+});
+
+test("formatStepSummary: allowed shape reports the finding without blocking language", () => {
+  const md = formatStepSummary({
+    findings: [{ file: "db/migrations/0010_drop.sql", signals: ["TRUNCATE"] }],
+    labelPresent: true,
+    overrideLabel: "db:drop-ok",
+  });
+  assert.ok(md.includes("### Destructive-migration guard — ALLOWED via override"));
+  assert.ok(md.includes("`db:drop-ok`"));
+  assert.ok(!md.includes("BLOCKED"));
+});
+
+// ── CLI end-to-end: exit codes are the gate (behavioural-parity proof) ──────
+
+function runCli(args, { input = "", env = {} } = {}) {
+  try {
+    const stdout = execFileSync(process.execPath, [SCRIPT, ...args], {
+      input,
+      encoding: "utf8",
+      env: { ...process.env, GITHUB_STEP_SUMMARY: "", ...env },
+    });
+    return { code: 0, stdout, stderr: "" };
+  } catch (err) {
+    return { code: err.status, stdout: err.stdout ?? "", stderr: err.stderr ?? "" };
+  }
+}
+
+test("CLI: destructive migration without the label blocks (exit 1)", () => {
+  const root = mkdtempSync(join(tmpdir(), "destmig-"));
+  try {
+    mkdirSync(join(root, "db", "migrations"), { recursive: true });
+    writeFileSync(join(root, "db", "migrations", "0010_drop.sql"), "DROP TABLE users;\n");
+    const res = runCli(
+      ["--changed-files", "-", "--repo-root", root, "--override-label", "db:drop-ok"],
+      { input: "db/migrations/0010_drop.sql\n" }
+    );
+    assert.equal(res.code, 1);
+    assert.ok(res.stderr.includes("'db:drop-ok' is NOT applied — blocking"));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("CLI: the override label downgrades the block to a warning (exit 0)", () => {
+  const root = mkdtempSync(join(tmpdir(), "destmig-"));
+  try {
+    mkdirSync(join(root, "db", "migrations"), { recursive: true });
+    writeFileSync(join(root, "db", "migrations", "0010_drop.sql"), "DROP TABLE users;\n");
+    const res = runCli(
+      ["--changed-files", "-", "--repo-root", root, "--label-present"],
+      { input: "db/migrations/0010_drop.sql\n" }
+    );
+    assert.equal(res.code, 0);
+    assert.ok(res.stdout.includes(`'${DEFAULT_OVERRIDE_LABEL}' is applied — allowing`));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("CLI: comment-only DROP does not trip the guard (exit 0)", () => {
+  const root = mkdtempSync(join(tmpdir(), "destmig-"));
+  try {
+    mkdirSync(join(root, "db", "migrations"), { recursive: true });
+    writeFileSync(
+      join(root, "db", "migrations", "0011_note.sql"),
+      "-- DROP TABLE users; (rolled back)\nALTER TABLE users ADD COLUMN nickname TEXT;\n"
+    );
+    const res = runCli(["--changed-files", "-", "--repo-root", root], {
+      input: "db/migrations/0011_note.sql\n",
+    });
+    assert.equal(res.code, 0);
+    assert.ok(res.stdout.includes("No destructive migration detected"));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("CLI: missing --changed-files is a usage error (exit 2)", () => {
+  const res = runCli([]);
+  assert.equal(res.code, 2);
+  assert.ok(res.stderr.includes("--changed-files"));
+});
+
+test("CLI: a finding writes the GITHUB_STEP_SUMMARY block when the env var is set", () => {
+  const root = mkdtempSync(join(tmpdir(), "destmig-"));
+  try {
+    mkdirSync(join(root, "db", "migrations"), { recursive: true });
+    writeFileSync(join(root, "db", "migrations", "0010_drop.sql"), "TRUNCATE audit_log;\n");
+    const summaryFile = join(root, "step-summary.md");
+    const res = runCli(
+      ["--changed-files", "-", "--repo-root", root],
+      { input: "db/migrations/0010_drop.sql\n", env: { GITHUB_STEP_SUMMARY: summaryFile } }
+    );
+    assert.equal(res.code, 1);
+    const summary = readFileSync(summaryFile, "utf8");
+    assert.ok(summary.includes("### ❌ Destructive-migration guard — BLOCKED"));
+    assert.ok(summary.includes("TRUNCATE"));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});