eslint-plugin-primer-react 8.0.0-rc.d848c88 → 8.1.0-rc.ce584c0

package/.github/copilot-instructions.md

@@ -0,0 +1,159 @@
+# eslint-plugin-primer-react
+
+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.
+
+**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.**
+
+## Working Effectively
+
+### Bootstrap and Setup
+
+- Install Node.js v20+ (v20 is the current standard):
+  - Check version: `node --version && npm --version`
+- Install dependencies: `npm ci` -- takes 60 seconds. Set timeout to 90+ seconds.
+- **NO BUILD STEP REQUIRED** - This is a direct JavaScript project with main entry at `src/index.js`
+
+### Development Commands
+
+- Run tests: `npm test` -- takes 5 seconds. Fast, no long timeout needed.
+- Run linting: `npm run lint` -- takes 1.5 seconds. Very fast.
+- Run markdown linting: `npm run lint:md` -- takes under 1 second. Very fast.
+- Check formatting: `npm run format:check` -- takes 0.5 seconds. Very fast.
+- Fix formatting: `npm run format` -- applies Prettier formatting fixes.
+
+### Testing and Validation
+
+- **ALWAYS** run `npm test` after making changes to rules - tests run in 5 seconds
+- **ALWAYS** run `npm run lint && npm run lint:md` before committing - both complete in under 3 seconds total
+- **ALWAYS** run `npm run format:check` to verify formatting - completes in 0.5 seconds
+- All validation commands are very fast - no need for long timeouts or cancellation warnings
+
+### Manual Rule Testing
+
+You can manually test individual rules using this pattern:
+
+```bash
+node -e "
+const rule = require('./src/rules/RULE_NAME');
+const {RuleTester} = require('eslint');
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    ecmaFeatures: { jsx: true }
+  }
+});
+ruleTester.run('test', rule, {
+  valid: [{ code: 'VALID_CODE_HERE' }],
+  invalid: [{ code: 'INVALID_CODE_HERE', errors: [{ messageId: 'MESSAGE_ID' }] }]
+});
+"
+```
+
+## Repository Structure and Navigation
+
+### Key Directories
+
+- `src/rules/` - ESLint rule implementations
+- `src/rules/__tests__/` - Jest tests for each rule using ESLint RuleTester
+- `docs/rules/` - Markdown documentation for each rule
+- `src/configs/` - ESLint configuration presets (e.g., recommended.js)
+- `src/utils/` - Utility functions shared across rules
+- `.github/workflows/` - CI pipeline definitions
+
+### Important Files
+
+- `src/index.js` - Main entry point, exports all rules and configs
+- `package.json` - Scripts and dependencies (no build scripts needed)
+- `jest.config.js` - Jest test configuration
+- `.eslintrc.js` - ESLint configuration for the project itself
+- `.nvmrc` - Node.js version specification (v20)
+
+### Rule Development Pattern
+
+Each rule follows this structure:
+
+1. Rule implementation: `src/rules/rule-name.js`
+2. Test file: `src/rules/__tests__/rule-name.test.js`
+3. Documentation: `docs/rules/rule-name.md`
+4. Export from: `src/index.js` (add to rules object)
+5. Optional: Add to `src/configs/recommended.js` if should be in recommended preset
+
+## Validation Scenarios
+
+### After Making Rule Changes
+
+1. Run the rule's specific test: `npm test -- --testNamePattern="rule-name"`
+2. Run all tests: `npm test` (5 seconds)
+3. Test the rule manually using the Node.js snippet pattern above
+4. Verify the rule is exported properly from `src/index.js`
+
+### Before Committing
+
+1. `npm run lint` - JavaScript linting (1.5 seconds)
+2. `npm run lint:md` - Markdown linting (<1 second)
+3. `npm run format:check` - Formatting validation (0.5 seconds)
+4. `npm test` - Full test suite (5 seconds)
+
+### Testing Plugin Integration
+
+The plugin can be tested by:
+
+1. Using manual Node.js rule testing (shown above)
+2. Running existing test suite which validates all rules
+3. Creating test files and using ESLint RuleTester in the **tests** files
+
+## Common Development Tasks
+
+### Adding a New Rule
+
+1. Create rule implementation: `src/rules/new-rule-name.js`
+2. Create test file: `src/rules/__tests__/new-rule-name.test.js`
+3. Add to exports in `src/index.js`
+4. Create documentation: `docs/rules/new-rule-name.md`
+5. Optionally add to `src/configs/recommended.js`
+6. Run tests: `npm test`
+7. Run linting: `npm run lint`
+
+### Modifying Existing Rules
+
+1. Edit rule in `src/rules/rule-name.js`
+2. Update tests in `src/rules/__tests__/rule-name.test.js`
+3. Update documentation in `docs/rules/rule-name.md` if needed
+4. Run tests: `npm test`
+5. Test manually using Node.js snippet if needed
+
+### Working with Changesets (for releases)
+
+- `npx changeset` - Create a changeset for changes
+- `npx changeset status` - Check changeset status
+- Changesets are used for versioning and publishing to npm
+
+## Troubleshooting
+
+### Common Issues
+
+- **Node.js version**: Use Node.js v20+ (v20 is the current standard)
+- **Dependencies**: Always use `npm ci` instead of `npm install` for consistent installs
+- **Test failures**: Run `npm test` to see specific failures - tests are fast and detailed
+- **Lint failures**: Run `npm run lint` and `npm run lint:md` to see specific issues
+- **Format issues**: Run `npm run format` to auto-fix formatting
+
+### Rule Testing Issues
+
+- Use the RuleTester pattern shown above for manual testing
+- Check that messageId in tests matches the rule's meta.messages
+- Verify JSX parsing works by including ecmaFeatures.jsx in parserOptions
+
+## Command Reference
+
+Essential commands and their typical execution times:
+
+- `npm ci` - Install dependencies (60 seconds)
+- `npm test` - Run all tests (5 seconds)
+- `npm run lint` - Lint JavaScript (1.5 seconds)
+- `npm run lint:md` - Lint Markdown (<1 second)
+- `npm run format:check` - Check formatting (0.5 seconds)
+- `npm run format` - Fix formatting (similar time)
+
+All commands except `npm ci` are very fast. No need for extended timeouts or cancellation warnings on validation commands.

