Implement HTML anchor elements check in a11y-link-in-text-block rule

Copilot · TylerJDev · Copilot · commit 67629e9b3f4b · 2025-05-19T18:50:22.000Z
Co-authored-by: TylerJDev &lt;26746305+TylerJDev@users.noreply.github.com&gt;
diff --git a/docs/rules/a11y-link-in-text-block.md b/docs/rules/a11y-link-in-text-block.md
@@ -1,22 +1,26 @@
-# EXPERIMENTAL: Require `inline` prop on `<Link>` in text block
+# EXPERIMENTAL: Require `inline` prop on `<Link>` in text block and convert HTML anchors to Link components
 
 This is an experimental rule. If you suspect any false positives reported by this rule, please file an issue so we can make this rule better.
 
 ## Rule Details
 
 The `Link` component should have the `inline` prop when it is used within a text block and has no styles (aside from color) to distinguish itself from surrounding plain text.
 
+Additionally, HTML anchor elements (`<a>`) in text blocks should be converted to use the `Link` component from `@primer/react` to maintain consistent styling and accessibility.
+
 Related: [WCAG 1.4.1 Use of Color issues](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html)
 
-The lint rule will flag any `<Link>` without the `inline` property (equal to `true`) detected with string nodes on either side.
+The lint rule will flag:
+- Any `<Link>` without the `inline` property (equal to `true`) detected with string nodes on either side.
+- Any HTML `<a>` elements detected within a text block, with an autofix to convert them to `Link` components.
 
 There are certain edge cases that the linter skips to avoid false positives including:
 
-- `<Link className="...">` because there may be distinguishing styles applied.
+- `<Link className="...">` or `<a className="...">` because there may be distinguishing styles applied.
 - `<Link sx={{fontWeight:...}}>` or `<Link sx={{fontFamily:...}}>` because these technically may provide sufficient distinguishing styling.
-- `<Link>` where the only adjacent text is a period, since that can't really be considered a text block.
-- `<Link>` where the children is a JSX component, rather than a string literal, because then it might be an icon link rather than a text link.
-- `<Link>` that are nested inside of headings as these have often been breadcrumbs.
+- `<Link>` or `<a>` where the only adjacent text is a period, since that can't really be considered a text block.
+- `<Link>` or `<a>` where the children is a JSX component, rather than a string literal, because then it might be an icon link rather than a text link.
+- `<Link>` or `<a>` that are nested inside of headings as these have often been breadcrumbs.
 
 This rule will not catch all instances of link in text block due to the limitations of static analysis, so be sure to also have in-browser checks in place such as the [link-in-text-block Axe rule](https://dequeuniversity.com/rules/axe/4.9/link-in-text-block) for additional coverage.
 
@@ -46,6 +50,26 @@ function ExampleComponent() {
 }
 ```
 
+```jsx
+function ExampleComponent() {
+  return (
+    <SomeComponent>
+      Please <a href="https://github.com">visit our site</a> for more information.
+    </SomeComponent>
+  )
+}
+```
+
+```jsx
+function ExampleComponent() {
+  return (
+    <p>
+      Learn more about <a href="https://github.com/pricing">GitHub plans</a> and pricing options.
+    </p>
+  )
+}
+```
+
 👍 Examples of **correct** code for this rule:
 
 ```jsx
@@ -68,6 +92,30 @@ function ExampleComponent() {
 }
 ```
 
+```jsx
+import {Link} from '@primer/react'
+
+function ExampleComponent() {
+  return (
+    <SomeComponent>
+      Please <Link href="https://github.com">visit our site</Link> for more information.
+    </SomeComponent>
+  )
+}
+```
+
+```jsx
+import {Link} from '@primer/react'
+
+function ExampleComponent() {
+  return (
+    <p>
+      Learn more about <Link href="https://github.com/pricing" inline>GitHub plans</Link> and pricing options.
+    </p>
+  )
+}
+```
+
 This rule will skip `Link`s containing JSX elements to minimize potential false positives because it is possible the JSX element sufficiently distinguishes the link from surrounding text.
 
 ```jsx
diff --git a/src/rules/__tests__/a11y-link-in-text-block.test.js b/src/rules/__tests__/a11y-link-in-text-block.test.js
@@ -125,6 +125,19 @@ ruleTester.run('a11y-link-in-text-block', rule, {
     <Link className='some-class'>Link text</Link>
     </p>
   `,
+    // Valid HTML anchor examples
+    `<h1>
+      <a href="/home">Home</a>
+    </h1>`,
+    `<p>
+      <a href="/about" className="custom-link">About us</a>
+    </p>`,
+    `<div>
+      <a href="/contact"><CustomIcon /> Contact</a>
+    </div>`,
+    `<div>
+      <a href="/link">Link</a>.
+    </div>`,
   ],
   invalid: [
     {
@@ -167,5 +180,26 @@ ruleTester.run('a11y-link-in-text-block', rule, {
     `,
       errors: [{messageId: 'linkInTextBlock'}],
     },
+    // HTML anchor element tests
+    {
+      code: `<p>Please <a href="https://github.com">visit our site</a> for more information.</p>`,
+      errors: [{messageId: 'htmlAnchorInTextBlock'}],
+      output: `<p>Please <Link href="https://github.com">visit our site</Link> for more information.</p>`,
+    },
+    {
+      code: `<div>Learn more about <a href="/pricing">pricing</a> options.</div>`,
+      errors: [{messageId: 'htmlAnchorInTextBlock'}],
+      output: `<div>Learn more about <Link href="/pricing">pricing</Link> options.</div>`,
+    },
+    {
+      code: `<span>Check out <a href="https://github.com" target="_blank">GitHub</a> today!</span>`,
+      errors: [{messageId: 'htmlAnchorInTextBlock'}],
+      output: `<span>Check out <Link href="https://github.com" target="_blank">GitHub</Link> today!</span>`,
+    },
+    {
+      code: `<p><a href="/home">Home page</a> has been updated.</p>`,
+      errors: [{messageId: 'htmlAnchorInTextBlock'}],
+      output: `<p><Link href="/home">Home page</Link> has been updated.</p>`,
+    },
   ],
 })
