wcag-scanner 1.2.65 → 1.2.67

package/README.md

@@ -22,13 +22,13 @@ WCAG Scanner is a powerful accessibility testing tool that helps developers iden
 
 ## ✨ Features
 
-- **Comprehensive Accessibility Testing**: Scans websites against WCAG 2.1 A, AA, and AAA compliance levels
-- **Detailed Reports**: Generates comprehensive reports highlighting issues with severity ratings
-- **Actionable Recommendations**: Provides specific guidance on how to fix identified issues
-- **Integration with Development Workflows**: CI/CD integration via GitHub Actions, GitLab CI, etc.
-- **Custom Rule Configuration**: Tailor scanning criteria to your project's specific needs
-- **Interactive Dashboard**: Visual representation of accessibility issues with filtering capabilities
-- **Performance Optimization**: Minimal impact on development and build processes
+- **WCAG 2.1 Compliance Scanning**: Checks against A, AA, and AAA conformance levels
+- **Fast and Full Presets**: Default fast scans plus optional heavier rules like `backgroundImages`
+- **React Dev Overlay**: Live in-browser inspector with element highlighting, pinning, and impact filtering
+- **AI Fix Suggestions**: Paste your Gemini API key in the overlay settings to get instant fix suggestions per violation
+- **Programmatic API**: Scan HTML strings or local files from Node.js
+- **Express Middleware**: Auto-scan responses in your Express app
+- **Multiple Report Formats**: JSON, HTML, and console output
 
 ## 📦 Installation
 
@@ -43,105 +43,129 @@ yarn add wcag-scanner
 pnpm add wcag-scanner
 ```
 
-> **React users:** React and React DOM are peer dependencies and are already installed in your project — no extra steps needed.
+> **React users:** React and React DOM are peer dependencies already in your project — no extra install needed.
 
-### For the React Dev Overlay
+## 🖥️ React Dev Overlay
 
-Add one line to your app entry point (`main.ts`, `index.js`, `App.tsx`, etc.):
+The easiest way to use wcag-scanner in a React app. Add **one line** to your entry file and a live accessibility inspector appears in the corner of your browser during development.
 
 ```ts
+// main.ts / main.jsx / index.tsx — works with any file type
 import { initWcagOverlay } from 'wcag-scanner/react';
-initWcagOverlay(); // shows a live WCAG inspector in the browser, dev only
+
+initWcagOverlay(); // auto-disabled in production
 ```
 
-The overlay is automatically disabled in production (`NODE_ENV=production`) and never ships to your users.
+**Options:**
+```ts
+initWcagOverlay({
+  level:    'AA',           // 'A' | 'AA' | 'AAA' — default: 'AA'
+  preset:   'fast',         // 'fast' | 'full' — default: 'fast'
+  position: 'bottom-right', // 'bottom-right' | 'bottom-left'
+  debounce: 750,            // ms to wait after DOM change before rescanning
+  rules:    ['images', 'backgroundImages', 'contrast'], // explicit rules override preset
+});
+```
 
-## How to use
-### CLI Usage Example:
+`preset: 'full'` includes the heavier optional checks such as `backgroundImages`. Use `rules` when you want an exact rule list.
 
-```bash
-# Scan a file
-npx wcag-scanner file index.html --level AA --format console
+**Preset Contents**
+
+| Preset | Rules included |
+| --- | --- |
+| `fast` | `images`, `contrast`, `forms`, `aria`, `structure`, `keyboard` |
+| `full` | `images`, `contrast`, `forms`, `aria`, `structure`, `keyboard`, `backgroundImages` |
+
+You can also import these programmatically:
+
+```ts
+import { RULE_PRESETS, resolveRuleNames } from 'wcag-scanner';
+
+console.log(RULE_PRESETS.fast);
+console.log(resolveRuleNames({ preset: 'full' }));
+```
+
+**Features:**
+- Hover over a violation to highlight the element on the page
+- Click to pin the highlight; click again to unpin
+- Expand any violation card for the HTML snippet, element path, WCAG criteria, and fix hint
+- Filter by impact level (critical / serious / moderate / minor)
+- Drag the panel anywhere on screen
+- Keyboard shortcut `Alt+Shift+W` to toggle open/close
+- **⚙ Settings** — paste a free Google Gemini API key to get AI-powered fix suggestions per violation
+
+> The overlay never runs in production (`NODE_ENV=production`) and is never included in your production bundle.
+
+## 🔧 Programmatic API
 
