wcag-a11y 0.4.2 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![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` 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**.
+Most accessibility auditors stop at detection — they tell you *what* is broken and leave the rest to you. `wcag-a11y` 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**. Works with authenticated apps via Playwright session state.
 
 Two modes:
 - **`scan`** — find violations + get AI prompts you paste into Cursor, Copilot, or Claude
@@ -78,13 +78,8 @@ npm install -g wcag-a11y
 ## Quick start
 
 ```bash
-# 1. Configure your AI provider and framework (Gemini is free, no credit card)
-wcag-a11y init --framework next      # Next.js
-wcag-a11y init --framework react     # React / Vite
-wcag-a11y init --framework vue       # Vue / Nuxt
-wcag-a11y init --framework angular   # Angular
-wcag-a11y init --framework svelte    # Svelte / SvelteKit
-wcag-a11y init                       # plain HTML or auto-detect
+# 1. Configure your AI provider (Gemini is free, no credit card)
+wcag-a11y init
 
 # 2. Start your dev server, then scan
 wcag-a11y scan -u http://localhost:3000
@@ -92,6 +87,12 @@ wcag-a11y scan -u http://localhost:3000
 
 Add `--pages / /about /contact` to scan specific routes, or `--crawl` to follow links automatically.
 
+**Optional — set your framework once:** The tool auto-detects common frameworks at runtime. If detection fails (e.g. scanning a staging URL, or using Astro/SvelteKit), set it in your config so every run uses the right syntax:
+
+```bash
+wcag-a11y init --framework next    # or react, vue, angular, svelte, astro, …
+```
+
 ---
 
 ## Commands
@@ -120,8 +121,9 @@ wcag-a11y scan -u http://localhost:3000 --terminal --fast-mode
 | `--fast-mode` | off | Output only the raw prompts — no summaries or decoration |
 | `--group <strategy>` | `rule` | `rule`: one prompt per rule type. `none`: one prompt per element |
 | `--ci` | off | Exit with code `1` if any violations are found |
+| `--auth-state <path>` | — | Path to a Playwright `storageState` JSON. Loads cookies and localStorage so you can scan pages behind a login wall |
 | `--provider <name>` | from config | Override AI provider for this run |
-| `--framework <name>` | from config | Override framework for this run (e.g. `next`, `react`, `vue`, `angular`, `svelte`, `astro`) |
+| `--framework <name>` | from config | *(optional)* Override framework for this run. Auto-detected by default; use this when scanning staging URLs or for frameworks outside the detection list |
 
 ---
 
@@ -164,34 +166,65 @@ wcag-a11y fix --from-report --apply       # patches files from that report, no s
 | `-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 rescanning |
 | `--apply` | off | Write fixes to disk (dry-run without this flag) |
+| `--force` | off | Skip the git dirty-state check when using `--apply` |
 | `--provider <name>` | from config | Override AI provider for this run |
-| `--framework <name>` | from config | Override framework for this run (e.g. `next`, `react`, `vue`, `angular`, `svelte`, `astro`) |
+| `--framework <name>` | from config | *(optional)* Override framework for this run. Auto-detected by default; use this when scanning staging URLs or for frameworks outside the detection list |
+
+**Git safety:** `wcag-a11y fix --apply` checks for uncommitted changes before writing anything. If the working tree is dirty it exits with an error — commit or stash first, or pass `--force` to override.
+
+---
+
+### Scanning authenticated pages
+
+Most real apps require a login. Save your session with Playwright once, then reuse it on every scan:
+
+```bash
+# 1. Save session (run this once after logging in)
+node -e "
+const { chromium } = require('playwright');
+(async () => {
+  const browser = await chromium.launch({ headless: false });
+  const context = await browser.newContext();
+  const page = await context.newPage();
+  await page.goto('http://localhost:3000/login');
+  // log in manually in the browser window that opens
+  await page.waitForTimeout(30000);
+  await context.storageState({ path: 'auth.json' });
+  await browser.close();
+})();
+"
+
+# 2. Scan with your saved session
+wcag-a11y scan -u http://localhost:3000 --auth-state auth.json --pages / /dashboard /settings
+```
+
+`auth.json` captures cookies and `localStorage`. Keep it out of source control (add `auth.json` to `.gitignore`).
 
 ---
 
 ### `wcag-a11y init`
 
-Create `a11y.config.json` pre-configured for your chosen provider and framework.
+Create `a11y.config.json` pre-configured for your chosen provider.
 
 ```bash
 wcag-a11y init                                      # Gemini (free, default)
-wcag-a11y init --provider openai --framework next   # OpenAI + Next.js
-wcag-a11y init --provider ollama --framework react  # local Ollama + React
-# … 12 providers total, any framework string accepted
+wcag-a11y init --provider openai
+wcag-a11y init --provider ollama                    # local — no API key needed
+wcag-a11y init --provider openai --framework next   # optional: save framework too
 ```
 
 | Flag | Description |
 |---|---|
 | `--provider <name>` | AI provider. Default: `gemini`. See [AI Providers](#ai-providers) for all options |
-| `--framework <name>` | Your project framework — saved to config so every scan uses it automatically |
+| `--framework <name>` | *(optional)* Your project framework — saved to config so every scan uses it automatically. The tool auto-detects common frameworks; use this flag when scanning staging URLs or using a framework not in the detection list |
 
-Framework is saved as `"framework"` in `a11y.config.json`. You can also edit the file directly at any time. Supported values for best results: `next`, `react`, `vue`, `nuxt`, `angular`, `svelte`, `gatsby`, `remix`, `astro` — or any free-form string.
+Accepted framework values: `next`, `react`, `vue`, `nuxt`, `angular`, `svelte`, `gatsby`, `remix`, `astro` — or any free-form string. You can also add `"framework": "next"` directly to `a11y.config.json` at any time.
 
 ---
 
 ### `wcag-a11y demo`
 
-Scan a built-in page with 10 intentional violations. No dev server or config required — useful for trying the tool before pointing it at your own project.
+Scan a built-in page with 11 intentional violations. No dev server or config required — useful for trying the tool before pointing it at your own project.
 
 ```bash
 wcag-a11y demo           # violations + AI fix prompts (requires config)
@@ -227,6 +260,15 @@ All models are configurable. If the AI response is unparseable, the tool generat
 
 Run `wcag-a11y init` to generate `a11y.config.json`. Only fill in the fields for your chosen provider. This file is gitignored by default.
 
+```json
+{
+  "provider": "gemini",
+  "apiKey": "YOUR_GEMINI_API_KEY"
+}
+```
+
+`"framework"` is optional — add it if auto-detection fails for your setup:
+
 ```json
 {
   "provider": "gemini",

package/dist/cli.js

@@ -13,7 +13,7 @@ const program = new Command();
 program
     .name('wcag-a11y')
     .description('WCAG 2.1/2.2 accessibility auditor with AI-powered fixes')
-    .version('0.4.2');
+    .version('0.4.3');
 program
     .command('init')
     .description('Create a11y.config.json in the current directory')
@@ -35,12 +35,13 @@ program
     .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)
+    .option('--auth-state <path>', 'Path to Playwright storageState JSON for authenticated sessions (e.g. auth.json)')
     .option('--provider <name>', 'Override the AI provider from config (gemini|openai|ollama|anthropic|mistral|groq|cohere|xai|deepseek|together|perplexity|azure-openai)')
     .option('--framework <name>', 'Override framework detection for this run (e.g. next, react, vue, angular, svelte, astro)')
     .action(async (opts) => {
     try {
         console.log(`\nScanning ${opts.url}...`);
-        const result = await crawl({ url: opts.url, pages: opts.pages, crawl: opts.crawl, framework: opts.framework });
+        const result = await crawl({ url: opts.url, pages: opts.pages, crawl: opts.crawl, framework: opts.framework, authState: opts.authState });
         if (opts.terminal && !opts.fastMode) {
             printTerminalReport(result);
         }
@@ -85,6 +86,7 @@ program
     .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('--force', 'Skip git dirty-state check when using --apply', false)
     .option('--provider <name>', 'Override the AI provider from config (gemini|openai|ollama|anthropic|mistral|groq|cohere|xai|deepseek|together|perplexity|azure-openai)')
     .option('--framework <name>', 'Override framework detection for this run (e.g. next, react, vue, angular, svelte, astro)')
     .action(async (opts) => {
@@ -106,6 +108,7 @@ program
             crawl: opts.crawl,
             reportPath,
             apply: opts.apply,
+            force: opts.force,
             provider,
             srcDir: resolve(process.cwd(), 'src'),
             framework: opts.framework ?? config.framework,

package/dist/crawler.js

@@ -43,7 +43,7 @@ export async function crawl(options) {
     const baseUrl = url.replace(/\/$/, '');
     const browser = await chromium.launch({ headless: true });
     try {
-        const context = await browser.newContext();
+        const context = await browser.newContext(options.authState ? { storageState: options.authState } : {});
         let pagesToVisit = pages.map((p) => `${baseUrl}${p}`);
         if (autoCrawl) {
             const discoveredPage = await context.newPage();

package/dist/demo.js

@@ -17,36 +17,43 @@ const DEMO_HTML = `<!DOCTYPE html>
   <!-- 1. img-alt: missing alt -->
   <img src="banner.jpg">
 
-  <!-- 2. color contrast: fails 4.5:1 -->
+  <!-- 2. color-contrast: low contrast on solid background (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 -->
+  <!-- 3. color-contrast: rgba(0,0,0,0) transparent bg — walks up to dark parent -->
+  <div style="background:#1a1a2e;padding:8px;">
+    <p style="color:#888;background:rgba(0,0,0,0);font-size:14px;">
+      Free shipping on orders over $50.
+    </p>
+  </div>
+
+  <!-- 4. keyboard: div with click but no role/tabindex -->
   <div onclick="addToCart()">Add to Cart</div>
 
-  <!-- 4. form: input with no label -->
+  <!-- 5. form: input with no label -->
   <form id="newsletter">
     <input type="email" placeholder="your@email.com">
     <button type="submit"></button>
   </form>
 
-  <!-- 5. ARIA: invalid role -->
+  <!-- 6. ARIA: invalid role -->
   <div role="widget" id="promo-banner">Special offer!</div>
 
-  <!-- 6. Structure: heading skips h2 → h4 -->
+  <!-- 7. Structure: heading skips h2 → h4 -->
   <h4>Featured Products</h4>
 
-  <!-- 7. Link: non-descriptive text -->
+  <!-- 8. Link: non-descriptive text -->
   <a href="/sale">Click here</a>
 
-  <!-- 8. Media: video without captions -->
+  <!-- 9. Media: video without captions -->
   <video src="promo.mp4" controls></video>
 
-  <!-- 9. ARIA: aria-hidden but focusable -->
+  <!-- 10. ARIA: aria-hidden but focusable -->
   <button aria-hidden="true" tabindex="0">Hidden action</button>
 
-  <!-- 10. Link: empty anchor -->
+  <!-- 11. Link: empty anchor -->
   <a href="/about"></a>
 
 </body>
@@ -66,7 +73,7 @@ function startDemoServer() {
 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');
+        console.log('\nRunning demo scan against a built-in page with 11 intentional WCAG violations...\n');
         const result = await crawl({ url, pages: ['/'] });
         printTerminalReport(result);
         if (opts.ai && result.totalViolations > 0) {

package/dist/engine/rules/color-contrast.js

@@ -26,6 +26,37 @@ export const colorContrastRules = [
                 }
                 return parts.join(' > ') || el.tagName.toLowerCase();
             };
+            const parseRgba = (raw) => {
+                const m = raw.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+                if (!m)
+                    return null;
+                return [+m[1], +m[2], +m[3], m[4] !== undefined ? parseFloat(m[4]) : 1];
+            };
+            const getOpaqueBg = (el) => {
+                let node = el;
+                while (node) {
+                    const rgba = parseRgba(window.getComputedStyle(node).backgroundColor);
+                    if (rgba && rgba[3] > 0.01)
+                        return [rgba[0], rgba[1], rgba[2]];
+                    node = node.parentElement;
+                }
+                return [255, 255, 255];
+            };
+            const resolveBackground = (bgRaw, el) => {
+                const bgRgba = parseRgba(bgRaw);
+                if (!bgRgba || bgRgba[3] <= 0.01)
+                    return getOpaqueBg(el.parentElement ?? el);
+                if (bgRgba[3] < 0.99) {
+                    const parent = getOpaqueBg(el.parentElement ?? el);
+                    const a = bgRgba[3];
+                    return [
+                        Math.round(bgRgba[0] * a + parent[0] * (1 - a)),
+                        Math.round(bgRgba[1] * a + parent[1] * (1 - a)),
+                        Math.round(bgRgba[2] * a + parent[2] * (1 - a)),
+                    ];
+                }
+                return [bgRgba[0], bgRgba[1], bgRgba[2]];
+            };
             const elements = Array.from(document.querySelectorAll('p, span, li, td, th, h1, h2, h3, h4, h5, h6, a, label'));
             const violations = [];
             for (const el of elements) {
@@ -37,16 +68,14 @@ export const colorContrastRules = [
                 const isLargeText = fontSize >= 24 || (fontSize >= 18.67 && (fontWeight === 'bold' || parseInt(fontWeight) >= 700));
                 if (isLargeText)
                     continue;
-                const fgRaw = style.color;
-                const bgRaw = style.backgroundColor;
-                const fgMatch = fgRaw.match(/rgb\((\d+),\s*(\d+),\s*(\d+)\)/);
-                const bgMatch = bgRaw.match(/rgb\((\d+),\s*(\d+),\s*(\d+)\)/);
-                if (!fgMatch || !bgMatch)
+                const fgRgba = parseRgba(style.color);
+                if (!fgRgba)
                     continue;
+                const [bgR, bgG, bgB] = resolveBackground(style.backgroundColor, el);
                 const toLinear = (c) => { const s = c / 255; return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4); };
                 const lum = (r, g, b) => 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
-                const l1 = lum(+fgMatch[1], +fgMatch[2], +fgMatch[3]);
-                const l2 = lum(+bgMatch[1], +bgMatch[2], +bgMatch[3]);
+                const l1 = lum(fgRgba[0], fgRgba[1], fgRgba[2]);
+                const l2 = lum(bgR, bgG, bgB);
                 const ratio = (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
                 if (ratio < 4.5) {
                     violations.push({ selector: getCssPath(el), html: el.outerHTML.slice(0, 200) });
@@ -82,6 +111,37 @@ export const colorContrastRules = [
                 }
                 return parts.join(' > ') || el.tagName.toLowerCase();
             };
+            const parseRgba = (raw) => {
+                const m = raw.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+                if (!m)
+                    return null;
+                return [+m[1], +m[2], +m[3], m[4] !== undefined ? parseFloat(m[4]) : 1];
+            };
+            const getOpaqueBg = (el) => {
+                let node = el;
+                while (node) {
+                    const rgba = parseRgba(window.getComputedStyle(node).backgroundColor);
+                    if (rgba && rgba[3] > 0.01)
+                        return [rgba[0], rgba[1], rgba[2]];
+                    node = node.parentElement;
+                }
+                return [255, 255, 255];
+            };
+            const resolveBackground = (bgRaw, el) => {
+                const bgRgba = parseRgba(bgRaw);
+                if (!bgRgba || bgRgba[3] <= 0.01)
+                    return getOpaqueBg(el.parentElement ?? el);
+                if (bgRgba[3] < 0.99) {
+                    const parent = getOpaqueBg(el.parentElement ?? el);
+                    const a = bgRgba[3];
+                    return [
+                        Math.round(bgRgba[0] * a + parent[0] * (1 - a)),
+                        Math.round(bgRgba[1] * a + parent[1] * (1 - a)),
+                        Math.round(bgRgba[2] * a + parent[2] * (1 - a)),
+                    ];
+                }
+                return [bgRgba[0], bgRgba[1], bgRgba[2]];
+            };
             const elements = Array.from(document.querySelectorAll('p, span, h1, h2, h3, h4, h5, h6'));
             const violations = [];
             for (const el of elements) {
@@ -93,16 +153,14 @@ export const colorContrastRules = [
                 const isLargeText = fontSize >= 24 || (fontSize >= 18.67 && (fontWeight === 'bold' || parseInt(fontWeight) >= 700));
                 if (!isLargeText)
                     continue;
-                const fgRaw = style.color;
-                const bgRaw = style.backgroundColor;
-                const fgMatch = fgRaw.match(/rgb\((\d+),\s*(\d+),\s*(\d+)\)/);
-                const bgMatch = bgRaw.match(/rgb\((\d+),\s*(\d+),\s*(\d+)\)/);
-                if (!fgMatch || !bgMatch)
+                const fgRgba = parseRgba(style.color);
+                if (!fgRgba)
                     continue;
+                const [bgR, bgG, bgB] = resolveBackground(style.backgroundColor, el);
                 const toLinear = (c) => { const s = c / 255; return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4); };
                 const lum = (r, g, b) => 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
-                const l1 = lum(+fgMatch[1], +fgMatch[2], +fgMatch[3]);
-                const l2 = lum(+bgMatch[1], +bgMatch[2], +bgMatch[3]);
+                const l1 = lum(fgRgba[0], fgRgba[1], fgRgba[2]);
+                const l2 = lum(bgR, bgG, bgB);
                 const ratio = (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
                 if (ratio < 3) {
                     violations.push({ selector: getCssPath(el), html: el.outerHTML.slice(0, 200) });

package/dist/fixer.js

@@ -1,4 +1,5 @@
 import { readFileSync, writeFileSync, readdirSync, existsSync } from 'fs';
+import { execSync } from 'child_process';
 import { join, resolve } from 'path';
 import chalk from 'chalk';
 import { crawl } from './crawler.js';
@@ -54,6 +55,19 @@ export async function runFix(opts) {
     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'));
+    if (opts.apply && !opts.force) {
+        try {
+            const dirty = execSync('git status --porcelain', { encoding: 'utf8' }).trim();
+            if (dirty) {
+                console.error(chalk.red('Error: uncommitted changes detected. Commit or stash them first, or run with --force to override.\n'));
+                console.error(chalk.gray(dirty.split('\n').slice(0, 5).join('\n')));
+                process.exit(1);
+            }
+        }
+        catch {
+            // not a git repo or git unavailable — proceed without guard
+        }
+    }
     let modifiedFiles = 0;
     let modifiedViolations = 0;
     for (const [filePath, violations] of fileGroups) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wcag-a11y",
-  "version": "0.4.2",
-  "description": "WCAG 2.1/2.2 accessibility auditor with AI-powered fixes. Crawls your dev server with Playwright, runs 40+ checks, and uses AI (12 providers) to generate fix prompts or patch source files directly.",
+  "version": "0.5.0",
+  "description": "WCAG 2.1/2.2 accessibility auditor with AI-powered fixes. Crawls your dev server with Playwright, runs 40+ checks, and uses AI (12 providers) to generate fix prompts or patch source files directly. Supports authenticated sessions via Playwright storageState.",
   "keywords": [
     "wcag",
     "accessibility",
@@ -18,6 +18,7 @@
     "gemini",
     "openai",
     "anthropic",
+    "auth",
     "screen-reader"
   ],
   "type": "module",