eslint-plugin-primer-react 5.4.0 → 6.0.0-rc.0df8090

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-primer-react",
-  "version": "5.4.0",
+  "version": "6.0.0-rc.0df8090",
   "description": "ESLint rules for Primer React",
   "main": "src/index.js",
   "scripts": {
@@ -33,7 +33,9 @@
     "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-traverse": "^1.0.0",
     "lodash": "^4.17.21",
-    "styled-system": "^5.1.5"
+    "styled-system": "^5.1.5",
+    "@typescript-eslint/utils": "7.16.0",
+    "typescript": "^5.5.3"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.0",
@@ -44,7 +46,9 @@
     "eslint-plugin-prettier": "^5.0.1",
     "jest": "^29.7.0",
     "markdownlint-cli2": "^0.13.0",
-    "markdownlint-cli2-formatter-pretty": "^0.0.6"
+    "markdownlint-cli2-formatter-pretty": "^0.0.6",
+    "@typescript-eslint/rule-tester": "7.16.0",
+    "@types/jest": "^29.5.12"
   },
   "prettier": "@github/prettier-config"
 }

package/src/configs/recommended.js

@@ -18,6 +18,7 @@ module.exports = {
     'primer-react/no-deprecated-props': 'warn',
     'primer-react/a11y-remove-disable-tooltip': 'error',
     'primer-react/a11y-use-next-tooltip': 'error',
+    'primer-react/no-unnecessary-components': 'error',
   },
   settings: {
     github: {

package/src/index.js

@@ -10,6 +10,8 @@ module.exports = {
     'a11y-link-in-text-block': require('./rules/a11y-link-in-text-block'),
     'a11y-remove-disable-tooltip': require('./rules/a11y-remove-disable-tooltip'),
     'a11y-use-next-tooltip': require('./rules/a11y-use-next-tooltip'),
+    'use-deprecated-from-deprecated': require('./rules/use-deprecated-from-deprecated'),
+    'primer-react/no-unnecessary-components': require('./rules/no-unnecessary-components'),
   },
   configs: {
     recommended: require('./configs/recommended'),

package/src/rules/__tests__/fixtures/File.tsx

@@ -0,0 +1 @@
+// https://typescript-eslint.io/packages/rule-tester/#type-aware-testing

package/src/rules/__tests__/fixtures/file.ts

@@ -0,0 +1 @@
+// https://typescript-eslint.io/packages/rule-tester/#type-aware-testing

package/src/rules/__tests__/fixtures/tsconfig.json

@@ -0,0 +1,7 @@
+// https://typescript-eslint.io/packages/rule-tester/#type-aware-testing
+{
+  "compilerOptions": {
+    "strict": true
+  },
+  "include": ["file.ts", "File.tsx"]
+}

package/src/rules/__tests__/no-unnecessary-components.test.js

@@ -0,0 +1,153 @@
+// @ts-check
+
+const {RuleTester} = require('@typescript-eslint/rule-tester')
+
+const path = require('node:path')
+const rule = require('../no-unnecessary-components')
+const {components} = require('../no-unnecessary-components')
+
+const prcImport = 'import React from "react"; import {Box, Text} from "@primer/react";'
+const brandImport = 'import React from "react"; import {Box, Text} from "@primer/brand";'
+
+/** @param {string} content */
+const jsx = content => `export const Component = () => <>${content}</>`
+
+const sxObjectDeclaration = `const props = {sx: {color: "red"}};`
+const asObjectDeclaration = `const props = {as: "table"};`
+const stringRecordDeclaration = `const props: Record<string, any> = {};`
+const testIdObjectDeclaration = `const props = {'data-testid': 'xyz'};`
+const componentDeclaration = `const OtherComponent = ({children}: {children: React.ReactNode}) => <>{children}</>;`
+const asConstDeclaration = `const as = "p";`
+
+const ruleTester = new RuleTester({
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    tsconfigRootDir: path.resolve(__dirname, 'fixtures'),
+    project: path.resolve(__dirname, 'fixtures', 'tsconfig.json'),
+  },
+  defaultFilenames: {
+    ts: 'file.ts',
+    tsx: 'File.tsx',
+  },
+})
+
+jest.retryTimes(0, {logErrorsBeforeRetry: true})
+
+const filename = 'File.tsx'
+
+ruleTester.run('unnecessary-components', rule, {
+  valid: [
+    {name: 'Unrelated JSX', code: jsx('<span>Hello World</span>'), filename},
+    ...Object.keys(components).flatMap(component => [
+      {
+        name: `Non-PRC ${component}`,
+        code: `${brandImport}${jsx(`<${component}>Hello World</${component}>`)}`,
+        filename,
+      },
+      {
+        name: `${component} with sx prop`,
+        code: `${prcImport}${jsx(`<${component} sx={{color: "red"}}>Hello World</${component}>`)}`,
+        filename,
+      },
+      {
+        name: `${component} with any styled-system prop`,
+        code: `${prcImport}${jsx(`<${component} flex="row">Hello World</${component}>`)}`,
+        filename,
+      },
+      {
+        name: `${component} with spread sx prop`,
+        code: `${prcImport}${sxObjectDeclaration}${jsx(`<${component} {...props}>Hello World</${component}>`)}`,
+        filename,
+      },
+      {
+        name: `${component} with string index spread props`,
+        code: `${prcImport}${stringRecordDeclaration}${jsx(`<${component} {...props}>Hello World</${component}>`)}`,
+        filename,
+      },
+    ]),
+    {
+      name: `Text with weight prop`,
+      code: `${prcImport}${jsx(`<Text weight='medium'>Hello World</Text>`)}`,
+      filename,
+    },
+    {
+      name: `Text with size prop`,
+      code: `${prcImport}${jsx(`<Text size='small'>Hello World</Text>`)}`,
+      filename,
+    },
+  ],
+  invalid: Object.entries(components).flatMap(([component, {messageId, replacement}]) => [
+    {
+      name: `${component} without any styled-system props`,
+      code: `${prcImport}${jsx(`<${component}>Hello World</${component}>`)}`,
+      output: `${prcImport}${jsx(`<${replacement}>Hello World</${replacement}>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `Self-closing ${component} without any styled-system props`,
+      code: `${prcImport}${jsx(`<${component} />`)}`,
+      output: `${prcImport}${jsx(`<${replacement} />`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with spread props without sx`,
+      code: `${prcImport}${testIdObjectDeclaration}${jsx(`<${component} {...props}>Hello World</${component}>`)}`,
+      output: `${prcImport}${testIdObjectDeclaration}${jsx(`<${replacement} {...props}>Hello World</${replacement}>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with string element 'as' prop`,
+      code: `${prcImport}${jsx(`<${component} as="code">Hello world</${component}>`)}`,
+      // There is extra whitespace here we don't worry about since formatters would get rid of it
+      output: `${prcImport}${jsx(`<code >Hello world</code>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with single-character 'as' prop`,
+      code: `${prcImport}${jsx(`<${component} as="p">Hello world</${component}>`)}`,
+      output: `${prcImport}${jsx(`<p >Hello world</p>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with string element 'as' prop surrounded by unnecessary braces`,
+      code: `${prcImport}${jsx(`<${component} as={"code"}>Hello world</${component}>`)}`,
+      output: `${prcImport}${jsx(`<code >Hello world</code>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with component reference 'as' prop`,
+      code: `${prcImport}${componentDeclaration}${jsx(`<${component} as={OtherComponent}>Hello world</${component}>`)}`,
+      output: `${prcImport}${componentDeclaration}${jsx(`<OtherComponent >Hello world</OtherComponent>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with spread 'as' prop`,
+      code: `${prcImport}${asObjectDeclaration}${jsx(`<${component} {...props}>Hello world</${component}>`)}`,
+      output: null,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with unusable lowercase reference 'as' prop`,
+      code: `${prcImport}${asConstDeclaration}${jsx(`<${component} as={as}>Hello world</${component}>`)}`,
+      output: null,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `Non-PRC ${component} when \`skipImportCheck\` is enabled`,
+      code: `${brandImport}${jsx(`<${component}>Hello World</${component}>`)}`,
+      output: `${brandImport}${jsx(`<${replacement}>Hello World</${replacement}>`)}`,
+      filename,
+      errors: [{messageId}],
+      options: [{skipImportCheck: true}],
+    },
+  ]),
+})

package/src/rules/__tests__/use-deprecated-from-deprecated.test.js

@@ -0,0 +1,66 @@
+'use strict'
+
+const {RuleTester} = require('eslint')
+const rule = require('../use-deprecated-from-deprecated')
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+})
+
+ruleTester.run('use-deprecated-from-deprecated', rule, {
+  valid: [],
+  invalid: [
+    // Single deprecated import
+    {
+      code: `import {Tooltip} from '@primer/react'`,
+      output: `import {Tooltip} from '@primer/react/deprecated'`,
+      errors: ['Import deprecated components from @primer/react/deprecated'],
+    },
+
+    // Single deprecated import with existing deprecated entrypoint
+    {
+      code: `import {Tooltip} from '@primer/react'
+import {Dialog} from '@primer/react/deprecated'`,
+      output: `\nimport {Dialog, Tooltip} from '@primer/react/deprecated'`,
+      errors: ['Import deprecated components from @primer/react/deprecated'],
+    },
+
+    // Multiple deprecated imports
+    {
+      code: `import {Dialog, Tooltip} from '@primer/react'`,
+      output: `import {Dialog, Tooltip} from '@primer/react/deprecated'`,
+      errors: ['Import deprecated components from @primer/react/deprecated'],
+    },
+
+    // Mixed deprecated and non-deprecated imports
+    {
+      code: `import {Button, Tooltip} from '@primer/react'`,
+      output: `import {Button, } from '@primer/react'
+import {Tooltip} from '@primer/react/deprecated'`,
+      errors: ['Import deprecated components from @primer/react/deprecated'],
+    },
+
+    // Mixed deprecated and non-deprecated imports with existing deprecated
+    {
+      code: `import {Button, Tooltip} from '@primer/react'
+import {Dialog} from '@primer/react/deprecated'`,
+      output: `import {Button, } from '@primer/react'
+import {Dialog, Tooltip} from '@primer/react/deprecated'`,
+      errors: ['Import deprecated components from @primer/react/deprecated'],
+    },
+
+    // Multiple mixed deprecated and non-deprecated imports
+    {
+      code: `import {Button, Dialog, Tooltip} from '@primer/react'`,
+      output: `import {Button,  } from '@primer/react'
+import {Dialog, Tooltip} from '@primer/react/deprecated'`,
+      errors: ['Import deprecated components from @primer/react/deprecated'],
+    },
+  ],
+})

package/src/rules/no-unnecessary-components.js

@@ -0,0 +1,160 @@
+// @ts-check
+
+const {ESLintUtils} = require('@typescript-eslint/utils')
+const {IndexKind} = require('typescript')
+const {pick: pickStyledSystemProps} = require('@styled-system/props')
+const {isPrimerComponent} = require('../utils/is-primer-component')
+
+/** @typedef {import('@typescript-eslint/types').TSESTree.JSXAttribute} JSXAttribute */
+
+const components = {
+  Box: {
+    replacement: 'div',
+    messageId: 'unecessaryBox',
+    message: 'Prefer plain HTML elements over `Box` when not using `sx` for styling.',
+    allowedProps: new Set(['sx']), // + styled-system props
+  },
+  Text: {
+    replacement: 'span',
+    messageId: 'unecessarySpan',
+    message: 'Prefer plain HTML elements over `Text` when not using `sx` for styling.',
+    allowedProps: new Set(['sx', 'size', 'weight']), // + styled-system props
+  },
+}
+
+const elementNameRegex = /^[a-z]\w*$/
+const componentNameRegex = /^[A-Z][\w._]*$/
+
+/** @param {string} propName */
+const isStyledSystemProp = propName => propName in pickStyledSystemProps({[propName]: propName})
+
+const rule = ESLintUtils.RuleCreator.withoutDocs({
+  meta: {
+    docs: {
+      description:
+        '`Box` and `Text` should only be used to provide access to the `sx` styling system and have a performance cost. If `sx` props are not being used, prefer `div` and `span` instead.',
+    },
+    messages: {
+      [components.Box.messageId]: components.Box.message,
+      [components.Text.messageId]: components.Text.message,
+    },
+    type: 'problem',
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          skipImportCheck: {
+            type: 'boolean',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    fixable: 'code',
+  },
+  defaultOptions: [{skipImportCheck: false}],
+  create(context) {
+    return {
+      JSXElement({openingElement, closingElement}) {
+        const {name, attributes} = openingElement
+
+        // Ensure this is one of the components we are looking for. Note this doesn't account for import aliases; this
+        // is intentional to avoid having to do the scope tree traversal for every component of every name, which would
+        // be needlessly expensive. We just ignore aliased imports.
+        if (name.type !== 'JSXIdentifier' || !(name.name in components)) return
+        const componentConfig = components[/** @type {keyof typeof components} */ (name.name)]
+
+        // Only continue if the variable declaration is an import from @primer/react. Otherwise it could, for example,
+        // be an import from @primer/brand, which would be valid without sx.
+        const skipImportCheck = context.options[0]?.skipImportCheck
+        const isPrimer = skipImportCheck || isPrimerComponent(name, context.sourceCode.getScope(openingElement))
+        if (!isPrimer) return
+
+        /** @param {string} name */
+        const isAllowedProp = name => componentConfig.allowedProps.has(name) || isStyledSystemProp(name)
+
+        // Validate the attributes and ensure an allowed prop is present or spreaded in
+        /** @type {typeof attributes[number] | undefined | null} */
+        let asProp = undefined
+        for (const attribute of attributes) {
+          // If there is a spread type, check if the type of the spreaded value has an allowed property
+          if (attribute.type === 'JSXSpreadAttribute') {
+            const services = ESLintUtils.getParserServices(context)
+            const typeChecker = services.program.getTypeChecker()
+
+            const spreadType = services.getTypeAtLocation(attribute.argument)
+
+            // Check if the spread type has a string index signature - this could hide an allowed property
+            if (typeChecker.getIndexTypeOfType(spreadType, IndexKind.String) !== undefined) return
+
+            const spreadPropNames = typeChecker.getPropertiesOfType(spreadType).map(prop => prop.getName())
+
+            // If an allowed prop gets spread in, this is a valid use of the component
+            if (spreadPropNames.some(isAllowedProp)) return
+
+            // If there is an `as` inside the spread object, we can't autofix reliably
+            if (spreadPropNames.includes('as')) asProp = null
+
+            continue
+          }
+
+          // Has an allowed prop, so should keep using this component
+          if (attribute.name.type === 'JSXIdentifier' && isAllowedProp(attribute.name.name)) return
+
+          // If there is an `as` prop we will need to account for that when autofixing
+          if (attribute.name.type === 'JSXIdentifier' && attribute.name.name === 'as') asProp = attribute
+        }
+
+        // Determine a replacement component name accounting for the `as` prop if present
+        /** @type {string | null} */
+        let replacement = componentConfig.replacement
+        if (asProp === null) {
+          // {...{as: 'something-unusable'}}
+          replacement = null
+        } else if (asProp?.type === 'JSXAttribute') {
+          // as={ComponentReference}
+          if (asProp.value?.type === 'JSXExpressionContainer' && asProp.value.expression.type === 'Identifier') {
+            // can't just use expression.name here because we want the whole expression if it's A.B
+            const expressionStr = context.sourceCode.getText(asProp.value.expression)
+            replacement = componentNameRegex.test(expressionStr) ? expressionStr : null
+          }
+          // as={'tagName'} (surprisingly common, we really should enable `react/jsx-curly-brace-presence`)
+          else if (
+            asProp.value?.type === 'JSXExpressionContainer' &&
+            asProp.value.expression.type === 'Literal' &&
+            typeof asProp.value.expression.value === 'string' &&
+            elementNameRegex.test(asProp.value.expression.value)
+          ) {
+            replacement = asProp.value.expression.value
+          }
+          // as="tagName"
+          else if (
+            asProp.value?.type === 'Literal' &&
+            typeof asProp.value.value === 'string' &&
+            elementNameRegex.test(asProp.value.value)
+          ) {
+            replacement = asProp.value.value
+          }
+          // too complex to autofix
+          else {
+            replacement = null
+          }
+        }
+
+        context.report({
+          node: name,
+          messageId: componentConfig.messageId,
+          fix: replacement
+            ? function* (fixer) {
+                yield fixer.replaceText(name, replacement)
+                if (closingElement) yield fixer.replaceText(closingElement.name, replacement)
+                if (asProp) yield fixer.remove(asProp)
+              }
+            : undefined,
+        })
+      },
+    }
+  },
+})
+
+module.exports = {...rule, components}

package/src/rules/use-deprecated-from-deprecated.js

@@ -0,0 +1,130 @@
+'use strict'
+
+const url = require('../url')
+
+const components = [
+  {
+    identifier: 'Dialog',
+    entrypoint: '@primer/react',
+  },
+  {
+    identifier: 'Octicon',
+    entrypoint: '@primer/react',
+  },
+  {
+    identifier: 'Pagehead',
+    entrypoint: '@primer/react',
+  },
+  {
+    identifier: 'TabNav',
+    entrypoint: '@primer/react',
+  },
+  {
+    identifier: 'Tooltip',
+    entrypoint: '@primer/react',
+  },
+]
+
+const entrypoints = new Map()
+
+for (const component of components) {
+  if (!entrypoints.has(component.entrypoint)) {
+    entrypoints.set(component.entrypoint, new Set())
+  }
+  entrypoints.get(component.entrypoint).add(component.identifier)
+}
+
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Use deprecated components from the `@primer/react/deprecated` entrypoint',
+      recommended: true,
+      url: url(module),
+    },
+    fixable: true,
+    schema: [],
+  },
+  create(context) {
+    const sourceCode = context.getSourceCode()
+
+    return {
+      ImportDeclaration(node) {
+        if (!entrypoints.has(node.source.value)) {
+          return
+        }
+
+        const entrypoint = entrypoints.get(node.source.value)
+        const deprecated = node.specifiers.filter(specifier => {
+          return entrypoint.has(specifier.imported.name)
+        })
+
+        if (deprecated.length === 0) {
+          return
+        }
+
+        const deprecatedEntrypoint = node.parent.body.find(node => {
+          if (node.type !== 'ImportDeclaration') {
+            return false
+          }
+
+          return node.source.value === '@primer/react/deprecated'
+        })
+
+        // All imports are deprecated
+        if (deprecated.length === node.specifiers.length) {
+          context.report({
+            node,
+            message: 'Import deprecated components from @primer/react/deprecated',
+            *fix(fixer) {
+              if (deprecatedEntrypoint) {
+                const lastSpecifier = deprecatedEntrypoint.specifiers[deprecatedEntrypoint.specifiers.length - 1]
+
+                yield fixer.remove(node)
+                yield fixer.insertTextAfter(
+                  lastSpecifier,
+                  `, ${node.specifiers.map(specifier => specifier.imported.name).join(', ')}`,
+                )
+              } else {
+                yield fixer.replaceText(node.source, `'@primer/react/deprecated'`)
+              }
+            },
+          })
+        } else {
+          // There is a mix of deprecated and non-deprecated imports
+          context.report({
+            node,
+            message: 'Import deprecated components from @primer/react/deprecated',
+            *fix(fixer) {
+              for (const specifier of deprecated) {
+                yield fixer.remove(specifier)
+                const comma = sourceCode.getTokenAfter(specifier)
+                if (comma.value === ',') {
+                  yield fixer.remove(comma)
+                }
+              }
+
+              if (deprecatedEntrypoint) {
+                const lastSpecifier = deprecatedEntrypoint.specifiers[deprecatedEntrypoint.specifiers.length - 1]
+                yield fixer.insertTextAfter(
+                  lastSpecifier,
+                  `, ${deprecated.map(specifier => specifier.imported.name).join(', ')}`,
+                )
+              } else {
+                yield fixer.insertTextAfter(
+                  node,
+                  `\nimport {${deprecated
+                    .map(specifier => specifier.imported.name)
+                    .join(', ')}} from '@primer/react/deprecated'`,
+                )
+              }
+            },
+          })
+        }
+      },
+    }
+  },
+}

package/src/utils/is-primer-component.js

@@ -1,5 +1,6 @@
 const {isImportedFrom} = require('./is-imported-from')
 
+/** @returns {boolean} */
 function isPrimerComponent(name, scope) {
   let identifier