ci: Validate redirects belong to their config's site section

The root .gitbook.yaml is rooted at docs/guides/, so redirects with
sources or targets in other sections (api/, brand-guides/) can't work
as space-level redirects. The validator now checks each redirect
belongs to its config's section and suggests using site-level
redirects in the GitBook UI for cross-section cases.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: louis-pre

codegen/validate-redirects.ts

@@ -5,55 +5,111 @@ import YAML from 'yaml'
 
 import { siteSections } from './lib/config.js'
 
-const gitbookConfig = YAML.parse(readFileSync('.gitbook.yaml', 'utf-8')) as {
+interface GitbookConfig {
+  root?: string
   redirects?: Record<string, string>
 }
 
-interface Redirect {
+interface BrokenRedirect {
+  configPath: string
   source: string
   target: string
+  reason: string
 }
 
-const redirects: Redirect[] = Object.entries(gitbookConfig.redirects ?? {}).map(
-  ([source, target]) => ({ source, target }),
-)
+function findForeignSection(path: string, ownRoot: string): string | undefined {
+  for (const other of siteSections) {
+    if (other.root === ownRoot) continue
+    const prefix = other.urlPrefix.replace(/^\//, '') + '/'
+    if (prefix !== '/' && path.startsWith(prefix)) return other.name
+  }
+  return undefined
+}
 
-function pageExists(fullPath: string): boolean {
-  return existsSync(fullPath) && statSync(fullPath).isFile()
+const broken: BrokenRedirect[] = []
+
+interface ConfigToValidate {
+  configPath: string
+  root: string
+  redirects: Record<string, string>
 }
 
-function resolveTarget(target: string): boolean {
-  for (const section of siteSections) {
-    if (section.urlPrefix === '') continue
+const configs: ConfigToValidate[] = []
+
+for (const section of siteSections) {
+  const configPath = join(section.root, '.gitbook.yaml')
+  if (!existsSync(configPath)) continue
+  const config = YAML.parse(readFileSync(configPath, 'utf-8')) as GitbookConfig
+  configs.push({
+    configPath,
+    root: section.root,
+    redirects: config.redirects ?? {},
+  })
+}
+
+const rootConfigPath = '.gitbook.yaml'
+const rootIsSection = configs.some((c) => c.configPath === rootConfigPath)
+if (!rootIsSection && existsSync(rootConfigPath)) {
+  const config = YAML.parse(
+    readFileSync(rootConfigPath, 'utf-8'),
+  ) as GitbookConfig
+  const root = (config.root ?? './').replace(/^\.\//, '').replace(/\/$/, '')
+  configs.push({
+    configPath: rootConfigPath,
+    root,
+    redirects: config.redirects ?? {},
+  })
+}
 
-    const prefix = section.urlPrefix.replace(/^\//, '') + '/'
-    if (target.startsWith(prefix)) {
-      const relativePath = target.slice(prefix.length)
-      return pageExists(join(section.root, relativePath))
+for (const { configPath, root, redirects } of configs) {
+  for (const [source, target] of Object.entries(redirects)) {
+    const foreignSource = findForeignSection(source, root)
+    if (foreignSource != null) {
+      broken.push({
+        configPath,
+        source,
+        target,
+        reason: `Source belongs to the "${foreignSource}" section. Use a site-level redirect in the GitBook UI instead`,
+      })
+      continue
     }
-  }
 
-  const guidesSection = siteSections.find((s) => s.urlPrefix === '')
-  if (guidesSection == null) return false
+    const foreignTarget = findForeignSection(target, root)
+    if (foreignTarget != null) {
+      broken.push({
+        configPath,
+        source,
+        target,
+        reason: `Target points to the "${foreignTarget}" section. Use a site-level redirect in the GitBook UI instead`,
+      })
+      continue
+    }
 
-  return pageExists(join(guidesSection.root, target))
+    const fullPath = join(root, target)
+    if (!existsSync(fullPath) || !statSync(fullPath).isFile()) {
+      broken.push({
+        configPath,
+        source,
+        target,
+        reason: `File not found: ${fullPath}`,
+      })
+    }
+  }
 }
 
-const broken: Redirect[] = redirects.filter((r) => !resolveTarget(r.target))
-
 if (broken.length > 0) {
   // eslint-disable-next-line no-console
-  console.error(
-    `Found ${broken.length} redirect(s) with missing target(s) in .gitbook.yaml:\n`,
-  )
-  for (const { source, target } of broken) {
+  console.error(`Found ${broken.length} redirect issue(s):\n`)
+  for (const { configPath, source, target, reason } of broken) {
+    // eslint-disable-next-line no-console
+    console.error(`  [${configPath}] ${source}`)
     // eslint-disable-next-line no-console
-    console.error(`  ${source}`)
+    console.error(`    target: ${target}`)
     // eslint-disable-next-line no-console
-    console.error(`    target: ${target}\n`)
+    console.error(`    ${reason}\n`)
   }
   process.exit(1)
 } else {
   // eslint-disable-next-line no-console
-  console.log('All .gitbook.yaml redirect targets are valid.')
+  console.log('All redirect targets are valid.')
 }