Fix internal link checker false positives via runtime redirect resolver (#62098)

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

Author: heiskr

src/links/lib/extract-links.ts

@@ -12,6 +12,8 @@ import { createLogger } from '@/observability/logger'
 import { allVersions } from '@/versions/lib/all-versions'
 import { latestStable } from '@/versions/lib/enterprise-server-releases'
 import { getDataByLanguage } from '@/data-directory/lib/get-data'
+import getRedirect from '@/redirects/lib/get-redirect'
+import { isArchivedVersionByPath } from '@/archives/lib/is-archived-version'
 import type { Context, Page } from '@/types'
 
 const logger = createLogger(import.meta.url)
@@ -447,8 +449,10 @@ export function checkInternalLink(
     }
   }
 
-  // Strip language prefix and check redirects (which are stored without it)
-  const langPrefixMatch = resolved.match(/^\/[a-z]{2}\//)
+  // Strip language prefix and check redirects (which are stored without it).
+  // Match hyphenated locales too (e.g. /pt-br/, /zh-cn/) so we don't later
+  // double-prefix them with /en.
+  const langPrefixMatch = resolved.match(/^\/[a-z]{2}(-[a-z]{2})?\//)
   if (langPrefixMatch) {
     const withoutLang = resolved.slice(langPrefixMatch[0].length - 1)
     if (redirects[withoutLang]) {
@@ -460,6 +464,49 @@ export function checkInternalLink(
     }
   }
 
+  // The path in language-prefixed form, used by the runtime resolvers below.
+  // Avoid double-prefixing when the link already carried a language code.
+  const withEn = langPrefixMatch ? resolved : withLang
+
+  // Links into deprecated/archived Enterprise Server versions (e.g.
+  // /enterprise-server@3.7/... or the legacy /enterprise/2.1/... format) are
+  // served by the archived enterprise versions system, which isn't loaded into
+  // pageMap. They resolve fine at runtime, so treat them as valid rather than
+  // broken.
+  if (isArchivedVersionByPath(withEn).isArchived) {
+    return { exists: true, isRedirect: false }
+  }
+
+  // Fall back to the runtime redirect resolver. It handles algorithmic
+  // corrections (version-prefix normalization, /admin, /desktop/guides, etc.)
+  // that the flat redirects map doesn't contain as literal keys. This mirrors
+  // what the production server actually does, so a link that redirects in
+  // production is reported as a redirect here instead of a false broken link.
+  try {
+    // Only redirects, userLanguage, and pages are read by getRedirect (and the
+    // resolvers it delegates to), so type the object to those fields rather than
+    // casting an arbitrary shape to the full Context.
+    const context: Pick<Context, 'redirects' | 'userLanguage' | 'pages'> = {
+      redirects,
+      userLanguage: 'en',
+      pages: pageMap,
+    }
+    const redirect = getRedirect(withEn, context as unknown as Context)
+    if (redirect) {
+      // getRedirect returns a language-prefixed path (e.g. /en/...); strip any
+      // locale prefix to match the format used by the flat-map branches above,
+      // and normalize a bare language root (e.g. /en) to /.
+      return {
+        exists: true,
+        isRedirect: true,
+        redirectTarget: redirect.replace(/^\/[a-z]{2}(-[a-z]{2})?(?=\/|$)/, '') || '/',
+      }
+    }
+  } catch {
+    // getRedirect throws on a few fully-deprecated shapes (e.g. github-ae).
+    // Treat those as unresolvable rather than crashing the whole check.
+  }
+
   return { exists: false, isRedirect: false }
 }
 

src/links/tests/extract-links.ts

@@ -434,6 +434,63 @@ describe('checkInternalLink', () => {
     expect(result.isRedirect).toBe(true)
     expect(result.redirectTarget).toBe('/actions/current-path')
   })
+
+  test('treats archived Enterprise Server versions as valid', () => {
+    // Deprecated GHES versions are served by the archived enterprise versions
+    // system, which isn't loaded into pageMap. They must not be reported broken.
+    const result = checkInternalLink(
+      '/enterprise-server@3.7/admin/release-notes',
+      pageMap,
+      redirects,
+    )
+    expect(result.exists).toBe(true)
+    expect(result.isRedirect).toBe(false)
+  })
+
+  test('treats legacy /enterprise/<version>/ archived paths as valid', () => {
+    const result = checkInternalLink(
+      '/enterprise/2.1/admin/guides/installation/provisioning-and-installation/',
+      pageMap,
+      redirects,
+    )
+    expect(result.exists).toBe(true)
+    expect(result.isRedirect).toBe(false)
+  })
+
+  test('resolves free-pro-team@latest prefixed links via the redirect resolver', () => {
+    // The flat redirects map has no literal key for this; getRedirect computes
+    // the correction (strip the version prefix) the same way production does.
+    const result = checkInternalLink('/free-pro-team@latest/actions/guides', pageMap, redirects)
+    expect(result.exists).toBe(true)
+    expect(result.isRedirect).toBe(true)
+    expect(result.redirectTarget).toBe('/actions/guides')
+  })
+
+  test('resolves versionless /enterprise-server/ links via the redirect resolver', () => {
+    const result = checkInternalLink(`/enterprise-server/admin/overview`, pageMap, redirects)
+    expect(result.exists).toBe(true)
+    expect(result.isRedirect).toBe(true)
+    // Normalized to the latest stable Enterprise Server version.
+    expect(result.redirectTarget).toBe(`/enterprise-server@${latestStable}/admin/overview`)
+  })
+
+  test('strips hyphenated locale prefixes without double-prefixing', () => {
+    // /pt-br/ is a hyphenated locale; it must be stripped (not turned into
+    // /en/pt-br/...) so the underlying path resolves against the redirects map.
+    const result = checkInternalLink('/pt-br/actions/legacy-path', pageMap, redirects)
+    expect(result.exists).toBe(true)
+    expect(result.isRedirect).toBe(true)
+    expect(result.redirectTarget).toBe('/actions/current-path')
+  })
+
+  test('normalizes a bare language-root redirect target to /', () => {
+    // getRedirect collapses '/free-pro-team@latest' to the language root ('/en');
+    // after stripping the locale that would be empty, so it must normalize to '/'.
+    const result = checkInternalLink('/free-pro-team@latest', pageMap, redirects)
+    expect(result.exists).toBe(true)
+    expect(result.isRedirect).toBe(true)
+    expect(result.redirectTarget).toBe('/')
+  })
 })
 
 describe('isAssetLink', () => {