wcag-a11y 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# WCAG A11y
+
+WCAG 2.1/2.2 accessibility CLI auditor with AI-powered fixes.
+
+## Install
+
+```bash
+npm install -g wcag-a11y
+```
+
+## Setup
+
+```bash
+wcag-a11y init          # creates a11y.config.json
+# Add your free Gemini API key from https://aistudio.google.com
+```
+
+## Usage
+
+```bash
+# Scan a single page
+wcag-a11y scan --url http://localhost:3000
+
+# Scan specific pages
+wcag-a11y scan --url http://localhost:3000 --pages / /about /contact
+
+# Auto-crawl all pages + generate report
+wcag-a11y scan --url http://localhost:3000 --crawl --report
+
+# Skip AI (violations only, no fixes)
+wcag-a11y scan --url http://localhost:3000 --no-ai
+```
+
+## Config (`a11y.config.json`)
+
+```json
+{
+  "provider": "gemini",
+  "apiKey": "YOUR_FREE_KEY",
+  "model": "gemini-2.0-flash"
+}
+```
+
+For local AI (no API key): set `"provider": "ollama"` and run `ollama serve`.

package/dist/ai/gemini.js

@@ -0,0 +1,57 @@
+import { buildPrompt } from './prompt.js';
+export class GeminiProvider {
+    apiKey;
+    model;
+    constructor(apiKey, model = 'gemini-2.0-flash') {
+        this.apiKey = apiKey;
+        this.model = model;
+    }
+    async generateFixes(violations) {
+        if (violations.length === 0)
+            return [];
+        const prompt = buildPrompt(violations);
+        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.2, maxOutputTokens: 8192 },
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Gemini API error: ${response.status} ${await response.text()}`);
+        }
+        const data = await response.json();
+        const text = data.candidates?.[0]?.content?.parts?.[0]?.text ?? '[]';
+        return this.parse(text, violations);
+    }
+    parse(text, violations) {
+        try {
+            const jsonMatch = text.match(/\[[\s\S]*\]/);
+            const fixes = jsonMatch ? JSON.parse(jsonMatch[0]) : [];
+            return violations.map((v) => {
+                const found = fixes.find((f) => f.ruleId === v.ruleId && f.selector === v.selector)
+                    ?? fixes.find((f) => f.ruleId === v.ruleId);
+                return found ?? {
+                    ruleId: v.ruleId,
+                    selector: v.selector,
+                    explanation: v.description,
+                    fixedCode: v.html,
+                    wcagReference: `WCAG 2.1 SC ${v.wcag}`,
+                    optimalPrompt: `Fix this accessibility violation: The element \`${v.html.slice(0, 120)}\` at selector \`${v.selector}\` violates ${v.wcag} — ${v.description}. Please fix it in the codebase.`,
+                };
+            });
+        }
+        catch {
+            return violations.map((v) => ({
+                ruleId: v.ruleId,
+                selector: v.selector,
+                explanation: v.description,
+                fixedCode: v.html,
+                wcagReference: `WCAG 2.1 SC ${v.wcag}`,
+                optimalPrompt: `Fix this accessibility violation: The element \`${v.html.slice(0, 120)}\` at selector \`${v.selector}\` violates ${v.wcag} — ${v.description}. Please fix it in the codebase.`,
+            }));
+        }
+    }
+}

package/dist/ai/index.js

@@ -0,0 +1,12 @@
+import { GeminiProvider } from './gemini.js';
+import { OllamaProvider } from './ollama.js';
+export function createAIProvider(config) {
+    if (config.provider === 'ollama') {
+        return new OllamaProvider(config.ollamaBaseUrl, config.ollamaModel);
+    }
+    if (!config.apiKey) {
+        console.error('No API key found. Run: wcag-a11y init');
+        process.exit(1);
+    }
+    return new GeminiProvider(config.apiKey, config.model);
+}

package/dist/ai/ollama.js

