ally-a11y 1.0.0

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * ally - Your codebase's accessibility ally
+ *
+ * Scans, explains, and fixes accessibility issues using GitHub Copilot CLI.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,528 @@
+#!/usr/bin/env node
+/**
+ * ally - Your codebase's accessibility ally
+ *
+ * Scans, explains, and fixes accessibility issues using GitHub Copilot CLI.
+ */
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import { handleErrorWithEnhancement } from './utils/enhanced-errors.js';
+// Read version from package.json to stay in sync
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+import { scanCommand } from './commands/scan.js';
+import { explainCommand } from './commands/explain.js';
+import { fixCommand } from './commands/fix.js';
+import { reportCommand } from './commands/report.js';
+import { initCommand } from './commands/init.js';
+import { statsCommand } from './commands/stats.js';
+import { badgeCommand } from './commands/badge.js';
+import { watchCommand } from './commands/watch.js';
+import { learnCommand } from './commands/learn.js';
+import { crawlCommand } from './commands/crawl.js';
+import { treeCommand } from './commands/tree.js';
+import { triageCommand } from './commands/triage.js';
+import { prCheckCommand } from './commands/pr-check.js';
+import { completionCommand } from './commands/completion.js';
+import { doctorCommand } from './commands/doctor.js';
+import { healthCommand } from './commands/health.js';
+import { scanStorybookCommand } from './commands/scan-storybook.js';
+import { auditPaletteCommand } from './commands/audit-palette.js';
+const program = new Command();
+program
+    .name('ally')
+    .description('Your codebase\'s accessibility ally. Scans, explains, and fixes a11y issues using GitHub Copilot CLI.')
+    .version(version);
+// ally scan [path]
+program
+    .command('scan [path]')
+    .description('Scan files for accessibility violations')
+    .option('-o, --output <dir>', 'Output directory for results', '.ally')
+    .option('-u, --url <url>', 'Scan a URL instead of files')
+    .option('-j, --json', 'Output raw JSON results')
+    .option('-f, --format <type>', 'Output format: json, sarif, junit, or csv')
+    .option('-v, --verbose', 'Show all violations including minor ones')
+    .option('-t, --threshold <number>', 'Exit with error if violations exceed threshold (for CI)')
+    .option('--ci', 'CI mode: minimal output, exit code based on violations')
+    .option('-F, --fail-on <severities>', 'Fail only on specified severities (comma-separated: critical,serious,moderate,minor)')
+    .option('-S, --simulate <type>', 'Simulate color blindness (deuteranopia, protanopia, tritanopia)', (value) => {
+    const valid = ['deuteranopia', 'protanopia', 'tritanopia'];
+    if (!valid.includes(value)) {
+        throw new Error(`Invalid simulation type: ${value}. Valid options: ${valid.join(', ')}`);
+    }
+    return value;
+})
+    .option('-s, --standard <level>', 'WCAG standard to test against (default: wcag22aa)', (value) => {
+    const valid = ['wcag2a', 'wcag2aa', 'wcag2aaa', 'wcag21a', 'wcag21aa', 'wcag21aaa', 'wcag22aa', 'section508', 'best-practice'];
+    if (!valid.includes(value)) {
+        throw new Error(`Invalid standard: ${value}. Valid options: ${valid.join(', ')}`);
+    }
+    return value;
+})
+    .option('-T, --timeout <ms>', 'Page load timeout in milliseconds (default: 30000)')
+    .option('-B, --browser <browser>', 'Browser engine: chromium, firefox, webkit (default: chromium)', (value) => {
+    const valid = ['chromium', 'firefox', 'webkit'];
+    if (!valid.includes(value)) {
+        throw new Error(`Invalid browser: ${value}. Valid options: ${valid.join(', ')}`);
+    }
+    return value;
+})
+    .option('--experimental-apca', 'Show APCA Lc values alongside WCAG 2.x contrast ratios (experimental)')
+    .option('--max-files <number>', 'Limit scan to first N files (useful for large projects)')
+    .option('--baseline', 'Set current scan as accessibility baseline (for regression detection)')
+    .option('--compare-baseline', 'Compare against saved baseline and show improvements/regressions')
+    .option('--fail-on-regression', 'Exit with error if accessibility regressions detected (with --compare-baseline)')
+    .option('--no-cache', 'Do not use cache, rescan all files')
+    .action(async (path, options) => {
+    try {
+        // Parse timeout if provided
+        if (options.timeout !== undefined) {
+            const timeout = parseInt(options.timeout, 10);
+            if (isNaN(timeout) || timeout < 1000) {
+                console.error('Error: --timeout must be at least 1000 (1 second)');
+                process.exit(1);
+            }
+            options.timeout = timeout;
+        }
+        // Parse threshold if provided
+        if (options.threshold !== undefined) {
+            const threshold = parseInt(options.threshold, 10);
+            if (isNaN(threshold) || threshold < 0) {
+                console.error('Error: --threshold must be a non-negative number');
+                process.exit(1);
+            }
+            options.threshold = threshold;
+        }
+        // Parse max-files if provided
+        if (options.maxFiles !== undefined) {
+            const maxFiles = parseInt(options.maxFiles, 10);
+            if (isNaN(maxFiles) || maxFiles < 1) {
+                console.error('Error: --max-files must be at least 1');
+                process.exit(1);
+            }
+            options.maxFiles = maxFiles;
+        }
+        const report = await scanCommand(path, options);
+        // CI threshold check
+        if (options.threshold !== undefined && report) {
+            // If --fail-on is set, filter violations before checking threshold
+            let violationCount;
+            if (options.failOn) {
+                const severities = options.failOn.split(',').map((s) => s.trim().toLowerCase());
+                const validSeverities = ['critical', 'serious', 'moderate', 'minor'];
+                const invalidSeverities = severities.filter((s) => !validSeverities.includes(s));
+                if (invalidSeverities.length > 0) {
+                    console.error(`Error: Invalid severity values: ${invalidSeverities.join(', ')}`);
+                    console.error(`Valid values are: ${validSeverities.join(', ')}`);
+                    process.exit(1);
+                }
+                // Count violations matching specified severities
+                violationCount = report.results.reduce((count, result) => {
+                    return count + result.violations.filter(v => severities.includes(v.impact)).length;
+                }, 0);
+            }
+            else {
+                violationCount = report.summary.totalViolations;
+            }
+            if (violationCount > options.threshold) {
+                const severityNote = options.failOn ? ` (filtered by: ${options.failOn})` : '';
+                console.error(`\nCI FAILED: ${violationCount} violations${severityNote} exceed threshold of ${options.threshold}`);
+                process.exit(1);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            handleErrorWithEnhancement(error);
+        }
+        else {
+            console.error('Scan failed:', error);
+        }
+        process.exit(1);
+    }
+});
+// ally explain
+program
+    .command('explain')
+    .description('Get plain-language explanations of violations using Copilot')
+    .option('-i, --input <file>', 'Path to scan results', '.ally/scan.json')
+    .option('-s, --severity <level>', 'Filter by severity (critical, serious, moderate, minor)')
+    .option('-l, --limit <number>', 'Maximum number of issues to explain', '10')
+    .option('--ai', 'Use GitHub Copilot CLI for AI-powered explanations')
+    .action(async (options) => {
+    try {
+        const limit = parseInt(options.limit, 10);
+        if (isNaN(limit) || limit < 1) {
+            console.error('Error: --limit must be a positive number');
+            process.exit(1);
+        }
+        await explainCommand({
+            ...options,
+            limit,
+        });
+    }
+    catch (error) {
+        console.error('Explain failed:', error);
+        process.exit(1);
+    }
+});
+// ally fix
+program
+    .command('fix')
+    .description('Fix accessibility issues using Copilot CLI agentic mode')
+    .option('-i, --input <file>', 'Path to scan results', '.ally/scan.json')
+    .option('-s, --severity <level>', 'Filter by severity (critical, serious, moderate, minor)')
+    .option('-a, --auto', 'Automatically apply all fixes without prompting')
+    .option('-d, --dry-run', 'Show what would be fixed without making changes')
+    .option('-y, --yes', 'Skip interactive review, apply all suggested fixes')
+    .action(async (options) => {
+    try {
+        await fixCommand(options);
+    }
+    catch (error) {
+        console.error('Fix failed:', error);
+        process.exit(1);
+    }
+});
+// ally report
+program
+    .command('report')
+    .description('Generate accessibility report (ACCESSIBILITY.md)')
+    .option('-i, --input <file>', 'Path to scan results', '.ally/scan.json')
+    .option('-o, --output <file>', 'Output file path', 'ACCESSIBILITY.md')
+    .option('-f, --format <type>', 'Report format (markdown, json, html)', 'markdown')
+    .action(async (options) => {
+    try {
+        await reportCommand(options);
+    }
+    catch (error) {
+        console.error('Report generation failed:', error);
+        process.exit(1);
+    }
+});
+// ally init
+program
+    .command('init')
+    .description('Initialize ally in your project')
+    .option('-f, --force', 'Overwrite existing configuration')
+    .option('-H, --hooks', 'Set up pre-commit hooks for accessibility checks')
+    .action(async (options) => {
+    try {
+        await initCommand(options);
+    }
+    catch (error) {
+        console.error('Initialization failed:', error);
+        process.exit(1);
+    }
+});
+// ally stats
+program
+    .command('stats')
+    .description('Show accessibility progress dashboard')
+    .action(async () => {
+    try {
+        await statsCommand();
+    }
+    catch (error) {
+        console.error('Stats failed:', error);
+        process.exit(1);
+    }
+});
+// ally history
+program
+    .command('history')
+    .description('View scan history and progress over time')
+    .option('-l, --limit <number>', 'Number of recent scans to show', '10')
+    .option('-b, --branch <name>', 'Filter by git branch')
+    .option('-v, --verbose', 'Show detailed information')
+    .action(async (options) => {
+    try {
+        const { historyCommand } = await import('./commands/history.js');
+        const limit = parseInt(options.limit, 10);
+        await historyCommand({ limit, branch: options.branch, verbose: options.verbose });
+    }
+    catch (error) {
+        console.error('History failed:', error);
+        process.exit(1);
+    }
+});
+// ally badge
+program
+    .command('badge')
+    .description('Generate accessibility score badge for README')
+    .option('-i, --input <file>', 'Path to scan results', '.ally/scan.json')
+    .option('-f, --format <type>', 'Output format (url, markdown, svg)', 'url')
+    .option('-o, --output <file>', 'Save badge to file (primarily for SVG)')
+    .action(async (options) => {
+    try {
+        await badgeCommand(options);
+    }
+    catch (error) {
+        console.error('Badge generation failed:', error);
+        process.exit(1);
+    }
+});
+// ally watch
+program
+    .command('watch [path]')
+    .description('Watch for file changes and run accessibility scans continuously')
+    .option('-d, --debounce <ms>', 'Debounce time in milliseconds', '500')
+    .option('--clear', 'Clear console between scans')
+    .option('--fix-on-save', 'Automatically apply high-confidence fixes (≥90%) when files change')
+    .action(async (path, options) => {
+    try {
+        const debounce = parseInt(options.debounce, 10);
+        if (isNaN(debounce) || debounce < 0) {
+            console.error('Error: --debounce must be a non-negative number');
+            process.exit(1);
+        }
+        await watchCommand(path, {
+            ...options,
+            debounce,
+        });
+    }
+    catch (error) {
+        console.error('Watch failed:', error);
+        process.exit(1);
+    }
+});
+// ally learn
+program
+    .command('learn [violation-id]')
+    .description('Learn about WCAG accessibility criteria in depth')
+    .option('-l, --list', 'List all known violation types')
+    .action(async (violationId, options) => {
+    try {
+        await learnCommand(violationId, options);
+    }
+    catch (error) {
+        console.error('Learn failed:', error);
+        process.exit(1);
+    }
+});
+// ally crawl
+program
+    .command('crawl <url>')
+    .description('Crawl entire website by following links and scan each page')
+    .option('-d, --depth <number>', 'Maximum crawl depth', '2')
+    .option('-l, --limit <number>', 'Maximum pages to scan', '10')
+    .option('--same-origin', 'Only follow links to same origin (default: true)', true)
+    .option('--no-same-origin', 'Follow links to any origin')
+    .option('-o, --output <dir>', 'Output directory for results', '.ally')
+    .action(async (url, options) => {
+    try {
+        // Parse numeric options
+        const depth = parseInt(options.depth, 10);
+        if (isNaN(depth) || depth < 0) {
+            console.error('Error: --depth must be a non-negative number');
+            process.exit(1);
+        }
+        const limit = parseInt(options.limit, 10);
+        if (isNaN(limit) || limit < 1) {
+            console.error('Error: --limit must be a positive number');
+            process.exit(1);
+        }
+        await crawlCommand(url, {
+            depth,
+            limit,
+            sameOrigin: options.sameOrigin,
+            output: options.output,
+        });
+    }
+    catch (error) {
+        console.error('Crawl failed:', error);
+        process.exit(1);
+    }
+});
+// ally tree
+program
+    .command('tree <url>')
+    .description('Display accessibility tree for a URL')
+    .option('-d, --depth <number>', 'Maximum tree depth to display', '5')
+    .option('-r, --role <role>', 'Filter to specific ARIA role')
+    .option('-j, --json', 'Output as JSON')
+    .option('-s, --speak', 'Simulate screen reader announcement')
+    .option('--no-audio', 'Print announcement but skip TTS playback (use with --speak)')
+    .action(async (url, options) => {
+    try {
+        const depth = parseInt(options.depth, 10);
+        if (isNaN(depth) || depth < 1) {
+            console.error('Error: --depth must be a positive number');
+            process.exit(1);
+        }
+        await treeCommand(url, {
+            depth,
+            role: options.role,
+            json: options.json,
+            speak: options.speak,
+            noAudio: !options.audio, // Commander converts --no-audio to audio: false
+        });
+    }
+    catch (error) {
+        console.error('Tree failed:', error);
+        process.exit(1);
+    }
+});
+// ally triage
+program
+    .command('triage')
+    .description('Interactively categorize and prioritize accessibility issues')
+    .option('-i, --input <file>', 'Path to scan results', '.ally/scan.json')
+    .action(async (options) => {
+    try {
+        await triageCommand(options);
+    }
+    catch (error) {
+        console.error('Triage failed:', error);
+        process.exit(1);
+    }
+});
+// ally pr-check
+program
+    .command('pr-check')
+    .description('Post accessibility results to GitHub PR')
+    .option('-i, --input <file>', 'Path to scan results', '.ally/scan.json')
+    .option('-p, --pr <number>', 'PR number (auto-detected in GitHub Actions)')
+    .option('--no-comment', 'Skip posting PR comment')
+    .option('-F, --fail-on <severities>', 'Fail on specified severities (comma-separated)')
+    .action(async (options) => {
+    try {
+        const prNumber = options.pr ? parseInt(options.pr, 10) : undefined;
+        await prCheckCommand({
+            ...options,
+            pr: prNumber,
+        });
+    }
+    catch (error) {
+        console.error('PR check failed:', error);
+        process.exit(1);
+    }
+});
+// ally completion
+program
+    .command('completion [shell]')
+    .description('Generate shell completion script (bash, zsh, fish)')
+    .action(async (shell) => {
+    try {
+        await completionCommand(shell);
+    }
+    catch (error) {
+        console.error('Completion failed:', error);
+        process.exit(1);
+    }
+});
+// ally doctor
+program
+    .command('doctor')
+    .description('Diagnose installation and configuration issues')
+    .action(async () => {
+    try {
+        await doctorCommand();
+    }
+    catch (error) {
+        console.error('Doctor failed:', error);
+        process.exit(1);
+    }
+});
+// ally health
+program
+    .command('health')
+    .description('Quick accessibility health check (like npm audit)')
+    .option('-p, --path <path>', 'Path to scan', '.')
+    .option('-s, --standard <level>', 'WCAG standard to test against (default: wcag22aa)', (value) => {
+    const valid = ['wcag2a', 'wcag2aa', 'wcag2aaa', 'wcag21a', 'wcag21aa', 'wcag21aaa', 'wcag22aa', 'section508', 'best-practice'];
+    if (!valid.includes(value)) {
+        throw new Error(`Invalid standard: ${value}. Valid options: ${valid.join(', ')}`);
+    }
+    return value;
+})
+    .option('-i, --input <file>', 'Use existing scan results instead of scanning')
+    .action(async (options) => {
+    try {
+        await healthCommand(options);
+    }
+    catch (error) {
+        console.error('Health check failed:', error);
+        process.exit(1);
+    }
+});
+// ally scan-storybook
+program
+    .command('scan-storybook')
+    .description('Scan Storybook stories for accessibility issues')
+    .option('-u, --url <url>', 'Storybook URL (default: http://localhost:6006)', 'http://localhost:6006')
+    .option('-T, --timeout <ms>', 'Page load timeout in milliseconds (default: 10000)', '10000')
+    .option('-f, --filter <pattern>', 'Filter stories by name pattern')
+    .option('-F, --format <format>', 'Output format (default, json, csv)', 'default')
+    .option('-o, --output <dir>', 'Output directory for results', '.ally')
+    .option('-s, --standard <level>', 'WCAG standard to test against (default: wcag22aa)', (value) => {
+    const valid = ['wcag2a', 'wcag2aa', 'wcag2aaa', 'wcag21a', 'wcag21aa', 'wcag21aaa', 'wcag22aa', 'section508', 'best-practice'];
+    if (!valid.includes(value)) {
+        throw new Error(`Invalid standard: ${value}. Valid options: ${valid.join(', ')}`);
+    }
+    return value;
+})
+    .action(async (options) => {
+    try {
+        // Parse timeout if provided
+        const timeout = parseInt(options.timeout, 10);
+        if (isNaN(timeout) || timeout < 1000) {
+            console.error('Error: --timeout must be at least 1000 (1 second)');
+            process.exit(1);
+        }
+        // Validate format
+        const validFormats = ['default', 'json', 'csv'];
+        if (!validFormats.includes(options.format)) {
+            console.error(`Error: --format must be one of: ${validFormats.join(', ')}`);
+            process.exit(1);
+        }
+        await scanStorybookCommand({
+            url: options.url,
+            timeout,
+            filter: options.filter,
+            format: options.format,
+            output: options.output,
+            standard: options.standard,
+        });
+    }
+    catch (error) {
+        console.error('Storybook scan failed:', error);
+        process.exit(1);
+    }
+});
+// ally audit-palette
+program
+    .command('audit-palette <file>')
+    .description('Audit a design system color palette for contrast issues')
+    .option('-f, --format <format>', 'Output format (default, json, csv)', 'default')
+    .option('-l, --level <level>', 'Minimum WCAG level to pass (aa, aaa)', 'aa')
+    .option('--large-text', 'Use large text thresholds (3:1 for AA)')
+    .option('--apca', 'Include APCA contrast values in output')
+    .action(async (file, options) => {
+    try {
+        // Validate level
+        const validLevels = ['aa', 'aaa'];
+        if (!validLevels.includes(options.level)) {
+            console.error(`Error: --level must be one of: ${validLevels.join(', ')}`);
+            process.exit(1);
+        }
+        // Validate format
+        const validFormats = ['default', 'json', 'csv'];
+        if (!validFormats.includes(options.format)) {
+            console.error(`Error: --format must be one of: ${validFormats.join(', ')}`);
+            process.exit(1);
+        }
+        await auditPaletteCommand(file, {
+            format: options.format,
+            level: options.level,
+            largeText: options.largeText,
+            apca: options.apca,
+        });
+    }
+    catch (error) {
+        console.error('Palette audit failed:', error);
+        process.exit(1);
+    }
+});
+// Parse and run
+program.parse();

package/dist/commands/audit-palette.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ally audit-palette command - Audits a design system color palette for contrast issues
+ *
+ * Supports:
+ * - Tailwind config files (tailwind.config.js, tailwind.config.ts)
+ * - CSS variable files (*.css)
+ * - JSON palette files (*.json)
+ */
+type OutputFormat = 'default' | 'json' | 'csv';
+type WcagLevel = 'aa' | 'aaa';
+interface AuditPaletteOptions {
+    format?: OutputFormat;
+    level?: WcagLevel;
+    largeText?: boolean;
+    apca?: boolean;
+}
+export declare function auditPaletteCommand(filePath: string, options?: AuditPaletteOptions): Promise<void>;
+export default auditPaletteCommand;