@jfdevelops/docs 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +87 -2
- package/dist/check.d.ts +69 -0
- package/dist/check.js +588 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +84 -0
- package/dist/config.d.ts +17 -0
- package/dist/config.js +51 -0
- package/dist/generate.d.ts +7 -0
- package/dist/generate.js +102 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +4 -0
- package/dist/manifest.d.ts +112 -0
- package/dist/manifest.js +214 -0
- package/package.json +47 -3
package/dist/check.js
ADDED
|
@@ -0,0 +1,588 @@
|
|
|
1
|
+
import { existsSync, readFileSync, readdirSync, realpathSync, statSync, } from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { loadConfig } from './config.js';
|
|
4
|
+
import { buildDocsNavigation, listVersions, parseFrontmatter, } from './manifest.js';
|
|
5
|
+
export { parseFrontmatter };
|
|
6
|
+
/**
|
|
7
|
+
* Validates every public page against the docs content contract. docs.json
|
|
8
|
+
* and meta.json are generated
|
|
9
|
+
* from the same tree, so the checker builds them in memory instead of reading
|
|
10
|
+
* them. It uses Node builtins only.
|
|
11
|
+
*/
|
|
12
|
+
export const FENCE_LANGUAGES = [
|
|
13
|
+
'ts',
|
|
14
|
+
'tsx',
|
|
15
|
+
'js',
|
|
16
|
+
'jsx',
|
|
17
|
+
'json',
|
|
18
|
+
'sh',
|
|
19
|
+
'bash',
|
|
20
|
+
'text',
|
|
21
|
+
'css',
|
|
22
|
+
'diff',
|
|
23
|
+
'yaml',
|
|
24
|
+
];
|
|
25
|
+
export const IMAGE_EXTENSIONS = [
|
|
26
|
+
'.png',
|
|
27
|
+
'.jpg',
|
|
28
|
+
'.jpeg',
|
|
29
|
+
'.gif',
|
|
30
|
+
'.svg',
|
|
31
|
+
'.webp',
|
|
32
|
+
'.avif',
|
|
33
|
+
];
|
|
34
|
+
export const FRONTMATTER_KEYS = ['title', 'description', 'order'];
|
|
35
|
+
// Install commands whose package versions are checked.
|
|
36
|
+
const INSTALL_COMMAND = /^\s*(pnpm add|npm (install|i)|yarn add|bun add)\s/;
|
|
37
|
+
const EXCLUDED = ['maintainers'];
|
|
38
|
+
const GENERATED_FILES = ['docs.json', 'meta.json'];
|
|
39
|
+
const SEGMENT = /^[a-z0-9]+(-[a-z0-9]+)*$/;
|
|
40
|
+
const MAX_SEGMENTS = 3;
|
|
41
|
+
function issue(errors, code, file, message) {
|
|
42
|
+
errors.push({
|
|
43
|
+
code,
|
|
44
|
+
file,
|
|
45
|
+
message,
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
function escapeRegExp(text) {
|
|
49
|
+
return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
50
|
+
}
|
|
51
|
+
function toPosix(value) {
|
|
52
|
+
return value.split(path.sep).join('/');
|
|
53
|
+
}
|
|
54
|
+
function isInside(parent, child) {
|
|
55
|
+
const relative = path.relative(parent, child);
|
|
56
|
+
return (relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative));
|
|
57
|
+
}
|
|
58
|
+
/** GitHub-style heading slug without the duplicate suffix. */
|
|
59
|
+
export function slugifyHeading(text) {
|
|
60
|
+
return text
|
|
61
|
+
.toLowerCase()
|
|
62
|
+
.replace(/[^\p{L}\p{N}\s_-]/gu, '')
|
|
63
|
+
.trim()
|
|
64
|
+
.replace(/\s/g, '-');
|
|
65
|
+
}
|
|
66
|
+
function plainHeading(text) {
|
|
67
|
+
return text
|
|
68
|
+
.replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
|
|
69
|
+
.replace(/`([^`]*)`/g, '$1')
|
|
70
|
+
.replace(/[*_]{1,3}([^*_]+)[*_]{1,3}/g, '$1')
|
|
71
|
+
.trim();
|
|
72
|
+
}
|
|
73
|
+
function stripInlineCode(line) {
|
|
74
|
+
return line.replace(/`[^`]*`/g, (match) => ' '.repeat(match.length));
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Walks a Markdown body and returns its headings, links, images, code fences
|
|
78
|
+
* and any construct the contract rejects.
|
|
79
|
+
*/
|
|
80
|
+
export function scanMarkdown(body) {
|
|
81
|
+
const result = {
|
|
82
|
+
headings: [],
|
|
83
|
+
links: [],
|
|
84
|
+
fences: [],
|
|
85
|
+
problems: [],
|
|
86
|
+
};
|
|
87
|
+
const seen = new Map();
|
|
88
|
+
const lines = body.split('\n');
|
|
89
|
+
let fence = null;
|
|
90
|
+
for (const [index, rawLine] of lines.entries()) {
|
|
91
|
+
const lineNumber = index + 1;
|
|
92
|
+
const fenceMatch = /^\s*(`{3,}|~{3,})\s*(.*)$/.exec(rawLine);
|
|
93
|
+
if (fence) {
|
|
94
|
+
const marker = fenceMatch?.[1] ?? '';
|
|
95
|
+
if (fenceMatch && marker[0] === fence.marker[0] && marker.length >= fence.marker.length && fenceMatch[2] === '') {
|
|
96
|
+
result.fences.push({
|
|
97
|
+
...fence,
|
|
98
|
+
content: fence.lines.join('\n'),
|
|
99
|
+
});
|
|
100
|
+
fence = null;
|
|
101
|
+
}
|
|
102
|
+
else {
|
|
103
|
+
fence.lines.push(rawLine);
|
|
104
|
+
}
|
|
105
|
+
continue;
|
|
106
|
+
}
|
|
107
|
+
if (fenceMatch) {
|
|
108
|
+
const info = (fenceMatch[2] ?? '').trim();
|
|
109
|
+
const [language = '', ...rest] = info.split(/\s+/).filter(Boolean);
|
|
110
|
+
fence = {
|
|
111
|
+
marker: fenceMatch[1] ?? '',
|
|
112
|
+
language,
|
|
113
|
+
info,
|
|
114
|
+
example: rest
|
|
115
|
+
.map((part) => /^example=(.+)$/.exec(part)?.[1])
|
|
116
|
+
.find((value) => value !== undefined),
|
|
117
|
+
line: lineNumber,
|
|
118
|
+
lines: [],
|
|
119
|
+
};
|
|
120
|
+
continue;
|
|
121
|
+
}
|
|
122
|
+
const heading = /^(#{1,6})\s+(.*?)\s*#*\s*$/.exec(rawLine);
|
|
123
|
+
if (heading) {
|
|
124
|
+
const text = plainHeading(heading[2] ?? '');
|
|
125
|
+
const base = slugifyHeading(text);
|
|
126
|
+
const count = seen.get(base) ?? 0;
|
|
127
|
+
seen.set(base, count + 1);
|
|
128
|
+
result.headings.push({
|
|
129
|
+
level: (heading[1] ?? '').length,
|
|
130
|
+
text,
|
|
131
|
+
slug: count === 0 ? base : `${base}-${count}`,
|
|
132
|
+
line: lineNumber,
|
|
133
|
+
});
|
|
134
|
+
}
|
|
135
|
+
const line = stripInlineCode(rawLine);
|
|
136
|
+
if (/<\/?[A-Za-z][^>\n]*>|<!--/.test(line)) {
|
|
137
|
+
result.problems.push({
|
|
138
|
+
code: 'page-html',
|
|
139
|
+
line: lineNumber,
|
|
140
|
+
message: 'Raw HTML, HTML comments and angle-bracket autolinks are not supported.',
|
|
141
|
+
});
|
|
142
|
+
}
|
|
143
|
+
if (/^\s*\[[^\]]+\]:\s+\S+/.test(line)) {
|
|
144
|
+
result.problems.push({
|
|
145
|
+
code: 'link-reference-style',
|
|
146
|
+
line: lineNumber,
|
|
147
|
+
message: 'Reference-style links are not supported. Use inline links.',
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
for (const match of line.matchAll(/(!?)\[([^\]]*)\]\(([^)\s]*)(?:\s+"[^"]*")?\)/g)) {
|
|
151
|
+
result.links.push({
|
|
152
|
+
image: match[1] === '!',
|
|
153
|
+
text: match[2] ?? '',
|
|
154
|
+
target: match[3] ?? '',
|
|
155
|
+
line: lineNumber,
|
|
156
|
+
});
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
if (fence) {
|
|
160
|
+
result.problems.push({
|
|
161
|
+
code: 'code-fence-unclosed',
|
|
162
|
+
line: fence.line,
|
|
163
|
+
message: 'A code fence is never closed.',
|
|
164
|
+
});
|
|
165
|
+
}
|
|
166
|
+
return result;
|
|
167
|
+
}
|
|
168
|
+
function collectFiles(directory) {
|
|
169
|
+
const entries = readdirSync(directory, {
|
|
170
|
+
withFileTypes: true,
|
|
171
|
+
});
|
|
172
|
+
return entries.flatMap((entry) => {
|
|
173
|
+
const full = path.join(directory, entry.name);
|
|
174
|
+
return entry.isDirectory() ? collectFiles(full) : [full];
|
|
175
|
+
});
|
|
176
|
+
}
|
|
177
|
+
function loadPages(version, errors) {
|
|
178
|
+
const versionDir = version.full;
|
|
179
|
+
const pages = new Map();
|
|
180
|
+
const assets = new Set();
|
|
181
|
+
if (!existsSync(versionDir) || !statSync(versionDir).isDirectory()) {
|
|
182
|
+
issue(errors, 'version-directory', `docs/${version.path}`, `The directory for ${version.id} does not exist.`);
|
|
183
|
+
return {
|
|
184
|
+
versionDir,
|
|
185
|
+
pages,
|
|
186
|
+
assets,
|
|
187
|
+
};
|
|
188
|
+
}
|
|
189
|
+
for (const full of collectFiles(versionDir)) {
|
|
190
|
+
const relative = toPosix(path.relative(versionDir, full));
|
|
191
|
+
const display = `docs/${version.path}/${relative}`;
|
|
192
|
+
if (path.basename(full) === 'meta.json' ||
|
|
193
|
+
(version.generatedReference && isInside(version.generatedReference, full))) {
|
|
194
|
+
continue;
|
|
195
|
+
}
|
|
196
|
+
if (relative.startsWith('assets/')) {
|
|
197
|
+
if (IMAGE_EXTENSIONS.includes(path.extname(relative).toLowerCase())) {
|
|
198
|
+
assets.add(relative);
|
|
199
|
+
}
|
|
200
|
+
else {
|
|
201
|
+
issue(errors, 'unsupported-file', display, `Assets must be images (${IMAGE_EXTENSIONS.join(', ')}).`);
|
|
202
|
+
}
|
|
203
|
+
continue;
|
|
204
|
+
}
|
|
205
|
+
if (!relative.endsWith('.md')) {
|
|
206
|
+
issue(errors, 'unsupported-file', display, 'Only .md pages and images under assets/ are allowed in a version directory.');
|
|
207
|
+
continue;
|
|
208
|
+
}
|
|
209
|
+
const id = relative.slice(0, -3);
|
|
210
|
+
const segments = id.split('/');
|
|
211
|
+
if (segments.length > MAX_SEGMENTS ||
|
|
212
|
+
segments.some((segment) => !SEGMENT.test(segment))) {
|
|
213
|
+
issue(errors, 'page-slug', display, `Page id "${id}" must be lowercase kebab-case with at most ${MAX_SEGMENTS} segments.`);
|
|
214
|
+
}
|
|
215
|
+
pages.set(id, {
|
|
216
|
+
id,
|
|
217
|
+
file: display,
|
|
218
|
+
full,
|
|
219
|
+
});
|
|
220
|
+
}
|
|
221
|
+
return {
|
|
222
|
+
versionDir,
|
|
223
|
+
pages,
|
|
224
|
+
assets,
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* The current version follows the latest release, so its installs may be
|
|
229
|
+
* unpinned. Older versions pin every package so a reader gets that major.
|
|
230
|
+
*/
|
|
231
|
+
function checkInstall(specifier, version, where, errors) {
|
|
232
|
+
const pinned = /@\d+\.\d+\.\d+$/.test(specifier);
|
|
233
|
+
const unpinned = !/^(@[^/]+\/)?[^@]+@/.test(specifier);
|
|
234
|
+
const core = version.package.name;
|
|
235
|
+
if (!pinned && !(unpinned && version.status === 'current')) {
|
|
236
|
+
issue(errors, 'install-version', where, `Pin ${specifier} to the audited package version so this guide does not install a different major.`);
|
|
237
|
+
}
|
|
238
|
+
const sameRelease = version.status === 'current'
|
|
239
|
+
? specifier.startsWith(`${core}@${version.major}.`)
|
|
240
|
+
: specifier === `${core}@${version.package.endpointVersion}`;
|
|
241
|
+
if (pinned && specifier.startsWith(`${core}@`) && !sameRelease) {
|
|
242
|
+
issue(errors, 'install-version', where, version.status === 'current'
|
|
243
|
+
? `Install a ${version.major}.x release of ${core} for this documentation.`
|
|
244
|
+
: `Install ${core}@${version.package.endpointVersion} for this documentation snapshot.`);
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
function validatePage(page, version, context, errors) {
|
|
248
|
+
const text = readFileSync(page.full, 'utf8');
|
|
249
|
+
const parsed = parseFrontmatter(text);
|
|
250
|
+
if (parsed.data === null) {
|
|
251
|
+
issue(errors, 'page-frontmatter', page.file, parsed.error);
|
|
252
|
+
return null;
|
|
253
|
+
}
|
|
254
|
+
const { data } = parsed;
|
|
255
|
+
for (const key of Object.keys(data)) {
|
|
256
|
+
if (!FRONTMATTER_KEYS.includes(key)) {
|
|
257
|
+
issue(errors, 'page-frontmatter', page.file, `Unknown frontmatter key "${key}". Allowed: ${FRONTMATTER_KEYS.join(', ')}.`);
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
const title = data['title'] ?? '';
|
|
261
|
+
const description = data['description'] ?? '';
|
|
262
|
+
if (title === '' || title.length > 80) {
|
|
263
|
+
issue(errors, 'page-frontmatter', page.file, 'title is required and at most 80 characters.');
|
|
264
|
+
}
|
|
265
|
+
if (description === '' || description.length > 220) {
|
|
266
|
+
issue(errors, 'page-frontmatter', page.file, 'description is required and at most 220 characters.');
|
|
267
|
+
}
|
|
268
|
+
if (!/^\d+$/.test(data['order'] ?? '')) {
|
|
269
|
+
issue(errors, 'page-frontmatter', page.file, 'order is required and must be an integer.');
|
|
270
|
+
}
|
|
271
|
+
const versionWord = new RegExp(`(^|[^\\w.])(v\\d+|${escapeRegExp(context.library)} \\d+)(?![\\w.])`, 'i');
|
|
272
|
+
if (!page.id.endsWith('migration') &&
|
|
273
|
+
versionWord.test(`${title} ${description}`)) {
|
|
274
|
+
issue(errors, 'title-version', page.file, "Titles and descriptions must not name the page's own version. The URL already says it.");
|
|
275
|
+
}
|
|
276
|
+
const scan = scanMarkdown(parsed.body);
|
|
277
|
+
for (const problem of scan.problems) {
|
|
278
|
+
issue(errors, problem.code, `${page.file}:${problem.line}`, problem.message);
|
|
279
|
+
}
|
|
280
|
+
let lastLevel = 1;
|
|
281
|
+
for (const heading of scan.headings) {
|
|
282
|
+
if (heading.level === 1) {
|
|
283
|
+
issue(errors, 'page-h1', `${page.file}:${heading.line}`, 'The body must not contain a "#" heading. The title comes from frontmatter.');
|
|
284
|
+
}
|
|
285
|
+
else if (heading.level > lastLevel + 1) {
|
|
286
|
+
issue(errors, 'heading-level', `${page.file}:${heading.line}`, `Heading "${heading.text}" skips from level ${lastLevel} to ${heading.level}.`);
|
|
287
|
+
}
|
|
288
|
+
lastLevel = Math.max(heading.level, 2);
|
|
289
|
+
}
|
|
290
|
+
for (const fence of scan.fences) {
|
|
291
|
+
const where = `${page.file}:${fence.line}`;
|
|
292
|
+
if (fence.language === 'sh' || fence.language === 'bash') {
|
|
293
|
+
for (const line of fence.content.split('\n')) {
|
|
294
|
+
if (!INSTALL_COMMAND.test(line)) {
|
|
295
|
+
continue;
|
|
296
|
+
}
|
|
297
|
+
const packages = line
|
|
298
|
+
.split(/\s+/)
|
|
299
|
+
.filter((word) => isFamilyPackage(word, context.family));
|
|
300
|
+
for (const specifier of packages) {
|
|
301
|
+
checkInstall(specifier, version, where, errors);
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
if (!FENCE_LANGUAGES.includes(fence.language)) {
|
|
306
|
+
issue(errors, 'code-fence-language', where, `A code fence needs a language from: ${FENCE_LANGUAGES.join(', ')}. Found "${fence.language}".`);
|
|
307
|
+
}
|
|
308
|
+
if (fence.example) {
|
|
309
|
+
checkExample({ ...fence, example: fence.example }, where, context, errors);
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
return {
|
|
313
|
+
order: Number(data['order']),
|
|
314
|
+
scan,
|
|
315
|
+
};
|
|
316
|
+
}
|
|
317
|
+
function checkExample(fence, where, context, errors) {
|
|
318
|
+
const requested = fence.example;
|
|
319
|
+
if (!context.examplesDir) {
|
|
320
|
+
issue(errors, 'example-path', where, `example="${requested}" needs an examples directory. Set the docs addon's "examples" option.`);
|
|
321
|
+
return;
|
|
322
|
+
}
|
|
323
|
+
const root = path.join(context.root, context.examplesDir);
|
|
324
|
+
const resolved = path.resolve(root, requested);
|
|
325
|
+
if (requested.includes('..') ||
|
|
326
|
+
path.isAbsolute(requested) ||
|
|
327
|
+
!isInside(root, resolved)) {
|
|
328
|
+
issue(errors, 'example-path', where, `example="${requested}" must stay inside ${context.examplesDir}.`);
|
|
329
|
+
return;
|
|
330
|
+
}
|
|
331
|
+
if (!existsSync(resolved)) {
|
|
332
|
+
issue(errors, 'example-missing', where, `The example fixture ${context.examplesDir}/${requested} does not exist.`);
|
|
333
|
+
return;
|
|
334
|
+
}
|
|
335
|
+
const expected = readFileSync(resolved, 'utf8')
|
|
336
|
+
.replace(/\r\n/g, '\n')
|
|
337
|
+
.trimEnd();
|
|
338
|
+
if (fence.content.replace(/\r\n/g, '\n').trimEnd() !== expected) {
|
|
339
|
+
issue(errors, 'example-mismatch', where, `The code block differs from ${context.examplesDir}/${requested}. Update the page to match the type-checked fixture.`);
|
|
340
|
+
}
|
|
341
|
+
}
|
|
342
|
+
function resolveLink(link, page, context, errors, options) {
|
|
343
|
+
const where = `${page.file}:${link.line}`;
|
|
344
|
+
const target = link.target;
|
|
345
|
+
if (target === '') {
|
|
346
|
+
issue(errors, 'link-empty', where, 'A link has an empty target.');
|
|
347
|
+
return null;
|
|
348
|
+
}
|
|
349
|
+
if (/^https:\/\//.test(target)) {
|
|
350
|
+
return null;
|
|
351
|
+
}
|
|
352
|
+
if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('//')) {
|
|
353
|
+
issue(errors, 'link-scheme', where, `Link "${target}" is not allowed. Use https:// or a relative page link.`);
|
|
354
|
+
return null;
|
|
355
|
+
}
|
|
356
|
+
if (target.startsWith('/')) {
|
|
357
|
+
issue(errors, 'link-absolute', where, `Link "${target}" is an absolute path. Use a relative link to a page.`);
|
|
358
|
+
return null;
|
|
359
|
+
}
|
|
360
|
+
const hashIndex = target.indexOf('#');
|
|
361
|
+
const filePart = hashIndex === -1 ? target : target.slice(0, hashIndex);
|
|
362
|
+
const anchor = hashIndex === -1 ? null : decodeURIComponent(target.slice(hashIndex + 1));
|
|
363
|
+
if (filePart === '') {
|
|
364
|
+
return {
|
|
365
|
+
full: page.full,
|
|
366
|
+
anchor,
|
|
367
|
+
where,
|
|
368
|
+
};
|
|
369
|
+
}
|
|
370
|
+
const resolved = path.resolve(path.dirname(page.full), decodeURIComponent(filePart));
|
|
371
|
+
if (!isInside(context.docsRoot, resolved)) {
|
|
372
|
+
issue(errors, 'path-containment', where, `Link "${target}" resolves outside docs/.`);
|
|
373
|
+
return null;
|
|
374
|
+
}
|
|
375
|
+
if (!existsSync(resolved) &&
|
|
376
|
+
context.generatedReferences.some((directory) => resolved === directory || isInside(directory, resolved))) {
|
|
377
|
+
// The API reference is generated and gitignored; it may not exist yet.
|
|
378
|
+
return null;
|
|
379
|
+
}
|
|
380
|
+
if (!existsSync(resolved)) {
|
|
381
|
+
issue(errors, link.image ? 'image-missing' : 'link-missing-file', where, `Link "${target}" does not resolve to a file.`);
|
|
382
|
+
return null;
|
|
383
|
+
}
|
|
384
|
+
if (!isInside(realpathSync(context.docsRoot), realpathSync(resolved))) {
|
|
385
|
+
issue(errors, 'path-containment', where, `Link "${target}" leaves docs/ through a symbolic link.`);
|
|
386
|
+
return null;
|
|
387
|
+
}
|
|
388
|
+
const relative = toPosix(path.relative(context.docsRoot, resolved));
|
|
389
|
+
const top = relative.split('/')[0] ?? '';
|
|
390
|
+
if (!options.allowExcluded && context.excluded.includes(top)) {
|
|
391
|
+
issue(errors, 'link-excluded', where, `Link "${target}" points into the excluded "${top}" directory. Public pages cannot link to maintainer pages.`);
|
|
392
|
+
return null;
|
|
393
|
+
}
|
|
394
|
+
if (link.image) {
|
|
395
|
+
if (!/^framework\/[^/]+\/v\d+\/assets\//.test(relative) ||
|
|
396
|
+
!IMAGE_EXTENSIONS.includes(path.extname(relative).toLowerCase())) {
|
|
397
|
+
issue(errors, 'image-asset-location', where, `Image "${target}" must be an image file under a version's assets/ directory.`);
|
|
398
|
+
return null;
|
|
399
|
+
}
|
|
400
|
+
return null;
|
|
401
|
+
}
|
|
402
|
+
if (!resolved.endsWith('.md')) {
|
|
403
|
+
issue(errors, 'link-not-page', where, `Link "${target}" must point to a .md page.`);
|
|
404
|
+
return null;
|
|
405
|
+
}
|
|
406
|
+
return {
|
|
407
|
+
full: resolved,
|
|
408
|
+
anchor,
|
|
409
|
+
where,
|
|
410
|
+
};
|
|
411
|
+
}
|
|
412
|
+
function headingSlugsFor(full, cache) {
|
|
413
|
+
const cached = cache.get(full);
|
|
414
|
+
if (cached) {
|
|
415
|
+
return cached;
|
|
416
|
+
}
|
|
417
|
+
const parsed = parseFrontmatter(readFileSync(full, 'utf8'));
|
|
418
|
+
const slugs = new Set(scanMarkdown(parsed.body).headings.map((heading) => heading.slug));
|
|
419
|
+
cache.set(full, slugs);
|
|
420
|
+
return slugs;
|
|
421
|
+
}
|
|
422
|
+
function checkLinks(page, scan, context, errors, options = {}) {
|
|
423
|
+
for (const link of scan.links) {
|
|
424
|
+
const resolved = resolveLink(link, page, context, errors, options);
|
|
425
|
+
if (resolved && resolved.anchor) {
|
|
426
|
+
const slugs = headingSlugsFor(resolved.full, context.slugCache);
|
|
427
|
+
if (!slugs.has(resolved.anchor)) {
|
|
428
|
+
issue(errors, 'link-anchor', resolved.where, `Anchor "#${resolved.anchor}" does not exist in ${toPosix(path.relative(context.docsRoot, resolved.full))}.`);
|
|
429
|
+
}
|
|
430
|
+
}
|
|
431
|
+
}
|
|
432
|
+
}
|
|
433
|
+
function checkFile(display, full, context, errors) {
|
|
434
|
+
const scan = scanMarkdown(readFileSync(full, 'utf8'));
|
|
435
|
+
const page = {
|
|
436
|
+
file: display,
|
|
437
|
+
full,
|
|
438
|
+
};
|
|
439
|
+
for (const problem of scan.problems) {
|
|
440
|
+
issue(errors, problem.code, `${display}:${problem.line}`, problem.message);
|
|
441
|
+
}
|
|
442
|
+
checkLinks(page, scan, context, errors, {
|
|
443
|
+
allowExcluded: true,
|
|
444
|
+
});
|
|
445
|
+
return scan;
|
|
446
|
+
}
|
|
447
|
+
/**
|
|
448
|
+
* docs/ holds README.md, framework/, maintainers/ and generated files.
|
|
449
|
+
* framework/<name>/ holds only v<major> directories.
|
|
450
|
+
*/
|
|
451
|
+
function checkLayout(docsRoot, frameworks, context, errors, stats) {
|
|
452
|
+
for (const entry of readdirSync(docsRoot, {
|
|
453
|
+
withFileTypes: true,
|
|
454
|
+
})) {
|
|
455
|
+
const relative = `docs/${entry.name}`;
|
|
456
|
+
if (entry.isDirectory()) {
|
|
457
|
+
if (entry.name !== 'framework' && !EXCLUDED.includes(entry.name)) {
|
|
458
|
+
issue(errors, 'stray-file', relative, `Directory "${entry.name}" is not framework/ or an excluded directory.`);
|
|
459
|
+
}
|
|
460
|
+
continue;
|
|
461
|
+
}
|
|
462
|
+
if (GENERATED_FILES.includes(entry.name)) {
|
|
463
|
+
continue;
|
|
464
|
+
}
|
|
465
|
+
if (entry.name !== 'README.md') {
|
|
466
|
+
issue(errors, 'stray-file', relative, 'Only README.md belongs at the docs root. Pages live under framework/.');
|
|
467
|
+
continue;
|
|
468
|
+
}
|
|
469
|
+
const scan = checkFile(relative, path.join(docsRoot, entry.name), context, errors);
|
|
470
|
+
stats.links += scan.links.length;
|
|
471
|
+
}
|
|
472
|
+
for (const framework of frameworks) {
|
|
473
|
+
for (const entry of readdirSync(framework.full, {
|
|
474
|
+
withFileTypes: true,
|
|
475
|
+
})) {
|
|
476
|
+
if (entry.isFile() && GENERATED_FILES.includes(entry.name)) {
|
|
477
|
+
continue;
|
|
478
|
+
}
|
|
479
|
+
if (!entry.isDirectory() || !/^v\d+$/.test(entry.name)) {
|
|
480
|
+
issue(errors, 'stray-file', `docs/${framework.path}/${entry.name}`, 'A framework directory holds only v<major> version directories.');
|
|
481
|
+
}
|
|
482
|
+
}
|
|
483
|
+
}
|
|
484
|
+
}
|
|
485
|
+
function checkOrders(collection, errors) {
|
|
486
|
+
const seen = new Map();
|
|
487
|
+
for (const page of collection.pages.values()) {
|
|
488
|
+
if (!Number.isInteger(page.order)) {
|
|
489
|
+
continue;
|
|
490
|
+
}
|
|
491
|
+
const key = `${path.posix.dirname(page.id)}:${page.order}`;
|
|
492
|
+
if (seen.has(key)) {
|
|
493
|
+
issue(errors, 'nav-order', page.file, `order ${page.order} is also used by ${seen.get(key)}. Pages in one directory need distinct orders.`);
|
|
494
|
+
}
|
|
495
|
+
else {
|
|
496
|
+
seen.set(key, page.file);
|
|
497
|
+
}
|
|
498
|
+
}
|
|
499
|
+
}
|
|
500
|
+
/**
|
|
501
|
+
* Packages checked in install commands: the documented package and its
|
|
502
|
+
* companions. That is every package in the same npm scope, or, without a
|
|
503
|
+
* scope, every package whose name starts with the documented package's name.
|
|
504
|
+
*/
|
|
505
|
+
function packageFamily(name) {
|
|
506
|
+
return name.startsWith('@') ? `${name.split('/')[0]}/` : name;
|
|
507
|
+
}
|
|
508
|
+
function isFamilyPackage(word, family) {
|
|
509
|
+
const name = word.replace(/(?<=.)@[^@/]*$/, '');
|
|
510
|
+
return family.endsWith('/')
|
|
511
|
+
? name.startsWith(family) && name.length > family.length
|
|
512
|
+
: name === family || name.startsWith(`${family}-`);
|
|
513
|
+
}
|
|
514
|
+
/** Runs every check. `root` is the repository root. */
|
|
515
|
+
export function checkDocs({ root, config = loadConfig(root) }) {
|
|
516
|
+
const examplesDir = config.examples;
|
|
517
|
+
const errors = [];
|
|
518
|
+
const docsRoot = path.join(root, 'docs');
|
|
519
|
+
const stats = {
|
|
520
|
+
versions: 0,
|
|
521
|
+
pages: 0,
|
|
522
|
+
links: 0,
|
|
523
|
+
examples: 0,
|
|
524
|
+
};
|
|
525
|
+
if (!existsSync(path.join(docsRoot, 'framework'))) {
|
|
526
|
+
issue(errors, 'framework-missing', 'docs/framework', 'The docs/framework directory does not exist.');
|
|
527
|
+
return {
|
|
528
|
+
errors,
|
|
529
|
+
stats,
|
|
530
|
+
};
|
|
531
|
+
}
|
|
532
|
+
const { core, frameworks } = listVersions(root, config);
|
|
533
|
+
const { manifest } = buildDocsNavigation({
|
|
534
|
+
root,
|
|
535
|
+
config,
|
|
536
|
+
});
|
|
537
|
+
const context = {
|
|
538
|
+
root,
|
|
539
|
+
docsRoot,
|
|
540
|
+
examplesDir,
|
|
541
|
+
family: packageFamily(core.name),
|
|
542
|
+
library: config.name,
|
|
543
|
+
excluded: EXCLUDED,
|
|
544
|
+
generatedReferences: frameworks
|
|
545
|
+
.flatMap((framework) => framework.versions)
|
|
546
|
+
.map((version) => version.generatedReference)
|
|
547
|
+
.filter((directory) => directory !== null),
|
|
548
|
+
slugCache: new Map(),
|
|
549
|
+
};
|
|
550
|
+
checkLayout(docsRoot, frameworks, context, errors, stats);
|
|
551
|
+
for (const framework of manifest.frameworks) {
|
|
552
|
+
if (!framework.defaultVersion) {
|
|
553
|
+
issue(errors, 'default-version', `docs/${framework.path}`, `No version directory matches the current package major (v${core.major}).`);
|
|
554
|
+
}
|
|
555
|
+
}
|
|
556
|
+
for (const framework of frameworks) {
|
|
557
|
+
for (const version of framework.versions) {
|
|
558
|
+
const described = {
|
|
559
|
+
...version,
|
|
560
|
+
package: {
|
|
561
|
+
name: core.name,
|
|
562
|
+
endpointVersion: version.endpointVersion,
|
|
563
|
+
},
|
|
564
|
+
};
|
|
565
|
+
if (!version.endpointVersion) {
|
|
566
|
+
issue(errors, 'version-release', `docs/${version.path}`, `No ${version.id} release is listed in ${path.posix.join(config.package, 'CHANGELOG.md')}.`);
|
|
567
|
+
}
|
|
568
|
+
stats.versions += 1;
|
|
569
|
+
const collection = loadPages(described, errors);
|
|
570
|
+
for (const page of collection.pages.values()) {
|
|
571
|
+
const checked = validatePage(page, described, context, errors);
|
|
572
|
+
if (!checked) {
|
|
573
|
+
continue;
|
|
574
|
+
}
|
|
575
|
+
page.order = checked.order;
|
|
576
|
+
stats.pages += 1;
|
|
577
|
+
stats.links += checked.scan.links.length;
|
|
578
|
+
stats.examples += checked.scan.fences.filter((fence) => fence.example).length;
|
|
579
|
+
checkLinks(page, checked.scan, context, errors);
|
|
580
|
+
}
|
|
581
|
+
checkOrders(collection, errors);
|
|
582
|
+
}
|
|
583
|
+
}
|
|
584
|
+
return {
|
|
585
|
+
errors,
|
|
586
|
+
stats,
|
|
587
|
+
};
|
|
588
|
+
}
|
package/dist/cli.d.ts
ADDED
package/dist/cli.js
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { parseArgs } from 'node:util';
|
|
4
|
+
import { checkDocs } from './check.js';
|
|
5
|
+
import { loadConfig } from './config.js';
|
|
6
|
+
import { generateDocs } from './generate.js';
|
|
7
|
+
const usage = `Usage: jfdevelops-docs <command> [options]
|
|
8
|
+
|
|
9
|
+
Commands:
|
|
10
|
+
generate Write the API reference, docs/docs.json and every meta.json
|
|
11
|
+
check Validate every page, link and install command
|
|
12
|
+
|
|
13
|
+
Options:
|
|
14
|
+
--root <dir> Project root (default: the current directory)
|
|
15
|
+
--package <dir> Documented package directory
|
|
16
|
+
--name <name> Library name shown in docs.json
|
|
17
|
+
--entry <file> TypeScript entry point for the API reference
|
|
18
|
+
--tsconfig <file> tsconfig for the API reference
|
|
19
|
+
--examples <dir> Directory of type-checked example fixtures
|
|
20
|
+
--skip-reference generate: write navigation only
|
|
21
|
+
-h, --help Show this help
|
|
22
|
+
|
|
23
|
+
Options default to the "docs" addon in jfdevelops.json.`;
|
|
24
|
+
function readOverrides(values) {
|
|
25
|
+
const overrides = {};
|
|
26
|
+
for (const key of ['package', 'name', 'entry', 'tsconfig', 'examples']) {
|
|
27
|
+
const value = values[key];
|
|
28
|
+
if (value !== undefined) {
|
|
29
|
+
overrides[key] = value;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
return overrides;
|
|
33
|
+
}
|
|
34
|
+
function runCheck(root, config) {
|
|
35
|
+
const { errors, stats } = checkDocs({ root, config });
|
|
36
|
+
if (errors.length > 0) {
|
|
37
|
+
for (const error of errors) {
|
|
38
|
+
console.error(`${error.file}: [${error.code}] ${error.message}`);
|
|
39
|
+
}
|
|
40
|
+
console.error(`\nDocs check failed with ${errors.length} problem${errors.length === 1 ? '' : 's'}.`);
|
|
41
|
+
return 1;
|
|
42
|
+
}
|
|
43
|
+
console.log(`Docs check passed: ${stats.versions} versions, ${stats.pages} pages, ${stats.links} links, ${stats.examples} embedded examples.`);
|
|
44
|
+
return 0;
|
|
45
|
+
}
|
|
46
|
+
async function main() {
|
|
47
|
+
const { values, positionals } = parseArgs({
|
|
48
|
+
allowPositionals: true,
|
|
49
|
+
options: {
|
|
50
|
+
root: { type: 'string' },
|
|
51
|
+
package: { type: 'string' },
|
|
52
|
+
name: { type: 'string' },
|
|
53
|
+
entry: { type: 'string' },
|
|
54
|
+
tsconfig: { type: 'string' },
|
|
55
|
+
examples: { type: 'string' },
|
|
56
|
+
'skip-reference': { type: 'boolean' },
|
|
57
|
+
help: { type: 'boolean', short: 'h' },
|
|
58
|
+
},
|
|
59
|
+
});
|
|
60
|
+
const [command] = positionals;
|
|
61
|
+
if (values.help || !command) {
|
|
62
|
+
console.log(usage);
|
|
63
|
+
return values.help ? 0 : 1;
|
|
64
|
+
}
|
|
65
|
+
const root = path.resolve(values.root ?? process.cwd());
|
|
66
|
+
const config = loadConfig(root, readOverrides(values));
|
|
67
|
+
switch (command) {
|
|
68
|
+
case 'generate':
|
|
69
|
+
await generateDocs({ root, config, isReferenceSkipped: values['skip-reference'] ?? false });
|
|
70
|
+
return 0;
|
|
71
|
+
case 'check':
|
|
72
|
+
return runCheck(root, config);
|
|
73
|
+
default:
|
|
74
|
+
console.error(`Unknown command "${command}".\n\n${usage}`);
|
|
75
|
+
return 1;
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
try {
|
|
79
|
+
process.exitCode = await main();
|
|
80
|
+
}
|
|
81
|
+
catch (error) {
|
|
82
|
+
console.error(error instanceof Error ? error.message : error);
|
|
83
|
+
process.exitCode = 1;
|
|
84
|
+
}
|
package/dist/config.d.ts
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
export declare const addonName = "docs";
|
|
2
|
+
declare const optionKeys: readonly ["package", "name", "entry", "tsconfig", "examples"];
|
|
3
|
+
type OptionKey = (typeof optionKeys)[number];
|
|
4
|
+
export type DocsOptions = Partial<Record<OptionKey, string>>;
|
|
5
|
+
export type DocsConfig = {
|
|
6
|
+
package: string;
|
|
7
|
+
name: string;
|
|
8
|
+
entry: string;
|
|
9
|
+
tsconfig: string;
|
|
10
|
+
examples: string;
|
|
11
|
+
};
|
|
12
|
+
/**
|
|
13
|
+
* Resolves the docs settings for a project. Explicit overrides win over the addon options in
|
|
14
|
+
* jfdevelops.json, which win over the defaults.
|
|
15
|
+
*/
|
|
16
|
+
export declare function loadConfig(root: string, overrides?: DocsOptions): DocsConfig;
|
|
17
|
+
export {};
|