// The docs: README.md and the pages in docs/, as docs/_style.md asks. Each // page has its front matter (title, section, order unique in its section, // summary) and no `#` heading; every relative link reaches a file, and its // anchor a heading there (GitHub's slugs); and prose, outside code, has no // semicolon or em dash. Files in docs/ starting with `_` are not pages. // // node harness/docs.mjs `just lint` // // Prints each problem as `file:line: what`, failing if any. import { existsSync, readdirSync, readFileSync } from 'node:fs'; import { dirname, join, relative, resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; const root = resolve(dirname(fileURLToPath(import.meta.url)), '..'); const docs = join(root, 'docs'); const sections = { HUD: [1, 99], Operations: [100, 299], Reference: [300, 999] }; const pages = readdirSync(docs) .filter((f) => f.endsWith('.md') && !f.startsWith('_')) .map((f) => join(docs, f)); const files = [join(root, 'README.md'), ...pages]; const problems = []; const say = (file, line, what) => problems.push(`${relative(root, file)}:${line}: ${what}`); // The lines of a file, each marked as code (front matter, fenced blocks) or not. const parse = (file) => { const lines = readFileSync(file, 'utf8').split('\n'); let fence = null; let front = lines[0] === '---'; return lines.map((text, i) => { if (front) { if (i > 0 && text === '---') front = false; return { text, code: true, front: true }; } const open = text.match(/^\s*(`{3,}|~{3,})/); if (fence) { if (open && open[1][0] === fence[0] && open[1].length >= fence.length) fence = null; return { text, code: true }; } if (open) { fence = open[1]; return { text, code: true }; } return { text, code: false }; }); }; // GitHub's anchor for a heading: lowercased, punctuation dropped, spaces to // `-`, a repeat suffixed -1, -2…. const anchors = new Map(); const anchorsOf = (file) => { if (anchors.has(file)) return anchors.get(file); const seen = new Map(); const set = new Set(); for (const { text, code } of parse(file)) { const h = !code && text.match(/^#{1,6}\s+(.*?)\s*#*\s*$/); if (!h) continue; const base = h[1] .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') .toLowerCase() .replace(/[^\p{L}\p{N}\s_-]/gu, '') .replace(/\s/g, '-'); const n = seen.get(base) ?? 0; seen.set(base, n + 1); set.add(n ? `${base}-${n}` : base); } anchors.set(file, set); return set; }; const orders = new Map(); for (const file of files) { const lines = parse(file); if (file !== files[0]) { const front = Object.fromEntries( lines.filter((l) => l.front && l.text !== '---').map((l) => { const [key, ...rest] = l.text.split(':'); return [key.trim(), rest.join(':').trim().replace(/^"(.*)"$/, '$1')]; }), ); for (const key of ['title', 'section', 'order', 'summary']) if (!front[key]) say(file, 1, `front matter has no ${key}`); const range = sections[front.section]; const order = Number(front.order); if (front.section && !range) say(file, 1, `section ${front.section} is none of ${Object.keys(sections).join(', ')}`); else if (range && !(order >= range[0] && order <= range[1])) say(file, 1, `order ${front.order} is outside ${front.section}'s ${range[0]}-${range[1]}`); else if (orders.has(order)) say(file, 1, `order ${order} is ${relative(root, orders.get(order))}'s too`); else orders.set(order, file); } lines.forEach(({ text, code }, i) => { if (code) return; if (file !== files[0] && /^#\s/.test(text)) say(file, i + 1, 'a page has no `#` heading: its title is in front matter'); const prose = text.replace(/`[^`]*`/g, ''); for (const [, target] of prose.matchAll(/\]\(([^)\s]+)\)/g)) { if (/^[a-z]+:/.test(target)) continue; const [path, anchor] = target.split('#'); const to = path ? resolve(dirname(file), path) : file; if (!existsSync(to)) say(file, i + 1, `${target}: no such file`); else if (anchor !== undefined && to.endsWith('.md') && !anchorsOf(to).has(anchor)) say(file, i + 1, `${target}: no such heading`); } const words = prose.replace(/\]\([^)]*\)/g, ']').replace(/<[^>]+>/g, '').replace(/&[a-z]+;|&#\d+;/g, ''); if (words.includes(';')) say(file, i + 1, 'a semicolon in prose'); if (/—|\s--\s/.test(words)) say(file, i + 1, 'an em dash in prose'); }); } for (const p of problems) console.log(p); if (problems.length) process.exit(1); console.log(`docs: README.md and ${pages.length} pages, their links and punctuation as docs/_style.md asks`);