@wcag-audit/cli 1.0.0-alpha.3

package/src/checkers/viewport.js

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

package/src/cli.js

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

package/src/commands/ci.js

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

package/src/commands/ci.test.js

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

package/src/commands/doctor.js

@@ -0,0 +1,105 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { randomUUID } from "crypto";
+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.3";
+
+export async function runDoctor({ cwd = process.cwd(), log = console.log } = {}) {
+  const checks = [];
+
+  // ── License ──────────────────────────────────────────────────────
+  const globalCfg = await readGlobalConfig();
+  if (!globalCfg.licenseKey) {
+    checks.push({
+      name: "license",
+      status: "fail",
+      message: "No license key found in ~/.wcagauditrc. Run `npx wcag-audit init` to set one.",
+    });
+  } else {
+    const license = await validateLicense(globalCfg.licenseKey, {
+      machineId: randomUUID(),
+      source: "cli",
+      version: CLI_VERSION,
+    });
+    if (!license.valid) {
+      checks.push({
+        name: "license",
+        status: "fail",
+        message: `License validation failed: ${license.error}`,
+      });
+    } else {
+      const credits = license.creditsRemaining?.total ?? "unlimited";
+      checks.push({
+        name: "license",
+        status: "pass",
+        message: `${license.tier} plan, ${credits} credits remaining`,
+      });
+    }
+  }
+
+  // ── AI key (optional) ───────────────────────────────────────────
+  if (globalCfg.ai?.enabled) {
+    if (!globalCfg.ai.apiKey) {
+      checks.push({
+        name: "ai-key",
+        status: "fail",
+        message: "AI review is enabled but no API key is configured. Re-run `wcag-audit init`.",
+      });
+    } else {
+      checks.push({
+        name: "ai-key",
+        status: "pass",
+        message: `${globalCfg.ai.provider} key present`,
+      });
+    }
+  }
+
+  // ── Framework ────────────────────────────────────────────────────
+  const det = await detectFramework(cwd);
+  if (!det) {
+    checks.push({
+      name: "framework",
+      status: "fail",
+      message:
+        "Could not detect a supported framework. Supported: Next.js, Vite+React Router, SvelteKit, Remix, Astro. Use --url or --routes for deployed sites / custom setups.",
+    });
+  } else {
+    checks.push({
+      name: "framework",
+      status: "pass",
+      message: `${det.framework} detected (${det.strategy})`,
+    });
+  }
+
+  // ── Dev script ───────────────────────────────────────────────────
+  try {
+    const pkg = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+    const hasDev = pkg.scripts && (pkg.scripts.dev || pkg.scripts.start);
+    checks.push({
+      name: "dev-script",
+      status: hasDev ? "pass" : "fail",
+      message: hasDev
+        ? `\`${pkg.scripts.dev ? "npm run dev" : "npm run start"}\` will be used to start the dev server`
+        : "No `dev` or `start` script in package.json. Add one or set devServer.command in .wcagauditrc.",
+    });
+  } catch {
+    // package.json doesn't exist — already failed on framework check
+  }
+
+  // ── Print results ────────────────────────────────────────────────
+  log("");
+  log("wcag-audit doctor");
+  log("─────────────────────────────");
+  for (const c of checks) {
+    const icon = c.status === "pass" ? "✓" : "✗";
+    log(`${icon} ${c.name.padEnd(14)} ${c.message}`);
+  }
+  log("");
+  const failing = checks.filter((c) => c.status === "fail");
+  const ok = failing.length === 0;
+  log(ok ? "All checks passed." : `${failing.length} check(s) failed. Fix these before running scan.`);
+  return { ok, checks };
+}

package/src/commands/doctor.test.js

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtemp, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { runDoctor } from "./doctor.js";
+
+let tmpHome;
+let projDir;
+
+beforeEach(async () => {
+  tmpHome = await mkdtemp(join(tmpdir(), "wcagdoc-home-"));
+  projDir = await mkdtemp(join(tmpdir(), "wcagdoc-proj-"));
+  process.env.HOME = tmpHome;
+  global.fetch = vi.fn();
+});
+
+afterEach(async () => {
+  await rm(tmpHome, { recursive: true, force: true });
+  await rm(projDir, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+describe("runDoctor", () => {
+  it("reports missing license when no global config exists", async () => {
+    const logs = [];
+    const result = await runDoctor({ cwd: projDir, log: (m) => logs.push(m) });
+    expect(result.ok).toBe(false);
+    expect(result.checks.find((c) => c.name === "license")?.status).toBe("fail");
+    const joined = logs.join("\n");
+    expect(joined).toMatch(/✗ license/);
+    expect(joined).toMatch(/wcag-audit init/);
+  });
+
+  it("marks license pass when config + validation succeed", async () => {
+    await writeFile(
+      join(tmpHome, ".wcagauditrc"),
+      JSON.stringify({
+        licenseKey: "WCAG-TEST-AAAA-BBBB-CCCC",
+        ai: { enabled: false, provider: "anthropic", apiKey: null },
+      }),
+      "utf8",
+    );
+    global.fetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ valid: true, tier: "pro", creditsRemaining: { total: 100 } }),
+    });
+    const result = await runDoctor({ cwd: projDir, log: () => {} });
+    expect(result.checks.find((c) => c.name === "license")?.status).toBe("pass");
+  });
+
+  it("reports missing framework when cwd is not a Next.js project", async () => {
+    await writeFile(
+      join(tmpHome, ".wcagauditrc"),
+      JSON.stringify({ licenseKey: "WCAG-TEST-AAAA-BBBB-CCCC", ai: { enabled: false } }),
+      "utf8",
+    );
+    global.fetch.mockResolvedValue({ ok: true, json: async () => ({ valid: true, tier: "pro" }) });
+    const result = await runDoctor({ cwd: projDir, log: () => {} });
+    expect(result.checks.find((c) => c.name === "framework")?.status).toBe("fail");
+  });
+
+  it("reports framework pass when cwd is a Next.js app", async () => {
+    await writeFile(
+      join(tmpHome, ".wcagauditrc"),
+      JSON.stringify({ licenseKey: "WCAG-TEST-AAAA-BBBB-CCCC", ai: { enabled: false } }),
+      "utf8",
+    );
+    await writeFile(
+      join(projDir, "package.json"),
+      JSON.stringify({ dependencies: { next: "15.0.0" }, scripts: { dev: "next dev" } }),
+      "utf8",
+    );
+    const { mkdir } = await import("fs/promises");
+    await mkdir(join(projDir, "app"), { recursive: true });
+    await writeFile(join(projDir, "app", "page.tsx"), "// test", "utf8");
+    global.fetch.mockResolvedValue({ ok: true, json: async () => ({ valid: true, tier: "pro" }) });
+    const result = await runDoctor({ cwd: projDir, log: () => {} });
+    expect(result.checks.find((c) => c.name === "framework")?.status).toBe("pass");
+    expect(result.checks.find((c) => c.name === "dev-script")?.status).toBe("pass");
+  });
+});