a11y-pilot 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 a11y-pilot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,281 @@
+# 🛫 a11y-pilot
+
+> **Your accessibility co-pilot for the terminal.**
+> AI-powered CLI that scans frontend codebases for accessibility issues and auto-fixes them using GitHub Copilot CLI.
+
+<p align="center">
+  <img src="docs/banner.png" alt="a11y-pilot banner" width="700" />
+</p>
+
+---
+
+## What is a11y-pilot?
+
+**a11y-pilot** is a CLI tool that works like ESLint for accessibility. Run it in any frontend project directory to:
+
+1. **Scan** your HTML, JSX, and TSX files for accessibility violations
+2. **Report** issues with file, line number, severity, and WCAG references
+3. **Auto-fix** issues by invoking GitHub Copilot CLI as the refactoring engine
+
+It catches real problems that affect real users — missing alt text, non-semantic buttons, unlabeled form inputs, broken heading hierarchies, and more.
+
+## Why?
+
+**95%+ of websites fail basic accessibility checks** ([WebAIM Million Report](https://webaim.org/projects/million/)). Most developers don't skip accessibility on purpose — they just don't have the tools that make it easy. a11y-pilot brings a11y linting right into your terminal workflow, and uses Copilot CLI to fix issues intelligently.
+
+---
+
+## Quick Start
+
+```bash
+# Clone the repo
+git clone https://github.com/YOUR_USERNAME/a11y-pilot.git
+cd a11y-pilot
+npm install
+
+# Scan the test fixtures
+node bin/a11y-pilot.js scan test/fixtures/
+
+# Scan your own project
+node bin/a11y-pilot.js scan /path/to/your/frontend/src
+
+# Show Copilot CLI fix commands
+node bin/a11y-pilot.js scan ./src --fix
+
+# Auto-fix with Copilot CLI (requires copilot CLI installed)
+node bin/a11y-pilot.js fix ./src
+
+# Or use the scan command with --auto-fix
+node bin/a11y-pilot.js scan ./src --auto-fix
+```
+
+### Install Globally (optional)
+
+```bash
+npm link
+a11y-pilot scan ./src
+```
+
+---
+
+## Commands
+
+### `scan [path]`
+
+Scan files for accessibility issues.
+
+```bash
+a11y-pilot scan                      # Scan current directory
+a11y-pilot scan ./src/components     # Scan specific directory
+a11y-pilot scan ./src/App.tsx        # Scan a single file
+```
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `-r, --rules <rules>` | Comma-separated rule IDs to check (e.g., `img-alt,no-div-button`) |
+| `-f, --format <format>` | Output format: `text` (default) or `json` |
+| `--fix` | Show Copilot CLI commands for each issue |
+| `--auto-fix` | Invoke Copilot CLI to auto-fix issues |
+| `--dry-run` | Preview what auto-fix would do (no changes) |
+| `--one-by-one` | Fix issues individually instead of batching |
+
+### `fix [path]`
+
+Convenience command — scans and auto-fixes in one step.
+
+```bash
+a11y-pilot fix ./src
+a11y-pilot fix ./src --dry-run
+```
+
+### `rules`
+
+List all available accessibility rules.
+
+```bash
+a11y-pilot rules
+```
+
+---
+
+## Rules
+
+a11y-pilot ships with 8 high-impact accessibility rules:
+
+| Rule | Severity | WCAG | What it catches |
+|------|----------|------|----------------|
+| `img-alt` | error | 1.1.1 | `<img>` without `alt` attribute |
+| `button-content` | error | 4.1.2 | Empty `<button>` with no text/aria-label |
+| `no-div-button` | error | 4.1.2, 2.1.1 | `<div>`/`<span>` with `onClick` but no `role`/`tabIndex` |
+| `form-label` | error | 1.3.1, 4.1.2 | `<input>` without associated label or `aria-label` |
+| `heading-order` | warning | 1.3.1 | Skipped heading levels (h1 → h3) |
+| `anchor-content` | error | 2.4.4, 4.1.2 | `<a>` with no text content or `aria-label` |
+| `no-autofocus` | warning | 3.2.1 | Usage of `autoFocus` attribute |
+| `semantic-nav` | warning | 1.3.1, 2.4.1 | Navigation links not wrapped in `<nav>` |
+
+---
+
+## Copilot CLI Integration
+
+a11y-pilot uses GitHub Copilot CLI as its AI-powered fix engine. When you run `--auto-fix` or `a11y-pilot fix`:
+
+1. **Detection** — a11y-pilot scans your code and identifies issues
+2. **Prompt Engineering** — For each issue, it builds a precise, context-rich prompt
+3. **Copilot Invocation** — It spawns `copilot` CLI with the fix prompt
+4. **Intelligent Fixing** — Copilot CLI reads your file, understands the context, and makes the fix
+5. **Progress Reporting** — You see real-time status of each fix
+
+### How it works under the hood
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   a11y-pilot    │────▶│  Issue detected   │────▶│  Build prompt   │
+│   scanner       │     │  (rule engine)    │     │  (context-rich) │
+└─────────────────┘     └──────────────────┘     └────────┬────────┘
+                                                          │
+                                                          ▼
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   File fixed!   │◀────│  Copilot applies  │◀────│  copilot CLI    │
+│   ✔ Report      │     │  the fix          │     │  invoked        │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+```
+
+### Prerequisites
+
+- [GitHub Copilot CLI](https://github.com/github/copilot-cli) installed and authenticated
+- Node.js 18+
+
+```bash
+# Install Copilot CLI
+# See: https://github.com/github/copilot-cli
+
+# Authenticate
+copilot auth login
+```
+
+---
+
+## JSON Output (CI-friendly)
+
+```bash
+a11y-pilot scan ./src --format json
+```
+
+Outputs structured JSON:
+
+```json
+{
+  "version": "1.0.0",
+  "timestamp": "2026-02-14T10:00:00.000Z",
+  "summary": {
+    "filesScanned": 23,
+    "filesWithIssues": 5,
+    "totalErrors": 12,
+    "totalWarnings": 3,
+    "totalIssues": 15
+  },
+  "files": {
+    "src/Hero.tsx": [
+      {
+        "ruleId": "img-alt",
+        "severity": "error",
+        "message": "<img> is missing the `alt` attribute",
+        "line": 12,
+        "fix": "Add alt=\"descriptive text\" or alt=\"\" if decorative",
+        "copilotCommand": "copilot \"In file src/Hero.tsx at line 12...\""
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Supported File Types
+
+| Extension | Parser |
+|-----------|--------|
+| `.jsx` | Babel (JSX) |
+| `.tsx` | Babel (TSX + TypeScript) |
+| `.html`, `.htm` | htmlparser2 |
+| `.vue` | htmlparser2 (template) |
+| `.svelte` | htmlparser2 (template) |
+| `.astro` | htmlparser2 (template) |
+
+---
+
+## Project Structure
+
+```
+a11y-pilot/
+├── bin/
+│   └── a11y-pilot.js            # CLI entry point
+├── src/
+│   ├── cli.js                   # Commander setup & orchestration
+│   ├── scanner.js               # File discovery & walking
+│   ├── parsers/
+│   │   ├── jsx-parser.js        # JSX/TSX AST parsing
+│   │   └── html-parser.js       # HTML parsing
+│   ├── rules/
+│   │   ├── index.js             # Rule registry
+│   │   ├── img-alt.js           # Missing alt attributes
+│   │   ├── button-content.js    # Empty buttons
+│   │   ├── no-div-button.js     # Non-semantic click handlers
+│   │   ├── form-label.js        # Unlabeled form inputs
+│   │   ├── heading-order.js     # Heading hierarchy
+│   │   ├── anchor-content.js    # Empty links
+│   │   ├── no-autofocus.js      # autoFocus anti-pattern
+│   │   └── semantic-nav.js      # Missing <nav> landmarks
+│   ├── reporter.js              # Terminal output (colors/formatting)
+│   └── copilot-bridge.js        # Copilot CLI invocation engine
+├── test/
+│   └── fixtures/                # Sample files with a11y issues
+├── docs/
+│   └── PLAN.md                  # Project plan
+├── package.json
+├── LICENSE
+└── README.md
+```
+
+---
+
+## Built With GitHub Copilot CLI
+
+This entire project was built using GitHub Copilot CLI as a core development tool. Copilot CLI was used for:
+
+- Scaffolding the project structure
+- Writing parser logic for JSX/TSX AST traversal
+- Implementing accessibility rules with WCAG references
+- Debugging edge cases in HTML parsing
+- Generating test fixtures
+- Writing documentation
+
+See the [submission article](#) for terminal screenshots and a full walkthrough.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+## Contributing
+
+Contributions welcome! Ideas for new rules, parser improvements, or better Copilot CLI integration are all appreciated.
+
+```bash
+# Run tests
+npm test
+
+# Scan the test fixtures during development
+node bin/a11y-pilot.js scan test/fixtures/
+```
+
+---
+
+<p align="center">
+  <strong>a11y-pilot</strong> — Making the web accessible, one terminal command at a time. 🛫
+</p>

package/bin/a11y-pilot.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { cli } from '../src/cli.js';
+
+cli(process.argv);

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "a11y-pilot",
+  "version": "1.0.0",
+  "description": "AI-powered accessibility scanner that uses GitHub Copilot CLI to auto-fix a11y issues in frontend codebases",
+  "main": "src/cli.js",
+  "bin": {
+    "a11y-pilot": "./bin/a11y-pilot.js"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/a11y-pilot.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "node bin/a11y-pilot.js --help"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "copilot",
+    "cli",
+    "scanner",
+    "wcag",
+    "aria",
+    "semantic-html",
+    "github-copilot",
+    "lint",
+    "a11y-lint",
+    "copilot-cli",
+    "keyboard-navigation",
+    "screen-reader"
+  ],
+  "author": "Safvan <github.com/Safvan-tsy>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Safvan-tsy/a11y-pilot.git"
+  },
+  "homepage": "https://github.com/Safvan-tsy/a11y-pilot#readme",
+  "bugs": {
+    "url": "https://github.com/Safvan-tsy/a11y-pilot/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.29.0",
+    "@babel/traverse": "^7.29.0",
+    "boxen": "^8.0.1",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "diff": "^8.0.3",
+    "figures": "^6.1.0",
+    "gradient-string": "^3.0.0",
+    "htmlparser2": "^10.1.0",
+    "log-symbols": "^7.0.1",
+    "ora": "^9.3.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,324 @@
+import { Command } from 'commander';
+import path from 'path';
+import chalk from 'chalk';
+import { walkDir, readFileSafe, getFileType, relativePath } from './scanner.js';
+import { parseJSX, collectJSXElements, collectHeadings } from './parsers/jsx-parser.js';
+import { parseHTML, collectHTMLHeadings } from './parsers/html-parser.js';
+import { allRules, getRules } from './rules/index.js';
+import {
+  printBanner,
+  printScanStart,
+  printFileIssues,
+  printSummary,
+  printFixPrompt,
+  printRulesList,
+  printJSON,
+  printError,
+  printInfo,
+} from './reporter.js';
+import { autoFixAll, generateFixCommand } from './copilot-bridge.js';
+
+/**
+ * Analyze a single file and return all issues found
+ * @param {string} filePath - Absolute file path
+ * @param {object[]} rules - Rules to check
+ * @returns {object[]} Issues found
+ */
+function analyzeFile(filePath, rules) {
+  const code = readFileSafe(filePath);
+  if (!code) return [];
+
+  const fileType = getFileType(filePath);
+  let elements = [];
+  let headings = [];
+
+  // Parse based on file type
+  if (fileType === 'jsx') {
+    const ast = parseJSX(code, filePath);
+    if (!ast) return [];
+    elements = collectJSXElements(ast, code);
+    headings = collectHeadings(elements);
+  } else if (fileType === 'html') {
+    elements = parseHTML(code);
+    headings = collectHTMLHeadings(elements);
+  } else {
+    return [];
+  }
+
+  const issues = [];
+
+  // Run element-level rules
+  for (const element of elements) {
+    for (const rule of rules) {
+      const issue = rule.check(element);
+      if (issue) {
+        issues.push(issue);
+      }
+    }
+  }
+
+  // Run file-level rules
+  for (const rule of rules) {
+    // Heading order check
+    if (rule.id === 'heading-order' && rule.checkHeadings) {
+      const headingIssues = rule.checkHeadings(headings);
+      issues.push(...headingIssues);
+    }
+
+    // Semantic nav check
+    if (rule.id === 'semantic-nav' && rule.checkNavPatterns) {
+      const navIssues = rule.checkNavPatterns(elements, code);
+      issues.push(...navIssues);
+    }
+  }
+
+  // Sort by line number
+  issues.sort((a, b) => a.line - b.line);
+
+  return issues;
+}
+
+/**
+ * Main CLI entry point
+ * @param {string[]} argv
+ */
+export function cli(argv) {
+  const program = new Command();
+
+  program
+    .name('a11y-pilot')
+    .description(
+      'AI-powered accessibility scanner that uses GitHub Copilot CLI to auto-fix a11y issues'
+    )
+    .version('1.0.0');
+
+  // ─── scan command ──────────────────────────────────────────────────────────
+  program
+    .command('scan')
+    .description('Scan files for accessibility issues')
+    .argument('[path]', 'Path to scan (file or directory)', '.')
+    .option('-r, --rules <rules>', 'Comma-separated list of rule IDs to check')
+    .option('-f, --format <format>', 'Output format: text or json', 'text')
+    .option('--fix', 'Show Copilot CLI fix commands for each issue')
+    .option('--auto-fix', 'Automatically invoke Copilot CLI to fix issues')
+    .option('--dry-run', 'Show what auto-fix would do without executing')
+    .option('--one-by-one', 'Fix issues one at a time (instead of batching per file)')
+    .action(async (targetPath, options) => {
+      const absolutePath = path.resolve(process.cwd(), targetPath);
+
+      // Get rules
+      const ruleIds = options.rules ? options.rules.split(',').map(s => s.trim()) : null;
+      const rules = getRules(ruleIds);
+
+      if (rules.length === 0) {
+        printError('No matching rules found. Run `a11y-pilot rules` to see available rules.');
+        process.exit(1);
+      }
+
+      // JSON format doesn't get the banner
+      if (options.format !== 'json') {
+        printBanner();
+      }
+
+      // Discover files
+      const files = walkDir(absolutePath);
+
+      if (files.length === 0) {
+        if (options.format !== 'json') {
+          printError(`No scannable files found in ${targetPath}`);
+          printInfo('Supported extensions: .html, .htm, .jsx, .tsx, .vue, .astro, .svelte');
+        }
+        process.exit(1);
+      }
+
+      if (options.format !== 'json') {
+        printScanStart(files.length);
+      }
+
+      // Analyze all files
+      const allIssues = new Map(); // filePath → issues[]
+      let totalErrors = 0;
+      let totalWarnings = 0;
+      let filesWithIssues = 0;
+
+      for (const file of files) {
+        const issues = analyzeFile(file, rules);
+
+        if (issues.length > 0) {
+          allIssues.set(file, issues);
+          filesWithIssues++;
+          totalErrors += issues.filter(i => i.severity === 'error').length;
+          totalWarnings += issues.filter(i => i.severity === 'warning').length;
+        }
+      }
+
+      // ─── Output results ─────────────────────────────────────────────────
+      if (options.format === 'json') {
+        const report = {
+          version: '1.0.0',
+          timestamp: new Date().toISOString(),
+          summary: {
+            filesScanned: files.length,
+            filesWithIssues,
+            totalErrors,
+            totalWarnings,
+            totalIssues: totalErrors + totalWarnings,
+          },
+          files: {},
+        };
+
+        for (const [filePath, issues] of allIssues) {
+          report.files[relativePath(filePath)] = issues.map(i => ({
+            ruleId: i.ruleId,
+            severity: i.severity,
+            message: i.message,
+            line: i.line,
+            fix: i.fix,
+            copilotCommand: generateFixCommand(filePath, i),
+          }));
+        }
+
+        printJSON(report);
+        process.exit(totalErrors > 0 ? 1 : 0);
+        return;
+      }
+
+      // Text output
+      if (options.autoFix || options.fix) {
+        // Show issues first
+        for (const [filePath, issues] of allIssues) {
+          printFileIssues(relativePath(filePath), issues);
+        }
+
+        printSummary({
+          errors: totalErrors,
+          warnings: totalWarnings,
+          files: filesWithIssues,
+          totalFiles: files.length,
+        });
+      }
+
+      // Auto-fix mode (Option B — the main event!)
+      if (options.autoFix) {
+        if (allIssues.size === 0) {
+          // Nothing to fix
+          process.exit(0);
+          return;
+        }
+
+        const { totalFixed, totalFailed } = await autoFixAll(allIssues, {
+          dryRun: options.dryRun,
+          oneByOne: options.oneByOne,
+        });
+
+        process.exit(totalFailed > 0 ? 1 : 0);
+        return;
+      }
+
+      // --fix mode: show copilot CLI commands
+      if (options.fix) {
+        if (allIssues.size > 0) {
+          console.log('');
+          printInfo('Copilot CLI fix commands:\n');
+
+          for (const [filePath, issues] of allIssues) {
+            for (const issue of issues) {
+              printFixPrompt(relativePath(filePath), issue);
+            }
+          }
+        }
+
+        process.exit(totalErrors > 0 ? 1 : 0);
+        return;
+      }
+
+      // Default: just show issues
+      for (const [filePath, issues] of allIssues) {
+        printFileIssues(relativePath(filePath), issues);
+      }
+
+      printSummary({
+        errors: totalErrors,
+        warnings: totalWarnings,
+        files: filesWithIssues,
+        totalFiles: files.length,
+      });
+
+      process.exit(totalErrors > 0 ? 1 : 0);
+    });
+
+  // ─── rules command ─────────────────────────────────────────────────────────
+  program
+    .command('rules')
+    .description('List all available accessibility rules')
+    .action(() => {
+      printRulesList(allRules);
+    });
+
+  // ─── fix command (convenience alias) ───────────────────────────────────────
+  program
+    .command('fix')
+    .description('Scan and auto-fix issues using GitHub Copilot CLI')
+    .argument('[path]', 'Path to scan (file or directory)', '.')
+    .option('-r, --rules <rules>', 'Comma-separated list of rule IDs to check')
+    .option('--dry-run', 'Show what would be fixed without executing')
+    .option('--one-by-one', 'Fix issues one at a time')
+    .action(async (targetPath, options) => {
+      // Delegate to scan with --auto-fix
+      const absolutePath = path.resolve(process.cwd(), targetPath);
+      const ruleIds = options.rules ? options.rules.split(',').map(s => s.trim()) : null;
+      const rules = getRules(ruleIds);
+
+      printBanner();
+
+      const files = walkDir(absolutePath);
+      if (files.length === 0) {
+        printError(`No scannable files found in ${targetPath}`);
+        process.exit(1);
+      }
+
+      printScanStart(files.length);
+
+      const allIssuesMap = new Map();
+      let totalErrors = 0;
+      let totalWarnings = 0;
+      let filesWithIssues = 0;
+
+      for (const file of files) {
+        const issues = analyzeFile(file, rules);
+        if (issues.length > 0) {
+          allIssuesMap.set(file, issues);
+          filesWithIssues++;
+          totalErrors += issues.filter(i => i.severity === 'error').length;
+          totalWarnings += issues.filter(i => i.severity === 'warning').length;
+        }
+      }
+
+      // Print issues
+      for (const [filePath, issues] of allIssuesMap) {
+        printFileIssues(relativePath(filePath), issues);
+      }
+
+      printSummary({
+        errors: totalErrors,
+        warnings: totalWarnings,
+        files: filesWithIssues,
+        totalFiles: files.length,
+      });
+
+      if (allIssuesMap.size === 0) {
+        process.exit(0);
+        return;
+      }
+
+      // Auto-fix
+      const { totalFixed, totalFailed } = await autoFixAll(allIssuesMap, {
+        dryRun: options.dryRun,
+        oneByOne: options.oneByOne,
+      });
+
+      process.exit(totalFailed > 0 ? 1 : 0);
+    });
+
+  program.parse(argv);
+}