@wcag-audit/cli 1.0.0-alpha.11

package/src/checkers/util/consistency-match.js

@@ -0,0 +1,53 @@
+// Shared helpers for WCAG 3.2.3 / 3.2.4 consistency checks. Kept as a
+// pure ES module so both the Node-side checker (cli/src/checkers/
+// consistency.js) and the Vitest suite can import them. The extension's
+// browser-context copy of the same logic lives inline in
+// ext-checkers/consistency.js — keep the two in sync.
+
+export function dedupPreserveOrder(arr) {
+  const seen = new Set();
+  const out = [];
+  for (const x of arr) if (!seen.has(x)) { seen.add(x); out.push(x); }
+  return out;
+}
+
+export function normalizeLabel(s) {
+  return (s || "")
+    .toLowerCase()
+    .replace(/[→←▸▶️→↗↘🡒→]/g, "")
+    .replace(/[^\p{L}\p{N}\s]/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+// WCAG 3.2.4 is about FUNCTIONAL consistency. Two names are compatible
+// when they describe the same component even if decorators differ.
+export function namesCompatible(a, b) {
+  const na = normalizeLabel(a);
+  const nb = normalizeLabel(b);
+  if (!na || !nb) return true;
+  if (na === nb) return true;
+  if (na.includes(nb) || nb.includes(na)) return true;
+  const fa = na.split(" ")[0];
+  const fb = nb.split(" ")[0];
+  if (fa && fa === fb && fa.length >= 4) return true;
+  // All words of the shorter name appear in the longer name.
+  // Catches "CLI" ↔ "Full CLI docs" and "CLI docs" ↔ "CLI (npx …)".
+  const wa = na.split(" ");
+  const wb = nb.split(" ");
+  const [short, long] = wa.length <= wb.length ? [wa, wb] : [wb, wa];
+  const longSet = new Set(long);
+  if (short.every((w) => w.length >= 3 && longSet.has(w))) return true;
+  return false;
+}
+
+// Relative-order check: given two nav link arrays (already dedupped),
+// return true when the subset of common labels appears in the SAME
+// relative order on both sides.
+export function navOrderMatches(a, b) {
+  const common = a.filter((x) => b.includes(x));
+  const aOrder = common.map((x) => a.indexOf(x));
+  const bOrder = common.map((x) => b.indexOf(x));
+  const increasing = (arr) => arr.every((v, i) => i === 0 || v > arr[i - 1]);
+  return increasing(aOrder) && increasing(bOrder);
+}

package/src/checkers/util/consistency-match.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import {
+  dedupPreserveOrder,
+  normalizeLabel,
+  namesCompatible,
+  navOrderMatches,
+} from "./consistency-match.js";
+
+describe("dedupPreserveOrder", () => {
+  it("drops later duplicates and preserves first-seen order", () => {
+    expect(dedupPreserveOrder(["a", "b", "a", "c", "b"])).toEqual(["a", "b", "c"]);
+  });
+  it("handles empty arrays", () => {
+    expect(dedupPreserveOrder([])).toEqual([]);
+  });
+});
+
+describe("normalizeLabel", () => {
+  it("strips trailing arrow decorator", () => {
+    expect(normalizeLabel("View on npm →")).toBe("view on npm");
+  });
+  it("collapses whitespace and lowercases", () => {
+    expect(normalizeLabel("  CLI   Docs  ")).toBe("cli docs");
+  });
+});
+
+describe("namesCompatible", () => {
+  it("treats view on npm / view on npm → as compatible", () => {
+    expect(namesCompatible("view on npm", "View on npm →")).toBe(true);
+  });
+  it("treats CLI / CLI Docs as compatible (substring)", () => {
+    expect(namesCompatible("CLI", "CLI Docs")).toBe(true);
+  });
+  it("treats View on npm / View on npm → as compatible (trailing arrow decorator)", () => {
+    expect(namesCompatible("View on npm", "View on npm →")).toBe(true);
+  });
+  it("flags unrelated names", () => {
+    expect(namesCompatible("Pricing", "Contact")).toBe(false);
+  });
+});
+
+describe("navOrderMatches", () => {
+  it("returns true when duplicate nav is dedupped and order is identical", () => {
+    const raw = ["WCAG Audit", "Pricing", "CLI", "Download", "Contact", "Dashboard",
+                 "Pricing", "CLI", "Download", "Contact", "Dashboard"];
+    const deduped = dedupPreserveOrder(raw);
+    expect(navOrderMatches(deduped, deduped)).toBe(true);
+  });
+  it("returns false when order differs after dedup", () => {
+    const a = ["Home", "Pricing", "CLI"];
+    const b = ["Home", "CLI", "Pricing"];
+    expect(navOrderMatches(a, b)).toBe(false);
+  });
+});

package/src/checkers/viewport.js

@@ -0,0 +1,214 @@
+// Viewport / CSS-injection checker. Covers:
+//
+//   1.4.4  Resize Text   — emulate 200% browser zoom, look for content loss
+//   1.4.10 Reflow        — shrink viewport to 320 CSS px, check for h-scroll
+//   1.4.12 Text Spacing  — inject WCAG-required spacing CSS, check for clipped text
+//
+// Each test runs in a fresh page context built from the live URL so we
+// don't pollute the main page state for downstream checkers.
+
+import { saveScreenshot } from "../util/screenshot.js";
+
+export async function runViewport(ctx) {
+  const findings = [];
+
+  // ── 1.4.10 Reflow ────────────────────────────────────────────────────
+  {
+    const sub = await ctx.context.newPage();
+    try {
+      await sub.setViewportSize({ width: 320, height: 256 });
+      await sub.goto(ctx.url, { waitUntil: "networkidle", timeout: 60_000 });
+      await sub.waitForTimeout(500);
+      const result = await sub.evaluate(() => {
+        return {
+          docWidth: document.documentElement.scrollWidth,
+          viewportWidth: window.innerWidth,
+          horizontalOverflowElems: (() => {
+            const out = [];
+            document.querySelectorAll("body *").forEach((el) => {
+              const r = el.getBoundingClientRect();
+              if (r.right > window.innerWidth + 5 && r.width > 50) {
+                out.push({
+                  tag: el.tagName.toLowerCase(),
+                  width: Math.round(r.width),
+                  text: (el.innerText || "").trim().slice(0, 60),
+                });
+              }
+            });
+            return out.slice(0, 15);
+          })(),
+        };
+      });
+      if (result.docWidth > result.viewportWidth + 5) {
+        const buf = await sub.screenshot({ fullPage: false, type: "png" });
+        const screenshotFile = await saveScreenshot(buf, ctx.screenshotsDir, "reflow_320");
+        findings.push({
+          source: "playwright",
+          ruleId: "viewport/reflow",
+          criteria: "1.4.10",
+          level: "AA",
+          impact: "serious",
+          description: `Page requires horizontal scrolling at 320 CSS px (document width = ${result.docWidth}px). WCAG 1.4.10 requires reflow without two-dimensional scrolling at this width.`,
+          help: "Make layouts responsive. Avoid fixed-pixel widths on containers, tables, and images. Use min-width: 0 on flex children, allow long words to break, and use overflow-wrap: anywhere.",
+          helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/reflow.html",
+          selector: result.horizontalOverflowElems.map((e) => e.tag).slice(0, 5).join(", "),
+          evidence: JSON.stringify(result.horizontalOverflowElems, null, 2),
+          failureSummary: `${result.horizontalOverflowElems.length} elements overflow the 320px viewport`,
+          screenshotFile,
+        });
+      }
+    } finally {
+      await sub.close().catch(() => {});
+    }
+  }
+
+  // ── 1.4.4 Resize Text (200% zoom) ────────────────────────────────────
+  {
+    const sub = await ctx.context.newPage();
+    try {
+      await sub.setViewportSize({ width: 1366, height: 900 });
+      await sub.goto(ctx.url, { waitUntil: "networkidle", timeout: 60_000 });
+      // Approximate 200% zoom by doubling the document fontSize and using
+      // CSS transform on body. Pure zoom would need DevTools Protocol; this
+      // catches most layout-loss bugs.
+      await sub.addStyleTag({
+        content: `html { font-size: 200% !important; } body { zoom: 2; }`,
+      });
+      await sub.waitForTimeout(400);
+      const overflow = await sub.evaluate(() => {
+        // Visually-hidden patterns (sr-only, screen-reader-only, etc.) are
+        // INTENDED to be 1x1px with clipped content — they're WCAG-approved
+        // for skip links and screen-reader-only instructions. Skip them.
+        function isVisuallyHidden(el, cs) {
+          const r = el.getBoundingClientRect();
+          if (r.width <= 2 && r.height <= 2) return true;
+          if (cs.clip && cs.clip !== "auto" && cs.clip !== "unset") return true;
+          if (cs.clipPath && cs.clipPath !== "none" && cs.clipPath.includes("inset(100%)")) return true;
+          const classes = el.className || "";
+          if (typeof classes === "string" && /\b(sr-only|visually-hidden|screen-reader|a11y-hidden)\b/.test(classes)) {
+            return true;
+          }
+          return false;
+        }
+        const out = [];
+        document.querySelectorAll("body *").forEach((el) => {
+          const cs = getComputedStyle(el);
+          if (isVisuallyHidden(el, cs)) return;
+          if (el.scrollHeight > el.clientHeight + 2 && cs.overflow === "hidden") {
+            const cls = (el.className && typeof el.className === "string") ? el.className.split(/\s+/).filter(Boolean).slice(0, 2).join(".") : "";
+            out.push({
+              tag: el.tagName.toLowerCase(),
+              id: el.id || "",
+              cls,
+              text: (el.innerText || "").trim().slice(0, 60),
+            });
+          }
+        });
+        return out.slice(0, 15);
+      });
+      // Keep only elements with a distinctive selector (id or class). A
+      // bare <a> or <div> with no class produces more noise than signal.
+      const informative = overflow.filter((e) => e.id || e.cls);
+      if (informative.length) {
+        const buf = await sub.screenshot({ fullPage: false, type: "png" });
+        const screenshotFile = await saveScreenshot(buf, ctx.screenshotsDir, "resize_text_200");
+        const sel = informative.slice(0, 5).map((e) => e.id ? `#${e.id}` : `${e.tag}.${e.cls}`).join(", ");
+        findings.push({
+          source: "playwright",
+          ruleId: "viewport/resize-text",
+          criteria: "1.4.4",
+          level: "AA",
+          impact: "serious",
+          description: `${informative.length} element(s) have clipped content when text is doubled in size (overflow:hidden with scroll content).`,
+          help: "WCAG 1.4.4 requires that text be resizable up to 200% without loss of content or function. Avoid fixed heights on text containers. Use min-height + padding instead of height.",
+          helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html",
+          selector: sel,
+          evidence: JSON.stringify(informative.slice(0, 10), null, 2),
+          failureSummary: `${informative.length} clipped containers`,
+          screenshotFile,
+        });
+      }
+    } finally {
+      await sub.close().catch(() => {});
+    }
+  }
+
+  // ── 1.4.12 Text Spacing ──────────────────────────────────────────────
+  {
+    const sub = await ctx.context.newPage();
+    try {
+      await sub.setViewportSize({ width: 1366, height: 900 });
+      await sub.goto(ctx.url, { waitUntil: "networkidle", timeout: 60_000 });
+      // Inject the WCAG 1.4.12 mandatory spacing values
+      await sub.addStyleTag({
+        content: `
+          * {
+            line-height: 1.5 !important;
+            letter-spacing: 0.12em !important;
+            word-spacing: 0.16em !important;
+          }
+          p { margin-bottom: 2em !important; }
+        `,
+      });
+      await sub.waitForTimeout(400);
+      const clipped = await sub.evaluate(() => {
+        // Skip visually-hidden (sr-only) patterns — they're intentionally
+        // clipped and WCAG-approved for skip links.
+        function isVisuallyHidden(el, cs) {
+          const r = el.getBoundingClientRect();
+          if (r.width <= 2 && r.height <= 2) return true;
+          if (cs.clip && cs.clip !== "auto" && cs.clip !== "unset") return true;
+          if (cs.clipPath && cs.clipPath !== "none" && cs.clipPath.includes("inset(100%)")) return true;
+          const classes = el.className || "";
+          if (typeof classes === "string" && /\b(sr-only|visually-hidden|screen-reader|a11y-hidden)\b/.test(classes)) {
+            return true;
+          }
+          return false;
+        }
+        const out = [];
+        document.querySelectorAll("body *").forEach((el) => {
+          const cs = getComputedStyle(el);
+          if (isVisuallyHidden(el, cs)) return;
+          if (
+            (cs.overflow === "hidden" || cs.overflowY === "hidden") &&
+            el.scrollHeight > el.clientHeight + 4 &&
+            (el.innerText || "").trim().length > 10
+          ) {
+            const cls = (el.className && typeof el.className === "string") ? el.className.split(/\s+/).filter(Boolean).slice(0, 2).join(".") : "";
+            out.push({
+              tag: el.tagName.toLowerCase(),
+              id: el.id || "",
+              cls,
+              text: (el.innerText || "").trim().slice(0, 60),
+            });
+          }
+        });
+        return out.slice(0, 15);
+      });
+      const informative = clipped.filter((e) => e.id || e.cls);
+      if (informative.length) {
+        const buf = await sub.screenshot({ fullPage: false, type: "png" });
+        const screenshotFile = await saveScreenshot(buf, ctx.screenshotsDir, "text_spacing");
+        const sel = informative.slice(0, 5).map((e) => e.id ? `#${e.id}` : `${e.tag}.${e.cls}`).join(", ");
+        findings.push({
+          source: "playwright",
+          ruleId: "viewport/text-spacing",
+          criteria: "1.4.12",
+          level: "AA",
+          impact: "serious",
+          description: `${informative.length} element(s) clip their content when WCAG-required text-spacing values are applied (line-height 1.5, letter-spacing 0.12em, word-spacing 0.16em, paragraph spacing 2x).`,
+          help: "Remove fixed heights on text containers and avoid overflow:hidden on text. Allow text containers to grow with content.",
+          helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html",
+          selector: sel,
+          evidence: JSON.stringify(informative.slice(0, 10), null, 2),
+          failureSummary: `${informative.length} clipped containers under WCAG spacing`,
+          screenshotFile,
+        });
+      }
+    } finally {
+      await sub.close().catch(() => {});
+    }
+  }
+
+  return { findings };
+}

package/src/cli.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// CLI entry. Hosts multiple subcommands:
+//   wcag-audit init           — interactive setup (~/.wcagauditrc)
+//   wcag-audit scan           — audit current project (uses discovery)
+//   wcag-audit audit <url>    — legacy single-URL mode (back-compat)
+//   wcag-audit config         — view current config
+
+import { Command } from "commander";
+import { runInit } from "./commands/init.js";
+import { runScan } from "./commands/scan.js";
+import { runCi, FAIL_ON_LEVELS } from "./commands/ci.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runWatch } from "./commands/watch.js";
+import { readGlobalConfig } from "./config/global.js";
+import { runAudit } from "./audit.js";
+
+const program = new Command();
+
+program
+  .name("wcag-audit")
+  .description("WCAG 2.1/2.2 auditor for web projects — with AI-ready fixes for Cursor / Claude Code / Windsurf.")
+  .version("1.0.0-alpha.11");
+
+// ── init ─────────────────────────────────────────────────────────
+program
+  .command("init")
+  .description("Interactive setup — saves license key + optional AI config to ~/.wcagauditrc")
+  .action(async () => {
+    const result = await runInit();
+    if (!result.ok) process.exit(1);
+  });
+
+// ── scan ─────────────────────────────────────────────────────────
+program
+  .command("scan")
+  .description("Audit every route in the current project")
+  .option("--dry-run", "Preview credit cost only; do not actually scan", false)
+  .option("--no-ai", "Skip AI vision review", false)
+  .option("--no-cache", "Ignore cached results from previous scans and re-audit every route", false)
+  .option("--url <url>", "Scan a deployed site via BFS crawl instead of local project")
+  .option("--routes <file>", "Load routes from a plain text file (one per line)")
+  .option("--crawl-depth <n>", "Max BFS depth when using --url", "2")
+  .action(async (opts) => {
+    const result = await runScan({
+      dryRun: !!opts.dryRun,
+      noAi: !opts.ai,
+      noCache: !opts.cache,
+      urlMode: opts.url || null,
+      routesFile: opts.routes || null,
+      crawlDepth: parseInt(opts.crawlDepth, 10) || 2,
+    });
+    if (!result.ok) {
+      console.error(`\n✗ ${result.error}`);
+      process.exit(1);
+    }
+  });
+
+// ── config ───────────────────────────────────────────────────────
+program
+  .command("config")
+  .description("Show current global config (~/.wcagauditrc)")
+  .action(async () => {
+    const cfg = await readGlobalConfig();
+    const redacted = {
+      ...cfg,
+      licenseKey: cfg.licenseKey ? maskKey(cfg.licenseKey) : null,
+      ai: {
+        ...cfg.ai,
+        apiKey: cfg.ai?.apiKey ? "***" : null,
+      },
+    };
+    console.log(JSON.stringify(redacted, null, 2));
+  });
+
+// ── watch ────────────────────────────────────────────────────────
+program
+  .command("watch")
+  .description("Watch source files and rescan on every change (debounced 2s).")
+  .option("--debounce <ms>", "Debounce interval between rescans", "2000")
+  .action(async (opts) => {
+    const result = await runWatch({
+      debounceMs: parseInt(opts.debounce, 10) || 2000,
+    });
+    if (!result.ok) process.exit(1);
+  });
+
+// ── ci ───────────────────────────────────────────────────────────
+program
+  .command("ci")
+  .description("CI-optimized scan. Exit 1 when findings meet the --fail-on threshold.")
+  .option(
+    `--fail-on <level>`,
+    `Fail when an issue of this impact or higher is found. One of: ${FAIL_ON_LEVELS.join(", ")}`,
+    "critical",
+  )
+  .action(async (opts) => {
+    const result = await runCi({ failOn: opts.failOn });
+    process.exit(result.exitCode || 0);
+  });
+
+// ── doctor ───────────────────────────────────────────────────────
+program
+  .command("doctor")
+  .description("Diagnose common setup issues (license, AI key, framework, dev script).")
+  .action(async () => {
+    const result = await runDoctor();
+    if (!result.ok) process.exit(1);
+  });
+
+// ── audit (legacy) ───────────────────────────────────────────────
+program
+  .command("audit")
+  .description("Single-URL audit (legacy). Prefer `scan` for local projects.")
+  .argument("<url>", "URL of the page (or starting page) to audit")
+  .option("--version-wcag <v>", "WCAG version: 2.1 or 2.2", "2.2")
+  .option("--levels <levels>", "Comma list of conformance levels (A,AA,AAA)", "A,AA")
+  .option("--out <path>", "Output xlsx path", "./wcag-report.xlsx")
+  .option("--screenshots-dir <path>", "Where to save annotated PNGs", "./wcag-screenshots")
+  .option("--max-pages <n>", "Max pages to crawl for multi-page consistency checks", "5")
+  .option("--auth-storage <path>", "Path to a Playwright storageState.json")
+  .option("--ai", "Enable AI review for visual-judgment criteria", false)
+  .option("--ai-provider <provider>", "LLM provider: anthropic | openai | google", "anthropic")
+  .option("--ai-model <model>", "Model id")
+  .option("--ai-key <key>", "API key for the chosen provider")
+  .option("--headed", "Run Chromium with a visible window", false)
+  .option("--slow-mo <ms>", "Slow each Playwright action by N ms", "0")
+  .option("--skip <checkers>", "Comma list of checkers to skip")
+  .option("--include <checkers>", "Comma list of opt-in checkers to enable")
+  .option("--screen-reader", "Shortcut for --include screen-reader", false)
+  .action(async (url, opts) => {
+    try {
+      await runAudit({
+        url,
+        wcagVersion: opts.versionWcag,
+        levels: opts.levels.split(",").map((s) => s.trim().toUpperCase()),
+        outPath: opts.out,
+        screenshotsDir: opts.screenshotsDir,
+        maxPages: parseInt(opts.maxPages, 10),
+        authStorage: opts.authStorage || null,
+        aiEnabled: !!opts.ai,
+        aiProvider: opts.aiProvider || "anthropic",
+        aiModel:
+          opts.aiModel ||
+          ({ anthropic: "claude-sonnet-4-6", openai: "gpt-4.1-mini", google: "gemini-2.5-flash" }[opts.aiProvider || "anthropic"]),
+        aiKey:
+          opts.aiKey ||
+          process.env[{ anthropic: "ANTHROPIC_API_KEY", openai: "OPENAI_API_KEY", google: "GOOGLE_API_KEY" }[opts.aiProvider || "anthropic"]] ||
+          null,
+        headed: !!opts.headed,
+        slowMo: parseInt(opts.slowMo, 10),
+        skip: (opts.skip || "").split(",").map((s) => s.trim()).filter(Boolean),
+        include: [
+          ...((opts.include || "").split(",").map((s) => s.trim()).filter(Boolean)),
+          ...(opts.screenReader ? ["screen-reader"] : []),
+        ],
+      });
+    } catch (err) {
+      console.error("\n✗ Audit failed:", err.message);
+      if (process.env.DEBUG) console.error(err.stack);
+      process.exit(1);
+    }
+  });
+
+function maskKey(key) {
+  if (!key || key.length < 12) return "***";
+  return key.slice(0, 9) + "…" + key.slice(-4);
+}
+
+program.parseAsync(process.argv);

package/src/commands/ci.js

@@ -0,0 +1,63 @@
+import { runScan } from "./scan.js";
+
+export const FAIL_ON_LEVELS = ["critical", "serious", "moderate", "minor", "none"];
+
+// Pure function so it's easy to test in isolation. The runtime runCi
+// below wraps runScan and uses this to decide the exit code.
+export function decideCiResult({ findings, failOn }) {
+  if (!FAIL_ON_LEVELS.includes(failOn)) {
+    throw new Error(`Invalid failOn value: ${failOn}. Must be one of: ${FAIL_ON_LEVELS.join(", ")}`);
+  }
+  const counts = { critical: 0, serious: 0, moderate: 0, minor: 0 };
+  for (const f of findings) {
+    const key = FAIL_ON_LEVELS.includes(f.impact) ? f.impact : "minor";
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  let shouldFail = false;
+  if (failOn !== "none") {
+    const threshold = FAIL_ON_LEVELS.indexOf(failOn);
+    for (let i = 0; i < threshold + 1; i++) {
+      if (counts[FAIL_ON_LEVELS[i]] > 0) {
+        shouldFail = true;
+        break;
+      }
+    }
+  }
+  const total = findings.length;
+  const summary = [
+    `${total} issues found`,
+    `(${counts.critical} critical, ${counts.serious} serious, ${counts.moderate} moderate, ${counts.minor} minor)`,
+  ].join(" ");
+  return { shouldFail, exitCode: shouldFail ? 1 : 0, counts, summary };
+}
+
+// Runtime wrapper — CI-flavored runScan: no spinners, structured logs,
+// machine-readable exit code.
+export async function runCi({ cwd = process.cwd(), failOn = "critical", log = console.log } = {}) {
+  const result = await runScan({
+    cwd,
+    dryRun: false,
+    noAi: true, // CI runs should be fast + deterministic
+    noCache: false,
+    log,
+  });
+
+  if (!result.ok) {
+    return { ok: false, error: result.error, exitCode: 1 };
+  }
+
+  const decision = decideCiResult({
+    findings: result.findings || [],
+    failOn,
+  });
+
+  log("");
+  log(`[wcag-audit ci] ${decision.summary}`);
+  if (decision.shouldFail) {
+    log(`[wcag-audit ci] ❌ Failing build — impact ≥ ${failOn}`);
+  } else {
+    log(`[wcag-audit ci] ✅ Passing — no impact ≥ ${failOn}`);
+  }
+
+  return { ok: true, exitCode: decision.exitCode, ...decision };
+}

package/src/commands/ci.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import { decideCiResult, FAIL_ON_LEVELS } from "./ci.js";
+
+describe("decideCiResult", () => {
+  it("passes when there are zero findings", () => {
+    const r = decideCiResult({ findings: [], failOn: "critical" });
+    expect(r.shouldFail).toBe(false);
+    expect(r.exitCode).toBe(0);
+    expect(r.summary).toMatch(/0 issues/);
+  });
+
+  it("fails when critical findings exist and threshold is critical", () => {
+    const r = decideCiResult({
+      findings: [{ impact: "critical" }, { impact: "minor" }],
+      failOn: "critical",
+    });
+    expect(r.shouldFail).toBe(true);
+    expect(r.exitCode).toBe(1);
+    expect(r.summary).toMatch(/critical/);
+  });
+
+  it("fails when serious findings exist and threshold is serious", () => {
+    const r = decideCiResult({
+      findings: [{ impact: "serious" }],
+      failOn: "serious",
+    });
+    expect(r.shouldFail).toBe(true);
+  });
+
+  it("does NOT fail on serious findings when threshold is critical", () => {
+    const r = decideCiResult({
+      findings: [{ impact: "serious" }, { impact: "minor" }],
+      failOn: "critical",
+    });
+    expect(r.shouldFail).toBe(false);
+    expect(r.exitCode).toBe(0);
+  });
+
+  it("never fails when threshold is none", () => {
+    const r = decideCiResult({
+      findings: [{ impact: "critical" }],
+      failOn: "none",
+    });
+    expect(r.shouldFail).toBe(false);
+    expect(r.exitCode).toBe(0);
+  });
+
+  it("rejects unknown failOn value", () => {
+    expect(() => decideCiResult({ findings: [], failOn: "bogus" })).toThrow(/failOn/);
+  });
+
+  it("exposes the accepted levels for the CLI help text", () => {
+    expect(FAIL_ON_LEVELS).toEqual(["critical", "serious", "moderate", "minor", "none"]);
+  });
+});