Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import { glob, readFile, stat } from 'node:fs/promises'; |
| 2 | import { dirname, relative, resolve, sep } from 'node:path'; |
| 3 | import { fileURLToPath } from 'node:url'; |
| 4 | import { |
| 5 | type FileObject, |
| 6 | type ValidateError, |
| 7 | type ValidateResult, |
| 8 | printErrors, |
| 9 | validateFiles, |
| 10 | } from 'next-validate-link'; |
| 11 | import GithubSlugger from 'github-slugger'; |
| 12 | import { toString } from 'mdast-util-to-string'; |
| 13 | import { remark } from 'remark'; |
| 14 | import { visit } from 'unist-util-visit'; |
| 15 | |
| 16 | const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..'); |
| 17 | const sdkDocsRoot = resolve(repositoryRoot, 'ts/docs'); |
| 18 | |
| 19 | interface MarkdownMetadata { |
| 20 | hashes: string[]; |
| 21 | links: Array<{ href: string; line: number; column: number }>; |
| 22 | fragmentLinks: Array<{ href: string; line: number; column: number }>; |
| 23 | } |
| 24 | |
| 25 | function inspectMarkdown(content: string): MarkdownMetadata { |
| 26 | const slugger = new GithubSlugger(); |
| 27 | const tree = remark().parse(content); |
| 28 | const metadata: MarkdownMetadata = { hashes: [], links: [], fragmentLinks: [] }; |
| 29 | |
| 30 | visit(tree, node => { |
| 31 | if (node.type === 'heading') metadata.hashes.push(slugger.slug(toString(node))); |
| 32 | if (node.type !== 'link' && node.type !== 'image') return; |
| 33 | |
| 34 | const link = { |
| 35 | href: node.url, |
| 36 | line: node.position?.start.line ?? 1, |
| 37 | column: node.position?.start.column ?? 1, |
| 38 | }; |
| 39 | metadata.links.push(link); |
| 40 | if (node.type !== 'link' || !node.url.startsWith('#')) return; |
| 41 | |
| 42 | metadata.fragmentLinks.push(link); |
| 43 | }); |
| 44 | |
| 45 | return metadata; |
| 46 | } |
| 47 | |
| 48 | async function getLinkedMarkdownTargets(files: FileObject[]): Promise<FileObject[]> { |
| 49 | const knownPaths = new Set(files.map(file => resolve(file.path))); |
| 50 | const targets = new Map<string, FileObject>(); |
| 51 | |
| 52 | for (const file of files) { |
| 53 | for (const link of inspectMarkdown(file.content).links) { |
| 54 | const pathname = link.href.match(/^[^?#]*/)?.[0] ?? ''; |
| 55 | if ( |
| 56 | !pathname.endsWith('.md') || |
| 57 | pathname.startsWith('/') || |
| 58 | /^[a-z][a-z\d+.-]*:/i.test(pathname) |
| 59 | ) { |
| 60 | continue; |
| 61 | } |
| 62 | |
| 63 | let decodedPath: string; |
| 64 | try { |
| 65 | decodedPath = decodeURIComponent(pathname); |
| 66 | } catch { |
| 67 | continue; |
| 68 | } |
| 69 | |
| 70 | const targetPath = resolve(dirname(file.path), decodedPath); |
| 71 | if (knownPaths.has(targetPath) || targets.has(targetPath)) continue; |
| 72 | |
| 73 | try { |
| 74 | const content = await readFile(targetPath, 'utf-8'); |
| 75 | const relativePath = relative(repositoryRoot, targetPath).split(sep).join('/'); |
| 76 | targets.set(targetPath, { |
| 77 | path: targetPath, |
| 78 | content, |
| 79 | url: `/sdk-docs-target/${relativePath}`, |
| 80 | }); |
| 81 | } catch { |
| 82 | // Missing files are reported by validateFiles with source line numbers. |
| 83 | } |
| 84 | } |
| 85 | } |
| 86 | |
| 87 | return [...targets.values()]; |
| 88 | } |
| 89 | |
| 90 | async function findMissingRelativeFiles( |
| 91 | files: FileObject[], |
| 92 | metadataByPath: Map<string, MarkdownMetadata> |
| 93 | ): Promise<ValidateResult[]> { |
| 94 | const results: ValidateResult[] = []; |
| 95 | |
| 96 | for (const file of files) { |
| 97 | const errors: ValidateError[] = []; |
| 98 | for (const link of metadataByPath.get(resolve(file.path))?.links ?? []) { |
| 99 | const pathname = link.href.match(/^[^?#]*/)?.[0] ?? ''; |
| 100 | if (!pathname || pathname.startsWith('/') || /^[a-z][a-z\d+.-]*:/i.test(pathname)) continue; |
| 101 | |
| 102 | let decodedPath: string; |
| 103 | try { |
| 104 | decodedPath = decodeURIComponent(pathname); |
| 105 | } catch { |
| 106 | decodedPath = pathname; |
| 107 | } |
| 108 | |
| 109 | try { |
| 110 | await stat(resolve(dirname(file.path), decodedPath)); |
| 111 | } catch { |
| 112 | errors.push({ |
| 113 | url: link.href, |
| 114 | line: link.line, |
| 115 | column: link.column, |
| 116 | reason: 'not-found', |
| 117 | }); |
| 118 | } |
| 119 | } |
| 120 | |
| 121 | if (errors.length > 0) { |
| 122 | results.push({ |
| 123 | file: file.path, |
| 124 | errors, |
| 125 | detected: errors.map(error => [error.url, error.line, error.column, error.reason]), |
| 126 | }); |
| 127 | } |
| 128 | } |
| 129 | |
| 130 | return results; |
| 131 | } |
| 132 | |
| 133 | function findInvalidPageFragments( |
| 134 | files: FileObject[], |
| 135 | metadataByPath: Map<string, MarkdownMetadata> |
| 136 | ): ValidateResult[] { |
| 137 | const results: ValidateResult[] = []; |
| 138 | |
| 139 | for (const file of files) { |
| 140 | const metadata = metadataByPath.get(resolve(file.path)); |
| 141 | const hashes = new Set(metadata?.hashes ?? []); |
| 142 | const errors: ValidateError[] = []; |
| 143 | |
| 144 | for (const link of metadata?.fragmentLinks ?? []) { |
| 145 | let hash: string; |
| 146 | try { |
| 147 | hash = decodeURIComponent(link.href.slice(1)); |
| 148 | } catch { |
| 149 | hash = link.href.slice(1); |
| 150 | } |
| 151 | if (hashes.has(hash)) continue; |
| 152 | |
| 153 | errors.push({ |
| 154 | url: link.href, |
| 155 | line: link.line, |
| 156 | column: link.column, |
| 157 | reason: 'invalid-fragment', |
| 158 | }); |
| 159 | } |
| 160 | |
| 161 | if (errors.length > 0) { |
| 162 | results.push({ |
| 163 | file: file.path, |
| 164 | errors, |
| 165 | detected: errors.map(error => [error.url, error.line, error.column, error.reason]), |
| 166 | }); |
| 167 | } |
| 168 | } |
| 169 | |
| 170 | return results; |
| 171 | } |
| 172 | |
| 173 | export async function validateSdkMarkdownLinks(files: FileObject[]): Promise<ValidateResult[]> { |
| 174 | const linkedTargets = await getLinkedMarkdownTargets(files); |
| 175 | const allFiles = [...files, ...linkedTargets]; |
| 176 | const urlsByPath = new Map<string, string>(); |
| 177 | const urls = new Map<string, { hashes: string[] }>(); |
| 178 | const metadataByPath = new Map<string, MarkdownMetadata>(); |
| 179 | |
| 180 | for (const file of allFiles) { |
| 181 | const filePath = resolve(file.path); |
| 182 | if (!file.url) throw new Error(`Missing URL for SDK documentation file: ${file.path}`); |
| 183 | const metadata = inspectMarkdown(file.content); |
| 184 | urlsByPath.set(filePath, file.url); |
| 185 | urls.set(file.url, { hashes: metadata.hashes }); |
| 186 | metadataByPath.set(filePath, metadata); |
| 187 | } |
| 188 | |
| 189 | const scanned = { urls, fallbackUrls: [] }; |
| 190 | const pathToUrl = (filePath: string) => { |
| 191 | let decodedPath = filePath; |
| 192 | try { |
| 193 | decodedPath = decodeURIComponent(filePath); |
| 194 | } catch { |
| 195 | // Keep malformed encodings as-is; the path check will report them. |
| 196 | } |
| 197 | return urlsByPath.get(resolve(decodedPath)); |
| 198 | }; |
| 199 | const determinatePathname = (pathname: string) => |
| 200 | pathname.startsWith('/') || /^[a-z][a-z\d+.-]*:/i.test(pathname) ? 'url' : 'relative-file-path'; |
| 201 | const [missingFiles, invalidAnchors] = await Promise.all([ |
| 202 | findMissingRelativeFiles(files, metadataByPath), |
| 203 | validateFiles(files, { |
| 204 | scanned, |
| 205 | pathToUrl, |
| 206 | checkRelativePaths: 'as-url', |
| 207 | checkRelativeUrls: false, |
| 208 | determinatePathname, |
| 209 | }), |
| 210 | ]); |
| 211 | |
| 212 | const resultsByFile = new Map<string, ValidateResult>(); |
| 213 | const results = [ |
| 214 | ...missingFiles, |
| 215 | ...invalidAnchors, |
| 216 | ...findInvalidPageFragments(files, metadataByPath), |
| 217 | ]; |
| 218 | for (const result of results) { |
| 219 | const existing = resultsByFile.get(result.file); |
| 220 | if (existing) existing.errors.push(...result.errors); |
| 221 | else resultsByFile.set(result.file, result); |
| 222 | } |
| 223 | |
| 224 | return [...resultsByFile.values()]; |
| 225 | } |
| 226 | |
| 227 | async function checkSdkDocLinks() { |
| 228 | const paths = await Array.fromAsync(glob('**/*.md', { cwd: sdkDocsRoot })); |
| 229 | const files: FileObject[] = await Promise.all( |
| 230 | paths.map(async path => { |
| 231 | const filePath = resolve(sdkDocsRoot, path); |
| 232 | const content = await readFile(filePath, 'utf-8'); |
| 233 | const relativePath = relative(sdkDocsRoot, filePath).split(sep).join('/'); |
| 234 | |
| 235 | return { |
| 236 | path: filePath, |
| 237 | content, |
| 238 | url: `/sdk-docs/${relativePath}`, |
| 239 | }; |
| 240 | }) |
| 241 | ); |
| 242 | |
| 243 | printErrors(await validateSdkMarkdownLinks(files), true); |
| 244 | } |
| 245 | |
| 246 | if (import.meta.main) void checkSdkDocLinks(); |