Fix link checker false positives (#59774)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: heiskr

src/links/lib/excluded-links.yml

@@ -70,8 +70,8 @@
 - is: https://moodle.org
 - is: https://azure.microsoft.com
 - is: https://api.octocorp.ghe.com
-- is: https://platform.openai.com/docs/guides/safety-best-practices
-- is: https://platform.openai.com/docs/guides/function-calling
+- startsWith: https://platform.openai.com/docs
+- startsWith: https://openai.com
 - is: https://global.rel.tunnels.api.visualstudio.com/api/version
 - is: https://www.wireguard.com/quickstart/
 - is: https://docs.openstack.org/horizon/latest/
@@ -85,8 +85,6 @@
 - is: https://jsonformatter.org/
 - is: https://mvnrepository.com/artifact/org.xwiki.platform/xwiki-platform-oldcore
 - is: https://mvnrepository.com/artifact/com.google.guava/guava
-- startsWith: https://platform.openai.com/docs/models
-- startsWith: https://openai.com/index
 - is: https://github.com/github-linguist/linguist/compare/master...octocat:master
 - is: https://www.servicenow.com/docs/bundle/utah-devops/page/product/enterprise-dev-ops/concept/github-integration-dev-ops.html
 - startsWith: https://www.ilo.org
@@ -95,8 +93,7 @@
 - is: https://www.nongnu.org/oath-toolkit/man-oathtool.html
 - is: https://www.gnu.org/software/emacs/
 - is: https://www.transparency.org/what-is-corruption
-- startsWith: https://platform.openai.com/docs/api-reference/
-- is: https://azuredownloads-g3ahgwb5b8bkbxhd.b01.azurefd.net/github-copilot/
+- startsWith: https://azuredownloads-g3ahgwb5b8bkbxhd.b01.azurefd.net/github-copilot/
 - is: https://www.anthropic.com/claude/sonnet
 - is: https://www.psiexams.com/become-psi-test-center/computer-specifications/
 - is: https://www.buymeacoffee.com/
@@ -115,3 +112,21 @@
 - is: https://collectd.org/documentation/manpages/collectd.conf.html#plugin-fhcount
 - is: https://mywiki.wooledge.org/BashPitfalls
 - startsWith: https://code.visualstudio.com/docs/configure/telemetry
+
+# npmjs.com blocks automated link checkers with 403.
+- startsWith: https://www.npmjs.com
+
+# Azure Marketplace blocks automated link checkers with 403.
+- startsWith: https://azuremarketplace.microsoft.com
+
+# Splunk docs blocks automated link checkers with 403.
+- startsWith: https://docs.splunk.com
+
+# HashiCorp rate-limits automated requests (429).
+- startsWith: https://www.hashicorp.com
+
+# ISO website blocks automated link checkers with 403.
+- startsWith: https://www.iso.org
+
+# Example domain used in style guide documentation.
+- startsWith: https://some-docs.com

src/links/lib/extract-links.ts

@@ -16,7 +16,8 @@ import type { Context, Page } from '@/types'
 // Link patterns for Markdown
 const INTERNAL_LINK_PATTERN = /\]\(\/[^)]+\)/g
 const AUTOTITLE_LINK_PATTERN = /\[AUTOTITLE\]\(([^)]+)\)/g
-const EXTERNAL_LINK_PATTERN = /\]\((https?:\/\/[^)]+)\)/g
+// Handles one level of balanced parentheses in URLs (e.g., Wikipedia links)
+const EXTERNAL_LINK_PATTERN = /\]\((https?:\/\/(?:[^()\s]+|\([^()]*\))*)\)/g
 const IMAGE_LINK_PATTERN = /!\[[^\]]*\]\(([^)]+)\)/g
 
 // Anchor link patterns (for same-page links)
@@ -82,10 +83,19 @@ export function extractLinksFromMarkdown(content: string): LinkExtractionResult
   const anchorLinks: ExtractedLink[] = []
   const imageLinks: ExtractedLink[] = []
 