diff --git a/src/rules/a11y-link-in-text-block.js b/src/rules/a11y-link-in-text-block.js
@@ -1,13 +1,15 @@
 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 {isHTMLElement} = require('../utils/is-html-element')
 
 module.exports = {
   meta: {
     docs: {
       url: require('../url')(module),
     },
     type: 'problem',
+    fixable: 'code',
     schema: [
       {
         properties: {
@@ -20,14 +22,103 @@ module.exports = {
     messages: {
       linkInTextBlock:
         'Links should have the inline prop if it appear in a text block and only uses color to distinguish itself from surrounding text.',
+      htmlAnchorInTextBlock:
+        'HTML anchor elements in text blocks should use the Link component from @primer/react instead.',
     },
   },
   create(context) {
     const sourceCode = context.sourceCode ?? context.getSourceCode()
+    
+    // Helper function to check if a node is in a text block
+    const isNodeInTextBlock = (node) => {
+      let siblings = node.parent.children
+      if (!siblings || siblings.length === 0) return false
+      
+      // Filter out whitespace nodes
+      siblings = siblings.filter(childNode => {
+        return (
+          !(childNode.type === 'JSXText' && /^\s+$/.test(childNode.value)) &&
+          !(
+            childNode.type === 'JSXExpressionContainer' &&
+            childNode.expression.type === 'Literal' &&
+            /^\s+$/.test(childNode.expression.value)
+          ) &&
+          !(childNode.type === 'Literal' && /^\s+$/.test(childNode.value))
+        )
+      })
+      
+      const index = siblings.findIndex(childNode => {
+        return childNode.range === node.range
+      })
+      
+      const prevSibling = siblings[index - 1]
+      const nextSibling = siblings[index + 1]
+      
+      const prevSiblingIsText = prevSibling && prevSibling.type === 'JSXText'
+      const nextSiblingIsText = nextSibling && nextSibling.type === 'JSXText'
+      
+      // If there's text on either side
+      if (prevSiblingIsText || nextSiblingIsText) {
+        // Skip if the only text adjacent to the link is a period
+        if (!prevSiblingIsText && /^\s*\.+\s*$/.test(nextSibling.value)) {
+          return false
+        }
+        return true
+      }
+      
+      return false
+    }
+    
     return {
       JSXElement(node) {
         const name = getJSXOpeningElementName(node.openingElement)
+        const parentName = node.parent.openingElement?.name?.name
+        const parentsToSkip = ['Heading', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6']
+        
+        // Check for HTML anchor elements
         if (
+          isHTMLElement(node.openingElement) &&
+          name === 'a' &&
+          node.parent.children
+        ) {
+          // Skip if anchor is nested inside of a heading
+          if (parentsToSkip.includes(parentName)) return
+          
+          // Skip if anchor has className (might have distinguishing styles)
+          const classNameAttribute = getJSXOpeningElementAttribute(node.openingElement, 'className')
+          if (classNameAttribute) return
+          
+          // Check for anchor in text block
+          if (isNodeInTextBlock(node)) {
+            // Skip if anchor child is a JSX element
+            const jsxElementChildren = node.children.filter(child => child.type === 'JSXElement')
+            if (jsxElementChildren.length > 0) return
+            
+            // Report and autofix
+            context.report({
+              node,
+              messageId: 'htmlAnchorInTextBlock',
+              fix(fixer) {
+                // Get all attributes from the anchor to transfer to Link
+                const attributes = node.openingElement.attributes
+                  .map(attr => sourceCode.getText(attr))
+                  .join(' ')
+                
+                // Create the Link component opening and closing tags
+                const openingTag = `<Link ${attributes}>`
+                const closingTag = '</Link>'
+                
+                // Apply fixes to the opening and closing tags
+                const openingFix = fixer.replaceText(node.openingElement, openingTag)
+                const closingFix = fixer.replaceText(node.closingElement, closingTag)
+                
+                return [openingFix, closingFix]
+              }
+            })
+          }
+        }
+        // Check for Primer Link component
+        else if (
           isPrimerComponent(node.openingElement.name, sourceCode.getScope(node)) &&
           name === 'Link' &&
           node.parent.children
