@veda-hq/pariksha 0.5.13 → 0.5.14

package/dist/doc-commands.js

@@ -0,0 +1,187 @@
+// The commands a Markdown document shows (DOC-DRIFT-02): each simple command
+// in a shell fence or an inline code span, read into the words bash would
+// hand the program. doc-command-rules.ts judges them.
+import { posix } from 'node:path';
+import { codeSpans, isShellFence, scanMarkdown } from "./doc-references.js";
+import { maskQuoted, stripComment } from "./shell-text.js";
+/** A command word: what makes a code span or a bare fence line a command. */
+const COMMAND_HEAD = /^(?:cd\s+\S+\s*&&\s*)?(?:[A-Z_][A-Z0-9_]*=\S*\s+)*(?:pnpm|npx|node|tsx|python3?|bash|sh)\s/;
+/**
+ * In a fence declared as shell, a script path may itself be the command
+ * (`./scripts/x.ts --flag`). Elsewhere a lone path is a mention.
+ */
+const SCRIPT_HEAD = /^(?:[A-Z_][A-Z0-9_]*=\S*\s+)*\.{0,2}\/?[\w./-]+\.(?:ts|mjs|js|sh|py)(?:[\s;&|]|$)/;
+/** Fence info strings that declare a block as shell (a bare fence only may be). */
+const DECLARED_SHELL = new Set(['bash', 'sh', 'shell', 'zsh', 'console', 'terminal']);
+/** The value of digits a pattern already matched in base `radix`. */
+const digitsValue = (digits, radix) => {
+    let value = 0;
+    for (const digit of digits.toLowerCase())
+        value = value * radix + '0123456789abcdef'.indexOf(digit);
+    return value;
+};
+/** The named escapes of ANSI-C quoting. */
+const ANSI_C_NAMED = { a: '\u0007', b: '\b', e: '\u001b', E: '\u001b', f: '\f', n: '\n', r: '\r', t: '\t', v: '\v', '\\': '\\', "'": "'", '"': '"', '?': '?' };
+/**
+ * The value of a `$'…'` body, as bash decodes it: the named escapes, octal
+ * `\N` to `\NNN` (low eight bits), `\xH`/`\xHH`, `\uHHHH`, `\UHHHHHHHH` and
+ * `\cX` (X's low five bits); an unknown escape keeps its backslash, and the
+ * value ends at its first NUL.
+ */
+const ansiC = (body) => String(body
+    .replace(/\\(?:([0-7]{1,3})|x([\da-fA-F]{1,2})|u([\da-fA-F]{1,4})|U([\da-fA-F]{1,8})|c([^])|[^])/g, (escape, octal, x, u, bigU, control) => {
+    if (octal !== undefined)
+        return String.fromCharCode(digitsValue(octal, 8) & 0xff);
+    const hex = x ?? u ?? bigU;
+    if (hex !== undefined) {
+        const code = digitsValue(hex, 16);
+        // Past Unicode bash writes no character; keep the escape.
+        return code > 0x10ffff ? escape : String.fromCodePoint(code);
+    }
+    if (control !== undefined)
+        return String.fromCharCode(control.charCodeAt(0) & 0x1f);
+    return ANSI_C_NAMED[escape.slice(1)] ?? escape;
+})
+    .split('\0')[0]);
+/**
+ * Shell words of one simple command, as bash hands them to the program. A
+ * word runs to unquoted whitespace and joins its parts (`--mode="a b"` is one
+ * word): single quotes keep every character, double quotes every character
+ * but a backslash before `$`, `` ` ``, `"` or `\`, and outside quotes a
+ * backslash keeps the character after it. `$'…'` is ANSI-C quoting, its
+ * escapes decoded, and `$"…"` a double-quoted string. A quote that never
+ * closes stays a character (bash refuses the line). Expansions, operators and
+ * line continuations are the callers' or out of reach.
+ */
+export const shellWords = (text) => Array.from(text.matchAll(/(?:\$'(?:[^'\\]|\\[^])*'|'[^']*'|\$?"(?:[^"\\]|\\[^])*"|\\[^]|[^\s'"\\]|['"\\])+/g), ([word]) => Array.from(word.matchAll(/\$'((?:[^'\\]|\\[^])*)'|'([^']*)'|\$?"((?:[^"\\]|\\[^])*)"|\\([^])|([^])/g), (part) => (part[1] === undefined ? undefined : ansiC(part[1])) ?? part[2] ?? part[3]?.replace(/\\([$`"\\])/g, '$1') ?? part[4] ?? String(part[5])).join(''));
+/** Whether code ends in a backslash that escapes what follows: an odd run of them. */
+const continues = (code) => /(?:^|[^\\])(?:\\\\)*\\$/.test(code);
+const withoutCr = (line) => (line.endsWith('\r') ? line.slice(0, -1) : line);
+/** `code` without its outer blanks, but one a backslash escapes (`a\ `). */
+const trimCode = (code) => {
+    const trimmed = code.trim();
+    if (!continues(trimmed))
+        return trimmed;
+    const end = code.length - code.trimStart().length + trimmed.length;
+    return `${trimmed}${code.charAt(end)}`;
+};
+/**
+ * The simple commands of one shell line, as written: split at `&&`, `||`, `;`
+ * and `|` outside quotes and escapes (found in the quote-masked line, which
+ * keeps every index).
+ */
+export const simpleCommands = (line) => {
+    const masked = maskQuoted(line);
+    const commands = [];
+    let start = 0;
+    for (const match of masked.matchAll(/&&|\|\||;|\|/g)) {
+        commands.push(trimCode(line.slice(start, match.index)));
+        start = match.index + match[0].length;
+    }
+    commands.push(trimCode(line.slice(start)));
+    return commands;
+};
+/** Words after any leading `NAME=value` environment assignments. */
+export const withoutAssignments = (words) => {
+    const first = words.findIndex((word) => !/^[A-Z_][A-Z0-9_]*=/.test(word));
+    return first === -1 ? [] : words.slice(first);
+};
+/** The directory a `cd` command's words name: after bash's own options (`-L`, `-P`, `-e`, `-@`) and a `--`. `cd -` is no option. */
+const cdOperand = (words) => {
+    let at = 1;
+    while (/^-[LPe@]+$/.test(String(words[at])))
+        at += 1;
+    if (words[at] === '--')
+        at += 1;
+    return words[at];
+};
+/** Options of npx (npm exec) whose value is the next word, `-c`/`--call` among them. */
+export const NPX_VALUE_OPTIONS = new Set(['--package', '-p', '--cache', '--userconfig', '--shell', '--call', '-c', '--workspace', '-w']);
+/**
+ * The shell command an `npx -c '…'` runs, if `words` are one: the value of
+ * `-c`/`--call` after npx's other options. npm refuses a call with words
+ * after it, so `npx -c tsx x.ts` runs nothing.
+ */
+export const npxCall = (words) => {
+    if (words[0] !== 'npx')
+        return undefined;
+    let at = 1;
+    for (let word = words[at]; word?.startsWith('-') === true; word = words[at]) {
+        const [name, inline] = word.split(/=(.*)/s);
+        if (name === '--call' || name === '-c') {
+            const call = inline ?? words[at + 1];
+            const next = at + (inline === undefined ? 2 : 1);
+            // npm reads an empty call as none: its words run.
+            return call === '' || next < words.length ? undefined : call;
+        }
+        at += NPX_VALUE_OPTIONS.has(word) ? 2 : 1;
+    }
+    return undefined;
+};
+/** Every simple command shown in a Markdown document. */
+export const documentedCommands = (file, content, exemptMarker) => {
+    const commands = [];
+    /** Reads `text` from directory `from`, recording its commands when `shown`; returns the directory its `cd`s leave the shell in. */
+    const read = (line, text, fenced, from, shown) => {
+        let cwd = from;
+        for (const part of simpleCommands(text)) {
+            const words = withoutAssignments(shellWords(part));
+            const dir = words[0] === 'cd' ? cdOperand(words) : undefined;
+            if (dir !== undefined) {
+                // An absolute operand replaces the directory.
+                cwd = posix.normalize(posix.isAbsolute(dir) ? dir : posix.join(cwd, dir)).replace(/^\.$/, '');
+                continue;
+            }
+            // `npx -c '…'` runs its call's commands, each one judged; npm runs the
+            // call in a shell of its own, so a `cd` in it moves only the call's later commands.
+            const call = npxCall(words);
+            if (call !== undefined) {
+                read(line, call, fenced, cwd, shown);
+                continue;
+            }
+            if (shown && words.length > 0)
+                commands.push({ file, line, words, text: part, cwd, fenced });
+        }
+        return cwd;
+    };
+    const lines = scanMarkdown(content, exemptMarker);
+    // A fence's lines are one shell session: a `cd` on its own line moves the
+    // lines after it. The next fence starts from the root again.
+    let fenceCwd = '';
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line === undefined)
+            break;
+        if (line.fence === null) {
+            if (line.exempt || line.frontmatter)
+                continue;
+            // An inline span is a command of its own, run from the root.
+            for (const span of codeSpans(line.text)) {
+                if (COMMAND_HEAD.test(`${span.content} `))
+                    read(line.number, span.content, false, '', true);
+            }
+            continue;
+        }
+        if (isShellFence(line.fence)) {
+            // A `#` outside quotes starts a comment, and a backslash inside one
+            // continues nothing, so the comment goes before a trailing backslash is
+            // read. That backslash joins the next line as bash joins it, and the
+            // joined text is read for a comment again. A CRLF line's CR is its line break.
+            let text = stripComment(withoutCr(line.text).replace(/^\s*\$\s+/, ''));
+            const start = line.number;
+            // Only a line of the same fence continues it.
+            for (let next = lines[index + 1]; continues(text) && next?.block === line.block; next = lines[index + 1]) {
+                index += 1;
+                text = stripComment(`${text.slice(0, -1)}${withoutCr(next.text)}`);
+            }
+            text = trimCode(text);
+            // Every line's `cd` counts, an exempt line's included (the shell still
+            // runs it); only a line that runs something, unexempt, is judged.
+            fenceCwd = read(start, text, true, fenceCwd, !line.exempt && (COMMAND_HEAD.test(`${text} `) || (DECLARED_SHELL.has(line.fence) && SCRIPT_HEAD.test(text))));
+        }
+        // The fence's last line: the next fence starts from the root.
+        if (lines[index + 1]?.block !== line.block)
+            fenceCwd = '';
+    }
+    return commands;
+};