+  // Strip fenced code blocks to avoid checking example/placeholder URLs
+  // Replaces non-newline characters with spaces to preserve line numbers and positions
+  const strippedContent = content.replace(
+    /^ {0,3}(`{3,})[^\n]*\n[\s\S]*?^ {0,3}\1\s*$/gm,
+    (match) => {
+      return match.replace(/[^\n]/g, ' ')
+    },
+  )
+
   // Extract AUTOTITLE links first (they're a special case of internal links)
   let match
-  while ((match = AUTOTITLE_LINK_PATTERN.exec(content)) !== null) {
-    const { line, column } = getLineAndColumn(content, match.index)
+  while ((match = AUTOTITLE_LINK_PATTERN.exec(strippedContent)) !== null) {
+    const { line, column } = getLineAndColumn(strippedContent, match.index)
     const href = match[1].split('#')[0] // Remove anchor if present
     if (href.startsWith('/')) {
       internalLinks.push({
@@ -102,17 +112,17 @@ export function extractLinksFromMarkdown(content: string): LinkExtractionResult
   AUTOTITLE_LINK_PATTERN.lastIndex = 0
 
   // Extract regular internal links
-  while ((match = INTERNAL_LINK_PATTERN.exec(content)) !== null) {
+  while ((match = INTERNAL_LINK_PATTERN.exec(strippedContent)) !== null) {
     // Skip if this is an AUTOTITLE link (already captured)
     const fullMatch = match[0]
-    if (content.substring(match.index - 10, match.index).includes('AUTOTITLE')) {
+    if (strippedContent.substring(match.index - 10, match.index).includes('AUTOTITLE')) {
       continue
     }
 
-    const { line, column } = getLineAndColumn(content, match.index)
+    const { line, column } = getLineAndColumn(strippedContent, match.index)
     // Extract href from ](/path) format
     const href = fullMatch.substring(2, fullMatch.length - 1).split('#')[0]
-    const text = extractLinkText(content, match.index)
+    const text = extractLinkText(strippedContent, match.index)
 
     internalLinks.push({
       href,
@@ -127,10 +137,10 @@ export function extractLinksFromMarkdown(content: string): LinkExtractionResult
   INTERNAL_LINK_PATTERN.lastIndex = 0
 
   // Extract external links
-  while ((match = EXTERNAL_LINK_PATTERN.exec(content)) !== null) {
-    const { line, column } = getLineAndColumn(content, match.index)
+  while ((match = EXTERNAL_LINK_PATTERN.exec(strippedContent)) !== null) {
+    const { line, column } = getLineAndColumn(strippedContent, match.index)
     const href = match[1]
-    const text = extractLinkText(content, match.index)
+    const text = extractLinkText(strippedContent, match.index)
 
     externalLinks.push({
       href,
@@ -144,8 +154,8 @@ export function extractLinksFromMarkdown(content: string): LinkExtractionResult
   EXTERNAL_LINK_PATTERN.lastIndex = 0
 
   // Extract anchor links
-  while ((match = ANCHOR_LINK_PATTERN.exec(content)) !== null) {
-    const { line, column } = getLineAndColumn(content, match.index)
+  while ((match = ANCHOR_LINK_PATTERN.exec(strippedContent)) !== null) {
+    const { line, column } = getLineAndColumn(strippedContent, match.index)
     const href = match[0].substring(2, match[0].length - 1)
 
     anchorLinks.push({
@@ -160,8 +170,8 @@ export function extractLinksFromMarkdown(content: string): LinkExtractionResult
   ANCHOR_LINK_PATTERN.lastIndex = 0
 
   // Extract image links
-  while ((match = IMAGE_LINK_PATTERN.exec(content)) !== null) {
-    const { line, column } = getLineAndColumn(content, match.index)
+  while ((match = IMAGE_LINK_PATTERN.exec(strippedContent)) !== null) {
+    const { line, column } = getLineAndColumn(strippedContent, match.index)
     const href = match[1]
 
     // Only include internal images (starting with /)
@@ -345,6 +355,19 @@ export function checkInternalLink(
     }
   }
 
+  // Strip language prefix and check redirects (which are stored without it)
+  const langPrefixMatch = resolved.match(/^\/[a-z]{2}\//)
+  if (langPrefixMatch) {
+    const withoutLang = resolved.slice(langPrefixMatch[0].length - 1)
+    if (redirects[withoutLang]) {
+      return {
+        exists: true,
+        isRedirect: true,
+        redirectTarget: redirects[withoutLang],
+      }
+    }
+  }
+
   return { exists: false, isRedirect: false }
 }
 

src/links/tests/extract-links.ts

@@ -140,6 +140,75 @@ Also [versioned](/enterprise-server@{{ currentVersion }}/admin).
     expect(result.internalLinks.length).toBeGreaterThanOrEqual(0)
   })
 
+  test('extracts external links with parentheses in URLs', () => {
+    const content = `
+See the [shebang article](https://en.wikipedia.org/wiki/Shebang_(Unix)) for more.
+Also [Continuum](https://en.wikipedia.org/wiki/Continuum_(measurement)) is relevant.
+`
+    const result = extractLinksFromMarkdown(content)
+
+    expect(result.externalLinks).toHaveLength(2)
+    expect(result.externalLinks[0].href).toBe('https://en.wikipedia.org/wiki/Shebang_(Unix)')
+    expect(result.externalLinks[1].href).toBe(
+      'https://en.wikipedia.org/wiki/Continuum_(measurement)',
+    )
+  })
+
+  test('skips links inside fenced code blocks', () => {
+    const content = `
+Here is [a real link](https://example.com).
+
+\`\`\`yaml
+![badge](https://github.com/octocat/repo/actions/workflows/ci.yml/badge.svg)
+[example](https://fake-example.com/not-real)
+\`\`\`
+
+And [another real link](https://real.example.com/page).
+`
+    const result = extractLinksFromMarkdown(content)
+
+    expect(result.externalLinks).toHaveLength(2)
+    expect(result.externalLinks[0].href).toBe('https://example.com')
+    expect(result.externalLinks[1].href).toBe('https://real.example.com/page')
+  })
+
+  test('preserves correct line numbers when code blocks are stripped', () => {
+    const content = `Line 1
+[Link on line 2](/path/one)
+\`\`\`
+code block on line 3
+code block on line 4
+\`\`\`
+Line 6
+[Link on line 8](/path/two)
+`
+    const result = extractLinksFromMarkdown(content)
+
+    expect(result.internalLinks).toHaveLength(2)
+    expect(result.internalLinks[0].line).toBe(2)
+    // Line numbers are preserved because code block content is replaced with spaces
+    expect(result.internalLinks[1].line).toBe(8)
+  })
+
+  test('skips links inside indented fenced code blocks', () => {
+    const content = `
+Here is [a real link](https://example.com).
+
+1. Step one:
+
+   \`\`\`yaml
+   [example](https://fake-example.com/not-real)
+   \`\`\`
+
+And [another real link](https://real.example.com/page).
+`
+    const result = extractLinksFromMarkdown(content)
+
+    expect(result.externalLinks).toHaveLength(2)
+    expect(result.externalLinks[0].href).toBe('https://example.com')
+    expect(result.externalLinks[1].href).toBe('https://real.example.com/page')
+  })
+
   test('handles complex nested brackets', () => {
     const content = `
 Use the [\`git clone\`](/repositories/cloning) command.
@@ -186,6 +255,8 @@ describe('checkInternalLink', () => {
   const redirects = {
     '/en/old-path': '/en/new-path',
     '/en/deprecated': '/en/current',
+    '/enterprise-server@3.19/actions/old-path': '/enterprise-server@3.19/actions/new-path',
+    '/actions/legacy-path': '/actions/current-path',
   }
 
   test('finds direct page match', () => {
@@ -233,6 +304,25 @@ describe('checkInternalLink', () => {
     const result = checkInternalLink('/enterprise-server@latest/does/not/exist', pageMap, redirects)
     expect(result.exists).toBe(false)
   })
+
+  test('finds redirect after stripping language prefix', () => {
+    // Links from rendered HTML have /en/ prefix but redirects are stored without it
+    const result = checkInternalLink(
+      '/en/enterprise-server@3.19/actions/old-path',
+      pageMap,
+      redirects,
+    )
+    expect(result.exists).toBe(true)
+    expect(result.isRedirect).toBe(true)
+    expect(result.redirectTarget).toBe('/enterprise-server@3.19/actions/new-path')
+  })
+
+  test('finds versionless redirect after stripping language prefix', () => {
+    const result = checkInternalLink('/en/actions/legacy-path', pageMap, redirects)
+    expect(result.exists).toBe(true)
+    expect(result.isRedirect).toBe(true)
+    expect(result.redirectTarget).toBe('/actions/current-path')
+  })
 })
 
 describe('isAssetLink', () => {