ally-a11y 1.0.0

package/dist/commands/completion.js

@@ -0,0 +1,185 @@
+/**
+ * ally completion command - Generate shell completion scripts
+ */
+// All commands and their options for completion
+const COMMANDS = {
+    scan: {
+        description: 'Scan files for accessibility violations',
+        options: ['-o', '--output', '-u', '--url', '-j', '--json', '-f', '--format', '-v', '--verbose', '-t', '--threshold', '--ci', '-F', '--fail-on', '-S', '--simulate', '-s', '--standard', '-T', '--timeout'],
+    },
+    explain: {
+        description: 'Get plain-language explanations of violations',
+        options: ['-i', '--input', '-s', '--severity', '-l', '--limit'],
+    },
+    fix: {
+        description: 'Fix accessibility issues using Copilot',
+        options: ['-i', '--input', '-s', '--severity', '-a', '--auto', '-d', '--dry-run'],
+    },
+    report: {
+        description: 'Generate accessibility report',
+        options: ['-i', '--input', '-o', '--output', '-f', '--format'],
+    },
+    init: {
+        description: 'Initialize ally in your project',
+        options: ['-f', '--force', '-H', '--hooks'],
+    },
+    stats: {
+        description: 'Show accessibility progress dashboard',
+        options: [],
+    },
+    badge: {
+        description: 'Generate accessibility score badge',
+        options: ['-i', '--input', '-f', '--format', '-o', '--output'],
+    },
+    watch: {
+        description: 'Watch for file changes and scan continuously',
+        options: ['-d', '--debounce', '--clear'],
+    },
+    learn: {
+        description: 'Learn about WCAG accessibility criteria',
+        options: ['-l', '--list'],
+    },
+    crawl: {
+        description: 'Crawl website and scan each page',
+        options: ['-d', '--depth', '-l', '--limit', '--same-origin', '--no-same-origin', '-o', '--output'],
+    },
+    tree: {
+        description: 'Display accessibility tree for a URL',
+        options: ['-d', '--depth', '-r', '--role', '-j', '--json'],
+    },
+    triage: {
+        description: 'Interactively categorize accessibility issues',
+        options: ['-i', '--input'],
+    },
+    'pr-check': {
+        description: 'Post accessibility results to GitHub PR',
+        options: ['-i', '--input', '-p', '--pr', '--no-comment', '-F', '--fail-on'],
+    },
+    completion: {
+        description: 'Generate shell completion script',
+        options: [],
+    },
+};
+const commandNames = Object.keys(COMMANDS);
+function generateBashCompletion() {
+    return `# Bash completion for ally
+# Add to ~/.bashrc or ~/.bash_profile:
+#   eval "$(ally completion bash)"
+
+_ally_completions() {
+    local cur prev commands
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+    commands="${commandNames.join(' ')}"
+
+    # Complete commands
+    if [[ \${COMP_CWORD} -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "\${commands}" -- "\${cur}") )
+        return 0
+    fi
+
+    # Complete options based on command
+    case "\${COMP_WORDS[1]}" in
+${Object.entries(COMMANDS).map(([cmd, info]) => `        ${cmd})
+            COMPREPLY=( $(compgen -W "${info.options.join(' ')}" -- "\${cur}") )
+            ;;`).join('\n')}
+    esac
+
+    return 0
+}
+
+complete -F _ally_completions ally
+`;
+}
+function generateZshCompletion() {
+    return `#compdef ally
+# Zsh completion for ally
+# Add to ~/.zshrc:
+#   eval "$(ally completion zsh)"
+
+_ally() {
+    local -a commands
+    commands=(
+${Object.entries(COMMANDS).map(([cmd, info]) => `        '${cmd}:${info.description}'`).join('\n')}
+    )
+
+    _arguments -C \\
+        '1:command:->command' \\
+        '*::options:->options'
+
+    case $state in
+        command)
+            _describe 'command' commands
+            ;;
+        options)
+            case $words[1] in
+${Object.entries(COMMANDS).map(([cmd, info]) => `                ${cmd})
+                    _arguments \\
+${info.options.filter(o => o.startsWith('--')).map(opt => `                        '${opt}[${opt.replace('--', '')}]'`).join(' \\\n') || "                        '*:'"}
+                    ;;`).join('\n')}
+            esac
+            ;;
+    esac
+}
+
+compdef _ally ally
+`;
+}
+function generateFishCompletion() {
+    return `# Fish completion for ally
+# Add to ~/.config/fish/completions/ally.fish:
+#   ally completion fish > ~/.config/fish/completions/ally.fish
+
+# Disable file completions for ally
+complete -c ally -f
+
+# Commands
+${Object.entries(COMMANDS).map(([cmd, info]) => `complete -c ally -n "__fish_use_subcommand" -a "${cmd}" -d "${info.description}"`).join('\n')}
+
+# Options for each command
+${Object.entries(COMMANDS).map(([cmd, info]) => info.options.filter(o => o.startsWith('--')).map(opt => `complete -c ally -n "__fish_seen_subcommand_from ${cmd}" -l "${opt.replace('--', '')}" -d "${opt.replace('--', '')}"`).join('\n')).filter(Boolean).join('\n')}
+`;
+}
+export async function completionCommand(shell) {
+    const validShells = ['bash', 'zsh', 'fish'];
+    if (!shell) {
+        console.log(`Usage: ally completion <shell>
+
+Generate shell completion scripts.
+
+Supported shells:
+  bash    Bash completion script
+  zsh     Zsh completion script
+  fish    Fish completion script
+
+Examples:
+  # Bash - add to ~/.bashrc
+  eval "$(ally completion bash)"
+
+  # Zsh - add to ~/.zshrc
+  eval "$(ally completion zsh)"
+
+  # Fish - save to completions directory
+  ally completion fish > ~/.config/fish/completions/ally.fish
+`);
+        return;
+    }
+    if (!validShells.includes(shell)) {
+        console.error(`Unknown shell: ${shell}`);
+        console.error(`Supported shells: ${validShells.join(', ')}`);
+        process.exit(1);
+    }
+    switch (shell) {
+        case 'bash':
+            console.log(generateBashCompletion());
+            break;
+        case 'zsh':
+            console.log(generateZshCompletion());
+            break;
+        case 'fish':
+            console.log(generateFishCompletion());
+            break;
+    }
+}

