ally-a11y 1.0.0

package/dist/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * Core types for Ally accessibility scanner
+ */
+export {};

package/dist/utils/baseline.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Baseline management for tracking accessibility improvements and detecting regressions
+ */
+import type { AllyReport } from '../types/index.js';
+interface BaselineData {
+    timestamp: string;
+    scores: Record<string, number>;
+    violations: Record<string, number>;
+    summary: {
+        totalViolations: number;
+        criticalCount: number;
+        seriousCount: number;
+        moderateCount: number;
+        minorCount: number;
+    };
+}
+interface RegressionAnalysis {
+    improved: number;
+    regressed: number;
+    unchanged: number;
+    improvementPercentage: number;
+    regressionPercentage: number;
+    details: {
+        newViolations: Array<{
+            file: string;
+            count: number;
+        }>;
+        fixedViolations: Array<{
+            file: string;
+            count: number;
+        }>;
+    };
+}
+/**
+ * Convert report to baseline data for comparison
+ */
+export declare function reportToBaseline(report: AllyReport): BaselineData;
+/**
+ * Save baseline from a report
+ */
+export declare function saveBaseline(report: AllyReport, baselineDir?: string): Promise<void>;
+/**
+ * Load baseline data
+ */
+export declare function loadBaseline(baselineDir?: string): Promise<BaselineData | null>;
+/**
+ * Compare current report against baseline, detecting improvements and regressions
+ */
+export declare function compareWithBaseline(currentReport: AllyReport, baseline: BaselineData): RegressionAnalysis;
+/**
+ * Check if baseline exists
+ */
+export declare function hasBaseline(baselineDir?: string): Promise<boolean>;
+/**
+ * Delete baseline
+ */
+export declare function deleteBaseline(baselineDir?: string): Promise<void>;
+/**
+ * Format regression analysis for display
+ */
+export declare function formatRegression(analysis: RegressionAnalysis): string;
+export {};

package/dist/utils/baseline.js

