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/) don't work.
The validator now flags these and suggests moving them to the correct
section's .gitbook.yaml.

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

Author: louis-pre

codegen/validate-redirects.ts

@@ -5,55 +5,136 @@ import YAML from 'yaml'
 
 import { siteSections } from './lib/config.js'
 
-const gitbookConfig = YAML.parse(readFileSync('.gitbook.yaml', 'utf-8')) as {
+interface GitbookConfig {
   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 }),
-)
+const broken: BrokenRedirect[] = []
 
-function pageExists(fullPath: string): boolean {
-  return existsSync(fullPath) && statSync(fullPath).isFile()
-}
+for (const section of siteSections) {
+  const configPath = join(section.root, '.gitbook.yaml')
+  if (!existsSync(configPath)) continue
 
-function resolveTarget(target: string): boolean {
-  for (const section of siteSections) {
-    if (section.urlPrefix === '') continue
+  const config = YAML.parse(readFileSync(configPath, 'utf-8')) as GitbookConfig
+  const redirects = config.redirects ?? {}
+  for (const [source, target] of Object.entries(redirects)) {
+    // Source must not start with another section's URL prefix
+    for (const other of siteSections) {
+      if (other.root === section.root) continue
+      const otherPrefix = other.urlPrefix.replace(/^\//, '') + '/'
+      if (otherPrefix !== '/' && source.startsWith(otherPrefix)) {
+        broken.push({
+          configPath,
+          source,
+          target,
+          reason: `Source belongs to the "${other.name}" section, not "${section.name}". Move this redirect to ${join(other.root, '.gitbook.yaml')}`,
+        })
+      }
+    }
+
+    // Target must not start with another section's URL prefix
+    for (const other of siteSections) {
+      if (other.root === section.root) continue
+      const otherPrefix = other.urlPrefix.replace(/^\//, '') + '/'
+      if (otherPrefix !== '/' && target.startsWith(otherPrefix)) {
+        broken.push({
+          configPath,
+          source,
+          target,
+          reason: `Target points to the "${other.name}" section. Move this redirect to ${join(other.root, '.gitbook.yaml')}`,
+        })
+      }
+    }
 
-    const prefix = section.urlPrefix.replace(/^\//, '') + '/'
-    if (target.startsWith(prefix)) {
-      const relativePath = target.slice(prefix.length)
-      return pageExists(join(section.root, relativePath))
+    // Target must resolve to an existing file within this section
+    const fullPath = join(section.root, target)
+    if (!existsSync(fullPath) || !statSync(fullPath).isFile()) {
+      broken.push({
+        configPath,
+        source,
+        target,
+        reason: `File not found: ${fullPath}`,
+      })
     }
   }
+}
 
-  const guidesSection = siteSections.find((s) => s.urlPrefix === '')
-  if (guidesSection == null) return false
+// Also check the root .gitbook.yaml if it's not already a section config
+const rootConfigPath = '.gitbook.yaml'
+const rootIsSection = siteSections.some(
+  (s) => join(s.root, '.gitbook.yaml') === rootConfigPath,
+)
 
-  return pageExists(join(guidesSection.root, target))
-}
+if (!rootIsSection && existsSync(rootConfigPath)) {
+  const config = YAML.parse(
+    readFileSync(rootConfigPath, 'utf-8'),
+  ) as GitbookConfig & { root?: string }
+  const redirects = config.redirects ?? {}
+  const root = (config.root ?? './').replace(/^\.\//, '').replace(/\/$/, '')
 
-const broken: Redirect[] = redirects.filter((r) => !resolveTarget(r.target))
+  const section = siteSections.find((s) => s.root === root)
+
+  for (const [source, target] of Object.entries(redirects)) {
+    for (const other of siteSections) {
+      if (section != null && other.root === section.root) continue
+      const otherPrefix = other.urlPrefix.replace(/^\//, '') + '/'
+      if (otherPrefix !== '/' && source.startsWith(otherPrefix)) {
+        broken.push({
+          configPath: rootConfigPath,
+          source,
+          target,
+          reason: `Source belongs to the "${other.name}" section. Move this redirect to ${join(other.root, '.gitbook.yaml')}`,
+        })
+      }
+    }
+
+    for (const other of siteSections) {
+      if (section != null && other.root === section.root) continue
+      const otherPrefix = other.urlPrefix.replace(/^\//, '') + '/'
+      if (otherPrefix !== '/' && target.startsWith(otherPrefix)) {
+        broken.push({
+          configPath: rootConfigPath,
+          source,
+          target,
+          reason: `Target points to the "${other.name}" section. Move this redirect to ${join(other.root, '.gitbook.yaml')}`,
+        })
+      }
+    }
+
+    const fullPath = join(root, target)
+    if (!existsSync(fullPath) || !statSync(fullPath).isFile()) {
+      broken.push({
+        configPath: rootConfigPath,
+        source,
+        target,
+        reason: `File not found: ${fullPath}`,
+      })
+    }
+  }
+}
 
 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`,
+    `Found ${broken.length} redirect issue(s):\n`,
   )
-  for (const { source, target } of broken) {
+  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.')
 }