@wcag-audit/cli 1.0.0-alpha.11

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/license/validate.js

@@ -0,0 +1,58 @@
+const LICENSE_KEY_RE = /^WCAG-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$/;
+
+const DEFAULT_API_URL = "https://wcagaudit.io/api/v1/license/validate";
+
+export function isValidLicenseFormat(key) {
+  return typeof key === "string" && LICENSE_KEY_RE.test(key);
+}
+
+export async function validateLicense(key, { machineId, source = "cli", version = "1.0.0-alpha.1", apiUrl } = {}) {
+  const normalized = (key || "").trim().toUpperCase();
+
+  if (!isValidLicenseFormat(normalized)) {
+    return {
+      valid: false,
+      tier: "free",
+      error: "Invalid license key format. Expected WCAG-XXXX-XXXX-XXXX-XXXX.",
+    };
+  }
+
+  const url = apiUrl || process.env.WCAG_LICENSE_VALIDATE_URL || DEFAULT_API_URL;
+
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        key: normalized,
+        machineId,
+        version,
+        source,
+      }),
+    });
+
+    const body = await res.json().catch(() => ({}));
+
+    if (!res.ok) {
+      return {
+        valid: false,
+        tier: body.tier || "free",
+        error: body.error || `License server returned ${res.status}`,
+      };
+    }
+
+    return {
+      valid: !!body.valid,
+      tier: body.tier || "free",
+      expiresAt: body.expiresAt || null,
+      creditsRemaining: body.creditsRemaining || null,
+      features: body.features || [],
+    };
+  } catch (err) {
+    return {
+      valid: false,
+      tier: "free",
+      error: `Network error: ${err.message}`,
+    };
+  }
+}

package/src/license/validate.test.js

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { validateLicense } from "./validate.js";
+
+describe("validateLicense", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("rejects invalid format without hitting the network", async () => {
+    const result = await validateLicense("not-a-key", { machineId: "m1" });
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/format/i);
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it("returns valid result for accepted license", async () => {
+    global.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        valid: true,
+        tier: "pro",
+        expiresAt: null,
+        creditsRemaining: { server: 153, total: 153 },
+      }),
+    });
+    const result = await validateLicense("WCAG-TEST-AAAA-BBBB-CCCC", {
+      machineId: "m1",
+    });
+    expect(result.valid).toBe(true);
+    expect(result.tier).toBe("pro");
+    expect(result.creditsRemaining.total).toBe(153);
+  });
+
+  it("returns invalid result when API rejects the key", async () => {
+    global.fetch.mockResolvedValueOnce({
+      ok: false,
+      status: 403,
+      json: async () => ({ valid: false, error: "License revoked" }),
+    });
+    const result = await validateLicense("WCAG-TEST-AAAA-BBBB-CCCC", {
+      machineId: "m1",
+    });
+    expect(result.valid).toBe(false);
+    expect(result.error).toBe("License revoked");
+  });
+
+  it("returns network-error result when fetch throws", async () => {
+    global.fetch.mockRejectedValueOnce(new Error("ECONNREFUSED"));
+    const result = await validateLicense("WCAG-TEST-AAAA-BBBB-CCCC", {
+      machineId: "m1",
+    });
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/network|econnrefused/i);
+  });
+});

package/src/output/agents-md.js

@@ -0,0 +1,58 @@
+import { readFile, writeFile } from "fs/promises";
+import { join } from "path";
+
+// Markers let us find and rewrite exactly our section without
+// disturbing hand-written content before/after.
+export const WCAG_SECTION_START = "<!-- wcag-audit:start -->";
+export const WCAG_SECTION_END = "<!-- wcag-audit:end -->";
+
+function buildSection(body) {
+  return [
+    WCAG_SECTION_START,
+    "## WCAG Accessibility Fixes",
+    "",
+    "The latest @wcag-audit/cli scan produced the fixes below.",
+    "Apply them when editing the affected files.",
+    "",
+    body.trimEnd(),
+    "",
+    WCAG_SECTION_END,
+  ].join("\n");
+}
+
+export async function upsertAgentsMd(projectDir, body) {
+  const path = join(projectDir, "AGENTS.md");
+  let current = "";
+  try {
+    current = await readFile(path, "utf8");
+  } catch {
+    // no existing file — we'll create one
+  }
+
+  const wantsRemoval = body === "";
+  const startIdx = current.indexOf(WCAG_SECTION_START);
+  const endIdx = current.indexOf(WCAG_SECTION_END);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = current.slice(0, startIdx).trimEnd();
+    const after = current.slice(endIdx + WCAG_SECTION_END.length).trimStart();
+    if (wantsRemoval) {
+      const merged = [before, after].filter(Boolean).join("\n\n").trimEnd() + "\n";
+      await writeFile(path, merged, "utf8");
+      return;
+    }
+    const merged = [before, buildSection(body), after].filter(Boolean).join("\n\n").trimEnd() + "\n";
+    await writeFile(path, merged, "utf8");
+    return;
+  }
+
+  if (wantsRemoval) {
+    // Nothing to remove — leave the file alone.
+    return;
+  }
+
+  const next = current.trim().length
+    ? current.trimEnd() + "\n\n" + buildSection(body) + "\n"
+    : buildSection(body) + "\n";
+  await writeFile(path, next, "utf8");
+}

