@veda-hq/pariksha 0.5.13 → 0.5.14

package/dist/doc-links.js

@@ -0,0 +1,183 @@
+// DOC-DRIFT-01, links and anchors: a relative Markdown link, reference
+// definition or image names a file that exists, and its `#anchor` a heading
+// in that file. The checking is lychee's, offline; this module only chooses
+// the tree it reads, parses its report, and applies the exemptions.
+//
+// lychee reads files from disk. A worktree or index snapshot is read where it
+// stands; a ref snapshot (a push's head or merge base) is extracted to a
+// temporary directory first. Backticked paths are not links: doc-paths.ts
+// reads those.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdtempSync, realpathSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, posix, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { normalizeRepoPath } from "./doc-references.js";
+import { gitEnv, PINNED } from "./git.js";
+import { isRecord } from "./registry-ratchet.js";
+const optionalString = (v, where) => {
+    if (v === undefined || typeof v === 'string')
+        return v;
+    throw new Error(`lychee's report: ${where} is not a string`);
+};
+/** The part of lychee's `--format json` report read here (`error_map`); the rest is ignored. */
+const errorMap = (report) => {
+    const parsed = JSON.parse(report);
+    if (!isRecord(parsed))
+        throw new Error("lychee's report is not a JSON object");
+    const map = parsed['error_map'];
+    if (map === undefined)
+        return [];
+    if (!isRecord(map))
+        throw new Error("lychee's report: error_map is not an object");
+    return Object.entries(map).map(([source, entries]) => {
+        if (!Array.isArray(entries))
+            throw new Error(`lychee's report: error_map["${source}"] is not a list`);
+        return [
+            source,
+            entries.map((entry, i) => {
+                const where = `error_map["${source}"][${i}]`;
+                if (!isRecord(entry))
+                    throw new Error(`lychee's report: ${where} is not an object`);
+                const status = entry['status'];
+                const span = entry['span'];
+                if (status !== undefined && !isRecord(status))
+                    throw new Error(`lychee's report: ${where}.status is not an object`);
+                if (span !== undefined && !isRecord(span))
+                    throw new Error(`lychee's report: ${where}.span is not an object`);
+                const line = span?.['line'];
+                if (line !== undefined && (typeof line !== 'number' || !Number.isSafeInteger(line) || line < 1))
+                    throw new Error(`lychee's report: ${where}.span.line is not a positive integer`);
+                return { url: optionalString(entry['url'], `${where}.url`), status: optionalString(status?.['text'], `${where}.status.text`) ?? '', line };
+            }),
+        ];
+    });
+};
+const reasonFor = (text, path, hash) => {
+    if (/fragment/i.test(text))
+        return path === '' ? `Cannot find heading for \`${hash}\`` : `Cannot find heading for \`${hash}\` in \`${path}\``;
+    if (/not found/i.test(text))
+        return `Cannot find file \`${path}\``;
+    return `${text || 'lychee could not check it'}: \`${path}${hash}\``;
+};
+/**
+ * Reads lychee's `--format json` report of a run in `dir`. Only `file://`
+ * links are this check's; a URL is not (offline, lychee blocks them). Each
+ * target is named from its doc's directory, as the link was written.
+ */
+export const parseLycheeReport = (report, dir) => {
+    const entries = errorMap(report);
+    const root = realpathSync(dir);
+    const findings = [];
+    for (const [source, list] of entries) {
+        const file = relative(root, resolve(root, source));
+        for (const entry of list) {
+            if (entry.url === undefined || !entry.url.startsWith('file:'))
+                continue;
+            const url = new URL(entry.url);
+            // fileURLToPath reads the path alone: the #anchor stays on `url`.
+            const target = fileURLToPath(url);
+            const path = target === join(root, file) ? '' : relative(join(root, file, '..'), target);
+            findings.push({ file, line: entry.line ?? 1, ref: `${path}${url.hash}`, reason: reasonFor(entry.status, path, url.hash) });
+        }
+    }
+    return findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+};
+/**
+ * How lychee's `--files-from` must name `file` to read that file and no
+ * other. It takes a line as a URL (`https:x.md`) unless it starts `./`, and
+ * as a glob when it holds `*`, `?` or `[`, so those are bracketed. A line
+ * cannot hold a newline: that path is refused, never left unchecked.
+ */
+export const lycheeInputLine = (file) => {
+    if (/[\n\r]/.test(file))
+        throw new Error(`lychee reads its file list a line at a time, so it cannot check ${JSON.stringify(file)}: rename it`);
+    return `./${file.replace(/[*?[]/g, (char) => `[${char}]`)}`;
+};
+/**
+ * The real runner: lychee, offline, anchors included. `--config /dev/null`
+ * keeps a lychee.toml in the tree out of it; `--root-dir` resolves a
+ * `/docs/x.md` link from the repository root. A missing lychee fails, never
+ * passes. `command` is the executable, `lychee` on PATH by default.
+ */
+export const lycheeRunner = (command = 'lychee') => (dir, files) => {
+    const result = spawnSync(command, ['--offline', '--include-fragments', '--format', 'json', '--no-progress', '--config', '/dev/null', '--root-dir', realpathSync(dir), '--files-from', '-'], {
+        cwd: dir,
+        encoding: 'utf8',
+        input: `${files.map(lycheeInputLine).join('\n')}\n`,
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    if (result.error !== undefined) {
+        if (result.error.code === 'ENOENT')
+            throw new Error(`${command} is not installed; the link check needs lychee (https://lychee.cli.rs)`);
+        throw result.error;
+    }
+    // 0: every link resolves; 2: some do not, listed in the report.
+    if (result.status !== 0 && result.status !== 2)
+        throw new Error(`lychee exited ${String(result.status)}: ${result.stderr}`);
+    return result.stdout;
+};
+/** A directory holding the snapshot's tree, and how to let it go. */
+export const treeFor = (snapshot) => {
+    if (snapshot.source.kind !== 'ref')
+        return { dir: snapshot.root, release: () => undefined };
+    const dir = mkdtempSync(join(tmpdir(), 'doc-links-'));
+    try {
+        const tar = join(dir, '.tree.tar');
+        execFileSync('git', [...PINNED, 'archive', '-o', tar, snapshot.source.ref], { cwd: snapshot.root, env: gitEnv(process.env), stdio: 'pipe' });
+        execFileSync('tar', ['-xf', tar, '-C', dir], { stdio: 'pipe' });
+        rmSync(tar);
+    }
+    catch (e) {
+        rmSync(dir, { recursive: true, force: true });
+        throw e;
+    }
+    return { dir, release: () => rmSync(dir, { recursive: true, force: true }) };
+};
+/**
+ * The broken links in `files`' Markdown (those the config's `links.include`
+ * takes), as DOC-DRIFT-01 problems. A finding stays out when its line carries
+ * the exemption marker, its target is a placeholder, or the repository's
+ * ignore rules cover the target.
+ */
+export const findLinkProblems = (config, snapshot, files, run) => {
+    const include = config.links?.include;
+    if (include === undefined)
+        return [];
+    const docs = files.filter((file) => include.test(file));
+    if (docs.length === 0)
+        return [];
+    const tree = treeFor(snapshot);
+    let findings;
+    try {
+        // Parsed while the tree stands: its targets are named from tree.dir.
+        findings = parseLycheeReport(run(tree.dir, docs), tree.dir);
+    }
+    finally {
+        tree.release();
+    }
+    const asked = new Set(docs);
+    const kept = findings.filter((finding) => {
+        if (!asked.has(finding.file))
+            return false;
+        const text = snapshot.read(finding.file)?.split('\n')[finding.line - 1];
+        if (text !== undefined && config.exemptMarker.test(text))
+            return false;
+        return !config.placeholder.test(finding.ref);
+    });
+    const targetOf = (finding) => {
+        const path = finding.ref.replace(/#.*$/, '');
+        return path === '' ? null : normalizeRepoPath(posix.join(posix.dirname(finding.file), path));
+    };
+    const targets = kept.flatMap((finding) => {
+        const target = targetOf(finding);
+        return target === null ? [] : [target, `${target}/`];
+    });
+    const ignored = snapshot.ignored([...new Set(targets)]);
+    return kept
+        .filter((finding) => {
+        const target = targetOf(finding);
+        return target === null || (!ignored.has(target) && !ignored.has(`${target}/`));
+    })
+        .map((finding) => ({ check: 'DOC-DRIFT-01', file: finding.file, line: finding.line, ref: finding.ref, reason: finding.reason }));
+};

package/dist/doc-paths.js

@@ -0,0 +1,267 @@
+// DOC-DRIFT-01, backticked paths: a repository path written in backticks, in
+// prose, a shell fence, frontmatter or a code comment (`dir/file.ext`,
+// `dir/`, `dir/**/*.ts`), resolves; so does `file.ext:12`, and a backticked
+// symbol cited beside it is at those lines. No link checker reads code spans,
+// so this is the repository's own check. It needs only the snapshot's file
+// list, so it runs at commit with the link check. A path the repository's
+// ignore rules cover is out of scope.
+import { posix } from 'node:path';
+import { ancestorDirs, codeSpans, commentText, docKind, globToRegExp, isShellFence, normalizeRepoPath, scanMarkdown } from "./doc-references.js";
+import { boundedWord, manifestObject } from "./doc-identifiers.js";
+/** `0123abcd:path` and `origin/main:path` name a blob in history, not the tree. */
+const HISTORICAL_BLOB = /^(?:[0-9a-f]{7,40}|HEAD[~^\d]*|origin\/[\w./-]+|main):/;
+const DOMAIN = /\.(com|org|io|dev|net|ai|app|co|so|sh)$/i;
+/**
+ * Trims wrapping punctuation from a token cut out of prose or a command:
+ * opening brackets and quotes before it, closing ones and sentence
+ * punctuation (a final `.` or `:` included) after it.
+ */
+const trimToken = (token) => token.replace(/^[("'[]+/, '').replace(/[)"'\],;!?.:]+$/, '');
+/** Digits as a line number, or null past a safe integer: no line this check can count to. */
+const lineNumber = (digits) => {
+    const n = Number(digits);
+    return Number.isSafeInteger(n) ? n : null;
+};
+/**
+ * The repository path a single token names, or null when it is not one.
+ * `requireSlash`: a bare name (`spec.md`) is too generic to resolve unless a
+ * line number pins it to one file, so most callers require a directory.
+ */
+export const pathRef = (config, raw, requireSlash = true) => {
+    const { placeholder, paths } = config;
+    if (placeholder.test(raw))
+        return null;
+    let token = trimToken(raw);
+    // `--root=docs/x.md` names its value; `:docs/x.md` names a staged path.
+    const assigned = /^-{1,2}[\w-]+=(.+)$/.exec(token);
+    if (assigned !== null)
+        token = String(assigned[1]);
+    if (HISTORICAL_BLOB.test(token))
+        return null;
+    const blob = /^:([^:\d].*)$/.exec(token);
+    if (blob !== null)
+        token = String(blob[1]);
+    // A scoped package (`@acme/core/…`) or a flag (`-x/…`). An empty token, a
+    // URL, a leading `/` or `~`, `=` and `\` fail the segment test below.
+    if (/^[@-]/.test(token))
+        return null;
+    let lines;
+    const lineSuffix = /^(.+?\.[A-Za-z0-9]+)(?::(\d+)(?:-(\d+))?(?::\d+)?|#L(\d+)(?:-L(\d+))?)$/.exec(token);
+    if (lineSuffix !== null) {
+        token = String(lineSuffix[1]);
+        const startText = String(lineSuffix[2] ?? lineSuffix[4]);
+        const start = lineNumber(startText);
+        const end = lineNumber(lineSuffix[3] ?? lineSuffix[5] ?? startText);
+        if (start !== null && end !== null)
+            lines = [start, end];
+    }
+    const glob = /[*?]/.test(token);
+    const dir = token.endsWith('/');
+    const segments = token.replace(/\/$/, '').split('/');
+    // An empty segment (`a//b`, a leading `/`) fails here too; `{` never gets this far: a placeholder.
+    if (!segments.every((segment) => /^[\w.@+*?,-]+$/.test(segment)))
+        return null;
+    if (segments.length > 1 && DOMAIN.test(String(segments[0])))
+        return null;
+    if (requireSlash && segments.length < 2 && lines === undefined)
+        return null;
+    const extension = /\.([A-Za-z0-9]+)$/.exec(String(segments.at(-1)))?.[1]?.toLowerCase();
+    const hasExtension = extension !== undefined && paths.extensions.has(extension);
+    if (!dir && !hasExtension && !(glob && segments.length > 1))
+        return null;
+    // `0.1/2.5` and friends: a path segment has at least one letter.
+    if (!segments.some((segment) => /[A-Za-z]/.test(segment)))
+        return null;
+    if (paths.examples.test(token.replace(/\/$/, '')))
+        return null;
+    if (paths.untracked.some((prefix) => `${token}/`.startsWith(prefix)))
+        return null;
+    return { path: token, glob, dir, lines };
+};
+const DEPENDENCY_LISTS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+const resolverFor = (config, snapshot) => {
+    const manifests = [...snapshot.files].filter((file) => file === 'package.json' || config.paths.workspaces.test(file));
+    // A workspace's source root too: code comments cite `src`-relative paths.
+    const workspaces = manifests.filter((file) => file !== 'package.json').flatMap((file) => [posix.dirname(file), `${posix.dirname(file)}/src`]);
+    // Package names any tracked manifest depends on: `pg-pool/index.js` is a file inside one.
+    const dependencies = new Set();
+    for (const text of snapshot.readMany(manifests).values()) {
+        const pkg = manifestObject(text);
+        for (const list of DEPENDENCY_LISTS) {
+            const deps = pkg?.[list];
+            // A malformed list names no dependencies; the manifest's other lists count.
+            if (typeof deps === 'object' && deps !== null && !Array.isArray(deps))
+                for (const name of Object.keys(deps))
+                    dependencies.add(name);
+        }
+    }
+    const globs = new Map();
+    const globMatches = (glob) => {
+        const cached = globs.get(glob);
+        if (cached !== undefined)
+            return cached;
+        const pattern = globToRegExp(glob);
+        const found = [...snapshot.files, ...snapshot.dirs].some((path) => pattern.test(path));
+        globs.set(glob, found);
+        return found;
+    };
+    const exists = (path) => snapshot.files.has(path) || snapshot.dirs.has(path);
+    return {
+        inDependency: (path) => dependencies.has(String(path.split('/')[0])),
+        // A path as a reader would resolve it: next to the doc, then upwards, then from each workspace.
+        resolveLoose: (doc, ref) => {
+            const tried = [...new Set([...ancestorDirs(doc), ...workspaces].map((base) => normalizeRepoPath(posix.join(base, ref.path))))].filter((candidate) => candidate !== null);
+            const path = tried.find((candidate) => (ref.glob ? globMatches(candidate) : exists(candidate))) ?? null;
+            // A directory is asked about as one, so `dir/` ignore rules apply.
+            return { path, tried: ref.dir ? tried.map((t) => `${t}/`) : tried };
+        },
+        // A directory or glob is anchored when its first segment exists from some base:
+        // `refs/heads/*` and branch prefixes are not paths. `..` above the root is anchored.
+        anchored: (doc, ref) => {
+            const first = String(ref.path.split('/')[0]);
+            if (first === '..')
+                return true;
+            return [...ancestorDirs(doc), ...workspaces].some((base) => {
+                const candidate = normalizeRepoPath(posix.join(base, first));
+                return candidate !== null && snapshot.dirs.has(candidate);
+            });
+        },
+    };
+};
+const IDENTIFIER = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*(?:\(\))?$/;
+/** The backticked symbol cited beside a span: "`name` in `file.ts:12`", or "`file.ts:12` (`name`)". */
+const symbolNear = (text, spans, index) => {
+    const span = spans[index];
+    if (span === undefined)
+        return null;
+    const before = spans[index - 1];
+    if (before !== undefined && IDENTIFIER.test(before.content) && /^\s*(?:\(|at|in|—|–|-|:)?\s*\[?$/.test(text.slice(before.end + 1, span.start - 1)))
+        return before.content;
+    const after = spans[index + 1];
+    if (after !== undefined && IDENTIFIER.test(after.content) && /^\]?(?:\([^)]*\))?\s*\(\s*$/.test(text.slice(span.end + 1, after.start - 1)))
+        return after.content;
+    return null;
+};
+/** DOC-DRIFT-01's backticked paths over `files` in `snapshot`. Links and anchors are lychee's (doc-links.ts). */
+export const findPathProblems = (config, snapshot, files) => {
+    const resolver = resolverFor(config, snapshot);
+    const pending = [];
+    const flag = (file, line, ref, reason, tried = []) => {
+        pending.push({ file, line, ref, reason, tried });
+    };
+    /** Checks a resolved file's line range and the symbol cited beside it. */
+    const checkLines = (file, line, shown, target, lines, symbol) => {
+        // A directory has no lines to count.
+        const text = snapshot.read(target);
+        if (text === undefined)
+            return;
+        const content = text.split('\n');
+        const count = text.endsWith('\n') ? content.length - 1 : content.length;
+        const [start, end] = lines;
+        if (start < 1 || end < start || end > count) {
+            flag(file, line, shown, `\`${target}\` has ${count} lines; line ${end > count ? end : start} does not exist`);
+            return;
+        }
+        if (symbol === null)
+            return;
+        // `a.b.run()` is looked for as `run`.
+        const name = symbol.replace(/\(\)$/, '').replace(/^.*\./, '');
+        const window = content.slice(Math.max(0, start - 4), end + 3).join('\n');
+        if (!boundedWord(name).test(window))
+            flag(file, line, shown, `\`${symbol}\` is not at \`${target}:${start}${end === start ? '' : `-${end}`}\` — the citation drifted`);
+    };
+    /** A backticked or fenced token: resolve loosely, then lines and symbol. */
+    const checkToken = (file, line, token, symbol) => {
+        const ref = pathRef(config, token, true);
+        if (ref === null || config.paths.layouts.some((l) => l.pattern.test(ref.path) && !(l.except?.test(file) ?? false)))
+            return;
+        let target;
+        let tried;
+        if (!ref.path.includes('/')) {
+            const near = resolver.resolveLoose(file, ref);
+            tried = near.tried;
+            if (near.path !== null) {
+                target = near.path;
+            }
+            else {
+                const matches = snapshot.byBasename.get(ref.path) ?? [];
+                if (matches.length > 1)
+                    return; // ambiguous: cannot tell which file
+                target = matches[0] ?? null;
+            }
+        }
+        else {
+            if ((ref.dir || ref.glob) && !resolver.anchored(file, ref))
+                return;
+            if (resolver.inDependency(ref.path))
+                return;
+            const resolved = resolver.resolveLoose(file, ref);
+            target = resolved.path;
+            tried = resolved.tried;
+        }
+        if (target === null) {
+            flag(file, line, token, ref.glob ? `\`${ref.path}\` matches no tracked file` : `\`${ref.path}\` is not tracked (looked beside the doc, above it and at the root)`, tried);
+            return;
+        }
+        if (ref.dir && snapshot.files.has(target)) {
+            flag(file, line, token, `\`${ref.path}\` is a file, not a directory`);
+            return;
+        }
+        if (ref.lines !== undefined)
+            checkLines(file, line, token, target, ref.lines, symbol);
+    };
+    const checkSpans = (file, line, text, skipLinkLabels) => {
+        const spans = codeSpans(text);
+        spans.forEach((span, index) => {
+            // A span that is the label of a link is checked through its link.
+            if (skipLinkLabels && /\]\(/.test(text.slice(span.end, span.end + 3)))
+                return;
+            const symbol = symbolNear(text, spans, index);
+            for (const token of span.content.split(/\s+/))
+                checkToken(file, line, token, symbol);
+        });
+    };
+    const checkMarkdownLine = (file, line) => {
+        if (line.exempt)
+            return;
+        if (line.fence !== null) {
+            if (!isShellFence(line.fence))
+                return;
+            // A `$ ` prompt is no path (a placeholder); a `#` word starts a comment that runs to the end of the line.
+            for (const token of line.text.split(/\s+/)) {
+                if (token.startsWith('#'))
+                    break;
+                checkToken(file, line.number, token, null);
+            }
+            return;
+        }
+        if (line.frontmatter) {
+            for (const [, value] of line.text.matchAll(/^\s*(?:-\s+|[\w-]+:\s+)(.+)$/g)) {
+                for (const token of String(value).split(/[\s,]+/))
+                    checkToken(file, line.number, token, null);
+            }
+            return;
+        }
+        checkSpans(file, line.number, line.text, true);
+    };
+    for (const file of files) {
+        const kind = docKind(config, file);
+        const content = snapshot.read(file);
+        if (kind === null || content === undefined)
+            continue;
+        if (kind === 'markdown') {
+            for (const line of scanMarkdown(content, config.exemptMarker))
+                checkMarkdownLine(file, line);
+        }
+        else if (kind === 'code') {
+            content.split('\n').forEach((text, index) => {
+                const comment = commentText(config.files.hashComments, file, text);
+                if (comment === null || config.exemptMarker.test(comment))
+                    return;
+                checkSpans(file, index + 1, comment, false);
+            });
+        }
+    }
+    const ignored = snapshot.ignored([...new Set(pending.flatMap((problem) => problem.tried))]);
+    return pending.filter((problem) => !problem.tried.some((path) => ignored.has(path))).map(({ file, line, ref, reason }) => ({ check: 'DOC-DRIFT-01', file, line, ref, reason }));
+};

package/dist/doc-references-config.js

@@ -0,0 +1,172 @@
+// The doc-references config: every fact about one repository the checks read
+// (which files carry references, where scripts and identifiers are defined,
+// what reads as a placeholder) lives here, never in the engine.
+import { isRecord, isRepoPath, list, object, onlyKeys, parseJson, path, regex, required, text } from "./registry-ratchet.js";
+const strings = (raw, key, where) => list(raw, key, where).map((s, i) => {
+    if (typeof s !== 'string' || s === '')
+        throw new Error(`${where}${key}[${i}] must be a non-empty string`);
+    return s;
+});
+/** A list of regular expressions, empty allowed. */
+const patterns = (raw, key, where, flags = '') => list(raw, key, where).map((s, i) => regex(s, `${where}${key}[${i}]`, flags));
+const nonEmpty = (items, key, where) => {
+    if (items.length === 0)
+        throw new Error(`${where}"${key}" is empty, so nothing would match`);
+    return items;
+};
+/** A regex at `raw[key]`, flags optional as `{ "pattern", "flags" }`. */
+const pattern = (raw, key, where) => {
+    const v = raw[key];
+    if (isRecord(v)) {
+        onlyKeys(v, ['pattern', 'flags'], `${where}${key}: `);
+        const flags = v['flags'] ?? '';
+        if (typeof flags !== 'string' || !/^[imsu]*$/.test(flags))
+            throw new Error(`${where}${key}.flags must be some of i, m, s, u`);
+        return regex(v['pattern'], `${where}${key}.pattern`, flags);
+    }
+    return regex(v, `${where}"${key}"`);
+};
+const MARKER_WORD = /^[\w-]+$/;
+export const parseConfig = (source) => {
+    const raw = parseJson(source);
+    onlyKeys(raw, ['baseline', 'exemptMarker', 'files', 'placeholder', 'paths', 'links', 'scripts', 'commands', 'identifiers'], '');
+    const skipped = [];
+    const exemptWord = text(raw, 'exemptMarker', '');
+    if (!MARKER_WORD.test(exemptWord))
+        throw new Error('"exemptMarker" must be one word of letters, digits, _ and -');
+    const filesRaw = object(raw, 'files', '');
+    const fw = 'files: ';
+    onlyKeys(filesRaw, ['markdown', 'html', 'code', 'codeExclude', 'exclude', 'hashComments'], fw);
+    const files = {
+        markdown: nonEmpty(patterns(filesRaw, 'markdown', fw), 'markdown', fw),
+        html: patterns(filesRaw, 'html', fw),
+        code: patterns(filesRaw, 'code', fw),
+        codeExclude: patterns(filesRaw, 'codeExclude', fw),
+        exclude: patterns(filesRaw, 'exclude', fw),
+        hashComments: pattern(filesRaw, 'hashComments', fw),
+    };
+    const pathsRaw = object(raw, 'paths', '');
+    const pw = 'paths: ';
+    onlyKeys(pathsRaw, ['extensions', 'examples', 'untracked', 'workspaces', 'layouts'], pw);
+    const extensions = nonEmpty(strings(pathsRaw, 'extensions', pw), 'extensions', pw).map((e, i) => {
+        if (!/^[a-z0-9]+$/.test(e))
+            throw new Error(`${pw}extensions[${i}]: "${e}" must be lowercase letters and digits, no dot`);
+        return e;
+    });
+    const untracked = strings(pathsRaw, 'untracked', pw).map((p, i) => {
+        if (!p.endsWith('/') || !isRepoPath(p.slice(0, -1)))
+            throw new Error(`${pw}untracked[${i}]: "${p}" must be a root-relative folder ending in /`);
+        return p;
+    });
+    const layouts = list(pathsRaw, 'layouts', pw).map((l, i) => {
+        const where = `${pw}layouts[${i}]: `;
+        if (!isRecord(l))
+            throw new Error(`${pw}layouts[${i}] must be an object`);
+        onlyKeys(l, ['pattern', 'except'], where);
+        return { pattern: regex(l['pattern'], `${where}"pattern"`), except: l['except'] === undefined ? undefined : regex(l['except'], `${where}"except"`) };
+    });
+    const paths = {
+        extensions: new Set(extensions),
+        examples: pattern(pathsRaw, 'examples', pw),
+        untracked,
+        workspaces: pattern(pathsRaw, 'workspaces', pw),
+        layouts,
+    };
+    const links = required(raw, 'links', '', skipped, () => {
+        const l = object(raw, 'links', '');
+        onlyKeys(l, ['include'], 'links: ');
+        return { include: pattern(l, 'include', 'links: ') };
+    });
+    const scriptsRaw = object(raw, 'scripts', '');
+    const sw = 'scripts: ';
+    onlyKeys(scriptsRaw, ['manifests', 'mutating', 'verification', 'wrappers'], sw);
+    const manifests = nonEmpty(strings(scriptsRaw, 'manifests', sw), 'manifests', sw).map((m, i) => {
+        if (!isRepoPath(m) || !/(?:^|\/)package\.json$/.test(m))
+            throw new Error(`${sw}manifests[${i}]: "${m}" must be a root-relative package.json`);
+        return m;
+    });
+    const mutatingRaw = object(scriptsRaw, 'mutating', sw);
+    const mutating = new Map();
+    for (const [name, safer] of Object.entries(mutatingRaw)) {
+        if (typeof safer !== 'string' || safer === '')
+            throw new Error(`${sw}mutating.${name} must name the script to use instead`);
+        mutating.set(name, safer);
+    }
+    const scripts = {
+        manifests,
+        mutating,
+        verification: pattern(scriptsRaw, 'verification', sw),
+        wrappers: strings(scriptsRaw, 'wrappers', sw),
+    };
+    const commandsRaw = object(raw, 'commands', '');
+    const cw = 'commands: ';
+    onlyKeys(commandsRaw, ['typescriptRunner', 'nested'], cw);
+    const commands = {
+        typescriptRunner: required(commandsRaw, 'typescriptRunner', cw, skipped, () => text(commandsRaw, 'typescriptRunner', cw)),
+        nested: strings(commandsRaw, 'nested', cw),
+    };
+    const idRaw = object(raw, 'identifiers', '');
+    const iw = 'identifiers: ';
+    onlyKeys(idRaw, ['notIdentifiers', 'searchExclude', 'diffExclude', 'prisma', 'routes', 'jobs', 'packages'], iw);
+    const prisma = required(idRaw, 'prisma', iw, skipped, () => {
+        const p = object(idRaw, 'prisma', iw);
+        const w = 'identifiers.prisma: ';
+        onlyKeys(p, ['schemas', 'migrations', 'roles'], w);
+        return {
+            schemas: pattern(p, 'schemas', w),
+            migrations: required(p, 'migrations', w, skipped, () => path(p, 'migrations', w)),
+            roles: required(p, 'roles', w, skipped, () => {
+                const r = object(p, 'roles', w);
+                onlyKeys(r, ['schema', 'enum'], `${w}roles: `);
+                const name = text(r, 'enum', `${w}roles: `);
+                if (!/^\w+$/.test(name))
+                    throw new Error(`${w}roles.enum must be an enum name`);
+                return { schema: path(r, 'schema', `${w}roles: `), enum: name };
+            }),
+        };
+    });
+    const routes = required(idRaw, 'routes', iw, skipped, () => {
+        const r = object(idRaw, 'routes', iw);
+        const w = 'identifiers.routes: ';
+        onlyKeys(r, ['controllers', 'prefixes'], w);
+        return { controllers: pattern(r, 'controllers', w), prefixes: pattern(r, 'prefixes', w) };
+    });
+    const jobs = required(idRaw, 'jobs', iw, skipped, () => {
+        const j = object(idRaw, 'jobs', iw);
+        onlyKeys(j, ['workflows'], 'identifiers.jobs: ');
+        return { workflows: pattern(j, 'workflows', 'identifiers.jobs: ') };
+    });
+    const packages = required(idRaw, 'packages', iw, skipped, () => {
+        const p = object(idRaw, 'packages', iw);
+        const w = 'identifiers.packages: ';
+        onlyKeys(p, ['manifests', 'lockfile', 'ownScopes'], w);
+        const ownScopes = strings(p, 'ownScopes', w).map((s, i) => {
+            if (!/^@[a-z0-9][\w.-]*\/$/.test(s))
+                throw new Error(`${w}ownScopes[${i}]: "${s}" must be a scope ending in / (@acme/)`);
+            return s;
+        });
+        return { manifests: pattern(p, 'manifests', w), lockfile: required(p, 'lockfile', w, skipped, () => path(p, 'lockfile', w)), ownScopes };
+    });
+    const identifiers = {
+        notIdentifiers: new Set(strings(idRaw, 'notIdentifiers', iw)),
+        searchExclude: patterns(idRaw, 'searchExclude', iw),
+        diffExclude: strings(idRaw, 'diffExclude', iw),
+        prisma,
+        routes,
+        jobs,
+        packages,
+    };
+    return {
+        baseline: path(raw, 'baseline', ''),
+        exemptMarker: new RegExp(`${exemptWord}:\\s*\\S`),
+        exemptWord,
+        files,
+        placeholder: pattern(raw, 'placeholder', ''),
+        paths,
+        links,
+        scripts,
+        commands,
+        identifiers,
+        skipped,
+    };
+};