ally-a11y 1.0.0

package/dist/utils/cache.js

@@ -0,0 +1,178 @@
+/**
+ * Caching utilities for incremental scans
+ *
+ * Caches scan results by file hash to avoid re-scanning unchanged files.
+ */
+import { createHash } from 'crypto';
+import { readFile, writeFile, mkdir, stat } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve, dirname, relative } from 'path';
+const CACHE_VERSION = 1;
+const CACHE_DIR = '.ally/cache';
+const CACHE_INDEX_FILE = '.ally/cache/index.json';
+/**
+ * Compute SHA-256 hash of file content
+ */
+export async function hashFile(filePath) {
+    const content = await readFile(filePath);
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Compute hash of content string
+ */
+export function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Load cache index from disk
+ */
+export async function loadCacheIndex() {
+    const indexPath = resolve(CACHE_INDEX_FILE);
+    if (!existsSync(indexPath)) {
+        return {
+            version: CACHE_VERSION,
+            entries: {},
+            updatedAt: Date.now(),
+        };
+    }
+    try {
+        const content = await readFile(indexPath, 'utf-8');
+        const index = JSON.parse(content);
+        // Check version compatibility
+        if (index.version !== CACHE_VERSION) {
+            return {
+                version: CACHE_VERSION,
+                entries: {},
+                updatedAt: Date.now(),
+            };
+        }
+        return index;
+    }
+    catch {
+        return {
+            version: CACHE_VERSION,
+            entries: {},
+            updatedAt: Date.now(),
+        };
+    }
+}
+/**
+ * Save cache index to disk
+ */
+export async function saveCacheIndex(index) {
+    const indexPath = resolve(CACHE_INDEX_FILE);
+    const cacheDir = dirname(indexPath);
+    if (!existsSync(cacheDir)) {
+        await mkdir(cacheDir, { recursive: true });
+    }
+    index.updatedAt = Date.now();
+    await writeFile(indexPath, JSON.stringify(index, null, 2));
+}
+/**
+ * Get cached result for a file if valid
+ */
+export async function getCachedResult(filePath, standard) {
+    const index = await loadCacheIndex();
+    const relativePath = relative(process.cwd(), filePath);
+    const entry = index.entries[relativePath];
+    if (!entry) {
+        return null;
+    }
+    // Check if standard matches
+    if (entry.standard !== standard) {
+        return null;
+    }
+    try {
+        // Check if file has been modified
+        const stats = await stat(filePath);
+        const mtime = stats.mtimeMs;
+        if (mtime !== entry.mtime) {
+            // File modified, verify with hash
+            const hash = await hashFile(filePath);
+            if (hash !== entry.hash) {
+                return null;
+            }
+            // Hash matches, update mtime in cache
+            entry.mtime = mtime;
+            await saveCacheIndex(index);
+        }
+        return entry.result;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Cache a scan result for a file
+ */
+export async function cacheResult(filePath, result, standard) {
+    const index = await loadCacheIndex();
+    const relativePath = relative(process.cwd(), filePath);
+    try {
+        const stats = await stat(filePath);
+        const hash = await hashFile(filePath);
+        index.entries[relativePath] = {
+            path: relativePath,
+            hash,
+            mtime: stats.mtimeMs,
+            result,
+            standard,
+            cachedAt: Date.now(),
+        };
+        await saveCacheIndex(index);
+    }
+    catch {
+        // Silently fail if caching fails
+    }
+}
+/**
+ * Clear all cached results
+ */
+export async function clearCache() {
+    const index = {
+        version: CACHE_VERSION,
+        entries: {},
+        updatedAt: Date.now(),
+    };
+    await saveCacheIndex(index);
+}
+/**
+ * Get cache statistics
+ */
+export async function getCacheStats() {
+    const index = await loadCacheIndex();
+    const entries = Object.values(index.entries);
+    if (entries.length === 0) {
+        return {
+            entries: 0,
+            size: 0,
+            oldestEntry: null,
+            newestEntry: null,
+        };
+    }
+    const timestamps = entries.map((e) => e.cachedAt);
+    return {
+        entries: entries.length,
+        size: JSON.stringify(index).length,
+        oldestEntry: Math.min(...timestamps),
+        newestEntry: Math.max(...timestamps),
+    };
+}
+/**
+ * Remove stale cache entries (files that no longer exist)
+ */
+export async function pruneCache() {
+    const index = await loadCacheIndex();
+    let removed = 0;
+    for (const path of Object.keys(index.entries)) {
+        const fullPath = resolve(path);
+        if (!existsSync(fullPath)) {
+            delete index.entries[path];
+            removed++;
+        }
+    }
+    if (removed > 0) {
+        await saveCacheIndex(index);
+    }
+    return removed;
+}

package/dist/utils/config.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Configuration file support for Ally A11y CLI
+ *
+ * Supports loading config from:
+ * - .allyrc.json
+ * - .allyrc (JSON format)
+ * - ally.config.js (CommonJS module)
+ *
+ * Searches current directory and parent directories (like eslint)
+ */
+import type { Severity } from '../types/index.js';
+import type { WcagStandard } from './scanner.js';
+/**
+ * Configuration options for the scan command
+ */
+export interface ScanConfig {
+    /** Paths to scan (relative to config file or cwd) */
+    paths?: string[];
+    /** Glob patterns to ignore */
+    ignore?: string[];
+    /** Violation threshold for CI (exit with error if exceeded) */
+    threshold?: number;
+    /** WCAG standard to test against */
+    standard?: WcagStandard;
+    /** Only fail on these severity levels */
+    failOn?: Severity[];
+}
+/**
+ * Configuration options for report generation
+ */
+export interface ReportConfig {
+    /** Output format: json, sarif, markdown, html */
+    format?: string;
+    /** Output directory or file path */
+    output?: string;
+}
+/**
+ * Configuration options for the fix command
+ */
+export interface FixConfig {
+    /** Show what would be fixed without making changes */
+    dryRun?: boolean;
+    /** Auto-approve fixes for these violation types */
+    autoApprove?: string[];
+}
+/**
+ * Complete Ally configuration
+ */
+export interface AllyConfig {
+    scan?: ScanConfig;
+    report?: ReportConfig;
+    fix?: FixConfig;
+}
+/** Result from loading config */
+export interface ConfigResult {
+    config: AllyConfig;
+    configPath: string | null;
+}
+/**
+ * Load configuration from .allyrc.json or similar config files
+ *
+ * Searches current directory and parent directories for config files.
+ * Returns an empty config if no file is found.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Loaded configuration and path to config file (if found)
+ */
+export declare function loadConfig(startDir?: string): Promise<ConfigResult>;
+/**
+ * Get the path to the config file that would be used
+ *
+ * Useful for debugging to see which config file is being loaded.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Path to config file or null if none found
+ */
+export declare function getConfigPath(startDir?: string): Promise<string | null>;
+/**
+ * Merge CLI options with config file options
+ *
+ * CLI options take precedence over config file options.
+ *
+ * @param cliOptions - Options from command line
+ * @param config - Options from config file
+ * @returns Merged options
+ */
+export declare function mergeOptions<T extends Record<string, unknown>>(cliOptions: T, configOptions: Partial<T>): T;
+/** Result from loading ignore patterns */
+export interface IgnoreResult {
+    patterns: string[];
+    ignorePath: string | null;
+}
+/**
+ * Load ignore patterns from .allyignore file
+ *
+ * Searches current directory and parent directories for ignore file.
+ * Returns empty patterns array if no file is found.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Loaded ignore patterns and path to ignore file (if found)
+ */
+export declare function loadIgnorePatterns(startDir?: string): Promise<IgnoreResult>;

package/dist/utils/config.js

@@ -0,0 +1,237 @@
+/**
+ * Configuration file support for Ally A11y CLI
+ *
+ * Supports loading config from:
+ * - .allyrc.json
+ * - .allyrc (JSON format)
+ * - ally.config.js (CommonJS module)
+ *
+ * Searches current directory and parent directories (like eslint)
+ */
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { resolve, dirname, join } from 'path';
+/** Ignore file names to search for (in order of priority) */
+const IGNORE_FILES = ['.allyignore', '.ally-ignore'];
+/** Config file names to search for (in order of priority) */
+const CONFIG_FILES = [
+    '.allyrc.json',
+    '.allyrc',
+    'ally.config.js',
+    'ally.config.cjs',
+];
+/**
+ * Search for config file starting from directory and moving up to root
+ */
+async function findConfigFile(startDir) {
+    let currentDir = resolve(startDir);
+    const root = dirname(currentDir);
+    // Keep searching until we hit the root
+    while (currentDir !== root) {
+        for (const configFile of CONFIG_FILES) {
+            const configPath = join(currentDir, configFile);
+            if (existsSync(configPath)) {
+                return configPath;
+            }
+        }
+        currentDir = dirname(currentDir);
+    }
+    // Check root as well
+    for (const configFile of CONFIG_FILES) {
+        const configPath = join(currentDir, configFile);
+        if (existsSync(configPath)) {
+            return configPath;
+        }
+    }
+    return null;
+}
+/**
+ * Load and parse a config file
+ */
+async function parseConfigFile(configPath) {
+    const ext = configPath.split('.').pop();
+    if (ext === 'js' || ext === 'cjs') {
+        // Load JavaScript config (CommonJS)
+        try {
+            const configModule = await import(configPath);
+            return configModule.default || configModule;
+        }
+        catch (error) {
+            throw new Error(`Failed to load config from ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // Load JSON config
+    try {
+        const content = await readFile(configPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid JSON in config file ${configPath}: ${error.message}`);
+        }
+        throw new Error(`Failed to read config file ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Validate config structure and values
+ */
+function validateConfig(config, configPath) {
+    const validStandards = [
+        'wcag2a', 'wcag2aa', 'wcag2aaa',
+        'wcag21a', 'wcag21aa', 'wcag21aaa',
+        'wcag22aa', 'section508', 'best-practice'
+    ];
+    const validSeverities = ['critical', 'serious', 'moderate', 'minor'];
+    if (config.scan?.standard && !validStandards.includes(config.scan.standard)) {
+        throw new Error(`Invalid standard "${config.scan.standard}" in ${configPath}. ` +
+            `Valid options: ${validStandards.join(', ')}`);
+    }
+    if (config.scan?.failOn) {
+        for (const severity of config.scan.failOn) {
+            if (!validSeverities.includes(severity)) {
+                throw new Error(`Invalid severity "${severity}" in failOn in ${configPath}. ` +
+                    `Valid options: ${validSeverities.join(', ')}`);
+            }
+        }
+    }
+    if (config.scan?.threshold !== undefined) {
+        if (typeof config.scan.threshold !== 'number' || config.scan.threshold < 0) {
+            throw new Error(`Invalid threshold "${config.scan.threshold}" in ${configPath}. ` +
+                `Must be a non-negative number.`);
+        }
+    }
+    const validFormats = ['json', 'sarif', 'markdown', 'html'];
+    if (config.report?.format && !validFormats.includes(config.report.format)) {
+        throw new Error(`Invalid report format "${config.report.format}" in ${configPath}. ` +
+            `Valid options: ${validFormats.join(', ')}`);
+    }
+}
+/**
+ * Load configuration from .allyrc.json or similar config files
+ *
+ * Searches current directory and parent directories for config files.
+ * Returns an empty config if no file is found.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Loaded configuration and path to config file (if found)
+ */
+export async function loadConfig(startDir = process.cwd()) {
+    try {
+        const configPath = await findConfigFile(startDir);
+        if (!configPath) {
+            return { config: {}, configPath: null };
+        }
+        const config = await parseConfigFile(configPath);
+        validateConfig(config, configPath);
+        return { config, configPath };
+    }
+    catch (error) {
+        // Re-throw validation/parsing errors
+        if (error instanceof Error && error.message.includes('config')) {
+            throw error;
+        }
+        // Wrap other errors
+        throw new Error(`Failed to load config: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Get the path to the config file that would be used
+ *
+ * Useful for debugging to see which config file is being loaded.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Path to config file or null if none found
+ */
+export async function getConfigPath(startDir = process.cwd()) {
+    return findConfigFile(startDir);
+}
+/**
+ * Merge CLI options with config file options
+ *
+ * CLI options take precedence over config file options.
+ *
+ * @param cliOptions - Options from command line
+ * @param config - Options from config file
+ * @returns Merged options
+ */
+export function mergeOptions(cliOptions, configOptions) {
+    const merged = { ...configOptions };
+    // CLI options override config options (only if explicitly set)
+    for (const [key, value] of Object.entries(cliOptions)) {
+        if (value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+/**
+ * Search for .allyignore file starting from directory and moving up to root
+ */
+async function findIgnoreFile(startDir) {
+    let currentDir = resolve(startDir);
+    const root = dirname(currentDir);
+    while (currentDir !== root) {
+        for (const ignoreFile of IGNORE_FILES) {
+            const ignorePath = join(currentDir, ignoreFile);
+            if (existsSync(ignorePath)) {
+                return ignorePath;
+            }
+        }
+        currentDir = dirname(currentDir);
+    }
+    // Check root as well
+    for (const ignoreFile of IGNORE_FILES) {
+        const ignorePath = join(currentDir, ignoreFile);
+        if (existsSync(ignorePath)) {
+            return ignorePath;
+        }
+    }
+    return null;
+}
+/**
+ * Parse ignore file content into glob patterns
+ *
+ * Supports glob patterns, directory patterns (ending with /),
+ * comments (lines starting with #), and blank lines.
+ */
+function parseIgnoreFile(content) {
+    return content
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith('#'))
+        .map((pattern) => {
+        // Convert directory patterns to glob patterns
+        if (pattern.endsWith('/')) {
+            return `**/${pattern}**`;
+        }
+        // Ensure patterns without slashes match anywhere
+        if (!pattern.includes('/') && !pattern.startsWith('**/')) {
+            return `**/${pattern}`;
+        }
+        return pattern;
+    });
+}
+/**
+ * Load ignore patterns from .allyignore file
+ *
+ * Searches current directory and parent directories for ignore file.
+ * Returns empty patterns array if no file is found.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Loaded ignore patterns and path to ignore file (if found)
+ */
+export async function loadIgnorePatterns(startDir = process.cwd()) {
+    const ignorePath = await findIgnoreFile(startDir);
+    if (!ignorePath) {
+        return { patterns: [], ignorePath: null };
+    }
+    try {
+        const content = await readFile(ignorePath, 'utf-8');
+        const patterns = parseIgnoreFile(content);
+        return { patterns, ignorePath };
+    }
+    catch {
+        // If we can't read the file, return empty patterns
+        return { patterns: [], ignorePath: null };
+    }
+}

package/dist/utils/converters.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Format converters for accessibility reports
+ * Converts AllyReport to various output formats (SARIF, JUnit, CSV)
+ */
+import type { AllyReport } from '../types/index.js';
+export interface SarifReport {
+    $schema: string;
+    version: string;
+    runs: SarifRun[];
+}
+interface SarifRun {
+    tool: {
+        driver: {
+            name: string;
+            version: string;
+            informationUri: string;
+            rules: SarifRule[];
+        };
+    };
+    results: SarifResult[];
+}
+interface SarifRule {
+    id: string;
+    name: string;
+    shortDescription: {
+        text: string;
+    };
+    fullDescription: {
+        text: string;
+    };
+    helpUri: string;
+    defaultConfiguration: {
+        level: 'error' | 'warning' | 'note';
+    };
+    properties?: {
+        tags?: string[];
+    };
+}
+interface SarifResult {
+    ruleId: string;
+    ruleIndex: number;
+    level: 'error' | 'warning' | 'note';
+    message: {
+        text: string;
+    };
+    locations: SarifLocation[];
+}
+interface SarifLocation {
+    physicalLocation: {
+        artifactLocation: {
+            uri: string;
+            uriBaseId?: string;
+        };
+        region?: {
+            startLine?: number;
+            startColumn?: number;
+            snippet?: {
+                text: string;
+            };
+        };
+    };
+}
+/**
+ * Convert AllyReport to SARIF 2.1.0 format for GitHub Code Scanning integration
+ */
+export declare function convertToSarif(report: AllyReport): SarifReport;
+/**
+ * Convert AllyReport to JUnit XML format for CI/CD tools (Jenkins, GitLab, etc.)
+ * Each violation is represented as a test failure
+ */
+export declare function convertToJunit(report: AllyReport): string;
+/**
+ * Convert AllyReport to CSV format
+ * Headers: file,violation_id,impact,description,selector,wcag,help_url
+ */
+export declare function convertToCsv(report: AllyReport): string;
+export {};