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();