npm - ally-a11y - Versions diffs - 1.0.0 - Mend

ally-a11y 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (84) hide show

package/ACCESSIBILITY.md +205 -0
package/LICENSE +21 -0
package/README.md +940 -0
package/dist/cli.d.ts +7 -0
package/dist/cli.js +528 -0
package/dist/commands/audit-palette.d.ts +18 -0
package/dist/commands/audit-palette.js +613 -0
package/dist/commands/auto-pr.d.ts +19 -0
package/dist/commands/auto-pr.js +434 -0
package/dist/commands/badge.d.ts +11 -0
package/dist/commands/badge.js +143 -0
package/dist/commands/completion.d.ts +4 -0
package/dist/commands/completion.js +185 -0
package/dist/commands/crawl.d.ts +12 -0
package/dist/commands/crawl.js +249 -0
package/dist/commands/doctor.d.ts +5 -0
package/dist/commands/doctor.js +233 -0
package/dist/commands/explain.d.ts +12 -0
package/dist/commands/explain.js +233 -0
package/dist/commands/fix.d.ts +13 -0
package/dist/commands/fix.js +668 -0
package/dist/commands/health.d.ts +11 -0
package/dist/commands/health.js +367 -0
package/dist/commands/history.d.ts +10 -0
package/dist/commands/history.js +191 -0
package/dist/commands/init.d.ts +9 -0
package/dist/commands/init.js +164 -0
package/dist/commands/learn.d.ts +8 -0
package/dist/commands/learn.js +592 -0
package/dist/commands/pr-check.d.ts +12 -0
package/dist/commands/pr-check.js +270 -0
package/dist/commands/report.d.ts +11 -0
package/dist/commands/report.js +375 -0
package/dist/commands/scan-storybook.d.ts +18 -0
package/dist/commands/scan-storybook.js +402 -0
package/dist/commands/scan.d.ts +25 -0
package/dist/commands/scan.js +673 -0
package/dist/commands/stats.d.ts +5 -0
package/dist/commands/stats.js +137 -0
package/dist/commands/tree.d.ts +12 -0
package/dist/commands/tree.js +635 -0
package/dist/commands/triage.d.ts +13 -0
package/dist/commands/triage.js +327 -0
package/dist/commands/watch.d.ts +17 -0
package/dist/commands/watch.js +302 -0
package/dist/types/index.d.ts +60 -0
package/dist/types/index.js +4 -0
package/dist/utils/baseline.d.ts +62 -0
package/dist/utils/baseline.js +169 -0
package/dist/utils/browser.d.ts +78 -0
package/dist/utils/browser.js +239 -0
package/dist/utils/cache.d.ts +76 -0
package/dist/utils/cache.js +178 -0
package/dist/utils/config.d.ts +102 -0
package/dist/utils/config.js +237 -0
package/dist/utils/converters.d.ts +77 -0
package/dist/utils/converters.js +200 -0
package/dist/utils/copilot.d.ts +36 -0
package/dist/utils/copilot.js +139 -0
package/dist/utils/detect.d.ts +22 -0
package/dist/utils/detect.js +197 -0
package/dist/utils/enhanced-errors.d.ts +46 -0
package/dist/utils/enhanced-errors.js +295 -0
package/dist/utils/errors.d.ts +31 -0
package/dist/utils/errors.js +149 -0
package/dist/utils/fix-patterns.d.ts +56 -0
package/dist/utils/fix-patterns.js +529 -0
package/dist/utils/history-tracking.d.ts +94 -0
package/dist/utils/history-tracking.js +230 -0
package/dist/utils/history.d.ts +42 -0
package/dist/utils/history.js +255 -0
package/dist/utils/impact-scores.d.ts +44 -0
package/dist/utils/impact-scores.js +257 -0
package/dist/utils/retry.d.ts +24 -0
package/dist/utils/retry.js +76 -0
package/dist/utils/scanner.d.ts +74 -0
package/dist/utils/scanner.js +606 -0
package/dist/utils/scanner.test.d.ts +4 -0
package/dist/utils/scanner.test.js +162 -0
package/dist/utils/ui.d.ts +44 -0
package/dist/utils/ui.js +276 -0
package/mcp-server/dist/index.d.ts +8 -0
package/mcp-server/dist/index.js +1923 -0
package/package.json +88 -0