package/.github/workflows/add-to-inbox.yml

@@ -12,7 +12,7 @@ jobs:
       PROJECT_ID: 4503
     steps:
       - id: get-primer-access-token
-        uses: actions/create-github-app-token@v1
+        uses: actions/create-github-app-token@v2
         with:
           app-id: ${{ vars.PRIMER_ISSUE_TRIAGE_APP_ID }}
           private-key: ${{ secrets.PRIMER_ISSUE_TRIAGE_APP_PRIVATE_KEY }}
@@ -22,7 +22,7 @@ jobs:
         env:
           GH_TOKEN: ${{ steps.get-primer-access-token.outputs.token }}
       - id: get-github-access-token
-        uses: actions/create-github-app-token@v1
+        uses: actions/create-github-app-token@v2
         with:
           app-id: ${{ vars.PRIMER_ISSUE_TRIAGE_APP_ID_FOR_GITHUB }}
           private-key: ${{ secrets.PRIMER_ISSUE_TRIAGE_APP_PRIVATE_KEY_FOR_GITHUB }}

package/.markdownlint-cli2.cjs

@@ -16,11 +16,11 @@ const options = githubMarkdownOpinions.init({
   'no-hard-tabs': false,
   'first-line-heading': false,
   'no-space-in-emphasis': false,
-  'blanks-around-fences': false
+  'blanks-around-fences': false,
 })
 
 module.exports = {
   config: options,
   customRules: ['@github/markdownlint-github'],
-  outputFormatters: [['markdownlint-cli2-formatter-pretty', {appendLink: true}]]
+  outputFormatters: [['markdownlint-cli2-formatter-pretty', {appendLink: true}]],
 }

package/CHANGELOG.md

