ally-a11y 1.0.0

package/dist/commands/pr-check.js

@@ -0,0 +1,270 @@
+/**
+ * ally pr-check command - Post accessibility results to GitHub PR
+ */
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+import boxen from 'boxen';
+import { printBanner, createSpinner, printError, printSuccess, printInfo, printWarning, } from '../utils/ui.js';
+import { suggestInit } from '../utils/errors.js';
+/**
+ * Get current GitHub repo from git remote
+ */
+function getGitHubRepo() {
+    try {
+        const remote = execSync('git remote get-url origin', { encoding: 'utf-8' }).trim();
+        // Parse GitHub URL (supports both HTTPS and SSH)
+        // https://github.com/owner/repo.git
+        // git@github.com:owner/repo.git
+        const httpsMatch = remote.match(/github\.com\/([^/]+)\/([^/.]+)/);
+        const sshMatch = remote.match(/github\.com:([^/]+)\/([^/.]+)/);
+        const match = httpsMatch || sshMatch;
+        if (match) {
+            return {
+                owner: match[1],
+                repo: match[2].replace(/\.git$/, ''),
+            };
+        }
+    }
+    catch {
+        // Not in a git repo or no remote
+    }
+    return null;
+}
+/**
+ * Get current PR number from environment or git
+ */
+function getCurrentPR() {
+    // Check GitHub Actions environment
+    if (process.env.GITHUB_EVENT_NAME === 'pull_request') {
+        const eventPath = process.env.GITHUB_EVENT_PATH;
+        if (eventPath && existsSync(eventPath)) {
+            try {
+                const event = JSON.parse(require('fs').readFileSync(eventPath, 'utf-8'));
+                return event.pull_request?.number || null;
+            }
+            catch {
+                // Ignore
+            }
+        }
+    }
+    // Check GITHUB_REF for PR number
+    const ref = process.env.GITHUB_REF;
+    if (ref) {
+        const prMatch = ref.match(/refs\/pull\/(\d+)/);
+        if (prMatch) {
+            return parseInt(prMatch[1], 10);
+        }
+    }
+    return null;
+}
+/**
+ * Format severity for display
+ */
+function getSeverityEmoji(severity) {
+    const emojis = {
+        critical: ':red_circle:',
+        serious: ':orange_circle:',
+        moderate: ':yellow_circle:',
+        minor: ':blue_circle:',
+    };
+    return emojis[severity] || ':white_circle:';
+}
+/**
+ * Generate markdown comment for PR
+ */
+function generatePRComment(report) {
+    const { summary } = report;
+    const scoreEmoji = summary.score >= 90 ? ':star:' : summary.score >= 75 ? ':white_check_mark:' : summary.score >= 50 ? ':warning:' : ':x:';
+    let comment = `## ${scoreEmoji} Accessibility Report
+
+**Score:** ${summary.score}/100
+
+| Severity | Count |
+|----------|-------|
+| :red_circle: Critical | ${summary.bySeverity.critical || 0} |
+| :orange_circle: Serious | ${summary.bySeverity.serious || 0} |
+| :yellow_circle: Moderate | ${summary.bySeverity.moderate || 0} |
+| :blue_circle: Minor | ${summary.bySeverity.minor || 0} |
+
+`;
+    if (summary.topIssues.length > 0) {
+        comment += `### Top Issues\n\n`;
+        for (const issue of summary.topIssues.slice(0, 5)) {
+            const emoji = getSeverityEmoji(issue.severity);
+            comment += `- ${emoji} **${issue.id}**: ${issue.description} (${issue.count} occurrences)\n`;
+        }
+        comment += '\n';
+    }
+    if (summary.totalViolations > 0) {
+        comment += `<details>
+<summary>How to fix</summary>
+
+\`\`\`bash
+# Get detailed explanations
+ally explain
+
+# Apply AI-powered fixes
+ally fix
+\`\`\`
+
+</details>
+
+`;
+    }
+    comment += `---
+*Generated by [ally](https://github.com/forbiddenlink/ally) :robot:*`;
+    return comment;
+}
+/**
+ * Post comment to GitHub PR using gh CLI
+ */
+async function postPRComment(repo, prNumber, comment) {
+    try {
+        // Write comment to temp file to avoid shell escaping issues
+        const tempFile = resolve('.ally/pr-comment.md');
+        await writeFile(tempFile, comment);
+        // Use gh CLI to post comment
+        execSync(`gh pr comment ${prNumber} --repo ${repo.owner}/${repo.repo} --body-file "${tempFile}"`, { encoding: 'utf-8', stdio: 'pipe' });
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            // Check for common errors
+            if (error.message.includes('gh: command not found')) {
+                printError('GitHub CLI (gh) not found. Install it from https://cli.github.com/');
+            }
+            else if (error.message.includes('not logged in')) {
+                printError('Not logged in to GitHub CLI. Run: gh auth login');
+            }
+            else {
+                printError(`Failed to post comment: ${error.message}`);
+            }
+        }
+        return false;
+    }
+}
+/**
+ * Create GitHub check annotations for violations
+ */
+function generateAnnotations(report) {
+    const annotations = [];
+    for (const result of report.results) {
+        const file = result.file || 'unknown';
+        for (const violation of result.violations) {
+            for (const node of violation.nodes) {
+                // Try to extract line number from HTML context
+                const annotation = {
+                    path: file,
+                    start_line: 1, // Would need source map for actual line
+                    end_line: 1,
+                    annotation_level: violation.impact === 'critical' || violation.impact === 'serious' ? 'failure' : 'warning',
+                    message: `${violation.id}: ${violation.help}\n\nElement: ${node.html.substring(0, 100)}...`,
+                    title: violation.description,
+                };
+                annotations.push(JSON.stringify(annotation));
+            }
+        }
+    }
+    return annotations.join('\n');
+}
+export async function prCheckCommand(options = {}) {
+    printBanner();
+    const { input = '.ally/scan.json', pr, comment = true, failOn } = 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;
+    }
+    // Get GitHub repo info
+    const repo = getGitHubRepo();
+    if (!repo) {
+        printWarning('Not a GitHub repository. Skipping PR integration.');
+        console.log();
+        printInfo('This command works best in a GitHub repository with a PR open.');
+        return;
+    }
+    // Get PR number
+    const prNumber = pr || getCurrentPR();
+    if (!prNumber) {
+        printWarning('No PR number detected. Use --pr <number> to specify.');
+        console.log();
+        printInfo('Run this command from a GitHub Actions PR workflow or specify --pr manually.');
+        // Still show the report summary
+        console.log();
+        console.log(boxen(`${chalk.bold('Accessibility Report')}\n\n` +
+            `Score: ${report.summary.score}/100\n` +
+            `Violations: ${report.summary.totalViolations}`, {
+            padding: 1,
+            borderStyle: 'round',
+            borderColor: report.summary.score >= 75 ? 'green' : 'yellow',
+        }));
+        return;
+    }
+    console.log();
+    printInfo(`Posting results to ${repo.owner}/${repo.repo}#${prNumber}`);
+    // Post PR comment
+    if (comment) {
+        const commentSpinner = createSpinner('Posting PR comment...');
+        commentSpinner.start();
+        const prComment = generatePRComment(report);
+        const success = await postPRComment(repo, prNumber, prComment);
+        if (success) {
+            commentSpinner.succeed('Posted accessibility report to PR');
+        }
+        else {
+            commentSpinner.fail('Failed to post PR comment');
+        }
+    }
+    // Print summary
+    console.log();
+    const scoreColor = report.summary.score >= 90 ? chalk.green
+        : report.summary.score >= 75 ? chalk.yellow
+            : chalk.red;
+    console.log(boxen(`${chalk.bold('Accessibility Check Complete')}\n\n` +
+        `Score: ${scoreColor(`${report.summary.score}/100`)}\n\n` +
+        `Critical: ${report.summary.bySeverity.critical || 0}\n` +
+        `Serious: ${report.summary.bySeverity.serious || 0}\n` +
+        `Moderate: ${report.summary.bySeverity.moderate || 0}\n` +
+        `Minor: ${report.summary.bySeverity.minor || 0}`, {
+        padding: 1,
+        borderStyle: 'round',
+        borderColor: report.summary.score >= 75 ? 'green' : 'yellow',
+    }));
+    // Check fail conditions
+    if (failOn) {
+        const severities = failOn.split(',').map((s) => s.trim().toLowerCase());
+        let shouldFail = false;
+        for (const severity of severities) {
+            if (report.summary.bySeverity[severity] && report.summary.bySeverity[severity] > 0) {
+                shouldFail = true;
+                break;
+            }
+        }
+        if (shouldFail) {
+            console.log();
+            printError(`Failing due to ${failOn} violations`);
+            process.exit(1);
+        }
+    }
+    console.log();
+    printSuccess('PR check complete!');
+}
+export default prCheckCommand;

