@wcag-audit/cli 1.0.0-alpha.5 → 1.0.0-alpha.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wcag-audit/cli",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.8",
   "description": "Project-aware WCAG 2.1/2.2 auditor with AI-ready fix prompts for vibe-coding tools (Cursor, Claude Code, Windsurf).",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -10,6 +10,7 @@ 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";
 
@@ -18,7 +19,7 @@ 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.5");
+  .version("1.0.0-alpha.8");
 
 // ── init ─────────────────────────────────────────────────────────
 program
@@ -71,6 +72,18 @@ program
     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")

package/src/commands/doctor.js

@@ -5,7 +5,7 @@ import { readGlobalConfig } from "../config/global.js";
 import { validateLicense } from "../license/validate.js";
 import { detectFramework } from "../discovery/registry.js";
 
-const CLI_VERSION = "1.0.0-alpha.5";
+const CLI_VERSION = "1.0.0-alpha.8";
 
 export async function runDoctor({ cwd = process.cwd(), log = console.log } = {}) {
   const checks = [];

package/src/commands/init.js

@@ -1,9 +1,10 @@
 import enquirer from "enquirer";
 import { randomUUID } from "crypto";
 import { validateLicense } from "../license/validate.js";
+import { requestFreeLicense } from "../license/request-free.js";
 import { writeGlobalConfig } from "../config/global.js";
 
-const CLI_VERSION = "1.0.0-alpha.5";
+const CLI_VERSION = "1.0.0-alpha.8";
 
 // runInit can be called two ways:
 //   1. Interactive (no answers) — uses enquirer to prompt
@@ -13,7 +14,7 @@ export async function runInit({ answers, log = console.log } = {}) {
   log("Welcome to WCAG Audit CLI");
   log("");
 
-  const resolved = answers || (await promptUser());
+  const resolved = answers || (await promptUser({ log }));
 
   // 1. Validate license
   const machineId = randomUUID();
@@ -68,7 +69,42 @@ function defaultModelFor(provider) {
   }[provider] || "claude-sonnet-4-6";
 }
 
-async function promptUser() {
+async function promptUser({ log = console.log } = {}) {
+  // Step 1: Has a key? Or request free?
+  const { hasKey } = await enquirer.prompt([
+    {
+      type: "confirm",
+      name: "hasKey",
+      message: "Do you already have a license key?",
+      initial: true,
+    },
+  ]);
+
+  if (!hasKey) {
+    // Free-tier flow: ask for email, request a free key, wait for them
+    // to paste it from their inbox.
+    const { email } = await enquirer.prompt([
+      {
+        type: "input",
+        name: "email",
+        message: "Enter your email for a free license (1 audit/day):",
+        validate: (v) => (/@.+\./.test(v) ? true : "Enter a valid email"),
+      },
+    ]);
+    log("");
+    log(`Requesting free license for ${email}...`);
+    const machineId = randomUUID();
+    const result = await requestFreeLicense({ email, machineId });
+    if (!result.ok) {
+      log(`✗ ${result.error}`);
+      log("  You can try again or skip and use --help to paste a key later.");
+      throw new Error(result.error);
+    }
+    log(`✓ ${result.message}`);
+    log("");
+  }
+
+  // Step 2: Paste the key (works for both free and paid)
   const answers = await enquirer.prompt([
     {
       type: "input",

package/src/commands/scan.js

@@ -15,9 +15,10 @@ import { startDevServer, detectDevCommand } from "../devserver/spawn.js";
 import { renderFindingsMarkdown } from "../output/markdown.js";
 import { renderCursorRules } from "../output/cursor-rules.js";
 import { upsertAgentsMd } from "../output/agents-md.js";
+import { writeProjectReport } from "../output/excel-project.js";
 import { hashContent, readCacheEntry, writeCacheEntry } from "../cache/route-cache.js";
 
-const CLI_VERSION = "1.0.0-alpha.5";
+const CLI_VERSION = "1.0.0-alpha.8";
 
 export async function runScan({
   cwd = process.cwd(),
@@ -240,6 +241,31 @@ export async function runScan({
     log(`✓ WCAG_FIXES.md (${allFindings.length} findings)`);
   }
 
+  if (outputs.has("json")) {
+    // Structured JSON output for programmatic consumers (custom
+    // dashboards, CI integrations, historical trend tracking).
+    const json = {
+      generator: `@wcag-audit/cli v${CLI_VERSION}`,
+      generatedAt: new Date().toISOString(),
+      projectName,
+      framework,
+      strategy,
+      wcagVersion: globalCfg.defaults.wcagVersion,
+      levels: globalCfg.defaults.conformanceLevel,
+      totalPages: routes.length,
+      newPagesCount,
+      cachedPagesCount,
+      totalIssues: allFindings.length,
+      findings: allFindings,
+    };
+    await writeFile(
+      resolve(cwd, "wcag-report.json"),
+      JSON.stringify(json, null, 2),
+      "utf8",
+    );
+    log(`✓ wcag-report.json`);
+  }
+
   if (outputs.has("cursor-rules")) {
     const mdc = renderCursorRules({ projectName, findings: allFindings });
     const dir = resolve(cwd, ".cursor/rules");
@@ -276,11 +302,23 @@ export async function runScan({
     log(`✓ AGENTS.md WCAG section updated`);
   }
 
-  // Note: multi-page Excel is not yet supported. report.js is
-  // per-page only (expects meta.url, meta.startedAt, meta.scopeCriteria).
-  // Phase 1 ships markdown only; aggregate Excel comes in a later phase.
   if (outputs.has("excel")) {
-    log("! Excel output skipped in Phase 1 — use `wcag-audit audit <url>` for per-page Excel.");
+    await writeProjectReport({
+      findings: allFindings,
+      meta: {
+        projectName,
+        generator: `@wcag-audit/cli v${CLI_VERSION}`,
+        framework,
+        strategy,
+        wcagVersion: globalCfg.defaults.wcagVersion,
+        levels: globalCfg.defaults.conformanceLevel,
+        totalPages: routes.length,
+        newPagesCount,
+        cachedPagesCount,
+      },
+      outPath: resolve(cwd, "wcag-report.xlsx"),
+    });
+    log(`✓ wcag-report.xlsx`);
   }
 
   // 9. Log usage for billing

package/src/commands/watch.js

@@ -0,0 +1,89 @@
+import { watch } from "fs";
+import { join } from "path";
+import { runScan } from "./scan.js";
+
+// Watch mode: rescan every time a source file changes. Debounced so a
+// burst of saves (prettier-on-save, hot reload) only triggers one scan.
+//
+// The watcher only fires on changes to /src, /app, /pages, /components
+// — not node_modules or .next. Ignores .wcag-audit/cache so cache
+// writes don't re-trigger scans.
+export async function runWatch({
+  cwd = process.cwd(),
+  debounceMs = 2000,
+  log = console.log,
+} = {}) {
+  const watchDirs = ["src", "app", "pages", "components"]
+    .map((d) => join(cwd, d));
+
+  log("");
+  log("wcag-audit watch — rescanning on source changes");
+  log(`Watched dirs: ${watchDirs.map((d) => d.replace(cwd + "/", "")).join(", ")}`);
+  log("Press Ctrl+C to stop.");
+  log("");
+
+  // Run once on startup so the first report lands before any edits.
+  await runScan({ cwd, log });
+
+  let pending = null;
+  let running = false;
+  let needsRerun = false;
+
+  const trigger = (reason) => {
+    if (pending) clearTimeout(pending);
+    pending = setTimeout(async () => {
+      pending = null;
+      if (running) {
+        needsRerun = true;
+        return;
+      }
+      running = true;
+      log("");
+      log(`─── change detected (${reason}) — rescanning ───`);
+      try {
+        await runScan({ cwd, log });
+      } catch (err) {
+        log(`✗ Scan failed: ${err.message}`);
+      }
+      running = false;
+      if (needsRerun) {
+        needsRerun = false;
+        trigger("queued changes");
+      }
+    }, debounceMs);
+  };
+
+  const watchers = [];
+  for (const dir of watchDirs) {
+    try {
+      const w = watch(dir, { recursive: true }, (_event, filename) => {
+        if (!filename) return;
+        // Ignore cache writes so our own output doesn't loop
+        if (filename.startsWith(".wcag-audit")) return;
+        if (filename.includes("node_modules")) return;
+        trigger(filename);
+      });
+      watchers.push(w);
+    } catch {
+      // Directory doesn't exist — skip silently
+    }
+  }
+
+  if (watchers.length === 0) {
+    log("! No source directories found to watch. Tried: " + watchDirs.join(", "));
+    return { ok: false, error: "No source directories to watch" };
+  }
+
+  // Keep the process alive until SIGINT
+  return new Promise((resolve) => {
+    const cleanup = () => {
+      for (const w of watchers) w.close();
+      if (pending) clearTimeout(pending);
+      log("");
+      log("Watcher stopped.");
+      resolve({ ok: true });
+    };
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+  });
+}

package/src/config/project.js

@@ -5,8 +5,8 @@ export const DEFAULT_PROJECT_CONFIG = {
   routes: "auto",
   excludePaths: [],
   failOn: "critical",
-  // Valid values: "excel" (deferred to later phase), "markdown",
-  // "cursor-rules", "agents-md". Unknown values are ignored.
+  // Valid values: "excel" (deferred), "markdown", "cursor-rules",
+  // "agents-md", "json". Unknown values are ignored.
   outputs: ["excel", "markdown"],
   dynamicRouteSamples: {},
   devServer: {

package/src/license/request-free.js

@@ -0,0 +1,46 @@
+// Free-tier license request. POSTs to /v1/license/free which creates a
+// User + License row (tier: "free") and emails the key to the user.
+// The key is NEVER returned in the response body — it's mailed out,
+// so users have to paste it from their inbox. This matches the
+// Chrome extension free-tier flow.
+
+const DEFAULT_API_URL = "https://wcagaudit.io/api/v1/license/free";
+
+export async function requestFreeLicense({ email, machineId, apiUrl } = {}) {
+  const url = apiUrl || process.env.WCAG_LICENSE_FREE_URL || DEFAULT_API_URL;
+
+  const trimmedEmail = (email || "").trim();
+  if (!trimmedEmail || !trimmedEmail.includes("@")) {
+    return {
+      ok: false,
+      error: "A valid email address is required",
+    };
+  }
+
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ email: trimmedEmail, machineId }),
+    });
+
+    const body = await res.json().catch(() => ({}));
+
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: body.error || `Free license request failed (HTTP ${res.status})`,
+      };
+    }
+
+    return {
+      ok: true,
+      message: body.message || "Check your email for your free license key",
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `Network error: ${err.message}`,
+    };
+  }
+}

package/src/license/request-free.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { requestFreeLicense } from "./request-free.js";
+
+describe("requestFreeLicense", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("rejects invalid email without hitting the network", async () => {
+    const result = await requestFreeLicense({ email: "not-an-email", machineId: "m1" });
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/email/i);
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it("rejects empty email", async () => {
+    const result = await requestFreeLicense({ email: "", machineId: "m1" });
+    expect(result.ok).toBe(false);
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it("returns ok when API returns 200", async () => {
+    global.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ ok: true, message: "Check your email for your free license key" }),
+    });
+    const result = await requestFreeLicense({ email: "sai@example.com", machineId: "m1" });
+    expect(result.ok).toBe(true);
+    expect(result.message).toMatch(/email/i);
+    const [url, init] = global.fetch.mock.calls[0];
+    expect(url).toMatch(/\/v1\/license\/free$/);
+    const body = JSON.parse(init.body);
+    expect(body.email).toBe("sai@example.com");
+    expect(body.machineId).toBe("m1");
+  });
+
+  it("returns error on non-2xx", async () => {
+    global.fetch.mockResolvedValueOnce({
+      ok: false,
+      status: 429,
+      json: async () => ({ error: "Rate limit exceeded" }),
+    });
+    const result = await requestFreeLicense({ email: "sai@example.com", machineId: "m1" });
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/rate limit/i);
+  });
+
+  it("returns error when fetch throws", async () => {
+    global.fetch.mockRejectedValueOnce(new Error("ECONNREFUSED"));
+    const result = await requestFreeLicense({ email: "sai@example.com", machineId: "m1" });
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/network/i);
+  });
+});

package/src/output/excel-project.js

@@ -0,0 +1,212 @@
+// Multi-page (project-wide) Excel report writer.
+//
+// Unlike src/report.js (which writes one Excel per page audit with
+// embedded screenshots), this writer aggregates findings across all
+// routes into three sheets: Summary, Issues, Coverage.
+//
+// No embedded screenshots — a 50-route project would produce a 500MB+
+// file. The markdown output already has the text evidence, and users
+// can run `wcag-audit audit <url>` for a single-page Excel with
+// screenshots if they need them.
+
+import ExcelJS from "exceljs";
+
+const IMPACT_ORDER = ["critical", "serious", "moderate", "minor"];
+
+export async function writeProjectReport({
+  findings,
+  meta,
+  outPath,
+}) {
+  const wb = new ExcelJS.Workbook();
+  wb.creator = meta.generator || "@wcag-audit/cli";
+  wb.created = new Date();
+
+  // ── Summary sheet ─────────────────────────────────────────────
+  const sum = wb.addWorksheet("Summary");
+  sum.columns = [
+    { header: "", key: "k", width: 28 },
+    { header: "", key: "v", width: 60 },
+  ];
+
+  const impactCounts = countByImpact(findings);
+
+  const rows = [
+    ["WCAG Audit — Project Report"],
+    [],
+    ["Project", meta.projectName],
+    ["Generator", meta.generator],
+    ["Generated", new Date().toISOString()],
+    [],
+    ["Framework", meta.framework || "—"],
+    ["Strategy", meta.strategy || "—"],
+    ["WCAG version", meta.wcagVersion],
+    ["Levels", (meta.levels || []).join(", ")],
+    [],
+    ["Total pages audited", String(meta.totalPages)],
+    ["Pages with new audits", String(meta.newPagesCount ?? meta.totalPages)],
+    ["Pages served from cache", String(meta.cachedPagesCount ?? 0)],
+    [],
+    ["Total issues", String(findings.length)],
+    ["  Critical", String(impactCounts.critical)],
+    ["  Serious", String(impactCounts.serious)],
+    ["  Moderate", String(impactCounts.moderate)],
+    ["  Minor", String(impactCounts.minor)],
+  ];
+  rows.forEach((r) => sum.addRow(r));
+  sum.getRow(1).font = { bold: true, size: 14, color: { argb: "FF0969DA" } };
+
+  // ── Issues sheet ──────────────────────────────────────────────
+  const issues = wb.addWorksheet("Issues");
+  issues.columns = [
+    { header: "Route", key: "route", width: 28 },
+    { header: "File", key: "sourceFile", width: 38 },
+    { header: "Criterion", key: "criteria", width: 14 },
+    { header: "Level", key: "level", width: 8 },
+    { header: "Impact", key: "impact", width: 12 },
+    { header: "Rule", key: "ruleId", width: 24 },
+    { header: "Description", key: "description", width: 50 },
+    { header: "Fix", key: "help", width: 50 },
+    { header: "Detected by", key: "source", width: 14 },
+    { header: "Selector", key: "selector", width: 30 },
+    { header: "Evidence", key: "evidence", width: 40 },
+    { header: "Reference", key: "helpUrl", width: 40 },
+  ];
+  issues.getRow(1).font = { bold: true };
+  issues.getRow(1).fill = {
+    type: "pattern",
+    pattern: "solid",
+    fgColor: { argb: "FFF1F5F9" },
+  };
+
+  // Sort by impact desc, then by route, so critical issues surface first
+  const sorted = [...findings].sort((a, b) => {
+    const ai = IMPACT_ORDER.indexOf(a.impact);
+    const bi = IMPACT_ORDER.indexOf(b.impact);
+    const aImp = ai === -1 ? 4 : ai;
+    const bImp = bi === -1 ? 4 : bi;
+    if (aImp !== bImp) return aImp - bImp;
+    return String(a.route || "").localeCompare(String(b.route || ""));
+  });
+
+  for (const f of sorted) {
+    const criteria = Array.isArray(f.criteria) ? f.criteria.join(", ") : f.criteria || "";
+    issues.addRow({
+      route: f.route || "",
+      sourceFile: f.sourceFile || "",
+      criteria,
+      level: f.level || "",
+      impact: f.impact || "",
+      ruleId: f.ruleId || "",
+      description: truncate(f.description, 400),
+      help: truncate(f.help, 400),
+      source: f.source || "",
+      selector: truncate(f.selector, 200),
+      evidence: truncate(asText(f.evidence), 400),
+      helpUrl: f.helpUrl || "",
+    });
+  }
+
+  // Color-code impact column
+  issues.eachRow({ includeEmpty: false }, (row, rowNum) => {
+    if (rowNum === 1) return;
+    const impact = row.getCell("impact").value;
+    const fill = impactFill(impact);
+    if (fill) row.getCell("impact").fill = fill;
+  });
+
+  // Freeze header row
+  issues.views = [{ state: "frozen", ySplit: 1 }];
+  // Enable autofilter
+  issues.autoFilter = {
+    from: { row: 1, column: 1 },
+    to: { row: 1, column: issues.columns.length },
+  };
+
+  // ── Coverage sheet ────────────────────────────────────────────
+  // Groups findings by criterion so compliance auditors can see
+  // which criteria were violated and how many times.
+  const cov = wb.addWorksheet("Coverage");
+  cov.columns = [
+    { header: "Criterion", key: "id", width: 14 },
+    { header: "Level", key: "level", width: 8 },
+    { header: "Violations", key: "count", width: 12 },
+    { header: "Routes affected", key: "routes", width: 28 },
+    { header: "Rules triggered", key: "rules", width: 40 },
+  ];
+  cov.getRow(1).font = { bold: true };
+  cov.getRow(1).fill = {
+    type: "pattern",
+    pattern: "solid",
+    fgColor: { argb: "FFF1F5F9" },
+  };
+
+  const byCriterion = new Map();
+  for (const f of findings) {
+    const critList = Array.isArray(f.criteria) ? f.criteria : f.criteria ? [f.criteria] : ["?"];
+    for (const c of critList) {
+      if (!byCriterion.has(c)) {
+        byCriterion.set(c, { level: f.level || "", routes: new Set(), rules: new Set(), count: 0 });
+      }
+      const entry = byCriterion.get(c);
+      entry.count++;
+      if (f.route) entry.routes.add(f.route);
+      if (f.ruleId) entry.rules.add(f.ruleId);
+    }
+  }
+
+  const sortedCriteria = [...byCriterion.entries()].sort(([a], [b]) => a.localeCompare(b, undefined, { numeric: true }));
+  for (const [id, e] of sortedCriteria) {
+    cov.addRow({
+      id,
+      level: e.level,
+      count: e.count,
+      routes: [...e.routes].sort().join(", "),
+      rules: [...e.rules].sort().join(", "),
+    });
+  }
+
+  cov.views = [{ state: "frozen", ySplit: 1 }];
+
+  await wb.xlsx.writeFile(outPath);
+}
+
+function countByImpact(findings) {
+  const counts = { critical: 0, serious: 0, moderate: 0, minor: 0 };
+  for (const f of findings) {
+    const key = IMPACT_ORDER.includes(f.impact) ? f.impact : "minor";
+    counts[key]++;
+  }
+  return counts;
+}
+
+function impactFill(impact) {
+  switch (impact) {
+    case "critical":
+      return { type: "pattern", pattern: "solid", fgColor: { argb: "FFFEE2E2" } };
+    case "serious":
+      return { type: "pattern", pattern: "solid", fgColor: { argb: "FFFFE4CC" } };
+    case "moderate":
+      return { type: "pattern", pattern: "solid", fgColor: { argb: "FFFEF3C7" } };
+    case "minor":
+      return { type: "pattern", pattern: "solid", fgColor: { argb: "FFE0E7FF" } };
+    default:
+      return null;
+  }
+}
+
+function truncate(value, max) {
+  const s = asText(value);
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1) + "…";
+}
+
+function asText(value) {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/output/excel-project.test.js

@@ -0,0 +1,140 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import ExcelJS from "exceljs";
+import { writeProjectReport } from "./excel-project.js";
+
+let dir;
+beforeEach(async () => { dir = await mkdtemp(join(tmpdir(), "excel-")); });
+afterEach(async () => { await rm(dir, { recursive: true, force: true }); });
+
+async function loadWorkbook(path) {
+  const wb = new ExcelJS.Workbook();
+  await wb.xlsx.readFile(path);
+  return wb;
+}
+
+const sampleMeta = {
+  projectName: "my-nextjs-app",
+  generator: "@wcag-audit/cli v1.0.0-alpha.8",
+  framework: "nextjs-app",
+  strategy: "source-walk",
+  wcagVersion: "2.2",
+  levels: ["A", "AA"],
+  totalPages: 3,
+  newPagesCount: 3,
+  cachedPagesCount: 0,
+};
+
+const sampleFindings = [
+  {
+    source: "axe", ruleId: "image-alt", criteria: ["1.1.1"], level: "A",
+    impact: "critical", description: "Images must have alt text",
+    help: "Add an alt attribute", helpUrl: "https://example/1",
+    selector: "img.hero", evidence: "<img>", route: "/", sourceFile: "app/page.tsx",
+  },
+  {
+    source: "playwright", ruleId: "kbd/focus", criteria: "2.4.7", level: "AA",
+    impact: "serious", description: "Focus indicator missing",
+    help: "Add :focus-visible", helpUrl: "https://example/2",
+    selector: "button", evidence: "<button>", route: "/about", sourceFile: "app/about/page.tsx",
+  },
+  {
+    source: "axe", ruleId: "color-contrast", criteria: "1.4.3", level: "AA",
+    impact: "minor", description: "Low contrast",
+    help: "Increase contrast", helpUrl: "https://example/3",
+    selector: ".muted", evidence: "rgb(150,150,150) on rgb(200,200,200)",
+    route: "/pricing", sourceFile: "app/pricing/page.tsx",
+  },
+];
+
+describe("writeProjectReport", () => {
+  it("creates a workbook with 3 sheets: Summary, Issues, Coverage", async () => {
+    const outPath = join(dir, "report.xlsx");
+    await writeProjectReport({ findings: sampleFindings, meta: sampleMeta, outPath });
+    const wb = await loadWorkbook(outPath);
+    const names = wb.worksheets.map((ws) => ws.name);
+    expect(names).toEqual(["Summary", "Issues", "Coverage"]);
+  });
+
+  it("Summary sheet includes project metadata + impact counts", async () => {
+    const outPath = join(dir, "report.xlsx");
+    await writeProjectReport({ findings: sampleFindings, meta: sampleMeta, outPath });
+    const wb = await loadWorkbook(outPath);
+    const sum = wb.getWorksheet("Summary");
+    const cells = [];
+    sum.eachRow((row) => row.eachCell((c) => cells.push(String(c.value ?? ""))));
+    const joined = cells.join(" | ");
+    expect(joined).toContain("my-nextjs-app");
+    expect(joined).toContain("nextjs-app");
+    expect(joined).toContain("source-walk");
+    expect(joined).toContain("2.2");
+    // Impact counts: 1 critical, 1 serious, 0 moderate, 1 minor
+    expect(joined).toMatch(/Critical.*1/);
+    expect(joined).toMatch(/Serious.*1/);
+    expect(joined).toMatch(/Minor.*1/);
+  });
+
+  it("Issues sheet has one row per finding (+ header)", async () => {
+    const outPath = join(dir, "report.xlsx");
+    await writeProjectReport({ findings: sampleFindings, meta: sampleMeta, outPath });
+    const wb = await loadWorkbook(outPath);
+    const issues = wb.getWorksheet("Issues");
+    // 1 header row + 3 findings
+    expect(issues.rowCount).toBe(4);
+  });
+
+  it("Issues sheet sorts by impact severity (critical first)", async () => {
+    const outPath = join(dir, "report.xlsx");
+    await writeProjectReport({ findings: sampleFindings, meta: sampleMeta, outPath });
+    const wb = await loadWorkbook(outPath);
+    const issues = wb.getWorksheet("Issues");
+    // Columns: 1=route, 2=sourceFile, 3=criteria, 4=level, 5=impact
+    // Row 2 (first data row) should be critical
+    expect(String(issues.getRow(2).getCell(5).value)).toBe("critical");
+    expect(String(issues.getRow(3).getCell(5).value)).toBe("serious");
+    expect(String(issues.getRow(4).getCell(5).value)).toBe("minor");
+  });
+
+  it("Coverage sheet groups findings by criterion", async () => {
+    const outPath = join(dir, "report.xlsx");
+    await writeProjectReport({ findings: sampleFindings, meta: sampleMeta, outPath });
+    const wb = await loadWorkbook(outPath);
+    const cov = wb.getWorksheet("Coverage");
+    // 1 header + 3 criteria (1.1.1, 1.4.3, 2.4.7)
+    expect(cov.rowCount).toBe(4);
+    const ids = [];
+    cov.eachRow((row, i) => {
+      if (i === 1) return;
+      // Columns: 1=id, 2=level, 3=count
+      ids.push(String(row.getCell(1).value));
+    });
+    expect(ids.sort()).toEqual(["1.1.1", "1.4.3", "2.4.7"]);
+  });
+
+  it("handles zero findings", async () => {
+    const outPath = join(dir, "report.xlsx");
+    await writeProjectReport({ findings: [], meta: sampleMeta, outPath });
+    const wb = await loadWorkbook(outPath);
+    const issues = wb.getWorksheet("Issues");
+    // Just the header row
+    expect(issues.rowCount).toBe(1);
+    const cov = wb.getWorksheet("Coverage");
+    expect(cov.rowCount).toBe(1);
+  });
+
+  it("handles criteria as string or array", async () => {
+    const outPath = join(dir, "report.xlsx");
+    const mixed = [
+      { impact: "critical", criteria: ["1.1.1", "4.1.2"], ruleId: "a", route: "/" },
+      { impact: "minor", criteria: "2.4.3", ruleId: "b", route: "/x" },
+    ];
+    await writeProjectReport({ findings: mixed, meta: sampleMeta, outPath });
+    const wb = await loadWorkbook(outPath);
+    const issues = wb.getWorksheet("Issues");
+    // Column 3 = criteria. Impact sort: critical first, then minor.
+    expect(String(issues.getRow(2).getCell(3).value)).toBe("1.1.1, 4.1.2");
+    expect(String(issues.getRow(3).getCell(3).value)).toBe("2.4.3");
+  });
+});