@@ -1,9 +1,17 @@
 # eslint-plugin-primer-react
 
+## 8.1.0
+
+### Minor Changes
+
+- [#382](https://github.com/primer/eslint-plugin-primer-react/pull/382) [`93e4b76`](https://github.com/primer/eslint-plugin-primer-react/commit/93e4b76269bf816bfc24991180f73ef22266a6f5) Thanks [@jonrohan](https://github.com/jonrohan)! - Add rule `use-styled-react-import` to enforce importing components with sx prop from @primer/styled-react
+
 ## 8.0.0
 
 ### Major Changes
 
+- [#381](https://github.com/primer/eslint-plugin-primer-react/pull/381) [`52f3be6`](https://github.com/primer/eslint-plugin-primer-react/commit/52f3be6881a522b0c9b261fe5acbe0c84a7deb5a) Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Upgrade to ESLint v9 support with eslint-plugin-github v6
+
 - [#380](https://github.com/primer/eslint-plugin-primer-react/pull/380) [`d42d5c0`](https://github.com/primer/eslint-plugin-primer-react/commit/d42d5c03a0e7df44efeed84baff2eca95af05113) Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Update repository to Node.js v20
 
 ### Minor Changes
@@ -169,7 +177,6 @@
 ### Major Changes
 
 - [#174](https://github.com/primer/eslint-plugin-primer-react/pull/174) [`d9832b8`](https://github.com/primer/eslint-plugin-primer-react/commit/d9832b850cbcf808ddcdfd3efbbab7d2bf913ccd) Thanks [@langermank](https://github.com/langermank)! - - Remove `no-deprecated-colors` plugin
-
   - Remove dependency on `primer/primitives`
 
 - [#172](https://github.com/primer/eslint-plugin-primer-react/pull/172) [`8e24d66`](https://github.com/primer/eslint-plugin-primer-react/commit/8e24d660065b3c690a14d826580c793d7b305068) Thanks [@langermank](https://github.com/langermank)! - [Breaking] Remove `new-color-css-vars-have-fallback`
@@ -380,7 +387,6 @@
 - [#7](https://github.com/primer/eslint-plugin-primer-react/pull/7) [`d9dfb8d`](https://github.com/primer/eslint-plugin-primer-react/commit/d9dfb8de6d6dc42efe606517db7a0dd90d5c5578) Thanks [@colebemis](https://github.com/colebemis)! - Add `skipImportCheck` option. By default, the `no-deprecated-colors` rule will only check for deprecated colors used in functions and components that are imported from `@primer/react`. You can disable this behavior by setting `skipImportCheck` to `true`. This is useful for linting custom components that pass color-related props down to Primer React components.
 
 * [#6](https://github.com/primer/eslint-plugin-primer-react/pull/6) [`dd14594`](https://github.com/primer/eslint-plugin-primer-react/commit/dd14594b05e4d800baa76771f5b911d77352a983) Thanks [@colebemis](https://github.com/colebemis)! - The `no-deprecated-colors` rule can now find deprecated colors in the following cases:
-
   - Nested `sx` properties:
 
     ```jsx

package/docs/rules/use-styled-react-import.md

@@ -0,0 +1,128 @@
+# use-styled-react-import
+
+💼 This rule is _disabled_ in the ✅ `recommended` config.
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
+Enforce importing components that use `sx` prop from `@primer/styled-react` instead of `@primer/react`, and vice versa.
+
+## Rule Details
+
+This rule detects when certain Primer React components are used with the `sx` prop and ensures they are imported from the temporary `@primer/styled-react` package instead of `@primer/react`. When the same components are used without the `sx` prop, it ensures they are imported from `@primer/react` instead of `@primer/styled-react`.
+
+When a component is used both with and without the `sx` prop in the same file, the rule will import the styled version with an alias (e.g., `StyledButton`) and update the JSX usage accordingly to avoid naming conflicts.
+
+It also moves certain types and utilities to the styled-react package.
+
+### Components that should be imported from `@primer/styled-react` when used with `sx`:
+
+- ActionList
+- ActionMenu
+- Box
+- Breadcrumbs
+- Button
+- Flash
+- FormControl
+- Heading
+- IconButton
+- Label
+- Link
+- LinkButton
+- PageLayout
+- Text
+- TextInput
+- Truncate
+- Octicon
+- Dialog
+
+### Types and utilities that should always be imported from `@primer/styled-react`:
+
+- `BoxProps` (type)
+- `SxProp` (type)
+- `BetterSystemStyleObject` (type)
+- `sx` (utility)
+
+## Examples
+
+### ❌ Incorrect
+
+```jsx
+import {Button, Link} from '@primer/react'
+
+const Component = () => <Button sx={{color: 'red'}}>Click me</Button>
+```
+
+```jsx
+import {Box} from '@primer/react'
+
+const Component = () => <Box sx={{padding: 2}}>Content</Box>
+```
+
+```jsx
+import {sx} from '@primer/react'
+```
+
+```jsx
+import {Button} from '@primer/styled-react'
+
+const Component = () => <Button>Click me</Button>
+```
+
+```jsx
+import {Button} from '@primer/react'
+
+const Component1 = () => <Button>Click me</Button>
+const Component2 = () => <Button sx={{color: 'red'}}>Styled me</Button>
+```
+
+### ✅ Correct
+
+```jsx
+import {Link} from '@primer/react'
+import {Button} from '@primer/styled-react'
+
+const Component = () => <Button sx={{color: 'red'}}>Click me</Button>
+```
+
+```jsx
+import {Box} from '@primer/styled-react'
+
+const Component = () => <Box sx={{padding: 2}}>Content</Box>
+```
+
+```jsx
+import {sx} from '@primer/styled-react'
+```
+
+```jsx
+// Components without sx prop can stay in @primer/react
+import {Button} from '@primer/react'
+
+const Component = () => <Button>Click me</Button>
+```
+
+```jsx
+// Components imported from styled-react but used without sx prop should be moved back
+import {Button} from '@primer/react'
+
+const Component = () => <Button>Click me</Button>
+```
+
+```jsx
+// When a component is used both ways, use an alias for the styled version
+import {Button} from '@primer/react'
+import {Button as StyledButton} from '@primer/styled-react'
+
+const Component1 = () => <Button>Click me</Button>
+const Component2 = () => <StyledButton sx={{color: 'red'}}>Styled me</StyledButton>
+```
+
+## Options
+
+This rule has no options.
+
+## When Not To Use It
+
+This rule is specifically for migrating components that use the `sx` prop to the temporary `@primer/styled-react` package. If you're not using the `sx` prop or not participating in this migration, you can disable this rule.

package/eslint.config.js

@@ -0,0 +1,54 @@
+'use strict'
+
+const js = require('@eslint/js')
+const globals = require('globals')
+const github = require('eslint-plugin-github')
+
+/**
+ * @type {import('eslint').Linter.FlatConfig[]}
+ */
+module.exports = [
+  {
+    ignores: ['node_modules/**', '.git/**'],
+  },
+  js.configs.recommended,
+  github.default.getFlatConfigs().recommended,
+  {
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'commonjs',
+      globals: {
+        ...globals.commonjs,
+        ...globals.node,
+      },
+    },
+    rules: {
+      // Override specific rules for the repository
+      'import/no-commonjs': 'off',
+      'import/no-dynamic-require': 'off', // Allow dynamic requires in tests
+      'no-shadow': 'off',
+      'no-unused-vars': [
+        'error',
+        {
+          varsIgnorePattern: '^_',
+        },
+      ],
+      'github/filenames-match-regex': 'off', // Allow various file naming patterns
+      'i18n-text/no-en': 'off', // Allow English text in this repository
+    },
+  },
+  {
+    files: ['**/*.test.js'],
+    languageOptions: {
+      globals: {
+        ...globals.jest,
+      },
+    },
+  },
+  {
+    files: ['eslint.config.js'],
+    rules: {
+      'no-undef': 'off', // Allow require() in config file
+    },
+  },
+]