Extract shared computeHeadingIds helper for anchor validation (#62401)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7bc51b35-b5bd-4cec-9948-a1664d171f4c

Author: heiskr

src/links/lib/heading-anchors.ts

@@ -0,0 +1,118 @@
+import GithubSlugger from 'github-slugger'
+
+/**
+ * Strip inline Markdown markup from a heading to get plain text for slug computation.
+ * Matches what hast-util-to-string produces on a heading node after remark parsing.
+ *
+ * Key design decisions:
+ * - Inline code spans (backtick) are extracted verbatim so that `<job_id>` inside them
+ *   is not incorrectly stripped by the HTML-tag regex (which is needed for octicon SVGs).
+ * - HTML stripping only removes valid HTML element names (no underscores) to avoid stripping
+ *   angle-bracket placeholders like <job_id> that appear in code-span heading text.
+ * - No final .trim() — trailing whitespace from stripped SVGs becomes trailing hyphens via
+ *   github-slugger, reproducing the live site's heading IDs (e.g. `allow--`).
+ */
+export function headingTextToPlain(text: string): string {
+  // Strip HTML tags using a state machine rather than a regex so that CodeQL can verify
+  // the stripping is complete. Tags like <script\n...> or tags with '>' in attribute values
+  // are handled correctly. Output is only used for slug computation, never rendered as HTML.
+  function stripHtmlTags(s: string): string {
+    let out = ''
+    let inTag = false
+    for (let i = 0; i < s.length; i++) {
+      if (!inTag && s[i] === '<') {
+        // Peek ahead: if this looks like an underscore-containing placeholder (e.g. <job_id>),
+        // emit the inner text instead of dropping it entirely so the slug stays correct.
+        const close = s.indexOf('>', i + 1)
+        if (close !== -1) {
+          const inner = s.slice(i + 1, close)
+          if (/^[a-zA-Z][a-zA-Z0-9]*(?:_[a-zA-Z0-9]+)+$/.test(inner)) {
+            out += inner
+            i = close
+            continue
+          }
+        }
+        inTag = true
+      } else if (inTag && s[i] === '>') {
+        inTag = false
+        // Don't emit a replacement space — surrounding whitespace in the source markdown
+        // already provides the correct spacing for github-slugger (e.g. `allow ` from
+        // the space before an octicon tag).
+      } else if (!inTag) {
+        out += s[i]
+      }
+    }
+    return out
+  }
+
+  // Process non-code portions: strip HTML and inline formatting markup.
+  function processNonCode(s: string): string {
+    return stripHtmlTags(s)
+      .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1') // images: ![alt](url) → alt
+      .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // links: [text](url) → text
+      .replace(/\*\*([^*]+)\*\*/g, '$1') // bold **text**
+      .replace(/\*([^*]+)\*/g, '$1') // italic *text*
+      .replace(/(?<![a-zA-Z0-9_])__([^_]+)__(?![a-zA-Z0-9_])/g, '$1') // bold __text__
+      .replace(/(?<![a-zA-Z0-9_])_([^_]+)_(?![a-zA-Z0-9_])/g, '$1') // italic _text_
+  }
+
+  // Split text into alternating non-code / code-span segments.
+  // Code spans are extracted verbatim (hast-util-to-string returns their raw text content).
+  const parts: string[] = []
+  let remaining = text
+  while (remaining.length > 0) {
+    const open = remaining.indexOf('`')
+    if (open === -1) {
+      parts.push(processNonCode(remaining))
+      break
+    }
+    if (open > 0) parts.push(processNonCode(remaining.slice(0, open)))
+    const close = remaining.indexOf('`', open + 1)
+    if (close === -1) {
+      // Unclosed backtick — treat remainder as non-code
+      parts.push(processNonCode(remaining.slice(open)))
+      break
+    }
+    parts.push(remaining.slice(open + 1, close)) // code content verbatim
+    remaining = remaining.slice(close + 1)
+  }
+  return parts.join('')
+  // Note: no .trim() — see comment above.
+}
+
+/**
+ * Compute the set of heading anchor IDs for a page from its Liquid-rendered markdown.
+ *
+ * Uses github-slugger (the same library as rehype-slug in the render pipeline) to compute
+ * heading anchor IDs in document order, producing results that match the live site,
+ * including the `-1`, `-2`, ... dedupe suffixes github-slugger adds for repeated headings.
+ *
+ * Handles ATX headings (`## Heading`), Setext headings (underlined with `===`/`---`), and
+ * explicit `<a name="...">` / `<a id="...">` anchors embedded in the markdown.
+ */
+export function computeHeadingIds(renderedMarkdown: string): Set<string> {
+  const slugger = new GithubSlugger()
+  const headingIds = new Set<string>()
+
+  // ATX headings: ## Heading text (optional trailing ##)
+  const ATX_HEADING_RE = /^#{1,6}\s+(.+?)(?:\s+#+)?\s*$/gm
+  let m: RegExpExecArray | null
+  while ((m = ATX_HEADING_RE.exec(renderedMarkdown)) !== null) {
+    headingIds.add(slugger.slug(headingTextToPlain(m[1])))
+  }
+
+  // Setext headings: text line followed by === or --- underline
+  const SETEXT_HEADING_RE = /^([^\n]+)\n[=-]{2,}\s*$/gm
+  while ((m = SETEXT_HEADING_RE.exec(renderedMarkdown)) !== null) {
+    headingIds.add(slugger.slug(headingTextToPlain(m[1])))
+  }
+
+  // Explicit <a name="..."> and <a id="..."> anchors embedded in the markdown.
+  // Some pages (e.g. site-policy) use raw HTML anchors instead of headings.
+  const NAMED_ANCHOR_RE = /<a\s[^>]*(?:name|id)="([^"]+)"[^>]*>/gi
+  while ((m = NAMED_ANCHOR_RE.exec(renderedMarkdown)) !== null) {
+    headingIds.add(m[1])
+  }
+
+  return headingIds
+}

