wcag-a11y 0.3.4 → 0.3.6

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,72 @@ 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
+
+# Skip rescanning — load violations from an existing report
+wcag-a11y fix --from-report
+wcag-a11y fix --from-report ./reports/a11y-report.md --apply
+```
+
+**How it works:**
+
+1. Runs the same scan as `wcag-a11y scan` (or loads an existing report with `--from-report`)
+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>` | — | Base URL of your running dev server. Required unless `--from-report` is used |
+| `-p, --pages <pages...>` | `/` | Specific pages to scan |
+| `-c, --crawl` | off | Auto-discover pages by following same-origin links |
+| `--from-report [path]` | `a11y-report.md` | Load violations from an existing report instead of scanning. Useful when you already ran `scan --report` and just want to apply fixes |
+| `--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.
+
+**Common workflow:** run `scan --report` to generate a report for review, then run `fix --from-report --apply` to patch the files — no second browser crawl needed.
+
+```bash
+wcag-a11y scan -u http://localhost:3000 --report   # review a11y-report.md
+wcag-a11y fix --from-report --apply                 # patch files from that report
+```
+
+---
+
 ## 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 {
@@ -29,6 +30,22 @@ export class GeminiProvider {
         const text = data.candidates?.[0]?.content?.parts?.[0]?.text ?? '[]';
         return this.parse(text, groups, framework);
     }
+    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]*\]/);

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 {
@@ -39,6 +40,18 @@ export class OllamaProvider {
             return this.fallback(groups, framework);
         }
     }
+    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));
     }

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 {
@@ -33,6 +34,23 @@ export class OpenAIProvider {
         const text = data.choices?.[0]?.message?.content ?? '[]';
         return this.parse(text, groups, framework);
     }
+    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]*\]/);

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/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.4');
+    .version('0.3.6');
 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)
@@ -72,10 +74,47 @@ program
         process.exit(1);
     }
 });
+program
+    .command('fix')
+    .description('Scan for violations and apply AI fixes directly to source files')
+    .option('-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('--from-report [path]', 'Use an existing report instead of scanning (default: a11y-report.md)')
+    .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) => {
+    if (!opts.url && !opts.fromReport) {
+        console.error('\nError: provide --url <url> to scan, or --from-report [path] to load an existing report.');
+        process.exit(1);
+    }
+    try {
+        const config = loadConfig();
+        if (opts.provider)
+            config.provider = opts.provider;
+        const provider = createAIProvider(config);
+        const reportPath = opts.fromReport
+            ? (opts.fromReport === true ? 'a11y-report.md' : opts.fromReport)
+            : undefined;
+        await runFix({
+            url: opts.url,
+            pages: opts.pages,
+            crawl: opts.crawl,
+            reportPath,
+            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

@@ -18,9 +18,16 @@ async function detectFramework(page) {
                 return 'Vue 2';
             if (document.querySelector('[ng-version]') !== null)
                 return 'Angular';
-            const root = document.getElementById('root') ?? document.getElementById('app') ?? document.body;
-            if (root && Object.keys(root).some((k) => k.startsWith('__reactFiber') || k.startsWith('__reactContainer'))) {
+            // 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';

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,322 @@
+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) {
+    let allViolations;
+    let framework;
+    if (opts.reportPath) {
+        const absReport = resolve(process.cwd(), opts.reportPath);
+        if (!existsSync(absReport)) {
+            throw new Error(`Report file not found: ${opts.reportPath}`);
+        }
+        console.log(`\nLoading violations from ${opts.reportPath}...`);
+        allViolations = parseReportViolations(absReport);
+        if (allViolations.length === 0) {
+            console.log(chalk.green('\nNo violations found in report.'));
+            return;
+        }
+        console.log(`Found ${allViolations.length} violation(s) in report. Locating source files...\n`);
+    }
+    else {
+        console.log(`\nScanning ${opts.url}...`);
+        const result = await crawl({ url: opts.url, pages: opts.pages, crawl: opts.crawl });
+        framework = result.framework;
+        if (result.totalViolations === 0) {
+            console.log(chalk.green('\nNo violations found.'));
+            return;
+        }
+        console.log(`Found ${result.totalViolations} violation(s). Locating source files...\n`);
+        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.`));
+    }
+}
+function parseReportViolations(reportPath) {
+    const content = readFileSync(reportPath, 'utf8');
+    const violations = [];
+    const pageParts = content.split(/^## Page:/m).slice(1);
+    for (const part of pageParts) {
+        const pageUrl = part.split('\n')[0].trim();
+        if (part.includes('✅ No violations found'))
+            continue;
+        for (const group of part.split(/^---$/m)) {
+            const headingMatch = group.match(/^###\s+\S+\s+\[(\w+)\]\s+(.+)$/m);
+            if (!headingMatch)
+                continue;
+            const impact = headingMatch[1].toLowerCase();
+            const description = headingMatch[2].trim();
+            const ruleMatch = group.match(/\*\*Rule:\*\*\s+`([^`]+)`/);
+            if (!ruleMatch)
+                continue;
+            const ruleId = ruleMatch[1];
+            let wcag = '';
+            let level = 'A';
+            const wcagStd = group.match(/\*\*WCAG:\*\*\s+SC\s+([\d.]+)\s+\(Level\s+([A-Z]+)\)/);
+            if (wcagStd) {
+                wcag = wcagStd[1];
+                level = wcagStd[2];
+            }
+            else {
+                const wcagAI = group.match(/\*\*WCAG:\*\*\s+WCAG\s+[\d.]+\s+SC\s+([\d.]+)/);
+                if (wcagAI)
+                    wcag = wcagAI[1];
+            }
+            const repMatch = group.match(/\*\*Representative element:\*\*\s*\n`([^`]+)`(?:\s+—\s+`([^`]+)`)?/);
+            if (!repMatch)
+                continue;
+            const selector = repMatch[1];
+            const source = repMatch[2];
+            const htmlMatch = group.match(/\*\*Representative element:\*\*[\s\S]*?```html\n([\s\S]*?)\n```/);
+            const html = htmlMatch?.[1] ?? '';
+            violations.push({ ruleId, wcag, level, impact, description, selector, html, page: pageUrl, ...(source ? { source } : {}) });
+            const alsoSection = group.match(/\*\*Also affects[^*]*\*\*([\s\S]*?)(?:\n\n\*\*|\n---|\n```|$)/);
+            if (alsoSection) {
+                for (const line of alsoSection[1].split('\n')) {
+                    const m = line.match(/^-\s+`([^`]+)`(?:\s+—\s+`([^`]+)`)?/);
+                    if (!m)
+                        continue;
+                    violations.push({ ruleId, wcag, level, impact, description, selector: m[1], html: '', page: pageUrl, ...(m[2] ? { source: m[2] } : {}) });
+                }
+            }
+        }
+    }
+    return violations;
+}
+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.4",
+  "version": "0.3.6",
   "description": "WCAG 2.1/2.2 accessibility auditor with AI-powered fixes",
   "type": "module",
   "bin": {