@veda-hq/pariksha 0.5.12 → 0.5.14

package/README.md

@@ -4,8 +4,8 @@
 test-quality ratchets. Part of [Veda](https://github.com/veda-hq/veda).
 
 ```sh
-npx @veda-hq/pariksha@0.5.12 <check> [flags]
-npx @veda-hq/pariksha@0.5.12 --version
+npx @veda-hq/pariksha@0.5.14 <check> [flags]
+npx @veda-hq/pariksha@0.5.14 --version
 ```
 
 Every check exits 0 when the repository passes, 1 when it refuses something
@@ -263,6 +263,137 @@ row that is not `` | `path` | bytes | ``, since nothing would enforce it.
 The table file is read on every check too, so it must budget itself: a row
 for its own path (relative to `--root`) is required.
 
+## `doc-references`
+
+```sh
+pariksha doc-references --config <file> --staged [--checks <ids>] [--root <dir>]
+pariksha doc-references --config <file> --base <ref> [--head <ref>] [--checks <ids>] [--root <dir>]
+pariksha doc-references --config <file> --all [--update-baseline | --write-baseline] [--checks <ids>] [--root <dir>]
+```
+
+A doc that names a file, a script or a function the repository no longer
+has reads as true and sends its reader into a broken step. Three checks read
+the docs and code comments the config's `files` select:
+
+- `DOC-DRIFT-01`, paths and links. A path in backticks (in prose, a shell
+  fence, frontmatter or a code comment), a glob, or `file.ts:12` resolves
+  beside the doc, above it, at the root or from a workspace; a cited line
+  exists, and a backticked symbol beside it is near that line. Relative
+  Markdown links and their `#anchor`s are checked by
+  [lychee](https://lychee.cli.rs), offline, which must be on `PATH` (set
+  `links` to `null` to leave links out). A path the tracked `.gitignore`
+  rules cover is out of scope.
+- `DOC-DRIFT-02`, commands. A `pnpm <script>` exists in the scope it runs
+  from (a workspace script needs `--filter`; bins in `node_modules/.bin`
+  count everywhere), and a verification step does not run a script that
+  rewrites the tree (`mutating`). A command a doc shows runs as written:
+  `--filter` before the script name, every `--flag` read by the script it
+  reaches (through a package script or an interpreter), required argparse
+  flags present, enum values and first-positional actions the script
+  accepts, and, with `typescriptRunner` set, a `.ts` file started through it.
+- `DOC-DRIFT-04`, identifiers. A single-identifier code span in prose
+  (`DATABASE_URL`, `parseArgs()`, `OrderService`) occurs as a whole word in
+  the tracked code, or in the file the doc cites for it ("`x` in `y.ts`").
+  Optional kinds: Prisma `Model.field`, `@@unique([…])`, migration folders and
+  `@Roles(…)` values; routes (`GET /stores/:id`) against controller
+  decorators; CI jobs ("the `build` job"); packages against workspace names
+  and the lockfile.
+
+A line ending in `<!-- doc-ref-ok: <why> -->` (in code, a comment holding
+`doc-ref-ok: <why>`; the word is the config's `exemptMarker`) names
+something absent on purpose. Placeholders (`<id>`, `NNN`) and illustrative
+names (`src/foo.ts`) are never references.
+
+Modes. `--staged` (a commit) reads the index: staged docs and comments,
+and any doc naming a path the commit deletes or renames, under
+DOC-DRIFT-01 and -02. During a merge, what the merge took unchanged from the
+merged branch is that branch's to judge. `--base` (a push, CI) reads the
+`--head` tree (default `HEAD`) against its merge base with `--base`: changed
+docs, and docs naming a deleted or renamed path, a changed file by
+`name:line`, or an identifier, script or `--flag` the diff removed, under
+all three checks; a finding the merge base already had is not this push's.
+`--all` reads every reference file in the worktree; it alone may lower the
+baseline (`--update-baseline`) or seed it (`--write-baseline`). `--checks`
+takes a comma-separated subset (`01,02`).
+
+The baseline is a JSON file of per-file counts, `{ "version": 1, "files":
+{ "docs/old.md": { "DOC-DRIFT-01": 3 } } }`, for references that predate
+the check. A checked file may not exceed its count; a file a change touches
+must lower a count it no longer needs; the baseline may only lose entries or
+lower counts against the merge base; an entry for a file the change removed
+must go. The JSON `--config` (relative to the root):
+
+```json
+{
+  "baseline": "scripts/doc-references-baseline.json",
+  "exemptMarker": "doc-ref-ok",
+  "files": {
+    "markdown": ["\\.(md|mdx)$"],
+    "html": ["^(?:.*/)?docs/.*\\.html$"],
+    "code": ["\\.(ts|tsx|js|mjs|sh|py)$"],
+    "codeExclude": ["\\.(test|spec)\\.[jt]sx?$"],
+    "exclude": ["(^|/)node_modules/", "(^|/)fixtures?/", "^docs/history/"],
+    "hashComments": "\\.(sh|py)$"
+  },
+  "placeholder": "[<>${}%…]|\\.\\.\\.|NNN",
+  "paths": {
+    "extensions": ["ts", "js", "json", "md", "sh", "py", "yml", "yaml"],
+    "examples": { "pattern": "(^|/)(foo|bar|example)(\\.[\\w.]+)?$", "flags": "i" },
+    "untracked": [".claude/worktrees/"],
+    "workspaces": "^(apps|packages)/[^/]+/package\\.json$",
+    "layouts": [{ "pattern": "^evidence/[A-Z]-\\d{2}", "except": "^docs/work/" }]
+  },
+  "links": { "include": "\\.md$" },
+  "scripts": {
+    "manifests": ["package.json", "apps/api/package.json"],
+    "mutating": { "lint": "lint:ci", "format": "format:check" },
+    "verification": { "pattern": "verif|check|gate", "flags": "i" },
+    "wrappers": []
+  },
+  "commands": { "typescriptRunner": "pnpm exec tsx", "nested": ["vitest", "turbo", "git"] },
+  "identifiers": {
+    "notIdentifiers": ["GitHub", "TypeScript"],
+    "searchExclude": ["\\.(md|mdx|html)$", "^docs/", "^pnpm-lock\\.yaml$"],
+    "diffExclude": ["*.md", "docs/**"],
+    "prisma": { "schemas": "^apps/api/prisma/.*\\.prisma$", "migrations": "apps/api/prisma/migrations", "roles": { "schema": "apps/api/prisma/schema.prisma", "enum": "Role" } },
+    "routes": { "controllers": "^apps/api/src/.*\\.controller\\.ts$", "prefixes": "^(api|v\\d+)$" },
+    "jobs": { "workflows": "^\\.github/workflows/[^/]+\\.ya?ml$" },
+    "packages": { "manifests": "^(?!(?:.*/)?node_modules/)(?:.*/)?package\\.json$", "lockfile": "pnpm-lock.yaml", "ownScopes": ["@acme/"] }
+  }
+}
+```
+
+- `files`: what a tracked path is, first match winning after `exclude`:
+  Markdown (and Markdown-like XML), HTML pages, or code whose comments are
+  read (`codeExclude` drops tests and fixtures, which name absent paths on
+  purpose). `hashComments` is the code whose comments start with `#`.
+- `paths`: the extensions a backticked path may end in; `examples` and
+  `untracked` names that are never a tracked file; `workspaces`, the
+  manifests whose folders (and `src`) a path also resolves from;
+  `layouts`, paths that name a folder layout rather than a file outside the
+  docs `except` matches.
+- `scripts.wrappers`: repository scripts that run the rest of a line as a
+  command (`pnpm dev:exec pnpm x`). `commands.nested`: programs a wrapper
+  script hands its remaining words to, so they are not its own flags.
+- `identifiers.searchExclude`: tracked text that defines no name (prose,
+  data, sources that quote wrong names on purpose); binaries and the
+  baseline are never read. `diffExclude`: pathspecs the removed-identifier
+  diff leaves out.
+- `links`, `commands.typescriptRunner`, and each of `identifiers.prisma`
+  (and its `migrations` and `roles`), `routes`, `jobs`, `packages` (and its
+  `lockfile`) may be `null`, which leaves that part unchecked and says so on
+  stdout. Absent, each is refused.
+
+On a pass, stdout has one line, `pariksha doc-references: <n> reference
+file(s) checked (<staged|pushed|all>), no new problem; the baseline does not
+grow`. Each refusal is a stderr line, `pariksha doc-references:
+<file>:<line>: [<check>] <ref>: <reason>`, then what to do. Refused (exit 1):
+a reference over its file's count, a count a touched file no longer needs,
+baseline growth, and an entry for a removed file. Exit 2: a bad flag set or
+config (an unknown, missing or bad key or pattern), a malformed baseline, no
+`node_modules/.bin` (DOC-DRIFT-02 would know no bin), a missing or failing
+lychee, a `--base` with no merge base, or a failed git call.
+
 ## `enforcement-claims`
 
 ```sh

package/dist/cli.js

@@ -9,6 +9,10 @@ import { findDenied, hash, isText, parseDenyList } from "./boundary.js";
 import { DEFAULT_CONFIG, findGaps, formatGaps, listedPaths, parseConfig, treePaths } from "./coverage-by-type.js";
 import { checkBuild, checkPackage, checkVitest, formatViolations, loaderFailure, loadVitestExclude, missingConfigs, ownedBy, parseConfig as parseExemptions } from "./coverage-exemptions.js";
 import { checkBudgets } from "./doc-budgets.js";
+import { lycheeRunner } from "./doc-links.js";
+import { parseConfig as parseDocReferencesConfig } from "./doc-references-config.js";
+import { formatReport as formatDocReferences, runGate } from "./doc-references-gate.js";
+import { CHECK_IDS } from "./doc-references.js";
 import { diskReads, formatReads, listFiles, needsTypescript, parseConfig as parseGateConfig, readerFor, readGate } from "./env-gate-switches.js";
 import { loadTypescript, typescriptLoaders } from "./typescript.js";
 import { checkExportDeletions, formatReport } from "./export-deletions.js";
@@ -26,6 +30,7 @@ const USAGE = [
     '       pariksha coverage-by-type [--config <file>] [--files-from <file>|-] [--root <dir>]',
     '       pariksha coverage-exemptions --config <file> [--package <dir>] [--root <dir>]',
     '       pariksha doc-budgets --table <file> [--section <name>] [--root <dir>]',
+    '       pariksha doc-references --config <file> (--staged | --base <ref> [--head <ref>] | --all [--update-baseline | --write-baseline]) [--checks <ids>] [--root <dir>]',
     '       pariksha enforcement-claims --config <file> [--root <dir>]',
     '       pariksha env-gate-switches --config <file> [--mode staged|tree] [--root <dir>]',
     '       pariksha export-deletions [--base <ref>] [--root <dir>]',
@@ -129,6 +134,55 @@ const docBudgets = (f, io) => {
     outcome.err.forEach(io.err);
     return outcome.ok ? 0 : 1;
 };
+/** `--checks 01,DOC-DRIFT-04` as check ids, or every id that is not one. */
+const checkList = (value) => {
+    const ids = value.split(',').map((id) => (id.startsWith('DOC-DRIFT-') ? id : `DOC-DRIFT-${id}`));
+    const unknown = ids.filter((id) => !CHECK_IDS.includes(id));
+    if (unknown.length === 0)
+        return ids;
+    return { unknown: `${unknown.join(', ')} ${unknown.length === 1 ? 'is not one' : 'are not'} of` };
+};
+const docReferences = (f, io) => {
+    const P = 'pariksha doc-references:';
+    const configPath = f.get('--config');
+    const base = f.get('--base');
+    const all = f.has('--all');
+    const baseline = f.has('--update-baseline') ? 'update' : f.has('--write-baseline') ? 'write' : undefined;
+    const modes = [f.has('--staged'), all, base !== undefined].filter(Boolean).length;
+    if (configPath === undefined || modes !== 1 || (f.has('--update-baseline') && f.has('--write-baseline')) || (baseline !== undefined && !all) || (f.has('--head') && base === undefined)) {
+        io.err(USAGE);
+        return 2;
+    }
+    const asked = f.get('--checks');
+    const listed = asked === undefined ? undefined : checkList(asked);
+    if (listed !== undefined && !Array.isArray(listed)) {
+        io.err(`${P} --checks: ${listed.unknown} ${CHECK_IDS.join(', ')}`);
+        return 2;
+    }
+    const dir = resolve(f.get('--root') ?? '.');
+    const root = topOf(dir);
+    if (root === undefined) {
+        io.err(`${P} ${dir} is not in a git repository`);
+        return 2;
+    }
+    const mode = base !== undefined ? { kind: 'range', base, head: f.get('--head') ?? 'HEAD' } : all ? { kind: 'all' } : { kind: 'staged' };
+    // The identifier search reads the whole tree: a push and CI, not a commit.
+    const checks = listed ?? (mode.kind === 'staged' ? ['DOC-DRIFT-01', 'DOC-DRIFT-02'] : [...CHECK_IDS]);
+    let config;
+    let report;
+    try {
+        config = parseDocReferencesConfig(readFileSync(resolve(root, configPath), 'utf8'));
+        report = runGate({ root, config, mode, checks, baseline, links: io.links ?? lycheeRunner() });
+    }
+    catch (e) {
+        io.err(`${P} ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    const result = formatDocReferences(report, { config, mode, checks }, configPath);
+    result.out.forEach(io.out);
+    result.err.forEach(io.err);
+    return result.ok ? 0 : 1;
+};
 const enforcementClaims = async (f, io) => {
     const configPath = f.get('--config');
     if (configPath === undefined) {
@@ -503,6 +557,7 @@ const COMMANDS = {
     boundary: { allowed: ['--root', '--deny'], run: boundary },
     'coverage-by-type': { allowed: ['--config', '--files-from', '--root'], run: coverageByType },
     'doc-budgets': { allowed: ['--table', '--section', '--root'], run: docBudgets },
+    'doc-references': { allowed: ['--config', '--base', '--head', '--checks', '--root'], switches: ['--staged', '--all', '--update-baseline', '--write-baseline'], run: docReferences },
     'enforcement-claims': { allowed: ['--config', '--root'], run: enforcementClaims },
     'env-gate-switches': { allowed: ['--config', '--mode', '--root'], run: envGateSwitches },
     'export-deletions': { allowed: ['--base', '--root'], run: exportDeletions },

package/dist/doc-command-rules.js

@@ -0,0 +1,179 @@
+// DOC-DRIFT-02, the command as written runs: `--filter` before the script,
+// every flag known to the script it reaches, required flags present,
+// enum-valued flags given a value the script accepts, and (when the config
+// names a runner) a `.ts` file started through one.
+//
+// doc-commands.ts reads the commands, doc-command-targets.ts finds the script
+// each runs, and doc-flag-spec.ts reads what that script declares.
+import { posix } from 'node:path';
+import { interpreterTarget, INTERPRETERS, nestedCommands, ownArgs, parsePnpm, scriptIndex, scriptTarget } from "./doc-command-targets.js";
+import { documentedCommands } from "./doc-commands.js";
+import { flagSpec } from "./doc-flag-spec.js";
+/** Text of a script plus the relative modules it imports directly. */
+const sourceWithImports = (context, path) => {
+    const own = context.read(path) ?? '';
+    const parts = [own];
+    // Only a JS/TS module's imports are its own code.
+    if (!/\.[cm]?[jt]sx?$/.test(path))
+        return own;
+    for (const match of own.matchAll(/from\s+['"](\.{1,2}\/[^'"]+)['"]/g)) {
+        const base = posix.join(posix.dirname(path), String(match[1]));
+        const imported = [base, `${base}.ts`, `${base}.mjs`, `${base}.js`, base.replace(/\.js$/, '.ts')].map((candidate) => context.read(candidate)).find((text) => text !== undefined);
+        if (imported !== undefined)
+            parts.push(imported);
+    }
+    return parts.join('\n');
+};
+const LOADER_OPTIONS = new Set(['--import', '--loader', '--experimental-loader', '--require', '-r']);
+const STRIP_OPTIONS = new Set(['--experimental-strip-types', '--experimental-transform-types']);
+/**
+ * The `.ts` script an interpreter starts without a TypeScript loader, if it
+ * starts one. The script is the first word after the interpreter's options.
+ * Only node takes a loader, and only a tsx one (`--import tsx`,
+ * `--loader=tsx/esm`, `-r tsx/cjs`) or a type-stripping flag before the
+ * script runs TypeScript; bash and python run the file as their own language.
+ */
+const typeScriptStartedWithout = (words) => {
+    if (!['node', 'bash', 'sh', 'python', 'python3'].includes(String(words[0])))
+        return undefined;
+    const at = scriptIndex(words, 0);
+    const script = words[at];
+    if (script === undefined || !script.endsWith('.ts'))
+        return undefined;
+    if (words[0] !== 'node')
+        return script;
+    const options = words.slice(1, at);
+    const loader = options.some((word, index) => {
+        const [name = '', inline] = word.split(/=(.*)/s);
+        return STRIP_OPTIONS.has(name) || (LOADER_OPTIONS.has(name) && /^tsx(?:\/|$)/.test(String(inline ?? options[index + 1])));
+    });
+    return loader ? undefined : script;
+};
+/**
+ * The first positional word of `args`: options skipped, and the values the
+ * spec says each takes (`--out result destroy` names `destroy`). Values end
+ * at the next option.
+ */
+const firstPositional = (args, spec) => {
+    for (let index = 0; index < args.length; index += 1) {
+        const word = String(args[index]);
+        if (!word.startsWith('-'))
+            return word;
+        for (let count = spec.valueCount(word); count > 0 && args[index + 1]?.startsWith('-') === false; count -= 1)
+            index += 1;
+    }
+    return undefined;
+};
+const FLAG = /^--[\w-]+(=|$)/;
+/** Runs the DOC-DRIFT-02 command rules over the commands in `files`. */
+export const findCommandProblems = (config, context, files) => {
+    const problems = [];
+    const runner = config.commands.typescriptRunner;
+    const nested = nestedCommands(config.commands.nested);
+    const specs = new Map();
+    const specFor = (path) => {
+        const cached = specs.get(path);
+        if (cached !== undefined)
+            return cached;
+        const spec = flagSpec(sourceWithImports(context, path), path);
+        specs.set(path, spec);
+        return spec;
+    };
+    // join normalizes, and never leaves a leading `./`.
+    const resolveFrom = (dir, path) => {
+        const candidate = posix.join(dir, path);
+        return context.exists(candidate) ? candidate : undefined;
+    };
+    for (const file of files) {
+        const content = context.read(file);
+        if (content === undefined)
+            continue;
+        for (const command of documentedCommands(file, content, config.exemptMarker)) {
+            const { words } = command;
+            const head = String(words[0]);
+            const report = (script, reason) => {
+                problems.push({ file, line: command.line, script, reason });
+            };
+            if (runner !== undefined) {
+                // A `.ts` file started by anything but the runner.
+                if (head.endsWith('.ts')) {
+                    report(head, `\`${head}\` is TypeScript run as a program — start it with \`${runner} ${head}\``);
+                    continue;
+                }
+                const script = typeScriptStartedWithout(words);
+                if (script !== undefined) {
+                    report(script, `\`${head} ${script}\` does not run TypeScript here — use \`${runner} ${script}\``);
+                    continue;
+                }
+            }
+            let target;
+            if (head === 'pnpm') {
+                const pnpm = parsePnpm(words);
+                if (pnpm.exec !== undefined) {
+                    target = interpreterTarget(['exec', ...pnpm.exec], (path) => resolveFrom(posix.join(command.cwd, pnpm.dir ?? ''), path) ?? resolveFrom('', path));
+                }
+                else if (pnpm.script !== undefined) {
+                    const scope = pnpm.filter ?? (command.cwd === '' ? '.' : command.cwd);
+                    const body = context.scripts.get(scope)?.get(pnpm.script);
+                    const dir = context.scopeDirs.get(scope);
+                    // A package script's own options come first; `--filter` among them
+                    // reaches the script, not pnpm. After a positional word it belongs
+                    // to a nested command, and a bin such as turbo has a --filter of its own.
+                    const misplaced = pnpm.args.findIndex((word) => /^(--filter|-F)(=|$)/.test(word));
+                    const before = pnpm.args.slice(0, misplaced);
+                    if (body !== undefined && misplaced !== -1 && before.every((word) => word.startsWith('-')) && !before.includes('--')) {
+                        report(pnpm.script, `\`${String(pnpm.args[misplaced])}\` after \`${pnpm.script}\` is handed to the script, not to pnpm — write \`pnpm --filter <pkg> ${pnpm.script}\``);
+                        continue;
+                    }
+                    if (body !== undefined && dir !== undefined) {
+                        const inner = scriptTarget(body, dir, resolveFrom, nested);
+                        if (inner !== undefined)
+                            target = { path: inner.path, args: pnpm.args[0] === '--' ? pnpm.args.slice(1) : pnpm.args };
+                    }
+                    else if (INTERPRETERS.has(pnpm.script)) {
+                        target = interpreterTarget([pnpm.script, ...pnpm.args], (path) => resolveFrom(command.cwd, path) ?? resolveFrom('', path));
+                    }
+                }
+            }
+            else {
+                target = interpreterTarget(words, (path) => resolveFrom(command.cwd, path) ?? resolveFrom('', path));
+            }
+            if (target === undefined)
+                continue;
+            const { path } = target;
+            const spec = specFor(path);
+            const args = ownArgs(target.args, nested);
+            const flags = args.filter((word) => FLAG.test(word));
+            if (spec.closed) {
+                for (const word of flags) {
+                    const flag = String(word.split('=')[0]);
+                    if (!spec.known(flag))
+                        report(flag, `\`${flag}\` is not a flag of \`${path}\` — the script never reads it`);
+                }
+            }
+            args.forEach((word, index) => {
+                if (!FLAG.test(word))
+                    return;
+                const [flag = '', inline] = word.split(/=(.*)/s);
+                const allowed = spec.values(flag);
+                const value = inline ?? args[index + 1];
+                if (allowed !== undefined && value !== undefined && /^[\w.:/-]+$/.test(value) && !value.startsWith('-') && !allowed.has(value)) {
+                    report(flag, `\`${flag} ${value}\` — \`${path}\` accepts ${[...allowed].join(', ')}`);
+                }
+            });
+            // `python3 x.py collects …` names the program; only a command with arguments, or one in a fence, is an invocation to complete.
+            if (!flags.includes('--help') && (command.fenced || args.length > 0)) {
+                for (const flag of spec.required) {
+                    if (!flags.some((word) => word.split('=')[0] === flag))
+                        report(flag, `\`${path}\` requires \`${flag}\`; the documented command omits it`);
+                }
+            }
+            if (spec.positional !== undefined) {
+                const first = firstPositional(args, spec);
+                if (first !== undefined && /^\w[\w-]*$/.test(first) && !spec.positional.has(first))
+                    report(first, `\`${first}\` is not an action of \`${path}\` (${[...spec.positional].join(', ')})`);
+            }
+        }
+    }
+    return problems;
+};

package/dist/doc-command-targets.js

@@ -0,0 +1,122 @@
+// The repository script a documented command runs (DOC-DRIFT-02): how pnpm
+// reads its options, which words start an interpreter or a nested command,
+// and the script file an interpreter or a package script reaches.
+import { NPX_VALUE_OPTIONS, shellWords, simpleCommands, withoutAssignments } from "./doc-commands.js";
+/** pnpm options that take a value, before the script name. */
+const PNPM_VALUE_OPTIONS = new Set(['--filter', '-F', '--dir', '-C', '--workspace-concurrency', '--reporter']);
+export const parsePnpm = (words) => {
+    let at = 1;
+    const out = { args: [] };
+    for (let word = words[at]; word?.startsWith('-') === true; word = words[at]) {
+        const [name = '', inline] = word.split(/=(.*)/s);
+        if (PNPM_VALUE_OPTIONS.has(name)) {
+            const value = inline ?? words[at + 1];
+            if (value !== undefined && (name === '--filter' || name === '-F'))
+                out.filter = value;
+            if (value !== undefined && (name === '--dir' || name === '-C'))
+                out.dir = value;
+            at += inline === undefined ? 2 : 1;
+        }
+        else {
+            at += 1;
+        }
+    }
+    if (words[at] === 'exec' || words[at] === 'dlx') {
+        out.exec = words.slice(at + 1);
+        return out;
+    }
+    if (words[at] === 'run')
+        at += 1;
+    const script = words[at];
+    if (script !== undefined)
+        out.script = script;
+    out.args = words.slice(at + 1);
+    return out;
+};
+/** Commands that run the script file named after them. */
+export const INTERPRETERS = new Set(['tsx', 'node', 'python', 'python3', 'bash', 'sh']);
+/** Words that start a nested command a wrapper script runs for you: interpreters, pnpm, npx and the config's `commands.nested`. */
+export const nestedCommands = (nested) => new Set([...INTERPRETERS, 'pnpm', 'npx', ...nested]);
+/**
+ * The arguments the script itself parses: everything before a `--` or a
+ * nested command (`test-db.ts vitest run --coverage` hands `--coverage` to
+ * vitest, not to test-db.ts).
+ */
+export const ownArgs = (args, nested) => {
+    const end = args.findIndex((word) => word === '--' || nested.has(word));
+    return end === -1 ? [...args] : args.slice(0, end);
+};
+/** Options of node, and of tsx, which hands them to node, whose value may be the next word: that word is not the script. */
+const NODE_VALUE_OPTIONS = new Set([
+    '--import',
+    '--loader',
+    '--experimental-loader',
+    '--require',
+    '-r',
+    '--env-file',
+    '--env-file-if-exists',
+    '--title',
+    '--conditions',
+    '-C',
+    '--input-type',
+    '--disable-warning',
+    '--redirect-warnings',
+    '--watch-path',
+    '--inspect-port',
+    '--test-reporter',
+    '--test-reporter-destination',
+    '--test-name-pattern',
+    '--test-skip-pattern',
+]);
+/**
+ * Where the script an interpreter at `words[at]` runs sits: the first word
+ * after its options. Only node and tsx options take a separate value; bash's
+ * `-r` and `-C` take none. `--` ends the options.
+ */
+export const scriptIndex = (words, at) => {
+    const valueOptions = words[at] === 'node' || words[at] === 'tsx' ? NODE_VALUE_OPTIONS : new Set();
+    let index = at + 1;
+    for (let word = words[index]; word?.startsWith('-') === true; word = words[index]) {
+        if (word === '--')
+            return index + 1;
+        index += valueOptions.has(word) ? 2 : 1;
+    }
+    return index;
+};
+/** Options of `pnpm exec` whose value is the next word; its `-c` is `--shell-mode`, a switch. */
+const PNPM_EXEC_VALUE_OPTIONS = new Set(['--resume-from']);
+/**
+ * The repository script an interpreter command runs, if it names one: `tsx
+ * scripts/x.ts --a`, `python3 scripts/y.py b`, `bash scripts/z.sh`. The
+ * runner's own options before the interpreter are skipped, a value option's
+ * value with them (`npx --yes tsx …`, `npx -p tsx tsx …`).
+ */
+export const interpreterTarget = (words, resolve) => {
+    let at = 0;
+    if (words[0] === 'npx' || words[0] === 'pnpm')
+        at += 1;
+    if (words[at] === 'exec')
+        at += 1;
+    const valueOptions = words[0] === 'npx' ? NPX_VALUE_OPTIONS : PNPM_EXEC_VALUE_OPTIONS;
+    // The commands an `npx -c '…'` runs are documentedCommands' to read; here its value is skipped like any other.
+    for (let word = words[at]; word?.startsWith('-') === true; word = words[at])
+        at += valueOptions.has(word) ? 2 : 1;
+    if (!INTERPRETERS.has(String(words[at])))
+        return undefined;
+    at = scriptIndex(words, at);
+    const script = words[at];
+    if (script === undefined)
+        return undefined;
+    const path = resolve(script);
+    return path === undefined ? undefined : { path, args: words.slice(at + 1) };
+};
+/** The single command a package script runs, as a Target, if it is one. */
+export const scriptTarget = (command, manifestDir, resolveFrom, nested) => {
+    if (simpleCommands(command).length > 1)
+        return undefined;
+    const target = interpreterTarget(withoutAssignments(shellWords(command)), (path) => resolveFrom(manifestDir, path));
+    // A script that wraps another command passes the doc's words on to it.
+    if (target === undefined || ownArgs(target.args, nested).length < target.args.length)
+        return undefined;
+    return target;
+};