Add content linter rule to prevent multiple emphasis patterns (#56122)

Author: heiskr

src/content-linter/lib/linting-rules/index.js

@@ -35,6 +35,7 @@ import { liquidTagWhitespace } from './liquid-tag-whitespace.js'
 import { linkQuotation } from './link-quotation.js'
 import { octiconAriaLabels } from './octicon-aria-labels.js'
 import { liquidIfversionVersions } from './liquid-ifversion-versions.js'
+import { multipleEmphasisPatterns } from './multiple-emphasis-patterns.js'
 import { noteWarningFormatting } from './note-warning-formatting.js'
 
 const noDefaultAltText = markdownlintGitHub.find((elem) =>
@@ -85,6 +86,7 @@ export const gitHubDocsMarkdownlint = {
     liquidTagWhitespace,
     linkQuotation,
     octiconAriaLabels,
+    multipleEmphasisPatterns,
     noteWarningFormatting,
   ],
 }

src/content-linter/lib/linting-rules/multiple-emphasis-patterns.js

@@ -0,0 +1,93 @@
+import { addError } from 'markdownlint-rule-helpers'
+import { getRange } from '../helpers/utils.js'
+import frontmatter from '#src/frame/lib/read-frontmatter.js'
+
+export const multipleEmphasisPatterns = {
+  names: ['GHD050', 'multiple-emphasis-patterns'],
+  description: 'Do not use more than one emphasis/strong, italics, or uppercase for a string',
+  tags: ['formatting', 'emphasis', 'style'],
+  severity: 'warning',
+  function: (params, onError) => {
+    // Skip autogenerated files
+    const frontmatterString = params.frontMatterLines.join('\n')
+    const fm = frontmatter(frontmatterString).data
+    if (fm && fm.autogenerated) return
+
+    const lines = params.lines
+    let inCodeBlock = false
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      const lineNumber = i + 1
+
+      // Track code block state
+      if (line.trim().startsWith('```')) {
+        inCodeBlock = !inCodeBlock
+        continue
+      }
+
+      // Skip code blocks and indented code
+      if (inCodeBlock || line.trim().startsWith('    ')) continue
+
+      // Check for multiple emphasis patterns
+      checkMultipleEmphasis(line, lineNumber, onError)
+    }
+  },
+}
+
+/**
+ * Check for multiple emphasis types in a single text segment
+ */
+function checkMultipleEmphasis(line, lineNumber, onError) {
+  // Focus on the clearest violations of the style guide
+  const multipleEmphasisPatterns = [
+    // Bold + italic combinations (***text***)
+    { regex: /\*\*\*([^*]+)\*\*\*/g, types: ['bold', 'italic'] },
+    { regex: /___([^_]+)___/g, types: ['bold', 'italic'] },
+
+    // Bold with code nested inside
+    { regex: /\*\*([^*]*`[^`]+`[^*]*)\*\*/g, types: ['bold', 'code'] },
+    { regex: /__([^_]*`[^`]+`[^_]*)__/g, types: ['bold', 'code'] },
+
+    // Code with bold nested inside
+    { regex: /`([^`]*\*\*[^*]+\*\*[^`]*)`/g, types: ['code', 'bold'] },
+    { regex: /`([^`]*__[^_]+__[^`]*)`/g, types: ['code', 'bold'] },
+  ]
+
+  for (const pattern of multipleEmphasisPatterns) {
+    let match
+    while ((match = pattern.regex.exec(line)) !== null) {
+      // Skip if this is likely intentional or very short
+      if (shouldSkipMatch(match[0], match[1])) continue
+
+      const range = getRange(line, match[0])
+      addError(
+        onError,
+        lineNumber,
+        `Do not use multiple emphasis types in a single string: ${pattern.types.join(' + ')}`,
+        line,
+        range,
+        null, // No auto-fix as this requires editorial judgment
+      )
+    }
+  }
+}
+
+/**
+ * Determine if a match should be skipped (likely intentional formatting)
+ */
+function shouldSkipMatch(fullMatch, content) {
+  // Skip common false positives
+  if (!content) return true
+
+  // Skip very short content (likely intentional single chars)
+  if (content.trim().length < 2) return true
+
+  // Skip if it's mostly code-like content (constants, variables)
+  if (/^[A-Z_][A-Z0-9_]*$/.test(content.trim())) return true
+
+  // Skip file extensions or URLs
+  if (/\.[a-z]{2,4}$/i.test(content.trim()) || /https?:\/\//.test(content)) return true
+
+  return false
+}

src/content-linter/tests/unit/multiple-emphasis-patterns.js

@@ -0,0 +1,231 @@
+import { describe, expect, test } from 'vitest'
+
+import { runRule } from '../../lib/init-test.js'
+import { multipleEmphasisPatterns } from '../../lib/linting-rules/multiple-emphasis-patterns.js'
+
+describe(multipleEmphasisPatterns.names.join(' - '), () => {
+  test('Single emphasis types pass', async () => {
+    const markdown = [
+      'This is **bold text** that is fine.',
+      'This is *italic text* that is okay.',
+      'This is `code text` that is acceptable.',
+      'This is a SCREAMING_CASE_WORD that is allowed.',
+      'This is __bold with underscores__ that works.',
+      'This is _italic with underscores_ that works.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(0)
+  })
+
+  test('Multiple emphasis types in same string are flagged', async () => {
+    const markdown = [
+      'This is **bold and `code`** in the same string.',
+      'This is ***bold and italic*** combined.',
+      'This is `code with **bold**` inside.',
+      'This is ___bold and italic___ with underscores.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(4)
+    expect(errors[0].lineNumber).toBe(1)
+    expect(errors[1].lineNumber).toBe(2)
+    expect(errors[2].lineNumber).toBe(3)
+    expect(errors[3].lineNumber).toBe(4)
+  })
+
+  test('Nested emphasis patterns are flagged', async () => {
+    const markdown = [
+      'This is **bold with `code` inside**.',
+      'This is `code with **bold** nested`.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(2)
+    expect(errors[0].lineNumber).toBe(1)
+    expect(errors[1].lineNumber).toBe(2)
+  })
+
+  test('Separate emphasis patterns on same line pass', async () => {
+    const markdown = [
+      'This is **bold** and this is *italic* but separate.',
+      'Here is `code` and here is UPPERCASE but apart.',
+      'First **bold**, then some text, then *italic*.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(0)
+  })
+
+  test('Code blocks are ignored', async () => {
+    const markdown = [
+      '```javascript',
+      'const text = "**bold** and `code` mixed";',
+      'const more = "***triple emphasis***";',
+      '```',
+      '',
+      '    // Indented code block',
+      '    const example = "**bold** with `code`";',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(0)
+  })
+
+  test('Inline code prevents other emphasis detection', async () => {
+    const markdown = [
+      'Use `**bold**` to make text bold.',
+      'The `*italic*` syntax creates italic text.',
+      'Type `__bold__` for bold formatting.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(2) // Code with bold inside is detected
+  })
+
+  test('Complex mixed emphasis patterns', async () => {
+    const markdown = [
+      'This is **bold and `code`** mixed.',
+      'Here is ***bold italic*** combined.',
+      'Text with __bold and `code`__ together.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(3)
+    expect(errors[0].lineNumber).toBe(1)
+    expect(errors[1].lineNumber).toBe(2)
+    expect(errors[2].lineNumber).toBe(3)
+  })
+
+  test('Edge case: adjacent emphasis without overlap passes', async () => {
+    const markdown = [
+      'This is **bold**_italic_ adjacent but not overlapping.',
+      'Here is `code`**bold** touching but separate.',
+      'Text with UPPERCASE**bold** next to each other.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(0)
+  })
+
+  test('Triple asterisk bold+italic is flagged', async () => {
+    const markdown = [
+      'This is ***bold and italic*** combined.',
+      'Here is ___bold and italic___ with underscores.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(2)
+    expect(errors[0].lineNumber).toBe(1)
+    expect(errors[1].lineNumber).toBe(2)
+  })
+
+  test('Mixed adjacent emphasis types are allowed', async () => {
+    const markdown = [
+      'This has **bold** and normal text.',
+      'This has **bold** and other text.',
+      'The API key and **configuration** work.',
+      'The API key and **setup** process.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(0)
+  })
+
+  test('Autogenerated files are skipped', async () => {
+    const frontmatter = ['---', 'title: API Reference', 'autogenerated: rest', '---'].join('\n')
+    const markdown = [
+      'This is **bold and `code`** mixed.',
+      'This is ***bold italic*** combined.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, {
+      strings: {
+        markdown: frontmatter + '\n' + markdown,
+      },
+    })
+    const errors = result.markdown
+    expect(errors.length).toBe(0)
+  })
+
+  test('Links with emphasis are handled correctly', async () => {
+    const markdown = [
+      'See [**bold link**](http://example.com) for details.',
+      'Check [*italic link*](http://example.com) here.',
+      'Visit [`code link`](http://example.com) for info.',
+      'Go to [**bold and `code`**](http://example.com) - should be flagged.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(1)
+    expect(errors[0].lineNumber).toBe(4)
+  })
+
+  test('Headers with emphasis are checked', async () => {
+    const markdown = [
+      '# This is **bold** header',
+      '## This is *italic* header',
+      '### This is **bold and `code`** header',
+      '#### This is normal header',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(1)
+    expect(errors[0].lineNumber).toBe(3)
+  })
+
+  test('List items with emphasis are checked', async () => {
+    const markdown = [
+      '- This is **bold** item',
+      '- This is *italic* item',
+      '- This is **bold and `code`** item',
+      '1. This is numbered **bold** item',
+      '2. This is numbered ***bold italic*** item',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(2)
+    expect(errors[0].lineNumber).toBe(3)
+    expect(errors[1].lineNumber).toBe(5)
+  })
+
+  test('Escaped emphasis characters are ignored', async () => {
+    const markdown = [
+      'This has \\*\\*escaped\\*\\* asterisks.',
+      'This has \\`escaped\\` backticks.',
+      'This has \\_escaped\\_ underscores.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(0)
+  })
+
+  test('Rule has correct metadata', () => {
+    expect(multipleEmphasisPatterns.names).toEqual(['GHD050', 'multiple-emphasis-patterns'])
+    expect(multipleEmphasisPatterns.description).toContain('emphasis')
+    expect(multipleEmphasisPatterns.tags).toContain('formatting')
+    expect(multipleEmphasisPatterns.tags).toContain('emphasis')
+    expect(multipleEmphasisPatterns.tags).toContain('style')
+    expect(multipleEmphasisPatterns.severity).toBe('warning')
+  })
+
+  test('Empty content does not cause errors', async () => {
+    const markdown = ['', '   ', '\t'].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(0)
+  })
+
+  test('Single character emphasis is handled', async () => {
+    const markdown = [
+      'This is **a** single letter.',
+      'This is *b* single letter.',
+      'This is `c` single letter.',
+      'This is **a** and *b* separate.',
+      'This is **`x`** nested single chars.',
+    ].join('\n')
+    const result = await runRule(multipleEmphasisPatterns, { strings: { markdown } })
+    const errors = result.markdown
+    expect(errors.length).toBe(1) // Nested single chars still flagged
+    expect(errors[0].lineNumber).toBe(5)
+  })
+})