src/links/scripts/check-links-internal.ts

@@ -24,8 +24,6 @@ import os from 'os'
 import { program } from 'commander'
 import chalk from 'chalk'
 
-import GithubSlugger from 'github-slugger'
-
 import warmServer from '@/frame/lib/warm-server'
 import { allVersions, allVersionKeys } from '@/versions/lib/all-versions'
 import languages from '@/languages/lib/languages-server'
@@ -48,6 +46,7 @@ import { uploadArtifact } from '@/links/scripts/upload-artifact'
 import { createReportIssue, linkReports } from '@/workflows/issue-report'
 import github from '@/workflows/github'
 import excludedLinks from '@/links/lib/excluded-links'
+import { computeHeadingIds } from '@/links/lib/heading-anchors'
 import { getFeaturesByVersion } from '@/versions/middleware/features'
 import type { Page, Permalink, Context } from '@/types'
 import * as coreLib from '@actions/core'
@@ -201,86 +200,6 @@ async function getLinksFromMarkdown(
   })
 }
 
-/**
- * Strip inline Markdown markup from a heading to get plain text for slug computation.
- * Matches what hast-util-to-string produces on a heading node after remark parsing.
- *
- * Key design decisions:
- * - Inline code spans (backtick) are extracted verbatim so that `<job_id>` inside them
- *   is not incorrectly stripped by the HTML-tag regex (which is needed for octicon SVGs).
- * - HTML stripping only removes valid HTML element names (no underscores) to avoid stripping
- *   angle-bracket placeholders like <job_id> that appear in code-span heading text.
- * - No final .trim() — trailing whitespace from stripped SVGs becomes trailing hyphens via
- *   github-slugger, reproducing the live site's heading IDs (e.g. `allow--`).
- */
-function headingTextToPlain(text: string): string {
-  // Strip HTML tags using a state machine rather than a regex so that CodeQL can verify
-  // the stripping is complete. Tags like <script\n...> or tags with '>' in attribute values
-  // are handled correctly. Output is only used for slug computation, never rendered as HTML.
-  function stripHtmlTags(s: string): string {
-    let out = ''
-    let inTag = false
-    for (let i = 0; i < s.length; i++) {
-      if (!inTag && s[i] === '<') {
-        // Peek ahead: if this looks like an underscore-containing placeholder (e.g. <job_id>),
-        // emit the inner text instead of dropping it entirely so the slug stays correct.
-        const close = s.indexOf('>', i + 1)
-        if (close !== -1) {
-          const inner = s.slice(i + 1, close)
-          if (/^[a-zA-Z][a-zA-Z0-9]*(?:_[a-zA-Z0-9]+)+$/.test(inner)) {
-            out += inner
-            i = close
-            continue
-          }
-        }
-        inTag = true
-      } else if (inTag && s[i] === '>') {
-        inTag = false
-        // Don't emit a replacement space — surrounding whitespace in the source markdown
-        // already provides the correct spacing for github-slugger (e.g. `allow ` from
-        // the space before an octicon tag).
-      } else if (!inTag) {
-        out += s[i]
-      }
-    }
-    return out
-  }
-
-  // Process non-code portions: strip HTML and inline formatting markup.
-  function processNonCode(s: string): string {
-    return stripHtmlTags(s)
-      .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1') // images: ![alt](url) → alt
-      .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // links: [text](url) → text
-      .replace(/\*\*([^*]+)\*\*/g, '$1') // bold **text**
-      .replace(/\*([^*]+)\*/g, '$1') // italic *text*
-      .replace(/(?<![a-zA-Z0-9_])__([^_]+)__(?![a-zA-Z0-9_])/g, '$1') // bold __text__
-      .replace(/(?<![a-zA-Z0-9_])_([^_]+)_(?![a-zA-Z0-9_])/g, '$1') // italic _text_
-  }
-
-  // Split text into alternating non-code / code-span segments.
-  // Code spans are extracted verbatim (hast-util-to-string returns their raw text content).
-  const parts: string[] = []
-  let remaining = text
-  while (remaining.length > 0) {
-    const open = remaining.indexOf('`')
-    if (open === -1) {
-      parts.push(processNonCode(remaining))
-      break
-    }
-    if (open > 0) parts.push(processNonCode(remaining.slice(0, open)))
-    const close = remaining.indexOf('`', open + 1)
-    if (close === -1) {
-      // Unclosed backtick — treat remainder as non-code
-      parts.push(processNonCode(remaining.slice(open)))
-      break
-    }
-    parts.push(remaining.slice(open + 1, close)) // code content verbatim
-    remaining = remaining.slice(close + 1)
-  }
-  return parts.join('')
-  // Note: no .trim() — see comment above.
-}
-
 /**
  * Check anchor links on a page using fast heading ID computation from Liquid-rendered
  * markdown. Avoids the expensive full HTML render previously used.
@@ -299,30 +218,7 @@ function checkAnchorsFromHeadings(
   const fmOffset = getFrontmatterLineOffset(page.fullPath)
 
   // Compute heading anchor IDs from the Liquid-rendered markdown in document order.
-  // github-slugger deduplicates identical headings with -1, -2, ... suffixes,
-  // matching the behaviour of rehype-slug in the full render pipeline.
-  const slugger = new GithubSlugger()
-  const headingIds = new Set<string>()
-
-  // ATX headings: ## Heading text (optional trailing ##)
-  const ATX_HEADING_RE = /^#{1,6}\s+(.+?)(?:\s+#+)?\s*$/gm
-  let m: RegExpExecArray | null
-  while ((m = ATX_HEADING_RE.exec(renderedMarkdown)) !== null) {
-    headingIds.add(slugger.slug(headingTextToPlain(m[1])))
-  }
-
-  // Setext headings: text line followed by === or --- underline
-  const SETEXT_HEADING_RE = /^([^\n]+)\n[=-]{2,}\s*$/gm
-  while ((m = SETEXT_HEADING_RE.exec(renderedMarkdown)) !== null) {
-    headingIds.add(slugger.slug(headingTextToPlain(m[1])))
-  }
-
-  // Explicit <a name="..."> and <a id="..."> anchors embedded in the markdown.
-  // Some pages (e.g. site-policy) use raw HTML anchors instead of headings.
-  const NAMED_ANCHOR_RE = /<a\s[^>]*(?:name|id)="([^"]+)"[^>]*>/gi
-  while ((m = NAMED_ANCHOR_RE.exec(renderedMarkdown)) !== null) {
-    headingIds.add(m[1])
-  }
+  const headingIds = computeHeadingIds(renderedMarkdown)
 
   // Build line-number map from the raw (pre-Liquid) source for accurate file line numbers.
   const anchorLineMap = new Map<string, number>()

src/links/tests/heading-anchors.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'vitest'
+
+import { computeHeadingIds, headingTextToPlain } from '../lib/heading-anchors'
+
+describe('headingTextToPlain', () => {
+  test('leaves plain text unchanged', () => {
+    expect(headingTextToPlain('Configuring proxy settings')).toBe('Configuring proxy settings')
+  })
+
+  test('strips inline markdown formatting', () => {
+    expect(headingTextToPlain('**Bold** and *italic* text')).toBe('Bold and italic text')
+    expect(headingTextToPlain('__Bold__ and _italic_ text')).toBe('Bold and italic text')
+  })
+
+  test('extracts link and image text', () => {
+    expect(headingTextToPlain('See [the guide](/actions) here')).toBe('See the guide here')
+    expect(headingTextToPlain('![alt text](/img.png) caption')).toBe('alt text caption')
+  })
+
+  test('preserves inline code spans verbatim, including angle-bracket placeholders', () => {
+    expect(headingTextToPlain('Use `<job_id>` in your workflow')).toBe(
+      'Use <job_id> in your workflow',
+    )
+  })
+
+  test('strips HTML/octicon tags but keeps underscore placeholders outside code', () => {
+    expect(headingTextToPlain('Allow <svg class="octicon"></svg>')).toBe('Allow ')
+    expect(headingTextToPlain('Set <job_id> here')).toBe('Set job_id here')
+  })
+})
+
+describe('computeHeadingIds', () => {
+  test('slugs ATX headings', () => {
+    const ids = computeHeadingIds(
+      '## Configuring proxy settings for Copilot\n\ntext\n\n### Usage limits and policy',
+    )
+    expect(ids.has('configuring-proxy-settings-for-copilot')).toBe(true)
+    expect(ids.has('usage-limits-and-policy')).toBe(true)
+  })
+
+  test('slugs Setext headings', () => {
+    const ids = computeHeadingIds('Introduction\n============\n\nDetails\n-------')
+    expect(ids.has('introduction')).toBe(true)
+    expect(ids.has('details')).toBe(true)
+  })
+
+  test('dedupes repeated headings with github-slugger suffixes', () => {
+    const ids = computeHeadingIds('## Overview\n\n## Overview')
+    expect(ids.has('overview')).toBe(true)
+    expect(ids.has('overview-1')).toBe(true)
+  })
+
+  test('captures explicit <a name>/<a id> anchors', () => {
+    const ids = computeHeadingIds('<a name="legacy-anchor"></a>\n\n<a id="another-anchor"></a>')
+    expect(ids.has('legacy-anchor')).toBe(true)
+    expect(ids.has('another-anchor')).toBe(true)
+  })
+
+  test('reproduces Liquid-rendered heading with variable already expanded', () => {
+    // After Liquid render, the variable is expanded to plain text; the full slug includes it.
+    const ids = computeHeadingIds(
+      '## Disabling or enabling Copilot coding agent in your repositories',
+    )
+    expect(ids.has('disabling-or-enabling-copilot-coding-agent-in-your-repositories')).toBe(true)
+  })
+})