@wcag-audit/cli 1.0.0-alpha.3

package/src/report.js

@@ -0,0 +1,235 @@
+// 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";
+
+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: 42 },
+    { header: "Level", key: "level", width: 8 },
+    { header: "Added in", key: "added", width: 12 },
+    { header: "axe", key: "axe", width: 14 },
+    { header: "Playwright", key: "pw", width: 14 },
+    { header: "AI vision", key: "ai", width: 14 },
+    { header: "Findings", key: "found", width: 12 },
+    { header: "Notes", key: "notes", width: 60 },
+  ];
+  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 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,
+      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 });
+}

package/src/util/llm.js

@@ -0,0 +1,159 @@
+// Server-side mirror of the extension's llm-client.js. Same interface,
+// same provider catalogue, same call shape. Pure fetch — no SDKs — so
+// the same prompts work identically in browser and Node.
+//
+//   await callLlmJsonArray({
+//     provider, apiKey, model, prompt,
+//     images: [{ buffer, mimeType }], maxTokens
+//   })
+//   → { array, usage: { input_tokens, output_tokens }, raw }
+
+export const PROVIDERS = {
+  anthropic: {
+    label: "Anthropic Claude",
+    envKey: "ANTHROPIC_API_KEY",
+    defaultModel: "claude-sonnet-4-6",
+  },
+  openai: {
+    label: "OpenAI",
+    envKey: "OPENAI_API_KEY",
+    defaultModel: "gpt-4.1-mini",
+  },
+  google: {
+    label: "Google Gemini",
+    envKey: "GOOGLE_API_KEY",
+    defaultModel: "gemini-2.5-flash",
+  },
+};
+
+function toBase64(image) {
+  if (!image) return "";
+  if (typeof image.base64 === "string") return image.base64;
+  if (Buffer.isBuffer(image.buffer)) return image.buffer.toString("base64");
+  if (image.buffer) return Buffer.from(image.buffer).toString("base64");
+  return "";
+}
+
+// ─── Anthropic ──────────────────────────────────────────────────────────
+async function callAnthropic({ apiKey, model, prompt, images, maxTokens }) {
+  const content = [];
+  for (const img of images || []) {
+    content.push({
+      type: "image",
+      source: { type: "base64", media_type: img.mimeType || "image/png", data: toBase64(img) },
+    });
+  }
+  content.push({ type: "text", text: prompt });
+
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxTokens || 4096,
+      messages: [{ role: "user", content }],
+    }),
+  });
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error(`Anthropic API ${res.status}: ${txt.slice(0, 400)}`);
+  }
+  const data = await res.json();
+  const text = (data.content || []).filter((c) => c.type === "text").map((c) => c.text).join("\n");
+  return {
+    text,
+    usage: { input_tokens: data.usage?.input_tokens || 0, output_tokens: data.usage?.output_tokens || 0 },
+  };
+}
+
+// ─── OpenAI ─────────────────────────────────────────────────────────────
+async function callOpenAi({ apiKey, model, prompt, images, maxTokens }) {
+  const content = [];
+  for (const img of images || []) {
+    const b64 = toBase64(img);
+    content.push({
+      type: "image_url",
+      image_url: { url: `data:${img.mimeType || "image/png"};base64,${b64}` },
+    });
+  }
+  content.push({ type: "text", text: prompt });
+
+  const res = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: "Bearer " + apiKey },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxTokens || 4096,
+      messages: [{ role: "user", content }],
+    }),
+  });
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error(`OpenAI API ${res.status}: ${txt.slice(0, 400)}`);
+  }
+  const data = await res.json();
+  const text = data.choices?.[0]?.message?.content || "";
+  return {
+    text,
+    usage: { input_tokens: data.usage?.prompt_tokens || 0, output_tokens: data.usage?.completion_tokens || 0 },
+  };
+}
+
+// ─── Google Gemini ──────────────────────────────────────────────────────
+async function callGoogle({ apiKey, model, prompt, images, maxTokens }) {
+  const parts = [];
+  for (const img of images || []) {
+    parts.push({ inline_data: { mime_type: img.mimeType || "image/png", data: toBase64(img) } });
+  }
+  parts.push({ text: prompt });
+
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(apiKey)}`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      contents: [{ role: "user", parts }],
+      generationConfig: { maxOutputTokens: maxTokens || 4096 },
+    }),
+  });
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error(`Google API ${res.status}: ${txt.slice(0, 400)}`);
+  }
+  const data = await res.json();
+  const text = (data.candidates?.[0]?.content?.parts || []).map((p) => p.text || "").join("\n");
+  return {
+    text,
+    usage: {
+      input_tokens: data.usageMetadata?.promptTokenCount || 0,
+      output_tokens: data.usageMetadata?.candidatesTokenCount || 0,
+    },
+  };
+}
+
+// ─── Dispatcher ─────────────────────────────────────────────────────────
+export async function callLlm(opts) {
+  const provider = (opts.provider || "anthropic").toLowerCase();
+  if (provider === "anthropic") return callAnthropic(opts);
+  if (provider === "openai") return callOpenAi(opts);
+  if (provider === "google") return callGoogle(opts);
+  throw new Error(`Unknown LLM provider: ${provider}`);
+}
+
+// JSON-array wrapper. Strips markdown fences and extracts the first
+// [...] block. Same contract as the extension's WCAG_LLM.callJsonArray.
+export async function callLlmJsonArray(opts) {
+  const { text, usage } = await callLlm(opts);
+  let t = (text || "").trim();
+  t = t.replace(/^```json\s*/i, "").replace(/^```\s*/i, "").replace(/```\s*$/i, "").trim();
+  const start = t.indexOf("[");
+  const end = t.lastIndexOf("]");
+  if (start === -1 || end === -1) {
+    throw new Error("LLM response did not contain a JSON array. Raw: " + (text || "").slice(0, 300));
+  }
+  return { array: JSON.parse(t.slice(start, end + 1)), usage, raw: text };
+}

