wcag-scanner 1.0.0

package/dist/rules/images.js

@@ -0,0 +1,390 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Check image accessibility (alt text, etc.)
+ */
+exports.default = {
+    /**
+    * Run image accessibility checks
+    * @param document DOM document
+    * @param window Browser window
+    * @param options Scanner options
+    * @returns Promise<ScanResults> Results from image checks
+    */
+    async check(document, window, options) {
+        const results = {
+            passes: [],
+            violations: [],
+            warnings: []
+        };
+        // Check <img> elements
+        checkImageElements(document, results);
+        // Check <svg> elements
+        checkSvgElements(document, results);
+        // Check background images
+        checkBackgroundImages(document, window, results);
+        // Check image maps
+        checkImageMaps(document, results);
+        return results;
+    }
+};
+/**
+ * Check all <img> elements for accessibility issues
+ * @param document DOM document
+ * @param results DOM results
+ */
+function checkImageElements(document, results) {
+    const images = document.querySelectorAll('img');
+    images.forEach(img => {
+        const info = {
+            tagName: 'img',
+            id: img.id || null,
+            className: img.className || null,
+            src: img.getAttribute('src') || null
+        };
+        // Check for alt attribute
+        if (!img.hasAttribute('alt')) {
+            results.violations.push({
+                rule: 'img-alt',
+                element: info,
+                impact: 'critical',
+                description: 'Image is missing alt text',
+                snippet: img.outerHTML,
+                wcag: ['1.1.1'],
+                help: 'Images must have alternative text',
+                helpUrl: 'https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html'
+            });
+        }
+        else {
+            const altText = img.getAttribute('alt') || '';
+            if (altText === '') {
+                // Empty alt is valid for decorative images
+                if (!isLikelyDecorativeImage(img)) {
+                    results.warnings.push({
+                        rule: 'img-alt-decorative',
+                        element: info,
+                        impact: 'moderate',
+                        description: 'Image has empty alt text but may not be decorative',
+                        snippet: img.outerHTML,
+                        wcag: ['1.1.1'],
+                        help: 'Verify this image is decorative; if not, add descriptive alt text'
+                    });
+                }
+                else {
+                    results.passes.push({
+                        rule: 'img-alt-decorative',
+                        element: info,
+                        description: 'Decorative image has appropriate empty alt text',
+                        snippet: img.outerHTML
+                    });
+                }
+            }
+            else if (hasGenericAltText(altText)) {
+                // Check for generic/placeholder alt text
+                results.warnings.push({
+                    rule: 'img-alt-generic',
+                    element: info,
+                    impact: 'moderate',
+                    description: 'Image may have generic/placeholder alt text',
+                    snippet: img.outerHTML,
+                    wcag: ['1.1.1'],
+                    help: 'Replace generic alt text with specific description'
+                });
+            }
+            else if (altText.length > 125) {
+                // Long alt text warning
+                results.warnings.push({
+                    rule: 'img-alt-long',
+                    element: info,
+                    impact: 'minor',
+                    description: 'Alt text is unusually long (over 125 characters)',
+                    snippet: img.outerHTML,
+                    wcag: ['1.1.1'],
+                    help: 'Consider using a more concise alt text or using a longdesc attribute'
+                });
+            }
+            else {
+                results.passes.push({
+                    rule: 'img-alt',
+                    element: info,
+                    description: 'Image has appropriate alt text',
+                    snippet: img.outerHTML
+                });
+            }
+        }
+        // Check for responsive images
+        if (!img.hasAttribute('width') || !img.hasAttribute('height')) {
+            results.warnings.push({
+                rule: 'img-dimensions',
+                element: info,
+                impact: 'minor',
+                description: 'Image is missing width and/or height attributes',
+                snippet: img.outerHTML,
+                help: 'Set explicit width and height to prevent layout shifts'
+            });
+        }
+    });
+}
+/**
+ * Check SVG elements for accessibility
+ * @param document DOM document
+ * @param results Scan results
+ */
+function checkSvgElements(document, results) {
+    const svgs = document.querySelectorAll('svg');
+    svgs.forEach(svg => {
+        var _a, _b;
+        const info = {
+            tagName: 'svg',
+            id: svg.id || null,
+            className: ((_a = svg.classList) === null || _a === void 0 ? void 0 : _a.toString()) || null
+        };
+        // Check for role="img"
+        if (!svg.hasAttribute('role') || svg.getAttribute('role') !== 'img') {
+            results.warnings.push({
+                rule: 'svg-role',
+                element: info,
+                impact: 'moderate',
+                description: 'SVG element should have role="img"',
+                snippet: svg.outerHTML.slice(0, 150) + (svg.outerHTML.length > 150 ? '...' : ''),
+                wcag: ['1.1.1'],
+                help: 'Add role="img" to SVG elements'
+            });
+        }
+        // Check for accessible name via title or aria-label
+        const title = svg.querySelector('title');
+        const ariaLabel = svg.getAttribute('aria-label');
+        const ariaLabelledby = svg.getAttribute('aria-labelledby');
+        if (!title && !ariaLabel && !ariaLabelledby) {
+            results.violations.push({
+                rule: 'svg-accessible-name',
+                element: info,
+                impact: 'serious',
+                description: 'SVG lacks accessible name (title, aria-label, or aria-labelledby)',
+                snippet: svg.outerHTML.slice(0, 150) + (svg.outerHTML.length > 150 ? '...' : ''),
+                wcag: ['1.1.1'],
+                help: 'Add a <title> element or aria-label attribute to SVG'
+            });
+        }
+        else if (title && !((_b = title.textContent) === null || _b === void 0 ? void 0 : _b.trim())) {
+            results.violations.push({
+                rule: 'svg-title-empty',
+                element: info,
+                impact: 'serious',
+                description: 'SVG title element is empty',
+                snippet: svg.outerHTML.slice(0, 150) + (svg.outerHTML.length > 150 ? '...' : ''),
+                wcag: ['1.1.1'],
+                help: 'Add content to the SVG title element'
+            });
+        }
+        else {
+            results.passes.push({
+                rule: 'svg-accessible-name',
+                element: info,
+                description: 'SVG has an accessible name',
+                snippet: svg.outerHTML.slice(0, 150) + (svg.outerHTML.length > 150 ? '...' : '')
+            });
+        }
+    });
+}
+/**
+ * Check background images for accessibility issues
+ * @param document DOM document
+ * @param window Window object
+ * @param results Scan results
+ */
+function checkBackgroundImages(document, window, results) {
+    // Find elements with background image
+    const allElements = document.querySelectorAll('*');
+    allElements.forEach(element => {
+        var _a, _b, _c;
+        const style = window.getComputedStyle(element);
+        const backgroundImage = style.backgroundImage;
+        // Skip if no background image or if it's "none"
+        if (!backgroundImage || backgroundImage === 'none') {
+            return;
+        }
+        // Skip if the element is hidden/decorative
+        if (isElementHidden(element) || element.getAttribute('aria-hidden') === 'true') {
+            return;
+        }
+        const info = {
+            tagName: element.tagName.toLowerCase(),
+            id: element.id || null,
+            className: ((_a = element.className) === null || _a === void 0 ? void 0 : _a.toString()) || null,
+            textContent: ((_b = element.textContent) === null || _b === void 0 ? void 0 : _b.substring(0, 50)) || null
+        };
+        // Check if meaningful background image has text alternative
+        const hasTextContent = ((_c = element.textContent) === null || _c === void 0 ? void 0 : _c.trim()) !== '';
+        const hasAriaLabel = element.hasAttribute('aria-label');
+        const hasAriaLabelledby = element.hasAttribute('aria-labelledby');
+        const hasTitle = element.hasAttribute('title');
+        if (!hasTextContent && !hasAriaLabel && !hasAriaLabelledby && !hasTitle) {
+            // Only warn if the background image looks like content (not decoration)
+            if (backgroundImage.includes('url(') && !isBackgroundLikelyDecorative(element)) {
+                results.warnings.push({
+                    rule: 'background-image',
+                    element: info,
+                    impact: 'moderate',
+                    description: 'Element with background image may need text alternative',
+                    snippet: element.outerHTML.slice(0, 150) + (element.outerHTML.length > 150 ? '...' : ''),
+                    wcag: ['1.1.1'],
+                    help: 'If the background image conveys meaning, add text alternative via aria-label or text content'
+                });
+            }
+        }
+    });
+}
+/**
+ * Check image maps for accessibility
+ * @param document DOM document
+ * @param results Scan results
+ */
+function checkImageMaps(document, results) {
+    const maps = document.querySelectorAll('map');
+    maps.forEach(map => {
+        const info = {
+            tagName: 'map',
+            id: map.id || null,
+            name: map.getAttribute('name') || null
+        };
+        // Check if the map is used
+        const usedByImages = document.querySelectorAll(`img[usemap="#${map.name}"]`);
+        if (usedByImages.length === 0) {
+            results.warnings.push({
+                rule: 'map-unused',
+                element: info,
+                impact: 'minor',
+                description: 'Image map appears to be unused',
+                snippet: map.outerHTML,
+                help: 'Remove unused image maps'
+            });
+            return;
+        }
+        // Check area elements
+        const areas = map.querySelectorAll('area');
+        areas.forEach(area => {
+            const areaInfo = {
+                tagName: 'area',
+                shape: area.getAttribute('shape') || null,
+                coords: area.getAttribute('coords') || null,
+                href: area.getAttribute('href') || null
+            };
+            // Check for alt text
+            if (!area.hasAttribute('alt')) {
+                results.violations.push({
+                    rule: 'area-alt',
+                    element: areaInfo,
+                    impact: 'critical',
+                    description: 'Area element in image map is missing alt text',
+                    snippet: area.outerHTML,
+                    wcag: ['1.1.1', '2.4.4'],
+                    help: 'Add alt text to all area elements'
+                });
+            }
+            else {
+                results.passes.push({
+                    rule: 'area-alt',
+                    element: areaInfo,
+                    description: 'Area element has alt text',
+                    snippet: area.outerHTML
+                });
+            }
+        });
+    });
+}
+/**
+ * Check if an element is hidden
+ * @param element Element to check
+ */
+function isElementHidden(element) {
+    // This is a simplified check - a real implementation would be more comprehensive
+    if (element.hasAttribute('hidden') || element.getAttribute('aria-hidden') === 'true') {
+        return true;
+    }
+    // Check computed style if available
+    try {
+        const style = getComputedStyle(element);
+        return style.display === 'none' || style.visibility === 'hidden';
+    }
+    catch (e) {
+        return false;
+    }
+}
+/**
+ * Check if a background image is likely decorative
+ * @param element Element to check
+ */
+function isBackgroundLikelyDecorative(element) {
+    var _a, _b;
+    // Common decorative pattern elements
+    const decorativeElements = ['header', 'footer', 'section', 'article', 'div'];
+    const tagName = ((_a = element.tagName) === null || _a === void 0 ? void 0 : _a.toLowerCase()) || '';
+    if (decorativeElements.includes(tagName)) {
+        // Check for certain classes that might indicate decorative backgrounds
+        const className = ((_b = element.className) === null || _b === void 0 ? void 0 : _b.toString()) || '';
+        if (className.includes('background') ||
+            className.includes('banner') ||
+            className.includes('hero') ||
+            className.includes('container') ||
+            className.includes('wrapper') ||
+            className.includes('section')) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Determine if an image is likely decorative
+ * @param img Image to check
+ */
+function isLikelyDecorativeImage(img) {
+    var _a;
+    // Images with role="presentation" are explicitly decorative
+    if (img.getAttribute('role') === 'presentation' || img.getAttribute('role') === 'none') {
+        return true;
+    }
+    // Very small images are often decorative
+    const width = parseInt(img.getAttribute('width') || img.width.toString());
+    const height = parseInt(img.getAttribute('height') || img.height.toString());
+    if ((width > 0 && width < 16) || (height > 0 && height < 16)) {
+        return true;
+    }
+    // Check class names for hints
+    const className = img.className || '';
+    if (className.includes('decoration') ||
+        className.includes('ornament') ||
+        className.includes('icon') ||
+        className.includes('separator') ||
+        className.includes('bg') ||
+        className.includes('background')) {
+        return true;
+    }
+    // Check if the image is inside a link with text
+    const parentLink = img.closest('a');
+    if (parentLink && ((_a = parentLink.textContent) === null || _a === void 0 ? void 0 : _a.trim()) && parentLink.textContent.trim().length > 0) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if alt text appears to be generic or placeholder text
+ * @param altText Alt text to check
+ */
+function hasGenericAltText(altText) {
+    const genericTerms = ['image', 'picture', 'photo', 'img', 'graphic', 'icon', 'logo', 'photo.jpg', 'untitled'];
+    const lowerAlt = altText.toLowerCase().trim();
+    // Check for file extensions in alt text
+    if (lowerAlt.match(/\.(jpg|jpeg|png|gif|webp|svg)$/i)) {
+        return true;
+    }
+    // Check for generic terms used alone
+    if (genericTerms.includes(lowerAlt)) {
+        return true;
+    }
+    // Check for very short alt text that's not meaningful
+    if (lowerAlt.length < 5 && !['ok', 'yes', 'no'].includes(lowerAlt)) {
+        return true;
+    }
+    return false;
+}

package/dist/rules/keyboard.d.ts

@@ -0,0 +1,15 @@
+import { ScannerOptions, ScanResults } from '../types';
+/**
+ * Accessibility checker for tab index, keyboard events, focus indicators, and interactive elements
+ */
+declare const _default: {
+    /**
+     * Run accessibility checks on tab index, keyboard events, focus indicators, and interactive elements
+     * @param document DOM document
+     * @param window Browser window
+     * @param options Scanner options
+     * @returns Promise<ScanResults> Results from accessibility checks
+     */
+    check(document: Document, window: Window, options: ScannerOptions): Promise<ScanResults>;
+};
+export default _default;

package/dist/rules/keyboard.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Accessibility checker for tab index, keyboard events, focus indicators, and interactive elements
+ */
+exports.default = {
+    /**
+     * Run accessibility checks on tab index, keyboard events, focus indicators, and interactive elements
+     * @param document DOM document
+     * @param window Browser window
+     * @param options Scanner options
+     * @returns Promise<ScanResults> Results from accessibility checks
+     */
+    async check(document, window, options) {
+        const results = {
+            passes: [],
+            violations: [],
+            warnings: []
+        };
+        // Check tabindex values
+        checkTabindex(document, results);
+        // Check keyboard event handlers
+        checkKeyboardEvents(document, results);
+        // Check focus indicators
+        checkFocusIndicators(document, window, results);
+        // Check interactive elements
+        checkInteractiveElements(document, results);
+        return results;
+    }
+};
+/**
+ * Check for valid tabindex values
+ * @param document DOM document
+ * @param results Scan results
+ */
+function checkTabindex(document, results) {
+    const elements = document.querySelectorAll('[tabindex]');
+    elements.forEach(element => {
+        const tabindex = element.getAttribute('tabindex');
+        const tabindexNum = parseInt(tabindex || '0');
+        const info = {
+            tagName: element.tagName.toLowerCase(),
+            id: element.id || null,
+            tabindex: tabindex || null
+        };
+        // Check for positive tabindex values (creates a custom tab order)
+        if (tabindexNum > 0) {
+            results.warnings.push({
+                rule: 'tabindex-positive',
+                element: info,
+                impact: 'moderate',
+                description: `Element has a positive tabindex value (${tabindexNum})`,
+                snippet: element.outerHTML,
+                wcag: ['2.4.3'],
+                help: 'Avoid positive tabindex values as they create a custom tab order'
+            });
+        }
+        // Check if non-interactive elements are focusable
+        const isNativelyFocusable = [
+            'a', 'button', 'input', 'select', 'textarea', 'summary', 'details'
+        ].includes(element.tagName.toLowerCase());
+        const hasInteractiveRole = element.hasAttribute('role') && [
+            'button', 'checkbox', 'link', 'menuitem', 'menuitemcheckbox',
+            'menuitemradio', 'option', 'radio', 'slider', 'tab', 'textbox',
+            'switch', 'searchbox', 'combobox'
+        ].includes(element.getAttribute('role') || '');
+        if (!isNativelyFocusable && !hasInteractiveRole && tabindexNum >= 0) {
+            results.warnings.push({
+                rule: 'tabindex-non-interactive',
+                element: info,
+                impact: 'moderate',
+                description: 'Non-interactive element has a tabindex making it focusable',
+                snippet: element.outerHTML,
+                wcag: ['2.1.1'],
+                help: 'Only make interactive elements focusable or add appropriate ARIA roles'
+            });
+        }
+    });
+}
+/**
+ * Check keyboard event handlers
+ * @param document DOM document
+ * @param results Scan results
+ */
+function checkKeyboardEvents(document, results) {
+    // Elements with mouse event handlers but no keyboard equivalent
+    const allElements = document.querySelectorAll('*');
+    allElements.forEach(element => {
+        // This is a simple check - a full implementation would analyze event handlers
+        // through JavaScript frameworks, which is complex
+        const hasOnClick = element.hasAttribute('onclick');
+        const hasOnMousedown = element.hasAttribute('onmousedown');
+        const hasOnMouseup = element.hasAttribute('onmouseup');
+        const hasOnKeydown = element.hasAttribute('onkeydown');
+        const hasOnKeyup = element.hasAttribute('onkeyup');
+        const hasOnKeypress = element.hasAttribute('onkeypress');
+        const info = {
+            tagName: element.tagName.toLowerCase(),
+            id: element.id || null,
+            className: element.className || null
+        };
+        // Check if element has mouse event but no keyboard event
+        if ((hasOnClick || hasOnMousedown || hasOnMouseup) &&
+            !(hasOnKeydown || hasOnKeyup || hasOnKeypress)) {
+            // Skip natively clickable elements (browsers handle keyboard events)
+            if (['a', 'button', 'input', 'select', 'textarea'].includes(element.tagName.toLowerCase())) {
+                return;
+            }
+            results.warnings.push({
+                rule: 'keyboard-event-equivalents',
+                element: info,
+                impact: 'moderate',
+                description: 'Element has mouse event handlers but no keyboard event handlers',
+                snippet: element.outerHTML.slice(0, 150) + (element.outerHTML.length > 150 ? '...' : ''),
+                wcag: ['2.1.1'],
+                help: 'Ensure all functionality is operable through keyboard'
+            });
+        }
+    });
+}
+/**
+ * Check for focus indicators
+ * @param document DOM document
+ * @param window Browser window
+ * @param results Scan results
+ */
+function checkFocusIndicators(document, window, results) {
+    // Elements that should have visible focus indicators
+    const focusableElements = document.querySelectorAll('a[href], button, input, textarea, select, [tabindex]:not([tabindex="-1"])');
+    focusableElements.forEach(element => {
+        // Without actually applying focus, we can't check the exact appearance
+        // But we can check for CSS that might suppress focus styles
+        const style = window.getComputedStyle(element);
+        const info = {
+            tagName: element.tagName.toLowerCase(),
+            id: element.id || null,
+            className: element.className || null
+        };
+        // Check for CSS that might remove the focus outline
+        if (style.outlineStyle === 'none' || style.outlineWidth === '0px') {
+            // Look for alternative focus indicators like background-color changes or borders
+            // This is a simplified check
+            results.warnings.push({
+                rule: 'focus-visible',
+                element: info,
+                impact: 'moderate',
+                description: 'Element may be missing visible focus indicator',
+                snippet: element.outerHTML.slice(0, 150) + (element.outerHTML.length > 150 ? '...' : ''),
+                wcag: ['2.4.7'],
+                help: 'Ensure all focusable elements have visible focus indicators'
+            });
+        }
+    });
+}
+/**
+ * Check interactive elements
+ * @param document DOM document
+ * @param results Scan results
+ */
+function checkInteractiveElements(document, results) {
+    // Check for non-button elements that act as buttons
+    const clickableItems = document.querySelectorAll('div[onclick], span[onclick], a:not([href])');
+    clickableItems.forEach(element => {
+        const info = {
+            tagName: element.tagName.toLowerCase(),
+            id: element.id || null,
+            className: element.className || null
+        };
+        // Check for button role
+        const hasButtonRole = element.getAttribute('role') === 'button';
+        // Check for interactivity properties
+        const isInteractive = element.hasAttribute('tabindex') ||
+            element.hasAttribute('onclick') ||
+            element.hasAttribute('onkeyup') ||
+            element.hasAttribute('onkeydown');
+        if (isInteractive && !hasButtonRole && element.tagName.toLowerCase() !== 'button') {
+            results.violations.push({
+                rule: 'interactive-semantics',
+                element: info,
+                impact: 'serious',
+                description: 'Interactive element is missing semantic role',
+                snippet: element.outerHTML.slice(0, 150) + (element.outerHTML.length > 150 ? '...' : ''),
+                wcag: ['4.1.2'],
+                help: 'Add role="button" to non-button elements that act as buttons'
+            });
+        }
+        // Check if interactive elements are focusable
+        if (isInteractive && !element.hasAttribute('tabindex') && element.tagName.toLowerCase() !== 'a') {
+            results.violations.push({
+                rule: 'interactive-focusable',
+                element: info,
+                impact: 'serious',
+                description: 'Interactive element is not keyboard focusable',
+                snippet: element.outerHTML.slice(0, 150) + (element.outerHTML.length > 150 ? '...' : ''),
+                wcag: ['2.1.1'],
+                help: 'Add tabindex="0" to make interactive elements focusable'
+            });
+        }
+    });
+    // Check for links that open in new windows
+    const linksNewWindow = document.querySelectorAll('a[target="_blank"]');
+    linksNewWindow.forEach(link => {
+        var _a, _b;
+        const info = {
+            tagName: 'a',
+            id: link.id || null,
+            href: link.getAttribute('href') || null,
+            target: '_blank'
+        };
+        const hasWarning = ((_a = link.textContent) === null || _a === void 0 ? void 0 : _a.toLowerCase().includes('new window')) ||
+            ((_b = link.textContent) === null || _b === void 0 ? void 0 : _b.toLowerCase().includes('new tab')) ||
+            link.querySelector('svg, img[alt*="new window"], img[alt*="external"]');
+        if (!hasWarning) {
+            results.warnings.push({
+                rule: 'link-new-window',
+                element: info,
+                impact: 'moderate',
+                description: 'Link opens in new window without warning',
+                snippet: link.outerHTML,
+                wcag: ['3.2.2'],
+                help: 'Indicate in the link text that it opens in a new window'
+            });
+        }
+    });
+}

package/dist/rules/structure.d.ts

@@ -0,0 +1,15 @@
+import { ScannerOptions, ScanResults } from '../types';
+/**
+ * Check accessibility of structural elements (headings, landmarks, etc.)
+ */
+declare const _default: {
+    /**
+     * Run accessibility checks on the entire document
+     * @param document DOM document
+     * @param window Browser window
+     * @param options Scanner options
+     * @returns Promise<ScanResults> Results from accessibility checks
+     */
+    check(document: Document, window: Window, options: ScannerOptions): Promise<ScanResults>;
+};
+export default _default;