Repository navigation
Expand file tree
/
Copy pathlint-docs.mjs
More file actions
116 lines (106 loc) · 3.72 KB
/
Copy pathlint-docs.mjs
File metadata and controls
116 lines (106 loc) · 3.72 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
#!/usr/bin/env node
// Validate Volcano docs against spec/markdown-format.md.
// Usage: node scripts/lint-docs.mjs <dir> [<dir> ...] (default: content)
// Exits non-zero and prints every violation. Missing dirs are skipped, not failed.
import fs from "node:fs";
import path from "node:path";
import url from "node:url";
import yaml from "js-yaml";
import Ajv from "ajv";
import addFormats from "ajv-formats";
import { markdownLinks, routePath } from "./markdown-links.mjs";
const here = path.dirname(url.fileURLToPath(import.meta.url));
const schema = JSON.parse(
fs.readFileSync(path.join(here, "..", "spec", "frontmatter.schema.json"), "utf8"),
);
const config = yaml.load(fs.readFileSync(path.join(here, "..", "docs.config.yaml"), "utf8"));
const siteSections = new Set(config.nav);
const ajv = new Ajv({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(schema);
const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*\.md$/;
const dirs = process.argv.slice(2);
if (dirs.length === 0) dirs.push("content");
const errors = [];
const err = (file, msg) => errors.push(`${file}: ${msg}`);
function splitFrontmatter(text) {
const m = text.match(/^---\n([\s\S]*?)\n---\n?/);
if (!m) return { fm: null, body: text, fmLines: 0 };
return { fm: m[1], body: text.slice(m[0].length), fmLines: m[0].split("\n").length - 1 };
}
function checkBody(file, body, offset) {
const lines = body.split("\n");
let inFence = false;
let fenceChar = "";
lines.forEach((line, i) => {
const f = line.match(/^(`{3,}|~{3,})(.*)$/);
if (f) {
if (!inFence) {
inFence = true;
fenceChar = f[1][0];
if (f[2].trim() === "") err(file, `bare code fence (missing language) at line ${offset + i + 1}`);
} else if (f[1][0] === fenceChar) {
inFence = false;
}
return;
}
if (!inFence && /^# /.test(line)) err(file, `H1 in body at line ${offset + i + 1}; move it to the frontmatter title`);
});
for (const link of markdownLinks(body)) {
if (!link.url.startsWith("/")) continue;
const route = routePath(link.url);
if (route === "/") continue;
const section = route.split("/", 2)[1];
if (!siteSections.has(section)) {
err(file, `site-absolute link must start with a docs section at line ${offset + link.line}: ${link.url}`);
}
}
}
function lintFile(file) {
const base = path.basename(file);
if (base !== "index.md" && base !== "README.md" && !KEBAB.test(base)) {
err(file, "filename is not kebab-case");
}
const text = fs.readFileSync(file, "utf8");
const { fm, body, fmLines } = splitFrontmatter(text);
if (fm === null) {
err(file, "missing YAML frontmatter block");
return;
}
let data;
try {
data = yaml.load(fm);
} catch (e) {
err(file, `invalid YAML frontmatter: ${e.message}`);
return;
}
if (!validate(data)) {
for (const e of validate.errors) err(file, `frontmatter ${e.instancePath || "/"} ${e.message}`);
}
checkBody(file, body, fmLines);
}
function walk(dir) {
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
// internal/ docs are not published; examples/ are reference code (READMEs
// carry frontmatter for rendering but aren't held to the prose format).
if (e.isDirectory() && (e.name === "internal" || e.name === "examples")) continue;
const p = path.join(dir, e.name);
if (e.isDirectory()) walk(p);
else if (e.name.endsWith(".md")) lintFile(p);
}
}
let linted = 0;
for (const d of dirs) {
if (!fs.existsSync(d)) {
console.log(`skip: ${d} (not found)`);
continue;
}
walk(d);
linted++;
}
if (errors.length) {
console.error(`\n${errors.length} doc problem(s):\n`);
for (const e of errors) console.error(" " + e);
process.exit(1);
}
console.log(linted ? "docs OK" : "nothing to lint");