Validate cross-page anchor links in the internal link checker (#62411)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7bc51b35-b5bd-4cec-9948-a1664d171f4c
Copilot-Session: 3993852f-89f9-401f-a2f8-2753a3d0ad43

Author: heiskr

src/links/lib/cross-page-anchors.ts

@@ -0,0 +1,51 @@
+import type { BrokenLink } from '@/links/lib/link-report'
+
+/**
+ * A cross-page anchor link (`/some/path#fragment`) collected during pass 1 of the
+ * internal link checker, to be validated in pass 2 once every page's heading IDs are known.
+ */
+export interface PendingCrossPageAnchor {
+  targetKey: string
+  fragment: string
+  href: string
+  file: string
+  line: number
+  text?: string
+}
+
+/**
+ * Pass 2 of cross-page anchor validation: given the collected cross-page anchor links
+ * and the fully-populated per-page heading ID cache, return the links whose fragment is
+ * missing from the target page.
+ *
+ * A target with no cache entry is skipped, not flagged. That happens when the target
+ * resolves to a version not covered by the current run, or the target is an autogenerated
+ * page whose anchors resolve at runtime. Note the scheduled matrix does not run every
+ * version, so an anchor whose target only resolves to an uncovered version is currently
+ * not validated anywhere: closing that gap is follow-up guardrail work. Kept as a pure
+ * function so the two-pass behavior can be tested without rendering the whole site.
+ *
+ * `#top` is exempt, mirroring the same-page anchor check. Per the HTML spec a browser
+ * scrolls to the top of the document for `#top` when nothing carries that ID, so it is
+ * always valid and never appears in a page's computed heading IDs.
+ */
+export function validateCrossPageAnchors(
+  pendingCrossPageAnchors: PendingCrossPageAnchor[],
+  headingIdsByPageKey: Map<string, Set<string>>,
+): BrokenLink[] {
+  const broken: BrokenLink[] = []
+  for (const anchor of pendingCrossPageAnchors) {
+    if (anchor.fragment === 'top') continue
+    const targetHeadingIds = headingIdsByPageKey.get(anchor.targetKey)
+    if (!targetHeadingIds) continue
+    if (!targetHeadingIds.has(anchor.fragment)) {
+      broken.push({
+        href: anchor.href,
+        file: anchor.file,
+        lines: [anchor.line],
+        text: anchor.text,
+      })
+    }
+  }
+  return broken
+}

src/links/lib/extract-links.ts

@@ -46,6 +46,13 @@ export interface ExtractedLink {
   isAutotitle?: boolean
   isImage?: boolean
   isAnchor?: boolean
+  /**
+   * The URL fragment (the part after `#`) for internal links that carry one, e.g.
+   * `some-heading` for `/foo/bar#some-heading`. `href` keeps the fragment stripped
+   * (so path resolution is unaffected); this field preserves it for cross-page anchor
+   * validation. Undefined when the link has no fragment.
+   */
+  fragment?: string
 }
 
 export interface LinkExtractionResult {
@@ -126,6 +133,17 @@ export function extractLinksFromMarkdown(content: string): LinkExtractionResult
   const imageLinks: ExtractedLink[] = []
   const liquidPrefixedLinks: ExtractedLink[] = []
 
+  // Split an internal link destination into its path and optional fragment.
+  // href keeps the fragment stripped (so path resolution is unaffected); the
+  // fragment is returned separately for cross-page anchor validation. An empty
+  // fragment (a trailing bare `#`) is treated as no fragment.
+  const splitFragment = (raw: string): { href: string; fragment?: string } => {
+    const hashIndex = raw.indexOf('#')
+    if (hashIndex === -1) return { href: raw }
+    const fragment = raw.slice(hashIndex + 1)
+    return { href: raw.slice(0, hashIndex), fragment: fragment.length ? fragment : undefined }
+  }
+
   // Strip fenced code blocks to avoid checking example/placeholder URLs
   // Replaces non-newline characters with spaces to preserve line numbers and positions
   const withoutFences = content.replace(
@@ -156,14 +174,15 @@ export function extractLinksFromMarkdown(content: string): LinkExtractionResult
   let match
   while ((match = AUTOTITLE_LINK_PATTERN.exec(strippedContent)) !== null) {
     const { line, column } = getLineAndColumn(lineOffsets, match.index)
-    const href = match[1].split('#')[0] // Remove anchor if present
+    const { href, fragment } = splitFragment(match[1]) // Split off anchor if present
     if (href.startsWith('/')) {
       internalLinks.push({
         href,
         line,
         column,
         text: 'AUTOTITLE',
         isAutotitle: true,
+        fragment,
       })
     }
   }
@@ -181,7 +200,7 @@ export function extractLinksFromMarkdown(content: string): LinkExtractionResult
     const { line, column } = getLineAndColumn(lineOffsets, match.index)
     // Extract href from ](/path) format. The destination is captured in group 1,
     // which handles balanced parentheses (e.g. asset filenames like `(fr).pdf`).
-    const href = match[1].split('#')[0]
+    const { href, fragment } = splitFragment(match[1])
     const text = extractLinkText(strippedContent, match.index)
 
     internalLinks.push({
@@ -190,6 +209,7 @@ export function extractLinksFromMarkdown(content: string): LinkExtractionResult
       column,
       text,
       isAutotitle: false,
+      fragment,
     })
   }
 
@@ -252,12 +272,13 @@ export function extractLinksFromMarkdown(content: string): LinkExtractionResult
   // These are distinct from inline links but point to the same targets that need validating.
   while ((match = LINK_DEFINITION_PATTERN.exec(strippedContent)) !== null) {
     const { line, column } = getLineAndColumn(lineOffsets, match.index)
-    const href = match[1].split('#')[0]
+    const { href, fragment } = splitFragment(match[1])
     internalLinks.push({
       href,
       line,
       column,
       isAutotitle: false,
+      fragment,
     })
   }
 
@@ -416,6 +437,34 @@ export function normalizeLinkPath(href: string): string {
   return normalized
 }
 
+/**
+ * Resolve an internal link href to the exact pageMap key of the page it lands on,
+ * but ONLY for direct (non-redirect) hits. Returns null when the link doesn't
+ * resolve directly to a page (redirect, archived version, or broken).
+ *
+ * This mirrors the two direct-hit branches of `checkInternalLink` (a bare path or a
+ * language-prefixed path). It's used by the cross-page anchor checker to look up the
+ * target page's precomputed heading IDs. Redirects are intentionally excluded: the
+ * link is already reported as a redirect-to-update, and its final anchor is ambiguous.
+ */
+export function resolveInternalLinkKey(href: string, pageMap: Record<string, Page>): string | null {
+  const normalized = normalizeLinkPath(href)
+
+  const latestPrefix = '/enterprise-server@latest'
+  const stablePrefix = `/enterprise-server@${latestStable}`
+  const resolved =
+    normalized.startsWith(latestPrefix) || normalized.startsWith(`/en${latestPrefix}`)
+      ? normalized.replace(latestPrefix, stablePrefix)
+      : normalized
+
+  if (pageMap[resolved]) return resolved
+
+  const withLang = `/en${resolved}`
+  if (pageMap[withLang]) return withLang
+
+  return null
+}
+
 /**
  * Check if a path exists in the pageMap or redirects
  */

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

@@ -30,6 +30,7 @@ import languages from '@/languages/lib/languages-server'
 import {
   normalizeLinkPath,
   checkInternalLink,
+  resolveInternalLinkKey,
   checkAssetLink,
   isAssetLink,
   extractLinksWithLiquid,
@@ -46,6 +47,10 @@ 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 {
+  validateCrossPageAnchors,
+  type PendingCrossPageAnchor,
+} from '@/links/lib/cross-page-anchors'
 import { computeHeadingIds } from '@/links/lib/heading-anchors'
 import { getFeaturesByVersion } from '@/versions/middleware/features'
 import type { Page, Permalink, Context } from '@/types'
@@ -119,7 +124,7 @@ async function getLinksFromMarkdown(
   context: Context,
   precomputedRawResult?: LinkExtractionResult,
   prerenderedResult?: LinkExtractionResult,
-): Promise<{ href: string; text: string | undefined; line: number }[]> {
+): Promise<{ href: string; text: string | undefined; line: number; fragment?: string }[]> {
   const fmOffset = getFrontmatterLineOffset(page.fullPath)
 
   // Build a map of raw-markdown line numbers per href, plus a parallel index
@@ -189,14 +194,18 @@ async function getLinksFromMarkdown(
   // extractLinksWithLiquid already catches Liquid render failures internally and
   // falls back to raw extraction with a warning, so no outer try/catch is needed.
   const renderedResult = prerenderedResult ?? (await extractLinksWithLiquid(page.markdown, context))
-  const renderedLinks = renderedResult.internalLinks.map((l) => ({ href: l.href, text: l.text }))
+  const renderedLinks = renderedResult.internalLinks.map((l) => ({
+    href: l.href,
+    text: l.text,
+    fragment: l.fragment,
+  }))
 
   return renderedLinks.map((link) => {
     const lines = rawLinesByHref.get(link.href)
     const idx = rawLinesIndex.get(link.href) ?? 0
     const line = lines && idx < lines.length ? lines[idx] : 0
     rawLinesIndex.set(link.href, idx + 1)
-    return { href: link.href, text: link.text, line }
+    return { href: link.href, text: link.text, line, fragment: link.fragment }
   })
 }
 
@@ -206,20 +215,18 @@ async function getLinksFromMarkdown(
  *
  * Uses github-slugger (the same library as rehype-slug in the render pipeline) to compute
  * heading anchor IDs, producing results that match the live site.
+ *
+ * `headingIds` is precomputed once per page in checkPage and shared with the cross-page
+ * anchor cache, so this function only checks same-page (`#fragment`) links here.
  */
 function checkAnchorsFromHeadings(
   page: Page,
   rawResult: LinkExtractionResult,
   renderedResult: LinkExtractionResult,
-  renderedMarkdown: string,
+  headingIds: Set<string>,
 ): BrokenLink[] {
-  if (page.autogenerated) return []
-
   const fmOffset = getFrontmatterLineOffset(page.fullPath)
 
-  // Compute heading anchor IDs from the Liquid-rendered markdown in document order.
-  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>()
   for (const link of rawResult.anchorLinks) {
@@ -259,9 +266,16 @@ async function checkPage(
   pageMap: Record<string, Page>,
   redirects: Record<string, string>,
   options: { checkAnchors: boolean },
-): Promise<{ brokenLinks: BrokenLink[]; redirectLinks: BrokenLink[]; linksChecked: number }> {
+): Promise<{
+  brokenLinks: BrokenLink[]
+  redirectLinks: BrokenLink[]
+  linksChecked: number
+  headingIds: Set<string> | null
+  crossPageAnchors: PendingCrossPageAnchor[]
+}> {
   const brokenLinks: BrokenLink[] = []
   const redirectLinks: BrokenLink[] = []
+  const crossPageAnchors: PendingCrossPageAnchor[] = []
 
   const rawMarkdownLinks = extractLinksFromMarkdown(page.markdown)
 
@@ -272,6 +286,15 @@ async function checkPage(
     pageContext,
   )
 
+  // Compute this page's heading anchor IDs once from the Liquid-rendered markdown.
+  // Autogenerated pages (REST/GraphQL/webhooks) derive their anchors from OpenAPI
+  // operation IDs, not markdown headings, so we can't compute them here — leave them
+  // out of the cache so links into them are never flagged (they resolve at runtime).
+  // Skip the work entirely when anchor checking is disabled: nothing downstream reads
+  // the heading cache in that mode.
+  const headingIds =
+    options.checkAnchors && !page.autogenerated ? computeHeadingIds(renderedMarkdown) : null
+
   const links = await getLinksFromMarkdown(page, pageContext, rawMarkdownLinks, renderedLinkResult)
 
   for (const link of links) {
@@ -309,20 +332,35 @@ async function checkPage(
         isRedirect: true,
         redirectTarget: result.redirectTarget,
       })
+    } else if (options.checkAnchors && link.fragment) {
+      // Direct (non-redirect) hit with a fragment: defer a cross-page anchor check.
+      // We can't validate it now because the target page may not have been rendered
+      // yet, so collect it and validate after the whole version finishes.
+      const targetKey = resolveInternalLinkKey(link.href, pageMap)
+      if (targetKey) {
+        crossPageAnchors.push({
+          targetKey,
+          fragment: link.fragment,
+          href: `${link.href}#${link.fragment}`,
+          file: page.relativePath,
+          line: link.line,
+          text: link.text,
+        })
+      }
     }
   }
 
-  if (options.checkAnchors) {
+  if (options.checkAnchors && headingIds) {
     const anchorFlaws = checkAnchorsFromHeadings(
       page,
       rawMarkdownLinks,
       renderedLinkResult,
-      renderedMarkdown,
+      headingIds,
     )
     brokenLinks.push(...anchorFlaws)
   }
 
-  return { brokenLinks, redirectLinks, linksChecked: links.length }
+  return { brokenLinks, redirectLinks, linksChecked: links.length, headingIds, crossPageAnchors }
 }
 
 /**
@@ -370,6 +408,17 @@ async function checkVersion(
   let totalPagesChecked = 0
   let totalLinksChecked = 0
 
+  // Cross-page anchor validation is a two-pass process within the version:
+  //   pass 1 — render every page, caching its heading IDs and collecting the
+  //            cross-page anchor links it contains (target may not be rendered yet)
+  //   pass 2 — after all pages are rendered, validate each collected anchor against
+  //            the now-complete heading cache
+  // The cache is keyed by pageMap key (lang + version + path). A link whose target
+  // resolves to a different version isn't in this run's cache and is skipped here;
+  // it's validated when the workflow runs the checker for that target version.
+  const headingIdsByPageKey = new Map<string, Set<string>>()
+  const pendingCrossPageAnchors: PendingCrossPageAnchor[] = []
+
   // Bounded concurrency: process up to `options.concurrency` pages simultaneously.
   // All workers drain from the same shared iterator — no page is processed twice.
   const queue = relevantPages.entries()
@@ -389,6 +438,10 @@ async function checkVersion(
       // between await points cannot interleave with another worker's pushes.
       allBrokenLinks.push(...result.brokenLinks)
       allRedirectLinks.push(...result.redirectLinks)
+      if (result.headingIds) headingIdsByPageKey.set(permalink.href, result.headingIds)
+      if (result.crossPageAnchors.length) {
+        pendingCrossPageAnchors.push(...result.crossPageAnchors)
+      }
       totalPagesChecked++
       totalLinksChecked += result.linksChecked
 
@@ -401,6 +454,11 @@ async function checkVersion(
   // Launch `concurrency` workers that all drain from the same shared queue iterator.
   await Promise.all(Array.from({ length: options.concurrency }, worker))
 
+  // Pass 2: validate cross-page anchors now that every page's headings are cached.
+  if (options.checkAnchors) {
+    allBrokenLinks.push(...validateCrossPageAnchors(pendingCrossPageAnchors, headingIdsByPageKey))
+  }
+
   return {
     brokenLinks: allBrokenLinks,
     redirectLinks: allRedirectLinks,