ally-a11y 1.0.0

package/dist/utils/converters.js

@@ -0,0 +1,200 @@
+/**
+ * Format converters for accessibility reports
+ * Converts AllyReport to various output formats (SARIF, JUnit, CSV)
+ */
+import { relative } from 'path';
+/**
+ * Map axe-core severity to SARIF level
+ */
+function severityToSarifLevel(severity) {
+    switch (severity) {
+        case 'critical':
+        case 'serious':
+            return 'error';
+        case 'moderate':
+            return 'warning';
+        case 'minor':
+        default:
+            return 'note';
+    }
+}
+/**
+ * Convert AllyReport to SARIF 2.1.0 format for GitHub Code Scanning integration
+ */
+export function convertToSarif(report) {
+    // Collect unique rules from all violations
+    const ruleMap = new Map();
+    for (const result of report.results) {
+        for (const violation of result.violations) {
+            if (!ruleMap.has(violation.id)) {
+                ruleMap.set(violation.id, { violation, severity: violation.impact });
+            }
+        }
+    }
+    // Build rules array
+    const rules = [];
+    const ruleIndexMap = new Map();
+    Array.from(ruleMap.entries()).forEach(([ruleId, { violation, severity }]) => {
+        ruleIndexMap.set(ruleId, rules.length);
+        rules.push({
+            id: ruleId,
+            name: ruleId,
+            shortDescription: { text: violation.help },
+            fullDescription: { text: violation.description },
+            helpUri: violation.helpUrl,
+            defaultConfiguration: {
+                level: severityToSarifLevel(severity),
+            },
+            properties: {
+                tags: violation.tags,
+            },
+        });
+    });
+    // Build results array
+    const results = [];
+    for (const scanResult of report.results) {
+        const fileUri = scanResult.file
+            ? relative(process.cwd(), scanResult.file)
+            : scanResult.url;
+        for (const violation of scanResult.violations) {
+            const ruleIndex = ruleIndexMap.get(violation.id) ?? 0;
+            // Create a result for each affected node
+            for (const node of violation.nodes) {
+                const locations = [
+                    {
+                        physicalLocation: {
+                            artifactLocation: {
+                                uri: fileUri,
+                                uriBaseId: '%SRCROOT%',
+                            },
+                            region: {
+                                startLine: 1, // Line info not available from axe-core
+                                snippet: { text: node.html },
+                            },
+                        },
+                    },
+                ];
+                results.push({
+                    ruleId: violation.id,
+                    ruleIndex,
+                    level: severityToSarifLevel(violation.impact),
+                    message: {
+                        text: `${violation.help}. ${node.failureSummary}`,
+                    },
+                    locations,
+                });
+            }
+        }
+    }
+    return {
+        $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'ally',
+                        version: '1.0.0',
+                        informationUri: 'https://github.com/forbiddenlink/ally',
+                        rules,
+                    },
+                },
+                results,
+            },
+        ],
+    };
+}
+/**
+ * Escape XML special characters
+ */
+function escapeXml(str) {
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/**
+ * Convert AllyReport to JUnit XML format for CI/CD tools (Jenkins, GitLab, etc.)
+ * Each violation is represented as a test failure
+ */
+export function convertToJunit(report) {
+    // Count total tests (violations) and failures
+    let totalTests = 0;
+    let totalFailures = 0;
+    // Collect all violations with their file context
+    const testcases = [];
+    for (const result of report.results) {
+        const fileUri = result.file
+            ? relative(process.cwd(), result.file)
+            : result.url || 'unknown';
+        for (const violation of result.violations) {
+            for (const node of violation.nodes) {
+                totalTests++;
+                totalFailures++;
+                const wcagTags = violation.tags.filter(t => t.startsWith('wcag')).join(', ');
+                const failureMessage = escapeXml(`${violation.help}. ${node.failureSummary || ''}`);
+                const failureDetails = escapeXml(`File: ${fileUri}\n` +
+                    `Selector: ${node.target.join(' > ')}\n` +
+                    `HTML: ${node.html}\n` +
+                    `WCAG: ${wcagTags}\n` +
+                    `Help: ${violation.helpUrl}`);
+                testcases.push(`    <testcase name="${escapeXml(violation.id)}" classname="${escapeXml(violation.impact)}" time="0">\n` +
+                    `      <failure message="${failureMessage}" type="${escapeXml(violation.impact)}">\n` +
+                    `${failureDetails}\n` +
+                    `      </failure>\n` +
+                    `    </testcase>`);
+            }
+        }
+    }
+    // Build the JUnit XML
+    const xml = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<testsuites name="ally-a11y" tests="${totalTests}" failures="${totalFailures}" errors="0" time="0">`,
+        `  <testsuite name="accessibility" tests="${totalTests}" failures="${totalFailures}" errors="0" skipped="0" time="0">`,
+        ...testcases,
+        '  </testsuite>',
+        '</testsuites>',
+    ].join('\n');
+    return xml;
+}
+/**
+ * Escape a value for CSV output
+ */
+function escapeCsv(value) {
+    // If value contains comma, quote, or newline, wrap in quotes and escape internal quotes
+    if (value.includes(',') || value.includes('"') || value.includes('\n') || value.includes('\r')) {
+        return '"' + value.replace(/"/g, '""') + '"';
+    }
+    return value;
+}
+/**
+ * Convert AllyReport to CSV format
+ * Headers: file,violation_id,impact,description,selector,wcag,help_url
+ */
+export function convertToCsv(report) {
+    const headers = ['file', 'violation_id', 'impact', 'description', 'selector', 'wcag', 'help_url'];
+    const rows = [headers.join(',')];
+    for (const result of report.results) {
+        const fileUri = result.file
+            ? relative(process.cwd(), result.file)
+            : result.url || 'unknown';
+        for (const violation of result.violations) {
+            const wcagTags = violation.tags.filter(t => t.startsWith('wcag')).join('; ');
+            for (const node of violation.nodes) {
+                const row = [
+                    escapeCsv(fileUri),
+                    escapeCsv(violation.id),
+                    escapeCsv(violation.impact),
+                    escapeCsv(violation.help),
+                    escapeCsv(node.target.join(' > ')),
+                    escapeCsv(wcagTags),
+                    escapeCsv(violation.helpUrl),
+                ];
+                rows.push(row.join(','));
+            }
+        }
+    }
+    return rows.join('\n');
+}

package/dist/utils/copilot.d.ts

@@ -0,0 +1,36 @@
+/**
+ * GitHub Copilot CLI integration utilities
+ */
+export interface CopilotConfig {
+    available: boolean;
+    command: string;
+    version?: string;
+}
+/**
+ * Check if GitHub Copilot CLI is installed and available
+ */
+export declare function checkCopilotCli(): CopilotConfig;
+/**
+ * Generate a Copilot CLI prompt for fixing an accessibility issue
+ */
+export declare function generateFixPrompt(file: string, issue: string, html: string, suggestedFix?: string): string;
+/**
+ * Invoke Copilot CLI to fix an issue (with approval flow)
+ */
+export declare function invokeCopilotFix(file: string, prompt: string, options?: {
+    allowEdits?: boolean;
+}): Promise<{
+    success: boolean;
+    output: string;
+}>;
+/**
+ * Print Copilot CLI installation instructions
+ */
+export declare function printCopilotInstructions(): void;
+/**
+ * Check if MCP server is configured
+ */
+export declare function checkMcpConfig(): {
+    configured: boolean;
+    path: string;
+};

package/dist/utils/copilot.js

@@ -0,0 +1,139 @@
+/**
+ * GitHub Copilot CLI integration utilities
+ */
+import { spawn, execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { homedir } from 'os';
+import chalk from 'chalk';
+/**
+ * Check if GitHub Copilot CLI is installed and available
+ */
+export function checkCopilotCli() {
+    const commands = ['copilot', 'gh copilot'];
+    for (const cmd of commands) {
+        try {
+            const result = execSync(`${cmd} --version 2>/dev/null`, {
+                encoding: 'utf-8',
+                timeout: 5000,
+            });
+            return {
+                available: true,
+                command: cmd,
+                version: result.trim(),
+            };
+        }
+        catch {
+            // Command not found, try next
+        }
+    }
+    return {
+        available: false,
+        command: '',
+    };
+}
+/**
+ * Generate a Copilot CLI prompt for fixing an accessibility issue
+ */
+export function generateFixPrompt(file, issue, html, suggestedFix) {
+    let prompt = `Fix this accessibility issue in ${file}:
+
+Issue: ${issue}
+
+Current code:
+${html}
+`;
+    if (suggestedFix) {
+        prompt += `
+Suggested fix pattern:
+${suggestedFix}
+`;
+    }
+    prompt += `
+Requirements:
+- Make the minimal change needed to fix the accessibility issue
+- Preserve existing functionality and styling
+- Follow WCAG 2.1 AA guidelines
+- Use semantic HTML where possible
+`;
+    return prompt;
+}
+/**
+ * Invoke Copilot CLI to fix an issue (with approval flow)
+ */
+export async function invokeCopilotFix(file, prompt, options = {}) {
+    const config = checkCopilotCli();
+    if (!config.available) {
+        return {
+            success: false,
+            output: 'GitHub Copilot CLI is not installed. Install it with: npm install -g @github/copilot-cli',
+        };
+    }
+    return new Promise((resolve) => {
+        const args = ['-p', prompt];
+        if (options.allowEdits) {
+            args.unshift('--allow-edits');
+        }
+        // Split command if it contains spaces (e.g., "gh copilot")
+        const cmdParts = config.command.split(' ');
+        const cmd = cmdParts[0];
+        const cmdArgs = [...cmdParts.slice(1), ...args];
+        const copilot = spawn(cmd, cmdArgs, {
+            stdio: ['inherit', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        copilot.stdout?.on('data', (data) => {
+            stdout += data.toString();
+            process.stdout.write(data);
+        });
+        copilot.stderr?.on('data', (data) => {
+            stderr += data.toString();
+            process.stderr.write(data);
+        });
+        copilot.on('close', (code) => {
+            resolve({
+                success: code === 0,
+                output: stdout || stderr,
+            });
+        });
+        copilot.on('error', (error) => {
+            resolve({
+                success: false,
+                output: error.message,
+            });
+        });
+    });
+}
+/**
+ * Print Copilot CLI installation instructions
+ */
+export function printCopilotInstructions() {
+    console.log();
+    console.log(chalk.yellow('GitHub Copilot CLI not detected.'));
+    console.log();
+    console.log(chalk.bold('To enable AI-powered fixes, install Copilot CLI:'));
+    console.log();
+    console.log(chalk.cyan('  npm install -g @github/copilot-cli'));
+    console.log(chalk.cyan('  copilot auth login'));
+    console.log();
+    console.log(chalk.dim('Once installed, run `ally fix` again for AI-assisted fixes.'));
+    console.log(chalk.dim('For now, showing manual fix suggestions below.'));
+    console.log();
+}
+/**
+ * Check if MCP server is configured
+ */
+export function checkMcpConfig() {
+    const home = homedir();
+    const configPaths = [
+        '.copilot/mcp-config.json',
+        ...(home ? [resolve(home, '.copilot/mcp-config.json')] : []),
+    ];
+    for (const configPath of configPaths) {
+        if (existsSync(configPath)) {
+            return { configured: true, path: configPath };
+        }
+    }
+    return { configured: false, path: '' };
+}

package/dist/utils/detect.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Smart project detection for zero-config scanning
+ */
+export type ProjectType = 'next' | 'nuxt' | 'react' | 'vue' | 'svelte' | 'angular' | 'html' | 'unknown';
+export interface ProjectInfo {
+    type: ProjectType;
+    srcDir: string;
+    publicDir: string;
+    patterns: string[];
+}
+/**
+ * Detect the project type and return appropriate scan patterns
+ */
+export declare function detectProject(cwd: string): Promise<ProjectInfo>;
+/**
+ * Count files matching the detected patterns
+ */
+export declare function countProjectFiles(cwd: string, patterns: string[]): Promise<number>;
+/**
+ * Get a human-readable description of the project type
+ */
+export declare function getProjectDescription(type: ProjectType): string;

package/dist/utils/detect.js

@@ -0,0 +1,197 @@
+/**
+ * Smart project detection for zero-config scanning
+ */
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve, join } from 'path';
+import { glob } from 'glob';
+/**
+ * Detect the project type and return appropriate scan patterns
+ */
+export async function detectProject(cwd) {
+    const packageJsonPath = resolve(cwd, 'package.json');
+    // Try to detect from package.json first
+    if (existsSync(packageJsonPath)) {
+        try {
+            const content = await readFile(packageJsonPath, 'utf-8');
+            const pkg = JSON.parse(content);
+            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+            // Check for frameworks in priority order
+            if ('next' in allDeps) {
+                return detectNextProject(cwd);
+            }
+            if ('nuxt' in allDeps) {
+                return detectNuxtProject(cwd);
+            }
+            if ('@angular/core' in allDeps) {
+                return {
+                    type: 'angular',
+                    srcDir: 'src',
+                    publicDir: 'public',
+                    patterns: ['src/**/*.html', 'src/**/*.component.html'],
+                };
+            }
+            if ('svelte' in allDeps || '@sveltejs/kit' in allDeps) {
+                return {
+                    type: 'svelte',
+                    srcDir: 'src',
+                    publicDir: 'static',
+                    patterns: ['src/**/*.svelte'],
+                };
+            }
+            if ('vue' in allDeps) {
+                return {
+                    type: 'vue',
+                    srcDir: 'src',
+                    publicDir: 'public',
+                    patterns: ['src/**/*.vue'],
+                };
+            }
+            if ('react' in allDeps || 'react-dom' in allDeps) {
+                return {
+                    type: 'react',
+                    srcDir: 'src',
+                    publicDir: 'public',
+                    patterns: ['src/**/*.tsx', 'src/**/*.jsx'],
+                };
+            }
+        }
+        catch {
+            // Failed to parse package.json, fall through to directory detection
+        }
+    }
+    // No package.json or no recognized framework - check for common directories
+    return await detectStaticSite(cwd);
+}
+/**
+ * Detect Next.js project structure
+ */
+async function detectNextProject(cwd) {
+    // Check for app router (Next.js 13+)
+    const hasAppDir = existsSync(join(cwd, 'app'));
+    const hasSrcAppDir = existsSync(join(cwd, 'src', 'app'));
+    // Check for pages router
+    const hasPagesDir = existsSync(join(cwd, 'pages'));
+    const hasSrcPagesDir = existsSync(join(cwd, 'src', 'pages'));
+    const patterns = [];
+    let srcDir = '.';
+    if (hasSrcAppDir || hasSrcPagesDir) {
+        srcDir = 'src';
+    }
+    if (hasAppDir || hasSrcAppDir) {
+        const appPath = hasSrcAppDir ? 'src/app' : 'app';
+        patterns.push(`${appPath}/**/*.tsx`, `${appPath}/**/*.jsx`);
+    }
+    if (hasPagesDir || hasSrcPagesDir) {
+        const pagesPath = hasSrcPagesDir ? 'src/pages' : 'pages';
+        patterns.push(`${pagesPath}/**/*.tsx`, `${pagesPath}/**/*.jsx`);
+    }
+    // Also scan components directory if it exists
+    if (existsSync(join(cwd, 'components'))) {
+        patterns.push('components/**/*.tsx', 'components/**/*.jsx');
+    }
+    else if (existsSync(join(cwd, 'src', 'components'))) {
+        patterns.push('src/components/**/*.tsx', 'src/components/**/*.jsx');
+    }
+    // Include public HTML files
+    patterns.push('public/**/*.html');
+    return {
+        type: 'next',
+        srcDir,
+        publicDir: 'public',
+        patterns: patterns.length > 0 ? patterns : ['**/*.tsx', '**/*.jsx', 'public/**/*.html'],
+    };
+}
+/**
+ * Detect Nuxt project structure
+ */
+async function detectNuxtProject(cwd) {
+    const patterns = [];
+    // Nuxt 3 uses pages/ and components/
+    if (existsSync(join(cwd, 'pages'))) {
+        patterns.push('pages/**/*.vue');
+    }
+    if (existsSync(join(cwd, 'components'))) {
+        patterns.push('components/**/*.vue');
+    }
+    if (existsSync(join(cwd, 'layouts'))) {
+        patterns.push('layouts/**/*.vue');
+    }
+    // App.vue at root
+    if (existsSync(join(cwd, 'app.vue'))) {
+        patterns.push('app.vue');
+    }
+    // Public HTML files
+    patterns.push('public/**/*.html');
+    return {
+        type: 'nuxt',
+        srcDir: '.',
+        publicDir: 'public',
+        patterns: patterns.length > 0 ? patterns : ['**/*.vue', 'public/**/*.html'],
+    };
+}
+/**
+ * Detect static HTML site
+ */
+async function detectStaticSite(cwd) {
+    // Check for common static site directories
+    const staticDirs = ['public', 'dist', 'build', 'out', '_site', 'www'];
+    for (const dir of staticDirs) {
+        const dirPath = join(cwd, dir);
+        if (existsSync(dirPath)) {
+            const htmlFiles = await glob('**/*.html', { cwd: dirPath, absolute: false });
+            if (htmlFiles.length > 0) {
+                return {
+                    type: 'html',
+                    srcDir: dir,
+                    publicDir: dir,
+                    patterns: [`${dir}/**/*.html`, `${dir}/**/*.htm`],
+                };
+            }
+        }
+    }
+    // Check for HTML files in the root
+    const rootHtmlFiles = await glob('*.html', { cwd, absolute: false });
+    if (rootHtmlFiles.length > 0) {
+        return {
+            type: 'html',
+            srcDir: '.',
+            publicDir: '.',
+            patterns: ['**/*.html', '**/*.htm'],
+        };
+    }
+    // Unknown project type - default to scanning for HTML files
+    return {
+        type: 'unknown',
+        srcDir: '.',
+        publicDir: '.',
+        patterns: ['**/*.html', '**/*.htm'],
+    };
+}
+/**
+ * Count files matching the detected patterns
+ */
+export async function countProjectFiles(cwd, patterns) {
+    const files = await glob(patterns, {
+        cwd,
+        ignore: ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.git/**'],
+        absolute: false,
+    });
+    return files.length;
+}
+/**
+ * Get a human-readable description of the project type
+ */
+export function getProjectDescription(type) {
+    const descriptions = {
+        next: 'Next.js project',
+        nuxt: 'Nuxt project',
+        react: 'React project',
+        vue: 'Vue project',
+        svelte: 'Svelte project',
+        angular: 'Angular project',
+        html: 'Static HTML site',
+        unknown: 'Unknown project type',
+    };
+    return descriptions[type];
+}

package/dist/utils/enhanced-errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Enhanced Error Messages System
+ *
+ * Provides actionable, helpful error messages with:
+ * - Clear explanations of what went wrong
+ * - Step-by-step remediation guidance
+ * - Code examples
+ * - Links to documentation
+ * - Context-specific suggestions
+ */
+export interface EnhancedError {
+    title: string;
+    message: string;
+    remediation: string[];
+    example?: string;
+    docs?: string;
+    tip?: string;
+}
+/**
+ * Error messages for common issues
+ */
+export declare const ERROR_MESSAGES: Record<string, EnhancedError>;
+/**
+ * Get enhanced error message
+ */
+export declare function getEnhancedError(errorCode: string): EnhancedError | null;
+/**
+ * Format enhanced error for console output
+ */
+export declare function formatEnhancedError(error: EnhancedError): string;
+/**
+ * Common error patterns and their codes
+ */
+export declare function detectErrorCode(error: Error): string | null;
+/**
+ * Show enhanced error and exit
+ */
+export declare function showEnhancedErrorAndExit(errorCode: string, exitCode?: number): never;
+/**
+ * Throw enhanced error (for backwards compatibility)
+ */
+export declare function throwEnhancedError(errorCode: string, originalError?: Error): never;
+/**
+ * Handle error with enhanced message
+ */
+export declare function handleErrorWithEnhancement(error: Error): void;