@veda-hq/pariksha 0.5.13 → 0.5.17

package/dist/cli.js

@@ -4,11 +4,20 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { checkAbsolutePaths, DEFAULT_GUIDANCE as ABSOLUTE_PATHS_GUIDANCE } from "./absolute-paths.js";
+import { checkGates, DEFAULT_GATE_CONFIG, parseGateConfig as parseAggregateConfig } from "./aggregate-gate-needs.js";
+import { parseDocConfig, readDoc, selectDocs } from "./doc-files.js";
+import { checkNonSyncedResources, DEFAULT_GUIDANCE as NON_SYNCED_GUIDANCE } from "./non-synced-resources.js";
+import { checkPnpmSettings, DEFAULT_PNPM_CONFIG, formatParity, parsePnpmConfig } from "./pnpm-settings.js";
 import { adrDirOf, DEFAULTS, findUncited, formatClaims, listAdrs, readOrUndefined, stagedSource, treeSource } from "./authority-citations.js";
 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";
@@ -21,15 +30,20 @@ import { checkClaims, formatOutcome, loadEslint, parseConfig as parseClaimsConfi
 export const DENY_FILE = '.veda/deny.sha256';
 const USAGE = [
     'usage: pariksha authority-citations [--mode staged|tree] [--authority <a,b>] [--issue-prefix <A,B>] [--adr-dir <dir>] [--root <dir>]',
+    '       pariksha absolute-paths [--config <file>] [--files-from <file>|-] [--root <dir>]',
+    '       pariksha aggregate-gate-needs [--config <file>] [--root <dir>]',
     '       pariksha boundary [--root <dir>] [--deny <file>]',
     '       pariksha codec-registry --config <file> [--base <ref> | --no-base] [--root <dir>]',
     '       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>]',
     '       pariksha fault-injection-registry --config <file> [--base <ref> | --no-base] [--root <dir>]',
+    '       pariksha non-synced-resources [--config <file>] [--files-from <file>|-] [--root <dir>]',
+    '       pariksha pnpm-settings [--config <file>] [--root <dir>]',
     '       pariksha required-settings --require <file> [--settings <file>] [--root <dir>]',
     '       pariksha hash <word>',
     '       pariksha --version',
@@ -76,6 +90,68 @@ export const flags = (rest, allowed, switches = []) => {
     }
     return out;
 };
+/**
+ * absolute-paths and non-synced-resources: the documents `--files-from`
+ * lists (a file, or `-` for stdin), or every tracked one, each path read
+ * from `--root`; the report goes to stdout, as the shell checks printed it.
+ */
+const docCheck = (name, defaultGuidance, check) => (f, io) => {
+    const P = `pariksha ${name}:`;
+    const base = resolve(f.get('--root') ?? '.');
+    try {
+        const configPath = f.get('--config');
+        const config = parseDocConfig(configPath === undefined ? undefined : readFileSync(resolve(base, configPath), 'utf8'), defaultGuidance);
+        const from = f.get('--files-from');
+        const listed = from === undefined ? undefined : from === '-' ? (io.stdin ?? (() => readFileSync(0, 'utf8')))() : readFileSync(resolve(from), 'utf8');
+        const docs = selectDocs(base, listed, config.include).map((file) => ({ file, text: () => readDoc(base, file) }));
+        const result = check(docs, base, config);
+        result.out.forEach(io.out);
+        return result.ok ? 0 : 1;
+    }
+    catch (e) {
+        io.err(`${P} ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+};
+const absolutePaths = docCheck('absolute-paths', ABSOLUTE_PATHS_GUIDANCE, (docs, _base, config) => checkAbsolutePaths(docs, config));
+const nonSyncedResources = docCheck('non-synced-resources', NON_SYNCED_GUIDANCE, (docs, base, config) => checkNonSyncedResources(docs, () => {
+    const top = topOf(base);
+    if (top === undefined)
+        throw new Error(`${base} is not in a git repository`);
+    return top;
+}, config));
+const aggregateGateNeeds = (f, io) => {
+    const root = resolve(f.get('--root') ?? '.');
+    const configPath = f.get('--config');
+    let config = DEFAULT_GATE_CONFIG;
+    try {
+        if (configPath !== undefined)
+            config = parseAggregateConfig(readFileSync(resolve(root, configPath), 'utf8'));
+    }
+    catch (e) {
+        io.err(`pariksha aggregate-gate-needs: ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    const result = checkGates(root, config);
+    result.out.forEach(io.out);
+    result.err.forEach(io.err);
+    return result.ok ? 0 : 1;
+};
+const pnpmSettings = (f, io) => {
+    const root = resolve(f.get('--root') ?? '.');
+    const configPath = f.get('--config');
+    try {
+        const config = configPath === undefined ? DEFAULT_PNPM_CONFIG : parsePnpmConfig(readFileSync(resolve(root, configPath), 'utf8'));
+        const result = formatParity(checkPnpmSettings(root, config, (io.now ?? Date.now)()), config.id);
+        result.err.forEach(io.err);
+        result.out.forEach(io.out);
+        return result.ok ? 0 : 1;
+    }
+    catch (e) {
+        io.err(`pariksha pnpm-settings: ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+};
 const boundary = (f, io) => {
     const root = resolve(f.get('--root') ?? '.');
     const denyPath = resolve(root, f.get('--deny') ?? DENY_FILE);
@@ -129,6 +205,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) {
@@ -499,10 +624,15 @@ const COMMANDS = {
     'codec-registry': { allowed: ['--config', '--base', '--root'], switches: ['--no-base'], run: codecRegistry },
     'coverage-exemptions': { allowed: ['--config', '--package', '--root'], run: coverageExemptions },
     'fault-injection-registry': { allowed: ['--config', '--base', '--root'], switches: ['--no-base'], run: faultInjectionRegistry },
+    'absolute-paths': { allowed: ['--config', '--files-from', '--root'], run: absolutePaths },
+    'aggregate-gate-needs': { allowed: ['--config', '--root'], run: aggregateGateNeeds },
+    'non-synced-resources': { allowed: ['--config', '--files-from', '--root'], run: nonSyncedResources },
+    'pnpm-settings': { allowed: ['--config', '--root'], run: pnpmSettings },
     'authority-citations': { allowed: ['--mode', '--authority', '--issue-prefix', '--adr-dir', '--root'], run: authorityCitations },
     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;
+};