mandrel-platform 0.12.0 → 0.14.2

package/scripts/check-coverage-threshold.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/**
+ * check-coverage-threshold.mjs
+ *
+ * Optional coverage-floor gate for the shared `pr-quality.yml` reusable
+ * workflow (Story #109).
+ *
+ * `pr-quality.yml` already uploads the `coverage/` tree as a build artifact,
+ * but no job asserts a floor — a PR can drop coverage and `ci-required` stays
+ * green.
+ * The `.agents/` harness ships a CRAP/MI/coverage *ratchet*, but the shared CI
+ * workflow itself had no coverage floor an operator could opt into at the
+ * workflow layer. This script is that floor: the `unit` job runs it with the
+ * `coverage-threshold` workflow input, and a non-zero exit fails the job —
+ * which is a `needs:` of `ci-required`.
+ *
+ * Design constraints:
+ *   • OPT-IN. A threshold of 0 (the default) is a no-op: the gate prints a
+ *     skip note and exits 0, preserving today's behaviour for non-adopters.
+ *   • No new tooling for consumers. The coverage source is the EXISTING
+ *     coverage output. We read the standard Istanbul/c8/vitest
+ *     `coverage-summary.json` (`total.<metric>.pct`) — the same file the test
+ *     runners already emit alongside the artifact upload.
+ *   • Dependency-free (no YAML/JSON-schema libs) so it copies cleanly into any
+ *     consumer's `scripts/` directory, exactly like the other shared lints.
+ *
+ * Usage:
+ *   node scripts/check-coverage-threshold.mjs --threshold 80
+ *   node scripts/check-coverage-threshold.mjs --threshold 80 --metric statements
+ *   node scripts/check-coverage-threshold.mjs --threshold 80 --coverage-dir packages/api/coverage
+ *
+ * Flags:
+ *   --threshold <pct>    Minimum coverage percentage (0 disables the gate).
+ *   --metric <name>      Which summary metric to assert: lines | statements |
+ *                        functions | branches. Default: lines.
+ *   --coverage-dir <d>   Override the coverage directory glob root. May be
+ *                        repeated. Default: scan the working tree for every
+ *                        coverage/coverage-summary.json under it.
+ *   --cwd <dir>          Root to resolve coverage paths against. Default: cwd.
+ *
+ * Exit codes:
+ *   0 — gate disabled (threshold 0), or measured coverage ≥ threshold.
+ *   1 — measured coverage below the threshold, OR the threshold is set but no
+ *       coverage summary could be found / parsed (a set floor must never pass
+ *       silently on missing data).
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for the sibling node:test suite)
+// ---------------------------------------------------------------------------
+
+export const VALID_METRICS = ["lines", "statements", "functions", "branches"];
+
+/**
+ * Parse the CLI argv (array AFTER `node script.mjs`) into an options object.
+ * Throws on a malformed numeric threshold or an unknown metric so the gate
+ * fails loudly rather than silently mis-reading its own configuration.
+ */
+export function parseArgs(argv) {
+  const opts = {
+    threshold: 0,
+    metric: "lines",
+    coverageDirs: [],
+    cwd: process.cwd(),
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if ((arg === "--threshold" || arg === "-t") && argv[i + 1] !== undefined) {
+      opts.threshold = parseThreshold(argv[++i]);
+    } else if ((arg === "--metric" || arg === "-m") && argv[i + 1] !== undefined) {
+      const metric = String(argv[++i]).trim().toLowerCase();
+      if (!VALID_METRICS.includes(metric)) {
+        throw new Error(
+          `unknown --metric "${metric}" (expected one of: ${VALID_METRICS.join(", ")})`
+        );
+      }
+      opts.metric = metric;
+    } else if (arg === "--coverage-dir" && argv[i + 1] !== undefined) {
+      opts.coverageDirs.push(String(argv[++i]));
+    } else if (arg === "--cwd" && argv[i + 1] !== undefined) {
+      opts.cwd = String(argv[++i]);
+    }
+  }
+  return opts;
+}
+
+/**
+ * Coerce a raw threshold token into a number in [0, 100]. An empty / unset
+ * value is treated as 0 (gate off), mirroring the workflow input default.
+ * Throws on a non-numeric or out-of-range value.
+ */
+export function parseThreshold(raw) {
+  if (raw === undefined || raw === null || String(raw).trim() === "") return 0;
+  const n = Number(String(raw).trim());
+  if (!Number.isFinite(n)) {
+    throw new Error(`invalid --threshold "${raw}" (must be a number)`);
+  }
+  if (n < 0 || n > 100) {
+    throw new Error(`--threshold ${n} out of range (must be between 0 and 100)`);
+  }
+  return n;
+}
+
+/**
+ * Extract `total.<metric>.pct` from a parsed coverage-summary.json object.
+ * Returns a finite number, or null when the shape doesn't carry it.
+ */
+export function extractPct(summary, metric) {
+  if (!summary || typeof summary !== "object") return null;
+  const total = summary.total;
+  if (!total || typeof total !== "object") return null;
+  const entry = total[metric];
+  if (!entry || typeof entry !== "object") return null;
+  const pct = entry.pct;
+  return typeof pct === "number" && Number.isFinite(pct) ? pct : null;
+}
+
+/**
+ * Decide pass/fail for a single measured pct against a threshold. The gate is
+ * inclusive: measured === threshold PASSES (a floor of 80 admits exactly 80%).
+ */
+export function meetsThreshold(pct, threshold) {
+  return typeof pct === "number" && Number.isFinite(pct) && pct >= threshold;
+}
+
+/**
+ * Recursively find every `coverage-summary.json` under `coverage/` directories
+ * below `root`. `node_modules` and dotted dirs (e.g. `.git`, `.agents`) are
+ * pruned so the scan stays fast and never reads a vendored framework tree.
+ * `roots` (from `--coverage-dir`) overrides the auto-scan when provided.
+ */
+export function findCoverageSummaries(root, roots = []) {
+  if (roots.length > 0) {
+    const out = [];
+    for (const dir of roots) {
+      const abs = resolve(root, dir);
+      const file = join(abs, "coverage-summary.json");
+      if (existsSync(file)) out.push(file);
+    }
+    return out;
+  }
+
+  const found = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const name = entry.name;
+      if (!entry.isDirectory()) continue;
+      if (name === "node_modules" || name.startsWith(".")) continue;
+      const full = join(dir, name);
+      if (name === "coverage") {
+        const file = join(full, "coverage-summary.json");
+        if (existsSync(file)) found.push(file);
+        // A coverage dir may still nest sub-package coverage; keep walking.
+      }
+      walk(full);
+    }
+  };
+  walk(resolve(root));
+  return found;
+}
+
+/**
+ * Read + parse a coverage-summary.json file. Returns the parsed object, or
+ * null on a read / JSON-parse failure (the caller treats this as "no data").
+ */
+export function readSummary(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Core gate evaluation, decoupled from argv + process so the test suite can
+ * drive it directly. Returns a structured verdict:
+ *   { ok, skipped, reason, threshold, metric, results: [{ file, pct, ok }] }
+ */
+export function evaluateGate(opts, { findSummaries = findCoverageSummaries, read = readSummary } = {}) {
+  const { threshold, metric, cwd, coverageDirs } = opts;
+
+  if (threshold <= 0) {
+    return {
+      ok: true,
+      skipped: true,
+      reason: "threshold 0 — coverage gate disabled (no-op)",
+      threshold,
+      metric,
+      results: [],
+    };
+  }
+
+  const files = findSummaries(cwd, coverageDirs);
+  if (files.length === 0) {
+    return {
+      ok: false,
+      skipped: false,
+      reason:
+        "coverage threshold is set but no coverage-summary.json was found under " +
+        "any **/coverage/ directory — ensure the test step emits a json-summary " +
+        "reporter (a set floor must not pass on missing data)",
+      threshold,
+      metric,
+      results: [],
+    };
+  }
+
+  const results = [];
+  for (const file of files) {
+    const summary = read(file);
+    const pct = extractPct(summary, metric);
+    if (pct === null) {
+      results.push({ file, pct: null, ok: false });
+    } else {
+      results.push({ file, pct, ok: meetsThreshold(pct, threshold) });
+    }
+  }
+
+  const failures = results.filter((r) => !r.ok);
+  return {
+    ok: failures.length === 0,
+    skipped: false,
+    reason: failures.length === 0 ? "all coverage summaries meet the floor" : "below floor",
+    threshold,
+    metric,
+    results,
+  };
+}
+
+/** Render the verdict to human-readable lines for the workflow log. */
+export function formatVerdict(verdict) {
+  const lines = [];
+  if (verdict.skipped) {
+    lines.push(`[coverage-threshold] ⏭️  ${verdict.reason}`);
+    return lines;
+  }
+  if (verdict.results.length === 0) {
+    lines.push(`[coverage-threshold] ❌ ${verdict.reason}`);
+    return lines;
+  }
+  for (const r of verdict.results) {
+    if (r.pct === null) {
+      lines.push(
+        `[coverage-threshold] ❌ ${r.file}: no "${verdict.metric}" total.pct in summary`
+      );
+    } else {
+      const mark = r.ok ? "✅" : "❌";
+      lines.push(
+        `[coverage-threshold] ${mark} ${r.file}: ${verdict.metric} ${r.pct}% ` +
+        `(floor ${verdict.threshold}%)`
+      );
+    }
+  }
+  if (verdict.ok) {
+    lines.push(
+      `[coverage-threshold] ✅ ${verdict.metric} coverage meets the ${verdict.threshold}% floor.`
+    );
+  } else {
+    lines.push(
+      `[coverage-threshold] ❌ ${verdict.metric} coverage is below the ${verdict.threshold}% floor.`
+    );
+  }
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// CLI entrypoint (skipped under `node --test` import)
+// ---------------------------------------------------------------------------
+
+export function runCli(argv, { log = console.log, err = console.error } = {}) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (e) {
+    err(`[coverage-threshold] ❌ ${e.message}`);
+    return 1;
+  }
+
+  const verdict = evaluateGate(opts);
+  for (const line of formatVerdict(verdict)) {
+    (verdict.ok ? log : err)(line);
+  }
+  return verdict.ok ? 0 : 1;
+}
+
+// Only run when executed directly, not when imported by the test suite.
+const invokedDirectly =
+  process.argv[1] && resolve(process.argv[1]).endsWith("check-coverage-threshold.mjs");
+if (invokedDirectly) {
+  process.exit(runCli(process.argv.slice(2)));
+}

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

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+/**
+ * check-coverage-threshold.test.mjs — node:test suite for the optional
+ * coverage-floor gate that backs `pr-quality.yml`'s `coverage-threshold`
+ * input (Story #109).
+ *
+ * This is the "equivalent self-test" the Story's acceptance criteria call for:
+ * it exercises the gate with the threshold both UNSET (0 → no-op, exit 0) and
+ * SET (pass when measured ≥ floor, fail when below, fail when the floor is set
+ * but no coverage summary exists). Pure helpers + an injectable summary
+ * source keep the whole pipeline offline — no real coverage tree needed.
+ *
+ * Run: node scripts/check-coverage-threshold.test.mjs   (or `node --test scripts/`)
+ */
+
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import {
+  VALID_METRICS,
+  parseArgs,
+  parseThreshold,
+  extractPct,
+  meetsThreshold,
+  findCoverageSummaries,
+  readSummary,
+  evaluateGate,
+  formatVerdict,
+  runCli,
+} from "./check-coverage-threshold.mjs";
+
+// Build a minimal Istanbul/c8/vitest-shaped coverage-summary object.
+function summary({ lines = 0, statements = 0, functions = 0, branches = 0 } = {}) {
+  return {
+    total: {
+      lines: { total: 100, covered: lines, skipped: 0, pct: lines },
+      statements: { total: 100, covered: statements, skipped: 0, pct: statements },
+      functions: { total: 100, covered: functions, skipped: 0, pct: functions },
+      branches: { total: 100, covered: branches, skipped: 0, pct: branches },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// parseThreshold
+// ---------------------------------------------------------------------------
+
+test("parseThreshold treats empty/unset as 0 (gate off)", () => {
+  assert.equal(parseThreshold(""), 0);
+  assert.equal(parseThreshold("   "), 0);
+  assert.equal(parseThreshold(undefined), 0);
+  assert.equal(parseThreshold(null), 0);
+});
+
+test("parseThreshold coerces numeric strings", () => {
+  assert.equal(parseThreshold("80"), 80);
+  assert.equal(parseThreshold("0"), 0);
+  assert.equal(parseThreshold("99.5"), 99.5);
+});
+
+test("parseThreshold rejects non-numeric and out-of-range values", () => {
+  assert.throws(() => parseThreshold("abc"), /must be a number/);
+  assert.throws(() => parseThreshold("-1"), /out of range/);
+  assert.throws(() => parseThreshold("101"), /out of range/);
+});
+
+// ---------------------------------------------------------------------------
+// parseArgs
+// ---------------------------------------------------------------------------
+
+test("parseArgs defaults: threshold 0, metric lines", () => {
+  const opts = parseArgs([]);
+  assert.equal(opts.threshold, 0);
+  assert.equal(opts.metric, "lines");
+  assert.deepEqual(opts.coverageDirs, []);
+});
+
+test("parseArgs reads --threshold/--metric/--coverage-dir", () => {
+  const opts = parseArgs([
+    "--threshold", "85",
+    "--metric", "Statements",
+    "--coverage-dir", "packages/api/coverage",
+    "--coverage-dir", "packages/web/coverage",
+  ]);
+  assert.equal(opts.threshold, 85);
+  assert.equal(opts.metric, "statements"); // normalized lowercase
+  assert.deepEqual(opts.coverageDirs, [
+    "packages/api/coverage",
+    "packages/web/coverage",
+  ]);
+});
+
+test("parseArgs rejects an unknown --metric", () => {
+  assert.throws(() => parseArgs(["--metric", "nonsense"]), /unknown --metric/);
+});
+
+test("VALID_METRICS covers the four Istanbul totals", () => {
+  assert.deepEqual(VALID_METRICS, ["lines", "statements", "functions", "branches"]);
+});
+
+// ---------------------------------------------------------------------------
+// extractPct / meetsThreshold
+// ---------------------------------------------------------------------------
+
+test("extractPct pulls total.<metric>.pct", () => {
+  const s = summary({ lines: 82, branches: 71 });
+  assert.equal(extractPct(s, "lines"), 82);
+  assert.equal(extractPct(s, "branches"), 71);
+});
+
+test("extractPct returns null for malformed shapes", () => {
+  assert.equal(extractPct(null, "lines"), null);
+  assert.equal(extractPct({}, "lines"), null);
+  assert.equal(extractPct({ total: {} }, "lines"), null);
+  assert.equal(extractPct({ total: { lines: {} } }, "lines"), null);
+  assert.equal(extractPct({ total: { lines: { pct: "x" } } }, "lines"), null);
+});
+
+test("meetsThreshold is inclusive at the floor", () => {
+  assert.equal(meetsThreshold(80, 80), true);
+  assert.equal(meetsThreshold(80.01, 80), true);
+  assert.equal(meetsThreshold(79.99, 80), false);
+  assert.equal(meetsThreshold(null, 80), false);
+});
+
+// ---------------------------------------------------------------------------
+// evaluateGate — threshold UNSET (the non-adopter no-op path)
+// ---------------------------------------------------------------------------
+
+test("evaluateGate: threshold 0 is a no-op pass (skipped)", () => {
+  const verdict = evaluateGate(
+    { threshold: 0, metric: "lines", cwd: ".", coverageDirs: [] },
+    {
+      // These MUST NOT be consulted when the gate is off.
+      findSummaries: () => {
+        throw new Error("findSummaries should not run when gate is disabled");
+      },
+      read: () => {
+        throw new Error("read should not run when gate is disabled");
+      },
+    }
+  );
+  assert.equal(verdict.ok, true);
+  assert.equal(verdict.skipped, true);
+  assert.match(verdict.reason, /disabled/);
+});
+
+// ---------------------------------------------------------------------------
+// evaluateGate — threshold SET
+// ---------------------------------------------------------------------------
+
+test("evaluateGate: SET + measured above floor → pass", () => {
+  const verdict = evaluateGate(
+    { threshold: 80, metric: "lines", cwd: ".", coverageDirs: [] },
+    {
+      findSummaries: () => ["/x/coverage/coverage-summary.json"],
+      read: () => summary({ lines: 91 }),
+    }
+  );
+  assert.equal(verdict.ok, true);
+  assert.equal(verdict.skipped, false);
+  assert.equal(verdict.results[0].pct, 91);
+  assert.equal(verdict.results[0].ok, true);
+});
+
+test("evaluateGate: SET + measured below floor → fail", () => {
+  const verdict = evaluateGate(
+    { threshold: 80, metric: "lines", cwd: ".", coverageDirs: [] },
+    {
+      findSummaries: () => ["/x/coverage/coverage-summary.json"],
+      read: () => summary({ lines: 73 }),
+    }
+  );
+  assert.equal(verdict.ok, false);
+  assert.equal(verdict.results[0].pct, 73);
+  assert.equal(verdict.results[0].ok, false);
+});
+
+test("evaluateGate: SET but no coverage summary found → fail (never silent-pass)", () => {
+  const verdict = evaluateGate(
+    { threshold: 80, metric: "lines", cwd: ".", coverageDirs: [] },
+    {
+      findSummaries: () => [],
+      read: () => null,
+    }
+  );
+  assert.equal(verdict.ok, false);
+  assert.equal(verdict.skipped, false);
+  assert.match(verdict.reason, /no coverage-summary\.json was found/);
+});
+
+test("evaluateGate: SET, one of many packages below floor → fail", () => {
+  const verdict = evaluateGate(
+    { threshold: 80, metric: "statements", cwd: ".", coverageDirs: [] },
+    {
+      findSummaries: () => ["a/coverage/coverage-summary.json", "b/coverage/coverage-summary.json"],
+      read: (f) => (f.startsWith("a") ? summary({ statements: 95 }) : summary({ statements: 40 })),
+    }
+  );
+  assert.equal(verdict.ok, false);
+  assert.equal(verdict.results.length, 2);
+  assert.equal(verdict.results.find((r) => r.file.startsWith("a")).ok, true);
+  assert.equal(verdict.results.find((r) => r.file.startsWith("b")).ok, false);
+});
+
+// ---------------------------------------------------------------------------
+// findCoverageSummaries / readSummary — real filesystem
+// ---------------------------------------------------------------------------
+
+test("findCoverageSummaries auto-scans **/coverage/, pruning node_modules + dotted dirs", () => {
+  const root = mkdtempSync(join(tmpdir(), "cov-gate-"));
+  try {
+    // A real package coverage dir.
+    mkdirSync(join(root, "packages", "api", "coverage"), { recursive: true });
+    writeFileSync(
+      join(root, "packages", "api", "coverage", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 88 }))
+    );
+    // A decoy under node_modules that MUST be pruned.
+    mkdirSync(join(root, "node_modules", "dep", "coverage"), { recursive: true });
+    writeFileSync(
+      join(root, "node_modules", "dep", "coverage", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 1 }))
+    );
+    // A decoy under a dotted dir that MUST be pruned.
+    mkdirSync(join(root, ".agents", "coverage"), { recursive: true });
+    writeFileSync(
+      join(root, ".agents", "coverage", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 2 }))
+    );
+
+    const files = findCoverageSummaries(root);
+    assert.equal(files.length, 1);
+    assert.match(files[0], /packages[/\\]api[/\\]coverage[/\\]coverage-summary\.json$/);
+
+    const parsed = readSummary(files[0]);
+    assert.equal(extractPct(parsed, "lines"), 88);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("findCoverageSummaries honours explicit --coverage-dir roots", () => {
+  const root = mkdtempSync(join(tmpdir(), "cov-gate-"));
+  try {
+    mkdirSync(join(root, "custom", "cov"), { recursive: true });
+    writeFileSync(
+      join(root, "custom", "cov", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 90 }))
+    );
+    const files = findCoverageSummaries(root, ["custom/cov"]);
+    assert.equal(files.length, 1);
+    assert.match(files[0], /custom[/\\]cov[/\\]coverage-summary\.json$/);
+
+    // A non-existent override yields nothing (the gate then fails as "no data").
+    assert.deepEqual(findCoverageSummaries(root, ["does/not/exist"]), []);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("readSummary returns null on unreadable / malformed JSON", () => {
+  const root = mkdtempSync(join(tmpdir(), "cov-gate-"));
+  try {
+    const bad = join(root, "coverage-summary.json");
+    writeFileSync(bad, "{ not valid json");
+    assert.equal(readSummary(bad), null);
+    assert.equal(readSummary(join(root, "missing.json")), null);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// runCli — end-to-end exit codes (threshold both unset and set)
+// ---------------------------------------------------------------------------
+
+test("runCli: threshold unset → exit 0 (preserves non-adopter behaviour)", () => {
+  const out = [];
+  const code = runCli([], { log: (m) => out.push(m), err: (m) => out.push(m) });
+  assert.equal(code, 0);
+  assert.ok(out.some((l) => /disabled/.test(l)));
+});
+
+test("runCli: threshold set, real passing coverage tree → exit 0", () => {
+  const root = mkdtempSync(join(tmpdir(), "cov-gate-"));
+  try {
+    mkdirSync(join(root, "coverage"), { recursive: true });
+    writeFileSync(
+      join(root, "coverage", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 95 }))
+    );
+    const out = [];
+    const code = runCli(["--threshold", "80", "--cwd", root], {
+      log: (m) => out.push(m),
+      err: (m) => out.push(m),
+    });
+    assert.equal(code, 0);
+    assert.ok(out.some((l) => /meets the 80% floor/.test(l)));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("runCli: threshold set, real failing coverage tree → exit 1", () => {
+  const root = mkdtempSync(join(tmpdir(), "cov-gate-"));
+  try {
+    mkdirSync(join(root, "coverage"), { recursive: true });
+    writeFileSync(
+      join(root, "coverage", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 50 }))
+    );
+    const out = [];
+    const code = runCli(["--threshold", "80", "--cwd", root], {
+      log: (m) => out.push(m),
+      err: (m) => out.push(m),
+    });
+    assert.equal(code, 1);
+    assert.ok(out.some((l) => /below the 80% floor/.test(l)));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("runCli: threshold set but no coverage data → exit 1", () => {
+  const root = mkdtempSync(join(tmpdir(), "cov-gate-"));
+  try {
+    const out = [];
+    const code = runCli(["--threshold", "80", "--cwd", root], {
+      log: (m) => out.push(m),
+      err: (m) => out.push(m),
+    });
+    assert.equal(code, 1);
+    assert.ok(out.some((l) => /no coverage-summary\.json was found/.test(l)));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("formatVerdict renders a skip line for the disabled gate", () => {
+  const lines = formatVerdict({
+    ok: true, skipped: true, reason: "threshold 0 — coverage gate disabled (no-op)",
+    threshold: 0, metric: "lines", results: [],
+  });
+  assert.equal(lines.length, 1);
+  assert.match(lines[0], /⏭️/);
+});