#!/usr/bin/env node /** * Prose check for the Markdown a reader outside the tool sees. * * Two rules, applied to every tracked `.md` and `.mdx` file in scope: * * 1. No dash written as a spaced double hyphen (` -- `), an em dash (U+2014) * or a spaced en dash (U+2013). A sentence uses a period, a comma, a colon * or parentheses instead. * 2. No heading or section named "Why this exists" or "Why this matters", * including the forms with a noun between ("Why this playbook exists"). * * Only prose is read. Front matter, fenced code blocks, indented code blocks, * HTML comments and inline code spans are skipped: inside a command, `--` is an * option prefix or the end-of-options separator, not a dash. A table delimiter * row and a line of hyphens alone are markup, not prose. * * Out of scope, by path: CHANGELOG.md and the fragments in changelog.d/ * (released history is not rewritten; changelog.d/README.md is in scope), * LICENSE files, dependency and build output, and every test, fixture, corpus, * golden, snapshot or example directory, whose text is data a test compares * against. * * node scripts/check-docs-prose.mjs every tracked file in scope * node scripts/check-docs-prose.mjs ... the named files, in scope or not * * Exit 0 when every file passes, 1 with one `file:line: reason` per hit, and * 2 when the file list cannot be read or a named file does not exist. */ import { spawnSync } from 'node:child_process'; import { existsSync, readFileSync } from 'node:fs'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); /** Directory names whose Markdown is data, output or a dependency rather than documentation. */ const EXCLUDED_DIR = /^(?:node_modules|vendor|dist|build|__tests__|tests?|test-[\w.-]+|[\w.-]*fixtures?|corpus|golden|__snapshots__|snapshots?|examples?)$/i; /** True when a repository-relative path is held to the prose rules. */ export function inScope(relPath) { const parts = relPath.split('/'); const base = parts[parts.length - 1]; if (!/\.mdx?$/i.test(base)) return false; if (base === 'CHANGELOG.md') return false; if (/^LICENSE/i.test(base)) return false; if (parts.slice(0, -1).some((dir) => EXCLUDED_DIR.test(dir))) return false; const changelogDir = parts.indexOf('changelog.d'); if (changelogDir !== -1 && !(changelogDir === parts.length - 2 && base === 'README.md')) return false; return true; } /** * Tracked Markdown files in scope, repository-relative. Every GIT_ variable is * dropped first: a GIT_DIR exported by a hook would otherwise point the * listing at another repository. */ export function trackedFiles(root = REPO_ROOT) { const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith('GIT_'))); const run = spawnSync('git', ['-C', root, 'ls-files', '-z', '--', '*.md', '*.mdx'], { encoding: 'utf8', env }); if (run.status !== 0) { throw new Error(`git ls-files failed in ${root}: ${(run.stderr || '').trim() || `exit ${run.status}`}`); } return run.stdout.split('\0').filter((p) => p && inScope(p)).sort(); } /** Index of the next run of exactly `n` backticks at or after `from`, or -1. */ function closingRun(text, from, n) { let j = from; while (j < text.length) { if (text[j] !== '`') { j += 1; continue; } let m = 0; while (text[j + m] === '`') m += 1; if (m === n) return j; j += m; } return -1; } const masked = (s) => s.replace(/[^\n]/g, 'x'); /** * Mask the inline code spans and HTML comments in one block of Markdown, * keeping every line break so the result splits back into the same lines. * A span opened by N backticks closes at the next run of exactly N, which may * sit on a later line of the same block; an unclosed run is literal text. A * comment may run past the block, so its state is carried in `state`. The * mask character is not a space, so `a`--`b` cannot turn into a spaced double * hyphen once the spans are gone. */ export function maskBlock(text, state = { inComment: false }) { let out = ''; let i = 0; while (i < text.length) { if (state.inComment) { const end = text.indexOf('-->', i); const stop = end === -1 ? text.length : end + 3; out += masked(text.slice(i, stop)); i = stop; if (end !== -1) state.inComment = false; continue; } if (text.startsWith('