package/dist/commands/crawl.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ally crawl command - Crawls entire websites by following links
+ */
+import type { AllyReport } from '../types/index.js';
+interface CrawlCommandOptions {
+    depth?: number;
+    limit?: number;
+    sameOrigin?: boolean;
+    output?: string;
+}
+export declare function crawlCommand(startUrl: string, options?: CrawlCommandOptions): Promise<AllyReport | null>;
+export default crawlCommand;

package/dist/commands/crawl.js

@@ -0,0 +1,249 @@
+/**
+ * ally crawl command - Crawls entire websites by following links
+ */
+import { resolve } from 'path';
+import { mkdir, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { AccessibilityScanner, createReport, calculateScore } from '../utils/scanner.js';
+import { printBanner, createSpinner, printSummary, printSuccess, printError, printInfo, printWarning, } from '../utils/ui.js';
+import { withRetry } from '../utils/retry.js';
+import chalk from 'chalk';
+/**
+ * Normalize URL by removing hash and trailing slash
+ */
+function normalizeUrl(url) {
+    try {
+        const parsed = new URL(url);
+        // Remove hash
+        parsed.hash = '';
+        // Remove trailing slash (except for root)
+        let normalized = parsed.toString();
+        if (normalized.endsWith('/') && parsed.pathname !== '/') {
+            normalized = normalized.slice(0, -1);
+        }
+        return normalized;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Check if a URL is same-origin as the base URL
+ */
+function isSameOrigin(baseUrl, targetUrl) {
+    try {
+        const base = new URL(baseUrl);
+        const target = new URL(targetUrl);
+        return base.origin === target.origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a URL should be crawled (is a valid page URL)
+ */
+function isValidPageUrl(url) {
+    try {
+        const parsed = new URL(url);
+        // Only HTTP/HTTPS
+        if (!['http:', 'https:'].includes(parsed.protocol)) {
+            return false;
+        }
+        // Block localhost and private IPs for security (except for explicit localhost scans)
+        const hostname = parsed.hostname.toLowerCase();
+        if (hostname !== 'localhost' && hostname !== '127.0.0.1') {
+            // Block private IP ranges (10.x, 172.16-31.x, 192.168.x)
+            const ipMatch = hostname.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+            if (ipMatch) {
+                const [, a, b] = ipMatch.map(Number);
+                if (a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168)) {
+                    return false;
+                }
+            }
+        }
+        // Skip common non-page extensions
+        const skipExtensions = [
+            '.pdf', '.zip', '.tar', '.gz', '.rar',
+            '.jpg', '.jpeg', '.png', '.gif', '.svg', '.ico', '.webp',
+            '.mp3', '.mp4', '.avi', '.mov', '.wmv',
+            '.css', '.js', '.json', '.xml',
+            '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+        ];
+        const pathname = parsed.pathname.toLowerCase();
+        for (const ext of skipExtensions) {
+            if (pathname.endsWith(ext)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Format a page result line for console output
+ */
+function formatPageResult(progress) {
+    const { current, total, url, violations, score } = progress;
+    // Truncate URL if too long
+    const maxUrlLength = 50;
+    let displayUrl = url;
+    if (displayUrl.length > maxUrlLength) {
+        displayUrl = displayUrl.slice(0, maxUrlLength - 3) + '...';
+    }
+    // Color based on score
+    let scoreColor = chalk.green;
+    if (score < 50)
+        scoreColor = chalk.red;
+    else if (score < 75)
+        scoreColor = chalk.yellow;
+    const violationText = violations === 0
+        ? chalk.green('0 violations')
+        : violations === 1
+            ? chalk.yellow('1 violation')
+            : chalk.yellow(`${violations} violations`);
+    return `[${current}/${total}] ${displayUrl} - ${violationText} (score: ${scoreColor(score.toString())})`;
+}
+export async function crawlCommand(startUrl, options = {}) {
+    printBanner();
+    const { depth = 2, limit = 10, sameOrigin = true, output = '.ally', } = options;
+    // Validate URL
+    let normalizedStartUrl;
+    try {
+        normalizedStartUrl = normalizeUrl(startUrl);
+        new URL(normalizedStartUrl);
+    }
+    catch {
+        printError(`Invalid URL: ${startUrl}`);
+        return null;
+    }
+    console.log(chalk.cyan(`Crawling ${normalizedStartUrl} (depth: ${depth}, limit: ${limit})`));
+    console.log();
+    const scanner = new AccessibilityScanner();
+    const visited = new Set();
+    const toVisit = [{ url: normalizedStartUrl, depth: 0 }];
+    const results = [];
+    try {
+        await scanner.init();
+        while (toVisit.length > 0 && results.length < limit) {
+            const next = toVisit.shift();
+            if (!next)
+                break;
+            const { url, depth: currentDepth } = next;
+            const normalized = normalizeUrl(url);
+            // Skip if already visited
+            if (visited.has(normalized)) {
+                continue;
+            }
+            visited.add(normalized);
+            // Skip if not same origin and sameOrigin is enabled
+            if (sameOrigin && !isSameOrigin(normalizedStartUrl, normalized)) {
+                continue;
+            }
+            // Skip if not a valid page URL
+            if (!isValidPageUrl(normalized)) {
+                continue;
+            }
+            const pageNum = results.length + 1;
+            const spinner = createSpinner(`[${pageNum}/${limit}] Scanning ${normalized}...`);
+            spinner.start();
+            try {
+                // Scan the page for accessibility issues with retry for transient errors
+                const result = await withRetry(() => scanner.scanUrl(normalized), {
+                    maxRetries: 3,
+                    baseDelayMs: 1000,
+                    onRetry: (attempt, error, delayMs) => {
+                        spinner.stop();
+                        printWarning(`Retry ${attempt}/3 for ${normalized} after ${delayMs / 1000}s (${error.message})`);
+                        spinner.start();
+                    },
+                });
+                results.push(result);
+                // Calculate score for this single result
+                const pageScore = calculateScore([result]);
+                spinner.stop();
+                console.log(formatPageResult({
+                    current: pageNum,
+                    total: limit,
+                    url: normalized,
+                    violations: result.violations.length,
+                    score: pageScore,
+                }));
+                // Extract links if we haven't reached max depth
+                if (currentDepth < depth) {
+                    const links = await scanner.extractLinks(normalized);
+                    // Add new links to the queue
+                    for (const link of links) {
+                        const normalizedLink = normalizeUrl(link);
+                        if (!visited.has(normalizedLink) && isValidPageUrl(normalizedLink)) {
+                            if (!sameOrigin || isSameOrigin(normalizedStartUrl, normalizedLink)) {
+                                // Check if already in queue
+                                const alreadyQueued = toVisit.some(item => normalizeUrl(item.url) === normalizedLink);
+                                if (!alreadyQueued) {
+                                    toVisit.push({ url: normalizedLink, depth: currentDepth + 1 });
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                spinner.fail(`Failed to scan ${normalized}`);
+                printError(error instanceof Error ? error.message : String(error));
+            }
+        }
+        console.log();
+        if (results.length === 0) {
+            printError('No pages were successfully scanned');
+            return null;
+        }
+        // Create combined report
+        const report = createReport(results);
+        // Print crawl summary
+        console.log(chalk.bold(`Crawl complete: ${results.length} page${results.length === 1 ? '' : 's'} scanned`));
+        // Calculate totals
+        const totalViolations = results.reduce((sum, r) => sum + r.violations.length, 0);
+        const avgScore = Math.round(results.reduce((sum, r) => sum + calculateScore([r]), 0) / results.length);
+        console.log(chalk.dim(`Total violations: ${totalViolations}`));
+        console.log(chalk.dim(`Average score: ${avgScore}`));
+        console.log();
+        // Print full summary
+        printSummary(report.summary);
+        // Save report
+        await saveReport(report, output, normalizedStartUrl);
+        return report;
+    }
+    catch (error) {
+        printError(`Crawl failed: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+    finally {
+        await scanner.close();
+    }
+}
+async function saveReport(report, outputDir, startUrl) {
+    try {
+        // Ensure output directory exists
+        if (!existsSync(outputDir)) {
+            await mkdir(outputDir, { recursive: true });
+        }
+        // Generate filename from URL
+        const urlObj = new URL(startUrl);
+        const safeHost = urlObj.hostname.replace(/[^a-z0-9]/gi, '-');
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+        // Save crawl report
+        const reportPath = resolve(outputDir, `crawl-${safeHost}-${timestamp}.json`);
+        await writeFile(reportPath, JSON.stringify(report, null, 2));
+        printSuccess(`Crawl report saved to ${reportPath}`);
+        // Also save as the default scan.json for compatibility with other commands
+        const defaultPath = resolve(outputDir, 'scan.json');
+        await writeFile(defaultPath, JSON.stringify(report, null, 2));
+        printInfo(`Also saved to ${defaultPath} for use with other ally commands`);
+    }
+    catch (error) {
+        printError(`Failed to save report: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export default crawlCommand;

package/dist/commands/doctor.d.ts

@@ -0,0 +1,5 @@
+/**
+ * ally doctor command - Diagnoses installation and configuration issues
+ */
+export declare function doctorCommand(): Promise<void>;
+export default doctorCommand;

package/dist/commands/doctor.js

@@ -0,0 +1,233 @@
+/**
+ * ally doctor command - Diagnoses installation and configuration issues
+ */
+import { existsSync, readFileSync } from 'fs';
+import { resolve, join, dirname } from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import chalk from 'chalk';
+import { printBanner } from '../utils/ui.js';
+// ESM equivalent of __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Get the installed Node.js version
+ */
+function getNodeVersion() {
+    return process.version.replace('v', '');
+}
+/**
+ * Parse a semver string and return major version number
+ */
+function parseMajorVersion(version) {
+    const match = version.match(/^(\d+)/);
+    return match ? parseInt(match[1], 10) : 0;
+}
+/**
+ * Check if a command exists
+ */
+function commandExists(command) {
+    try {
+        execSync(`which ${command}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get ally version from package.json
+ */
+function getAllyVersion() {
+    try {
+        // Use createRequire to read package.json (same approach as cli.ts)
+        const require = createRequire(import.meta.url);
+        const { version } = require('../../package.json');
+        return version || 'unknown';
+    }
+    catch {
+        // Fallback: try to get from local package.json
+        try {
+            const localPkgPath = resolve(process.cwd(), 'package.json');
+            if (existsSync(localPkgPath)) {
+                const pkg = JSON.parse(readFileSync(localPkgPath, 'utf-8'));
+                if (pkg.name === 'ally-a11y') {
+                    return pkg.version || 'unknown';
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return 'unknown';
+}
+/**
+ * Check if Puppeteer browser is installed
+ */
+async function checkPuppeteerBrowser() {
+    try {
+        // Try to import puppeteer and check for browser
+        const puppeteer = await import('puppeteer');
+        const browser = await puppeteer.default.launch({
+            headless: true,
+            args: ['--no-sandbox', '--disable-setuid-sandbox'],
+        });
+        await browser.close();
+        return { status: 'pass', message: 'Puppeteer browser installed' };
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        if (errorMsg.includes('Could not find Chrome') || errorMsg.includes('Could not find Chromium')) {
+            return { status: 'fail', message: 'Puppeteer browser not installed. Run: npx puppeteer browsers install chrome' };
+        }
+        return { status: 'fail', message: `Puppeteer browser check failed: ${errorMsg}` };
+    }
+}
+/**
+ * Check if MCP server is configured
+ */
+function checkMcpServer() {
+    const cwd = process.cwd();
+    // Check for mcp-server in node_modules (installed package)
+    const nodeModulesPath = join(cwd, 'node_modules', 'ally-a11y', 'mcp-server', 'dist', 'index.js');
+    if (existsSync(nodeModulesPath)) {
+        return { status: 'pass', message: 'MCP server configured (via node_modules)' };
+    }
+    // Check for local mcp-server (development)
+    const localPath = join(cwd, 'mcp-server', 'dist', 'index.js');
+    if (existsSync(localPath)) {
+        return { status: 'pass', message: 'MCP server configured (local development)' };
+    }
+    // Check if .copilot/mcp-config.json exists
+    const mcpConfigPath = join(cwd, '.copilot', 'mcp-config.json');
+    if (existsSync(mcpConfigPath)) {
+        try {
+            const config = JSON.parse(readFileSync(mcpConfigPath, 'utf-8'));
+            if (config.mcpServers && config.mcpServers['ally-patterns']) {
+                return { status: 'warn', message: 'MCP config exists but server files not found. Run: npm run build:all' };
+            }
+        }
+        catch {
+            return { status: 'warn', message: 'MCP config file invalid' };
+        }
+    }
+    return { status: 'info', message: 'MCP server not configured. Run: ally init' };
+}
+/**
+ * Check if .allyrc.json exists and is valid
+ */
+function checkAllyConfig() {
+    const cwd = process.cwd();
+    const configPath = join(cwd, '.allyrc.json');
+    if (!existsSync(configPath)) {
+        return { status: 'info', message: '.allyrc.json not found (using defaults)' };
+    }
+    try {
+        const content = readFileSync(configPath, 'utf-8');
+        JSON.parse(content);
+        return { status: 'pass', message: '.allyrc.json valid' };
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return { status: 'fail', message: `.allyrc.json invalid JSON: ${errorMsg}` };
+    }
+}
+/**
+ * Check if .allyignore exists
+ */
+function checkAllyIgnore() {
+    const cwd = process.cwd();
+    const ignorePath = join(cwd, '.allyignore');
+    if (existsSync(ignorePath)) {
+        return { status: 'pass', message: '.allyignore found' };
+    }
+    return { status: 'info', message: '.allyignore not found (optional)' };
+}
+/**
+ * Print a check result with appropriate styling
+ */
+function printCheck(result) {
+    const icons = {
+        pass: chalk.green('  '),
+        warn: chalk.yellow('  '),
+        fail: chalk.red('  '),
+        info: chalk.blue('  '),
+    };
+    const colors = {
+        pass: chalk.green,
+        warn: chalk.yellow,
+        fail: chalk.red,
+        info: chalk.blue,
+    };
+    console.log(`${icons[result.status]} ${colors[result.status](result.message)}`);
+}
+export async function doctorCommand() {
+    printBanner();
+    console.log(chalk.bold.cyan('Checking ally installation...\n'));
+    const results = [];
+    let hasFailures = false;
+    // 1. Check Node.js version
+    const nodeVersion = getNodeVersion();
+    const nodeMajor = parseMajorVersion(nodeVersion);
+    if (nodeMajor >= 18) {
+        results.push({ status: 'pass', message: `Node.js ${nodeVersion} (>=18 required)` });
+    }
+    else {
+        results.push({ status: 'fail', message: `Node.js ${nodeVersion} (>=18 required)` });
+        hasFailures = true;
+    }
+    // 2. Check ally version
+    const allyVersion = getAllyVersion();
+    if (allyVersion !== 'unknown') {
+        results.push({ status: 'pass', message: `ally v${allyVersion} installed` });
+    }
+    else {
+        results.push({ status: 'warn', message: 'ally version unknown' });
+    }
+    // 3. Check Puppeteer browser
+    const puppeteerResult = await checkPuppeteerBrowser();
+    results.push(puppeteerResult);
+    if (puppeteerResult.status === 'fail') {
+        hasFailures = true;
+    }
+    // 4. Check GitHub Copilot CLI
+    if (commandExists('copilot')) {
+        results.push({ status: 'pass', message: 'GitHub Copilot CLI available' });
+    }
+    else if (commandExists('gh') && commandExists('gh-copilot')) {
+        results.push({ status: 'pass', message: 'GitHub Copilot CLI available (gh extension)' });
+    }
+    else {
+        results.push({ status: 'warn', message: 'GitHub Copilot CLI not found (optional)' });
+    }
+    // 5. Check MCP server
+    const mcpResult = checkMcpServer();
+    results.push(mcpResult);
+    if (mcpResult.status === 'fail') {
+        hasFailures = true;
+    }
+    // 6. Check .allyrc.json
+    const configResult = checkAllyConfig();
+    results.push(configResult);
+    if (configResult.status === 'fail') {
+        hasFailures = true;
+    }
+    // 7. Check .allyignore
+    const ignoreResult = checkAllyIgnore();
+    results.push(ignoreResult);
+    // Print all results
+    for (const result of results) {
+        printCheck(result);
+    }
+    // Print summary
+    console.log();
+    if (hasFailures) {
+        console.log(chalk.red.bold('Some checks failed. Please fix the issues above.'));
+    }
+    else {
+        console.log(chalk.green.bold('All checks passed! ally is ready to use.'));
+    }
+}
+export default doctorCommand;