Add explicit-heading rule

.changeset/lovely-toys-attend.md

@@ -0,0 +1,5 @@
+---
+'eslint-plugin-primer-react': major
+---
+
+Add `a11y-explicit-heading` rule

docs/rules/explicit-heading.md

@@ -0,0 +1,37 @@
+## Require explicit heading level on `<Heading>` component
+
+The `Heading` component does not require you to use `as` to specify the heading level, as it will default to an `h2` if one isn't specified. This may lead to inaccessible usage if the default is out of order in the existing heading hierarchy. 
+
+## Rule Details
+
+This rule enforces using `as` on the `<Heading>` component to specify a heading level (`h1`-`h6`). In addition, it enforces `as` usage to only be used for headings.
+
+👎 Examples of **incorrect** code for this rule
+
+```jsx
+import {Heading} from '@primer/react'
+
+<Heading>Heading without explicit heading level</Heading>
+```
+
+`as` must only be for headings (`h1`-`h6`)
+
+```jsx
+import {Heading} from '@primer/react'
+
+<Heading as="span">Heading component used as "span"</Heading>
+```
+
+👍 Examples of **correct** code for this rule:
+
+```jsx
+import {Heading} from '@primer/react';
+
+<Heading as="h2">Heading level 2</Heading>
+```
+
+## Options
+
+- `skipImportCheck` (default: `false`)
+
+  By default, the `a11y-explicit-heading` rule will only check for `<Heading>` components imported directly from `@primer/react`. You can disable this behavior by setting `skipImportCheck` to `true`.

src/configs/recommended.js

@@ -11,7 +11,8 @@ module.exports = {
     'primer-react/direct-slot-children': 'error',
     'primer-react/no-deprecated-colors': 'warn',
     'primer-react/no-system-props': 'warn',
-    'primer-react/a11y-tooltip-interactive-trigger': 'error'
+    'primer-react/a11y-tooltip-interactive-trigger': 'error',
+    'primer-react/a11y-explicit-heading': 'error'
   },
   settings: {
     github: {

src/index.js

@@ -3,7 +3,8 @@ module.exports = {
     'direct-slot-children': require('./rules/direct-slot-children'),
     'no-deprecated-colors': require('./rules/no-deprecated-colors'),
     'no-system-props': require('./rules/no-system-props'),
-    'a11y-tooltip-interactive-trigger': require('./rules/a11y-tooltip-interactive-trigger')
+    'a11y-tooltip-interactive-trigger': require('./rules/a11y-tooltip-interactive-trigger'),
+    'a11y-explicit-heading': require('./rules/a11y-explicit-heading')
   },
   configs: {
     recommended: require('./configs/recommended')

src/rules/__tests__/a11y-explicit-heading.test.js

@@ -0,0 +1,41 @@
+const rule = require('../a11y-explicit-heading')
+const {RuleTester} = require('eslint')
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true
+    }
+  }
+})
+
+ruleTester.run('a11y-explicit-heading', rule, {
+  valid: [
+  `import {Heading} from '@primer/react';
+  <Heading as="h1">Heading level 1</Heading>
+  `,
+  `import {Heading} from '@primer/react';
+  <Heading as="h2">Heading level 2</Heading>
+  `,
+  `import {Heading} from '@primer/react';
+  <Heading as="H3">Heading level 3</Heading>
+  `,
+],
+invalid: [    
+  {
+    code: 
+    `import {Heading} from '@primer/react';
+    <Heading>Heading without "as"</Heading>`,
+    errors: [{ messageId: 'nonExplicitHeadingLevel' }]
+  },
+  {
+    code: 
+    `import {Heading} from '@primer/react';
+    <Heading as="span">Heading component used as "span"</Heading>
+    `,
+    errors: [{ messageId: 'invalidAsValue' }]
+  },
+]
+})

src/rules/a11y-explicit-heading.js

@@ -0,0 +1,60 @@
+const {isPrimerComponent} = require('../utils/is-primer-component')
+const {getJSXOpeningElementName} = require('../utils/get-jsx-opening-element-name')
+const {getJSXOpeningElementAttribute} = require('../utils/get-jsx-opening-element-attribute')
+
+const validHeadings = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']
+
+const isHeadingComponent = elem => getJSXOpeningElementName(elem) === 'Heading'
+const isUsingAsProp = elem => {
+  const componentAs = getJSXOpeningElementAttribute(elem, 'as')
+
+  if (!componentAs) return
+
+  return componentAs.value
+}
+
+const isValidAsUsage = value => validHeadings.includes(value.toLowerCase())
+const isInvalid = elem => {
+  const elemAs = isUsingAsProp(elem)
+
+  if (!elemAs) return 'nonExplicitHeadingLevel'
+  if (!isValidAsUsage(elemAs.value)) return 'invalidAsValue'
+
+  return false
+}
+
+module.exports = {
+  meta: {
+    schema: [
+      {
+        properties: {
+          skipImportCheck: {
+            type: 'boolean'
+          }
+        }
+      }
+    ],
+    messages: {
+      nonExplicitHeadingLevel: 'Heading must have an explicit heading level applied through the `as` prop.',
+      invalidAsValue: 'Usage of `as` must only be used for heading elements (h1-h6).'
+    }
+  },
+  create: function(context) {
+    return {
+      JSXOpeningElement(jsxNode) {
+        const skipImportCheck = context.options[0] ? context.options[0].skipImportCheck : false
+
+        if ((skipImportCheck || isPrimerComponent(jsxNode.name, context.getScope(jsxNode))) && isHeadingComponent(jsxNode)) {
+          const error = isInvalid(jsxNode)
+
+          if (error) {
+            context.report({
+              node: jsxNode,
+              messageId: error
+            })
+          }
+        }
+      }
+    }
+  }
+}