@@ -0,0 +1,55 @@
+import { buildPrompt } from './prompt.js';
+export class OllamaProvider {
+    baseUrl;
+    model;
+    constructor(baseUrl = 'http://localhost:11434', model = 'llama3') {
+        this.baseUrl = baseUrl;
+        this.model = model;
+    }
+    async generateFixes(violations) {
+        if (violations.length === 0)
+            return [];
+        const prompt = buildPrompt(violations);
+        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();
+        const text = data.response ?? '[]';
+        try {
+            const jsonMatch = text.match(/\[[\s\S]*\]/);
+            if (!jsonMatch)
+                return this.fallback(violations);
+            const fixes = JSON.parse(jsonMatch[0]);
+            return violations.map((v) => {
+                const found = fixes.find((f) => f.ruleId === v.ruleId && f.selector === v.selector)
+                    ?? fixes.find((f) => f.ruleId === v.ruleId);
+                return found ?? {
+                    ruleId: v.ruleId,
+                    selector: v.selector,
+                    explanation: v.description,
+                    fixedCode: v.html,
+                    wcagReference: `WCAG 2.1 SC ${v.wcag}`,
+                    optimalPrompt: `Fix this accessibility violation: The element \`${v.html.slice(0, 120)}\` at selector \`${v.selector}\` violates ${v.wcag} — ${v.description}. Please fix it in the codebase.`,
+                };
+            });
+        }
+        catch {
+            return this.fallback(violations);
+        }
+    }
+    fallback(violations) {
+        return violations.map((v) => ({
+            ruleId: v.ruleId,
+            selector: v.selector,
+            explanation: v.description,
+            fixedCode: v.html,
+            wcagReference: `WCAG 2.1 SC ${v.wcag}`,
+            optimalPrompt: `Fix this accessibility violation: The element \`${v.html.slice(0, 120)}\` at selector \`${v.selector}\` violates ${v.wcag} — ${v.description}. Please fix it in the codebase.`,
+        }));
+    }
+}

package/dist/ai/prompt.js

@@ -0,0 +1,20 @@
+export function buildPrompt(violations) {
+    const items = violations
+        .map((v, i) => `${i + 1}. Rule: ${v.ruleId} | WCAG ${v.wcag} (Level ${v.level}) | Impact: ${v.impact}
+   Page: ${v.page}
+   Element: ${v.html}
+   Problem: ${v.description}`)
+        .join('\n\n');
+    return `You are a WCAG accessibility expert. Analyze these violations and return a JSON array.
+Each item must have:
+- "ruleId": the rule id from the input
+- "explanation": 1-2 sentences explaining why this matters for users with disabilities (plain English, no jargon)
+- "fixedCode": the corrected HTML snippet only (no explanation, just code)
+- "wcagReference": e.g. "WCAG 2.1 SC 1.1.1 — Non-text Content"
+- "optimalPrompt": a ready-to-paste prompt the developer can give to an AI coding assistant (Cursor, GitHub Copilot, Claude) to fix this issue in their codebase. Include the violating element, what rule it breaks, and exactly what change is needed. Be specific and actionable.
+
+Return ONLY a valid JSON array. No markdown, no code fences, no explanation outside the JSON.
+
+Violations:
+${items}`;
+}