@@ -0,0 +1,169 @@
+/**
+ * Baseline management for tracking accessibility improvements and detecting regressions
+ */
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+const BASELINE_DIR = '.ally';
+const BASELINE_FILE = resolve(BASELINE_DIR, 'baseline.json');
+/**
+ * Convert report to baseline data for comparison
+ */
+export function reportToBaseline(report) {
+    const scores = {};
+    const violations = {};
+    for (const result of report.results) {
+        const fileKey = result.file || result.url || 'unknown';
+        violations[fileKey] = result.violations.length;
+        // Score based on violations (100 - violations * 10)
+        scores[fileKey] = Math.max(0, 100 - result.violations.length * 10);
+    }
+    return {
+        timestamp: new Date().toISOString(),
+        scores,
+        violations,
+        summary: {
+            totalViolations: report.summary.totalViolations,
+            criticalCount: report.summary.bySeverity.critical ?? 0,
+            seriousCount: report.summary.bySeverity.serious ?? 0,
+            moderateCount: report.summary.bySeverity.moderate ?? 0,
+            minorCount: report.summary.bySeverity.minor ?? 0,
+        },
+    };
+}
+/**
+ * Save baseline from a report
+ */
+export async function saveBaseline(report, baselineDir = BASELINE_DIR) {
+    const baseline = reportToBaseline(report);
+    const filePath = resolve(baselineDir, 'baseline.json');
+    // Ensure directory exists
+    if (!existsSync(baselineDir)) {
+        await mkdir(baselineDir, { recursive: true });
+    }
+    await writeFile(filePath, JSON.stringify(baseline, null, 2));
+}
+/**
+ * Load baseline data
+ */
+export async function loadBaseline(baselineDir = BASELINE_DIR) {
+    const filePath = resolve(baselineDir, 'baseline.json');
+    try {
+        if (!existsSync(filePath)) {
+            return null;
+        }
+        const data = await readFile(filePath, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch (error) {
+        console.error('Failed to load baseline:', error);
+        return null;
+    }
+}
+/**
+ * Compare current report against baseline, detecting improvements and regressions
+ */
+export function compareWithBaseline(currentReport, baseline) {
+    const currentBaseline = reportToBaseline(currentReport);
+    let improved = 0;
+    let regressed = 0;
+    let unchanged = 0;
+    const newViolations = [];
+    const fixedViolations = [];
+    // Check each file in current baseline
+    for (const [file, currentViolationCount] of Object.entries(currentBaseline.violations)) {
+        const previousViolationCount = baseline.violations[file] ?? 0;
+        if (currentViolationCount < previousViolationCount) {
+            improved++;
+            const fixed = previousViolationCount - currentViolationCount;
+            fixedViolations.push({ file, count: fixed });
+        }
+        else if (currentViolationCount > previousViolationCount) {
+            regressed++;
+            const added = currentViolationCount - previousViolationCount;
+            newViolations.push({ file, count: added });
+        }
+        else {
+            unchanged++;
+        }
+    }
+    // Check for newly scanned files (files not in baseline)
+    for (const [file, currentViolationCount] of Object.entries(currentBaseline.violations)) {
+        if (!(file in baseline.violations)) {
+            regressed++;
+            newViolations.push({ file, count: currentViolationCount });
+        }
+    }
+    const totalFiles = Object.keys(currentBaseline.violations).length;
+    const improvementPercentage = totalFiles > 0 ? (improved / totalFiles) * 100 : 0;
+    const regressionPercentage = totalFiles > 0 ? (regressed / totalFiles) * 100 : 0;
+    return {
+        improved,
+        regressed,
+        unchanged,
+        improvementPercentage,
+        regressionPercentage,
+        details: {
+            newViolations,
+            fixedViolations,
+        },
+    };
+}
+/**
+ * Check if baseline exists
+ */
+export async function hasBaseline(baselineDir = BASELINE_DIR) {
+    const filePath = resolve(baselineDir, 'baseline.json');
+    return existsSync(filePath);
+}
+/**
+ * Delete baseline
+ */
+export async function deleteBaseline(baselineDir = BASELINE_DIR) {
+    const filePath = resolve(baselineDir, 'baseline.json');
+    if (existsSync(filePath)) {
+        // Can't use unlink here without importing fs, so we'll just overwrite with empty
+        // This is a placeholder - actual delete would be in the delete command
+        console.log(`Baseline can be deleted by removing ${filePath}`);
+    }
+}
+/**
+ * Format regression analysis for display
+ */
+export function formatRegression(analysis) {
+    const lines = [];
+    lines.push('');
+    lines.push('📊 Regression Analysis');
+    lines.push('─'.repeat(50));
+    if (analysis.improved > 0) {
+        lines.push(`✅ Fixed:      ${analysis.improved} file${analysis.improved === 1 ? '' : 's'} (${analysis.improvementPercentage.toFixed(1)}%)`);
+    }
+    if (analysis.regressed > 0) {
+        lines.push(`⚠️  Regressed:  ${analysis.regressed} file${analysis.regressed === 1 ? '' : 's'} (${analysis.regressionPercentage.toFixed(1)}%)`);
+    }
+    if (analysis.unchanged > 0) {
+        lines.push(`➖ Unchanged:  ${analysis.unchanged} file${analysis.unchanged === 1 ? '' : 's'}`);
+    }
+    if (analysis.details.fixedViolations.length > 0) {
+        lines.push('');
+        lines.push('✨ Issues Fixed:');
+        for (const { file, count } of analysis.details.fixedViolations.slice(0, 5)) {
+            lines.push(`   ${file}: -${count} issue${count === 1 ? '' : 's'}`);
+        }
+        if (analysis.details.fixedViolations.length > 5) {
+            lines.push(`   ... and ${analysis.details.fixedViolations.length - 5} more`);
+        }
+    }
+    if (analysis.details.newViolations.length > 0) {
+        lines.push('');
+        lines.push('⚠️  New Issues:');
+        for (const { file, count } of analysis.details.newViolations.slice(0, 5)) {
+            lines.push(`   ${file}: +${count} issue${count === 1 ? '' : 's'}`);
+        }
+        if (analysis.details.newViolations.length > 5) {
+            lines.push(`   ... and ${analysis.details.newViolations.length - 5} more`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/utils/browser.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Browser abstraction layer for cross-browser accessibility testing
+ *
+ * Supports Puppeteer (default, always available) and Playwright (optional, for Firefox/WebKit)
+ */
+export type BrowserType = 'chromium' | 'firefox' | 'webkit';
+/**
+ * Abstract page interface for browser-agnostic operations
+ */
+export interface PageAdapter {
+    goto(url: string, options?: {
+        waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+        timeout?: number;
+    }): Promise<void>;
+    setContent(html: string, options?: {
+        waitUntil?: 'load' | 'domcontentloaded';
+    }): Promise<void>;
+    content(): Promise<string>;
+    waitForSelector(selector: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    evaluate<T>(fn: () => T): Promise<T>;
+    addStyleTag(options: {
+        content: string;
+    }): Promise<void>;
+    setViewport(viewport: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    screenshot(options: {
+        path: string;
+        fullPage?: boolean;
+    }): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Get the underlying page object for axe-core integration
+     * Returns the Puppeteer Page or Playwright Page instance
+     */
+    getUnderlyingPage(): unknown;
+    /**
+     * Get the adapter type for conditional axe-core setup
+     */
+    getAdapterType(): 'puppeteer' | 'playwright';
+}
+/**
+ * Abstract browser interface
+ */
+export interface BrowserAdapter {
+    launch(): Promise<void>;
+    newPage(): Promise<PageAdapter>;
+    close(): Promise<void>;
+    getBrowserType(): BrowserType;
+}
+/**
+ * Check if Playwright is installed
+ */
+export declare function isPlaywrightInstalled(): Promise<boolean>;
+/**
+ * Error thrown when Playwright is requested but not installed
+ */
+export declare class PlaywrightNotInstalledError extends Error {
+    constructor(browser: BrowserType);
+}
+/**
+ * Create a browser adapter for the specified browser type
+ *
+ * @param type Browser type: 'chromium', 'firefox', or 'webkit'
+ * @returns BrowserAdapter instance
+ *
+ * Note: chromium uses Puppeteer by default (always available).
+ * Firefox and WebKit require Playwright to be installed.
+ * Use --browser chromium-playwright to force Playwright for Chromium.
+ */
+export declare function createBrowser(type?: BrowserType | 'chromium-playwright'): BrowserAdapter;
+/**
+ * Validate browser type option
+ */
+export declare function validateBrowserType(value: string): BrowserType;

package/dist/utils/browser.js

@@ -0,0 +1,239 @@
+/**
+ * Browser abstraction layer for cross-browser accessibility testing
+ *
+ * Supports Puppeteer (default, always available) and Playwright (optional, for Firefox/WebKit)
+ */
+/**
+ * Dynamic import helper that works with optional dependencies
+ * Uses eval to avoid TypeScript module resolution errors
+ */
+// eslint-disable-next-line @typescript-eslint/no-implied-eval
+const dynamicImport = new Function('modulePath', 'return import(modulePath)');
+/**
+ * Check if Playwright is installed
+ */
+export async function isPlaywrightInstalled() {
+    try {
+        await dynamicImport('playwright');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Error thrown when Playwright is requested but not installed
+ */
+export class PlaywrightNotInstalledError extends Error {
+    constructor(browser) {
+        super(`Playwright is required for ${browser} browser but is not installed.\n\n` +
+            `To install Playwright, run:\n` +
+            `  npm install playwright\n\n` +
+            `Then install browser binaries:\n` +
+            `  npx playwright install ${browser}\n\n` +
+            `Or use the default Chromium browser (no additional installation required):\n` +
+            `  ally scan --browser chromium`);
+        this.name = 'PlaywrightNotInstalledError';
+    }
+}
+/**
+ * Puppeteer adapter - wraps Puppeteer for chromium support
+ */
+class PuppeteerPageAdapter {
+    page;
+    constructor(page) {
+        this.page = page;
+    }
+    async goto(url, options) {
+        // Map our waitUntil to Puppeteer's options
+        const waitUntil = options?.waitUntil === 'networkidle' ? 'networkidle2' : options?.waitUntil || 'load';
+        await this.page.goto(url, { waitUntil, timeout: options?.timeout });
+    }
+    async setContent(html, options) {
+        await this.page.setContent(html, { waitUntil: options?.waitUntil || 'domcontentloaded' });
+    }
+    async content() {
+        return this.page.content();
+    }
+    async waitForSelector(selector, options) {
+        await this.page.waitForSelector(selector, options);
+    }
+    async evaluate(fn) {
+        return this.page.evaluate(fn);
+    }
+    async addStyleTag(options) {
+        await this.page.addStyleTag(options);
+    }
+    async setViewport(viewport) {
+        await this.page.setViewport(viewport);
+    }
+    async screenshot(options) {
+        await this.page.screenshot(options);
+    }
+    async close() {
+        await this.page.close();
+    }
+    getUnderlyingPage() {
+        return this.page;
+    }
+    getAdapterType() {
+        return 'puppeteer';
+    }
+}
+class PuppeteerBrowserAdapter {
+    browser = null;
+    async launch() {
+        // Dynamic import to avoid loading at startup
+        const puppeteer = await import('puppeteer');
+        this.browser = await puppeteer.default.launch({
+            headless: true,
+            args: ['--no-sandbox', '--disable-setuid-sandbox'],
+        });
+    }
+    async newPage() {
+        if (!this.browser) {
+            throw new Error('Browser not launched. Call launch() first.');
+        }
+        const page = await this.browser.newPage();
+        return new PuppeteerPageAdapter(page);
+    }
+    async close() {
+        if (this.browser) {
+            await this.browser.close();
+            this.browser = null;
+        }
+    }
+    getBrowserType() {
+        return 'chromium';
+    }
+}
+/**
+ * Playwright adapter - supports chromium, firefox, and webkit
+ */
+class PlaywrightPageAdapter {
+    page;
+    constructor(page) {
+        this.page = page;
+    }
+    async goto(url, options) {
+        // Playwright uses 'networkidle' directly
+        await this.page.goto(url, {
+            waitUntil: options?.waitUntil,
+            timeout: options?.timeout,
+        });
+    }
+    async setContent(html, options) {
+        await this.page.setContent(html, { waitUntil: options?.waitUntil || 'domcontentloaded' });
+    }
+    async content() {
+        return this.page.content();
+    }
+    async waitForSelector(selector, options) {
+        await this.page.waitForSelector(selector, options ? { timeout: options.timeout } : undefined);
+    }
+    async evaluate(fn) {
+        return this.page.evaluate(fn);
+    }
+    async addStyleTag(options) {
+        await this.page.addStyleTag(options);
+    }
+    async setViewport(viewport) {
+        await this.page.setViewportSize(viewport);
+    }
+    async screenshot(options) {
+        await this.page.screenshot(options);
+    }
+    async close() {
+        await this.page.close();
+    }
+    getUnderlyingPage() {
+        return this.page;
+    }
+    getAdapterType() {
+        return 'playwright';
+    }
+}
+class PlaywrightBrowserAdapter {
+    browser = null;
+    browserType;
+    constructor(browserType) {
+        this.browserType = browserType;
+    }
+    async launch() {
+        // Dynamic import to avoid loading at startup
+        let playwright;
+        try {
+            playwright = await dynamicImport('playwright');
+        }
+        catch {
+            throw new PlaywrightNotInstalledError(this.browserType);
+        }
+        // Select the appropriate browser engine
+        const browserLauncher = playwright[this.browserType];
+        if (!browserLauncher) {
+            throw new Error(`Unknown browser type: ${this.browserType}`);
+        }
+        try {
+            this.browser = await browserLauncher.launch({
+                headless: true,
+            });
+        }
+        catch (error) {
+            // Check if the error is about missing browser binaries
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage.includes('Executable doesn\'t exist') || errorMessage.includes('browserType.launch')) {
+                throw new Error(`${this.browserType} browser binaries are not installed.\n\n` +
+                    `To install them, run:\n` +
+                    `  npx playwright install ${this.browserType}\n\n` +
+                    `Or install all browsers:\n` +
+                    `  npx playwright install`);
+            }
+            throw error;
+        }
+    }
+    async newPage() {
+        if (!this.browser) {
+            throw new Error('Browser not launched. Call launch() first.');
+        }
+        const page = await this.browser.newPage();
+        return new PlaywrightPageAdapter(page);
+    }
+    async close() {
+        if (this.browser) {
+            await this.browser.close();
+            this.browser = null;
+        }
+    }
+    getBrowserType() {
+        return this.browserType;
+    }
+}
+/**
+ * Create a browser adapter for the specified browser type
+ *
+ * @param type Browser type: 'chromium', 'firefox', or 'webkit'
+ * @returns BrowserAdapter instance
+ *
+ * Note: chromium uses Puppeteer by default (always available).
+ * Firefox and WebKit require Playwright to be installed.
+ * Use --browser chromium-playwright to force Playwright for Chromium.
+ */
+export function createBrowser(type = 'chromium') {
+    // For chromium, use Puppeteer by default (lighter weight, always available)
+    if (type === 'chromium') {
+        return new PuppeteerBrowserAdapter();
+    }
+    // For chromium-playwright, firefox, or webkit, use Playwright
+    const playwrightType = type === 'chromium-playwright' ? 'chromium' : type;
+    return new PlaywrightBrowserAdapter(playwrightType);
+}
+/**
+ * Validate browser type option
+ */
+export function validateBrowserType(value) {
+    const valid = ['chromium', 'firefox', 'webkit'];
+    if (!valid.includes(value)) {
+        throw new Error(`Invalid browser: ${value}. Valid options: ${valid.join(', ')}`);
+    }
+    return value;
+}

package/dist/utils/cache.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Caching utilities for incremental scans
+ *
+ * Caches scan results by file hash to avoid re-scanning unchanged files.
+ */
+import type { ScanResult } from '../types/index.js';
+/**
+ * Cache index entry for a single file
+ */
+interface CacheEntry {
+    /** File path (relative to project root) */
+    path: string;
+    /** Content hash */
+    hash: string;
+    /** Last modified timestamp */
+    mtime: number;
+    /** Scan result */
+    result: ScanResult;
+    /** WCAG standard used for the scan */
+    standard: string;
+    /** Cache creation timestamp */
+    cachedAt: number;
+}
+/**
+ * Cache index structure
+ */
+interface CacheIndex {
+    /** Cache format version */
+    version: number;
+    /** Map of file path to cache entry */
+    entries: Record<string, CacheEntry>;
+    /** Last updated timestamp */
+    updatedAt: number;
+}
+/**
+ * Compute SHA-256 hash of file content
+ */
+export declare function hashFile(filePath: string): Promise<string>;
+/**
+ * Compute hash of content string
+ */
+export declare function hashContent(content: string): string;
+/**
+ * Load cache index from disk
+ */
+export declare function loadCacheIndex(): Promise<CacheIndex>;
+/**
+ * Save cache index to disk
+ */
+export declare function saveCacheIndex(index: CacheIndex): Promise<void>;
+/**
+ * Get cached result for a file if valid
+ */
+export declare function getCachedResult(filePath: string, standard: string): Promise<ScanResult | null>;
+/**
+ * Cache a scan result for a file
+ */
+export declare function cacheResult(filePath: string, result: ScanResult, standard: string): Promise<void>;
+/**
+ * Clear all cached results
+ */
+export declare function clearCache(): Promise<void>;
+/**
+ * Get cache statistics
+ */
+export declare function getCacheStats(): Promise<{
+    entries: number;
+    size: number;
+    oldestEntry: number | null;
+    newestEntry: number | null;
+}>;
+/**
+ * Remove stale cache entries (files that no longer exist)
+ */
+export declare function pruneCache(): Promise<number>;
+export {};