package/dist/utils/scanner.test.js ADDED Viewed

@@ -0,0 +1,162 @@
+/**
+ * Tests for the accessibility scanner
+ */
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import { resolve } from 'path';
+import { AccessibilityScanner, calculateScore, generateSummary, createReport, findHtmlFiles, } from '../../dist/utils/scanner.js';
+describe('AccessibilityScanner', () => {
+    let scanner;
+    before(async () => {
+        scanner = new AccessibilityScanner();
+        await scanner.init();
+    });
+    after(async () => {
+        await scanner.close();
+    });
+    it('should scan HTML file with violations', async () => {
+        const testFile = resolve(process.cwd(), 'test-fixtures/bad-a11y.html');
+        const result = await scanner.scanHtmlFile(testFile);
+        assert.ok(result.violations.length > 0, 'Should find violations');
+        assert.ok(result.timestamp, 'Should have timestamp');
+        assert.ok(result.passes > 0, 'Should have some passing rules');
+    });
+    it('should scan clean HTML file', async () => {
+        const testFile = resolve(process.cwd(), 'test-fixtures/good-a11y.html');
+        const result = await scanner.scanHtmlFile(testFile);
+        assert.strictEqual(result.violations.length, 0, 'Should find no violations');
+    });
+    it('should scan HTML string', async () => {
+        const html = `
+      <!DOCTYPE html>
+      <html lang="en">
+      <head><title>Test</title></head>
+      <body><main><h1>Test</h1></main></body>
+      </html>
+    `;
+        const result = await scanner.scanHtmlString(html, 'test-string');
+        assert.ok(result, 'Should return result');
+        assert.strictEqual(result.file, 'test-string');
+    });
+});
+describe('calculateScore', () => {
+    it('should return 100 for no violations', () => {
+        const results = [{
+                url: 'test',
+                timestamp: new Date().toISOString(),
+                violations: [],
+                passes: 50,
+                incomplete: 0,
+            }];
+        const score = calculateScore(results);
+        assert.strictEqual(score, 100);
+    });
+    it('should penalize critical violations heavily', () => {
+        const criticalViolation = {
+            id: 'test',
+            impact: 'critical',
+            description: 'Test',
+            help: 'Test help',
+            helpUrl: 'https://example.com',
+            tags: [],
+            nodes: [{ html: '<div>', target: ['div'], failureSummary: '' }],
+        };
+        const results = [{
+                url: 'test',
+                timestamp: new Date().toISOString(),
+                violations: [criticalViolation],
+                passes: 50,
+                incomplete: 0,
+            }];
+        const score = calculateScore(results);
+        assert.ok(score < 100, 'Score should be reduced');
+        assert.ok(score <= 75, 'Critical violation should reduce score significantly');
+    });
+    it('should penalize minor violations lightly', () => {
+        const minorViolation = {
+            id: 'test',
+            impact: 'minor',
+            description: 'Test',
+            help: 'Test help',
+            helpUrl: 'https://example.com',
+            tags: [],
+            nodes: [{ html: '<div>', target: ['div'], failureSummary: '' }],
+        };
+        const results = [{
+                url: 'test',
+                timestamp: new Date().toISOString(),
+                violations: [minorViolation],
+                passes: 50,
+                incomplete: 0,
+            }];
+        const score = calculateScore(results);
+        assert.ok(score >= 95, 'Minor violation should only reduce score slightly');
+    });
+});
+describe('generateSummary', () => {
+    it('should count violations by severity', () => {
+        const results = [{
+                url: 'test',
+                timestamp: new Date().toISOString(),
+                violations: [
+                    { id: 'a', impact: 'critical', description: '', help: '', helpUrl: '', tags: [], nodes: [] },
+                    { id: 'b', impact: 'serious', description: '', help: '', helpUrl: '', tags: [], nodes: [] },
+                    { id: 'c', impact: 'serious', description: '', help: '', helpUrl: '', tags: [], nodes: [] },
+                ],
+                passes: 0,
+                incomplete: 0,
+            }];
+        const summary = generateSummary(results);
+        assert.strictEqual(summary.bySeverity.critical, 1);
+        assert.strictEqual(summary.bySeverity.serious, 2);
+        assert.strictEqual(summary.totalViolations, 3);
+    });
+    it('should identify top issues', () => {
+        const results = [{
+                url: 'test',
+                timestamp: new Date().toISOString(),
+                violations: [
+                    { id: 'image-alt', impact: 'critical', description: '', help: 'Images need alt', helpUrl: '', tags: [], nodes: [] },
+                    { id: 'image-alt', impact: 'critical', description: '', help: 'Images need alt', helpUrl: '', tags: [], nodes: [] },
+                    { id: 'button-name', impact: 'critical', description: '', help: 'Buttons need name', helpUrl: '', tags: [], nodes: [] },
+                ],
+                passes: 0,
+                incomplete: 0,
+            }];
+        const summary = generateSummary(results);
+        assert.ok(summary.topIssues.length > 0);
+        assert.strictEqual(summary.topIssues[0].id, 'image-alt');
+        assert.strictEqual(summary.topIssues[0].count, 2);
+    });
+});
+describe('findHtmlFiles', () => {
+    it('should find HTML files in test-fixtures', async () => {
+        const files = await findHtmlFiles(resolve(process.cwd(), 'test-fixtures'));
+        assert.ok(files.length >= 2, 'Should find at least 2 HTML files');
+        assert.ok(files.some(f => f.includes('bad-a11y.html')));
+        assert.ok(files.some(f => f.includes('good-a11y.html')));
+    });
+    it('should ignore node_modules', async () => {
+        const files = await findHtmlFiles(process.cwd());
+        const inNodeModules = files.filter(f => f.includes('node_modules'));
+        assert.strictEqual(inNodeModules.length, 0, 'Should not include node_modules');
+    });
+});
+describe('createReport', () => {
+    it('should create valid report structure', () => {
+        const results = [{
+                url: 'test.html',
+                file: 'test.html',
+                timestamp: new Date().toISOString(),
+                violations: [],
+                passes: 10,
+                incomplete: 0,
+            }];
+        const report = createReport(results);
+        assert.ok(report.version);
+        assert.ok(report.scanDate);
+        assert.strictEqual(report.totalFiles, 1);
+        assert.ok(report.summary);
+        assert.strictEqual(report.summary.score, 100);
+    });
+});

