Extend link and path validators to check HTML links and SUMMARY nesting

- Add HTML <a href> link checking to validate-links (both relative and
  absolute docs.seam.co URLs)
- Stop absolute URL pattern at quote characters for HTML compatibility
- Extend validate-paths to check that nested SUMMARY.md entries have
  file paths under their parent's directory, matching how GitBook builds
  published URLs from the tree structure

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

Author: louis-pre

codegen/validate-links.ts

@@ -13,7 +13,7 @@ function findSiteSection(filePath: string): SiteSection | undefined {
 }
 
 const absoluteUrlPattern = new RegExp(
-  `${baseUrl.replaceAll('.', '\\.')}[^)\\s]+`,
+  `${baseUrl.replaceAll('.', '\\.')}[^)"\\s]+`,
   'g',
 )
 
@@ -23,6 +23,15 @@ const absoluteUrlPattern = new RegExp(
 const relativeLinkPattern =
   /(?<!!)\]\((?!https?:\/\/|mailto:|#|{%|<|cursor:|file:)((?:[^)\\]|\\.)+)\)/g
 
+// Matches HTML links like <a href="path"> but not external URLs or anchors.
+const htmlRelativeLinkPattern = /<a\s+href="(?!https?:\/\/|mailto:|#)([^"]+)"/g
+
+// Matches HTML links with absolute docs.seam.co URLs.
+const htmlAbsoluteUrlPattern = new RegExp(
+  `<a\\s+href="(${baseUrl.replaceAll('.', '\\.')}[^"]+)"`,
+  'g',
+)
+
 interface BrokenLink {
   file: string
   line: number
@@ -160,6 +169,20 @@ for (const file of files) {
       if (rawLink == null) continue
       checkRelativeLink(file, i + 1, rawLink)
     }
+
+    // Check HTML href links (relative)
+    for (const match of lineText.matchAll(htmlRelativeLinkPattern)) {
+      const rawLink = match[1]
+      if (rawLink == null) continue
+      checkRelativeLink(file, i + 1, rawLink)
+    }
+
+    // Check HTML href links (absolute docs.seam.co URLs)
+    for (const match of lineText.matchAll(htmlAbsoluteUrlPattern)) {
+      const rawUrl = match[1]
+      if (rawUrl == null) continue
+      checkAbsoluteUrl(file, i + 1, rawUrl)
+    }
   }
 }
 

codegen/validate-paths.ts

@@ -18,6 +18,16 @@ function slugify(heading: string): string {
     .trim()
 }
 
+function slugFromPath(linkPath: string): string {
+  return linkPath
+    .replace(/README\.md$/, '')
+    .replace(/\.md$/, '')
+    .replace(/\/$/, '')
+    .split('/')
+    .filter(Boolean)
+    .pop() ?? ''
+}
+
 interface PathMismatch {
   section: string
   line: number
@@ -37,6 +47,11 @@ for (const section of siteSections) {
 
   let currentGroup: string | null = null
 
+  // Track nesting: each entry is { level, slug, path }
+  // GitBook builds URLs by joining ancestor slugs, so child file paths
+  // should be under their parent's directory.
+  const parentStack: Array<{ level: number; slug: string; path: string }> = []
+
   for (let i = 0; i < lines.length; i++) {
     const lineText = lines[i]
     if (lineText == null) continue
@@ -48,7 +63,14 @@ for (const section of siteSections) {
       continue
     }
 
-    for (const match of lineText.matchAll(summaryLinkPattern)) {
+    // Only process list items
+    const stripped = lineText.trimStart()
+    if (!stripped.startsWith('* [')) continue
+
+    const indent = lineText.length - stripped.length
+    const level = Math.floor(indent / 2)
+
+    for (const match of stripped.matchAll(summaryLinkPattern)) {
       const title = match[1] ?? ''
       const linkPath = match[2] ?? ''
 
@@ -79,6 +101,49 @@ for (const section of siteSections) {
           reason: `Path should start with "${currentGroup}/" (listed under "## ${currentGroup}")`,
         })
       }
+
+      // Check 3: nested items should have paths under their parent's directory.
+      // GitBook builds published URLs from the SUMMARY.md tree, so a child
+      // nested under a parent gets a URL like /parent-slug/child-slug.
+      // The file path must match this structure.
+      // Trim stack to current level
+      while (parentStack.length > 0) {
+        const top = parentStack[parentStack.length - 1]
+        if (top != null && top.level >= level) parentStack.pop()
+        else break
+      }
+
+      const slug = slugFromPath(linkPath)
+      const parent =
+        parentStack.length > 0
+          ? parentStack[parentStack.length - 1]
+          : undefined
+
+      if (parent != null) {
+        // The parent's path determines the expected directory prefix.
+        // e.g., parent path "access_codes/simulate/README.md" means
+        // children should start with "access_codes/simulate/".
+        const parentDir = parent.path
+          .replace(/README\.md$/, '')
+          .replace(/\.md$/, '/')
+        if (!linkPath.startsWith(parentDir)) {
+          const publishedUrl =
+            section.urlPrefix +
+            '/' +
+            [...parentStack.map((p) => p.slug), slug].join('/')
+          mismatches.push({
+            section: section.name,
+            line: i + 1,
+            title,
+            path: linkPath,
+            reason: `Path should start with "${parentDir}" to match published URL ${publishedUrl}`,
+          })
+        }
+      }
+
+      if (slug !== '') {
+        parentStack.push({ level, slug, path: linkPath })
+      }
     }
   }
 }