@williamthorsen/nmr 0.39.0 → 0.41.0

package/dist/esm/runCli.js

@@ -16,16 +16,16 @@ import { isTerminalStream, OUTPUT_STYLE_ENV_VAR, OUTPUT_STYLE_FLAG, resolveOutpu
 import { renderRecording, renderRefusal, resolveRecording } from "./recording.js";
 import { assembleReplay } from "./replay-assembly.js";
 import { readReportFormatEnv, REPORT_FORMAT_ENV_VAR, resolveReportFormat } from "./report-format.js";
-import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandScript, findChainedSelfReference, resolveScript, } from "./resolver.js";
+import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandScript, findChainedSelfReference, readPackageJsonScripts, resolveScript, } from "./resolver.js";
 import { resolveChannel, runSteps } from "./runner.js";
-import { composeNmrStep, dropRecursiveSteps, findNmrCrossing, renderChain } from "./steps.js";
+import { composeNmrStep, dropRecursiveSteps, findNmrCrossing, quoteToken, renderChain } from "./steps.js";
 import { UserError } from "./UserError.js";
 import { COMMAND_VERBOSITY_ENV_VAR, readVerbosityEnv, resolveVerbosity, } from "./verbosity.js";
 import { writeVerdict } from "./verdict.js";
 import { readWorkspacePackageNames, resolveWorkspace } from "./workspace.js";
 const VERSION = readPackageVersion(import.meta.url);
 const CROSSING_CONSEQUENCE = "so nmr handles the nested run's output as a tool's.";
