wcag-a11y 0.3.3 → 0.3.5

package/README.md

@@ -2,9 +2,11 @@
 
 [![CI](https://github.com/Dannyplusplus12/WCAG-A11y/actions/workflows/ci.yml/badge.svg)](https://github.com/Dannyplusplus12/WCAG-A11y/actions/workflows/ci.yml)
 
-Most accessibility auditors stop at detection — they tell you *what* is broken and leave the rest to you. `wcag-a11y` goes further. It crawls your running dev server with Playwright, runs 40+ WCAG 2.1/2.2 checks, and uses AI to generate a ready-to-paste fix prompt for each violation. You paste it into Cursor, Copilot, or Claude and the fix writes itself.
+Most accessibility auditors stop at detection — they tell you *what* is broken and leave the rest to you. `wcag-a11y` goes further. It crawls your running dev server with Playwright, runs 40+ WCAG 2.1/2.2 checks, and uses AI to generate ready-to-paste fix prompts **or write the fixes directly into your source files**.
 
-The goal is to close the loop between finding an accessibility issue and actually fixing it, without interrupting your existing workflow.
+Two modes:
+- **`scan`** — find violations + generate AI prompts you paste into Cursor, Copilot, or Claude
+- **`fix`** — find violations + patch source files automatically (dry-run by default, `--apply` to write)
 
 ---
 
@@ -140,6 +142,60 @@ wcag-a11y scan -u http://localhost:3000 --no-ai --ci
 
 ---
 
+### `wcag-a11y fix`
+
+Scan for violations and apply AI-generated patches directly to your source files. Works with any framework — React, Vue, Angular, Svelte, or plain HTML.
+
+```bash
+# Dry-run: scan and show what would change (safe, no files written)
+wcag-a11y fix -u http://localhost:3000
+
+# Preview specific pages
+wcag-a11y fix -u http://localhost:3000 --pages / /about /contact
+
+# Write fixes to disk
+wcag-a11y fix -u http://localhost:3000 --apply
+
+# Auto-discover pages + write fixes
+wcag-a11y fix -u http://localhost:3000 --crawl --apply
+```
+
+**How it works:**
+
+1. Runs the same scan as `wcag-a11y scan`
+2. For each violation, locates the source file — checks `violation.source` (React dev mode) first, then falls back to grepping `./src` for unique identifiers in the HTML snippet (`id=`, `name=`, `for=`, local `src=`, text content)
+3. Groups violations by file (multiple violations in the same file → one AI call)
+4. Sends the full file content + violation list to your configured AI provider and asks for the corrected file
+5. Shows a colored diff before writing anything
+6. With `--apply`, overwrites the file; without it, only prints the diff
+
+```
+src/components/Navbar.jsx — 2 violation(s)
+  · [button-name] Buttons must have an accessible name
+  · [aria-valid-role] Elements must use valid ARIA roles
+
+  Requesting AI patch... done
+  +2 -1
+    <nav className="navbar">
+  -   <button onClick={toggle}><MenuIcon /></button>
+  +   <button onClick={toggle} aria-label="Toggle navigation"><MenuIcon /></button>
+      <ul role="navigation">
+  -     <li role="listbox">Home</li>
+  +     <li>Home</li>
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `-u, --url <url>` | required | Base URL of your running dev server |
+| `-p, --pages <pages...>` | `/` | Specific pages to scan |
+| `-c, --crawl` | off | Auto-discover pages by following same-origin links |
+| `--apply` | off | Write patched files to disk (dry-run without this flag) |
+| `--provider <name>` | from config | Override AI provider for this run: `gemini`, `openai`, or `ollama` |
+
+> **Tip:** Always run without `--apply` first to review the diff. The dry-run is safe — nothing is written to disk.
+
+---
+
 ## AI Providers
 
 | Provider | Model | Cost | API Key |

package/dist/ai/gemini.js

@@ -1,4 +1,5 @@
 import { buildPrompt } from './prompt.js';
+import { buildPatchPrompt } from './patch-prompt.js';
 import { groupViolations } from './group.js';
 import { fallbackExplanation } from './fallback-explanation.js';
 export class GeminiProvider {
@@ -8,11 +9,11 @@ export class GeminiProvider {
         this.apiKey = apiKey;
         this.model = model;
     }
-    async generateFixes(violations, strategy = 'rule') {
+    async generateFixes(violations, strategy = 'rule', framework) {
         if (violations.length === 0)
             return [];
         const groups = groupViolations(violations, strategy);
-        const prompt = buildPrompt(groups);
+        const prompt = buildPrompt(groups, framework);
         const url = `https://generativelanguage.googleapis.com/v1beta/models/${this.model}:generateContent?key=${this.apiKey}`;
         const response = await fetch(url, {
             method: 'POST',
@@ -27,9 +28,25 @@ export class GeminiProvider {
         }
         const data = await response.json();
         const text = data.candidates?.[0]?.content?.parts?.[0]?.text ?? '[]';
-        return this.parse(text, groups);
+        return this.parse(text, groups, framework);
     }
-    parse(text, groups) {
+    async generateFilePatch(fileContent, violations, filePath, framework) {
+        const prompt = buildPatchPrompt(fileContent, violations, filePath, framework);
+        const url = `https://generativelanguage.googleapis.com/v1beta/models/${this.model}:generateContent?key=${this.apiKey}`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                contents: [{ parts: [{ text: prompt }] }],
+                generationConfig: { temperature: 0.1, maxOutputTokens: 16384 },
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Gemini API error: ${response.status} ${await response.text()}`);
+        const data = await response.json();
+        return data.candidates?.[0]?.content?.parts?.[0]?.text ?? '';
+    }
+    parse(text, groups, framework) {
         try {
             const jsonMatch = text.match(/\[[\s\S]*\]/);
             const fixes = jsonMatch ? JSON.parse(jsonMatch[0]) : [];
@@ -37,20 +54,21 @@ export class GeminiProvider {
                 const found = fixes.find((f) => f.ruleId === g.ruleId);
                 return found
                     ? { ...found, selectors: g.selectors, instanceCount: g.count }
-                    : this.fallbackFix(g);
+                    : this.fallbackFix(g, framework);
             });
         }
         catch {
-            return groups.map((g) => this.fallbackFix(g));
+            return groups.map((g) => this.fallbackFix(g, framework));
         }
     }
-    fallbackFix(g) {
+    fallbackFix(g, framework) {
         const v = g.representative;
         const selectorList = g.selectors.map((s) => `- ${s}`).join('\n');
         const explanation = fallbackExplanation(g.ruleId, g.description, g.wcag, g.level);
+        const fwNote = framework ? `This project uses ${framework}. ` : '';
         const prompt = g.count > 1
-            ? `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected elements (${g.count} instances):\n${selectorList}\n\nRepresentative HTML:\n\`${v.html.slice(0, 300)}\`\n\nApply the fix to all ${g.count} instances in the codebase to comply with WCAG 2.1 SC ${g.wcag}.`
-            : `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected element:\n- Selector: \`${g.selectors[0]}\`\n- HTML: \`${v.html.slice(0, 300)}\`\n\nApply the fix to comply with WCAG 2.1 SC ${g.wcag}.`;
+            ? `${fwNote}Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected elements (${g.count} instances):\n${selectorList}\n\nRepresentative HTML:\n\`${v.html.slice(0, 300)}\`\n\nApply the fix to all ${g.count} instances in the codebase to comply with WCAG 2.1 SC ${g.wcag}.`
+            : `${fwNote}Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected element:\n- Selector: \`${g.selectors[0]}\`\n- HTML: \`${v.html.slice(0, 300)}\`\n\nApply the fix to comply with WCAG 2.1 SC ${g.wcag}.`;
         return {
             ruleId: g.ruleId,
             selectors: g.selectors,

package/dist/ai/ollama.js

@@ -1,4 +1,5 @@
 import { buildPrompt } from './prompt.js';
+import { buildPatchPrompt } from './patch-prompt.js';
 import { groupViolations } from './group.js';
 import { fallbackExplanation } from './fallback-explanation.js';
 export class OllamaProvider {
@@ -8,11 +9,11 @@ export class OllamaProvider {
         this.baseUrl = baseUrl;
         this.model = model;
     }
-    async generateFixes(violations, strategy = 'rule') {
+    async generateFixes(violations, strategy = 'rule', framework) {
         if (violations.length === 0)
             return [];
         const groups = groupViolations(violations, strategy);
-        const prompt = buildPrompt(groups);
+        const prompt = buildPrompt(groups, framework);
         const response = await fetch(`${this.baseUrl}/api/generate`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
@@ -26,29 +27,42 @@ export class OllamaProvider {
         try {
             const jsonMatch = text.match(/\[[\s\S]*\]/);
             if (!jsonMatch)
-                return this.fallback(groups);
+                return this.fallback(groups, framework);
             const fixes = JSON.parse(jsonMatch[0]);
             return groups.map((g) => {
                 const found = fixes.find((f) => f.ruleId === g.ruleId);
                 return found
                     ? { ...found, selectors: g.selectors, instanceCount: g.count }
-                    : this.fallbackFix(g);
+                    : this.fallbackFix(g, framework);
             });
         }
         catch {
-            return this.fallback(groups);
+            return this.fallback(groups, framework);
         }
     }
-    fallback(groups) {
-        return groups.map((g) => this.fallbackFix(g));
+    async generateFilePatch(fileContent, violations, filePath, framework) {
+        const prompt = buildPatchPrompt(fileContent, violations, filePath, framework);
+        const response = await fetch(`${this.baseUrl}/api/generate`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ model: this.model, prompt, stream: false }),
+        });
+        if (!response.ok)
+            throw new Error(`Ollama error: ${response.status}. Is Ollama running? Run: ollama serve`);
+        const data = await response.json();
+        return data.response ?? '';
+    }
+    fallback(groups, framework) {
+        return groups.map((g) => this.fallbackFix(g, framework));
     }
-    fallbackFix(g) {
+    fallbackFix(g, framework) {
         const v = g.representative;
         const selectorList = g.selectors.map((s) => `- ${s}`).join('\n');
         const explanation = fallbackExplanation(g.ruleId, g.description, g.wcag, g.level);
+        const fwNote = framework ? `This project uses ${framework}. ` : '';
         const prompt = g.count > 1
-            ? `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected elements (${g.count} instances):\n${selectorList}\n\nRepresentative HTML:\n\`${v.html.slice(0, 300)}\`\n\nApply the fix to all ${g.count} instances in the codebase to comply with WCAG 2.1 SC ${g.wcag}.`
-            : `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected element:\n- Selector: \`${g.selectors[0]}\`\n- HTML: \`${v.html.slice(0, 300)}\`\n\nApply the fix to comply with WCAG 2.1 SC ${g.wcag}.`;
+            ? `${fwNote}Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected elements (${g.count} instances):\n${selectorList}\n\nRepresentative HTML:\n\`${v.html.slice(0, 300)}\`\n\nApply the fix to all ${g.count} instances in the codebase to comply with WCAG 2.1 SC ${g.wcag}.`
+            : `${fwNote}Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected element:\n- Selector: \`${g.selectors[0]}\`\n- HTML: \`${v.html.slice(0, 300)}\`\n\nApply the fix to comply with WCAG 2.1 SC ${g.wcag}.`;
         return {
             ruleId: g.ruleId,
             selectors: g.selectors,

package/dist/ai/openai.js

@@ -1,4 +1,5 @@
 import { buildPrompt } from './prompt.js';
+import { buildPatchPrompt } from './patch-prompt.js';
 import { groupViolations } from './group.js';
 import { fallbackExplanation } from './fallback-explanation.js';
 export class OpenAIProvider {
@@ -8,11 +9,11 @@ export class OpenAIProvider {
         this.apiKey = apiKey;
         this.model = model;
     }
-    async generateFixes(violations, strategy = 'rule') {
+    async generateFixes(violations, strategy = 'rule', framework) {
         if (violations.length === 0)
             return [];
         const groups = groupViolations(violations, strategy);
-        const prompt = buildPrompt(groups);
+        const prompt = buildPrompt(groups, framework);
         const response = await fetch('https://api.openai.com/v1/chat/completions', {
             method: 'POST',
             headers: {
@@ -31,9 +32,26 @@ export class OpenAIProvider {
         }
         const data = await response.json();
         const text = data.choices?.[0]?.message?.content ?? '[]';
-        return this.parse(text, groups);
+        return this.parse(text, groups, framework);
     }
-    parse(text, groups) {
+    async generateFilePatch(fileContent, violations, filePath, framework) {
+        const prompt = buildPatchPrompt(fileContent, violations, filePath, framework);
+        const response = await fetch('https://api.openai.com/v1/chat/completions', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this.apiKey}` },
+            body: JSON.stringify({
+                model: this.model,
+                messages: [{ role: 'user', content: prompt }],
+                temperature: 0.1,
+                max_tokens: 16384,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`OpenAI API error: ${response.status} ${await response.text()}`);
+        const data = await response.json();
+        return data.choices?.[0]?.message?.content ?? '';
+    }
+    parse(text, groups, framework) {
         try {
             const jsonMatch = text.match(/\[[\s\S]*\]/);
             const fixes = jsonMatch ? JSON.parse(jsonMatch[0]) : [];
@@ -41,20 +59,21 @@ export class OpenAIProvider {
                 const found = fixes.find((f) => f.ruleId === g.ruleId);
                 return found
                     ? { ...found, selectors: g.selectors, instanceCount: g.count }
-                    : this.fallbackFix(g);
+                    : this.fallbackFix(g, framework);
             });
         }
         catch {
-            return groups.map((g) => this.fallbackFix(g));
+            return groups.map((g) => this.fallbackFix(g, framework));
         }
     }
-    fallbackFix(g) {
+    fallbackFix(g, framework) {
         const v = g.representative;
         const selectorList = g.selectors.map((s) => `- ${s}`).join('\n');
         const explanation = fallbackExplanation(g.ruleId, g.description, g.wcag, g.level);
+        const fwNote = framework ? `This project uses ${framework}. ` : '';
         const prompt = g.count > 1
-            ? `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected elements (${g.count} instances):\n${selectorList}\n\nRepresentative HTML:\n\`${v.html.slice(0, 300)}\`\n\nApply the fix to all ${g.count} instances in the codebase to comply with WCAG 2.1 SC ${g.wcag}.`
-            : `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected element:\n- Selector: \`${g.selectors[0]}\`\n- HTML: \`${v.html.slice(0, 300)}\`\n\nApply the fix to comply with WCAG 2.1 SC ${g.wcag}.`;
+            ? `${fwNote}Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected elements (${g.count} instances):\n${selectorList}\n\nRepresentative HTML:\n\`${v.html.slice(0, 300)}\`\n\nApply the fix to all ${g.count} instances in the codebase to comply with WCAG 2.1 SC ${g.wcag}.`
+            : `${fwNote}Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected element:\n- Selector: \`${g.selectors[0]}\`\n- HTML: \`${v.html.slice(0, 300)}\`\n\nApply the fix to comply with WCAG 2.1 SC ${g.wcag}.`;
         return {
             ruleId: g.ruleId,
             selectors: g.selectors,

package/dist/ai/patch-prompt.js

@@ -0,0 +1,16 @@
+export function buildPatchPrompt(fileContent, violations, filePath, framework) {
+    const fwLine = framework ? `\nFramework: ${framework}` : '';
+    const vList = violations
+        .map((v, i) => `${i + 1}. [${v.ruleId}] WCAG ${v.wcag} Level ${v.level} — ${v.description}\n   Selector: ${v.selector}\n   HTML: ${v.html.slice(0, 300)}`)
+        .join('\n\n');
+    return `You are a WCAG accessibility expert. Fix the accessibility violations in the source file below.
+Return ONLY the complete fixed file content — no markdown fences, no explanations, no preamble.
+
+File: ${filePath}${fwLine}
+
+Violations to fix:
+${vList}
+
+FILE CONTENT:
+${fileContent}`;
+}

package/dist/ai/prompt.js

@@ -1,4 +1,16 @@
-export function buildPrompt(groups) {
+const FRAMEWORK_SYNTAX = {
+    'Next.js': 'React/TSX (JSX)',
+    'Gatsby': 'React/JSX',
+    'Remix': 'React/TSX',
+    'Nuxt.js': 'Vue 3 SFC (.vue files)',
+    'Vue 3': 'Vue 3 SFC (.vue files)',
+    'Vue 2': 'Vue 2 SFC (.vue files)',
+    'Angular': 'Angular template',
+    'React': 'React JSX/TSX',
+    'Svelte': 'Svelte (.svelte files)',
+};
+export function buildPrompt(groups, framework) {
+    const syntax = framework ? (FRAMEWORK_SYNTAX[framework] ?? 'JSX/TSX') : null;
     const items = groups
         .map((g, i) => `${i + 1}. Rule: ${g.ruleId} | WCAG ${g.wcag} (Level ${g.level}) | Impact: ${g.impact}
    Page: ${g.page}
@@ -7,14 +19,23 @@ export function buildPrompt(groups) {
    Representative Element: ${g.representative.html}
    Problem: ${g.description}`)
         .join('\n\n');
-    return `You are a WCAG accessibility expert. Analyze these violations and return a JSON array.
+    const frameworkLine = framework
+        ? `\nFramework: ${framework}. All "fixedCode" values must use ${syntax} syntax — not raw HTML.\n`
+        : '';
+    const fixedCodeInstruction = syntax
+        ? `"fixedCode": the corrected snippet in ${syntax} syntax (component/template code only — no imports, no surrounding boilerplate)`
+        : `"fixedCode": the corrected HTML snippet only (no explanation, just code)`;
+    const optimalPromptInstruction = framework
+        ? `"optimalPrompt": a ready-to-paste prompt for an AI coding assistant (Cursor, Copilot, Claude) working in a ${framework} codebase. Structure it as: (1) state the WCAG 2.1/2.2 criterion being violated, (2) list the affected selectors and HTML snippets, (3) state the exact change needed in ${syntax} syntax. Focus solely on the fix.`
+        : `"optimalPrompt": a ready-to-paste prompt for an AI coding assistant (Cursor, Copilot, Claude). Structure it as: (1) state the WCAG 2.1/2.2 criterion being violated, (2) list the affected selectors and HTML snippets, (3) state the exact change needed. Focus solely on the fix.`;
+    return `You are a WCAG accessibility expert. Analyze these violations and return a JSON array.${frameworkLine}
 Each item must have:
 - "ruleId": the rule id from the input
 - "selectors": array of CSS selectors affected (copy from input)
-- "explanation": 1-2 sentences on concrete user impact — name exactly who is affected (e.g. "screen reader users", "keyboard-only users", "users with low vision") and what they cannot do because of this specific violation. Do not write generic statements like "users with disabilities may be affected."
-- "fixedCode": the corrected HTML snippet only (no explanation, just code)
+- "explanation": 1-2 sentences on concrete user impact — name exactly who is affected (e.g. "screen reader users", "keyboard-only users", "users with low vision") and what they cannot do because of this specific violation. Do not write generic statements.
+- ${fixedCodeInstruction}
 - "wcagReference": the full criterion name, e.g. "WCAG 2.1 SC 1.1.1 Non-text Content (Level A)"
-- "optimalPrompt": a ready-to-paste prompt for an AI coding assistant (Cursor, Copilot, Claude). Structure it as: (1) state the WCAG 2.1/2.2 criterion being violated (e.g. "WCAG 2.1 SC 1.1.1 Non-text Content, Level A"), (2) list the affected selectors and HTML snippets, (3) state the exact code change needed to comply. Focus solely on the fix — do not explain why WCAG exists or what accessibility is. Be precise and actionable.
+- ${optimalPromptInstruction}
 
 Return ONLY a valid JSON array. No markdown, no code fences, no explanation outside the JSON.
 

package/dist/cli.js

@@ -7,11 +7,13 @@ import { groupViolations } from './ai/group.js';
 import { printTerminalReport, printAIPrompts } from './reporter/terminal.js';
 import { generateMarkdownReport } from './reporter/markdown.js';
 import { runDemo } from './demo.js';
+import { runFix } from './fixer.js';
+import { resolve } from 'path';
 const program = new Command();
 program
     .name('wcag-a11y')
     .description('WCAG 2.1/2.2 accessibility auditor with AI-powered fixes')
-    .version('0.3.3');
+    .version('0.3.5');
 program
     .command('init')
     .description('Create a11y.config.json in the current directory')
@@ -25,10 +27,10 @@ program
     .requiredOption('-u, --url <url>', 'Base URL of your dev server (e.g. http://localhost:3000)')
     .option('-p, --pages <pages...>', 'Specific pages to scan (e.g. / /about /contact)', ['/'])
     .option('-c, --crawl', 'Auto-discover pages by following same-origin links', false)
-    .option('-r, --report', 'Save a full markdown report to a11y-report.md', false)
+    .option('--no-report', 'Skip saving markdown report to a11y-report.md')
     .option('--no-ai', 'Skip AI fix generation (faster, violations only)')
     .option('--no-explain', 'Hide AI fix explanations in terminal output')
-    .option('--no-terminal', 'Suppress terminal output (violations summary)')
+    .option('--terminal', 'Print violations summary to terminal', false)
     .option('--fast-mode', 'Output only AI fix prompts — no summaries or explanations', false)
     .option('--group <strategy>', 'Group violations by rule or show individually (rule|none)', 'rule')
     .option('--ci', 'Exit with code 1 if any violations are found (for CI/CD pipelines)', false)
@@ -52,7 +54,7 @@ program
             if (!opts.fastMode) {
                 console.log(`\nGenerating AI fixes for ${ruleGroups.length} rule groups (${allViolations.length} violations)...`);
             }
-            const fixes = await provider.generateFixes(allViolations, strategy);
+            const fixes = await provider.generateFixes(allViolations, strategy, result.framework);
             if (opts.terminal) {
                 printAIPrompts(fixes, { explain: opts.explain, fastMode: opts.fastMode });
             }
@@ -72,10 +74,38 @@ program
         process.exit(1);
     }
 });
+program
+    .command('fix')
+    .description('Scan for violations and apply AI fixes directly to source files')
+    .requiredOption('-u, --url <url>', 'Base URL of your dev server (e.g. http://localhost:3000)')
+    .option('-p, --pages <pages...>', 'Specific pages to scan', ['/'])
+    .option('-c, --crawl', 'Auto-discover pages by following same-origin links', false)
+    .option('--apply', 'Write fixes to source files (default: dry-run, shows diff only)', false)
+    .option('--provider <name>', 'Override the AI provider from config (gemini|openai|ollama)')
+    .action(async (opts) => {
+    try {
+        const config = loadConfig();
+        if (opts.provider)
+            config.provider = opts.provider;
+        const provider = createAIProvider(config);
+        await runFix({
+            url: opts.url,
+            pages: opts.pages,
+            crawl: opts.crawl,
+            apply: opts.apply,
+            provider,
+            srcDir: resolve(process.cwd(), 'src'),
+        });
+    }
+    catch (err) {
+        console.error(`\nError: ${err.message}`);
+        process.exit(1);
+    }
+});
 program
     .command('demo')
     .description('Scan a built-in demo page with intentional violations — no dev server needed')
-    .option('-r, --report', 'Save a full markdown report to a11y-report.md', false)
+    .option('--no-report', 'Skip saving markdown report to a11y-report.md')
     .option('--no-ai', 'Skip AI fix generation (faster, violations only)')
     .action(async (opts) => {
     try {

package/dist/crawler.js

@@ -1,5 +1,43 @@
 import { chromium } from 'playwright';
 import { scanPage } from './engine/index.js';
+async function detectFramework(page) {
+    try {
+        return await page.evaluate(() => {
+            const w = window;
+            if (w['__NEXT_DATA__'])
+                return 'Next.js';
+            if (w['___gatsby'])
+                return 'Gatsby';
+            if (w['__remixContext'])
+                return 'Remix';
+            if (w['__nuxt'] || w['$nuxt'])
+                return 'Nuxt.js';
+            if (w['__vue_app__'])
+                return 'Vue 3';
+            if (w['Vue'])
+                return 'Vue 2';
+            if (document.querySelector('[ng-version]') !== null)
+                return 'Angular';
+            // React: hook is registered by react-dom on load (most reliable, works with Vite HMR)
+            if (w['__REACT_DEVTOOLS_GLOBAL_HOOK__'])
+                return 'React';
+            // React fallback: fiber properties on root element
+            const root = document.getElementById('root') ?? document.getElementById('app') ?? document.body;
+            if (root) {
+                const allKeys = Object.getOwnPropertyNames(root);
+                if (allKeys.some((k) => k.startsWith('__reactFiber') || k.startsWith('__reactContainer'))) {
+                    return 'React';
+                }
+            }
+            if (document.querySelector('[data-svelte-h]') !== null)
+                return 'Svelte';
+            return undefined;
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function crawl(options) {
     const { url, pages = ['/'], crawl: autoCrawl = false } = options;
     const baseUrl = url.replace(/\/$/, '');
@@ -23,10 +61,13 @@ export async function crawl(options) {
             }
         }
         const results = [];
+        let framework;
         for (const pageUrl of pagesToVisit) {
             const page = await context.newPage();
             try {
                 await page.goto(pageUrl, { waitUntil: 'networkidle', timeout: 30000 });
+                if (!framework)
+                    framework = await detectFramework(page);
                 const result = await scanPage(page, pageUrl);
                 results.push(result);
             }
@@ -46,6 +87,7 @@ export async function crawl(options) {
             seriousCount: allViolations.filter((v) => v.impact === 'serious').length,
             moderateCount: allViolations.filter((v) => v.impact === 'moderate').length,
             minorCount: allViolations.filter((v) => v.impact === 'minor').length,
+            framework,
         };
     }
     finally {

package/dist/demo.js

@@ -74,7 +74,7 @@ export async function runDemo(opts) {
             const provider = createAIProvider(config);
             const violations = result.pages.flatMap((p) => p.violations);
             console.log(`\nGenerating AI fixes for ${violations.length} violations...`);
-            const fixes = await provider.generateFixes(violations, 'rule');
+            const fixes = await provider.generateFixes(violations, 'rule', result.framework);
             printAIPrompts(fixes, { explain: true });
             if (opts.report)
                 generateMarkdownReport(result, fixes);

package/dist/engine/index.js

@@ -1,3 +1,42 @@
+async function resolveSourceLocations(page, violations) {
+    const selectors = [...new Set(violations.map((v) => v.selector))];
+    if (selectors.length === 0)
+        return;
+    try {
+        const sourceMap = await page.evaluate((sels) => {
+            const result = {};
+            for (const sel of sels) {
+                try {
+                    const el = document.querySelector(sel);
+                    if (!el)
+                        continue;
+                    const fiberKey = Object.getOwnPropertyNames(el).find((k) => k.startsWith('__reactFiber'));
+                    if (!fiberKey)
+                        continue;
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    let fiber = el[fiberKey];
+                    while (fiber) {
+                        if (fiber._debugSource) {
+                            const { fileName, lineNumber } = fiber._debugSource;
+                            const match = fileName.match(/[/\\]src[/\\].+/);
+                            const display = match ? match[0].replace(/\\/g, '/').replace(/^\//, '') : fileName;
+                            result[sel] = `${display}:${lineNumber}`;
+                            break;
+                        }
+                        fiber = fiber.return;
+                    }
+                }
+                catch { /* ignore */ }
+            }
+            return result;
+        }, selectors);
+        for (const v of violations) {
+            if (sourceMap[v.selector])
+                v.source = sourceMap[v.selector];
+        }
+    }
+    catch { /* non-React or production build — silently skip */ }
+}
 import { textAlternativeRules } from './rules/text-alternatives.js';
 import { colorContrastRules } from './rules/color-contrast.js';
 import { keyboardRules } from './rules/keyboard.js';
@@ -52,5 +91,6 @@ export async function scanPage(page, url) {
         });
         violations.push(...ruleViolations);
     }
+    await resolveSourceLocations(page, violations);
     return { url, violations };
 }

package/dist/fixer.js

@@ -0,0 +1,254 @@
+import { readFileSync, writeFileSync, readdirSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+import chalk from 'chalk';
+import { crawl } from './crawler.js';
+const SOURCE_EXTS = new Set(['.jsx', '.tsx', '.js', '.ts', '.vue', '.svelte', '.html']);
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git', '.next', '.nuxt', 'coverage', 'public']);
+export async function runFix(opts) {
+    console.log(`\nScanning ${opts.url}...`);
+    const result = await crawl({ url: opts.url, pages: opts.pages, crawl: opts.crawl });
+    const { framework } = result;
+    if (result.totalViolations === 0) {
+        console.log(chalk.green('\nNo violations found.'));
+        return;
+    }
+    console.log(`Found ${result.totalViolations} violation(s). Locating source files...\n`);
+    const allViolations = result.pages.flatMap((p) => p.violations);
+    // Group violations by resolved source file path
+    const fileGroups = new Map();
+    let unlocated = 0;
+    for (const violation of allViolations) {
+        const filePath = findSourceFile(violation, opts.srcDir);
+        if (!filePath) {
+            console.warn(chalk.yellow(`  warn: no source file for [${violation.ruleId}] ${violation.selector.slice(0, 60)}`));
+            unlocated++;
+            continue;
+        }
+        if (!fileGroups.has(filePath))
+            fileGroups.set(filePath, []);
+        fileGroups.get(filePath).push(violation);
+    }
+    if (fileGroups.size === 0) {
+        console.log(chalk.yellow('No source files located. Run from your project root and ensure sources are in ./src'));
+        return;
+    }
+    const locatedCount = allViolations.length - unlocated;
+    console.log(`Grouped ${locatedCount} violation(s) across ${fileGroups.size} file(s).\n`);
+    if (!opts.apply)
+        console.log(chalk.gray('Dry-run mode — use --apply to write changes.\n'));
+    let modifiedFiles = 0;
+    let modifiedViolations = 0;
+    for (const [filePath, violations] of fileGroups) {
+        const rel = relativize(filePath);
+        console.log(chalk.bold(`\n${rel}`) + chalk.gray(` — ${violations.length} violation(s)`));
+        for (const v of violations) {
+            console.log(chalk.gray(`  · [${v.ruleId}] ${v.description.slice(0, 80)}`));
+        }
+        let oldContent;
+        try {
+            oldContent = readFileSync(filePath, 'utf8');
+        }
+        catch {
+            console.warn(chalk.yellow(`  Cannot read file, skipping.`));
+            continue;
+        }
+        process.stdout.write('  Requesting AI patch...');
+        let rawResponse;
+        try {
+            rawResponse = await opts.provider.generateFilePatch(oldContent, violations, rel, framework);
+        }
+        catch (err) {
+            console.log('');
+            console.warn(chalk.yellow(`  AI error: ${err.message}`));
+            continue;
+        }
+        console.log(' done');
+        const newContent = stripCodeFences(rawResponse).trim();
+        if (!newContent || newContent.length < oldContent.length * 0.3) {
+            console.warn(chalk.yellow('  AI returned unexpected output, skipping.'));
+            continue;
+        }
+        const normalizedOld = oldContent.trim();
+        if (newContent === normalizedOld) {
+            console.log(chalk.gray('  No changes.'));
+            continue;
+        }
+        console.log(renderDiff(oldContent, newContent, rel));
+        if (opts.apply) {
+            writeFileSync(filePath, newContent + '\n', 'utf8');
+            console.log(chalk.green(`  Written.`));
+        }
+        modifiedFiles++;
+        modifiedViolations += violations.length;
+    }
+    // Summary
+    console.log('\n' + '─'.repeat(60));
+    if (modifiedFiles === 0) {
+        console.log(chalk.gray('No files changed.'));
+    }
+    else if (opts.apply) {
+        console.log(chalk.green.bold(`Fixed ${modifiedViolations} violation(s) across ${modifiedFiles} file(s).`));
+    }
+    else {
+        console.log(chalk.blue.bold(`Would fix ${modifiedViolations} violation(s) across ${modifiedFiles} file(s).`));
+        console.log(chalk.gray('Run with --apply to write changes to disk.'));
+    }
+    if (unlocated > 0) {
+        console.log(chalk.yellow(`${unlocated} violation(s) could not be located in source files.`));
+    }
+}
+export function findSourceFile(violation, srcDir) {
+    // Priority 1: React dev-mode source annotation
+    if (violation.source) {
+        const filePart = violation.source.split(':')[0];
+        for (const candidate of [resolve(process.cwd(), filePart), resolve(filePart)]) {
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    // Priority 2: grep src/ for unique attributes/text from the HTML snippet
+    for (const needle of extractNeedles(violation.html)) {
+        const hits = grepDir(srcDir, needle);
+        if (hits.length > 0)
+            return hits[0];
+    }
+    return null;
+}
+function extractNeedles(html) {
+    const results = [];
+    const id = html.match(/\bid=["']([^"']{2,})["']/)?.[1];
+    if (id)
+        results.push(`id="${id}"`);
+    const name = html.match(/\bname=["']([^"']{2,})["']/)?.[1];
+    if (name)
+        results.push(`name="${name}"`);
+    const forAttr = html.match(/\bfor=["']([^"']{2,})["']/)?.[1];
+    if (forAttr)
+        results.push(`for="${forAttr}"`);
+    // local src paths only
+    const src = html.match(/\bsrc=["'](?!https?:\/\/)([^"']{4,})["']/)?.[1];
+    if (src)
+        results.push(src);
+    const text = html.match(/>([^<\s][^<]{4,60})</)?.[1]?.trim();
+    if (text)
+        results.push(text);
+    // fallback: first meaningful class name
+    if (results.length === 0) {
+        const cls = html.match(/\bclass=["']([^"']+)["']/)?.[1]?.split(/\s+/)[0];
+        if (cls && cls.length > 3)
+            results.push(cls);
+    }
+    return results.filter((s) => s.length >= 3);
+}
+function grepDir(dir, needle) {
+    if (!existsSync(dir))
+        return [];
+    const hits = [];
+    try {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name))
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                hits.push(...grepDir(full, needle));
+            }
+            else if (entry.isFile() && SOURCE_EXTS.has(extOf(entry.name))) {
+                try {
+                    if (readFileSync(full, 'utf8').includes(needle))
+                        hits.push(full);
+                }
+                catch { /* skip */ }
+            }
+        }
+    }
+    catch { /* skip unreadable dirs */ }
+    return hits;
+}
+function extOf(name) {
+    const i = name.lastIndexOf('.');
+    return i >= 0 ? name.slice(i) : '';
+}
+function stripCodeFences(text) {
+    const m = text.match(/^```[\w]*\n([\s\S]*?)\n?```\s*$/);
+    if (m)
+        return m[1];
+    return text.replace(/^```[\w]*\n?/, '').replace(/\n?```\s*$/, '');
+}
+function relativize(absPath) {
+    const cwd = process.cwd();
+    return absPath.startsWith(cwd)
+        ? absPath.slice(cwd.length + 1).replace(/\\/g, '/')
+        : absPath.replace(/\\/g, '/');
+}
+function computeDiff(a, b) {
+    // Cap to avoid O(n²) freeze on huge files
+    if (a.length * b.length > 800_000) {
+        return [
+            ...a.map((line) => ({ type: 'del', line })),
+            ...b.map((line) => ({ type: 'add', line })),
+        ];
+    }
+    const m = a.length, n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++)
+        for (let j = 1; j <= n; j++)
+            dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] + 1 : Math.max(dp[i - 1][j], dp[i][j - 1]);
+    const result = [];
+    let i = m, j = n;
+    while (i > 0 || j > 0) {
+        if (i > 0 && j > 0 && a[i - 1] === b[j - 1]) {
+            result.unshift({ type: 'eq', line: a[i - 1] });
+            i--;
+            j--;
+        }
+        else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
+            result.unshift({ type: 'add', line: b[j - 1] });
+            j--;
+        }
+        else {
+            result.unshift({ type: 'del', line: a[i - 1] });
+            i--;
+        }
+    }
+    return result;
+}
+function renderDiff(oldContent, newContent, _filePath) {
+    const a = oldContent.split('\n');
+    const b = newContent.split('\n');
+    const diff = computeDiff(a, b);
+    const changeIdxs = [];
+    for (let k = 0; k < diff.length; k++)
+        if (diff[k].type !== 'eq')
+            changeIdxs.push(k);
+    if (changeIdxs.length === 0)
+        return chalk.gray('  (no changes)');
+    const CONTEXT = 3;
+    const hunks = [];
+    for (const idx of changeIdxs) {
+        const start = Math.max(0, idx - CONTEXT);
+        const end = Math.min(diff.length - 1, idx + CONTEXT);
+        const last = hunks[hunks.length - 1];
+        if (!last || start > last.end + 1)
+            hunks.push({ start, end });
+        else
+            last.end = Math.max(last.end, end);
+    }
+    const addCount = changeIdxs.filter((i) => diff[i].type === 'add').length;
+    const delCount = changeIdxs.filter((i) => diff[i].type === 'del').length;
+    const lines = [];
+    lines.push(`  ${chalk.green(`+${addCount}`)} ${chalk.red(`-${delCount}`)}`);
+    for (let h = 0; h < hunks.length; h++) {
+        if (h > 0)
+            lines.push(chalk.gray('    ...'));
+        for (let k = hunks[h].start; k <= hunks[h].end; k++) {
+            const { type, line } = diff[k];
+            if (type === 'add')
+                lines.push(chalk.green(`  + ${line}`));
+            else if (type === 'del')
+                lines.push(chalk.red(`  - ${line}`));
+            else
+                lines.push(chalk.gray(`    ${line}`));
+        }
+    }
+    return lines.join('\n');
+}

package/dist/reporter/markdown.js

@@ -63,11 +63,13 @@ function buildFullReport(result, fixes) {
             const v = group[0];
             const fix = fixes.find((f) => f.ruleId === v.ruleId);
             const others = group.slice(1);
-            lines.push(`### ${IMPACT_EMOJI[v.impact] ?? '⚪'} [${v.impact.toUpperCase()}] ${v.description}`, '', `**Rule:** \`${v.ruleId}\`  `, `**WCAG:** ${fix?.wcagReference ?? `SC ${v.wcag} (Level ${v.level})`}  `, `**Instances:** ${group.length}`, '', '**Representative element:**', `\`${v.selector}\``, '```html', v.html, '```', '');
+            const sourceRef = v.source ? ` — \`${v.source}\`` : '';
+            lines.push(`### ${IMPACT_EMOJI[v.impact] ?? '⚪'} [${v.impact.toUpperCase()}] ${v.description}`, '', `**Rule:** \`${v.ruleId}\`  `, `**WCAG:** ${fix?.wcagReference ?? `SC ${v.wcag} (Level ${v.level})`}  `, `**Instances:** ${group.length}`, '', '**Representative element:**', `\`${v.selector}\`${sourceRef}`, '```html', v.html, '```', '');
             if (others.length > 0) {
                 lines.push(`**Also affects ${others.length} more element${others.length > 1 ? 's' : ''} on this page:**`);
                 for (const o of others) {
-                    lines.push(`- \`${o.selector}\``);
+                    const otherSource = o.source ? ` — \`${o.source}\`` : '';
+                    lines.push(`- \`${o.selector}\`${otherSource}`);
                 }
                 lines.push('');
             }

package/dist/reporter/terminal.js

@@ -30,7 +30,8 @@ export function printTerminalReport(result) {
             const tag = color(`[${g.impact.toUpperCase()}]`) + countSuffix;
             const wcag = chalk.gray(`WCAG ${g.wcag}`);
             console.log(`     ${tag} ${g.description}  ${wcag}`);
-            console.log(`     ${chalk.gray('→')} ${chalk.dim(g.selectors[0])}`);
+            const sourceHint = g.representative.source ? chalk.dim(`  ${g.representative.source}`) : '';
+            console.log(`     ${chalk.gray('→')} ${chalk.dim(g.selectors[0])}${sourceHint}`);
             if (g.count > 1) {
                 console.log(`     ${chalk.gray(`   …and ${g.count - 1} more`)}`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wcag-a11y",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "WCAG 2.1/2.2 accessibility auditor with AI-powered fixes",
   "type": "module",
   "bin": {