A11y Codemod

A powerful codemod tool that automatically fixes accessibility (a11y) issues reported by ESLint. This tool helps developers maintain accessible web applications by automatically applying common accessibility fixes to React/JSX/TypeScript code.

Features

• 🔧 Automatic Fixes: Automatically fixes common accessibility issues
• 🎯 ESLint Integration: Targets issues commonly reported by eslint-plugin-jsx-a11y
• 📁 Batch Processing: Process multiple files with glob patterns
• 🔍 Dry Run Mode: Preview changes before applying them
• 📊 Detailed Reporting: Get comprehensive reports of what was fixed
• 🧪 Tested: Includes comprehensive test suite
• 🌐 Global Tool: Install once, use anywhere
• ⚡ Zero Config: Works out of the box with sensible defaults

Supported Accessibility Rules

| Rule | Description | Fix Applied | |------|-------------|-------------| | alt-text | Missing alt attributes on images | Adds empty alt="" attribute | | aria-label | Missing ARIA labels on interactive elements | Adds aria-label attributes | | click-events-have-key-events | Clickable elements without keyboard support | Adds role="button" and tabIndex="0" | | label-has-associated-control | Form inputs without proper labels | Adds id and aria-label attributes | | heading-order | Heading hierarchy violations | Adds TODO comments for manual review | | interactive-supports-focus | Interactive elements without proper focus | Adds appropriate roles and tabIndex | | color-contrast | Potential color contrast issues | Adds TODO comments for manual verification |

Installation

Global Installation (Recommended)

npm install -g a11y-codemod

Local Installation

npm install --save-dev a11y-codemod

Usage

Quick Start

The easiest way to use a11y-codemod is to run it in your project directory. It will automatically process all files matching src/**/*.{js,jsx,ts,tsx}:

# Navigate to your project directory
cd your-project

# Preview changes (dry run)
a11y-codemod

# Apply fixes
a11y-codemod --write

Command Line Interface

Fix Accessibility Issues

# Use default pattern (src/**/*.{js,jsx,ts,tsx})
a11y-codemod --write

# Custom pattern
a11y-codemod "components/**/*.jsx" --write

# Dry run (preview changes without applying them)
a11y-codemod --dry-run

# Verbose output
a11y-codemod --write --verbose

Check for Issues

# Check with default pattern
a11y-codemod check

# Check with custom pattern
a11y-codemod check "src/**/*.tsx"

# Verbose output
a11y-codemod check --verbose

List Supported Rules

a11y-codemod rules

Get Help

a11y-codemod --help

Programmatic Usage

const { transformFile, processFiles } = require('a11y-codemod');

// Transform a single file
const transformedCode = transformFile('./src/MyComponent.jsx');

// Process multiple files
const results = processFiles('src/**/*.{js,jsx,ts,tsx}');

Examples

Before (with accessibility issues)

import React from 'react';

function MyComponent() {
  return (
    <div>
      {/* Missing alt attribute */}
      <img src="profile.jpg" />
      
      {/* Missing aria-label */}
      <button onClick={handleClick}>Save</button>
      
      {/* Clickable div without proper accessibility */}
      <div onClick={handleClick}>Click me</div>
      
      {/* Input without proper label */}
      <input type="text" placeholder="Enter your name" />
    </div>
  );
}

After (automatically fixed)

import React from 'react';

function MyComponent() {
  return (
    <div>
      {/* Fixed: Added alt attribute */}
      <img src="profile.jpg" alt="" />
      
      {/* Fixed: Added aria-label */}
      <button onClick={handleClick} aria-label="button element">Save</button>
      
      {/* Fixed: Added role and tabIndex */}
      <div onClick={handleClick} role="button" tabIndex={0}>Click me</div>
      
      {/* Fixed: Added id and aria-label */}
      <input type="text" placeholder="Enter your name" id="input-abc123def" aria-label="Input field" />
    </div>
  );
}

Configuration

The codemod can be configured through options:

const options = {
  verbose: true,        // Show detailed output
  checkOnly: false,     // Only check, don't fix
  customRules: {        // Custom rule configurations
    'alt-text': {
      defaultAlt: 'Image'  // Custom default alt text
    }
  }
};

const results = processFiles('src/**/*.jsx', options);

Integration with ESLint

This codemod is designed to work alongside eslint-plugin-jsx-a11y. Here's how to integrate them:

1. Install ESLint plugin:

   npm install --save-dev eslint-plugin-jsx-a11y

2. Configure ESLint (.eslintrc.js):

   module.exports = {
     extends: ['plugin:jsx-a11y/recommended'],
     plugins: ['jsx-a11y'],
     rules: {
       // Customize rules as needed
       'jsx-a11y/alt-text': 'error',
       'jsx-a11y/aria-label': 'error',
       // ... other rules
     }
   };

3. Run ESLint to identify issues:

   npx eslint src/ --ext .js,.jsx,.ts,.tsx

4. Fix issues automatically:

   a11y-codemod fix "src/**/*.{js,jsx,ts,tsx}" --write

Best Practices

1. Always run in dry-run mode first to preview changes
2. Review generated TODO comments for manual fixes
3. Test your application after applying fixes
4. Use with version control to easily review and revert changes
5. Combine with ESLint for comprehensive accessibility checking

Limitations

• Manual Review Required: Some issues (like color contrast) require manual verification
• Context Awareness: The tool may not understand the full context of your application
• Custom Components: May not handle all custom component patterns
• Complex Interactions: Some accessibility issues require human judgment

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone the repository
git clone <repository-url>
cd a11y-codemod

# Install dependencies
npm install

# Run tests
npm test

# Run linting
npm run lint

Adding New Rules

To add support for new accessibility rules:

1. Create a new transform function in src/index.js
2. Add it to the applyAccessibilityTransforms function
3. Add test cases in tests/index.test.js
4. Update the documentation

License

MIT License - see LICENSE file for details.

Support

If you encounter any issues or have questions, please file an issue on GitHub.

Publishing to npm

To publish this package to npm:

1. Build the project:

   npm run build

2. Test the package locally:

   # Test the CLI
   node dist/cli.js --help
   node dist/cli.js --dry-run
      
   # Run tests
   npm test

3. Publish to npm:

   # Login to npm (if not already logged in)
   npm login
      
   # Publish the package
   npm publish

4. Install globally from npm:

   npm install -g a11y-codemod

Development

Setup

# Clone the repository
git clone <repository-url>
cd a11y-codemod

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run linting
npm run lint

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Watch mode for development
• npm test - Run test suite
• npm run lint - Lint TypeScript files
• npm run prepublishOnly - Build before publishing

Note: This tool provides automated fixes for common accessibility issues, but it's not a substitute for proper accessibility testing and human review. Always test your applications with screen readers and other accessibility tools.