ally-a11y 1.0.0

package/dist/utils/history-tracking.js

@@ -0,0 +1,230 @@
+/**
+ * Historical Tracking System
+ *
+ * Tracks scan history over time to show progress and trends.
+ * Quick win: 3 days effort, HIGH ROI - shows teams their improvement.
+ */
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+const HISTORY_FILE = '.ally/history.json';
+const MAX_ENTRIES = 100; // Keep last 100 scans
+/**
+ * Load history from file
+ */
+export async function loadHistory() {
+    if (!existsSync(HISTORY_FILE)) {
+        return {
+            entries: [],
+            firstScan: new Date().toISOString(),
+            lastScan: new Date().toISOString(),
+            totalScans: 0,
+        };
+    }
+    try {
+        const content = await readFile(HISTORY_FILE, 'utf-8');
+        const data = JSON.parse(content);
+        // Ensure entries is an array
+        if (!Array.isArray(data.entries)) {
+            data.entries = [];
+        }
+        return data;
+    }
+    catch {
+        return {
+            entries: [],
+            firstScan: new Date().toISOString(),
+            lastScan: new Date().toISOString(),
+            totalScans: 0,
+        };
+    }
+}
+/**
+ * Save history entry
+ */
+export async function saveHistoryEntry(report, command = 'scan') {
+    const history = await loadHistory();
+    // Get git info if available
+    let branch;
+    let commit;
+    try {
+        const { execSync } = await import('child_process');
+        branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf-8' }).trim();
+        commit = execSync('git rev-parse --short HEAD', { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        // Git not available or not a git repo
+    }
+    const entry = {
+        timestamp: report.scanDate,
+        score: report.summary.score,
+        totalViolations: report.summary.totalViolations,
+        bySeverity: report.summary.bySeverity,
+        filesScanned: report.totalFiles,
+        command,
+        branch,
+        commit,
+    };
+    history.entries.push(entry);
+    // Keep only last MAX_ENTRIES
+    if (history.entries.length > MAX_ENTRIES) {
+        history.entries = history.entries.slice(-MAX_ENTRIES);
+    }
+    // Update metadata
+    if (history.entries.length === 1) {
+        history.firstScan = entry.timestamp;
+    }
+    history.lastScan = entry.timestamp;
+    history.totalScans = history.entries.length;
+    // Ensure directory exists
+    const dir = resolve('.ally');
+    if (!existsSync(dir)) {
+        await mkdir(dir, { recursive: true });
+    }
+    // Save to file
+    await writeFile(HISTORY_FILE, JSON.stringify(history, null, 2), 'utf-8');
+}
+/**
+ * Get trend direction (improving, declining, stable)
+ */
+export function getTrend(history, lookback = 5) {
+    if (history.entries.length < 2) {
+        return 'stable';
+    }
+    const recentEntries = history.entries.slice(-lookback);
+    const scores = recentEntries.map(e => e.score);
+    // Calculate average of first half vs second half
+    const midpoint = Math.floor(scores.length / 2);
+    const firstHalf = scores.slice(0, midpoint);
+    const secondHalf = scores.slice(midpoint);
+    const avgFirst = firstHalf.reduce((a, b) => a + b, 0) / firstHalf.length;
+    const avgSecond = secondHalf.reduce((a, b) => a + b, 0) / secondHalf.length;
+    const diff = avgSecond - avgFirst;
+    if (diff > 2)
+        return 'improving';
+    if (diff < -2)
+        return 'declining';
+    return 'stable';
+}
+/**
+ * Get score change from previous scan
+ */
+export function getScoreChange(history) {
+    if (history.entries.length < 2) {
+        return null;
+    }
+    const latest = history.entries[history.entries.length - 1];
+    const previous = history.entries[history.entries.length - 2];
+    return latest.score - previous.score;
+}
+/**
+ * Get best score ever achieved
+ */
+export function getBestScore(history) {
+    if (history.entries.length === 0) {
+        return null;
+    }
+    return Math.max(...history.entries.map(e => e.score));
+}
+/**
+ * Get worst score ever recorded
+ */
+export function getWorstScore(history) {
+    if (history.entries.length === 0) {
+        return null;
+    }
+    return Math.min(...history.entries.map(e => e.score));
+}
+/**
+ * Get average score over time
+ */
+export function getAverageScore(history) {
+    if (history.entries.length === 0) {
+        return null;
+    }
+    const sum = history.entries.reduce((acc, e) => acc + e.score, 0);
+    return Math.round(sum / history.entries.length);
+}
+/**
+ * Get total violations fixed since first scan
+ */
+export function getTotalFixed(history) {
+    if (history.entries.length < 2) {
+        return null;
+    }
+    const first = history.entries[0];
+    const latest = history.entries[history.entries.length - 1];
+    return first.totalViolations - latest.totalViolations;
+}
+/**
+ * Get streak (consecutive scans with improving or stable scores)
+ */
+export function getStreak(history) {
+    if (history.entries.length < 2) {
+        return 0;
+    }
+    let streak = 0;
+    for (let i = history.entries.length - 1; i > 0; i--) {
+        const current = history.entries[i];
+        const previous = history.entries[i - 1];
+        if (current.score >= previous.score) {
+            streak++;
+        }
+        else {
+            break;
+        }
+    }
+    return streak;
+}
+/**
+ * Format time ago (e.g., "2 hours ago", "3 days ago")
+ */
+export function timeAgo(timestamp) {
+    const now = new Date();
+    const then = new Date(timestamp);
+    const diffMs = now.getTime() - then.getTime();
+    const seconds = Math.floor(diffMs / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0)
+        return `${days} day${days === 1 ? '' : 's'} ago`;
+    if (hours > 0)
+        return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+    if (minutes > 0)
+        return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+    return 'just now';
+}
+/**
+ * Get recent entries (last N scans)
+ */
+export function getRecentEntries(history, count = 10) {
+    return history.entries.slice(-count);
+}
+/**
+ * Get entries by branch
+ */
+export function getEntriesByBranch(history, branch) {
+    return history.entries.filter(e => e.branch === branch);
+}
+export function getStats(history) {
+    if (history.entries.length === 0) {
+        return null;
+    }
+    const latest = history.entries[history.entries.length - 1];
+    const previous = history.entries.length > 1 ? history.entries[history.entries.length - 2] : null;
+    return {
+        currentScore: latest.score,
+        previousScore: previous?.score ?? null,
+        scoreChange: getScoreChange(history),
+        trend: getTrend(history),
+        bestScore: getBestScore(history),
+        worstScore: getWorstScore(history),
+        averageScore: getAverageScore(history),
+        totalScans: history.totalScans,
+        totalFixed: getTotalFixed(history),
+        streak: getStreak(history),
+        lastScan: latest.timestamp,
+        firstScan: history.firstScan,
+    };
+}

package/dist/utils/history.d.ts

@@ -0,0 +1,42 @@
+/**
+ * History management utilities for tracking accessibility progress over time
+ */
+export interface HistoryEntry {
+    date: string;
+    score: number;
+    errors: number;
+    warnings: number;
+    filesScanned: number;
+}
+/**
+ * Save a new history entry
+ */
+export declare function saveHistoryEntry(projectPath: string, entry: HistoryEntry): Promise<void>;
+/**
+ * Load history entries (last N days by default)
+ */
+export declare function loadHistory(projectPath: string, days?: number): Promise<HistoryEntry[]>;
+/**
+ * Calculate trend information from history
+ */
+export interface TrendInfo {
+    lastWeekChange: number | null;
+    lastScanChange: number | null;
+    periodChange: number | null;
+    direction: 'up' | 'down' | 'stable';
+    periodDays: number;
+}
+export declare function calculateTrend(history: HistoryEntry[], currentScore: number): TrendInfo;
+/**
+ * Format trend string with arrow and color
+ */
+export declare function formatTrend(trend: TrendInfo): string;
+/**
+ * Render an ASCII chart of score history
+ * Uses block characters for a more polished look
+ */
+export declare function renderAsciiChart(history: HistoryEntry[], currentScore: number, width?: number, height?: number): string;
+/**
+ * Create a history entry from scan results
+ */
+export declare function createHistoryEntry(score: number, bySeverity: Record<string, number>, filesScanned: number): HistoryEntry;

package/dist/utils/history.js

@@ -0,0 +1,255 @@
+/**
+ * History management utilities for tracking accessibility progress over time
+ */
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import chalk from 'chalk';
+// Path to history file relative to project
+const HISTORY_FILE = 'history.json';
+const ALLY_DIR = '.ally';
+/**
+ * Get the path to the history file for a project
+ */
+function getHistoryPath(projectPath) {
+    return resolve(projectPath, ALLY_DIR, HISTORY_FILE);
+}
+/**
+ * Save a new history entry
+ */
+export async function saveHistoryEntry(projectPath, entry) {
+    const allyDir = resolve(projectPath, ALLY_DIR);
+    const historyPath = getHistoryPath(projectPath);
+    // Ensure .ally directory exists
+    if (!existsSync(allyDir)) {
+        await mkdir(allyDir, { recursive: true });
+    }
+    // Load existing history
+    let history = [];
+    if (existsSync(historyPath)) {
+        try {
+            const content = await readFile(historyPath, 'utf-8');
+            history = JSON.parse(content);
+        }
+        catch {
+            history = [];
+        }
+    }
+    // Add new entry (limit to last 90 days of entries)
+    history.push(entry);
+    if (history.length > 90) {
+        history = history.slice(-90);
+    }
+    await writeFile(historyPath, JSON.stringify(history, null, 2));
+}
+/**
+ * Load history entries (last N days by default)
+ */
+export async function loadHistory(projectPath, days = 30) {
+    const historyPath = getHistoryPath(projectPath);
+    if (!existsSync(historyPath)) {
+        return [];
+    }
+    try {
+        const content = await readFile(historyPath, 'utf-8');
+        const history = JSON.parse(content);
+        // Filter to last N days
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - days);
+        return history.filter(entry => new Date(entry.date) >= cutoff);
+    }
+    catch {
+        return [];
+    }
+}
+export function calculateTrend(history, currentScore) {
+    if (history.length === 0) {
+        return {
+            lastWeekChange: null,
+            lastScanChange: null,
+            periodChange: null,
+            direction: 'stable',
+            periodDays: 0,
+        };
+    }
+    // Change from last scan
+    const lastEntry = history[history.length - 1];
+    const lastScanChange = currentScore - lastEntry.score;
+    // Change from one week ago
+    const oneWeekAgo = new Date();
+    oneWeekAgo.setDate(oneWeekAgo.getDate() - 7);
+    const weekOldEntry = history.find(entry => new Date(entry.date) >= oneWeekAgo);
+    const lastWeekChange = weekOldEntry ? currentScore - weekOldEntry.score : null;
+    // Change over entire period
+    const firstEntry = history[0];
+    const periodChange = currentScore - firstEntry.score;
+    const firstDate = new Date(firstEntry.date);
+    const periodDays = Math.ceil((Date.now() - firstDate.getTime()) / (1000 * 60 * 60 * 24));
+    // Determine direction
+    let direction = 'stable';
+    if (lastScanChange > 0)
+        direction = 'up';
+    else if (lastScanChange < 0)
+        direction = 'down';
+    return {
+        lastWeekChange,
+        lastScanChange,
+        periodChange,
+        direction,
+        periodDays,
+    };
+}
+/**
+ * Format trend string with arrow and color
+ */
+export function formatTrend(trend) {
+    const lines = [];
+    if (trend.lastScanChange !== null && trend.lastScanChange !== 0) {
+        const arrow = trend.lastScanChange > 0 ? '\u2191' : '\u2193';
+        const sign = trend.lastScanChange > 0 ? '+' : '';
+        const color = trend.lastScanChange > 0 ? chalk.green : chalk.red;
+        lines.push(color(`${arrow} ${sign}${trend.lastScanChange} from last scan`));
+    }
+    if (trend.lastWeekChange !== null && trend.lastWeekChange !== 0) {
+        const arrow = trend.lastWeekChange > 0 ? '\u2191' : '\u2193';
+        const sign = trend.lastWeekChange > 0 ? '+' : '';
+        const color = trend.lastWeekChange > 0 ? chalk.green : chalk.red;
+        lines.push(color(`${arrow} ${sign}${trend.lastWeekChange} from last week`));
+    }
+    if (trend.periodChange !== null && trend.periodDays > 7 && trend.periodChange !== 0) {
+        const arrow = trend.periodChange > 0 ? '\u2191' : '\u2193';
+        const sign = trend.periodChange > 0 ? '+' : '';
+        const color = trend.periodChange > 0 ? chalk.green : chalk.red;
+        lines.push(color(`${arrow} ${sign}${trend.periodChange} points over ${trend.periodDays} days`));
+    }
+    return lines.join('\n');
+}
+/**
+ * Render an ASCII chart of score history
+ * Uses block characters for a more polished look
+ */
+export function renderAsciiChart(history, currentScore, width = 50, height = 8) {
+    if (history.length === 0) {
+        return chalk.dim('  No history data available yet.');
+    }
+    // Include current score in the data
+    const scores = [...history.map(h => h.score), currentScore];
+    const dates = [...history.map(h => h.date), new Date().toISOString()];
+    // Calculate min/max for scaling
+    const minScore = Math.min(...scores, 0);
+    const maxScore = Math.max(...scores, 100);
+    const range = maxScore - minScore || 1;
+    // Y-axis labels
+    const yAxisWidth = 4;
+    const chartWidth = width - yAxisWidth - 1;
+    // Sample data points to fit chart width
+    const step = Math.max(1, Math.floor(scores.length / chartWidth));
+    const sampledScores = [];
+    const sampledDates = [];
+    for (let i = 0; i < scores.length; i += step) {
+        sampledScores.push(scores[i]);
+        sampledDates.push(dates[i]);
+    }
+    // Ensure we include the last point
+    if (sampledScores[sampledScores.length - 1] !== scores[scores.length - 1]) {
+        sampledScores.push(scores[scores.length - 1]);
+        sampledDates.push(dates[dates.length - 1]);
+    }
+    const lines = [];
+    // Header
+    lines.push(chalk.bold.cyan('Score History (last 30 days):'));
+    lines.push('');
+    // Chart area - build from top to bottom
+    for (let row = height - 1; row >= 0; row--) {
+        const threshold = minScore + (range * (row + 1) / height);
+        const prevThreshold = minScore + (range * row / height);
+        // Y-axis label (only show a few)
+        let yLabel = '';
+        if (row === height - 1) {
+            yLabel = maxScore.toString().padStart(yAxisWidth - 1) + '\u2502';
+        }
+        else if (row === 0) {
+            yLabel = minScore.toString().padStart(yAxisWidth - 1) + '\u2502';
+        }
+        else if (row === Math.floor(height / 2)) {
+            const midVal = Math.round((minScore + maxScore) / 2);
+            yLabel = midVal.toString().padStart(yAxisWidth - 1) + '\u2502';
+        }
+        else {
+            yLabel = ' '.repeat(yAxisWidth - 1) + '\u2502';
+        }
+        // Chart line
+        let chartLine = '';
+        for (let col = 0; col < sampledScores.length; col++) {
+            const score = sampledScores[col];
+            if (score >= threshold) {
+                // Full block
+                chartLine += getBlockChar(score, true);
+            }
+            else if (score > prevThreshold) {
+                // Partial block (top)
+                chartLine += getBlockChar(score, false);
+            }
+            else {
+                // Empty
+                chartLine += ' ';
+            }
+        }
+        lines.push(yLabel + chartLine);
+    }
+    // X-axis
+    const xAxisLine = ' '.repeat(yAxisWidth - 1) + '\u2514' + '\u2500'.repeat(sampledScores.length);
+    lines.push(xAxisLine);
+    // X-axis labels (dates)
+    if (sampledDates.length > 0) {
+        const firstDate = formatDateShort(sampledDates[0]);
+        const lastDate = formatDateShort(sampledDates[sampledDates.length - 1]);
+        const midIdx = Math.floor(sampledDates.length / 2);
+        const midDate = sampledDates[midIdx] ? formatDateShort(sampledDates[midIdx]) : '';
+        // Calculate positions
+        const spacing = sampledScores.length - firstDate.length - lastDate.length;
+        let dateLabel = ' '.repeat(yAxisWidth) + firstDate;
+        if (spacing > midDate.length + 4) {
+            // Add middle date
+            const midPos = Math.floor(sampledScores.length / 2) - Math.floor(midDate.length / 2);
+            const leftPad = midPos - firstDate.length;
+            const rightPad = sampledScores.length - midPos - midDate.length - lastDate.length;
+            dateLabel = ' '.repeat(yAxisWidth) + firstDate + ' '.repeat(Math.max(1, leftPad)) + midDate + ' '.repeat(Math.max(1, rightPad)) + lastDate;
+        }
+        else {
+            dateLabel = ' '.repeat(yAxisWidth) + firstDate + ' '.repeat(Math.max(1, spacing)) + lastDate;
+        }
+        lines.push(chalk.dim(dateLabel));
+    }
+    return lines.join('\n');
+}
+/**
+ * Get block character for chart based on score
+ */
+function getBlockChar(score, full) {
+    const color = score >= 75 ? chalk.green
+        : score >= 50 ? chalk.yellow
+            : chalk.red;
+    // Use full or partial blocks
+    return color(full ? '\u2588' : '\u2584');
+}
+/**
+ * Format date for X-axis labels
+ */
+function formatDateShort(isoDate) {
+    const date = new Date(isoDate);
+    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    return `${months[date.getMonth()]} ${date.getDate()}`;
+}
+/**
+ * Create a history entry from scan results
+ */
+export function createHistoryEntry(score, bySeverity, filesScanned) {
+    return {
+        date: new Date().toISOString(),
+        score,
+        errors: (bySeverity.critical ?? 0) + (bySeverity.serious ?? 0),
+        warnings: (bySeverity.moderate ?? 0) + (bySeverity.minor ?? 0),
+        filesScanned,
+    };
+}

package/dist/utils/impact-scores.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Impact Scoring System
+ *
+ * Scores accessibility violations by real-world user impact and business cost.
+ * Research shows developers are overwhelmed by violations - impact scoring
+ * helps prioritize what actually matters.
+ */
+import type { Violation } from '../types/index.js';
+export interface ImpactScore {
+    score: number;
+    reasoning: string;
+    affectedUsers: string[];
+    businessImpact: 'critical' | 'high' | 'medium' | 'low';
+    estimatedUsers: string;
+    wcagLevel: 'A' | 'AA' | 'AAA';
+}
+export interface PageContext {
+    pageType?: 'landing' | 'checkout' | 'form' | 'content' | 'navigation' | 'dashboard';
+    hasForm?: boolean;
+    hasCheckout?: boolean;
+    isNavigation?: boolean;
+}
+/**
+ * Detect page context from HTML content
+ */
+export declare function detectPageContext(html: string): PageContext;
+/**
+ * Calculate impact score for a violation
+ */
+export declare function calculateImpactScore(violation: Violation, context?: PageContext): ImpactScore;
+/**
+ * Sort violations by impact score (highest first)
+ */
+export declare function sortByImpact(violations: Violation[], context?: PageContext): Array<{
+    violation: Violation;
+    impact: ImpactScore;
+}>;
+/**
+ * Group violations by impact category
+ */
+export declare function groupByImpact(violations: Violation[], context?: PageContext): Record<string, Array<{
+    violation: Violation;
+    impact: ImpactScore;
+}>>;