@kung-fu/wcag-compliance-scanner

A WCAG 2.1 Level AA accessibility compliance scanner for web applications. Point it at a folder and it analyzes your HTML (and templating) files for accessibility violations, reports them by severity, and can fail CI on the threshold you choose.

Installation

# Global (gives you the wcag-scan / scan-compliance commands)
npm install -g @kung-fu/wcag-compliance-scanner

# Or as a project dependency
npm install @kung-fu/wcag-compliance-scanner

CLI usage

# Scan a directory
wcag-scan ./src

# Interactive mode (guided setup)
wcag-scan --interactive

# Limit to specific file extensions
wcag-scan ./src --extensions html hbs php

# Save a JSON report
wcag-scan ./public --output report.json

# Emit only JSON (for CI pipelines)
wcag-scan ./app --json > violations.json

# Help
wcag-scan --help

scan-compliance is an alias for the same binary.

Failure control (CI)

The scanner exits non-zero when issues at or above your chosen level are found:

wcag-scan ./src                 # fail on critical (default)
wcag-scan ./src --fail-on major # fail on major or critical
wcag-scan ./src --fail-on any   # fail on any issue, incl. warnings
wcag-scan ./src --threshold 10  # fail if more than 10 violations
wcag-scan ./src --no-fail       # report only, never fail

Programmatic usage

const AccessibilityScanner = require('@kung-fu/wcag-compliance-scanner');

const scanner = new AccessibilityScanner();
const report = await scanner.scanDirectory('./my-project');

console.log(`Found ${report.summary.totalViolations} violations`);
scanner.printReport(report);

Supported file types

.html, .hbs / .handlebars, .php, .jsp, .asp (configurable via --extensions).

What it checks

Level A: 1.1.1 (image alt text), 1.3.1 (form labels, table headers), 2.1.1 (non-interactive elements with click handlers), 2.4.1 (skip-nav links), 2.4.4 (descriptive link text), 4.1.2 (ARIA references, non-semantic interactive elements).

Level AA: 1.4.3 (potential color-contrast issues), 1.3.1 (complex table structure).

Each violation reports its WCAG rule and level, the file and line, a description, and a remediation suggestion.

License

MIT