package/dist/utils/ui.d.ts ADDED Viewed

@@ -0,0 +1,44 @@
+/**
+ * Terminal UI utilities for polished output
+ */
+import { type Ora } from 'ora';
+import type { ReportSummary, Violation } from '../types/index.js';
+import type { ImpactScore } from './impact-scores.js';
+/**
+ * Create a terminal hyperlink using OSC 8 escape sequences
+ * Format: \x1b]8;;URL\x07TEXT\x1b]8;;\x07
+ *
+ * For VS Code and other editors, use file:// URLs with line and column:
+ * file://path/to/file:line:column
+ *
+ * @param text - The visible text to display
+ * @param url - The URL to link to
+ * @returns The text wrapped in hyperlink escape sequences, or plain text if unsupported
+ */
+export declare function hyperlink(text: string, url: string): string;
+/**
+ * Create a clickable file path link that opens in the editor
+ *
+ * @param filePath - Absolute or relative path to the file
+ * @param line - Optional line number (1-indexed)
+ * @param column - Optional column number (1-indexed)
+ * @returns Hyperlinked file path or plain text if unsupported
+ */
+export declare function fileLink(filePath: string, line?: number, column?: number): string;
+export declare function printBanner(): void;
+export declare function createSpinner(text: string): Ora;
+export declare function printViolation(violation: Violation, file?: string, absolutePath?: string, impactScore?: ImpactScore): void;
+export declare function printSummary(summary: ReportSummary): void;
+export declare function printSuccess(message: string): void;
+export declare function printError(message: string): void;
+export declare function printWarning(message: string): void;
+export declare function printInfo(message: string): void;
+export declare function printDiff(oldCode: string, newCode: string): void;
+export declare function printFixPrompt(file: string, line: number, issue: string): void;
+export declare function printScoreChange(before: number, after: number): void;
+/**
+ * Animate score counting up - creates memorable visual feedback
+ */
+export declare function animateScoreUp(from: number, to: number): Promise<void>;
+export declare function printScoreBadge(score: number): void;
+export declare function printFileHeader(file: string, violationCount: number, absolutePath?: string): void;

