@wcag-audit/cli 1.0.0-alpha.11

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 WCAG Audit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Note: This package is a client for the WCAG Audit SaaS. A valid license key
+from https://wcagaudit.io is required to run audits. See the website for
+pricing and terms.

package/README.md

@@ -0,0 +1,110 @@
+# @wcagaudit/cli
+
+Project-aware WCAG 2.1/2.2 auditor. Scans every route in your Next.js app, generates an Excel report AND AI-ready fix prompts your coding agent can read directly.
+
+## Install
+
+No install needed — use `npx`:
+
+```bash
+npx wcag-audit init   # one-time: license key + optional AI config
+cd my-nextjs-app
+npx wcag-audit scan   # audits every route, writes WCAG_FIXES.md + wcag-report.xlsx
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `init` | Interactive setup. Saves license + AI config to `~/.wcagauditrc` (chmod 600). |
+| `scan` | Audit every route in the current project. Next.js App + Pages Router supported. |
+| `scan --dry-run` | Preview credit cost only. No browser launches, no credits consumed. |
+| `scan --no-ai` | Skip AI vision review (faster, no LLM cost). |
+| `scan --no-cache` | Force a full scan even if cached findings are available (they're valid for 24h). |
+| `ci --fail-on=<level>` | CI-optimized scan. Exit 1 when findings at `critical` (default), `serious`, `moderate`, or `minor` threshold are found. |
+| `doctor` | Diagnose setup (license, AI key, framework detection, dev script). |
+| `scan --url=<url>` | Crawl a deployed site instead of the local project. Combine with `--crawl-depth`. |
+| `scan --routes=<file>` | Load routes from a plain text file (one per line, `#` for comments). |
+| `scan --crawl-depth=<n>` | Max BFS depth when using `--url` (default 2). |
+| `audit <url>` | Legacy single-URL audit. Prefer `scan` for local projects. |
+| `config` | Print current config (secrets masked). |
+
+## Config
+
+### Global: `~/.wcagauditrc` (secrets, never committed)
+
+Created by `init`. Contains license key + AI API key.
+
+### Project: `.wcagauditrc` (committed)
+
+Optional. Overrides scan behavior per project:
+
+```json
+{
+  "routes": "auto",
+  "excludePaths": ["/api/*", "/admin/*"],
+  "failOn": "critical",
+  "outputs": ["excel", "markdown"],
+  "devServer": {
+    "command": null,
+    "port": null,
+    "healthCheck": "/"
+  }
+}
+```
+
+## What Gets Generated
+
+- **`WCAG_FIXES.md`** — AI-ready markdown with file paths, route context, WCAG criteria, code snippets, and fix hints. Hand to Cursor / Claude Code / Windsurf.
+- **`wcag-report.xlsx`** — Full compliance report with embedded screenshots.
+
+## Supported Frameworks
+
+- Next.js App Router and Pages Router
+- Vite + React Router v6+
+- SvelteKit
+- Remix v2
+- Astro
+- Fallbacks: sitemap.xml, manual routes file, BFS crawl for deployed sites
+
+## Dynamic Routes
+
+Routes like `/blog/[slug]` or `/users/:id` are skipped by default. To include them, add samples to `.wcagauditrc`:
+
+```json
+{
+  "dynamicRouteSamples": {
+    "/blog/[slug]": ["hello-world", "another-post"],
+    "/users/[id]": ["1", "42"]
+  }
+}
+```
+
+Each sample value generates one concrete route.
+
+## Credits
+
+- Pro / Business: 1 credit per route audited.
+- Enterprise: postpaid monthly invoice.
+- AI vision review is BYOK (your own API key, your own LLM spend).
+
+## Cursor / Claude Code Integration
+
+Set `outputs` in `.wcagauditrc` to include one or both of:
+
+- `"cursor-rules"` — writes `.cursor/rules/wcag-fixes.mdc`. Cursor auto-attaches the rule as context when you edit matching files.
+- `"agents-md"` — upserts a `<!-- wcag-audit:start -->` / `<!-- wcag-audit:end -->` section in your root `AGENTS.md`. Safe to re-run; it replaces the section in place without disturbing surrounding content.
+
+Example:
+
+```json
+{
+  "outputs": ["markdown", "cursor-rules", "agents-md"]
+}
+```
+
+## Incremental Scans (Cache)
+
+Scan results are cached per route for 24h in `.wcag-audit/cache/`. Re-running `scan` within that window skips unchanged routes at zero credit cost. Gitignore `.wcag-audit/` to keep the cache local.
+
+Pass `--no-cache` to force a fresh scan.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@wcag-audit/cli",
+  "version": "1.0.0-alpha.11",
+  "description": "Project-aware WCAG 2.1/2.2 auditor with AI-ready fix prompts for vibe-coding tools (Cursor, Claude Code, Windsurf).",
+  "type": "module",
+  "bin": {
+    "wcag-audit": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "patches",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "wcag",
+    "accessibility",
+    "a11y",
+    "audit",
+    "cli",
+    "cursor",
+    "claude-code",
+    "nextjs",
+    "vite",
+    "sveltekit",
+    "remix",
+    "astro"
+  ],
+  "homepage": "https://wcagaudit.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wcagauditdev-commits/wcag-documentation-creator.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/wcagauditdev-commits/wcag-documentation-creator/issues"
+  },
+  "license": "MIT",
+  "scripts": {
+    "audit": "node src/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "postinstall": "playwright install chromium && patch-package"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.32.1",
+    "@axe-core/playwright": "^4.10.1",
+    "@guidepup/guidepup": "^0.24.1",
+    "@guidepup/playwright": "^0.15.0",
+    "axe-core": "^4.10.2",
+    "commander": "^12.1.0",
+    "enquirer": "^2.4.1",
+    "exceljs": "^4.4.0",
+    "execa": "^9.5.2",
+    "fast-xml-parser": "^4.5.0",
+    "get-port": "^7.1.0",
+    "p-limit": "^6.1.0",
+    "patch-package": "^8.0.1",
+    "pixelmatch": "^6.0.0",
+    "playwright": "^1.49.0",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "vite": "^8.0.8",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/patches/@guidepup+guidepup+0.24.1.patch

@@ -0,0 +1,30 @@
+diff --git a/node_modules/@guidepup/guidepup/lib/macOS/VoiceOver/supportsAppleScriptControl/enabledDefaults.js b/node_modules/@guidepup/guidepup/lib/macOS/VoiceOver/supportsAppleScriptControl/enabledDefaults.js
+index 19cbf41..af60107 100644
+--- a/node_modules/@guidepup/guidepup/lib/macOS/VoiceOver/supportsAppleScriptControl/enabledDefaults.js
++++ b/node_modules/@guidepup/guidepup/lib/macOS/VoiceOver/supportsAppleScriptControl/enabledDefaults.js
+@@ -5,13 +5,21 @@ const child_process_1 = require("child_process");
+ const VOICE_OVER_APPLESCRIPT_ENABLED_DEFAULTS = "defaults read com.apple.VoiceOver4/default SCREnableAppleScript";
+ async function enabledDefaults() {
+     return await new Promise((resolve) => {
+-        (0, child_process_1.exec)(VOICE_OVER_APPLESCRIPT_ENABLED_DEFAULTS, (err, stdout) => {
++        (0, child_process_1.exec)(VOICE_OVER_APPLESCRIPT_ENABLED_DEFAULTS, (err, stdout, stderr) => {
++            // Sequoia-and-later patch: macOS 15 stopped writing the
++            // SCREnableAppleScript key into com.apple.VoiceOver4/default.
++            // If the key simply doesn't exist, treat it as a soft pass and
++            // let the .VoiceOverAppleScriptEnabled DB file be authoritative.
+             if (err) {
++                const msg = ((stderr || "") + (err.message || "")).toString();
++                if (/does not exist/i.test(msg)) {
++                    resolve(true);
++                    return;
++                }
+                 resolve(false);
++                return;
+             }
+-            else {
+-                resolve(stdout.trim() === "1");
+-            }
++            resolve(stdout.trim() === "1");
+         });
+     });
+ }

package/src/__tests__/sanity.test.js

@@ -0,0 +1,7 @@
+import { describe, it, expect } from "vitest";
+
+describe("sanity", () => {
+  it("runs vitest", () => {
+    expect(1 + 1).toBe(2);
+  });
+});

package/src/ai-fix-json.js

@@ -0,0 +1,321 @@
+// Generates an AI-fixable JSON report from audit findings.
+// Each issue includes a specific prompt that an AI coding agent can use
+// to fix the violation in the source code.
+//
+// Output format:
+// {
+//   meta: { url, timestamp, wcagVersion, levels, totalIssues },
+//   issues: [
+//     {
+//       issueNumber, ruleId, criteria, level, severity, source,
+//       description, selector, evidence, helpUrl,
+//       fixPrompt: "...",         // Natural language instruction for AI
+//       fixContext: { ... },      // Structured context for the fix
+//     }
+//   ]
+// }
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// ─── Per-criterion fix prompt templates ─────────────────────────────
+// Maps WCAG criteria to specific, actionable fix instructions.
+// Each returns a function that takes the finding and returns a prompt.
+
+const CRITERION_FIX_TEMPLATES = {
+  // 1.1.1 Non-text Content
+  "1.1.1": (f) =>
+    `Add descriptive alt text to the image/non-text element at "${f.selector}". ` +
+    `The alt text should convey the same information as the visual content. ` +
+    `If the image is decorative, use alt="" or aria-hidden="true". ` +
+    `If it's a complex image (chart/diagram), provide a longer description via aria-describedby.`,
+
+  // 1.2.1 Audio/Video-only
+  "1.2.1": (f) =>
+    `Provide a text transcript for the audio/video-only content at "${f.selector}". ` +
+    `Add a <track> element with kind="captions" for video, or a visible text transcript link nearby.`,
+
+  // 1.2.2 Captions
+  "1.2.2": (f) =>
+    `Add captions to the video at "${f.selector}". ` +
+    `Include a <track kind="captions" src="captions.vtt" srclang="en" label="English"> element inside the <video> tag.`,
+
+  // 1.3.1 Info and Relationships
+  "1.3.1": (f) =>
+    `Fix the semantic structure at "${f.selector}". ` +
+    `Ensure visual relationships are expressed in markup: use proper heading levels (h1-h6), ` +
+    `<table> with <th>/<td> for tabular data, <fieldset>/<legend> for form groups, ` +
+    `and <ul>/<ol>/<li> for lists. Don't use visual-only styling to convey meaning.`,
+
+  // 1.3.2 Meaningful Sequence
+  "1.3.2": (f) =>
+    `Fix the reading order at "${f.selector}". ` +
+    `Remove positive tabindex values (use tabindex="0" or no tabindex instead). ` +
+    `Ensure the DOM order matches the visual reading order. ` +
+    `Use CSS flexbox/grid order only when it doesn't change the logical meaning.`,
+
+  // 1.3.4 Orientation
+  "1.3.4": (f) =>
+    `Remove the CSS orientation lock at "${f.selector}". ` +
+    `Delete any @media (orientation: portrait/landscape) rules that hide or restrict content. ` +
+    `The page must be usable in both portrait and landscape modes.`,
+
+  // 1.3.5 Identify Input Purpose
+  "1.3.5": (f) =>
+    `Add the correct autocomplete attribute to the input at "${f.selector}". ` +
+    `Use standard values like autocomplete="name", "email", "tel", "street-address", etc. ` +
+    `This helps browsers and assistive technologies auto-fill user information.`,
+
+  // 1.4.1 Use of Color
+  "1.4.1": (f) =>
+    `Don't use color alone to convey information at "${f.selector}". ` +
+    `Add a secondary visual indicator: an icon, underline, pattern, or text label. ` +
+    `For links in text blocks, add an underline or other non-color distinction.`,
+
+  // 1.4.3 Contrast (Minimum)
+  "1.4.3": (f) => {
+    const ratioMatch = f.failureSummary?.match(/(\d+\.?\d*:\d+)/);
+    const ratio = ratioMatch ? ratioMatch[1] : "unknown";
+    return (
+      `Fix the color contrast at "${f.selector}". ` +
+      `Current contrast ratio is ${ratio} — the minimum required is 4.5:1 for normal text and 3:1 for large text (18px+ or 14px+ bold). ` +
+      `Darken the text color or lighten the background. Use a contrast checker to verify.`
+    );
+  },
+
+  // 1.4.4 Resize Text
+  "1.4.4": (f) =>
+    `Fix text resizing at "${f.selector}". ` +
+    `Remove any user-scalable=no or maximum-scale restrictions from the viewport meta tag. ` +
+    `Use relative units (rem, em, %) instead of px for font sizes. ` +
+    `Content must be readable when text is resized to 200%.`,
+
+  // 1.4.5 Images of Text
+  "1.4.5": (f) =>
+    `Replace the image of text at "${f.selector}" with actual styled HTML text. ` +
+    `Use CSS for visual presentation (font-family, font-size, color, etc.). ` +
+    `Images of text are only acceptable for logotypes.`,
+
+  // 1.4.10 Reflow
+  "1.4.10": (f) =>
+    `Fix content reflow at "${f.selector}". ` +
+    `At 320px viewport width (or 400% zoom), content must not require horizontal scrolling. ` +
+    `Use responsive CSS (flexbox, grid, media queries). Avoid fixed-width containers.`,
+
+  // 1.4.11 Non-text Contrast
+  "1.4.11": (f) =>
+    `Increase the contrast of the UI component or graphic at "${f.selector}". ` +
+    `Non-text elements (borders, icons, focus indicators, chart segments) need at least 3:1 contrast ratio against adjacent colors.`,
+
+  // 1.4.12 Text Spacing
+  "1.4.12": (f) =>
+    `Fix text spacing handling at "${f.selector}". ` +
+    `Content must not be clipped or overlap when users override: ` +
+    `line-height to 1.5×, letter-spacing to 0.12em, word-spacing to 0.16em, paragraph spacing to 2×. ` +
+    `Avoid fixed heights on text containers.`,
+
+  // 1.4.13 Content on Hover or Focus
+  "1.4.13": (f) =>
+    `Fix the hover/focus content at "${f.selector}". ` +
+    `Tooltip or popup content must: (1) be dismissible via Escape without moving focus, ` +
+    `(2) remain visible while hovering over it, and (3) persist until dismissed or no longer relevant.`,
+
+  // 2.1.1 Keyboard
+  "2.1.1": (f) =>
+    `Make the element at "${f.selector}" keyboard accessible. ` +
+    `If it's a custom interactive control, add tabindex="0" and handle keydown events for Enter and Space. ` +
+    `If using onClick on a div/span, change it to a <button> or <a>. ` +
+    `Ensure all functionality available via mouse is also available via keyboard.`,
+
+  // 2.1.2 No Keyboard Trap
+  "2.1.2": (f) =>
+    `Fix the keyboard trap at "${f.selector}". ` +
+    `Users must be able to Tab away from any focusable element. ` +
+    `For modals, implement a focus trap that allows Escape to close the modal and restore focus. ` +
+    `Check for tabindex="-1" on wrapper elements that might steal focus.`,
+
+  // 2.4.1 Bypass Blocks
+  "2.4.1": (f) =>
+    `Add a skip navigation link. Insert a visually-hidden-until-focused link as the first element in <body>: ` +
+    `<a href="#main-content" class="sr-only focus:not-sr-only">Skip to main content</a>. ` +
+    `Add id="main-content" to the <main> element. Also add ARIA landmark roles (nav, main, complementary).`,
+
+  // 2.4.2 Page Titled
+  "2.4.2": (f) =>
+    `Add a descriptive <title> to this page. ` +
+    `The title should be unique and describe the page's topic or purpose. ` +
+    `Format: "Page Name — Site Name" or "Page Name | Site Name".`,
+
+  // 2.4.3 Focus Order
+  "2.4.3": (f) =>
+    `Fix the focus order at "${f.selector}". ` +
+    `Remove positive tabindex values (tabindex="2", etc.) — use tabindex="0" for natural order. ` +
+    `Rearrange DOM order to match the visual layout. ` +
+    `Focus should follow a logical, predictable sequence.`,
+
+  // 2.4.4 Link Purpose
+  "2.4.4": (f) =>
+    `Fix the link at "${f.selector}" — it needs a descriptive accessible name. ` +
+    `Add meaningful link text (not "click here" or "read more"). ` +
+    `For icon-only links, add aria-label="Description of destination". ` +
+    `For image-only links, add alt text to the image.`,
+
+  // 2.4.7 Focus Visible
+  "2.4.7": (f) =>
+    `Add a visible focus indicator to "${f.selector}". ` +
+    `Don't use outline: none without providing an alternative focus style. ` +
+    `Use CSS: :focus-visible { outline: 2px solid #005fcc; outline-offset: 2px; }. ` +
+    `The focus indicator must have at least 3:1 contrast.`,
+
+  // 2.5.3 Label in Name
+  "2.5.3": (f) =>
+    `Fix the accessible name at "${f.selector}". ` +
+    `The accessible name (aria-label or text content) must contain the visible label text. ` +
+    `If the button shows "Submit", don't set aria-label="Send form" — use aria-label="Submit form" instead.`,
+
+  // 2.5.8 Target Size (Minimum)
+  "2.5.8": (f) =>
+    `Increase the touch target size at "${f.selector}". ` +
+    `Interactive elements must be at least 24×24 CSS pixels. ` +
+    `Add padding, min-width/min-height, or use the CSS target-size property.`,
+
+  // 3.1.1 Language of Page
+  "3.1.1": (f) =>
+    `Add the lang attribute to the <html> element: <html lang="en">. ` +
+    `Use the correct ISO 639-1 language code for the page's primary language.`,
+
+  // 3.1.2 Language of Parts
+  "3.1.2": (f) =>
+    `Add lang attribute to the element at "${f.selector}" that contains text in a different language. ` +
+    `Example: <span lang="fr">Bonjour</span>. Use ISO 639-1 codes.`,
+
+  // 3.3.1 Error Identification
+  "3.3.1": (f) =>
+    `Add error identification to the form at "${f.selector}". ` +
+    `When validation fails: (1) describe the error in text near the field, ` +
+    `(2) set aria-invalid="true" on the field, ` +
+    `(3) use aria-describedby to associate error text, ` +
+    `(4) announce errors via aria-live="polite" region.`,
+
+  // 3.3.2 Labels or Instructions
+  "3.3.2": (f) =>
+    `Add a label to the form field at "${f.selector}". ` +
+    `Use <label for="field-id">Label text</label> associated via matching id. ` +
+    `Or use aria-label or aria-labelledby for custom controls.`,
+
+  // 4.1.1 Parsing (removed in 2.2 but still flagged)
+  "4.1.1": (f) =>
+    `Fix duplicate IDs at "${f.selector}". ` +
+    `Every id attribute must be unique within the document. ` +
+    `Search for duplicate id values and rename them.`,
+
+  // 4.1.2 Name, Role, Value
+  "4.1.2": (f) =>
+    `Fix the accessible name, role, or state at "${f.selector}". ` +
+    `Custom controls need: (1) an accessible name via aria-label or aria-labelledby, ` +
+    `(2) an appropriate role (button, link, checkbox, etc.), ` +
+    `(3) correct state attributes (aria-expanded, aria-checked, aria-selected). ` +
+    `Or use native HTML elements which have these built-in.`,
+};
+
+// ─── Generic fix prompt for criteria without specific templates ─────
+function genericFixPrompt(f) {
+  const parts = [
+    `Fix WCAG ${f.criteria} (${f.level}) violation at "${f.selector}".`,
+  ];
+  if (f.description) parts.push(`Issue: ${f.description}`);
+  if (f.help) parts.push(`Suggested fix: ${f.help}`);
+  if (f.helpUrl) parts.push(`Reference: ${f.helpUrl}`);
+  return parts.join("\n");
+}
+
+// ─── Build the fix prompt for a single finding ──────────────────────
+function buildFixPrompt(f) {
+  // Try each criterion in the comma-separated list
+  const criteria = String(f.criteria || "")
+    .split(",")
+    .map((s) => s.trim());
+  for (const c of criteria) {
+    if (CRITERION_FIX_TEMPLATES[c]) {
+      return CRITERION_FIX_TEMPLATES[c](f);
+    }
+  }
+  return genericFixPrompt(f);
+}
+
+// ─── Build structured fix context ───────────────────────────────────
+function buildFixContext(f) {
+  return {
+    element: f.selector || null,
+    htmlSnippet: (f.evidence || f.htmlSnippet || "").slice(0, 1000) || null,
+    failureSummary: f.failureSummary || null,
+    wcagCriterion: f.criteria || null,
+    wcagLevel: f.level || null,
+    severity: f.impact || null,
+    source: f.source || null,
+    ruleId: f.ruleId || null,
+    referenceUrl: f.helpUrl || null,
+  };
+}
+
+// ─── Generate the AI fix JSON ───────────────────────────────────────
+export function generateAiFixJson({ findings, meta }) {
+  const issues = findings.map((f) => ({
+    issueNumber: f.issueNumber,
+    ruleId: f.ruleId,
+    criteria: f.criteria,
+    level: f.level,
+    severity: f.impact,
+    source: f.source,
+    description: f.description,
+    selector: f.selector || "",
+    evidence: (f.evidence || f.htmlSnippet || "").slice(0, 1000),
+    helpUrl: f.helpUrl || "",
+    fixPrompt: buildFixPrompt(f),
+    fixContext: buildFixContext(f),
+  }));
+
+  return {
+    $schema: "https://wcagaudit.io/schemas/ai-fix-v1.json",
+    version: "1.0.0",
+    generatedAt: new Date().toISOString(),
+    meta: {
+      url: meta.url,
+      timestamp: meta.startedAt || meta.timestamp || new Date().toISOString(),
+      wcagVersion: meta.wcagVersion || meta.version || "2.2",
+      levels: meta.levels || [],
+      totalIssues: findings.length,
+      bySeverity: {
+        critical: findings.filter((f) => f.impact === "critical").length,
+        serious: findings.filter((f) => f.impact === "serious").length,
+        moderate: findings.filter((f) => f.impact === "moderate").length,
+        minor: findings.filter((f) => f.impact === "minor").length,
+      },
+      bySource: {
+        axe: findings.filter((f) => f.source === "axe").length,
+        playwright: findings.filter(
+          (f) => f.source === "playwright" || f.source === "playwright-eq"
+        ).length,
+        ai: findings.filter((f) => f.source === "ai").length,
+        cloud: findings.filter((f) =>
+          String(f.source || "").startsWith("cloud")
+        ).length,
+      },
+    },
+    systemPrompt:
+      "You are an accessibility remediation expert. You will receive a list of WCAG violations " +
+      "found on a web page. For each issue, use the fixPrompt and fixContext to generate " +
+      "the exact code changes needed to fix the violation. Output your fixes as a JSON array " +
+      "of objects with: { issueNumber, filePath (if known), originalCode, fixedCode, explanation }. " +
+      "Prioritize critical and serious issues first. Always use semantic HTML over ARIA when possible.",
+    issues,
+  };
+}
+
+// ─── Write to disk ──────────────────────────────────────────────────
+export async function writeAiFixJson({ findings, meta, outPath }) {
+  const json = generateAiFixJson({ findings, meta });
+  await fs.mkdir(path.dirname(path.resolve(outPath)), { recursive: true });
+  await fs.writeFile(outPath, JSON.stringify(json, null, 2), "utf-8");
+  return json;
+}