-# Scan a URL
-npx wcag-scanner url https://example.com --format html --output report.html
+Scan HTML strings or local files from Node.js scripts, CI pipelines, or build tools.
+
+```js
+import { scanHtml, scanFile, formatReport, saveReport } from 'wcag-scanner';
+
+// Scan an HTML string
+const results = await scanHtml('<img src="logo.png">', { level: 'AA', preset: 'fast' });
+console.log(`${results.violations.length} violations found`);
+
+// Scan a local HTML file
+const results = await scanFile('./public/index.html', { level: 'AA', preset: 'full' });
+
+// Run an exact subset of rules
+const targeted = await scanHtml('<div style="background-image:url(hero.jpg)"></div>', {
+  rules: ['images', 'backgroundImages'],
+});
+
+// Or resolve a built-in preset yourself
+// import { RULE_PRESETS } from 'wcag-scanner';
+// const results = await scanHtml(html, { rules: RULE_PRESETS.full });
+
+// Generate and save a report
+const html = formatReport(results, 'html');   // 'html' | 'json' | 'console'
+saveReport(html, 'accessibility-report.html');
 ```
 
-### Express Middleware Usage Example:
+## 🌐 Express Middleware
 
-```JavaScript
+Automatically scan every HTML response in your Express app and inject a violation badge.
+
+```js
 import express from 'express';
 import { middleware } from 'wcag-scanner';
 
 const app = express();
 
-// Add the WCAG scanner middleware
 app.use(middleware.express.createMiddleware({
-  enabled: true,
-  level: 'AA',
-  headerName: 'X-WCAG-Violations',
-  inlineReport: true,
-  onViolation: (results, req, res) => {
-    console.log(`Found ${results.violations.length} accessibility issues in ${req.path}`);
-  }
+  enabled:      true,
+  level:        'AA',
+  preset:       'fast',
+  headerName:   'X-WCAG-Violations', // violation count added to response headers
+  inlineReport: true,                // inject a small widget into the HTML response
+  onViolation: (results, req) => {
+    console.log(`${results.violations.length} issues on ${req.path}`);
+  },
 }));
 
-// Your routes
+// Switch to preset: 'full' if you also want heavier checks like backgroundImages.
+
 app.get('/', (req, res) => {
-  res.send(`
-    <!DOCTYPE html>
-    <html>
-      <head>
-        <title>Test Page</title>
-      </head>
-      <body>
-        <h1>Hello World</h1>
-        <img src="logo.png"> <!-- Missing alt text will trigger violation -->
-      </body>
-    </html>
-  `);
+  res.send(`<!DOCTYPE html><html><body><h1>Hello</h1></body></html>`);
 });
 
