ally-a11y 1.0.0

package/dist/commands/health.js

@@ -0,0 +1,367 @@
+/**
+ * ally health command - Quick accessibility overview like npm audit
+ */
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import chalk from 'chalk';
+import boxen from 'boxen';
+import { printBanner, createSpinner, printError, printInfo, } from '../utils/ui.js';
+import { AccessibilityScanner, findHtmlFiles, createReport, DEFAULT_STANDARD, DEFAULT_TIMEOUT, DEFAULT_BATCH_SIZE, } from '../utils/scanner.js';
+import { loadConfig, loadIgnorePatterns } from '../utils/config.js';
+const CATEGORY_CONFIG = {
+    'html-structure': {
+        name: 'HTML Structure',
+        icon: '1',
+        patterns: [
+            /^heading-order$/,
+            /^document-title$/,
+            /^html-has-lang$/,
+            /^html-lang-valid$/,
+            /^bypass$/,
+            /^landmark-/,
+            /^region$/,
+            /^page-has-heading-one$/,
+            /^meta-viewport$/,
+            /^frame-title$/,
+            /^valid-lang$/,
+        ],
+    },
+    'color-contrast': {
+        name: 'Color Contrast',
+        icon: '2',
+        patterns: [
+            /^color-contrast/,
+            /^link-in-text-block$/,
+        ],
+    },
+    'keyboard-nav': {
+        name: 'Keyboard Nav',
+        icon: '3',
+        patterns: [
+            /^tabindex$/,
+            /^focus-/,
+            /^scrollable-region-focusable$/,
+            /^accesskey/,
+            /^skip-link$/,
+        ],
+    },
+    'aria-usage': {
+        name: 'ARIA Usage',
+        icon: '4',
+        patterns: [
+            /^aria-/,
+            /^role-/,
+        ],
+    },
+    'forms': {
+        name: 'Forms',
+        icon: '5',
+        patterns: [
+            /^label$/,
+            /^label-/,
+            /^autocomplete-valid$/,
+            /^input-/,
+            /^select-/,
+            /^form-field-multiple-labels$/,
+        ],
+    },
+    'images': {
+        name: 'Images',
+        icon: '6',
+        patterns: [
+            /^image-alt$/,
+            /^svg-img-alt$/,
+            /^image-redundant-alt$/,
+            /^object-alt$/,
+            /^area-alt$/,
+        ],
+    },
+};
+/**
+ * Severity penalty points
+ */
+const SEVERITY_PENALTY = {
+    critical: 25,
+    serious: 15,
+    moderate: 10,
+    minor: 5,
+};
+/**
+ * Determine which category a violation belongs to based on its ID
+ */
+function categorizeViolation(violationId) {
+    for (const [category, config] of Object.entries(CATEGORY_CONFIG)) {
+        for (const pattern of config.patterns) {
+            if (pattern.test(violationId)) {
+                return category;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Calculate scores by category from violations
+ */
+function calculateCategoryScores(violations) {
+    // Initialize category data
+    const categoryData = {
+        'html-structure': { penalty: 0, violations: 0 },
+        'color-contrast': { penalty: 0, violations: 0 },
+        'keyboard-nav': { penalty: 0, violations: 0 },
+        'aria-usage': { penalty: 0, violations: 0 },
+        'forms': { penalty: 0, violations: 0 },
+        'images': { penalty: 0, violations: 0 },
+    };
+    // Process each violation
+    for (const violation of violations) {
+        const category = categorizeViolation(violation.id);
+        if (category) {
+            const penalty = SEVERITY_PENALTY[violation.impact] || 5;
+            // Count each node instance, capped at 10 per violation
+            const nodeCount = Math.min(violation.nodes.length, 10);
+            categoryData[category].penalty += penalty * nodeCount;
+            categoryData[category].violations += nodeCount;
+        }
+    }
+    // Convert to scores
+    const categoryOrder = ['html-structure', 'color-contrast', 'keyboard-nav', 'aria-usage', 'forms', 'images'];
+    return categoryOrder.map((category) => {
+        const config = CATEGORY_CONFIG[category];
+        const data = categoryData[category];
+        // Score starts at 100, subtract penalties, minimum 0
+        const score = Math.max(0, 100 - Math.min(data.penalty, 100));
+        return {
+            category,
+            name: config.name,
+            score: Math.round(score),
+            violations: data.violations,
+            icon: config.icon,
+        };
+    });
+}
+/**
+ * Get score label based on value
+ */
+function getScoreLabel(score) {
+    if (score >= 90)
+        return 'Excellent';
+    if (score >= 75)
+        return 'Good';
+    if (score >= 50)
+        return 'Needs Work';
+    return 'Poor';
+}
+/**
+ * Get score icon based on value
+ */
+function getScoreIcon(score) {
+    if (score >= 75)
+        return chalk.green('\u2713'); // checkmark
+    if (score >= 50)
+        return chalk.yellow('\u26A0'); // warning
+    return chalk.red('\u2717'); // x mark
+}
+/**
+ * Generate top recommendations from violations
+ */
+function generateRecommendations(violations, categoryScores) {
+    // Group violations by category and count
+    const categoryViolations = new Map();
+    for (const violation of violations) {
+        const category = categorizeViolation(violation.id);
+        if (!category)
+            continue;
+        if (!categoryViolations.has(category)) {
+            categoryViolations.set(category, new Map());
+        }
+        const catMap = categoryViolations.get(category);
+        const existing = catMap.get(violation.id);
+        const nodeCount = violation.nodes.length;
+        if (existing) {
+            existing.count += nodeCount;
+        }
+        else {
+            catMap.set(violation.id, { count: nodeCount, description: violation.help });
+        }
+    }
+    // Sort categories by score (lowest first) to prioritize recommendations
+    const sortedCategories = [...categoryScores].sort((a, b) => a.score - b.score);
+    const recommendations = [];
+    for (const catScore of sortedCategories) {
+        if (catScore.score >= 90)
+            continue; // Skip excellent categories
+        const catViolations = categoryViolations.get(catScore.category);
+        if (!catViolations)
+            continue;
+        // Get the most common violation in this category
+        let topViolation = null;
+        for (const [id, data] of catViolations.entries()) {
+            if (!topViolation || data.count > topViolation.count) {
+                topViolation = { id, count: data.count, description: data.description };
+            }
+        }
+        if (topViolation) {
+            recommendations.push({
+                message: `Fix ${topViolation.count} ${topViolation.description.toLowerCase()}`,
+                category: catScore.category,
+                count: topViolation.count,
+            });
+        }
+        if (recommendations.length >= 3)
+            break; // Limit to 3 recommendations
+    }
+    return recommendations;
+}
+/**
+ * Get the lowest scoring category for the fix command suggestion
+ */
+function getWorstCategory(categoryScores) {
+    let worst = categoryScores[0];
+    for (const score of categoryScores) {
+        if (score.score < worst.score) {
+            worst = score;
+        }
+    }
+    return worst.category;
+}
+/**
+ * Render the health check box
+ */
+function renderHealthBox(overallScore, categoryScores, recommendations) {
+    const boxWidth = 48;
+    const scoreLabel = getScoreLabel(overallScore);
+    const scoreColor = overallScore >= 75 ? chalk.green : overallScore >= 50 ? chalk.yellow : chalk.red;
+    // Build content lines
+    const lines = [];
+    // Header
+    lines.push(chalk.bold('  Accessibility Health Check'));
+    lines.push('');
+    // Overall score
+    lines.push(`  Overall Score: ${scoreColor.bold(`${overallScore}/100`)} (${scoreLabel})`);
+    lines.push('');
+    // Category scores
+    for (const cat of categoryScores) {
+        const icon = getScoreIcon(cat.score);
+        const nameWidth = 18;
+        const paddedName = cat.name.padEnd(nameWidth);
+        const scoreStr = `${cat.score}/100`;
+        lines.push(`  ${icon} ${paddedName} ${chalk.dim('|')} ${scoreStr}`);
+    }
+    lines.push('');
+    // Recommendations
+    if (recommendations.length > 0) {
+        lines.push(chalk.bold('  Top Recommendations:'));
+        recommendations.forEach((rec, i) => {
+            lines.push(`  ${i + 1}. ${rec.message}`);
+        });
+        lines.push('');
+    }
+    // Fix command suggestion
+    const worstCategory = getWorstCategory(categoryScores);
+    lines.push(chalk.dim(`  Run: ally fix --category ${worstCategory}`));
+    return lines.join('\n');
+}
+export async function healthCommand(options = {}) {
+    printBanner();
+    const { path: targetPath = '.', standard = DEFAULT_STANDARD, input, } = options;
+    let report = null;
+    // Check if we should use existing scan results
+    if (input) {
+        const inputPath = resolve(input);
+        if (!existsSync(inputPath)) {
+            printError(`Input file not found: ${input}`);
+            return;
+        }
+        const spinner = createSpinner('Loading scan results...');
+        spinner.start();
+        try {
+            const content = await readFile(inputPath, 'utf-8');
+            report = JSON.parse(content);
+            spinner.succeed('Loaded existing scan results');
+        }
+        catch (error) {
+            spinner.fail('Failed to load scan results');
+            printError(error instanceof Error ? error.message : String(error));
+            return;
+        }
+    }
+    else {
+        // Check for existing .ally/scan.json
+        const defaultScanPath = resolve(targetPath, '.ally', 'scan.json');
+        if (existsSync(defaultScanPath)) {
+            const spinner = createSpinner('Loading existing scan results...');
+            spinner.start();
+            try {
+                const content = await readFile(defaultScanPath, 'utf-8');
+                report = JSON.parse(content);
+                spinner.succeed('Using existing scan from .ally/scan.json');
+                printInfo('Run `ally scan` to update results');
+            }
+            catch {
+                // Fall through to new scan
+            }
+        }
+        // If no existing results, run a scan
+        if (!report) {
+            const spinner = createSpinner('Scanning project for accessibility issues...');
+            spinner.start();
+            try {
+                // Load config
+                const { config } = await loadConfig();
+                const { patterns: ignorePatterns } = await loadIgnorePatterns();
+                const allIgnorePatterns = [...ignorePatterns, ...(config.scan?.ignore ?? [])];
+                // Find HTML files
+                const absolutePath = resolve(targetPath);
+                const htmlFiles = await findHtmlFiles(absolutePath, allIgnorePatterns);
+                if (htmlFiles.length === 0) {
+                    spinner.fail('No HTML files found');
+                    printInfo('Use `ally scan --url <url>` to scan a live URL');
+                    return;
+                }
+                spinner.text = `Scanning ${htmlFiles.length} files...`;
+                // Scan files
+                const scanner = new AccessibilityScanner(DEFAULT_TIMEOUT);
+                await scanner.init();
+                try {
+                    const { results } = await scanner.scanHtmlFilesParallel(htmlFiles, standard, DEFAULT_BATCH_SIZE);
+                    report = createReport(results);
+                    spinner.succeed(`Scanned ${results.length} files`);
+                }
+                finally {
+                    await scanner.close();
+                }
+            }
+            catch (error) {
+                spinner.fail('Scan failed');
+                printError(error instanceof Error ? error.message : String(error));
+                return;
+            }
+        }
+    }
+    if (!report) {
+        printError('No scan results available');
+        return;
+    }
+    // Collect all violations from the report
+    const allViolations = [];
+    for (const result of report.results) {
+        allViolations.push(...result.violations);
+    }
+    // Calculate category scores
+    const categoryScores = calculateCategoryScores(allViolations);
+    // Calculate overall score (average of category scores)
+    const overallScore = Math.round(categoryScores.reduce((sum, cat) => sum + cat.score, 0) / categoryScores.length);
+    // Generate recommendations
+    const recommendations = generateRecommendations(allViolations, categoryScores);
+    // Render the health box
+    const content = renderHealthBox(overallScore, categoryScores, recommendations);
+    const borderColor = overallScore >= 75 ? 'green' : overallScore >= 50 ? 'yellow' : 'red';
+    console.log(boxen(content, {
+        padding: { top: 1, bottom: 1, left: 0, right: 0 },
+        borderStyle: 'round',
+        borderColor,
+    }));
+    console.log();
+}
+export default healthCommand;

package/dist/commands/history.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ally history command - View scan history and progress
+ */
+interface HistoryCommandOptions {
+    limit?: number;
+    branch?: string;
+    verbose?: boolean;
+}
+export declare function historyCommand(options?: HistoryCommandOptions): Promise<void>;
+export {};

package/dist/commands/history.js

@@ -0,0 +1,191 @@
+/**
+ * ally history command - View scan history and progress
+ */
+import chalk from 'chalk';
+import boxen from 'boxen';
+import { loadHistory, getStats, timeAgo, } from '../utils/history-tracking.js';
+import { printError, printInfo } from '../utils/ui.js';
+/**
+ * Display a single history entry
+ */
+function printEntry(entry, index, total) {
+    const num = total - index;
+    const scoreColor = entry.score >= 90 ? chalk.green :
+        entry.score >= 75 ? chalk.yellow :
+            entry.score >= 50 ? chalk.yellow.dim :
+                chalk.red;
+    const branchInfo = entry.branch ? chalk.dim(` [${entry.branch}`) + (entry.commit ? chalk.dim(`@${entry.commit}]`) : chalk.dim(']')) : '';
+    console.log(chalk.dim(`#${num}`) +
+        ' ' +
+        chalk.cyan(timeAgo(entry.timestamp)) +
+        ' ' +
+        scoreColor(`${entry.score}/100`) +
+        ' ' +
+        chalk.dim(`(${entry.totalViolations} issues, ${entry.filesScanned} files)`) +
+        branchInfo);
+}
+/**
+ * Display stats summary
+ */
+function printStats(stats) {
+    const scoreColor = stats.currentScore >= 90 ? chalk.green.bold :
+        stats.currentScore >= 75 ? chalk.yellow.bold :
+            stats.currentScore >= 50 ? chalk.yellow :
+                chalk.red.bold;
+    const trendIcon = stats.trend === 'improving' ? chalk.green('↗ improving') :
+        stats.trend === 'declining' ? chalk.red('↘ declining') :
+            chalk.blue('→ stable');
+    const changeText = stats.scoreChange !== null
+        ? stats.scoreChange > 0
+            ? chalk.green(`+${stats.scoreChange}`)
+            : stats.scoreChange < 0
+                ? chalk.red(`${stats.scoreChange}`)
+                : chalk.dim('no change')
+        : chalk.dim('first scan');
+    const fixedText = stats.totalFixed !== null
+        ? stats.totalFixed > 0
+            ? chalk.green(`${stats.totalFixed} fixed`)
+            : stats.totalFixed < 0
+                ? chalk.red(`${Math.abs(stats.totalFixed)} added`)
+                : chalk.dim('no change')
+        : chalk.dim('no data');
+    const streakText = stats.streak > 0
+        ? chalk.green(`${stats.streak} scan${stats.streak === 1 ? '' : 's'}`)
+        : chalk.dim('0 scans');
+    const summary = `
+${chalk.bold('Current Score:')} ${scoreColor(stats.currentScore.toString())}${chalk.dim('/100')} ${changeText}
+
+${chalk.bold('Trend:')} ${trendIcon}
+${chalk.bold('Streak:')} ${streakText} improving/stable
+
+${chalk.bold('Statistics:')}
+  Best:    ${chalk.green(stats.bestScore?.toString() ?? 'N/A')}${stats.bestScore ? '/100' : ''}
+  Average: ${chalk.yellow(stats.averageScore?.toString() ?? 'N/A')}${stats.averageScore ? '/100' : ''}
+  Worst:   ${chalk.red(stats.worstScore?.toString() ?? 'N/A')}${stats.worstScore ? '/100' : ''}
+
+${chalk.bold('Progress:')}
+  Total scans: ${chalk.cyan(stats.totalScans.toString())}
+  Issues fixed: ${fixedText}
+  First scan: ${chalk.dim(timeAgo(stats.firstScan))}
+  Last scan: ${chalk.dim(timeAgo(stats.lastScan))}
+`;
+    console.log(boxen(summary.trim(), {
+        padding: 1,
+        margin: 1,
+        borderStyle: 'round',
+        borderColor: stats.currentScore >= 75 ? 'green' : stats.currentScore >= 50 ? 'yellow' : 'red',
+        title: '📊 Accessibility Progress',
+        titleAlignment: 'center',
+    }));
+}
+/**
+ * Create ASCII sparkline from scores
+ */
+function createSparkline(entries, width = 50) {
+    if (entries.length === 0)
+        return '';
+    const scores = entries.map(e => e.score);
+    const min = Math.min(...scores);
+    const max = Math.max(...scores);
+    const range = max - min || 1;
+    const bars = '▁▂▃▄▅▆▇█';
+    // Sample scores to fit width
+    const step = Math.max(1, Math.ceil(scores.length / width));
+    const sampledScores = [];
+    for (let i = 0; i < scores.length; i += step) {
+        sampledScores.push(scores[i]);
+    }
+    return sampledScores
+        .map(score => {
+        const normalized = (score - min) / range;
+        const index = Math.min(bars.length - 1, Math.floor(normalized * bars.length));
+        const char = bars[index];
+        // Color based on score
+        if (score >= 90)
+            return chalk.green(char);
+        if (score >= 75)
+            return chalk.yellow(char);
+        if (score >= 50)
+            return chalk.yellow.dim(char);
+        return chalk.red(char);
+    })
+        .join('');
+}
+export async function historyCommand(options = {}) {
+    const { limit = 10, branch, verbose = false } = options;
+    // Load history
+    const history = await loadHistory();
+    if (history.entries.length === 0) {
+        printInfo('No scan history yet. Run `ally scan` to start tracking progress.');
+        return;
+    }
+    // Get stats
+    const stats = getStats(history);
+    if (!stats) {
+        printError('Unable to calculate statistics');
+        return;
+    }
+    // Print stats summary
+    printStats(stats);
+    // Filter by branch if requested
+    let entries = history.entries;
+    if (branch) {
+        entries = entries.filter(e => e.branch === branch);
+        if (entries.length === 0) {
+            printError(`No scans found for branch: ${branch}`);
+            return;
+        }
+        printInfo(`Showing scans for branch: ${branch}`);
+    }
+    // Print sparkline
+    if (entries.length > 1) {
+        console.log();
+        console.log(chalk.bold('Score History:'));
+        console.log(createSparkline(entries));
+        console.log(chalk.dim(`${entries[0].score}${' '.repeat(42)}${entries[entries.length - 1].score}`));
+        console.log();
+    }
+    // Print recent entries
+    console.log(chalk.bold(`Recent Scans (last ${Math.min(limit, entries.length)}):`));
+    console.log();
+    const recentEntries = entries.slice(-limit).reverse();
+    recentEntries.forEach((entry, index) => {
+        printEntry(entry, index, entries.length);
+    });
+    // Motivational message
+    console.log();
+    const motivation = getMotivationalMessage(stats);
+    if (motivation) {
+        console.log(chalk.cyan('💡 ' + motivation));
+    }
+}
+/**
+ * Get motivational message based on stats
+ */
+function getMotivationalMessage(stats) {
+    if (stats.currentScore === 100) {
+        return 'Perfect score! Your site is fully accessible. 🎉';
+    }
+    if (stats.trend === 'improving' && stats.streak >= 3) {
+        return `Great momentum! You've improved for ${stats.streak} consecutive scans. Keep it up!`;
+    }
+    if (stats.trend === 'improving') {
+        return 'You\'re on the right track! Keep fixing those issues.';
+    }
+    if (stats.trend === 'declining') {
+        return 'Score is declining. Time to address those new violations!';
+    }
+    if (stats.totalFixed && stats.totalFixed > 10) {
+        return `Awesome! You've fixed ${stats.totalFixed} violations since starting.`;
+    }
+    if (stats.currentScore >= 90) {
+        return 'Almost perfect! Just a few more fixes to go.';
+    }
+    if (stats.currentScore >= 75) {
+        return 'Good accessibility! Focus on critical and serious issues.';
+    }
+    if (stats.currentScore >= 50) {
+        return 'Making progress! Prioritize high-impact violations first.';
+    }
+    return 'Start by fixing critical violations - they block the most users.';
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ally init command - Sets up ally configuration in a project
+ */
+interface InitOptions {
+    force?: boolean;
+    hooks?: boolean;
+}
+export declare function initCommand(options?: InitOptions): Promise<void>;
+export default initCommand;