wcag-scanner 1.2.64 → 1.2.66

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
+- **6 Built-in Rules**: Images, contrast, forms, ARIA, structure, and keyboard accessibility
+- **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,82 @@ 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
+```
+
+**Options:**
+```ts
+initWcagOverlay({
+  level:    'AA',           // 'A' | 'AA' | 'AAA' — default: 'AA'
+  position: 'bottom-right', // 'bottom-right' | 'bottom-left'
+  debounce: 750,            // ms to wait after DOM change before rescanning
+  rules:    ['images', 'contrast'], // run a subset of rules only
+});
 ```
 
-The overlay is automatically disabled in production (`NODE_ENV=production`) and never ships to your users.
+**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
 
-## How to use
-### CLI Usage Example:
+> The overlay never runs in production (`NODE_ENV=production`) and is never included in your production bundle.
 
-```bash
-# Scan a file
-npx wcag-scanner file index.html --level AA --format console
+## 🔧 Programmatic API
+
+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 a URL
-npx wcag-scanner url https://example.com --format html --output report.html
+// Scan an HTML string
+const results = await scanHtml('<img src="logo.png">', { level: 'AA' });
+console.log(`${results.violations.length} violations found`);
+
+// Scan a local HTML file
+const results = await scanFile('./public/index.html', { level: 'AA' });
+
+// 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',
+  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
 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');
-});
-```
-
-### 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'));
-}
+app.listen(3000);
 ```

package/dist/index.d.ts

@@ -3,38 +3,19 @@ import { ScannerOptions, ScanResults } from './types';
 import { ReporterFormat } from './reporters';
 import middleware from './middleware';
 /**
- * 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 +25,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);
 };
@@ -42,7 +20,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.middleware = exports.WCAGScanner = 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,8 @@ 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"));
 /**
- * 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 +38,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 +48,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/react/WcagDevOverlay.d.ts

@@ -1,12 +1,8 @@
 import React from 'react';
 export interface WcagDevOverlayProps {
-    /** WCAG conformance level (default: 'AA') */
     level?: 'A' | 'AA' | 'AAA';
-    /** Subset of rules to run. Omit to run all. */
     rules?: string[];
-    /** Corner to anchor the overlay (default: 'bottom-right') */
     position?: 'bottom-right' | 'bottom-left';
-    /** Delay in ms between DOM mutation and re-scan (default: 750) */
     debounce?: number;
 }
 export declare const WcagDevOverlay: React.FC<WcagDevOverlayProps>;