Add cross-site link validator

Scans all markdown files for absolute docs.seam.co URLs and verifies
the target page exists in the correct site section directory. Uses
the centralized config for URL prefix → directory mapping.

Run with: npm run validate-links

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

Author: louis-pre

.github/workflows/generate.yml

@@ -66,3 +66,17 @@ jobs:
           commit_user_name: ${{ secrets.GIT_USER_NAME }}
           commit_user_email: ${{ secrets.GIT_USER_EMAIL }}
           commit_author: ${{ secrets.GIT_USER_NAME }} <${{ secrets.GIT_USER_EMAIL }}>
+  validate-links:
+    name: Validate links
+    needs: commit
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+      - name: Setup
+        uses: ./.github/actions/setup
+      - name: Validate cross-site links
+        run: npm run validate-links

codegen/validate-links.ts

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+  apiReferenceRoot,
+  apiReferenceUrlPrefix,
+  baseUrl,
+  guidesRoot,
+  siteUrlPrefix,
+} from './lib/config.js'
+
+// Maps published URL prefixes to their site section root on disk.
+const siteSections: Array<{ urlPrefix: string; root: string }> = [
+  { urlPrefix: apiReferenceUrlPrefix, root: apiReferenceRoot },
+  { urlPrefix: '', root: guidesRoot },
+]
+
+const urlPattern = new RegExp(
+  `${baseUrl.replaceAll('.', '\\.')}[^)\\s]+`,
+  'g',
+)
+
+interface BrokenLink {
+  file: string
+  line: number
+  url: string
+  reason: string
+}
+
+const brokenLinks: BrokenLink[] = []
+
+function walkDir(dir: string): string[] {
+  const files: string[] = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      files.push(...walkDir(fullPath))
+    } else if (entry.name.endsWith('.md')) {
+      files.push(fullPath)
+    }
+  }
+  return files
+}
+
+const files = walkDir('docs')
+
+for (const file of files) {
+  const contents = readFileSync(file, 'utf-8')
+  const lines = contents.split('\n')
+
+  for (let i = 0; i < lines.length; i++) {
+    const matches = lines[i]?.matchAll(urlPattern)
+    if (matches == null) continue
+
+    for (const match of matches) {
+      const rawUrl = match[0].replace(/[).,]*$/, '')
+      // Strip GitBook markdown escapes (e.g., \_ used to prevent italic rendering)
+      const cleanUrl = rawUrl.replaceAll('\\', '')
+      const url = new URL(cleanUrl)
+      url.pathname = url.pathname.replace(siteUrlPrefix, '')
+
+      // Strip hash anchors for file resolution
+      const pathname = url.pathname
+
+      const section = siteSections.find(({ urlPrefix }) =>
+        urlPrefix === ''
+          ? true
+          : pathname.startsWith(urlPrefix + '/') || pathname === urlPrefix,
+      )
+
+      if (section == null) {
+        brokenLinks.push({
+          file,
+          line: i + 1,
+          url: rawUrl,
+          reason: 'No matching site section',
+        })
+        continue
+      }
+
+      const pagePath = pathname.replace(section.urlPrefix, '')
+      const targetRoot = join(section.root, pagePath)
+
+      const targetMd = `${targetRoot}.md`
+      const targetReadme = join(targetRoot, 'README.md')
+
+      if (!existsSync(targetMd) && !existsSync(targetReadme)) {
+        brokenLinks.push({
+          file,
+          line: i + 1,
+          url: rawUrl,
+          reason: `File not found: ${targetMd} or ${targetReadme}`,
+        })
+      }
+    }
+  }
+}
+
+if (brokenLinks.length > 0) {
+  // eslint-disable-next-line no-console
+  console.error(`Found ${brokenLinks.length} broken cross-site link(s):\n`)
+  for (const { file, line, url, reason } of brokenLinks) {
+    // eslint-disable-next-line no-console
+    console.error(`  ${file}:${line}\n    ${url}\n    ${reason}\n`)
+  }
+  process.exit(1)
+} else {
+  // eslint-disable-next-line no-console
+  console.log('All cross-site links are valid.')
+}

docs/api-reference/README.md

@@ -1,3 +1,6 @@
+---
+description: Comprehensive reference for integrating with Seam API endpoints
+---
 
 # Overview
 
@@ -29,4 +32,3 @@ See the following reference topics:
 * [Events](events/)
 * [Action Attempts](action_attempts/)
 * [Connected Accounts](connected_accounts/)
-

package.json

@@ -16,6 +16,7 @@
   "scripts": {
     "generate": "tsx codegen/smith.ts",
     "postgenerate": "npm run format",
+    "validate-links": "tsx codegen/validate-links.ts",
     "typecheck": "tsc",
     "lint": "eslint .",
     "postlint": "prettier --check --ignore-path .prettierignore .",