package/dist/commands/report.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ally report command - Generates ACCESSIBILITY.md report
+ */
+type ReportFormat = 'markdown' | 'html' | 'json' | 'sarif' | 'junit' | 'csv' | 'all';
+interface ReportOptions {
+    input?: string;
+    output?: string;
+    format?: ReportFormat;
+}
+export declare function reportCommand(options?: ReportOptions): Promise<void>;
+export default reportCommand;

package/dist/commands/report.js

@@ -0,0 +1,375 @@
+/**
+ * ally report command - Generates ACCESSIBILITY.md report
+ */
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve, dirname, basename, relative } from 'path';
+import chalk from 'chalk';
+import { printBanner, createSpinner, printError, printInfo, printSuccess, } from '../utils/ui.js';
+import { suggestInit, suggestRescan } from '../utils/errors.js';
+import { convertToSarif, convertToJunit, convertToCsv } from '../utils/converters.js';
+export async function reportCommand(options = {}) {
+    printBanner();
+    const { input = '.ally/scan.json', output = 'ACCESSIBILITY.md', format = 'markdown', } = 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');
+        if (error instanceof SyntaxError) {
+            suggestRescan(reportPath);
+        }
+        else {
+            printError(error instanceof Error ? error.message : String(error));
+        }
+        return;
+    }
+    // Generate report
+    const generateSpinner = createSpinner('Generating report...');
+    generateSpinner.start();
+    // Handle batch export (--format all)
+    if (format === 'all') {
+        const outputDir = dirname(resolve(output));
+        const generatedFiles = [];
+        try {
+            // Generate all formats
+            const formats = [
+                { name: 'ACCESSIBILITY.md', ext: 'md', content: generateMarkdownReport(report) },
+                { name: 'accessibility.html', ext: 'html', content: generateHtmlReport(report) },
+                { name: 'accessibility.json', ext: 'json', content: JSON.stringify(report, null, 2) },
+                { name: 'accessibility.sarif', ext: 'sarif', content: JSON.stringify(convertToSarif(report), null, 2) },
+                { name: 'accessibility.junit.xml', ext: 'xml', content: convertToJunit(report) },
+                { name: 'accessibility.csv', ext: 'csv', content: convertToCsv(report) },
+            ];
+            for (const { name, content } of formats) {
+                const filePath = resolve(outputDir, name);
+                await writeFile(filePath, content);
+                generatedFiles.push(name);
+            }
+            generateSpinner.succeed('Generated all report formats');
+            console.log();
+            console.log(chalk.green(`\u2713 Generated ${generatedFiles.length} report files:`));
+            for (const file of generatedFiles) {
+                console.log(chalk.dim(`  \u2022 ${file}`));
+            }
+        }
+        catch (error) {
+            generateSpinner.fail('Failed to write reports');
+            printError(error instanceof Error ? error.message : String(error));
+            return;
+        }
+    }
+    else {
+        // Single format export
+        let reportContent;
+        switch (format) {
+            case 'json':
+                reportContent = JSON.stringify(report, null, 2);
+                break;
+            case 'html':
+                reportContent = generateHtmlReport(report);
+                break;
+            case 'sarif':
+                reportContent = JSON.stringify(convertToSarif(report), null, 2);
+                break;
+            case 'junit':
+                reportContent = convertToJunit(report);
+                break;
+            case 'csv':
+                reportContent = convertToCsv(report);
+                break;
+            case 'markdown':
+            default:
+                reportContent = generateMarkdownReport(report);
+        }
+        // Adjust output filename based on format
+        let outputPath = resolve(output);
+        if (format === 'sarif' && !output.endsWith('.sarif')) {
+            outputPath = resolve(dirname(output), 'accessibility.sarif');
+        }
+        else if (format === 'junit' && !output.endsWith('.xml')) {
+            outputPath = resolve(dirname(output), 'accessibility.junit.xml');
+        }
+        else if (format === 'csv' && !output.endsWith('.csv')) {
+            outputPath = resolve(dirname(output), 'accessibility.csv');
+        }
+        else if (format === 'json' && !output.endsWith('.json')) {
+            outputPath = resolve(dirname(output), 'accessibility.json');
+        }
+        else if (format === 'html' && !output.endsWith('.html')) {
+            outputPath = resolve(dirname(output), 'accessibility.html');
+        }
+        try {
+            await writeFile(outputPath, reportContent);
+            generateSpinner.succeed(`Report generated: ${outputPath}`);
+        }
+        catch (error) {
+            generateSpinner.fail('Failed to write report');
+            printError(error instanceof Error ? error.message : String(error));
+            return;
+        }
+        console.log();
+        printSuccess('Accessibility report ready!');
+        printInfo(`Add ${basename(outputPath)} to your repository to document your a11y compliance`);
+    }
+    // Generate badge URL
+    const badgeColor = report.summary.score >= 90 ? 'brightgreen'
+        : report.summary.score >= 75 ? 'green'
+            : report.summary.score >= 50 ? 'yellow'
+                : 'red';
+    console.log();
+    console.log(chalk.bold('Badge for README:'));
+    console.log(chalk.dim(`![Accessibility Score](https://img.shields.io/badge/a11y_score-${report.summary.score}%25-${badgeColor})`));
+}
+function generateMarkdownReport(report) {
+    const { summary } = report;
+    const scanDate = new Date(report.scanDate).toLocaleDateString();
+    // Score emoji
+    const scoreEmoji = summary.score >= 90 ? '🌟'
+        : summary.score >= 75 ? '✅'
+            : summary.score >= 50 ? '⚠️'
+                : '❌';
+    let md = `# Accessibility Report ${scoreEmoji}
+
+> Generated by [ally](https://github.com/forbiddenlink/ally) on ${scanDate}
+
+## Score: ${summary.score}/100
+
+![Accessibility Score](https://img.shields.io/badge/a11y_score-${summary.score}%25-${getScoreColor(summary.score)})
+
+## Summary
+
+| Severity | Count |
+|----------|-------|
+| 🔴 Critical | ${summary.bySeverity.critical || 0} |
+| 🟠 Serious | ${summary.bySeverity.serious || 0} |
+| 🟡 Moderate | ${summary.bySeverity.moderate || 0} |
+| 🔵 Minor | ${summary.bySeverity.minor || 0} |
+| **Total** | **${summary.totalViolations}** |
+
+## Top Issues
+
+`;
+    if (summary.topIssues.length > 0) {
+        for (const issue of summary.topIssues) {
+            const severityIcon = getSeverityIcon(issue.severity);
+            md += `### ${severityIcon} ${issue.description}\n\n`;
+            md += `- **Occurrences:** ${issue.count}\n`;
+            md += `- **Rule ID:** \`${issue.id}\`\n\n`;
+        }
+    }
+    else {
+        md += `No issues found! 🎉\n\n`;
+    }
+    // Files scanned
+    md += `## Files Scanned\n\n`;
+    md += `Total: ${report.totalFiles} files\n\n`;
+    if (report.results.length > 0) {
+        md += `| File | Issues |\n`;
+        md += `|------|--------|\n`;
+        for (const result of report.results) {
+            // Convert absolute paths to relative for cleaner reports
+            let fileName;
+            if (result.file) {
+                fileName = relative(process.cwd(), result.file) || result.file;
+            }
+            else if (result.url) {
+                fileName = result.url;
+            }
+            else {
+                fileName = 'unknown';
+            }
+            const issueCount = result.violations.length;
+            const icon = issueCount === 0 ? '✅' : issueCount < 5 ? '⚠️' : '❌';
+            md += `| ${icon} ${fileName} | ${issueCount} |\n`;
+        }
+    }
+    // WCAG Compliance
+    md += `\n## WCAG 2.1 Compliance\n\n`;
+    const wcagViolations = new Set();
+    for (const result of report.results) {
+        for (const violation of result.violations) {
+            for (const tag of violation.tags) {
+                if (tag.startsWith('wcag')) {
+                    wcagViolations.add(tag);
+                }
+            }
+        }
+    }
+    if (wcagViolations.size > 0) {
+        md += `The following WCAG criteria have violations:\n\n`;
+        for (const criterion of Array.from(wcagViolations).sort()) {
+            md += `- \`${criterion}\`\n`;
+        }
+    }
+    else {
+        md += `No WCAG violations detected! ✅\n`;
+    }
+    // Next steps
+    md += `\n## Next Steps\n\n`;
+    if (summary.totalViolations > 0) {
+        md += `1. Run \`ally explain\` to understand each issue\n`;
+        md += `2. Run \`ally fix\` to apply automated fixes\n`;
+        md += `3. Re-scan with \`ally scan\` to verify fixes\n`;
+    }
+    else {
+        md += `Your site is looking great! Consider:\n`;
+        md += `- Testing with real screen readers (NVDA, VoiceOver)\n`;
+        md += `- Running manual keyboard navigation tests\n`;
+        md += `- Getting user feedback from people with disabilities\n`;
+    }
+    // Footer
+    md += `\n---\n\n`;
+    md += `*This report was automatically generated. Automated testing can only catch ~50% of accessibility issues. Manual testing is recommended.*\n`;
+    return md;
+}
+function generateHtmlReport(report) {
+    const { summary } = report;
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Accessibility Report</title>
+  <style>
+    :root {
+      --critical: #dc2626;
+      --serious: #ea580c;
+      --moderate: #ca8a04;
+      --minor: #2563eb;
+      --pass: #16a34a;
+    }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      max-width: 800px;
+      margin: 0 auto;
+      padding: 2rem;
+      line-height: 1.6;
+    }
+    .score {
+      font-size: 4rem;
+      font-weight: bold;
+      text-align: center;
+      padding: 2rem;
+      border-radius: 1rem;
+      background: ${getScoreGradient(summary.score)};
+      color: white;
+    }
+    .severity-grid {
+      display: grid;
+      grid-template-columns: repeat(4, 1fr);
+      gap: 1rem;
+      margin: 2rem 0;
+    }
+    .severity-card {
+      padding: 1rem;
+      border-radius: 0.5rem;
+      text-align: center;
+    }
+    .severity-card.critical { background: var(--critical); color: white; }
+    .severity-card.serious { background: var(--serious); color: white; }
+    .severity-card.moderate { background: var(--moderate); color: white; }
+    .severity-card.minor { background: var(--minor); color: white; }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      margin: 1rem 0;
+    }
+    th, td {
+      padding: 0.75rem;
+      text-align: left;
+      border-bottom: 1px solid #e5e7eb;
+    }
+    th { background: #f9fafb; }
+  </style>
+</head>
+<body>
+  <h1>Accessibility Report</h1>
+  <div class="score">${summary.score}/100</div>
+
+  <h2>Violations by Severity</h2>
+  <div class="severity-grid">
+    <div class="severity-card critical">
+      <div style="font-size: 2rem;">${summary.bySeverity.critical || 0}</div>
+      <div>Critical</div>
+    </div>
+    <div class="severity-card serious">
+      <div style="font-size: 2rem;">${summary.bySeverity.serious || 0}</div>
+      <div>Serious</div>
+    </div>
+    <div class="severity-card moderate">
+      <div style="font-size: 2rem;">${summary.bySeverity.moderate || 0}</div>
+      <div>Moderate</div>
+    </div>
+    <div class="severity-card minor">
+      <div style="font-size: 2rem;">${summary.bySeverity.minor || 0}</div>
+      <div>Minor</div>
+    </div>
+  </div>
+
+  <h2>Top Issues</h2>
+  <table>
+    <thead>
+      <tr>
+        <th>Issue</th>
+        <th>Severity</th>
+        <th>Count</th>
+      </tr>
+    </thead>
+    <tbody>
+      ${summary.topIssues.map(issue => `
+        <tr>
+          <td>${issue.description}</td>
+          <td>${issue.severity}</td>
+          <td>${issue.count}</td>
+        </tr>
+      `).join('')}
+    </tbody>
+  </table>
+
+  <footer>
+    <p><em>Generated by ally on ${new Date(report.scanDate).toLocaleDateString()}</em></p>
+  </footer>
+</body>
+</html>`;
+}
+function getScoreColor(score) {
+    if (score >= 90)
+        return 'brightgreen';
+    if (score >= 75)
+        return 'green';
+    if (score >= 50)
+        return 'yellow';
+    return 'red';
+}
+function getScoreGradient(score) {
+    if (score >= 90)
+        return 'linear-gradient(135deg, #16a34a, #22c55e)';
+    if (score >= 75)
+        return 'linear-gradient(135deg, #65a30d, #84cc16)';
+    if (score >= 50)
+        return 'linear-gradient(135deg, #ca8a04, #eab308)';
+    return 'linear-gradient(135deg, #dc2626, #ef4444)';
+}
+function getSeverityIcon(severity) {
+    const icons = {
+        critical: '🔴',
+        serious: '🟠',
+        moderate: '🟡',
+        minor: '🔵',
+    };
+    return icons[severity] || '⚪';
+}
+export default reportCommand;

package/dist/commands/scan-storybook.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ally scan-storybook command - Scans Storybook stories for accessibility issues
+ */
+import { type WcagStandard } from '../utils/scanner.js';
+import type { AllyReport } from '../types/index.js';
+interface ScanStorybookOptions {
+    url?: string;
+    timeout?: number;
+    filter?: string;
+    format?: 'default' | 'json' | 'csv';
+    output?: string;
+    standard?: WcagStandard;
+}
+/**
+ * Main scan-storybook command
+ */
+export declare function scanStorybookCommand(options?: ScanStorybookOptions): Promise<AllyReport | null>;
+export default scanStorybookCommand;