package/dist/ai/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { loadConfig, initConfig } from './config.js';
+import { crawl } from './crawler.js';
+import { createAIProvider } from './ai/index.js';
+import { printTerminalReport, printAIPrompts } from './reporter/terminal.js';
+import { generateMarkdownReport } from './reporter/markdown.js';
+import { runDemo } from './demo.js';
+const program = new Command();
+program
+    .name('wcag-a11y')
+    .description('WCAG 2.1/2.2 accessibility auditor with AI-powered fixes')
+    .version('0.1.0');
+program
+    .command('init')
+    .description('Create a11y.config.json in the current directory')
+    .action(() => {
+    initConfig();
+});
+program
+    .command('scan')
+    .description('Scan a running dev server for accessibility violations')
+    .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-ai', 'Skip AI fix generation (faster, violations only)')
+    .action(async (opts) => {
+    try {
+        console.log(`\nScanning ${opts.url}...`);
+        const result = await crawl({ url: opts.url, pages: opts.pages, crawl: opts.crawl });
+        printTerminalReport(result);
+        if (opts.ai && result.totalViolations > 0) {
+            const config = loadConfig();
+            const provider = createAIProvider(config);
+            const allViolations = result.pages.flatMap((p) => p.violations);
+            console.log(`\nGenerating AI fixes for ${allViolations.length} violations...`);
+            const fixes = await provider.generateFixes(allViolations);
+            printAIPrompts(fixes);
+            if (opts.report) {
+                generateMarkdownReport(result, fixes);
+            }
+        }
+        else if (opts.report) {
+            generateMarkdownReport(result, []);
+        }
+    }
+    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-ai', 'Skip AI fix generation (faster, violations only)')
+    .action(async (opts) => {
+    try {
+        await runDemo({ ai: opts.ai, report: opts.report });
+    }
+    catch (err) {
+        console.error(`\nError: ${err.message}`);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/config.js

@@ -0,0 +1,32 @@
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+const CONFIG_FILE = 'a11y.config.json';
+const DEFAULTS = {
+    provider: 'gemini',
+    model: 'gemini-2.0-flash',
+    ollamaBaseUrl: 'http://localhost:11434',
+    ollamaModel: 'llama3',
+};
+export function loadConfig() {
+    const configPath = join(process.cwd(), CONFIG_FILE);
+    if (!existsSync(configPath)) {
+        console.error(`No ${CONFIG_FILE} found. Run: wcag-a11y init`);
+        process.exit(1);
+    }
+    const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+    return { ...DEFAULTS, ...raw };
+}
+export function initConfig() {
+    const configPath = join(process.cwd(), CONFIG_FILE);
+    if (existsSync(configPath)) {
+        console.log(`${CONFIG_FILE} already exists.`);
+        return;
+    }
+    const starter = {
+        provider: 'gemini',
+        apiKey: 'YOUR_GEMINI_API_KEY',
+        model: 'gemini-2.0-flash',
+    };
+    writeFileSync(configPath, JSON.stringify(starter, null, 2));
+    console.log(`Created ${CONFIG_FILE} — add your Gemini API key from https://aistudio.google.com`);
+}

package/dist/crawler.js

@@ -0,0 +1,54 @@
+import { chromium } from 'playwright';
+import { scanPage } from './engine/index.js';
+export async function crawl(options) {
+    const { url, pages = ['/'], crawl: autoCrawl = false } = options;
+    const baseUrl = url.replace(/\/$/, '');
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const context = await browser.newContext();
+        let pagesToVisit = pages.map((p) => `${baseUrl}${p}`);
+        if (autoCrawl) {
+            const discoveredPage = await context.newPage();
+            try {
+                await discoveredPage.goto(baseUrl, { waitUntil: 'networkidle' });
+                const hrefs = await discoveredPage.$$eval('a[href]', (anchors) => anchors.map((a) => a.href));
+                const sameOrigin = hrefs
+                    .filter((href) => href.startsWith(baseUrl))
+                    .map((href) => href.split('#')[0])
+                    .filter((v, i, arr) => arr.indexOf(v) === i);
+                pagesToVisit = sameOrigin.length > 0 ? sameOrigin : pagesToVisit;
+            }
+            finally {
+                await discoveredPage.close();
+            }
+        }
+        const results = [];
+        for (const pageUrl of pagesToVisit) {
+            const page = await context.newPage();
+            try {
+                await page.goto(pageUrl, { waitUntil: 'networkidle', timeout: 30000 });
+                const result = await scanPage(page, pageUrl);
+                results.push(result);
+            }
+            catch (err) {
+                console.error(`Failed to scan ${pageUrl}: ${err.message}`);
+                results.push({ url: pageUrl, violations: [] });
+            }
+            finally {
+                await page.close();
+            }
+        }
+        const allViolations = results.flatMap((r) => r.violations);
+        return {
+            pages: results,
+            totalViolations: allViolations.length,
+            criticalCount: allViolations.filter((v) => v.impact === 'critical').length,
+            seriousCount: allViolations.filter((v) => v.impact === 'serious').length,
+            moderateCount: allViolations.filter((v) => v.impact === 'moderate').length,
+            minorCount: allViolations.filter((v) => v.impact === 'minor').length,
+        };
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/demo.js

@@ -0,0 +1,89 @@
+import { createServer } from 'http';
+import { crawl } from './crawler.js';
+import { createAIProvider } from './ai/index.js';
+import { loadConfig } from './config.js';
+import { printTerminalReport, printAIPrompts } from './reporter/terminal.js';
+import { generateMarkdownReport } from './reporter/markdown.js';
+const DEMO_HTML = `<!DOCTYPE html>
+<html lang="">
+<head>
+  <meta charset="UTF-8">
+  <title></title>
+</head>
+<body>
+
+  <h1>Welcome to Acme Shop</h1>
+
+  <!-- 1. img-alt: missing alt -->
+  <img src="banner.jpg">
+
+  <!-- 2. color contrast: fails 4.5:1 -->
+  <p style="color:#aaa;background:#fff;font-size:14px;">
+    Summer sale — up to 50% off selected items.
+  </p>
+
+  <!-- 3. keyboard: div with click but no role/tabindex -->
+  <div onclick="addToCart()">Add to Cart</div>
+
+  <!-- 4. form: input with no label -->
+  <form id="newsletter">
+    <input type="email" placeholder="your@email.com">
+    <button type="submit"></button>
+  </form>
+
+  <!-- 5. ARIA: invalid role -->
+  <div role="widget" id="promo-banner">Special offer!</div>
+
+  <!-- 6. Structure: heading skips h2 → h4 -->
+  <h4>Featured Products</h4>
+
+  <!-- 7. Link: non-descriptive text -->
+  <a href="/sale">Click here</a>
+
+  <!-- 8. Media: video without captions -->
+  <video src="promo.mp4" controls></video>
+
+  <!-- 9. ARIA: aria-hidden but focusable -->
+  <button aria-hidden="true" tabindex="0">Hidden action</button>
+
+  <!-- 10. Link: empty anchor -->
+  <a href="/about"></a>
+
+</body>
+</html>`;
+function startDemoServer() {
+    return new Promise((resolve) => {
+        const server = createServer((_, res) => {
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(DEMO_HTML);
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            resolve({ server, url: `http://127.0.0.1:${addr.port}` });
+        });
+    });
+}
+export async function runDemo(opts) {
+    const { server, url } = await startDemoServer();
+    try {
+        console.log('\nRunning demo scan against a built-in page with intentional WCAG violations...\n');
+        const result = await crawl({ url, pages: ['/'] });
+        printTerminalReport(result);
+        if (opts.ai && result.totalViolations > 0) {
+            const config = loadConfig();
+            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);
+            printAIPrompts(fixes);
+            if (opts.report)
+                generateMarkdownReport(result, fixes);
+        }
+        else if (opts.report) {
+            generateMarkdownReport(result, []);
+        }
+    }
+    finally {
+        server.close();
+    }
+}

package/dist/engine/index.js

@@ -0,0 +1,56 @@
+import { textAlternativeRules } from './rules/text-alternatives.js';
+import { colorContrastRules } from './rules/color-contrast.js';
+import { keyboardRules } from './rules/keyboard.js';
+import { formRules } from './rules/forms.js';
+import { ariaRules } from './rules/aria.js';
+import { structureRules } from './rules/structure.js';
+import { linkRules } from './rules/links.js';
+import { languageRules } from './rules/language.js';
+import { mediaRules } from './rules/media.js';
+import { tableRules } from './rules/tables.js';
+const ALL_RULES = [
+    ...textAlternativeRules,
+    ...colorContrastRules,
+    ...keyboardRules,
+    ...formRules,
+    ...ariaRules,
+    ...structureRules,
+    ...linkRules,
+    ...languageRules,
+    ...mediaRules,
+    ...tableRules,
+];
+export async function scanPage(page, url) {
+    const violations = [];
+    for (const rule of ALL_RULES) {
+        // Serialize the check function and run it inside the browser page
+        const ruleViolations = await page.evaluate(({ checkFn, meta }) => {
+            // eslint-disable-next-line no-new-func
+            // __name is injected by esbuild/tsx at compile time but is not available
+            // inside page.evaluate's isolated context — provide a no-op shim.
+            const fn = new Function(`var __name=(t,_)=>t; return (${checkFn})`)();
+            const results = fn();
+            return results.map((r) => ({
+                ruleId: meta.id,
+                wcag: meta.wcag,
+                level: meta.level,
+                impact: meta.impact,
+                description: meta.description,
+                selector: r.selector,
+                html: r.html,
+                page: window.location.href,
+            }));
+        }, {
+            checkFn: rule.check.toString(),
+            meta: {
+                id: rule.id,
+                wcag: rule.wcag,
+                level: rule.level,
+                impact: rule.impact,
+                description: rule.description,
+            },
+        });
+        violations.push(...ruleViolations);
+    }
+    return { url, violations };
+}