package/src/util/screenshot.js

@@ -0,0 +1,131 @@
+// Screenshot helpers for the CLI. Captures cropped, annotated PNGs of
+// problem elements and writes them to the configured screenshots dir so the
+// report writer can embed them and reference them.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+let counter = 0;
+
+export function nextScreenshotId() {
+  counter++;
+  return String(counter).padStart(4, "0");
+}
+
+export function safeFileSegment(s, max = 60) {
+  return (s || "")
+    .replace(/[^a-z0-9._-]+/gi, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, max) || "issue";
+}
+
+// Capture an annotated viewport screenshot of a single element. Mirrors
+// the extension: scroll the element to the centre of the viewport, draw a
+// bold red highlight overlay, capture the visible viewport (not clipped),
+// then remove the overlay. The popup re-renders this onto its standard
+// 1100x700 canvas so every embedded image in the report is identical.
+export async function captureElement(page, locator, opts = {}) {
+  const { label = "" } = opts;
+  try {
+    const handle = await locator.elementHandle({ timeout: 2000 });
+    if (!handle) return null;
+    await handle.evaluate((el) => {
+      try { el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" }); } catch (_) {}
+    }).catch(() => {});
+    const box = await handle.boundingBox();
+    if (!box || box.width === 0 || box.height === 0) {
+      await handle.dispose();
+      return null;
+    }
+
+    // Bold red overlay matching the extension's content.js. Two layers of
+    // border + glow + a label with arrow so the highlight is unmissable
+    // even when the element fills most of the viewport.
+    await page.evaluate(
+      ({ x, y, w, h, label }) => {
+        const id = "__wcag_cli_overlay__";
+        const lid = "__wcag_cli_label__";
+        document.getElementById(id)?.remove();
+        document.getElementById(lid)?.remove();
+        const docX = x + window.scrollX;
+        const docY = y + window.scrollY;
+        const o = document.createElement("div");
+        o.id = id;
+        Object.assign(o.style, {
+          position: "absolute",
+          top: docY + "px",
+          left: docX + "px",
+          width: w + "px",
+          height: h + "px",
+          border: "5px solid #ff0033",
+          outline: "2px solid #ffffff",
+          boxShadow:
+            "0 0 0 4px rgba(255,255,255,0.95), " +
+            "0 0 0 8px rgba(255,0,51,0.6), " +
+            "0 0 24px 12px rgba(255,0,51,0.45)",
+          pointerEvents: "none",
+          zIndex: "2147483647",
+          boxSizing: "border-box",
+          borderRadius: "3px",
+        });
+        const t = document.createElement("div");
+        t.id = lid;
+        t.textContent = "▶ " + (label || "WCAG issue");
+        const labelTop = docY - 32;
+        const labelAbove = labelTop > 8;
+        Object.assign(t.style, {
+          position: "absolute",
+          top: (labelAbove ? labelTop : docY + h + 6) + "px",
+          left: docX + "px",
+          background: "#ff0033",
+          color: "#ffffff",
+          font: "bold 14px -apple-system, system-ui, sans-serif",
+          padding: "4px 10px",
+          borderRadius: "4px",
+          border: "2px solid #ffffff",
+          boxShadow: "0 2px 8px rgba(0,0,0,0.4)",
+          pointerEvents: "none",
+          zIndex: "2147483647",
+          whiteSpace: "nowrap",
+          maxWidth: "90vw",
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+        });
+        document.documentElement.appendChild(o);
+        document.documentElement.appendChild(t);
+      },
+      { x: box.x, y: box.y, w: box.width, h: box.height, label }
+    );
+
+    // Tiny pause for the overlay to paint and any sticky/fixed elements
+    // to settle after the scroll.
+    await page.waitForTimeout(150);
+
+    // Capture only the visible viewport. The element is already centred,
+    // so the highlight is in frame. The popup will normalize this through
+    // its fixed-size canvas, so we don't need to crop.
+    const buffer = await page.screenshot({ fullPage: false, type: "png" });
+
+    await page.evaluate(() => {
+      document.getElementById("__wcag_cli_overlay__")?.remove();
+      document.getElementById("__wcag_cli_label__")?.remove();
+    });
+    await handle.dispose();
+    return buffer;
+  } catch (e) {
+    return null;
+  }
+}
+
+export async function captureElementBySelector(page, selector, opts = {}) {
+  return captureElement(page, page.locator(selector).first(), opts);
+}
+
+export async function saveScreenshot(buffer, dir, ruleId) {
+  if (!buffer) return null;
+  await fs.mkdir(dir, { recursive: true });
+  const id = nextScreenshotId();
+  const file = path.join(dir, `${id}_${safeFileSegment(ruleId)}.png`);
+  await fs.writeFile(file, buffer);
+  return file;
+}