// Where a markdown page hands a reader a command. One scanner, shared by the two doc-command // rules — `scripts/doc-fixes.ts` (the `fix` column of the error reference) and // `scripts/doc-commands.ts` (every other page) — because two scanners over two file sets is the // drift both rules exist to refuse. // The LEAF module, never the `@ultimat3/cli` barrel: the barrel links every package in the tree, so // one half-written module anywhere crashed this module's guards with a bare SyntaxError (DX ledger #10). import type { FixCitation } from '../../packages/cli/src/fix-command'; import { fixCitations } from '../../packages/cli/src/fix-command'; export { asXCitation } from '../../packages/cli/src/fix-command'; import { toPosix } from './posix-path'; export interface MarkdownFile { readonly path: string; readonly text: string; } /** One `x …` a page wrote, with the span it was written in so a finding can quote it back. */ export interface DocCitation { readonly path: string; /** 1-based, so `path:line` opens it in an editor. */ readonly line: number; /** The code span or fenced line, trimmed — what the reader would copy. */ readonly span: string; readonly citation: FixCitation; } /** * Fence languages whose contents are shell, not a program. A `ts` fence's `x` is a variable and * every `x` in one would be a false citation; a bare fence and a `sh` fence are what a reader * pastes into a terminal, and `wiki/Installation.md`'s rendered `X_ENV_MISSING` block — the one * printing `fix: x env check --fix` — is a bare one. */ const SHELL_FENCE: ReadonlySet = new Set(['', 'sh', 'bash', 'shell', 'console', 'text']); const FENCE = /^\s*(?:```|~~~)\s*([A-Za-z0-9+#-]*)/; /** * Inline code spans, per GFM: a run of N backticks closed by a run of exactly N. Prose OUTSIDE a * span is deliberately not read — "the x axis of the chart" is not a citation, and a rule that * read bare prose would report findings on sentences nobody can run. */ const CODE_SPAN = /(`+)([^`]|[^`][\s\S]*?[^`])\1(?!`)/g; /** Every runnable-looking span on one line: the fenced line itself, or each code span in it. */ function spansOf(line: string, fence: string | undefined): readonly string[] { if (fence !== undefined) return SHELL_FENCE.has(fence) ? [line] : []; return [...line.matchAll(CODE_SPAN)].map((match) => match[2] ?? ''); } /** One runnable-looking span: a shell-fenced line or an inline code span, with its 1-based line. */ export interface DocSpan { readonly line: number; readonly span: string; } /** * Every span a page presents as runnable, fence state tracked across lines. Shared by every rule * that judges what a reader would paste, so two rules never disagree about what counts as one. */ export function scanDocSpans(file: MarkdownFile): readonly DocSpan[] { const found: DocSpan[] = []; const lines = file.text.split('\n'); let fence: string | undefined; for (let index = 0; index < lines.length; index += 1) { const line = lines[index] ?? ''; const opener = FENCE.exec(line); if (opener !== null) { fence = fence === undefined ? (opener[1] ?? '').toLowerCase() : undefined; continue; } for (const span of spansOf(line, fence)) found.push({ line: index + 1, span }); } return found; } /** * Every `x …` a page presents as runnable. Pure over the file's text, so the negative * case is a fixture rather than an edit to a page three other people are rewriting. */ export function scanDocCitations(file: MarkdownFile): readonly DocCitation[] { return scanDocSpans(file).flatMap(({ line, span }) => fixCitations(span).map((citation) => ({ path: file.path, line, span: span.trim(), citation })), ); } /** * Every markdown file under a glob, sorted, so two runs on one tree report in one order. * * **`dot: true`, and it is load-bearing rather than tidy, `As of 2026-08-27`.** `Bun.Glob` on * **1.3.14** matches nothing under a dot-directory without it — even when the pattern spells the * dot itself — where **1.4.0** matches either way. Measured, this tree, same patterns: * * ``` * 1.3.14 1.4.0 * .github/workflows/*.yml 0 5 * .github/workflows/*.yml dot:true 5 5 * the deep `.claude` markdown glob 0 15 * ``` * * Four scanners share this reader — `gate-steps`, `doc-commands`, `release-facts`, * `version-stamp-scan` — and `STEP_GLOBS` names `.github/workflows/*.yml` and a deep `.claude` * markdown glob precisely because a workflow and an agent brief each state the gate's step count. * On Bun 1.3 those two globs selected **zero files** and the rule reported green: not a wrong * answer, a question never asked, with the runtime as the only thing closing the hole. * * Found by trialling the repo on 1.3.14 (`.github/actions/setup/action.yml` records why that trial * was refused) and fixed regardless, because **a scan whose CORPUS depends on the Bun minor is the * defect** — the pin above this reader is one line and moves. Passed unconditionally rather than * branched on `Bun.version`: the flag is a no-op on the runtime that already does this. */ export async function readMarkdown( root: string, glob: string, skip: (path: string) => boolean = () => false, ): Promise { const files: MarkdownFile[] = []; for await (const scanned of new Bun.Glob(glob).scan({ cwd: root, absolute: false, dot: true })) { // `/`-spelt, so a page is one key on every host: Windows' `wiki\_Footer.md` was a second page // beside the `wiki/_Footer.md` every pin and stamp names, and reported as unscanned. const path = toPosix(scanned); if (skip(path)) continue; files.push({ path, text: await Bun.file(`${root}/${path}`).text() }); } return files.sort((a, b) => (a.path < b.path ? -1 : 1)); }