package/dist/doc-flag-spec.js

@@ -0,0 +1,87 @@
+// What a script's own source declares about its flags (DOC-DRIFT-02): whether
+// it reads its own argv, which flags it knows, the values an enum-valued flag
+// takes, its required flags and its first positional's choices.
+// doc-command-rules.ts holds a documented command to them.
+/** argparse actions that take no value: the flag alone is the input. */
+const FLAG_ONLY_ACTIONS = ['store_true', 'store_false', 'store_const', 'append_const', 'count', 'help', 'version'];
+/** The keyword arguments in an `add_argument` call's text, each value unquoted. A string is read whole, so `help="nargs=0"` is one argument. */
+const keywordArguments = (text) => {
+    const out = new Map();
+    for (const match of text.matchAll(/"[^"]*"|'[^']*'|(\w+)\s*=\s*("[^"]*"|'[^']*'|[^,"']*)/g)) {
+        if (match[1] !== undefined)
+            out.set(match[1], String(match[2]).trim().replace(/^["']|["']$/g, ''));
+    }
+    return out;
+};
+/** Words an argparse option with these keyword arguments takes. */
+const argparseValueCount = (kwargs) => {
+    const action = kwargs.get('action');
+    if (action !== undefined && (FLAG_ONLY_ACTIONS.includes(action) || action.endsWith('BooleanOptionalAction')))
+        return 0;
+    const nargs = kwargs.get('nargs');
+    if (nargs === undefined || nargs === '?')
+        return 1;
+    return /^\d+$/.test(nargs) ? Number(nargs) : Infinity;
+};
+const quotedValues = (text) => new Set([...text.matchAll(/["']([^"']+)["']/g)].map((m) => String(m[1])));
+/** What a script's own source declares about its flags. */
+export const flagSpec = (source, path) => {
+    const shell = /\.(sh|bash)$/.test(path) || !/\.\w+$/.test(path);
+    const python = path.endsWith('.py');
+    // A script that hands its arguments on cannot be judged from its own text.
+    // Nor can a shell script that sources a file: the file runs with the
+    // script's own arguments, so its flags may be read there.
+    const forwards = shell
+        ? /"\$@"|\$\*|"\$\{@\}"|\$@|^\s*(?:source|\.)\s/m.test(source)
+        : python
+            ? /parse_known_args|sys\.argv\[1:\]\s*\)/.test(source) && !/add_argument/.test(source)
+            : /strict:\s*false/.test(source);
+    const values = (flag) => {
+        const usage = new RegExp(`${flag}[ =]<([\\w.:-]+(?:\\|[\\w.:-]+)+)>`).exec(source);
+        if (usage !== null)
+            return new Set(String(usage[1]).split('|'));
+        const braces = new RegExp(`${flag}[ =]\\{([\\w.:-]+(?:,[\\w.:-]+)+)\\}`).exec(source);
+        if (braces !== null)
+            return new Set(String(braces[1]).split(','));
+        const choices = new RegExp(`add_argument\\(\\s*["']${flag}["'][^)]*?choices\\s*=\\s*[[(]([^\\])]*)[\\])]`).exec(source);
+        return choices === null ? undefined : quotedValues(String(choices[1]));
+    };
+    // With subparsers, an argument a subcommand's parser adds (`x =
+    // subs.add_parser(…)`, or chained on one) is that subcommand's: not
+    // required of every invocation, and not the first word.
+    const subcommands = /add_subparsers/.test(source);
+    const local = new Set([...source.matchAll(/(\w+)\s*=\s*[\w.]+\.add_parser\(/g)].map((m) => String(m[1])));
+    const calls = python
+        ? [...source.matchAll(/(?:(\w+)|\))\.add_argument\(\s*["']([\w-]+)["']((?:\s*,\s*["'][\w-]+["'])*)([^)]*)/g)]
+            .filter((match) => !subcommands || (match[1] !== undefined && !local.has(match[1])))
+            .map((match) => ({
+            name: String(match[2]),
+            // Every option string: `add_argument("-o", "--out")` is both.
+            aliases: [String(match[2]), ...Array.from(String(match[3]).matchAll(/["']([\w-]+)["']/g), (m) => String(m[1]))],
+            rest: String(match[4]),
+        }))
+        : [];
+    const required = calls.filter((call) => call.name.startsWith('--') && /required\s*=\s*True/.test(call.rest)).map((call) => call.name);
+    // The first positional's own choices. A call's text ends at its first `)`, so a tuple of choices runs to the end of it.
+    const first = calls.find((call) => !call.name.startsWith('-'));
+    const choices = first === undefined ? null : /choices\s*=\s*[[(]([^\])]*)/.exec(first.rest);
+    return {
+        closed: !forwards,
+        known: (flag) => {
+            if (flag === '--help' || flag === '-h')
+                return true;
+            if (new RegExp(`${flag}(?![\\w-])`).test(source))
+                return true;
+            // node:util parseArgs declares `name: { type: … }` without dashes.
+            const key = flag.replace(/^--/, '');
+            return new RegExp(`(?:^|[\\s{,])['"]?${key}['"]?\\s*:\\s*\\{[^}]*\\btype\\s*:`).test(source);
+        },
+        values,
+        required,
+        valueCount: (flag) => {
+            const call = calls.find((each) => each.aliases.includes(flag));
+            return call === undefined ? 0 : argparseValueCount(keywordArguments(call.rest));
+        },
+        positional: choices === null ? undefined : quotedValues(String(choices[1])),
+    };
+};

package/dist/doc-identifiers.js

@@ -0,0 +1,348 @@
+// DOC-DRIFT-04: a code identifier a doc names exists in the code. Every
+// single-identifier code span in a doc's prose is asked of the code:
+//
+//   - env vars, constants and symbols (`DATABASE_URL`, `parseArgs()`,
+//     `OrderService`): a whole word somewhere in the tracked code; when the doc
+//     says "`x` in `path`", in that file;
+//   - Prisma `Model.field`, `@@unique([a, b])`, migration folders and
+//     `@Roles(…)` values (`identifiers.prisma`);
+//   - HTTP routes (`GET /stores/:id`) against controller decorators
+//     (`identifiers.routes`);
+//   - CI jobs ("the `build` job") against workflow files (`identifiers.jobs`);
+//   - packages (`@acme/core`, `zod@4.1.0`) against workspaces and the
+//     lockfile (`identifiers.packages`).
+//
+// The code search reads the whole tree, so it runs at push and in CI, not at
+// commit.
+import { posix } from 'node:path';
+import { load } from 'js-yaml';
+import { codeSpans, docKind, scanMarkdown } from "./doc-references.js";
+import { isRecord } from "./registry-ratchet.js";
+const UPPER_SNAKE = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/;
+const CAMEL = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)+$/;
+const PASCAL = /^[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]*)+$/;
+const CALL = /^([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\(\)$/;
+const DOTTED = /^([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/;
+const MIGRATION = /^\d{14}_[a-z0-9_]+$/;
+const ROUTE = /^(GET|POST|PUT|PATCH|DELETE)\s+(\/\S*)$/;
+const ROLES = /^@Roles\((.*)\)$/;
+const SCOPED_PACKAGE = /^(@[a-z0-9][\w.-]*\/[a-z0-9][\w.-]*)(?:@(\d+\.\d+\.\d+))?$/;
+const VERSIONED_PACKAGE = /^([a-z0-9][\w.-]*)@(\d+\.\d+\.\d+)$/;
+/** What a single code span names, if it names an identifier; `notIdentifiers` are products and prose. */
+export const identifierRef = (span, notIdentifiers) => {
+    const text = span.trim();
+    if (/\s{2,}/.test(text))
+        return null;
+    if (MIGRATION.test(text))
+        return { kind: 'migration', text };
+    if (ROUTE.test(text))
+        return { kind: 'route', text };
+    if (ROLES.test(text))
+        return { kind: 'roles', text };
+    if (/^@@unique\(\[[\w\s,]+\]\)$/.test(text))
+        return { kind: 'prisma-unique', text };
+    if (SCOPED_PACKAGE.test(text) || VERSIONED_PACKAGE.test(text))
+        return { kind: 'package', text };
+    if (/\s/.test(text) || notIdentifiers.has(text))
+        return null;
+    const call = CALL.exec(text);
+    if (call !== null) {
+        const word = String(call[1]).replace(/^.*\./, '');
+        return word.length < 3 || notIdentifiers.has(word) ? null : { kind: 'symbol', text, word };
+    }
+    const dotted = DOTTED.exec(text);
+    if (dotted !== null && /^[A-Z]/.test(String(dotted[1])) && /^[a-z]/.test(String(dotted[2])))
+        return { kind: 'prisma-field', text };
+    // Lower snake_case is deliberately absent: it is dominated by names that are
+    // not the repository's code (tool names, database settings, table keys).
+    if (UPPER_SNAKE.test(text) || CAMEL.test(text) || PASCAL.test(text))
+        return { kind: 'symbol', text, word: text };
+    return null;
+};
+/** Text of every tracked file whose path matches `pattern`. */
+const contents = (snapshot, pattern) => [...snapshot.readMany([...snapshot.files].filter((file) => pattern.test(file))).values()];
+const prismaModels = (snapshot, schemas) => {
+    const models = new Map();
+    for (const text of contents(snapshot, schemas)) {
+        for (const block of text.matchAll(/^(model|enum|type|view)\s+(\w+)\s*\{([\s\S]*?)^\}/gm)) {
+            const fields = new Set();
+            const uniques = [];
+            for (const raw of String(block[3]).split('\n')) {
+                // A blank line, a `//` comment or an `@@` attribute starts with no word, so it names no field.
+                const line = raw.trim();
+                const unique = /^@@(?:unique|id)\(\s*\[([^\]]+)\]/.exec(line);
+                if (unique !== null) {
+                    uniques.push(String(unique[1])
+                        .split(',')
+                        .map((f) => String(f.trim().split(/[\s(]/)[0]))
+                        .join(','));
+                    continue;
+                }
+                const name = /^(\w+)/.exec(line);
+                if (name !== null)
+                    fields.add(String(name[1]));
+            }
+            models.set(String(block[2]), { fields, uniques });
+        }
+    }
+    return models;
+};
+const splitRoute = (path) => path
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => (/^[:{]/.test(segment) ? ':' : segment.toLowerCase()));
+/** Routes the controllers' decorators serve (`@Controller('x')`, `@Get(':id')`). */
+const controllerRoutes = (snapshot, controllers) => {
+    const routes = [];
+    for (const text of contents(snapshot, controllers)) {
+        let prefix = '';
+        for (const match of text.matchAll(/@(Controller|Get|Post|Put|Patch|Delete)\(\s*(?:['"`]([^'"`]*)['"`])?[^)]*\)/g)) {
+            const path = match[2] ?? '';
+            if (match[1] === 'Controller') {
+                prefix = path;
+                continue;
+            }
+            routes.push({ method: String(match[1]).toUpperCase(), segments: splitRoute(`${prefix}/${path}`) });
+        }
+    }
+    return routes;
+};
+/** A controller parameter takes any documented value (`/stores/42`); a documented parameter names only a parameter. */
+const routeMatches = (route, method, segments) => route.method === method && route.segments.length === segments.length && route.segments.every((segment, index) => segment === ':' || segment === segments[index]);
+const roleValues = (snapshot, schema, name) => {
+    const roles = new Set();
+    const text = snapshot.read(schema);
+    if (text === undefined)
+        return roles;
+    for (const [, block] of text.matchAll(new RegExp(`^enum ${name}\\s*\\{([\\s\\S]*?)^\\}`, 'gm'))) {
+        for (const [, role] of String(block).matchAll(/^[ \t]*([A-Z_]+)\s*$/gm))
+            roles.add(String(role));
+    }
+    return roles;
+};
+/** Job ids and job names in the workflow files; one that does not parse is its linter's to fail. */
+const workflowJobs = (snapshot, workflows) => {
+    const jobs = new Set();
+    for (const text of contents(snapshot, workflows)) {
+        let workflow;
+        try {
+            workflow = load(text);
+        }
+        catch {
+            continue;
+        }
+        const all = isRecord(workflow) ? workflow['jobs'] : undefined;
+        if (!isRecord(all))
+            continue;
+        for (const [id, job] of Object.entries(all)) {
+            jobs.add(id);
+            if (isRecord(job) && typeof job['name'] === 'string')
+                jobs.add(job['name']);
+        }
+    }
+    return jobs;
+};
+/** A manifest's parsed JSON as an object, or undefined: a malformed manifest is another check's to fail. */
+export const manifestObject = (text) => {
+    try {
+        const parsed = JSON.parse(text);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const packageIndex = (snapshot, manifests, lockfile) => {
+    const names = new Set();
+    const versions = new Set();
+    for (const text of contents(snapshot, manifests)) {
+        const name = manifestObject(text)?.['name'];
+        if (typeof name === 'string')
+            names.add(name);
+    }
+    const lock = lockfile === undefined ? undefined : snapshot.read(lockfile);
+    for (const match of (lock ?? '').matchAll(/^ {2}'?((?:@[\w.-]+\/)?[\w.-]+)@(\d+\.\d+\.\d+[^:'(]*)/gm)) {
+        names.add(String(match[1]));
+        versions.add(`${String(match[1])}@${String(match[2])}`);
+    }
+    return { names, versions };
+};
+const BINARY = /\.(png|jpe?g|gif|webp|ico|icns|ttf|otf|woff2?|jar|keystore|zip|gz|tgz|pdf|mp4|mov|mp3|wav|tflite|bin|so|a|dylib|car|lockb)$/i;
+/** Tracked text that can define a name: everything but binaries, the baseline and the config's `searchExclude`. */
+export const isCode = (config, path) => !BINARY.test(path) && path !== config.baseline && !config.identifiers.searchExclude.some((p) => p.test(path));
+/** Which of `words` occur as whole words in the snapshot's code. */
+export const wordsInCode = (config, snapshot, words) => {
+    const wanted = new Set(words);
+    const found = new Set();
+    if (wanted.size === 0)
+        return found;
+    // One tokenising pass over the code, in process: `git grep -F -w -f` with
+    // thousands of patterns runs for minutes on a large tree.
+    for (const text of snapshot.readMany([...snapshot.files].filter((path) => isCode(config, path))).values()) {
+        for (const match of text.matchAll(/[A-Za-z_$][\w$]*/g)) {
+            if (wanted.has(match[0])) {
+                found.add(match[0]);
+                if (found.size === wanted.size)
+                    return found;
+            }
+        }
+    }
+    return found;
+};
+/** `\b` cannot bound a `$`: a word bounded by "no identifier character" on either side. */
+export const boundedWord = (word) => new RegExp(`(?<![\\w$])${word.replace(/\$/g, '\\$')}(?![\\w$])`);
+/** Runs DOC-DRIFT-04 over `files` in `snapshot`. */
+export const findIdentifierProblems = (config, snapshot, files) => {
+    const { notIdentifiers, prisma, routes: routeConfig, jobs: jobConfig, packages: packageConfig } = config.identifiers;
+    const pending = [];
+    for (const file of files) {
+        if (docKind(config, file) !== 'markdown')
+            continue;
+        const content = snapshot.read(file);
+        if (content === undefined)
+            continue;
+        for (const line of scanMarkdown(content, config.exemptMarker)) {
+            if (line.exempt || line.fence !== null || line.frontmatter)
+                continue;
+            const spans = codeSpans(line.text);
+            spans.forEach((span, index) => {
+                const ref = identifierRef(span.content, notIdentifiers);
+                if (ref === null)
+                    return;
+                // A CI job is named as one: "the `build` job".
+                if (ref.kind === 'symbol' && /^\s+jobs?\b/.test(line.text.slice(span.end + 1))) {
+                    pending.push({ file, line: line.number, ref: { kind: 'job', text: ref.text }, citedFile: undefined });
+                    return;
+                }
+                const next = spans[index + 1];
+                let citedFile;
+                if (next !== undefined && /^\s*(?:in|from)\s*\[?$/.test(line.text.slice(span.end + 1, next.start - 1))) {
+                    const path = next.content.replace(/:\d+(?:-\d+)?$/, '');
+                    citedFile = [posix.join(posix.dirname(file), path), path].map((p) => posix.normalize(p)).find((p) => snapshot.files.has(p));
+                }
+                pending.push({ file, line: line.number, ref, citedFile });
+            });
+        }
+    }
+    const inCode = wordsInCode(config, snapshot, [...new Set(pending.flatMap((p) => (p.ref.word === undefined ? [] : [p.ref.word])))]);
+    let models;
+    let routes;
+    let roles;
+    let jobs;
+    let packages;
+    const problems = [];
+    const flag = (p, reason) => {
+        problems.push({ check: 'DOC-DRIFT-04', file: p.file, line: p.line, ref: p.ref.text, reason });
+    };
+    for (const p of pending) {
+        const { ref } = p;
+        switch (ref.kind) {
+            case 'symbol': {
+                const word = ref.word ?? ref.text;
+                if (p.citedFile !== undefined) {
+                    const text = snapshot.read(p.citedFile);
+                    if (text !== undefined && !boundedWord(word).test(text))
+                        flag(p, `\`${word}\` does not occur in \`${p.citedFile}\`, the file the doc cites for it`);
+                }
+                else if (!inCode.has(word)) {
+                    flag(p, `\`${word}\` occurs nowhere in the code — renamed, removed, or never written`);
+                }
+                break;
+            }
+            case 'prisma-field': {
+                if (prisma === undefined)
+                    break;
+                models ??= prismaModels(snapshot, prisma.schemas);
+                const [model = '', field = ''] = ref.text.split('.');
+                const found = models.get(model);
+                // Every `Capital.lower` reads as a column (`Object.keys`), so only a model the schema declares is judged.
+                if (found !== undefined && !found.fields.has(field))
+                    flag(p, `Prisma model \`${model}\` has no field \`${field}\``);
+                break;
+            }
+            case 'prisma-unique': {
+                if (prisma === undefined)
+                    break;
+                models ??= prismaModels(snapshot, prisma.schemas);
+                const wanted = ref.text
+                    .replace(/^@@unique\(\[|\]\)$/g, '')
+                    .split(',')
+                    .map((f) => f.trim())
+                    .join(',');
+                if (![...models.values()].some((model) => model.uniques.includes(wanted)))
+                    flag(p, `no Prisma model declares \`${ref.text}\``);
+                break;
+            }
+            case 'migration': {
+                const dir = prisma?.migrations;
+                if (dir !== undefined && !snapshot.dirs.has(`${dir}/${ref.text}`))
+                    flag(p, `\`${ref.text}\` is not a directory under ${dir}/`);
+                break;
+            }
+            case 'route': {
+                if (routeConfig === undefined)
+                    break;
+                routes ??= controllerRoutes(snapshot, routeConfig.controllers);
+                const [, method = '', rawPath = ''] = ROUTE.exec(ref.text) ?? [];
+                const path = rawPath.replace(/[?#].*$/, '');
+                if (/[{][^}]*,/.test(path))
+                    break; // a brace expansion lists several
+                const all = splitRoute(path);
+                const known = new Set(routes.map((route) => route.segments[0]));
+                // Clients and proxies prefix the served paths (`/api/v1`); the server does not.
+                const start = all.findIndex((segment) => known.has(segment) || !routeConfig.prefixes.test(segment));
+                const segments = all.slice(start === -1 ? all.length : start);
+                const head = segments[0];
+                if (head === undefined || !known.has(head))
+                    break; // not this repository's
+                if (!routes.some((served) => routeMatches(served, method, segments)))
+                    flag(p, `no controller serves \`${method} ${path}\``);
+                break;
+            }
+            case 'roles': {
+                const rolesConfig = prisma?.roles;
+                if (rolesConfig === undefined)
+                    break;
+                roles ??= roleValues(snapshot, rolesConfig.schema, rolesConfig.enum);
+                // No enum to read is a failure, not a pass: every role would go unchecked.
+                if (roles.size === 0) {
+                    flag(p, `no \`${rolesConfig.enum}\` in the Prisma schema to check roles against`);
+                    break;
+                }
+                for (const match of ref.text.replace(/^@Roles\(|\)$/g, '').matchAll(/(?:\w+\.)?([A-Z][A-Z_]+)/g)) {
+                    const role = String(match[1]);
+                    if (!roles.has(role))
+                        flag(p, `\`${role}\` is not a value of ${rolesConfig.enum}`);
+                }
+                break;
+            }
+            case 'job': {
+                if (jobConfig === undefined)
+                    break;
+                jobs ??= workflowJobs(snapshot, jobConfig.workflows);
+                if (!jobs.has(ref.text))
+                    flag(p, `no workflow has a job \`${ref.text}\``);
+                break;
+            }
+            case 'package': {
+                if (packageConfig === undefined)
+                    break;
+                packages ??= packageIndex(snapshot, packageConfig.manifests, packageConfig.lockfile);
+                const scoped = SCOPED_PACKAGE.exec(ref.text);
+                const versioned = VERSIONED_PACKAGE.exec(ref.text);
+                const name = scoped?.[1] ?? versioned?.[1] ?? ref.text;
+                const version = scoped?.[2] ?? versioned?.[2];
+                if (!packages.names.has(name)) {
+                    // Only the repository's own scopes are knowable; a third-party name the lockfile lacks may be installed elsewhere.
+                    if (packageConfig.ownScopes.some((scope) => name.startsWith(scope)))
+                        flag(p, `no workspace is named \`${name}\``);
+                }
+                else if (version !== undefined && !packages.versions.has(`${name}@${version}`)) {
+                    flag(p, `the lockfile has no \`${name}@${version}\``);
+                }
+                break;
+            }
+        }
+    }
+    return problems;
+};