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_...

📝 Example output

   ♿  A11Y COMMIT VALIDATOR  v2.0.0
   🤖  Powered by Groq AI

✔ Found 1 file(s) to scan

  📄 src/components/ProductCard.jsx

  Scanning files:
  [01/01]  ██████████████████████████████  100%  ProductCard.jsx

✖ Scan complete — 1 issue(s) found!

  Summary: 0 Critical  1 Warning  0 Info  (1 total)
           🔧 1 auto-fixable

  [01] 🟡  WARNING   jsx-a11y/img-redundant-alt  Line 42
       src/components/ProductCard.jsx
       Why  Screen reader users hear "image" announced twice when alt
            text includes the word "image" or "photo".
       Fix  <img src={product.image} alt={product.title} className="card__img" />

  🔧 AUTO-FIX AVAILABLE
  1 issue(s) can be fixed automatically — you will be prompted next.

  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

🔧 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.}