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 Groq AI (free) for intelligent 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
• 🤖 Groq AI Suggestions — Free LLaMA 3.3 70B, 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 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

⚙️ Configuration

Step 1 — Create your .env file

Create a .env file in the root of your project:

# Sign up free at https://console.groq.com — no credit card needed
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

That's it. Groq is completely free — no credit card, no billing, powered by LLaMA 3.3 70B.

Environment Variables Reference

No key? The tool still works — it falls back to built-in rule-based suggestions automatically.

⚙️ Setup

Option 1 — Husky (recommended)

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

Or create .husky/pre-commit manually:

#!/usr/bin/env sh
. "$(dirname "$0")/_/husky.sh"

echo "Running accessibility check..."
npx validate-a11y || exit 1

Make it executable (Mac/Linux): chmod +x .husky/pre-commit

Option 2 — Manual Git hook

#!/usr/bin/env sh
# .git/hooks/pre-commit
npx validate-a11y || exit 1

chmod +x .git/hooks/pre-commit

Option 3 — npm script only

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

🔄 Workflow

git add .                        ← Stage your files
    │
    ▼
git commit -m "your message"     ← Triggers the hook automatically
    │
    ▼
♿  a11y-commit-validator runs
    │
    ├── Detects staged .html / .jsx / .js / .liquid files
    ├── Scans each file for WCAG violations
    ├── Calls Groq AI for WHY + FIX  (falls back to built-in if unavailable)
    │
    ├── ✅ No issues?    → Commit goes through
    └── ❌ Issues found? → Commit BLOCKED
                           Auto-fix or fix manually
                           git add . && git commit again

📋 Rules checked

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

📂 Supported file types

🤖 AI-Powered Analysis

Powered by Groq — free, fast, no credit card required.

For each violation the AI provides:

• WHY — One sentence explaining how this harms disabled users
• FIX — A corrected, ready-to-paste snippet specific to your code

Getting a free Groq key (2 minutes)

1. Go to console.groq.com
2. Sign in with Google or GitHub — no credit card needed
3. Click API Keys → Create API key
4. Paste into your .env as GROQ_API_KEY=gsk_...

�️ See it in action

Drop it in, stage your files, and commit. This is what you'll see:

① Startup & file detection

┌──────────────────────────────────────────────────────────┐
│   ♿  A11Y COMMIT VALIDATOR  v2.0.2                       │
│   🤖  Powered by Groq AI                                  │
└──────────────────────────────────────────────────────────┘

  ✔  Found 2 file(s) to scan

  📄  src/components/ProductCard.jsx
  📄  src/sections/Hero.jsx

② Live scan with progress bar

  Scanning files:

  [01/02]  ████████████████░░░░░░░░░░░░░░  53%  ProductCard.jsx
  [02/02]  ██████████████████████████████  100%  Hero.jsx

  ✖  Scan complete — 3 issue(s) found!  (1 duplicate removed)

③ Groq AI steps in

  🤖  Groq AI is reviewing your accessibility issues...

  ✅  Groq AI analysis complete.

④ Red alert — issues detected

  ////////////////////////////////////////////////////////////////
  //   ♿  ACCESSIBILITY ISSUES DETECTED                         //
  ////////////////////////////////////////////////////////////////

  Summary:  🔴 2 Critical   🟡 1 Warning   🔵 0 Info   (3 total)
            🔧 3 auto-fixable  (AI-enhanced)

⑤ Per-issue breakdown

  ──────────────────────────────────────────────────────────

  [01] 🔴  CRITICAL   jsx-a11y/alt-text   Line 9
       src/components/ProductCard.jsx
       Why  Images without alt text are completely invisible to screen
            readers, locking out millions of visually impaired users.
       Fix  <img src={product.image} alt={product.title} className="card__img" />

  [02] 🔴  CRITICAL   jsx-a11y/click-events-have-key-events   Line 18
       src/components/ProductCard.jsx
       Why  A click-only handler locks out keyboard and switch-device
            users who cannot use a mouse — WCAG 2.1 failure.
       Fix  <div role="button" tabIndex={0} onClick={...} onKeyDown={...}>

  [03] 🟡  WARNING    jsx-a11y/label-has-associated-control   Line 34
       src/sections/Hero.jsx
       Why  A form input with no associated label is unreadable by screen
            readers — users won't know what the field is for.
       Fix  <label htmlFor="email">Email address</label>
            <input id="email" type="email" />

  ──────────────────────────────────────────────────────────

⑥ Interactive auto-fix prompt

  ╔══════════════════════════════╗
  ║  🔧  AUTO-FIX AVAILABLE      ║
  ╚══════════════════════════════╝

  Groq AI has suggested fixes for 3 of the 3 issue(s) found.

  What would you like to do?
    [1]  ✅  Apply all fixes automatically
    [2]  🔍  Review & apply fixes one by one
    [3]  ⏭️  Skip — I'll fix them manually

  Enter choice (1-3):  1

  ✅  Applied 3/3 fix(es) and re-staged the affected file(s).

⑦ All clean

  ✅  ALL ACCESSIBILITY CHECKS PASSED!

  All validators passed! Committing...

🔧 Troubleshooting

No staged files detected

Run git add <file> before committing. Only staged files are scanned.

SSL certificate error (corporate networks)

npm error UNABLE_TO_GET_ISSUER_CERT_LOCALLY

Run once: npm config set strict-ssl false

Groq API unavailable

Falls back to built-in suggestions automatically. No action needed.

🔌 Programmatic API

const { run } = require('a11y-commit-validator');
await run();

const { scanFile } = require('a11y-commit-validator/src/scanner');
const issues = await scanFile('src/index.html');
// [{ file, ruleId, description, match, lineNumber, wcag }]

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

const { applyAllFixes } = require('a11y-commit-validator/src/fixer');
const { applied, failed, total } = applyAllFixes(enhanced);

🆕 What's new in v2.0.0

• 🤖 Groq AI integration — Free LLaMA 3.3 70B, no credit card needed
• Auto-fix engine — Apply AI-suggested fixes from the terminal, files re-staged automatically
• 🎨 Simplified terminal output — Cleaner, focused issue display
• 🐛 Fixed duplicate output bug — HOW TO FIX section prints exactly once
• 🔒 Safer AI fixes — Constrained to single-line changes, prevents broken JSX

📈 Roadmap

• VS Code extension integration
• Support for Vue .vue single-file components
• WCAG 3.0 rules (when finalised)
• Custom rule configuration via .a11yrc.json
• GitHub Actions / CI mode
• Support for .svelte and .astro files

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit: git commit -m "Add my feature"
4. Push and open a Pull Request

📋 Requirements

• Node.js: >= 16.0.0
• Git: Any recent version
• AI Provider: Optional — Groq is free (sign up at console.groq.com)

🙏 Acknowledgments

• axe-core — The gold standard for accessibility auditing
• eslint-plugin-jsx-a11y — AST-level JSX rules
• Groq — Free, blazing-fast LLaMA inference
• The open-source accessibility community

📜 License

MIT

♿ Stop shipping inaccessible code. Catch it before it reaches your users.
Because accessibility isn't a nice-to-have — it's the baseline every developer owes the world.

Built with ❤️ by Rohit Sarkar

_{Every commit counts. Make it accessible.}