@wcag-audit/cli 1.0.0-alpha.11

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

@@ -0,0 +1,165 @@
+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 lists every scoped criterion and marks violated ones", async () => {
+    const outPath = join(dir, "report.xlsx");
+    await writeProjectReport({ findings: sampleFindings, meta: sampleMeta, outPath });
+    const wb = await loadWorkbook(outPath);
+    const cov = wb.getWorksheet("Coverage");
+    // WCAG 2.2 A+AA has ~55 criteria + 1 header row. Exact number can shift
+    // as W3C revises the spec, so just assert "significantly more than the
+    // number of violated criteria".
+    expect(cov.rowCount).toBeGreaterThan(40);
+    const ids = [];
+    const violatedWithCount = [];
+    cov.eachRow((row, i) => {
+      if (i === 1) return;
+      const id = String(row.getCell(1).value);
+      ids.push(id);
+      // Column 8 is violations found (after id,title,level,addedIn,status,automated,manual)
+      const count = Number(row.getCell(8).value) || 0;
+      if (count > 0) violatedWithCount.push({ id, count });
+    });
+    // The violated criteria from sampleFindings should appear with non-zero counts
+    expect(ids).toContain("1.1.1");
+    expect(ids).toContain("1.4.3");
+    expect(ids).toContain("2.4.7");
+    expect(violatedWithCount.map((v) => v.id).sort()).toEqual(["1.1.1", "1.4.3", "2.4.7"]);
+  });
+
+  it("Coverage sheet includes manual-verification steps for partial / manual criteria", async () => {
+    const outPath = join(dir, "report.xlsx");
+    await writeProjectReport({ findings: [], meta: sampleMeta, outPath });
+    const wb = await loadWorkbook(outPath);
+    const cov = wb.getWorksheet("Coverage");
+    let sawManualSteps = false;
+    cov.eachRow((row, i) => {
+      if (i === 1) return;
+      // Column 7 = manual steps
+      if (String(row.getCell(7).value || "").length > 20) sawManualSteps = true;
+    });
+    expect(sawManualSteps).toBe(true);
+  });
+
+  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");
+    // Coverage still has all scoped criteria even with zero findings
+    expect(cov.rowCount).toBeGreaterThan(40);
+  });
+
+  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");
+  });
+});

package/src/output/markdown.js