package/src/output/agents-md.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { upsertAgentsMd, WCAG_SECTION_START, WCAG_SECTION_END } from "./agents-md.js";
+
+let dir;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "agentsmd-"));
+});
+
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe("upsertAgentsMd", () => {
+  it("creates AGENTS.md when it does not exist", async () => {
+    await upsertAgentsMd(dir, "- Issue A\n- Issue B\n");
+    const raw = await readFile(join(dir, "AGENTS.md"), "utf8");
+    expect(raw).toMatch(WCAG_SECTION_START);
+    expect(raw).toMatch(/Issue A/);
+    expect(raw).toMatch(WCAG_SECTION_END);
+  });
+
+  it("appends the WCAG section to an existing AGENTS.md", async () => {
+    await writeFile(join(dir, "AGENTS.md"), "# Project\n\nExisting content.\n", "utf8");
+    await upsertAgentsMd(dir, "- Issue X\n");
+    const raw = await readFile(join(dir, "AGENTS.md"), "utf8");
+    expect(raw).toMatch(/Existing content/);
+    expect(raw).toMatch(WCAG_SECTION_START);
+    expect(raw).toMatch(/Issue X/);
+  });
+
+  it("replaces the WCAG section in-place when it already exists", async () => {
+    await writeFile(
+      join(dir, "AGENTS.md"),
+      `# Project\n\n${WCAG_SECTION_START}\n- Old issue\n${WCAG_SECTION_END}\n\nTrailing content.`,
+      "utf8",
+    );
+    await upsertAgentsMd(dir, "- Fresh issue\n");
+    const raw = await readFile(join(dir, "AGENTS.md"), "utf8");
+    expect(raw).not.toMatch(/Old issue/);
+    expect(raw).toMatch(/Fresh issue/);
+    expect(raw).toMatch(/Trailing content/);
+    // Single occurrence of the markers
+    expect(raw.match(new RegExp(WCAG_SECTION_START, "g"))?.length).toBe(1);
+  });
+
+  it("removes the WCAG section when body is empty string", async () => {
+    await writeFile(
+      join(dir, "AGENTS.md"),
+      `# Project\n\n${WCAG_SECTION_START}\n- Old\n${WCAG_SECTION_END}\n\nDone.\n`,
+      "utf8",
+    );
+    await upsertAgentsMd(dir, "");
+    const raw = await readFile(join(dir, "AGENTS.md"), "utf8");
+    expect(raw).not.toMatch(WCAG_SECTION_START);
+    expect(raw).not.toMatch(WCAG_SECTION_END);
+    expect(raw).toMatch(/Done\./);
+  });
+});

package/src/output/cursor-rules.js

