// node docs/readme-check.mjs [README.md docs/x.md ...] (default README.md) // Runs the fenced blocks of Markdown pages from a fresh clone of this repo's HEAD, in a scratch directory. // ```bash run runs (per page: one bash, in order, set -eo pipefail, cwd the clone, no ATPROTO_* in the env) // ```bash run=account runs only with DOCS_ACCOUNT=bob|aliceoa: that account's creds file (~/._bsky_social_source) // is sourced, `you.bsky.social` in the block becomes its handle, secrets are masked in any output // ```js run written to a .mjs file in the clone and run with node (needs `type: module` or imports by URL) // ```output right after a run block: its lines appear in that block's output, in order (`…` matches anything) // ```bash norun shown, never run (config for another program, an install of the machine) // Any other bash/sh/shell/js block fails: no snippet goes unchecked. DOCS_OFFLINE=1 skips `run=network` blocks. import { execFileSync, spawnSync } from "node:child_process"; import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { homedir, tmpdir } from "node:os"; import { join, resolve } from "node:path"; const root = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim(); const pages = process.argv.slice(2).length ? process.argv.slice(2) : ["README.md"]; const account = process.env.DOCS_ACCOUNT; const ACCOUNTS = { bob: ["bobvmbuilder.bsky.social", ".bobvmbuilder_bsky_social_source"], aliceoa: ["aliceoa.bsky.social", ".aliceoa_bsky_social_source"] }; const creds = account ? ACCOUNTS[account] : null; if (account && !creds) throw new Error(`DOCS_ACCOUNT is bob or aliceoa, not ${account}`); const secrets = []; let sourceLine = ""; if (creds) { const file = join(homedir(), creds[1]); for (const l of readFileSync(file, "utf8").split("\n")) { const m = /^\s*(?:export\s+)?([A-Z_]+)=(.*)$/.exec(l); if (m) secrets.push(m[2].replace(/^["']|["']$/g, "")); } sourceLine = `. ${file}\n`; } const mask = (s) => secrets.filter((v) => v.length > 3).reduce((t, v) => t.split(v).join("***"), s); function blocks(text) { const lines = text.split("\n"); const out = []; for (let i = 0; i < lines.length; i++) { const open = /^```(\S*)\s*(.*)$/.exec(lines[i]); if (!open) continue; const start = i; const body = []; while (++i < lines.length && lines[i] !== "```") body.push(lines[i]); out.push({ lang: open[1], tags: open[2].split(/\s+/).filter(Boolean), body: body.join("\n"), line: start + 1 }); } return out; } function matches(expected, actual) { const have = actual.split("\n").map((l) => l.trimEnd()); let at = 0; for (const want of expected.split("\n").map((l) => l.trimEnd())) { if (want.trim() === "" || want.trim() === "…") continue; const re = new RegExp(`^${want.split("…").map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`); while (at < have.length && !re.test(have[at])) at++; if (at === have.length) return `missing: ${want}`; at++; } return null; } let failed = 0; const fail = (page, line, msg) => { failed++; console.error(`FAIL ${page}:${line}: ${mask(msg)}`); }; for (const page of pages) { const bs = blocks(readFileSync(resolve(root, page), "utf8")); const dir = mkdtempSync(join(tmpdir(), "readme-check-")); const repo = join(dir, "repo"); execFileSync("git", ["clone", "-q", root, repo]); const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith("ATPROTO_") && !k.startsWith("ATP_"))); const script = []; const checks = []; let last = null; let n = 0; for (const b of bs) { const run = b.tags.find((t) => t === "run" || t.startsWith("run=")); const shell = ["bash", "sh", "shell"].includes(b.lang); if (b.lang === "output") { if (last) checks.push({ ...b, after: last }); continue; } last = null; if (b.tags.includes("norun")) continue; if (!shell && b.lang !== "js") continue; if (!run) { fail(page, b.line, `a ${b.lang} block with no run, run=account or norun tag`); continue; } if (run === "run=network" && process.env.DOCS_OFFLINE === "1") continue; if (run === "run=account" && !creds) continue; let body = creds ? b.body.split("you.bsky.social").join(creds[0]) : b.body; if (b.lang === "js") { const file = `docs-block-${++n}.mjs`; writeFileSync(join(repo, file), body); body = `node ${file}`; } const mark = `__BLOCK_${b.line}__`; script.push(`echo ${mark}`, body); last = { mark, line: b.line }; } if (script.length) { const full = `set -eo pipefail\n${sourceLine}${script.join("\n")}\n`; const r = spawnSync("bash", ["-c", full], { cwd: repo, env, encoding: "utf8", timeout: 20 * 60 * 1000 }); const out = `${r.stdout}${r.stderr}`; if (r.status !== 0) fail(page, 0, `the blocks failed (exit ${r.status}):\n${out.split("\n").slice(-25).join("\n")}`); for (const c of checks) { const part = out.split(c.after.mark)[1]?.split(/__BLOCK_\d+__/)[0] ?? ""; const miss = matches(c.body, part); if (miss) fail(page, c.line, `${miss}\n--- output of the block at line ${c.after.line}:\n${part}`); } console.log(`${page}: ${script.length / 2} blocks run, ${checks.length} outputs checked`); } else console.log(`${page}: no block to run`); rmSync(dir, { recursive: true, force: true }); } process.exit(failed ? 1 : 0);