a11y-commit-validator ♿

The accessibility guardian for your Git workflow.
Automatically scans staged HTML, JSX, JS and Liquid files for WCAG violations before every commit — powered by axe-core, eslint-plugin-jsx-a11y, and optional GitHub Copilot AI fix suggestions.

✨ Features

• ♿ WCAG 2.0 / 2.1 / 2.2 Compliance — Full audit via axe-core for HTML files
• ⚛️ React / JSX Support — AST-level analysis with eslint-plugin-jsx-a11y
• 💧 Liquid Template Support — Regex-based rules for Shopify / Liquid files
• 🤖 GitHub Copilot AI Suggestions — Contextual WHY + FIX for every violation
• 🔧 Auto-Fix Mode — Automatically patches fixable issues and re-stages them
• 🎨 Beautiful Terminal UI — Animated spinners, coloured output, progress bar
• 🛡️ Zero Config — Works out of the box, no .eslintrc or config files needed
• 🔌 Husky / pre-commit ready — Drop-in integration with any Git hook tool

What it does

Every time you run git commit, this tool:

1. Detects which .html, .jsx, .js, and .liquid files you've staged
2. Scans them for WCAG 2.1 / 2.2 accessibility violations using:
   • axe-core (deep audit for HTML via jsdom)
   • eslint-plugin-jsx-a11y (AST-level JSX/React analysis)
   • Regex rules (custom patterns for Liquid + extra JSX checks)
3. Explains every issue and suggests a fix (via GitHub Copilot AI or built-in rules)
4. Blocks the commit if issues are found — and optionally auto-fixes them

🚀 Installation

# Install as a dev dependency (recommended)
npm install --save-dev a11y-commit-validator

# Or install globally
npm install -g a11y-commit-validator

⚙️ Setup

Option 1 — Husky (recommended)

npx husky install
npx husky add .husky/pre-commit "npx validate-a11y"

Or add it directly in .husky/pre-commit:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx validate-a11y

Option 2 — Manual pre-commit hook

Create .git/hooks/pre-commit:

#!/bin/sh
npx validate-a11y

Make it executable:

chmod +x .git/hooks/pre-commit

Option 3 — npm script

Add to package.json:

{
  "scripts": {
    "validate-a11y": "validate-a11y"
  }
}

🔄 Workflow

git add .                  ← Stage your files
    │
    ▼
git commit -m "..."        ← Triggers the validator automatically
    │
    ▼
♿ a11y-commit-validator scans staged files
    │
    ├── ✅ No issues?  → Commit goes through
    └── ❌ Issues found? → Commit BLOCKED
                           Fix issues → git add . → git commit again

📋 Rules checked

Plus all axe-core WCAG 2.0/2.1/2.2 rules for HTML files, and all jsx-a11y recommended rules for JSX/JS files.

📂 Supported file types

🤖 GitHub Copilot AI suggestions (optional)

When a GITHUB_TOKEN is set, every violation gets a contextual AI explanation (WHY it harms users) and a corrected code snippet (FIX).

Step 1 — Create a .env file at your project root:

GITHUB_TOKEN=ghp_your_token_here

Getting your token:

1. Go to github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Select scope: read:user is sufficient
4. Copy and paste into .env

Step 2 (optional) — Choose a different AI model:

A11Y_COPILOT_MODEL=gpt-4o

No token? The tool still works — it uses built-in rule-based suggestions instead. AI is fully optional.

📝 Example output

                                              
   ♿  A11Y COMMIT VALIDATOR  v1.0.0          
                                              

✔ Found 2 file(s) to scan

  📄 src/index.html
  📄 components/Button.jsx

  Scanning files:

  [01/02]  ████████████████░░░░░░░░░░░░░░  53%  index.html
  [02/02]  ██████████████████████████████  100%  Button.jsx

✖ Scan complete — 2 issue(s) found!

♿ Accessibility Issues Found (2):

────────────────────────────────────────────────────────────
[1] img-missing-alt
    File    : src/index.html
    Issue   : <img> tag missing alt attribute
    Found   : <img src="banner.jpg" class="hero">
    WCAG    : wcag2a, wcag111
    Why     : Screen readers skip images without alt text, making content
              completely invisible to visually impaired users.
    Fix     : <img src="banner.jpg" class="hero" alt="Hero banner">

[2] jsx-a11y/anchor-is-valid
    File    : components/Button.jsx
    Issue   : Anchors must have content and the content must be accessible
    Found   : Line 14, Col 5
────────────────────────────────────────────────────────────

[a11y] ✖ Accessibility issues found. Commit blocked.
[a11y]   Fix the issues above, then re-run: git add . && git commit

🔧 Troubleshooting

Error: No staged files detected

[a11y] Could not get staged files — skipping.

Make sure you've run git add <file> before committing. The tool only scans staged files.

Error: SSL certificate issue (corporate networks)

npm error UNABLE_TO_GET_ISSUER_CERT_LOCALLY

Run once: npm config set strict-ssl false

Error: Copilot API unavailable

⚠️  Copilot API unavailable — using built-in suggestions.

Check your GITHUB_TOKEN in .env. The tool falls back to built-in suggestions automatically — no action needed.

Liquid files not being scanned

Only .liquid files that are staged (git add) are scanned. Unstaged files are skipped by design.

🔌 Programmatic API

// Run the full pre-commit check programmatically
const { run } = require('a11y-commit-validator');
await run();

// Scan a single file and get raw issues
const { scanFile } = require('a11y-commit-validator/src/scanner');
const issues = await scanFile('src/index.html');
console.log(issues);
// [{ file, ruleId, description, match, wcag }]

// Enhance issues with Copilot AI suggestions
const { enhanceWithCopilot } = require('a11y-commit-validator/src/copilot');
const enhanced = await enhanceWithCopilot(issues);
// [{ ...issue, copilotWhy, copilotFix }]

📈 Roadmap

• VS Code extension integration
• Support for Vue .vue single-file components
• WCAG 3.0 rules (when finalised)
• Custom rule configuration via .a11yrc.json
• CI/CD mode (GitHub Actions support)
• Auto-fix for all rule types

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Stage your changes: git add .
4. Commit: git commit -m "Add my feature"
5. Push: git push origin feature/my-feature
6. Open a Pull Request

📋 Requirements

• Node.js: >= 16.0.0
• Git: Any recent version
• GitHub Token: Optional — only needed for AI-powered suggestions

📜 License

MIT — Rohit Sarkar

Made with ♿ for a more accessible web.
Every commit counts. Make it accessible.