ally-a11y 1.0.0

package/dist/commands/triage.js

@@ -0,0 +1,327 @@
+/**
+ * ally triage command - Interactive issue categorization and prioritization
+ */
+import inquirer from 'inquirer';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import chalk from 'chalk';
+import boxen from 'boxen';
+import { printBanner, createSpinner, printError, printInfo, printSuccess, } from '../utils/ui.js';
+import { suggestInit } from '../utils/errors.js';
+// Severity colors and icons for consistent display
+const severityColors = {
+    critical: chalk.red.bold,
+    serious: chalk.red,
+    moderate: chalk.yellow,
+    minor: chalk.blue,
+};
+const severityIcons = {
+    critical: '!!!',
+    serious: '!!',
+    moderate: '!',
+    minor: 'i',
+};
+const severityLabels = {
+    critical: 'CRITICAL',
+    serious: 'SERIOUS',
+    moderate: 'MODERATE',
+    minor: 'MINOR',
+};
+/**
+ * Format a violation for display in the menu
+ */
+function formatViolationChoice(group) {
+    const color = severityColors[group.impact];
+    const icon = severityIcons[group.impact];
+    const label = severityLabels[group.impact];
+    // Format: [SEVERITY] id (N occurrences) - description
+    const occurrences = group.count === 1 ? '1 occurrence' : `${group.count} occurrences`;
+    return `${color(`[${icon}] ${label}`)} ${chalk.white(group.id)} ${chalk.dim(`(${occurrences})`)} - ${group.help}`;
+}
+/**
+ * Group violations by type/id and count occurrences
+ */
+function groupViolationsByType(report) {
+    const groupMap = new Map();
+    for (const result of report.results) {
+        for (const violation of result.violations) {
+            const existing = groupMap.get(violation.id);
+            if (existing) {
+                // Sum up all node occurrences
+                existing.count += violation.nodes.length;
+            }
+            else {
+                groupMap.set(violation.id, {
+                    id: violation.id,
+                    description: violation.description,
+                    help: violation.help,
+                    helpUrl: violation.helpUrl,
+                    impact: violation.impact,
+                    count: violation.nodes.length,
+                    tags: violation.tags,
+                });
+            }
+        }
+    }
+    // Sort by severity (critical first), then by count (highest first)
+    const severityOrder = {
+        critical: 0,
+        serious: 1,
+        moderate: 2,
+        minor: 3,
+    };
+    return Array.from(groupMap.values()).sort((a, b) => {
+        const severityDiff = severityOrder[a.impact] - severityOrder[b.impact];
+        if (severityDiff !== 0)
+            return severityDiff;
+        return b.count - a.count;
+    });
+}
+/**
+ * Load existing .allyignore patterns
+ */
+async function loadIgnorePatterns() {
+    const ignorePath = resolve('.allyignore');
+    if (!existsSync(ignorePath)) {
+        return [];
+    }
+    try {
+        const content = await readFile(ignorePath, 'utf-8');
+        return content
+            .split('\n')
+            .map(line => line.trim())
+            .filter(line => line && !line.startsWith('#'));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Save patterns to .allyignore
+ */
+async function saveIgnorePatterns(patterns) {
+    const ignorePath = resolve('.allyignore');
+    const existingPatterns = await loadIgnorePatterns();
+    // Combine existing and new patterns, removing duplicates
+    const allPatterns = [...new Set([...existingPatterns, ...patterns])];
+    // Build file content with header
+    const content = `# Ally accessibility ignore file
+# Patterns listed here will be skipped during scans
+# Generated by ally triage
+
+${allPatterns.join('\n')}
+`;
+    await writeFile(ignorePath, content, 'utf-8');
+}
+/**
+ * Load existing backlog
+ */
+async function loadBacklog() {
+    const backlogPath = resolve('.ally', 'backlog.json');
+    if (!existsSync(backlogPath)) {
+        return [];
+    }
+    try {
+        const content = await readFile(backlogPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Save backlog items
+ */
+async function saveBacklog(items) {
+    const backlogPath = resolve('.ally', 'backlog.json');
+    // Ensure .ally directory exists
+    const dirPath = dirname(backlogPath);
+    if (!existsSync(dirPath)) {
+        await mkdir(dirPath, { recursive: true });
+    }
+    const existingBacklog = await loadBacklog();
+    // Merge with existing, updating counts for existing items
+    const backlogMap = new Map();
+    for (const item of existingBacklog) {
+        backlogMap.set(item.id, item);
+    }
+    for (const item of items) {
+        backlogMap.set(item.id, item);
+    }
+    await writeFile(backlogPath, JSON.stringify(Array.from(backlogMap.values()), null, 2), 'utf-8');
+}
+/**
+ * Save fix queue for later use by ally fix
+ */
+async function saveFixQueue(violationIds) {
+    const fixQueuePath = resolve('.ally', 'fix-queue.json');
+    // Ensure .ally directory exists
+    const dirPath = dirname(fixQueuePath);
+    if (!existsSync(dirPath)) {
+        await mkdir(dirPath, { recursive: true });
+    }
+    const queue = {
+        createdAt: new Date().toISOString(),
+        violations: violationIds,
+    };
+    await writeFile(fixQueuePath, JSON.stringify(queue, null, 2), 'utf-8');
+}
+export async function triageCommand(options = {}) {
+    printBanner();
+    const { input = '.ally/scan.json' } = options;
+    // Load scan results
+    const spinner = createSpinner('Loading scan results...');
+    spinner.start();
+    const reportPath = resolve(input);
+    if (!existsSync(reportPath)) {
+        spinner.stop();
+        suggestInit(reportPath);
+        return;
+    }
+    let report;
+    try {
+        const content = await readFile(reportPath, 'utf-8');
+        report = JSON.parse(content);
+        spinner.succeed(`Loaded scan results`);
+    }
+    catch (error) {
+        spinner.fail('Failed to load scan results');
+        printError(error instanceof Error ? error.message : String(error));
+        return;
+    }
+    // Group violations by type
+    const violationGroups = groupViolationsByType(report);
+    if (violationGroups.length === 0) {
+        printSuccess('No violations to triage! Your code is fully accessible.');
+        return;
+    }
+    console.log();
+    console.log(chalk.bold.cyan('Interactive Issue Triage'));
+    console.log(chalk.dim('Categorize each violation type to prioritize your accessibility work'));
+    console.log(chalk.dim('━'.repeat(60)));
+    console.log();
+    // Show summary of what we're triaging
+    const totalOccurrences = violationGroups.reduce((sum, g) => sum + g.count, 0);
+    printInfo(`Found ${violationGroups.length} unique violation types (${totalOccurrences} total occurrences)`);
+    console.log();
+    // Triage results
+    const result = {
+        fix: [],
+        ignore: [],
+        backlog: [],
+    };
+    const backlogItems = [];
+    // Process each violation group
+    for (let i = 0; i < violationGroups.length; i++) {
+        const group = violationGroups[i];
+        const progress = chalk.dim(`[${i + 1}/${violationGroups.length}]`);
+        console.log();
+        console.log(`${progress} ${formatViolationChoice(group)}`);
+        console.log(chalk.dim(`   ${group.description}`));
+        console.log(chalk.dim(`   Learn more: ${group.helpUrl}`));
+        console.log();
+        // Interactive prompt for each violation
+        const { action } = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'action',
+                message: 'What would you like to do with this violation?',
+                choices: [
+                    {
+                        name: chalk.green('Fix now') + chalk.dim(' - Add to fix queue'),
+                        value: 'fix',
+                    },
+                    {
+                        name: chalk.yellow('Backlog') + chalk.dim(' - Defer for later'),
+                        value: 'backlog',
+                    },
+                    {
+                        name: chalk.red('Ignore') + chalk.dim(' - Add to .allyignore'),
+                        value: 'ignore',
+                    },
+                    {
+                        name: chalk.blue('Skip') + chalk.dim(' - Decide later'),
+                        value: 'skip',
+                    },
+                ],
+                default: 'fix',
+            },
+        ]);
+        switch (action) {
+            case 'fix':
+                result.fix.push(group.id);
+                console.log(chalk.green(`   + Added to fix queue`));
+                break;
+            case 'backlog':
+                result.backlog.push(group.id);
+                backlogItems.push({
+                    id: group.id,
+                    description: group.help,
+                    impact: group.impact,
+                    count: group.count,
+                    addedAt: new Date().toISOString(),
+                });
+                console.log(chalk.yellow(`   -> Added to backlog`));
+                break;
+            case 'ignore':
+                result.ignore.push(group.id);
+                console.log(chalk.red(`   x Will be ignored`));
+                break;
+            case 'skip':
+                console.log(chalk.dim(`   - Skipped for now`));
+                break;
+        }
+    }
+    // Save results
+    console.log();
+    console.log(chalk.dim('━'.repeat(60)));
+    console.log();
+    const saveSpinner = createSpinner('Saving triage results...');
+    saveSpinner.start();
+    try {
+        // Save .allyignore
+        if (result.ignore.length > 0) {
+            await saveIgnorePatterns(result.ignore);
+        }
+        // Save backlog
+        if (backlogItems.length > 0) {
+            await saveBacklog(backlogItems);
+        }
+        // Save fix queue
+        if (result.fix.length > 0) {
+            await saveFixQueue(result.fix);
+        }
+        saveSpinner.succeed('Triage results saved');
+    }
+    catch (error) {
+        saveSpinner.fail('Failed to save triage results');
+        printError(error instanceof Error ? error.message : String(error));
+    }
+    // Print summary
+    console.log();
+    const summaryContent = `
+${chalk.bold('Triage Complete!')}
+
+${chalk.green('Fix now:')} ${result.fix.length} violation type${result.fix.length === 1 ? '' : 's'}
+${chalk.yellow('Backlog:')} ${result.backlog.length} violation type${result.backlog.length === 1 ? '' : 's'}
+${chalk.red('Ignored:')} ${result.ignore.length} violation type${result.ignore.length === 1 ? '' : 's'}
+`.trim();
+    console.log(boxen(summaryContent, {
+        padding: 1,
+        borderStyle: 'round',
+        borderColor: 'cyan',
+    }));
+    // Show next steps
+    console.log();
+    if (result.fix.length > 0) {
+        printSuccess(`Run ${chalk.cyan('ally fix')} to fix the ${result.fix.length} queued issue${result.fix.length === 1 ? '' : 's'}`);
+    }
+    if (result.ignore.length > 0) {
+        printInfo(`${result.ignore.length} pattern${result.ignore.length === 1 ? '' : 's'} added to ${chalk.cyan('.allyignore')}`);
+    }
+    if (result.backlog.length > 0) {
+        printInfo(`${result.backlog.length} item${result.backlog.length === 1 ? '' : 's'} saved to ${chalk.cyan('.ally/backlog.json')}`);
+    }
+}
+export default triageCommand;

package/dist/commands/watch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ally watch command - Continuous accessibility testing for development
+ *
+ * Watches a directory for HTML file changes and automatically scans
+ * them for accessibility violations.
+ */
+interface WatchCommandOptions {
+    port?: number;
+    debounce?: number;
+    clear?: boolean;
+    fixOnSave?: boolean;
+}
+/**
+ * Main watch command
+ */
+export declare function watchCommand(targetPath?: string, options?: WatchCommandOptions): Promise<void>;
+export default watchCommand;

package/dist/commands/watch.js

@@ -0,0 +1,302 @@
+/**
+ * ally watch command - Continuous accessibility testing for development
+ *
+ * Watches a directory for HTML file changes and automatically scans
+ * them for accessibility violations.
+ */
+import { resolve, relative, extname } from 'path';
+import { watch, existsSync, statSync } from 'fs';
+import { readdir, readFile, writeFile } from 'fs/promises';
+import chalk from 'chalk';
+import { AccessibilityScanner, calculateScore, } from '../utils/scanner.js';
+import { printBanner, printInfo, printError, } from '../utils/ui.js';
+import { generateSuggestedFix, getFixConfidence, } from '../utils/fix-patterns.js';
+const SUPPORTED_EXTENSIONS = ['.html', '.htm'];
+/**
+ * Auto-apply high-confidence fixes to a file
+ * Returns the number of fixes applied
+ */
+async function autoFixFile(filePath, violations) {
+    let content = await readFile(filePath, 'utf-8');
+    let fixesApplied = 0;
+    // Only apply high-confidence fixes (>= 0.9)
+    const highConfidenceViolations = violations.filter((v) => {
+        const confidence = getFixConfidence(v.id);
+        return confidence !== null && confidence >= 0.9;
+    });
+    for (const violation of highConfidenceViolations) {
+        for (const node of violation.nodes) {
+            if (node.html) {
+                const fixedHtml = generateSuggestedFix(violation, node.html);
+                if (fixedHtml && fixedHtml !== node.html) {
+                    // Apply the fix by replacing the HTML
+                    content = content.replace(node.html, fixedHtml);
+                    fixesApplied++;
+                }
+            }
+        }
+    }
+    if (fixesApplied > 0) {
+        await writeFile(filePath, content, 'utf-8');
+    }
+    return fixesApplied;
+}
+/**
+ * Format time for log output
+ */
+function formatTime() {
+    const now = new Date();
+    return chalk.dim(`[${now.getHours().toString().padStart(2, '0')}:${now
+        .getMinutes()
+        .toString()
+        .padStart(2, '0')}:${now.getSeconds().toString().padStart(2, '0')}]`);
+}
+/**
+ * Debounce function to prevent rapid-fire scans
+ */
+function debounce(fn, delay) {
+    let timeoutId = null;
+    return (filePath) => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => fn(filePath), delay);
+    };
+}
+/**
+ * Get severity icon
+ */
+function getSeverityIcon(severity) {
+    const icons = {
+        critical: chalk.red('!!!'),
+        serious: chalk.red('!!'),
+        moderate: chalk.yellow('!'),
+        minor: chalk.blue('i'),
+    };
+    return icons[severity];
+}
+/**
+ * Print compact violation for watch mode
+ */
+function printCompactViolation(violation) {
+    const icon = getSeverityIcon(violation.impact);
+    const count = violation.nodes.length;
+    const countText = count > 1 ? chalk.dim(` (${count} instances)`) : '';
+    console.log(`   - ${chalk.cyan(violation.id)}: ${violation.help}${countText}`);
+}
+/**
+ * Print file scan result in watch mode format
+ */
+function printWatchResult(file, result, basePath, fixesApplied) {
+    const relPath = relative(basePath, file);
+    const score = calculateScore([result]);
+    const violations = result.violations;
+    console.log();
+    console.log(`${formatTime()} ${chalk.bold(relPath)} changed`);
+    if (fixesApplied && fixesApplied > 0) {
+        const fixText = fixesApplied === 1 ? 'fix' : 'fixes';
+        console.log(chalk.green(`   ✓ Auto-applied ${fixesApplied} ${fixText}`));
+    }
+    if (violations.length === 0) {
+        console.log(chalk.green(`   No issues found (score: ${score})`));
+    }
+    else {
+        const issueText = violations.length === 1 ? 'issue' : 'issues';
+        const scoreColor = score >= 75 ? chalk.green : score >= 50 ? chalk.yellow : chalk.red;
+        console.log(chalk.yellow(`   ${violations.length} ${issueText} found`) +
+            ` (score: ${scoreColor(score.toString())})`);
+        // Group by severity for compact output
+        const bySeverity = {};
+        for (const v of violations) {
+            if (!bySeverity[v.impact]) {
+                bySeverity[v.impact] = [];
+            }
+            bySeverity[v.impact].push(v);
+        }
+        // Print critical and serious first
+        const order = ['critical', 'serious', 'moderate', 'minor'];
+        for (const severity of order) {
+            const sViolations = bySeverity[severity];
+            if (sViolations) {
+                for (const v of sViolations) {
+                    printCompactViolation(v);
+                }
+            }
+        }
+    }
+}
+/**
+ * Print watch summary on exit
+ */
+function printWatchSummary(stats, startTime) {
+    const duration = Math.round((Date.now() - startTime.getTime()) / 1000);
+    const minutes = Math.floor(duration / 60);
+    const seconds = duration % 60;
+    const durationStr = minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+    console.log();
+    console.log(chalk.bold.cyan('\nWatch Session Summary'));
+    console.log(chalk.dim('-'.repeat(40)));
+    console.log(`  Duration:        ${durationStr}`);
+    console.log(`  Files scanned:   ${stats.filesScanned}`);
+    console.log(`  Total violations: ${stats.totalViolations}`);
+    console.log(`  Clean scans:     ${stats.cleanScans}`);
+    if (stats.autoFixed > 0) {
+        console.log(chalk.green(`  Auto-fixed:      ${stats.autoFixed}`));
+    }
+    console.log();
+}
+/**
+ * Recursively watch a directory
+ */
+async function watchDirectory(dirPath, callback) {
+    const watchers = [];
+    const watchedDirs = new Set();
+    async function addWatcher(dir) {
+        if (watchedDirs.has(dir))
+            return;
+        watchedDirs.add(dir);
+        try {
+            const watcher = watch(dir, { recursive: false }, (eventType, filename) => {
+                if (filename && isHtmlFile(filename)) {
+                    const fullPath = resolve(dir, filename);
+                    callback(fullPath);
+                }
+            });
+            watchers.push(watcher);
+            // Watch subdirectories
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory() &&
+                    !entry.name.startsWith('.') &&
+                    entry.name !== 'node_modules' &&
+                    entry.name !== 'dist' &&
+                    entry.name !== 'build') {
+                    await addWatcher(resolve(dir, entry.name));
+                }
+            }
+        }
+        catch (error) {
+            // Directory might not exist or be inaccessible
+        }
+    }
+    // Use recursive watching on supported platforms
+    try {
+        const watcher = watch(dirPath, { recursive: true }, (eventType, filename) => {
+            if (filename && isHtmlFile(filename)) {
+                const fullPath = resolve(dirPath, filename);
+                if (existsSync(fullPath)) {
+                    callback(fullPath);
+                }
+            }
+        });
+        watchers.push(watcher);
+    }
+    catch (error) {
+        // Fall back to manual recursive watching
+        await addWatcher(dirPath);
+    }
+    return () => {
+        for (const watcher of watchers) {
+            watcher.close();
+        }
+    };
+}
+/**
+ * Check if file is an HTML file
+ */
+function isHtmlFile(filename) {
+    const ext = extname(filename).toLowerCase();
+    return SUPPORTED_EXTENSIONS.includes(ext);
+}
+/**
+ * Main watch command
+ */
+export async function watchCommand(targetPath = '.', options = {}) {
+    const { debounce: debounceMs = 500, clear = false, fixOnSave = false } = options;
+    const absolutePath = resolve(targetPath);
+    // Verify path exists
+    if (!existsSync(absolutePath)) {
+        printError(`Path does not exist: ${absolutePath}`);
+        process.exit(1);
+    }
+    const pathStat = statSync(absolutePath);
+    if (!pathStat.isDirectory()) {
+        printError(`Path is not a directory: ${absolutePath}`);
+        process.exit(1);
+    }
+    printBanner();
+    console.log(chalk.cyan.bold('Watching for accessibility changes...'));
+    console.log(chalk.dim(`   Directory: ${absolutePath}`));
+    console.log(chalk.dim(`   Debounce: ${debounceMs}ms`));
+    if (fixOnSave) {
+        console.log(chalk.green('   Auto-fix: ON (confidence ≥ 90%)'));
+    }
+    console.log(chalk.dim('   Press Ctrl+C to stop\n'));
+    // Initialize scanner
+    const scanner = new AccessibilityScanner();
+    await scanner.init();
+    // Track stats
+    const stats = {
+        filesScanned: 0,
+        totalViolations: 0,
+        cleanScans: 0,
+        autoFixed: 0,
+    };
+    const startTime = new Date();
+    // Scan a file
+    const scanFile = async (filePath) => {
+        if (!existsSync(filePath))
+            return;
+        try {
+            if (clear) {
+                console.clear();
+                console.log(chalk.cyan.bold('Watching for accessibility changes...'));
+                console.log(chalk.dim('   Press Ctrl+C to stop\n'));
+            }
+            const result = await scanner.scanHtmlFile(filePath);
+            stats.filesScanned++;
+            stats.totalViolations += result.violations.length;
+            if (result.violations.length === 0) {
+                stats.cleanScans++;
+            }
+            // Auto-fix if enabled
+            let fixesApplied = 0;
+            if (fixOnSave && result.violations.length > 0) {
+                fixesApplied = await autoFixFile(filePath, result.violations);
+                stats.autoFixed += fixesApplied;
+                // Rescan after fixes to show updated violations
+                if (fixesApplied > 0) {
+                    const updatedResult = await scanner.scanHtmlFile(filePath);
+                    printWatchResult(filePath, updatedResult, absolutePath, fixesApplied);
+                    return;
+                }
+            }
+            printWatchResult(filePath, result, absolutePath);
+        }
+        catch (error) {
+            console.log();
+            console.log(`${formatTime()} ${chalk.red('Error scanning')} ${relative(absolutePath, filePath)}`);
+            printError(error instanceof Error ? error.message : String(error));
+        }
+    };
+    // Debounced scan
+    const debouncedScan = debounce(scanFile, debounceMs);
+    // Set up file watching
+    const stopWatching = await watchDirectory(absolutePath, (filename) => {
+        debouncedScan(filename);
+    });
+    // Handle graceful shutdown
+    const cleanup = async () => {
+        stopWatching();
+        await scanner.close();
+        printWatchSummary(stats, startTime);
+        process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+    // Initial message about watching
+    printInfo('Waiting for file changes...');
+    // Keep the process running
+    await new Promise(() => { });
+}
+export default watchCommand;

package/dist/types/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Core types for Ally accessibility scanner
+ */
+export type Severity = 'critical' | 'serious' | 'moderate' | 'minor';
+export interface Violation {
+    id: string;
+    impact: Severity;
+    description: string;
+    help: string;
+    helpUrl: string;
+    nodes: ViolationNode[];
+    tags: string[];
+}
+export interface ViolationNode {
+    html: string;
+    target: string[];
+    failureSummary: string;
+}
+export interface ScanResult {
+    url: string;
+    file?: string;
+    timestamp: string;
+    violations: Violation[];
+    passes: number;
+    incomplete: number;
+}
+export interface AllyReport {
+    version: string;
+    scanDate: string;
+    totalFiles: number;
+    results: ScanResult[];
+    summary: ReportSummary;
+}
+export interface ReportSummary {
+    totalViolations: number;
+    bySeverity: Record<Severity, number>;
+    score: number;
+    topIssues: TopIssue[];
+}
+export interface TopIssue {
+    id: string;
+    count: number;
+    description: string;
+    severity: Severity;
+}
+export interface FixResult {
+    file: string;
+    line: number;
+    violation: string;
+    fixed: boolean;
+    skipped: boolean;
+    diff?: string;
+}
+export interface ScanOptions {
+    path: string;
+    include?: string[];
+    exclude?: string[];
+    standards?: ('wcag2a' | 'wcag2aa' | 'wcag2aaa' | 'wcag21a' | 'wcag21aa' | 'wcag22aa')[];
+    output?: string;
+}