package/dist/utils/ui.js ADDED Viewed

@@ -0,0 +1,276 @@
+/**
+ * Terminal UI utilities for polished output
+ */
+import chalk from 'chalk';
+import boxen from 'boxen';
+import ora from 'ora';
+// Honor NO_COLOR environment variable (https://no-color.org/)
+const noColor = process.env.NO_COLOR !== undefined || process.env.ALLY_NO_COLOR !== undefined;
+if (noColor) {
+    chalk.level = 0;
+}
+/**
+ * Check if terminal hyperlinks should be disabled
+ * Disabled in NO_COLOR mode, CI environments, or non-TTY
+ */
+function supportsHyperlinks() {
+    if (noColor)
+        return false;
+    if (process.env.CI)
+        return false;
+    if (!process.stdout.isTTY)
+        return false;
+    // Some terminals advertise hyperlink support
+    if (process.env.TERM_PROGRAM === 'vscode')
+        return true;
+    if (process.env.TERM_PROGRAM === 'iTerm.app')
+        return true;
+    if (process.env.WT_SESSION)
+        return true; // Windows Terminal
+    if (process.env.KONSOLE_VERSION)
+        return true;
+    // Default to true for modern terminals
+    return true;
+}
+/**
+ * Create a terminal hyperlink using OSC 8 escape sequences
+ * Format: \x1b]8;;URL\x07TEXT\x1b]8;;\x07
+ *
+ * For VS Code and other editors, use file:// URLs with line and column:
+ * file://path/to/file:line:column
+ *
+ * @param text - The visible text to display
+ * @param url - The URL to link to
+ * @returns The text wrapped in hyperlink escape sequences, or plain text if unsupported
+ */
+export function hyperlink(text, url) {
+    if (!supportsHyperlinks()) {
+        return text;
+    }
+    return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+/**
+ * Create a clickable file path link that opens in the editor
+ *
+ * @param filePath - Absolute or relative path to the file
+ * @param line - Optional line number (1-indexed)
+ * @param column - Optional column number (1-indexed)
+ * @returns Hyperlinked file path or plain text if unsupported
+ */
+export function fileLink(filePath, line, column) {
+    // Build the file URL with optional line and column
+    let url = `file://${filePath}`;
+    if (line !== undefined) {
+        url += `:${line}`;
+        if (column !== undefined) {
+            url += `:${column}`;
+        }
+    }
+    // Build the display text
+    let displayText = filePath;
+    if (line !== undefined) {
+        displayText += `:${line}`;
+        if (column !== undefined) {
+            displayText += `:${column}`;
+        }
+    }
+    return hyperlink(displayText, url);
+}
+// Severity colors
+const severityColors = {
+    critical: chalk.red.bold,
+    serious: chalk.red,
+    moderate: chalk.yellow,
+    minor: chalk.blue,
+};
+const severityIcons = {
+    critical: '!!!',
+    serious: '!!',
+    moderate: '!',
+    minor: 'i',
+};
+export function printBanner() {
+    const banner = chalk.cyan.bold(`
+   __ _  | | _   _
+  / _\` | | || | | |
+ | (_| | | || |_| |
+  \\__,_| |_| \\__, |
+             |___/  v1.0.0
+`);
+    console.log(banner);
+    console.log(chalk.dim('  Your codebase\'s accessibility ally\n'));
+}
+export function createSpinner(text) {
+    return ora({
+        text,
+        color: 'cyan',
+        spinner: 'dots',
+    });
+}
+export function printViolation(violation, file, absolutePath, impactScore) {
+    const color = severityColors[violation.impact];
+    const icon = severityIcons[violation.impact];
+    // Print severity and impact score on the same line
+    if (impactScore) {
+        const scoreColor = impactScore.score >= 95 ? chalk.red.bold :
+            impactScore.score >= 75 ? chalk.red :
+                impactScore.score >= 40 ? chalk.yellow :
+                    chalk.blue;
+        console.log(color(`  [${icon}] ${violation.impact.toUpperCase()}`) +
+            scoreColor(` Impact: ${impactScore.score}/100`) +
+            chalk.dim(` (WCAG ${impactScore.wcagLevel})`));
+    }
+    else {
+        console.log(color(`  [${icon}] ${violation.impact.toUpperCase()}`));
+    }
+    console.log(chalk.white(`      ${violation.help}`));
+    // Print impact reasoning if available
+    if (impactScore) {
+        console.log(chalk.dim(`      💡 ${impactScore.reasoning}`));
+        console.log(chalk.dim(`      👥 Affects: `) +
+            chalk.cyan(impactScore.affectedUsers.join(', ')));
+        console.log(chalk.dim(`      📊 Estimated: `) +
+            chalk.cyan(impactScore.estimatedUsers));
+    }
+    if (file) {
+        // Use absolute path for the hyperlink if available, display relative path
+        const linkPath = absolutePath || file;
+        const linkedFile = fileLink(linkPath);
+        // Apply dim styling to the linked text
+        console.log(chalk.dim(`      File: `) + chalk.dim(linkedFile));
+    }
+    violation.nodes.forEach((node, i) => {
+        if (i < 3) { // Limit to 3 nodes for readability
+            const target = node.target.join(' > ');
+            console.log(chalk.dim(`      → ${target}`));
+        }
+    });
+    if (violation.nodes.length > 3) {
+        console.log(chalk.dim(`      ... and ${violation.nodes.length - 3} more occurrences`));
+    }
+    // Make the help URL clickable too
+    const helpLink = hyperlink(violation.helpUrl, violation.helpUrl);
+    console.log(chalk.dim(`      Learn more: `) + chalk.dim(helpLink));
+    console.log();
+}
+export function printSummary(summary) {
+    const { totalViolations, bySeverity, score } = summary;
+    // Score color
+    let scoreColor = chalk.green;
+    if (score < 50)
+        scoreColor = chalk.red;
+    else if (score < 75)
+        scoreColor = chalk.yellow;
+    const summaryText = `
+${chalk.bold('Accessibility Score:')} ${scoreColor.bold(`${score}/100`)}
+${chalk.red.bold(`!!! CRITICAL: ${bySeverity.critical || 0}`)}
+${chalk.red(`!!  SERIOUS:  ${bySeverity.serious || 0}`)}
+${chalk.yellow(`!   MODERATE: ${bySeverity.moderate || 0}`)}
+${chalk.blue(`i   MINOR:    ${bySeverity.minor || 0}`)}
+${chalk.dim(`Total issues: ${totalViolations}`)}
+`;
+    console.log(boxen(summaryText.trim(), {
+        padding: 1,
+        margin: 1,
+        borderStyle: 'round',
+        borderColor: score >= 75 ? 'green' : score >= 50 ? 'yellow' : 'red',
+        title: 'Scan Results',
+        titleAlignment: 'center',
+    }));
+}
+export function printSuccess(message) {
+    console.log(chalk.green('✓ ') + message);
+}
+export function printError(message) {
+    console.log(chalk.red('✗ ') + message);
+}
+export function printWarning(message) {
+    console.log(chalk.yellow('⚠ ') + message);
+}
+export function printInfo(message) {
+    console.log(chalk.blue('ℹ ') + message);
+}
+export function printDiff(oldCode, newCode) {
+    console.log(chalk.red(`  - ${oldCode}`));
+    console.log(chalk.green(`  + ${newCode}`));
+}
+export function printFixPrompt(file, line, issue) {
+    console.log();
+    console.log(chalk.cyan.bold(`📝 Fixing: ${file}:${line}`));
+    console.log(chalk.dim(`   Issue: ${issue}`));
+    console.log();
+}
+export function printScoreChange(before, after) {
+    const diff = after - before;
+    const diffStr = diff > 0 ? chalk.green(`+${diff}`) : chalk.red(`${diff}`);
+    console.log(boxen(`Score: ${before} → ${chalk.bold(after.toString())} (${diffStr})`, {
+        padding: { top: 0, bottom: 0, left: 1, right: 1 },
+        borderStyle: 'round',
+        borderColor: diff > 0 ? 'green' : 'red',
+    }));
+}
+/**
+ * Animate score counting up - creates memorable visual feedback
+ */
+export async function animateScoreUp(from, to) {
+    if (noColor || from >= to) {
+        // No animation in no-color mode or if score didn't improve
+        printScoreBadge(to);
+        return;
+    }
+    const frames = Math.min(to - from, 20); // Max 20 frames
+    const step = (to - from) / frames;
+    const delay = 50; // 50ms per frame
+    for (let i = 0; i <= frames; i++) {
+        const current = Math.round(from + (step * i));
+        process.stdout.write(`\r${getScoreBar(current)}`);
+        await sleep(delay);
+    }
+    console.log(); // New line after animation
+    printScoreBadge(to);
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function getScoreBar(score) {
+    const width = 30;
+    const filled = Math.round((score / 100) * width);
+    const empty = width - filled;
+    const color = score >= 90 ? chalk.green
+        : score >= 75 ? chalk.yellow
+            : score >= 50 ? chalk.hex('#FFA500')
+                : chalk.red;
+    const bar = color('█'.repeat(filled)) + chalk.gray('░'.repeat(empty));
+    const scoreText = color.bold(`${score}%`);
+    return `  ${bar} ${scoreText}`;
+}
+export function printScoreBadge(score) {
+    const emoji = score >= 90 ? '🌟'
+        : score >= 75 ? '✅'
+            : score >= 50 ? '⚠️'
+                : '❌';
+    const color = score >= 90 ? chalk.green
+        : score >= 75 ? chalk.yellow
+            : score >= 50 ? chalk.hex('#FFA500')
+                : chalk.red;
+    console.log(boxen(`${emoji} Accessibility Score: ${color.bold(`${score}/100`)}`, {
+        padding: { top: 0, bottom: 0, left: 1, right: 1 },
+        borderStyle: 'round',
+        borderColor: score >= 75 ? 'green' : score >= 50 ? 'yellow' : 'red',
+    }));
+}
+export function printFileHeader(file, violationCount, absolutePath) {
+    const color = violationCount > 0 ? chalk.yellow : chalk.green;
+    // Use absolute path for the hyperlink if available
+    const linkPath = absolutePath || file;
+    const linkedFile = fileLink(linkPath);
+    console.log(color.bold(`\n📄 `) + color.bold(linkedFile));
+    if (violationCount > 0) {
+        console.log(chalk.dim(`   ${violationCount} issue${violationCount === 1 ? '' : 's'} found`));
+    }
+    else {
+        console.log(chalk.green.dim('   No issues found'));
+    }
+}

package/mcp-server/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Ally MCP Server
+ *
+ * Exposes project-specific accessibility patterns to GitHub Copilot CLI.
+ * This enables Copilot to generate fixes that are consistent with your codebase.
+ */
+export {};