Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 246 lines 7.22 KB
Raw
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();