-const RECURSIVE_REJECTION = '-R/--recursive matched no workspace:';
+const RECURSIVE_REJECTION = '-R/--recursive did not match any workspace:';
 const LIST_CEILING = 10;
 const NAMED_ESCAPES = new Map([
     ['\n', String.raw `\n`],
@@ -34,7 +34,7 @@ const NAMED_ESCAPES = new Map([
 ]);
 export const RUN_IF_PRESENT_ENV_VAR = 'NMR_RUN_IF_PRESENT';
 export async function runCli(options) {
-    const { args, cwd, env, stdout, stderr } = options;
+    const { args, env, stdout, stderr } = options;
     const parseResult = parseArgs(args);
     if (!parseResult.ok) {
         reportError(parseResult.error, stderr);
@@ -52,6 +52,18 @@ export async function runCli(options) {
         return { exitCode: 1 };
     }
     const { styles } = presentationRead;
+    const { exitCode, isUnknownCommand = false } = await runInvocation({ ...options, parsedArgs, presentationRead });
+    if (exitCode !== 0 && !isUnknownCommand && isTopLevelInvocation(env)) {
+        const hint = formatMisplacedFlagHint(args, parsedArgs.passthrough, styles.stderr);
+        if (hint !== undefined) {
+            stderr.write(`${hint}\n`);
+        }
+    }
+    return { exitCode };
+}
+async function runInvocation(options) {
+    const { cwd, env, parsedArgs, presentationRead, stderr, stdout } = options;
+    const { styles } = presentationRead;
     if (parsedArgs.shouldShowVersion) {
         stdout.write(`${VERSION}\n`);
         return { exitCode: 0 };
@@ -103,7 +115,8 @@ export async function runCli(options) {
     };
     const delegation = composeDelegation({ childEnv, command, parsedArgs });
     if (delegation !== undefined) {
-        return runDelegation({ context, delegation, parsedArgs, runOptions, stderr });
+        const result = await runDelegation({ context, delegation, parsedArgs, runOptions, stderr });
+        return { ...result, isUnknownCommand: result.exitCode !== 0 && !isDefinedInAnyScope(command, context) };
     }
     const registry = shouldUseRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config);
     assertNoSelfReference({
@@ -120,7 +133,7 @@ export async function runCli(options) {
             return { exitCode: 0 };
         }
         reportError(`Unknown command: ${command}`, stderr);
-        return { exitCode: 1 };
+        return { exitCode: 1, isUnknownCommand: true };
     }
     const { isEmptiedByWorkspace, steps: runnableSteps } = readRunnableSteps(resolvedScript, context.workspacePackageDirs);
     const resolvedCommand = renderChain(runnableSteps);
@@ -200,6 +213,7 @@ export async function runCli(options) {
     reportVerdict({ command, scope, ...outcome }, stdout, format, styles.stdout);
     return { exitCode };
 }
+const FILTER_FLAGS = new Set(['-F', '--filter']);
 const BOOLEAN_FLAGS = new Map([
     ['-?', 'shouldShowHelp'],
     ['--help', 'shouldShowHelp'],
@@ -249,7 +263,7 @@ function bindPassthrough(steps, passthrough, command) {
     return { ok: true, steps: boundSteps };
 }
 function formatUnroutableArgumentsError(command) {
-    return (`\`${command}\` takes no trailing arguments: every step of its chain declines them. ` +
+    return (`\`${command}\` does not take trailing arguments: every step of its chain declines them. ` +
         'Running it unnarrowed is not what the arguments asked for, so nothing ran.');
 }
 function composeDelegation(options) {
@@ -320,7 +334,7 @@ function describeCrossingRemedy(options) {
 }
 function describeStepDestination(key) {
     if (isHookName(key)) {
-        return 'a script of their own that the step list names, because a hook has no `:pre` or `:post` of its own';
+        return 'a script of their own that the step list names, because a hook does not have a `:pre` or `:post` of its own';
     }
     return `a \`${key}:pre\` or \`${key}:post\` script`;
 }
@@ -357,7 +371,7 @@ function formatOverrideNotice(resolvedScript, registry, command, anchorDir, quie
 function formatSelfReferenceRemedy(options) {
     const { command, isWorkspaceRoot, monorepoRoot, registry, script } = options;
     if (isHookName(command)) {
-        return `Delete the re-invocation: \`${command}\` runs the steps standing beside it.`;
+        return `Delete the re-invocation: \`${command}\` runs the steps beside it.`;
     }
     const configSite = path.relative(monorepoRoot, resolveConfigPath(monorepoRoot));
     return formatPackageRemedy({ configSite, crossingStep: script, isWorkspaceRoot, key: command, registry });
@@ -366,14 +380,14 @@ function formatPackageRemedy(options) {
     const { configSite, crossingStep, isWorkspaceRoot, key, registry } = options;
     const registryEntry = Object.hasOwn(registry, key) ? registry[key] : undefined;
     if (registryEntry === undefined) {
-        return (`A \`package.json\` script holds no step list: define \`${key}\` in \`${configSite}\` and move the ` +
+        return (`A \`package.json\` script cannot contain a step list: define \`${key}\` in \`${configSite}\` and move the ` +
             `package-specific steps to ${describeStepDestination(key)}.`);
     }
     const registryChain = renderChain(expandScript(registryEntry, isWorkspaceRoot));
     if (registryChain === crossingStep) {
         return `Delete the entry: nmr's own \`${key}\` already runs \`${escapeControlCharacters(registryChain)}\`.`;
     }
-    return `Delete the entry and move the steps it adds to ${describeStepDestination(key)}.`;
+    return `Delete the entry and move the steps that it adds to ${describeStepDestination(key)}.`;
 }
 function findArgError(parsedArgs) {
     if (parsedArgs.shouldPrintLog &&
@@ -401,15 +415,15 @@ function findEmptySelectionRefusal(options) {
 function formatEmptyFilterError(pattern, names) {
     const rejection = formatFilterRejection(pattern);
     if (pattern.startsWith('!')) {
-        return `${rejection} A pattern beginning with \`!\` excludes what it matches, and this one leaves no package standing.`;
+        return `${rejection} A pattern beginning with \`!\` excludes what it matches, and this one excludes every package.`;
     }
     if (pattern.includes('[')) {
-        return `${rejection} A pattern carrying \`[<ref>]\` selects the packages changed since a git ref, and none has changed.`;
+        return `${rejection} A pattern containing \`[<ref>]\` selects the packages changed since a git ref, and none has changed.`;
     }
     if (pattern.startsWith('.') || pattern.startsWith('/') || pattern.startsWith('{')) {
         return (`${rejection} ` +
             'A pattern written `./dir`, `/dir`, or `{dir}` selects the packages under a directory, ' +
-            'and no package sits under this one.');
+            'and this directory does not contain any package.');
     }
     return (`${rejection} A pattern matches a package's manifest \`name\`, ` +
         `not its directory name.${suggestWorkspaceNames(pattern, names)}`);
@@ -426,23 +440,23 @@ function describeEmptyWorkspace(monorepoRoot) {
             return (`pnpm-workspace.yaml ${declaredClause}, whose \`!\` entries exclude every directory matched by the positive ` +
                 'patterns. Drop or narrow the exclusion.');
         case 'no-package':
-            return (`pnpm-workspace.yaml ${declaredClause}, and the matcher found no directory holding a \`package.json\`. ` +
-                'nmr counts a directory as a package only where it holds `package.json`; unlike pnpm, it recognizes ' +
+            return (`pnpm-workspace.yaml ${declaredClause}, and the matcher did not find any directory containing a \`package.json\`. ` +
+                'nmr counts a directory as a package only when it contains `package.json`; unlike pnpm, it recognizes ' +
                 'neither `package.yaml` nor `package.json5`. Add a `package.json` to the directory that should be a ' +
-                'package, or declare a pattern reaching a directory that holds one.');
+                'package, or declare a pattern reaching a directory that contains one.');
         case 'no-packages-list':
-            return (`pnpm-workspace.yaml at ${monorepoRoot} declares no \`packages\` list, so the workspace holds the root ` +
+            return (`pnpm-workspace.yaml at ${monorepoRoot} does not declare a \`packages\` list, so the workspace contains the root ` +
                 'package alone. Declare a positive pattern such as `packages/*` to reach the packages beneath it.');
         case 'no-pattern':
-            return (`pnpm-workspace.yaml ${declaredClause}, so no pattern reaches the matcher. Declare a positive pattern such ` +
-                'as `packages/*`, and quote any `!` entry, which YAML reads as a tag rather than a string where it ' +
-                'stands bare.');
+            return (`pnpm-workspace.yaml ${declaredClause}, so the matcher does not receive any pattern. Declare a positive ` +
+                'pattern such as `packages/*`, and quote any `!` entry, which YAML reads as a tag rather than a string ' +
+                'when it is unquoted.');
         case 'unreadable-packages':
             return (`pnpm-workspace.yaml at ${monorepoRoot} declares a \`packages\` value that is not a list of strings, so ` +
                 'nothing it declares reaches the matcher. Make it a list whose every entry is a quoted pattern; a bare ' +
                 'value and an entry YAML read as a number or a map are the usual ones.');
         case 'unreadable-manifest':
-            return (`pnpm-workspace.yaml at ${monorepoRoot} holds no valid YAML, so nothing it declares reaches the matcher. ` +
+            return (`pnpm-workspace.yaml at ${monorepoRoot} is not valid YAML, so the matcher does not receive anything that it declares. ` +
                 'Repair the syntax error and run the command again. An unterminated quoted string and a mis-indented ' +
                 'entry are the usual ones.');
         default: {
@@ -463,7 +477,7 @@ function describeDeclaredPatterns(patterns) {
         : `declares ${renderQuotedList(quotablePatterns)}, beside ${emptiedClause}`;
 }
 function formatFilterRejection(pattern) {
-    return `-F/--filter matched no workspace: \`${pattern}\`.`;
+    return `-F/--filter did not match any workspace: \`${pattern}\`.`;
 }
 function suggestWorkspaceNames(pattern, names) {
     if (names.length === 0) {
@@ -511,7 +525,7 @@ function assertNoSelfReference(options) {
     const remedy = formatSelfReferenceRemedy({ command, isWorkspaceRoot, monorepoRoot, registry, script });
     const site = path.relative(monorepoRoot, resolvePackageJsonPath(anchorDir));
     throw new UserError(`${site}: \`scripts.${command}\` re-invokes \`nmr ${command}\` (\`${escapeControlCharacters(script)}\`), ` +
-        `so nmr cannot run the steps it chains. ${remedy}`);
+        `so nmr cannot run the steps that it chains. ${remedy}`);
 }
 function hasRunnableHook(hookName, registry, anchorDir, isWorkspaceRoot) {
     if (findChainedSelfReference(anchorDir, hookName) !== undefined) {
@@ -536,7 +550,7 @@ async function lookUpRecordedPass(options) {
     }
     const [missingPackage] = buildOutput.missingPackages;
     if (missingPackage !== undefined) {
-        writeDebugNote(`running ${command}: ${missingPackage} has no build output`, env, stderr);
+        writeDebugNote(`running ${command}: ${missingPackage} does not have build output`, env, stderr);
         return undefined;
     }
     const stalePackage = findStaleBuildOutput(entry.buildDigests, buildOutput.digests);
@@ -587,7 +601,7 @@ function parseArgs(args) {
         const arg = args[index];
         if (arg === undefined)
             break;
-        if (arg === '-F' || arg === '--filter') {
+        if (FILTER_FLAGS.has(arg)) {
             index++;
             const filterValue = args[index];
             if (!filterValue) {
@@ -715,7 +729,7 @@ async function recordPass(options) {
     const output = await readBuildOutputState(monorepoRoot, options.config);
     const [missingPackage] = output.missingPackages;
     if (missingPackage !== undefined) {
-        writeDebugNote(`not recording ${command}: ${missingPackage} has no build output`, env, stderr);
+        writeDebugNote(`not recording ${command}: ${missingPackage} does not have build output`, env, stderr);
         return;
     }
     const changedPackage = findStaleBuildOutput(options.buildOutputBefore.digests, output.digests);
@@ -862,6 +876,69 @@ async function runGated(options) {
         outcome: exitCode === 0 ? { outcome: 'passed', durationMs } : { outcome: 'failed', durationMs, exitCode },
     };
 }
+function formatMisplacedFlagHint(args, passthrough, style) {
+    const { flagNames, movedTokens, remainingTokens } = splitMisplacedFlags(passthrough);
+    if (flagNames.length === 0) {
+        return undefined;
+    }
+    const commandIndex = args.length - passthrough.length - 1;
+    const correctedTokens = [
+        'nmr',
+        ...args.slice(0, commandIndex),
+        ...movedTokens,
+        ...args.slice(commandIndex, commandIndex + 1),
+        ...remainingTokens,
+    ];
+    const subject = flagNames.length === 1 ? 'is an nmr flag' : 'are nmr flags';
+    return (`${STATUS_GLYPHS[style].warning.text} ${renderQuotedList(flagNames)} ${subject}; ` +
+        `nmr reads its flags only before the command: \`${correctedTokens.map(quoteToken).join(' ')}\``);
+}
+function isDefinedInAnyScope(command, context) {
+    const registries = [buildRootRegistry(context.config), buildWorkspaceRegistry(context.config)];
+    if (registries.some((registry) => Object.hasOwn(registry, command))) {
+        return true;
+    }
+    return [context.monorepoRoot, ...context.workspacePackageDirs].some((dir) => Object.hasOwn(readPackageJsonScripts(dir) ?? {}, command));
+}
+function isTopLevelInvocation(env) {
+    const runId = env[RUN_ID_ENV_VAR];
+    return runId === undefined || runId === '';
+}
+function readMisplacedFlagLength(args, index) {
+    const arg = args[index] ?? '';
+    if (FILTER_FLAGS.has(arg)) {
+        return (args[index + 1] ?? '') === '' ? undefined : 2;
+    }
+    const booleanFlag = BOOLEAN_FLAGS.get(arg);
+    if (booleanFlag !== undefined) {
+        return booleanFlag === 'shouldShowHelp' || booleanFlag === 'shouldShowVersion' ? undefined : 1;
+    }
+    const styleArgument = readOutputStyleArgument(args, index);
+    return styleArgument?.ok === true ? styleArgument.consumedCount : undefined;
+}
+function splitMisplacedFlags(passthrough) {
+    const flagNames = new Set();
+    const movedTokens = [];
+    const remainingTokens = [];
+    let index = 0;
+    while (index < passthrough.length) {
+        const arg = passthrough[index] ?? '';
+        if (arg === '--') {
+            remainingTokens.push(...passthrough.slice(index));
+            break;
+        }
+        const flagLength = readMisplacedFlagLength(passthrough, index);
+        if (flagLength === undefined) {
+            remainingTokens.push(arg);
+            index++;
+            continue;
+        }
+        flagNames.add(arg.startsWith(`${OUTPUT_STYLE_FLAG}=`) ? OUTPUT_STYLE_FLAG : arg);
+        movedTokens.push(...passthrough.slice(index, index + flagLength));
+        index += flagLength;
+    }
+    return { flagNames: [...flagNames], movedTokens, remainingTokens };
+}
 function quoteForShell(arg) {
     return "'" + arg.replace(/'/g, String.raw `'\''`) + "'";
 }

package/dist/esm/runner.d.ts

@@ -1,16 +1,16 @@
 import type { Writable } from 'node:stream';
 import type { Step } from './steps.js';
-/** Where one of a child's output streams goes: a descriptor the child writes to, or a pipe nmr reads. */
+/** Where one of a child's output streams goes: a descriptor to which the child writes, or a pipe read by nmr. */
 export type OutputChannel = number | 'pipe';
-/** The channel each of a child's output streams runs on. */
+/** The channel on which each of a child's output streams runs. */
 export interface OutputChannels {
     stderr: OutputChannel;
     stdout: OutputChannel;
 }
 export interface RunCommandOptions {
-    /** The channel each of the child's output streams runs on. */
+    /** The channel on which each of the child's output streams runs. */
     channels: OutputChannels;
-    /** When true, suppress output on success and write captured output to stderr on failure. */
+    /** When true, suppresses output on success and writes captured output to stderr on failure. */
     quiet?: boolean;
     /** Stream that subprocess stdout flows to in non-quiet mode. Defaults to `process.stdout`. */
     stdout?: Writable;
@@ -34,7 +34,7 @@ export interface RunStepsResult {
      */
     retainedOutput?: RetainedOutput;
 }
-/** How a command ended, and the exit code that carries that ending to nmr's own caller. */
+/** How a command ended, and the exit code that reports that ending to nmr's own caller. */
 type CommandCompletion = {
     outcome: 'exited';
     exitCode: number;
@@ -50,33 +50,33 @@ type CommandCompletion = {
 export type RunCommandResult = CommandCompletion & {
     /**
      * Output retained while the command ran, elided in the middle when it overran the bound.
-     * `undefined` where the stream was handed to the child directly, or where capture stopped early
+     * `undefined` when the stream was handed to the child directly, or when capture stopped early
      * and the retained copy would understate what the command produced.
      */
     stdout: Buffer | undefined;
     stderr: Buffer | undefined;
 };
 /**
- * Returns the channel a stream runs on: the stream's own descriptor when it is a terminal and output is not
- * being withheld, so the child's terminal detection matches nmr's, and a pipe everywhere else.
+ * Returns the channel on which a stream runs: the stream's own descriptor when it is a terminal and output is
+ * not being withheld, so that the child's terminal detection matches nmr's, and a pipe everywhere else.
  */
 export declare function resolveChannel(stream: Writable, quiet: boolean): OutputChannel;
 /**
- * Returns the channel a step running an nmr process below this one runs on: nmr's own descriptor whenever it
- * has one, so the child writes where nmr writes and no ancestor stands between them relaying bytes. A stream
- * carrying no descriptor, which is the one a test injects, falls back to a pipe.
+ * Returns the channel for a step that runs an nmr process below this one: nmr's own descriptor whenever it has
+ * one, so that the child writes where nmr writes, without an ancestor between them relaying bytes. A stream
+ * without a descriptor falls back to a pipe.
  */
 export declare function resolveInheritedChannel(stream: Writable): OutputChannel;
 /**
- * Runs a step list in order and resolves once one fails or all have run, carrying the `&&` semantics nmr
- * promises: the first non-zero exit ends the sequence and is the code returned.
+ * Runs a step list in order and resolves once one fails or all have run, implementing the `&&` semantics that
+ * nmr promises: The first non-zero exit ends the sequence and is the code returned.
  *
- * Sequencing here rather than in a spawned shell is what lets each step run on the channels its kind calls
- * for, and what makes a signal to nmr end the run: the steps after it are never reached, where a shell would
- * have gone on running them unsupervised.
+ * Sequencing here rather than in a spawned shell lets each step run on the channels that its kind calls for, and
+ * makes a signal to nmr end the run: The steps after it are never reached, whereas a shell would have gone on
+ * running them unsupervised.
  *
- * Carries back a bounded copy of what the list's own commands wrote, so a caller can retain it. Only opaque
- * steps contribute: a structural step is another nmr process reporting for the subtree beneath it, and its
+ * Returns a bounded copy of what the list's own commands wrote, so that a caller can retain it. Only opaque
+ * steps contribute: A structural step is another nmr process reporting for the subtree beneath it, and its
  * output is that subtree's to account for.
  */
 export declare function runSteps(steps: readonly Step[], cwd: string | undefined, options: RunStepsOptions): Promise<RunStepsResult>;
@@ -89,7 +89,7 @@ export declare function runSteps(steps: readonly Step[], cwd: string | undefined
  * discarding the retained copy on success and writing it to `options.stderr` on failure, so it has nothing to
  * report unless the caller chose a pipe on both streams.
  *
- * Piped stdout and stderr are ordered by arrival rather than by a shared descriptor, so their interleaving
+ * Because piped stdout and stderr are ordered by arrival rather than by a shared descriptor, their interleaving
  * is approximate.
  */
 export declare function runCommand(command: string, cwd: string | undefined, options: RunCommandOptions): Promise<RunCommandResult>;

package/dist/esm/steps.d.ts

@@ -1,15 +1,15 @@
 /**
- * One element of a resolved command chain, carrying how it was composed rather than how its text reads.
- * A `structural` step is nmr's own composition, held as argv; an `opaque` step is a command nmr does not parse.
+ * One element of a resolved command chain, recording how it was composed rather than how its text reads.
+ * A `structural` step is nmr's own composition, stored as argv; an `opaque` step is a command that nmr does not
+ * parse.
  *
  * A structural step's argv leads with the file to spawn, so the runner has one to hand `spawn` without a shell.
  *
- * `shouldDeclineArguments` travels from the composite element that composed the step to the one reader that acts on it,
- * the binding of the invocation's trailing arguments. Every stage between the two -- the devBin substitution,
- * the chain rendering, the replay assembly, the runner -- passes it through and asks nothing of it.
+ * `shouldDeclineArguments` is passed from the composite element that composed the step to the one reader that acts
+ * on it, the binding of the invocation's trailing arguments. Every stage between the two passes it through unread.
  *
  * `shouldWithholdInput` is read by the runner alone, which gives the step's child the null device as stdin rather
- * than nmr's own. Like `shouldDeclineArguments`, it is set only where it holds and leaves the rendered chain unchanged.
+ * than nmr's own. Like `shouldDeclineArguments`, it is set only when it holds and leaves the rendered chain unchanged.
  */
 export type Step = {
     kind: 'opaque';
@@ -20,81 +20,84 @@ export type Step = {
     shouldDeclineArguments?: boolean;
     shouldWithholdInput?: boolean;
 };
-/** What a structural step asks of the nmr process it spawns. */
+/** What a structural step asks of the nmr process that it spawns. */
 export interface NmrStepTarget {
     command: string;
-    /** Whether the command is fanned out to other scopes, where a `-R` or `-F` sends it. */
+    /** Whether the command is fanned out to other scopes, as it is when a `-R` or `-F` sends it. */
     isDelegate: boolean;
     /**
-     * Whether the command is fanned out to every package, where a `-R` sends it. A separate field rather than a
-     * narrowing of `isDelegate`, whose reader surveys the scopes a `-F` may also have reached.
+     * Whether the command is fanned out to every package, as it is when a `-R` sends it. A separate field rather
+     * than a narrowing of `isDelegate`, whose reader surveys the scopes that a `-F` may also have reached.
      */
     isRecursive: boolean;
-    /** Whether the command runs against the root registry, where a `-w` anchors it. */
+    /** Whether the command runs against the root registry, as it does when a `-w` anchors it. */
     isWorkspaceRoot: boolean;
 }
 /**
- * How a `package.json` entry names the command it is declared under: as its whole value, or alongside other
- * steps. `sole` covers an entry carrying trailing arguments, which declare no step of their own.
+ * How a `package.json` entry names the command under which it is declared: as its whole value, or alongside
+ * other steps. `sole` covers an entry with trailing arguments, which do not declare a step of their own.
  */
 export type SelfReference = 'chained' | 'sole';
 /**
  * Composes the structural step that re-invokes nmr for one composite element.
  *
- * The element tokenizes on whitespace, so it may carry nmr's own flags but cannot carry a space-bearing token.
- * `-w` is prepended as its own token, so the child selects the root registry on its own.
+ * The element tokenizes on whitespace, so it may contain nmr's own flags but cannot contain a space-bearing
+ * token. `-w` is prepended as its own token: The child selects the root registry on its own.
  *
- * `shouldDeclineArguments` is set only where it holds, so a step that takes the trailing arguments renders and compares
- * exactly as it did before any element declared anything.
+ * Because `shouldDeclineArguments` is set only when it holds, a step that takes the trailing arguments compares
+ * equal to one composed without the option.
  */
 export declare function composeNmrStep(element: string, isWorkspaceRoot: boolean, shouldDeclineArguments?: boolean): Step;
 /**
- * Returns the steps that still run in a workspace holding no package: every step but the ones a `-R` fans out.
+ * Returns the steps that still run in a workspace without any package: every step but the ones that a `-R` fans
+ * out.
  *
- * A `-F` step is left standing. It names one package, and its absence is a real error whoever composed the
- * step, where a `-R` asked for every package and a workspace with none has nothing for it to do.
+ * A `-F` step is kept. It names one package, and its absence is a real error whoever composed the step, whereas
+ * a `-R` asked for every package and a workspace with none has nothing for it to do.
  */
 export declare function dropRecursiveSteps(steps: readonly Step[]): Step[];
 /**
- * Returns the text of the first opaque step that reaches nmr through a shell, or `undefined` when none does.
+ * Returns the text of the first opaque step that runs nmr through a shell, or `undefined` when none does.
  *
  * Recognizes nmr in command position: at the start of the step, after `&&`, `||`, `;`, `|`, or a newline, past
  * any leading environment assignments, and behind a launcher such as `npx` or `pnpm exec`. A separator inside
- * quotes opens no position, so a command merely naming nmr in an argument is not a crossing.
+ * quotes does not open a command position, so a command merely naming nmr in an argument is not a crossing.
  *
- * Partial by construction, and partial in stated ways rather than arbitrary ones: a value-taking flag standing
+ * Partial by construction, and partial in stated ways rather than arbitrary ones: A value-taking flag standing
  * immediately before the program name hides it (`npx -p foo nmr`), and a launcher outside `LAUNCHERS` goes
- * unreported. What it finds is the boundary below which nmr cannot tell its own processes from the tools it
- * runs.
+ * unreported. What it finds is the boundary below which nmr cannot tell its own processes from the tools that
+ * it runs.
  */
 export declare function findNmrCrossing(steps: readonly Step[]): string | undefined;
 /**
  * Returns the first token of a composite element that falls outside the grammar, or `undefined` when the
- * element is a command name optionally preceded by nmr's own flags. A token the shell would not read
- * literally is one the rendering would quote whole, turning the element into a command nobody wrote.
+ * element is a command name optionally preceded by nmr's own flags. A token that the shell would not read
+ * literally would be quoted whole by the rendering, turning the element into a command that nobody wrote.
  */
 export declare function findUnexpressibleToken(element: string): string | undefined;
+/** Quotes a token that the shell would not read literally, and leaves every other token bare. */
+export declare function quoteToken(token: string): string;
 /**
- * Returns the command a structural step's nmr process runs, whether the step hands that command to other
- * scopes rather than running it where it stands, and whether it anchors the command at the monorepo root.
- * Reports nothing for a step that names no nmr command.
+ * Returns the command that a structural step's nmr process runs, whether the step hands that command to other
+ * scopes rather than running it in its own scope, and whether it anchors the command at the monorepo root.
+ * Reports nothing for a step that does not name an nmr command.
  *
- * The inverse of `composeNmrStep`, and beside it because the two share one grammar: an element may lead with
+ * The inverse of `composeNmrStep`, and beside it because the two share one grammar: An element may lead with
  * nmr's own flags, and the command is the first token that is not one.
  */
 export declare function readNmrStep(step: Step): NmrStepTarget | undefined;
 /**
- * Reports whether a `package.json` entry re-invokes the command it is declared under, and whether it declares
- * anything besides. Reports nothing for an entry that names another command, or none.
+ * Reports whether a `package.json` entry re-invokes the command under which it is declared, and whether it
+ * declares anything besides. Reports nothing for an entry that names another command, or none.
  *
- * Honouring such an entry would spawn a shell running the same command in the same directory, reaching the
- * same entry again without bound, so resolution discards it however it reads. `chained` is what separates an
- * entry that thereby loses steps from one that declares nothing to lose.
+ * Honouring such an entry would spawn a shell running the same command in the same directory, which reads the
+ * same entry again without bound, so resolution discards it however it reads. `chained` separates an entry that
+ * thereby loses steps from one that declares nothing to lose.
  *
- * A segment that delegates carries the command to other scopes rather than back to this one. `-w` re-enters
- * only from the root, a package's entry reaching the root's registry and `package.json` instead of its own.
+ * A segment that delegates sends the command to other scopes rather than back to this one. `-w` re-enters
+ * only from the root, a package's `-w` entry resolving against the root's registry and `package.json` instead of its own.
  *
- * Partial in the same ways `findNmrCrossing` is, and for the same reason: what goes unrecognized re-enters
+ * Partial in the same ways `findNmrCrossing` is, and for the same reason: What goes unrecognized re-enters
  * without bound, which hangs rather than passing quietly.
  */
 export declare function readSelfReference(options: {
@@ -103,9 +106,9 @@ export declare function readSelfReference(options: {
     script: string;
 }): SelfReference | undefined;
 /**
- * Renders a step list as the `&&` chain a shell runs.
+ * Renders a step list as the `&&` chain that a shell runs.
  *
- * The sole producer of a chain string: the check-result cache keys on that string, so a change to the rendering
- * invalidates every recorded pass by construction rather than by anyone remembering to.
+ * The sole producer of a chain string: The check-result cache keys on that string, so a change to the rendering
+ * invalidates every recorded pass.
  */
 export declare function renderChain(steps: readonly Step[]): string;

package/dist/esm/steps.js

@@ -33,6 +33,12 @@ export function findNmrCrossing(steps) {
 export function findUnexpressibleToken(element) {
     return tokenize(element).find((token) => !SHELL_SAFE_TOKEN.test(token));
 }
+export function quoteToken(token) {
+    if (SHELL_SAFE_TOKEN.test(token)) {
+        return token;
+    }
+    return "'" + token.replaceAll("'", String.raw `'\''`) + "'";
+}
 export function readNmrStep(step) {
     if (step.kind !== 'structural') {
         return undefined;
@@ -66,12 +72,6 @@ function isRedirectionOperator(char, precedingText, nextChar) {
     }
     return (char === '&' && nextChar === '>') || /[<>]\s*$/.test(precedingText);
 }
-function quoteToken(token) {
-    if (SHELL_SAFE_TOKEN.test(token)) {
-        return token;
-    }
-    return "'" + token.replaceAll("'", String.raw `'\''`) + "'";
-}
 function readNmrTail(segment) {
     const [head, ...rest] = dropLeadingAssignments(tokenizeSegment(segment));
     if (head === undefined) {

package/dist/esm/taze.d.ts

@@ -12,7 +12,7 @@ export type TazeConfig = {
 /**
  * Builds a taze configuration from nmr's shared upgrade policy and a repo's own settings.
  *
- * Any property the caller supplies wins, including `0` and an explicit `undefined` — the latter restores
+ * Any property that the caller supplies wins, including `0` and an explicit `undefined`. The latter restores
  * taze's inheritance of pnpm's `minimumReleaseAge`, which only applies while `maturityPeriod` is unset.
  *
  * The merge is shallow, which suits a policy of scalar defaults. A nested default would clobber rather

package/dist/esm/tests.d.ts

@@ -1,29 +1,34 @@
 /**
- * Declares a suite asserting that a repo's test files hold to nmr's conventions: every collected file names an
- * isolation tier, and every test file sits under a `__tests__` directory.
+ * Declares a suite asserting that a repo's test files follow nmr's conventions: Every collected file names an
+ * isolation tier, and every test file is under a `__tests__` directory.
  *
- * Wire it from a one-line test of the repo's own, so the file stays under the repo's `__tests__` and the repo
- * scopes what the sweep covers. Both halves are silent without it: `unit` is the residual project, so an untiered
- * file runs and passes, and a file outside `__tests__` is collected by nothing at all.
+ * Call it from a one-line test of the repo's own, so that the file stays under the repo's `__tests__` and the repo
+ * scopes what the sweep covers. Without it, a violation of either half goes unreported: `unit` is the residual
+ * project, so an untiered file runs and passes, and a file outside `__tests__` is collected by nothing at all.
  *
- * `excludedBasenames` names directory basenames the sweep prunes at any depth, additive to the ones nmr always
+ * `excludedBasenames` names directory basenames that the sweep prunes at any depth, additive to the ones nmr always
  * prunes. Pass the same array to `defineVitestConfig`'s `testCollectionExclude`, or the sweep and the collection
- * glob describe different trees: a directory pruned here alone still runs the files this suite stopped reporting.
+ * glob describe different trees: Vitest still runs the files in a directory pruned here alone, and this suite no
+ * longer reports them.
+ *
+ * Because untracked paths that git ignores are out of scope for the sweep and the shared configs' collection alike,
+ * a directory that `.gitignore` covers does not need an entry in `excludedBasenames`. Outside a git repository, only
+ * the named directories are pruned.
  */
 export declare function checkTestFileConventions(options?: TestFileConventionsOptions): void;
 /**
- * Sweeps a repo for both halves of the convention, reporting the root it swept alongside what it found.
+ * Sweeps a repo for both halves of the convention, reporting the root that it swept alongside what it found.
  *
- * The root is what makes the result trustworthy, and it is the one thing an assertion cannot check: a sweep
- * started from the directory Vitest supplies covers one package, finds nothing, and passes.
+ * The root makes the result trustworthy, and it is the one thing that an assertion cannot check: A sweep started
+ * from the directory that Vitest supplies covers one package, finds nothing, and passes.
  *
  * @internal - Exported only to enable testing
  */
 export declare function reportTestFileConventions(options?: TestFileConventionsOptions): TestFileConventionsReport;
 export interface TestFileConventionsOptions {
     /**
-     * Directory basenames the sweep prunes at any depth, additive to the ones nmr always prunes. The array a repo
-     * passes here is the array it passes to `defineVitestConfig`'s `testCollectionExclude`.
+     * Directory basenames that the sweep prunes at any depth, additive to the ones nmr always prunes and to the paths
+     * that git ignores. A repo passes the same array here and to `defineVitestConfig`'s `testCollectionExclude`.
      */
     excludedBasenames?: readonly string[];
     /**
@@ -32,7 +37,7 @@ export interface TestFileConventionsOptions {
      */
     rootDir?: string;
 }
-/** What one sweep found, and the root it found it in. Paths are relative to that root and POSIX-separated. */
+/** What one sweep found, and the root in which it found it. Paths are relative to that root and POSIX-separated. */
 export interface TestFileConventionsReport {
     misplacedFiles: string[];
     rootDir: string;

package/dist/esm/tests.js

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { findMisplacedTestFiles, findUntieredTestFiles, TIER_NAMES } from "./tiers.js";
 import { findMonorepoRoot } from "./workspace.js";
-const MISPLACED_REMEDY = 'Every test file must sit under a `__tests__` directory, the only place the shared Vitest config collects from. Move each file below into one, or name its directory in `excludedBasenames`.';
+const MISPLACED_REMEDY = 'Every test file must be under a `__tests__` directory, the only place from which the shared Vitest config collects. Move each file below into one, or name its directory in `excludedBasenames`.';
 const UNTIERED_REMEDY = `Every collected test file must name its isolation tier in the segment before \`.test.\`, one of: ${TIER_NAMES.join(', ')}. Rename each file below to <subject>[.<aspect>].<tier>.test.ts.`;
 const RETIRED_OPTION_KEYS = new Map([['exclude', 'excludedBasenames']]);
 export function checkTestFileConventions(options = {}) {
@@ -11,7 +11,7 @@ export function checkTestFileConventions(options = {}) {
         it('every collected test file names its tier', () => {
             expect(untieredFiles, `${UNTIERED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
         });
-        it('every test file sits under a __tests__ directory', () => {
+        it('every test file is under a __tests__ directory', () => {
             expect(misplacedFiles, `${MISPLACED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
         });
     });