@@ -0,0 +1,119 @@
+// Renders findings as an AI-ready markdown document. The format is
+// designed for Cursor / Claude Code / Windsurf — each finding has
+// enough context (route, file, snippet, criterion, fix hint) for an
+// AI agent to open the file and apply the fix directly.
+
+const IMPACT_ORDER = ["critical", "serious", "moderate", "minor"];
+
+export function renderFindingsMarkdown({
+  projectName,
+  generator,
+  totalPages,
+  wcagVersion,
+  levels,
+  findings,
+}) {
+  const header = [
+    `# WCAG Audit Findings — ${projectName}`,
+    ``,
+    `Generated by ${generator}`,
+    `Total pages audited: ${totalPages}`,
+    `Total issues: ${findings.length}`,
+    `Criteria: WCAG ${wcagVersion} Level ${levels.join(" + ")}`,
+    ``,
+  ].join("\n");
+
+  if (findings.length === 0) {
+    return header + "\n✅ No issues found!\n";
+  }
+
+  const merged = mergeFindings(findings);
+
+  const groups = new Map(IMPACT_ORDER.map((k) => [k, []]));
+  for (const f of merged) {
+    const bucket = IMPACT_ORDER.includes(f.impact) ? f.impact : "minor";
+    groups.get(bucket).push(f);
+  }
+
+  const sections = [];
+  for (const impact of IMPACT_ORDER) {
+    const items = groups.get(impact);
+    if (!items.length) continue;
+    sections.push(
+      `## ${capitalize(impact)} Issues (${items.length})`,
+      ``,
+      ...items.map((f, i) => renderFinding(f, i + 1)),
+    );
+  }
+
+  return header + "\n" + sections.join("\n") + "\n";
+}
+
+function renderFinding(f, index) {
+  // criteria may be a string like "1.1.1" or an array ["1.1.1", "2.4.7"]
+  const criteriaList = Array.isArray(f.criteria)
+    ? f.criteria
+    : f.criteria
+    ? [f.criteria]
+    : [];
+  const criteria = criteriaList.join(", ") || "—";
+  const routesLine =
+    f.routes.length === 1
+      ? `- **Route:** \`${f.routes[0]}\``
+      : `- Routes affected: ${f.routes.length}\n${f.routes.map((r) => `- \`${r}\``).join("\n")}`;
+
+  const fileLine = f.sourceFile
+    ? `- **File:** \`${f.sourceFile}\``
+    : "- **File:** _approximate — source map not available_";
+
+  const snippet = f.evidence
+    ? "\n**Current code:**\n\n```html\n" + escapeCodeBlock(f.evidence) + "\n```\n"
+    : "";
+
+  const fixHint = f.help
+    ? `\n**How to fix:** ${f.help}\n`
+    : "";
+
+  return [
+    `### ${index}. ${f.description || f.ruleId}`,
+    ``,
+    fileLine,
+    routesLine,
+    `- **Criterion:** ${criteria} (Level ${f.level || "?"})`,
+    `- **Rule:** \`${f.ruleId}\``,
+    `- **Detected by:** ${f.source}`,
+    f.helpUrl ? `- **Reference:** ${f.helpUrl}` : "",
+    snippet,
+    fixHint,
+    "---",
+    "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function mergeFindings(findings) {
+  const byKey = new Map();
+  for (const f of findings) {
+    const key = `${f.ruleId}::${f.selector || ""}::${f.evidence || ""}`;
+    if (!byKey.has(key)) {
+      byKey.set(key, { ...f, routes: [], sourceFiles: new Set() });
+    }
+    const entry = byKey.get(key);
+    if (f.route) entry.routes.push(f.route);
+    if (f.sourceFile) entry.sourceFiles.add(f.sourceFile);
+  }
+  for (const entry of byKey.values()) {
+    entry.routes = [...new Set(entry.routes)];
+    entry.sourceFile = [...entry.sourceFiles][0] || null;
+  }
+  return [...byKey.values()];
+}
+
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function escapeCodeBlock(s) {
+  return String(s).replace(/```/g, "\\`\\`\\`");
+}

package/src/output/markdown.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import { renderFindingsMarkdown } from "./markdown.js";
+
+describe("renderFindingsMarkdown", () => {
+  const baseFinding = {
+    source: "axe",
+    ruleId: "image-alt",
+    criteria: ["1.1.1"],
+    level: "A",
+    impact: "critical",
+    description: "Images must have alternate text",
+    help: "Add an alt attribute describing the image",
+    helpUrl: "https://dequeuniversity.com/rules/axe/4.10/image-alt",
+    selector: "img.hero",
+    evidence: "<img src='/hero.png'>",
+  };
+
+  it("includes a header with project + generator metadata", () => {
+    const md = renderFindingsMarkdown({
+      projectName: "my-nextjs-app",
+      generator: "@wcag-audit/cli v1.0.0-alpha.1",
+      totalPages: 47,
+      wcagVersion: "2.2",
+      levels: ["A", "AA"],
+      findings: [],
+    });
+    expect(md).toMatch(/# WCAG Audit Findings — my-nextjs-app/);
+    expect(md).toMatch(/@wcag-audit\/cli v1\.0\.0-alpha\.1/);
+    expect(md).toMatch(/Total pages audited: 47/);
+    expect(md).toMatch(/WCAG 2\.2 Level A \+ AA/);
+    expect(md).toMatch(/No issues found!/);
+  });
+
+  it("groups findings by impact descending", () => {
+    const md = renderFindingsMarkdown({
+      projectName: "x",
+      generator: "x",
+      totalPages: 1,
+      wcagVersion: "2.2",
+      levels: ["A"],
+      findings: [
+        { ...baseFinding, impact: "minor", ruleId: "minor-rule" },
+        { ...baseFinding, impact: "critical", ruleId: "image-alt" },
+        { ...baseFinding, impact: "serious", ruleId: "serious-rule" },
+      ],
+    });
+    const criticalIdx = md.indexOf("## Critical");
+    const seriousIdx = md.indexOf("## Serious");
+    const minorIdx = md.indexOf("## Minor");
+    expect(criticalIdx).toBeGreaterThan(-1);
+    expect(criticalIdx).toBeLessThan(seriousIdx);
+    expect(seriousIdx).toBeLessThan(minorIdx);
+  });
+
+  it("renders a finding with route, file, criterion, and snippet", () => {
+    const md = renderFindingsMarkdown({
+      projectName: "x",
+      generator: "x",
+      totalPages: 1,
+      wcagVersion: "2.2",
+      levels: ["A"],
+      findings: [
+        {
+          ...baseFinding,
+          route: "/",
+          sourceFile: "src/app/page.tsx",
+        },
+      ],
+    });
+    expect(md).toMatch(/\*\*Route:\*\* `\/`/);
+    expect(md).toMatch(/\*\*File:\*\* `src\/app\/page\.tsx`/);
+    expect(md).toMatch(/1\.1\.1/);
+    expect(md).toMatch(/image-alt/);
+    expect(md).toMatch(/<img src='\/hero\.png'>/);
+  });
+
+  it("merges findings that share ruleId but appear on multiple routes", () => {
+    const md = renderFindingsMarkdown({
+      projectName: "x",
+      generator: "x",
+      totalPages: 3,
+      wcagVersion: "2.2",
+      levels: ["A"],
+      findings: [
+        { ...baseFinding, route: "/", sourceFile: "src/app/page.tsx" },
+        { ...baseFinding, route: "/about", sourceFile: "src/app/about/page.tsx" },
+        { ...baseFinding, route: "/pricing", sourceFile: "src/app/pricing/page.tsx" },
+      ],
+    });
+    expect(md).toMatch(/Routes affected: 3/);
+    expect(md).toMatch(/- `\/`/);
+    expect(md).toMatch(/- `\/about`/);
+    expect(md).toMatch(/- `\/pricing`/);
+  });
+});

package/src/report.js

@@ -0,0 +1,239 @@
+// Excel report writer. Mirrors the extension's three-sheet format
+// (Summary / Coverage / Issues) but with an additional Source column and
+// embedded screenshots loaded from disk rather than from in-memory buffers.
+
+import ExcelJS from "exceljs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getManualGuide } from "./wcag-manual-steps.js";
+
+const SHOT_MAX_W = 1000;
+const SHOT_MAX_H = 800;
+
+function pxToPt(px) {
+  return Math.ceil(px * 0.75) + 6;
+}
+
+async function imageDimensions(buffer) {
+  // Lightweight PNG dimension parse — avoids pulling in another dependency.
+  if (buffer[0] === 0x89 && buffer[1] === 0x50) {
+    const w = buffer.readUInt32BE(16);
+    const h = buffer.readUInt32BE(20);
+    return { width: w, height: h };
+  }
+  return { width: 800, height: 600 };
+}
+
+function fitDims(w, h) {
+  const scale = Math.min(SHOT_MAX_W / w, SHOT_MAX_H / h, 1);
+  return { width: Math.max(1, Math.round(w * scale)), height: Math.max(1, Math.round(h * scale)) };
+}
+
+export async function writeReport({ findings, meta, outPath }) {
+  const wb = new ExcelJS.Workbook();
+  wb.creator = "WCAG Documentation Creator CLI";
+  wb.created = new Date();
+
+  // ── Summary sheet ──
+  const sum = wb.addWorksheet("Summary");
+  sum.columns = [
+    { header: "", key: "k", width: 28 },
+    { header: "", key: "v", width: 90 },
+  ];
+  const rows = [
+    ["WCAG Documentation Creator — End-to-End Audit Report"],
+    [],
+    ["Page URL", meta.url],
+    ["WCAG version", meta.wcagVersion],
+    ["Levels", meta.levels.join(", ")],
+    ["Started", meta.startedAt],
+    ["Finished", meta.finishedAt],
+    ["Total findings", String(meta.totalFindings)],
+    [],
+    ["Per-checker timings (s)"],
+  ];
+  rows.forEach((r) => sum.addRow(r));
+  sum.getRow(1).font = { bold: true, size: 14, color: { argb: "FF0969DA" } };
+  for (const [k, v] of Object.entries(meta.perCheckerTimings || {})) {
+    sum.addRow([`  ${k}`, String(v)]);
+  }
+  if (Object.keys(meta.perCheckerErrors || {}).length) {
+    sum.addRow([]);
+    sum.addRow(["Checker errors"]);
+    for (const [k, v] of Object.entries(meta.perCheckerErrors)) sum.addRow([`  ${k}`, v]);
+  }
+  if (meta.aiEnabled) {
+    sum.addRow([]);
+    sum.addRow(["AI model", meta.aiModel || ""]);
+    if (meta.aiUsage) {
+      sum.addRow([
+        "AI tokens (in / out)",
+        `${meta.aiUsage.input_tokens || 0} / ${meta.aiUsage.output_tokens || 0}`,
+      ]);
+    }
+  }
+
+  // ── Coverage sheet ──
+  const cov = wb.addWorksheet("Coverage");
+  cov.columns = [
+    { header: "Criterion", key: "id", width: 12 },
+    { header: "Title", key: "title", width: 36 },
+    { header: "Level", key: "level", width: 8 },
+    { header: "Added in", key: "added", width: 12 },
+    { header: "axe", key: "axe", width: 12 },
+    { header: "Playwright", key: "pw", width: 12 },
+    { header: "AI vision", key: "ai", width: 12 },
+    { header: "Findings", key: "found", width: 10 },
+    { header: "Manual steps to verify", key: "manual", width: 60 },
+    { header: "Notes", key: "notes", width: 40 },
+  ];
+  const covHeader = cov.getRow(1);
+  covHeader.font = { bold: true, color: { argb: "FFFFFFFF" } };
+  covHeader.fill = { type: "pattern", pattern: "solid", fgColor: { argb: "FF0969DA" } };
+  cov.views = [{ state: "frozen", ySplit: 1 }];
+
+  // Build per-criterion finding counts
+  const counts = Object.create(null);
+  for (const f of findings) {
+    const ids = String(f.criteria || "").split(",").map((s) => s.trim()).filter(Boolean);
+    for (const id of ids) counts[id] = (counts[id] || 0) + 1;
+  }
+
+  for (const c of meta.scopeCriteria) {
+    const axeStatus =
+      c.automation === "automated" ? "Automated" :
+      c.automation === "partial" ? "Partial" : "—";
+    const pwStatus = c.playwrightCheckable ? "Checked" : "—";
+    const aiStatus = c.aiReviewable ? (meta.aiEnabled ? "Reviewed" : "available") : "—";
+
+    const guide = getManualGuide(c.id);
+    const row = cov.addRow({
+      id: c.id,
+      title: c.title,
+      level: c.level,
+      added: c.addedIn + (c.removedIn ? ` (rm ${c.removedIn})` : ""),
+      axe: axeStatus,
+      pw: pwStatus,
+      ai: aiStatus,
+      found: counts[c.id] || 0,
+      manual: guide.manualSteps || "",
+      notes: c.notes || "",
+    });
+    row.alignment = { vertical: "top", wrapText: true };
+
+    const colorCell = (key, label) => {
+      const cell = row.getCell(key);
+      const colors = {
+        Automated: "FF116329", Partial: "FFCA8A04",
+        Checked: "FF0969DA",
+        Reviewed: "FF6D28D9", available: "FF8C959F",
+      };
+      if (colors[label]) {
+        cell.font = { bold: true, color: { argb: "FFFFFFFF" } };
+        cell.fill = { type: "pattern", pattern: "solid", fgColor: { argb: colors[label] } };
+        cell.alignment = { vertical: "middle", horizontal: "center" };
+      }
+    };
+    colorCell("axe", axeStatus);
+    colorCell("pw", pwStatus);
+    colorCell("ai", aiStatus);
+    if (counts[c.id]) row.getCell("found").font = { bold: true, color: { argb: "FFB91C1C" } };
+  }
+
+  // ── Issues sheet ──
+  const ws = wb.addWorksheet("Issues");
+  ws.columns = [
+    { header: "Issue #", key: "n", width: 8 },
+    { header: "Source", key: "src", width: 12 },
+    { header: "Rule ID", key: "rule", width: 28 },
+    { header: "WCAG", key: "crit", width: 12 },
+    { header: "Level", key: "level", width: 8 },
+    { header: "Severity", key: "sev", width: 12 },
+    { header: "Description", key: "desc", width: 50 },
+    { header: "How to fix", key: "help", width: 50 },
+    { header: "Help URL", key: "url", width: 36 },
+  ];
+  const wsHeader = ws.getRow(1);
+  wsHeader.font = { bold: true, color: { argb: "FFFFFFFF" } };
+  wsHeader.fill = { type: "pattern", pattern: "solid", fgColor: { argb: "FF0969DA" } };
+  ws.views = [{ state: "frozen", ySplit: 1 }];
+
+  for (const f of findings) {
+    const metaRow = ws.addRow({
+      n: f.issueNumber,
+      src: f.source,
+      rule: f.ruleId,
+      crit: f.criteria,
+      level: f.level,
+      sev: f.impact,
+      desc: f.description + (f.help ? `\n\n${f.help}` : ""),
+      help: f.failureSummary || "",
+      url: f.helpUrl,
+    });
+    metaRow.alignment = { vertical: "top", wrapText: true };
+    metaRow.height = 90;
+
+    // Source colour-code
+    const srcCell = metaRow.getCell("src");
+    const srcColors = { axe: "FF0969DA", playwright: "FF116329", ai: "FF6D28D9" };
+    if (srcColors[f.source]) {
+      srcCell.fill = { type: "pattern", pattern: "solid", fgColor: { argb: srcColors[f.source] } };
+      srcCell.font = { bold: true, color: { argb: "FFFFFFFF" } };
+      srcCell.alignment = { horizontal: "center", vertical: "middle" };
+    }
+
+    // Severity colour-code
+    const sevCell = metaRow.getCell("sev");
+    const sevColors = { critical: "FFB91C1C", serious: "FFEA580C", moderate: "FFCA8A04", minor: "FF6B7280" };
+    if (sevColors[f.impact]) {
+      sevCell.fill = { type: "pattern", pattern: "solid", fgColor: { argb: sevColors[f.impact] } };
+      sevCell.font = { bold: true, color: { argb: "FFFFFFFF" } };
+      sevCell.alignment = { horizontal: "center", vertical: "middle" };
+    }
+
+    if (f.helpUrl) {
+      metaRow.getCell("url").value = { text: f.helpUrl, hyperlink: f.helpUrl };
+      metaRow.getCell("url").font = { color: { argb: "FF0969DA" }, underline: true };
+    }
+
+    // Selector + evidence row
+    const selRow = ws.addRow(["", "", "Selector:", f.selector || "", "", "", f.evidence || "", "", ""]);
+    ws.mergeCells(selRow.number, 4, selRow.number, 6);
+    ws.mergeCells(selRow.number, 7, selRow.number, 9);
+    selRow.getCell(3).font = { bold: true, italic: true, color: { argb: "FF57606A" } };
+    selRow.getCell(4).font = { name: "Menlo", size: 10 };
+    selRow.getCell(7).font = { name: "Menlo", size: 10 };
+    selRow.alignment = { vertical: "top", wrapText: true };
+    selRow.height = 60;
+
+    // Screenshot row
+    if (f.screenshotFile) {
+      try {
+        const buffer = await fs.readFile(f.screenshotFile);
+        const dims = await imageDimensions(buffer);
+        const fit = fitDims(dims.width, dims.height);
+        const imgRow = ws.addRow(["", "", "Screenshot", "", "", "", "", "", ""]);
+        imgRow.getCell(3).font = { bold: true, italic: true, color: { argb: "FF57606A" } };
+        ws.mergeCells(imgRow.number, 4, imgRow.number, 9);
+        imgRow.height = pxToPt(fit.height);
+        const imageId = wb.addImage({ buffer, extension: "png" });
+        ws.addImage(imageId, {
+          tl: { col: 3, row: imgRow.number - 1 },
+          ext: { width: fit.width, height: fit.height },
+          editAs: "oneCell",
+        });
+      } catch (_) {
+        const imgRow = ws.addRow(["", "", "Screenshot", "(load failed)"]);
+        imgRow.height = 24;
+      }
+    }
+
+    // Spacer
+    const spacer = ws.addRow([]);
+    spacer.height = 8;
+    spacer.fill = { type: "pattern", pattern: "solid", fgColor: { argb: "FFEAEEF2" } };
+  }
+
+  await fs.mkdir(path.dirname(path.resolve(outPath)), { recursive: true });
+  await wb.xlsx.writeFile(outPath);
+}

package/src/util/anthropic.js

@@ -0,0 +1,25 @@
+// Backwards-compatible thin wrapper. The original API was Anthropic-only;
+// the codebase now supports Anthropic / OpenAI / Google via callLlmJsonArray
+// in ./llm.js. We keep `askClaudeForJsonArray` as a delegating shim so
+// every existing checker (screen-reader, forms, ai-vision) keeps working
+// without an edit. The shim accepts an optional `provider` field — if
+// omitted it defaults to anthropic, matching the historical behaviour.
+
+import { callLlmJsonArray } from "./llm.js";
+
+export async function askClaudeForJsonArray({
+  provider = "anthropic",
+  apiKey,
+  model,
+  prompt,
+  images = [],
+  maxTokens = 8192,
+}) {
+  if (!apiKey) {
+    throw new Error(
+      `LLM API key required (provider=${provider}). Set --anthropic-api-key, ` +
+      `pass it in the audit request, or set the corresponding env var.`
+    );
+  }
+  return callLlmJsonArray({ provider, apiKey, model, prompt, images, maxTokens });
+}