|
| 1 | +# eslint-plugin-primer-react |
| 2 | + |
| 3 | +ESLint plugin for Primer React components. This is a JavaScript-based ESLint plugin that provides rules for validating and auto-fixing Primer React component usage. |
| 4 | + |
| 5 | +**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.** |
| 6 | + |
| 7 | +## Working Effectively |
| 8 | + |
| 9 | +### Bootstrap and Setup |
| 10 | + |
| 11 | +- Install Node.js v20+ (v20 is the current standard): |
| 12 | + - Check version: `node --version && npm --version` |
| 13 | +- Install dependencies: `npm ci` -- takes 60 seconds. Set timeout to 90+ seconds. |
| 14 | +- **NO BUILD STEP REQUIRED** - This is a direct JavaScript project with main entry at `src/index.js` |
| 15 | + |
| 16 | +### Development Commands |
| 17 | + |
| 18 | +- Run tests: `npm test` -- takes 5 seconds. Fast, no long timeout needed. |
| 19 | +- Run linting: `npm run lint` -- takes 1.5 seconds. Very fast. |
| 20 | +- Run markdown linting: `npm run lint:md` -- takes under 1 second. Very fast. |
| 21 | +- Check formatting: `npm run format:check` -- takes 0.5 seconds. Very fast. |
| 22 | +- Fix formatting: `npm run format` -- applies Prettier formatting fixes. |
| 23 | + |
| 24 | +### Testing and Validation |
| 25 | + |
| 26 | +- **ALWAYS** run `npm test` after making changes to rules - tests run in 5 seconds |
| 27 | +- **ALWAYS** run `npm run lint && npm run lint:md` before committing - both complete in under 3 seconds total |
| 28 | +- **ALWAYS** run `npm run format:check` to verify formatting - completes in 0.5 seconds |
| 29 | +- All validation commands are very fast - no need for long timeouts or cancellation warnings |
| 30 | + |
| 31 | +### Manual Rule Testing |
| 32 | + |
| 33 | +You can manually test individual rules using this pattern: |
| 34 | + |
| 35 | +```bash |
| 36 | +node -e " |
| 37 | +const rule = require('./src/rules/RULE_NAME'); |
| 38 | +const {RuleTester} = require('eslint'); |
| 39 | +const ruleTester = new RuleTester({ |
| 40 | + parserOptions: { |
| 41 | + ecmaVersion: 'latest', |
| 42 | + sourceType: 'module', |
| 43 | + ecmaFeatures: { jsx: true } |
| 44 | + } |
| 45 | +}); |
| 46 | +ruleTester.run('test', rule, { |
| 47 | + valid: [{ code: 'VALID_CODE_HERE' }], |
| 48 | + invalid: [{ code: 'INVALID_CODE_HERE', errors: [{ messageId: 'MESSAGE_ID' }] }] |
| 49 | +}); |
| 50 | +" |
| 51 | +``` |
| 52 | + |
| 53 | +## Repository Structure and Navigation |
| 54 | + |
| 55 | +### Key Directories |
| 56 | + |
| 57 | +- `src/rules/` - ESLint rule implementations |
| 58 | +- `src/rules/__tests__/` - Jest tests for each rule using ESLint RuleTester |
| 59 | +- `docs/rules/` - Markdown documentation for each rule |
| 60 | +- `src/configs/` - ESLint configuration presets (e.g., recommended.js) |
| 61 | +- `src/utils/` - Utility functions shared across rules |
| 62 | +- `.github/workflows/` - CI pipeline definitions |
| 63 | + |
| 64 | +### Important Files |
| 65 | + |
| 66 | +- `src/index.js` - Main entry point, exports all rules and configs |
| 67 | +- `package.json` - Scripts and dependencies (no build scripts needed) |
| 68 | +- `jest.config.js` - Jest test configuration |
| 69 | +- `.eslintrc.js` - ESLint configuration for the project itself |
| 70 | +- `.nvmrc` - Node.js version specification (v20) |
| 71 | + |
| 72 | +### Rule Development Pattern |
| 73 | + |
| 74 | +Each rule follows this structure: |
| 75 | + |
| 76 | +1. Rule implementation: `src/rules/rule-name.js` |
| 77 | +2. Test file: `src/rules/__tests__/rule-name.test.js` |
| 78 | +3. Documentation: `docs/rules/rule-name.md` |
| 79 | +4. Export from: `src/index.js` (add to rules object) |
| 80 | +5. Optional: Add to `src/configs/recommended.js` if should be in recommended preset |
| 81 | + |
| 82 | +## Validation Scenarios |
| 83 | + |
| 84 | +### After Making Rule Changes |
| 85 | + |
| 86 | +1. Run the rule's specific test: `npm test -- --testNamePattern="rule-name"` |
| 87 | +2. Run all tests: `npm test` (5 seconds) |
| 88 | +3. Test the rule manually using the Node.js snippet pattern above |
| 89 | +4. Verify the rule is exported properly from `src/index.js` |
| 90 | + |
| 91 | +### Before Committing |
| 92 | + |
| 93 | +1. `npm run lint` - JavaScript linting (1.5 seconds) |
| 94 | +2. `npm run lint:md` - Markdown linting (<1 second) |
| 95 | +3. `npm run format:check` - Formatting validation (0.5 seconds) |
| 96 | +4. `npm test` - Full test suite (5 seconds) |
| 97 | + |
| 98 | +### Testing Plugin Integration |
| 99 | + |
| 100 | +The plugin can be tested by: |
| 101 | + |
| 102 | +1. Using manual Node.js rule testing (shown above) |
| 103 | +2. Running existing test suite which validates all rules |
| 104 | +3. Creating test files and using ESLint RuleTester in the **tests** files |
| 105 | + |
| 106 | +## Common Development Tasks |
| 107 | + |
| 108 | +### Adding a New Rule |
| 109 | + |
| 110 | +1. Create rule implementation: `src/rules/new-rule-name.js` |
| 111 | +2. Create test file: `src/rules/__tests__/new-rule-name.test.js` |
| 112 | +3. Add to exports in `src/index.js` |
| 113 | +4. Create documentation: `docs/rules/new-rule-name.md` |
| 114 | +5. Optionally add to `src/configs/recommended.js` |
| 115 | +6. Run tests: `npm test` |
| 116 | +7. Run linting: `npm run lint` |
| 117 | + |
| 118 | +### Modifying Existing Rules |
| 119 | + |
| 120 | +1. Edit rule in `src/rules/rule-name.js` |
| 121 | +2. Update tests in `src/rules/__tests__/rule-name.test.js` |
| 122 | +3. Update documentation in `docs/rules/rule-name.md` if needed |
| 123 | +4. Run tests: `npm test` |
| 124 | +5. Test manually using Node.js snippet if needed |
| 125 | + |
| 126 | +### Working with Changesets (for releases) |
| 127 | + |
| 128 | +- `npx changeset` - Create a changeset for changes |
| 129 | +- `npx changeset status` - Check changeset status |
| 130 | +- Changesets are used for versioning and publishing to npm |
| 131 | + |
| 132 | +## Troubleshooting |
| 133 | + |
| 134 | +### Common Issues |
| 135 | + |
| 136 | +- **Node.js version**: Use Node.js v20+ (v20 is the current standard) |
| 137 | +- **Dependencies**: Always use `npm ci` instead of `npm install` for consistent installs |
| 138 | +- **Test failures**: Run `npm test` to see specific failures - tests are fast and detailed |
| 139 | +- **Lint failures**: Run `npm run lint` and `npm run lint:md` to see specific issues |
| 140 | +- **Format issues**: Run `npm run format` to auto-fix formatting |
| 141 | + |
| 142 | +### Rule Testing Issues |
| 143 | + |
| 144 | +- Use the RuleTester pattern shown above for manual testing |
| 145 | +- Check that messageId in tests matches the rule's meta.messages |
| 146 | +- Verify JSX parsing works by including ecmaFeatures.jsx in parserOptions |
| 147 | + |
| 148 | +## Command Reference |
| 149 | + |
| 150 | +Essential commands and their typical execution times: |
| 151 | + |
| 152 | +- `npm ci` - Install dependencies (60 seconds) |
| 153 | +- `npm test` - Run all tests (5 seconds) |
| 154 | +- `npm run lint` - Lint JavaScript (1.5 seconds) |
| 155 | +- `npm run lint:md` - Lint Markdown (<1 second) |
| 156 | +- `npm run format:check` - Check formatting (0.5 seconds) |
| 157 | +- `npm run format` - Fix formatting (similar time) |
| 158 | + |
| 159 | +All commands except `npm ci` are very fast. No need for extended timeouts or cancellation warnings on validation commands. |
0 commit comments