-app.listen(3000, () => {
-  console.log('Server running on http://localhost:3000');
-});
+app.listen(3000);
 ```
 
-### Programmatic API Usage Example:
-```JavaScript
-import { scanHtml, scanUrl, formatReport } from 'wcag-scanner';
-
-async function checkMyWebsite() {
-  try {
-    // Scan a URL
-    const results = await scanUrl('https://example.com', { level: 'AA' });
-    
-    console.log(`Found ${results.violations.length} accessibility issues`);
-    
-    // Generate a report
-    const htmlReport = formatReport(results, 'html');
-    
-    // Save the report
-    fs.writeFileSync('accessibility-report.html', htmlReport);
-  } catch (error) {
-    console.error('Error scanning website:', error);
-  }
-}
-
-async function checkHtmlString() {
-  const html = `
-    <!DOCTYPE html>
-    <html>
-      <head>
-        <title>Test</title>
-      </head>
-      <body>
-        <img src="logo.png"> <!-- Missing alt text -->
-      </body>
-    </html>
-  `;
-  
-  const results = await scanHtml(html);
-  console.log(formatReport(results, 'console'));
-}
-```
+## 📊 Profile Summary
+
+Current local synthetic benchmark baseline from the repo profiling scripts:
+
+| Rule | Command | Approx. duration |
+| --- | --- | --- |
+| `images` | `npm run profile:images` | `128ms` |
+| `forms` | `npm run profile:forms` | `484ms` |
+| `aria` | `npm run profile:aria` | `398ms` |
+| `contrast` | `npm run profile:contrast` | `1836ms` |
+
+Notes:
+- These are synthetic local benchmarks, not production browser traces.
+- `contrast` is currently the main runtime hotspot.
+- `backgroundImages` is intentionally excluded from the default `fast` preset because it is a heavier optional check.

package/dist/index.d.ts

@@ -2,39 +2,21 @@ import { WCAGScanner } from './scanner';
 import { ScannerOptions, ScanResults } from './types';
 import { ReporterFormat } from './reporters';
 import middleware from './middleware';
+export { FAST_RULES, FULL_RULES, RULE_PRESETS, resolveRuleNames } from './rules/presets';
 /**
- * Scan HTML string for WCAG violations
- * @param html HTML content to scan
- * @param options Scanner options
- * @returns Promise<ScanResults> Scan results
+ * Scan an HTML string for WCAG violations.
  */
 export declare function scanHtml(html: string, options?: ScannerOptions): Promise<ScanResults>;
 /**
- * Scan HTML file for WCAG violations
- * @param filePath Path to HTML file
- * @param options Scanner options
- * @returns Promise<ScanResults> Scan results
+ * Scan a local HTML file for WCAG violations.
  */
 export declare function scanFile(filePath: string, options?: ScannerOptions): Promise<ScanResults>;
 /**
- * Scan a URL for WCAG violations using Rust/WASM scraping
- * @param url URL to scan
- * @param options Scanner options
- * @returns Promise<ScanResults> Scan results
- */
-export declare function scanUrl(url: string, options?: ScannerOptions): Promise<ScanResults>;
-/**
- * Generate a report from scan results
- * @param results Scan results
- * @param format Report format
- * @param options Scanner options
- * @returns Report string
+ * Generate a report from scan results.
  */
 export declare function formatReport(results: ScanResults, format?: ReporterFormat, options?: ScannerOptions): string;
 /**
- * Save report to a file
- * @param report Report string
- * @param filePath Output file path
+ * Save a report string to a file.
  */
 export declare function saveReport(report: string, filePath: string): void;
 export { WCAGScanner };
@@ -44,7 +26,6 @@ export { middleware };
 declare const _default: {
     scanHtml: typeof scanHtml;
     scanFile: typeof scanFile;
-    scanUrl: typeof scanUrl;
     formatReport: typeof formatReport;
     saveReport: typeof saveReport;
     middleware: {

package/dist/index.js

@@ -10,28 +10,6 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
 }));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
@@ -39,10 +17,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.middleware = exports.WCAGScanner = void 0;
+exports.middleware = exports.WCAGScanner = exports.resolveRuleNames = exports.RULE_PRESETS = exports.FULL_RULES = exports.FAST_RULES = void 0;
 exports.scanHtml = scanHtml;
 exports.scanFile = scanFile;
-exports.scanUrl = scanUrl;
 exports.formatReport = formatReport;
 exports.saveReport = saveReport;
 const scanner_1 = require("./scanner");
@@ -52,13 +29,13 @@ const middleware_1 = __importDefault(require("./middleware"));
 exports.middleware = middleware_1.default;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const crypto_1 = __importDefault(require("crypto"));
-const os_1 = __importDefault(require("os"));
+var presets_1 = require("./rules/presets");
+Object.defineProperty(exports, "FAST_RULES", { enumerable: true, get: function () { return presets_1.FAST_RULES; } });
+Object.defineProperty(exports, "FULL_RULES", { enumerable: true, get: function () { return presets_1.FULL_RULES; } });
+Object.defineProperty(exports, "RULE_PRESETS", { enumerable: true, get: function () { return presets_1.RULE_PRESETS; } });
+Object.defineProperty(exports, "resolveRuleNames", { enumerable: true, get: function () { return presets_1.resolveRuleNames; } });
 /**
- * Scan HTML string for WCAG violations
- * @param html HTML content to scan
- * @param options Scanner options
- * @returns Promise<ScanResults> Scan results
+ * Scan an HTML string for WCAG violations.
  */
 async function scanHtml(html, options = {}) {
     const scanner = new scanner_1.WCAGScanner(options);
@@ -66,24 +43,7 @@ async function scanHtml(html, options = {}) {
     return scanner.scan();
 }
 /**
- * Get WASM scraper instance
- */
-async function getWasmScraper() {
-    try {
-        const { default: wasmModule } = await Promise.resolve().then(() => __importStar(require('./wasm')));
-        await wasmModule.initialize();
-        return wasmModule;
-    }
-    catch (error) {
-        console.error('Failed to load WASM scraper, falling back to HTTP requests:', error);
-        return null;
-    }
-}
-/**
- * Scan HTML file for WCAG violations
- * @param filePath Path to HTML file
- * @param options Scanner options
- * @returns Promise<ScanResults> Scan results
+ * Scan a local HTML file for WCAG violations.
  */
 async function scanFile(filePath, options = {}) {
     const html = fs_1.default.readFileSync(path_1.default.resolve(filePath), 'utf8');
@@ -93,91 +53,16 @@ async function scanFile(filePath, options = {}) {
     return scanner.scan();
 }
 /**
- * Scan a URL for WCAG violations using Rust/WASM scraping
- * @param url URL to scan
- * @param options Scanner options
- * @returns Promise<ScanResults> Scan results
- */
-async function scanUrl(url, options = {}) {
-    console.log(`Scanning URL: ${url}`);
-    // Create temp directory for saving content
-    const tempDir = path_1.default.join(os_1.default.tmpdir(), 'wcag-scanner-temp');
-    if (!fs_1.default.existsSync(tempDir)) {
-        fs_1.default.mkdirSync(tempDir, { recursive: true });
-    }
-    // Generate unique file name
-    const fileId = crypto_1.default.createHash('md5').update(url + Date.now().toString()).digest('hex').substring(0, 10);
-    const tempFile = path_1.default.join(tempDir, `${fileId}.html`);
-    try {
-        // Get the WASM scraper
-        const wasmScraper = await getWasmScraper();
-        let html;
-        if (wasmScraper) {
-            // Use WASM scraper
-            html = await wasmScraper.scrapeUrl(url);
-        }
-        else {
-            // Fallback to simple HTTP request
-            const response = await fetch(url, {
-                headers: {
-                    'User-Agent': 'WCAG-Scanner/1.0-js'
-                }
-            });
-            if (!response.ok) {
-                throw new Error(`HTTP error: ${response.status}`);
-            }
-            html = await response.text();
-        }
-        if (!html || html.trim().length === 0) {
-            throw new Error('Scraper returned empty HTML content');
-        }
-        console.log(`Successfully scraped ${html.length} bytes of HTML content`);
-        // Save content to temp file
-        fs_1.default.writeFileSync(tempFile, html);
-        console.log(`Saved scraped content to ${tempFile}`);
-        // If verbose logging is enabled, show a sample
-        if (options.verbose) {
-            console.log('First 200 characters of HTML:');
-            console.log(html.substring(0, 200) + '...');
-        }
-        // Run the scanner on the HTML content
-        const scanner = new scanner_1.WCAGScanner({
-            ...options,
-            baseUrl: url
-        });
-        await scanner.loadHTML(html, url);
-        return scanner.scan();
-    }
-    catch (error) {
-        console.error('Error scanning URL:', error);
-        throw error;
-    }
-}
-/**
- * Generate a report from scan results
- * @param results Scan results
- * @param format Report format
- * @param options Scanner options
- * @returns Report string
+ * Generate a report from scan results.
  */
 function formatReport(results, format = 'json', options = {}) {
     return (0, reporters_1.generateReport)(results, format, options);
 }
 /**
- * Save report to a file
- * @param report Report string
- * @param filePath Output file path
+ * Save a report string to a file.
  */
 function saveReport(report, filePath) {
     fs_1.default.writeFileSync(filePath, report);
 }
 __exportStar(require("./types"), exports);
-// Default export with all main functions
-exports.default = {
-    scanHtml,
-    scanFile,
-    scanUrl,
-    formatReport,
-    saveReport,
-    middleware: middleware_1.default
-};
+exports.default = { scanHtml, scanFile, formatReport, saveReport, middleware: middleware_1.default };

package/dist/middleware/express.js

@@ -11,13 +11,13 @@ function createMiddleware(options = {}) {
     const defaultOptions = {
         enabled: process.env.NODE_ENV !== 'production', // Disable in production by default
         level: 'AA',
-        headerName: 'X-WCAG-Violations',
+        headerName: undefined,
         inlineReport: false,
         ...options
     };
     return async function wcagScannerMiddleware(req, res, next) {
         // Skip if disabled or non-HTML request
-        if (!defaultOptions.enabled || !shouldProcessRequest(req)) {
+        if (!defaultOptions.enabled || !shouldProcessRequest(req) || !needsScanning(defaultOptions)) {
             return next();
         }
         // Store original send method
@@ -25,32 +25,47 @@ function createMiddleware(options = {}) {
         // Override send method to intercept HTML responses
         res.send = function (body) {
             // Only process HTML responses
-            if (typeof body === 'string' && isHtmlResponse(res)) {
+            if (typeof body === 'string' && isHtmlResponse(res) && looksLikeHtmlDocument(body)) {
                 try {
                     // Create scanner
                     const scanner = new index_1.WCAGScanner(defaultOptions);
-                    // Run scan asynchronously (we can't make res.send async)
-                    scanner.loadHTML(body).then(() => {
-                        return scanner.scan();
-                    }).then((results) => {
-                        // Add violation count header
-                        res.setHeader(defaultOptions.headerName || 'X-WCAG-Violations', results.violations.length.toString());
-                        // Call violation handler if provided
+                    const response = this;
+                    // If we do not need to mutate the response or set headers, scan after sending.
+                    if (!requiresBlockingScan(defaultOptions)) {
+                        void scanner.loadHTML(body)
+                            .then(() => scanner.scan())
+                            .then((results) => {
+                            if (defaultOptions.onViolation && results.violations.length > 0) {
+                                defaultOptions.onViolation(results, req, res);
+                            }
+                        })
+                            .catch((error) => {
+                            console.error('Error in WCAG scanner middleware:', error);
+                        });
+                        return originalSend.call(response, body);
+                    }
+                    // Run scan before sending when we need to add headers or inline report.
+                    void scanner.loadHTML(body)
+                        .then(() => scanner.scan())
+                        .then((results) => {
+                        let finalBody = body;
+                        if (defaultOptions.headerName) {
+                            res.setHeader(defaultOptions.headerName, results.violations.length.toString());
+                        }
                         if (defaultOptions.onViolation && results.violations.length > 0) {
                             defaultOptions.onViolation(results, req, res);
                         }
-                        // Add inline report if enabled
                         if (defaultOptions.inlineReport && results.violations.length > 0) {
-                            body = insertInlineReport(body, results);
+                            finalBody = insertInlineReport(body, results);
                         }
-                        // Send modified response
-                        originalSend.call(res, body);
-                    }).catch((error) => {
+                        res.send = originalSend;
+                        originalSend.call(response, finalBody);
+                    })
+                        .catch((error) => {
                         console.error('Error in WCAG scanner middleware:', error);
-                        // Send original response if there's an error
-                        originalSend.call(res, body);
+                        res.send = originalSend;
+                        originalSend.call(response, body);
                     });
-                    // Return a dummy response to prevent Express from sending twice
                     return res;
                 }
                 catch (error) {
@@ -93,6 +108,15 @@ function isHtmlResponse(res) {
     const contentType = res.get('Content-Type') || '';
     return contentType.includes('html');
 }
+function needsScanning(options) {
+    return Boolean(options.inlineReport || options.headerName || options.onViolation);
+}
+function requiresBlockingScan(options) {
+    return Boolean(options.inlineReport || options.headerName);
+}
+function looksLikeHtmlDocument(body) {
+    return /<(html|body|main|div|section|article|img|svg|form|a|button)\b/i.test(body);
+}
 /**
  * Insert inline accessibility report into HTML
  * @param html Original HTML

package/dist/react/WcagDevOverlay.d.ts

@@ -1,6 +1,8 @@
 import React from 'react';
+import { RulePreset } from '../types';
 export interface WcagDevOverlayProps {
     level?: 'A' | 'AA' | 'AAA';
+    preset?: RulePreset;
     rules?: string[];
     position?: 'bottom-right' | 'bottom-left';
     debounce?: number;