@@ -0,0 +1,57 @@
+// Renders `.cursor/rules/wcag-fixes.mdc` — Cursor's native rule format.
+// When a user edits any file under the globs, Cursor auto-attaches the
+// rule as context, so the agent "knows" about the WCAG issues in that
+// file without needing a separate prompt.
+
+export function renderCursorRules({ findings, projectName }) {
+  const frontMatter = [
+    "---",
+    "description: WCAG accessibility fixes generated by @wcag-audit/cli",
+    `globs: ${JSON.stringify(["src/app/**/*.tsx", "src/app/**/*.ts", "src/components/**/*.tsx"])}`,
+    "alwaysApply: false",
+    "---",
+    "",
+  ].join("\n");
+
+  if (!findings || findings.length === 0) {
+    return (
+      frontMatter +
+      `# WCAG Fixes (${projectName})\n\n✅ No outstanding WCAG issues found in the last scan.\n`
+    );
+  }
+
+  // Group findings by source file so the rule is contextually useful
+  // when the agent is editing one of those files.
+  const byFile = new Map();
+  for (const f of findings) {
+    const key = f.sourceFile || "(unknown)";
+    if (!byFile.has(key)) byFile.set(key, []);
+    byFile.get(key).push(f);
+  }
+
+  const lines = [
+    frontMatter,
+    `# WCAG Fixes (${projectName})`,
+    "",
+    "When editing any file listed below, apply the recommended accessibility fix.",
+    "Each item has the WCAG criterion, impact level, and specific remediation.",
+    "",
+  ];
+
+  for (const [file, items] of byFile.entries()) {
+    lines.push(`## ${file}`);
+    lines.push("");
+    for (const f of items) {
+      const criteriaList = Array.isArray(f.criteria) ? f.criteria : f.criteria ? [f.criteria] : [];
+      const crit = criteriaList.join(", ") || "?";
+      lines.push(`- **${f.description || f.ruleId}** — ${crit} (${f.level || "?"}, ${f.impact || "minor"})`);
+      if (f.help) lines.push(`  - Fix: ${f.help}`);
+      if (f.evidence) lines.push(`  - Evidence: \`${String(f.evidence).replace(/`/g, "'").slice(0, 120)}\``);
+      if (f.route) lines.push(`  - Observed on route: \`${f.route}\``);
+      if (f.helpUrl) lines.push(`  - Reference: ${f.helpUrl}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/output/cursor-rules.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import { renderCursorRules } from "./cursor-rules.js";
+
+describe("renderCursorRules", () => {
+  const findings = [
+    {
+      source: "axe",
+      ruleId: "image-alt",
+      criteria: ["1.1.1"],
+      level: "A",
+      impact: "critical",
+      description: "Images must have alternate text",
+      help: "Add an alt attribute.",
+      helpUrl: "https://example/axe/image-alt",
+      selector: "img.hero",
+      evidence: "<img src='/x.png'>",
+      route: "/",
+      sourceFile: "src/app/page.tsx",
+    },
+    {
+      source: "playwright",
+      ruleId: "kbd/focus-visible",
+      criteria: "2.4.7",
+      level: "AA",
+      impact: "serious",
+      description: "No visible focus indicator.",
+      help: "Add :focus-visible styles.",
+      helpUrl: "https://example/focus-visible",
+      selector: "button",
+      evidence: "<button/>",
+      route: "/about",
+      sourceFile: "src/app/about/page.tsx",
+    },
+  ];
+
+  it("includes Cursor MDC front-matter with globs", () => {
+    const out = renderCursorRules({ findings, projectName: "demo" });
+    expect(out).toMatch(/^---\n/);
+    expect(out).toMatch(/description: WCAG accessibility fixes/);
+    expect(out).toMatch(/globs: \["src\/app\/\*\*\/\*.tsx","src\/app\/\*\*\/\*.ts","src\/components\/\*\*\/\*.tsx"\]/);
+    expect(out).toMatch(/alwaysApply: false/);
+  });
+
+  it("returns a minimal no-issues rule when findings is empty", () => {
+    const out = renderCursorRules({ findings: [], projectName: "demo" });
+    expect(out).toMatch(/^---\n/);
+    expect(out).toMatch(/No outstanding WCAG issues found/);
+  });
+
+  it("groups findings by source file so Cursor attaches the rule contextually", () => {
+    const out = renderCursorRules({ findings, projectName: "demo" });
+    expect(out).toMatch(/src\/app\/page\.tsx/);
+    expect(out).toMatch(/src\/app\/about\/page\.tsx/);
+    expect(out.indexOf("src/app/page.tsx")).toBeLessThan(out.indexOf("src/app/about/page.tsx"));
+  });
+
+  it("tags each finding with its criterion + impact", () => {
+    const out = renderCursorRules({ findings, projectName: "demo" });
+    expect(out).toMatch(/1\.1\.1 \(A, critical\)/);
+    expect(out).toMatch(/2\.4\.7 \(AA, serious\)/);
+  });
+});

package/src/output/excel-project.js

@@ -0,0 +1,263 @@
+// 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";
+import { WCAG_CRITERIA, filterCriteriaForScope } from "../wcag-criteria.js";
+import { getManualGuide } from "../wcag-manual-steps.js";
+
+const IMPACT_ORDER = ["critical", "serious", "moderate", "minor"];
+
+function automationLabel(c) {
+  const hasAxe = !!c.axeRules && c.axeRules.length > 0;
+  const hasDynamic = !!c.playwrightCheckable;
+  const hasAi = !!c.aiReviewable;
+  if (c.automation === "automated") return "Automated";
+  if (hasAxe && (hasDynamic || hasAi)) return "Automated";
+  if (hasDynamic && hasAi) return "Automated";
+  if (hasAxe || hasDynamic || hasAi) return "Partial";
+  return "Manual";
+}
+
+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 ────────────────────────────────────────────
+  // Lists EVERY WCAG criterion in scope (version + levels the user
+  // requested), not just the ones with violations. For each criterion
+  // the sheet shows:
+  //   - automation status (Automated / Partial / Manual)
+  //   - what our engines verified automatically
+  //   - MANUAL STEPS a human must perform to confirm conformance
+  //   - violations found in this scan (if any)
+  //
+  // Auditors can use this sheet as the checklist for a WCAG 2.2 AA
+  // conformance statement: partial + manual rows are where humans
+  // plug the gap.
+  const cov = wb.addWorksheet("Coverage");
+  cov.columns = [
+    { header: "Criterion", key: "id", width: 11 },
+    { header: "Title", key: "title", width: 36 },
+    { header: "Level", key: "level", width: 7 },
+    { header: "Added", key: "addedIn", width: 8 },
+    { header: "Status", key: "status", width: 12 },
+    { header: "What the tool verified", key: "automated", width: 50 },
+    { header: "Manual steps to verify", key: "manual", width: 60 },
+    { header: "Violations found", key: "count", width: 14 },
+    { header: "Routes affected", key: "routes", width: 28 },
+    { header: "Reference", key: "url", width: 42 },
+  ];
+  cov.getRow(1).font = { bold: true };
+  cov.getRow(1).fill = {
+    type: "pattern",
+    pattern: "solid",
+    fgColor: { argb: "FFF1F5F9" },
+  };
+
+  // Build { criterionId -> { count, routes } } from the scan findings.
+  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, { routes: new Set(), count: 0 });
+      const entry = byCriterion.get(c);
+      entry.count++;
+      if (f.route) entry.routes.add(f.route);
+    }
+  }
+
+  // Emit one row PER criterion in scope (using the same scope the CLI
+  // used to build axe tags). This produces ~55 rows for WCAG 2.2 A+AA,
+  // versus the old behaviour of only emitting violated criteria.
+  const scoped = filterCriteriaForScope(meta.wcagVersion || "2.2", meta.levels || ["A", "AA"]);
+  const sortedScoped = [...scoped].sort((a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }));
+  for (const c of sortedScoped) {
+    const guide = getManualGuide(c.id);
+    const entry = byCriterion.get(c.id) || { routes: new Set(), count: 0 };
+    cov.addRow({
+      id: c.id,
+      title: c.title,
+      level: c.level,
+      addedIn: c.addedIn,
+      status: automationLabel(c),
+      automated: guide.automated || "",
+      manual: guide.manualSteps || "",
+      count: entry.count,
+      routes: [...entry.routes].sort().join(", "),
+      url: `https://www.w3.org/WAI/WCAG22/Understanding/${c.id.replace(/\./g, "-")}`,
+    });
+  }
+
+  // Color-code the Status column so Manual/Partial stand out.
+  cov.eachRow({ includeEmpty: false }, (row, rowNum) => {
+    if (rowNum === 1) return;
+    const status = String(row.getCell("status").value || "");
+    let fill = null;
+    if (status === "Automated") fill = { type: "pattern", pattern: "solid", fgColor: { argb: "FFDCFCE7" } };
+    else if (status === "Partial") fill = { type: "pattern", pattern: "solid", fgColor: { argb: "FFFEF3C7" } };
+    else if (status === "Manual") fill = { type: "pattern", pattern: "solid", fgColor: { argb: "FFE5E5E5" } };
+    if (fill) row.getCell("status").fill = fill;
+    // Wrap long text columns
+    row.getCell("title").alignment = { wrapText: true, vertical: "top" };
+    row.getCell("automated").alignment = { wrapText: true, vertical: "top" };
+    row.getCell("manual").alignment = { wrapText: true, vertical: "top" };
+  });
+  cov.views = [{ state: "frozen", ySplit: 1 }];
+  cov.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: cov.columns.length } };
+
+  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);
+  }
+}