@williamthorsen/nmr 0.38.0 → 0.40.0

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;
@@ -32,9 +32,9 @@ export interface RunStepsResult {
      * What the list's opaque steps produced, absent unless every one of them was captured whole and there was
      * at least one to capture.
      */
-    retained?: RetainedOutput;
+    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/runner.js

@@ -14,7 +14,7 @@ export function resolveInheritedChannel(stream) {
     return hasDescriptor(stream) ? stream.fd : 'pipe';
 }
 export async function runSteps(steps, cwd, options) {
-    const resolved = {
+    const resolvedOptions = {
         ...options,
         quiet: options.quiet === true,
         stdout: options.stdout ?? process.stdout,
@@ -23,7 +23,7 @@ export async function runSteps(steps, cwd, options) {
     const parts = [];
     let isCaptureWhole = true;
     for (const step of steps) {
-        const result = await runStep(step, cwd, resolved);
+        const result = await runStep(step, cwd, resolvedOptions);
         if (step.kind === 'opaque') {
             if (result.stderr === undefined || result.stdout === undefined) {
                 isCaptureWhole = false;
@@ -39,31 +39,31 @@ export async function runSteps(steps, cwd, options) {
     return { exitCode: 0, ...composeRetainedOutput(parts, isCaptureWhole) };
 }
 export async function runCommand(command, cwd, options) {
-    return runSpawned({ args: [], file: command, input: 'inherit', useShell: true }, cwd, options);
+    return runSpawned({ args: [], file: command, input: 'inherit', shouldUseShell: true }, cwd, options);
 }
-async function runSpawned({ args, file, input, useShell }, cwd, options) {
+async function runSpawned({ args, file, input, shouldUseShell }, cwd, options) {
     const quiet = options.quiet === true;
     const stdout = options.stdout ?? process.stdout;
     const stderr = options.stderr ?? process.stderr;
     const env = options.env ?? process.env;
     const child = spawn(file, args, {
-        shell: useShell,
+        shell: shouldUseShell,
         stdio: [input, options.channels.stdout, options.channels.stderr],
         cwd,
         env,
     });
     const stdoutCapture = child.stdout === null ? undefined : captureStream(child.stdout, quiet ? undefined : stdout);
     const stderrCapture = child.stderr === null ? undefined : captureStream(child.stderr, quiet ? undefined : stderr);
-    const completion = await awaitCompletion(child, () => {
+    const commandCompletion = await awaitCompletion(child, () => {
         stdoutCapture?.stopReading();
         stderrCapture?.stopReading();
     });
     stdoutCapture?.detach();
     stderrCapture?.detach();
     const result = {
-        ...completion,
-        stdout: stdoutCapture?.toBuffer(),
-        stderr: stderrCapture?.toBuffer(),
+        ...commandCompletion,
+        stdout: stdoutCapture?.readBuffer(),
+        stderr: stderrCapture?.readBuffer(),
     };
     if (result.outcome === 'spawn-failed') {
         reportError(result.error.message, stderr);
@@ -78,14 +78,14 @@ async function runSpawned({ args, file, input, useShell }, cwd, options) {
 function runStep(step, cwd, options) {
     const { quiet, stderr, stdout } = options;
     if (step.kind === 'opaque') {
-        return runSpawned({ args: [], file: step.command, input: 'inherit', useShell: true }, cwd, {
+        return runSpawned({ args: [], file: step.command, input: 'inherit', shouldUseShell: true }, cwd, {
             ...options,
             channels: { stderr: resolveChannel(stderr, quiet), stdout: resolveChannel(stdout, quiet) },
         });
     }
     const [file, ...args] = step.argv;
     const input = step.shouldWithholdInput === true ? 'ignore' : 'inherit';
-    return runSpawned({ args, file, input, useShell: false }, cwd, {
+    return runSpawned({ args, file, input, shouldUseShell: false }, cwd, {
         ...options,
         quiet: false,
         channels: { stderr: resolveInheritedChannel(stderr), stdout: resolveInheritedChannel(stdout) },
@@ -96,14 +96,14 @@ function composeRetainedOutput(parts, isCaptureWhole) {
         return {};
     }
     return {
-        retained: {
+        retainedOutput: {
             stderr: Buffer.concat(parts.map((part) => part.stderr)),
             stdout: Buffer.concat(parts.map((part) => part.stdout)),
         },
     };
 }
 function captureStream(source, destination) {
-    const retained = createBoundedBuffer();
+    const retainedCopy = createBoundedBuffer();
     let isComplete = true;
     function stopReading() {
         if (destination !== undefined)
@@ -119,9 +119,9 @@ function captureStream(source, destination) {
         destination.on('error', abandon);
         source.pipe(destination, { end: false });
     }
-    source.on('data', (chunk) => retained.append(chunk));
+    source.on('data', (chunk) => retainedCopy.append(chunk));
     return {
-        toBuffer: () => (isComplete ? retained.toBuffer() : undefined),
+        readBuffer: () => (isComplete ? retainedCopy.readBuffer() : undefined),
         detach: () => {
             destination?.off('error', abandon);
         },
@@ -145,11 +145,11 @@ function awaitCompletion(child, stopReading) {
             settle({ outcome: 'spawn-failed', exitCode: 1, error });
         });
         child.on('exit', (code, signal) => {
-            const completion = describeExit(code, signal);
-            exitCompletion = completion;
+            const exitDescription = describeExit(code, signal);
+            exitCompletion = exitDescription;
             graceTimer = setTimeout(() => {
                 stopReading();
-                settle(completion);
+                settle(exitDescription);
             }, PIPE_DRAIN_GRACE_MS);
         });
         child.on('close', () => {

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,69 +20,82 @@ 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 runs against the root registry, where a `-w` anchors it. */
+    /**
+     * 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, 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, workspaceRoot: boolean, shouldDeclineArguments?: boolean): Step;
+export declare function composeNmrStep(element: string, isWorkspaceRoot: boolean, shouldDeclineArguments?: boolean): Step;
 /**
- * Returns the text of the first opaque step that reaches nmr through a shell, or `undefined` when none does.
+ * 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 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 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;
 /**
- * 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: {
@@ -91,9 +104,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

@@ -11,14 +11,17 @@ const QUOTES = new Set(['"', "'"]);
 const SEGMENT_SEPARATORS = new Set([';', '|', '&', '\n', '\r']);
 const SHELL_SAFE_TOKEN = /^[\w@%+=:,./-]+$/;
 const TOKEN_SEPARATORS = new Set([' ', '\t', '\n', '\r']);
-export function composeNmrStep(element, workspaceRoot, shouldDeclineArguments = false) {
-    const flags = workspaceRoot ? ['-w'] : [];
+export function composeNmrStep(element, isWorkspaceRoot, shouldDeclineArguments = false) {
+    const flags = isWorkspaceRoot ? ['-w'] : [];
     return {
         kind: 'structural',
         argv: ['nmr', ...flags, ...tokenize(element)],
         ...(shouldDeclineArguments && { shouldDeclineArguments }),
     };
 }
+export function dropRecursiveSteps(steps) {
+    return steps.filter((step) => readNmrStep(step)?.isRecursive !== true);
+}
 export function findNmrCrossing(steps) {
     for (const step of steps) {
         if (step.kind === 'opaque' && splitSegments(step.command).some((segment) => readNmrTail(segment) !== undefined)) {
@@ -40,12 +43,12 @@ export function readNmrStep(step) {
 export function readSelfReference(options) {
     const { anchoredAtRoot, commandName, script } = options;
     const segments = splitSegments(script).filter((segment) => segment.trim() !== '');
-    const reenters = segments.some((segment) => {
+    const doesReenter = segments.some((segment) => {
         const tail = readNmrTail(segment);
         const target = tail === undefined ? undefined : readNmrTarget(tail);
         return target?.command === commandName && !target.isDelegate && (anchoredAtRoot || !target.isWorkspaceRoot);
     });
-    if (!reenters) {
+    if (!doesReenter) {
         return undefined;
     }
     return segments.length === 1 ? 'sole' : 'chained';
@@ -90,6 +93,7 @@ function readNmrTail(segment) {
 }
 function readNmrTarget(tokens) {
     let isDelegate = false;
+    let isRecursive = false;
     let isWorkspaceRoot = false;
     let index = 0;
     while (index < tokens.length) {
@@ -103,6 +107,7 @@ function readNmrTarget(tokens) {
             case '-R':
             case '--recursive':
                 isDelegate = true;
+                isRecursive = true;
                 index += 1;
                 break;
             case '-w':
@@ -112,7 +117,7 @@ function readNmrTarget(tokens) {
                 break;
             default:
                 if (!token.startsWith('-')) {
-                    return { command: token, isDelegate, isWorkspaceRoot };
+                    return { command: token, isDelegate, isRecursive, isWorkspaceRoot };
                 }
                 index += 1;
         }
@@ -124,49 +129,49 @@ function renderStep(step) {
 }
 function splitSegments(command) {
     const segments = [];
-    let current = '';
+    let currentSegment = '';
     let quote;
     let index = 0;
     while (index < command.length) {
         const char = command[index] ?? '';
         if (quote !== undefined) {
             if (char === '\\' && quote === '"') {
-                current += char + (command[index + 1] ?? '');
+                currentSegment += char + (command[index + 1] ?? '');
                 index += 2;
                 continue;
             }
-            current += char;
+            currentSegment += char;
             if (char === quote)
                 quote = undefined;
             index += 1;
             continue;
         }
         if (char === '\\') {
-            current += char + (command[index + 1] ?? '');
+            currentSegment += char + (command[index + 1] ?? '');
             index += 2;
             continue;
         }
         if (QUOTES.has(char)) {
             quote = char;
-            current += char;
+            currentSegment += char;
             index += 1;
             continue;
         }
         if (SEGMENT_SEPARATORS.has(char)) {
-            if (isRedirectionOperator(char, current, command[index + 1])) {
-                current += char;
+            if (isRedirectionOperator(char, currentSegment, command[index + 1])) {
+                currentSegment += char;
                 index += 1;
                 continue;
             }
             index += command[index + 1] === char ? 2 : 1;
-            segments.push(current);
-            current = '';
+            segments.push(currentSegment);
+            currentSegment = '';
             continue;
         }
-        current += char;
+        currentSegment += char;
         index += 1;
     }
-    segments.push(current);
+    segments.push(currentSegment);
     return segments;
 }
 function tokenize(element) {
@@ -174,47 +179,47 @@ function tokenize(element) {
 }
 function tokenizeSegment(segment) {
     const tokens = [];
-    let current = '';
+    let currentToken = '';
     let quote;
     let index = 0;
     while (index < segment.length) {
         const char = segment[index] ?? '';
         if (quote !== undefined) {
             if (char === '\\' && quote === '"') {
-                current += char + (segment[index + 1] ?? '');
+                currentToken += char + (segment[index + 1] ?? '');
                 index += 2;
                 continue;
             }
-            current += char;
+            currentToken += char;
             if (char === quote)
                 quote = undefined;
             index += 1;
             continue;
         }
         if (char === '\\') {
-            current += char + (segment[index + 1] ?? '');
+            currentToken += char + (segment[index + 1] ?? '');
             index += 2;
             continue;
         }
         if (QUOTES.has(char)) {
             quote = char;
-            current += char;
+            currentToken += char;
             index += 1;
             continue;
         }
         if (TOKEN_SEPARATORS.has(char)) {
-            if (current !== '') {
-                tokens.push(current);
+            if (currentToken !== '') {
+                tokens.push(currentToken);
             }
-            current = '';
+            currentToken = '';
             index += 1;
             continue;
         }
-        current += char;
+        currentToken += char;
         index += 1;
     }
-    if (current !== '') {
-        tokens.push(current);
+    if (currentToken !== '') {
+        tokens.push(currentToken);
     }
     return tokens;
 }

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,40 +1,45 @@
 /**
- * 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.
  *
- * `exclude` names directory basenames 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.
+ * `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: 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({ exclude, rootDir, }?: TestFileConventionsOptions): TestFileConventionsReport;
+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`.
      */
-    exclude?: readonly string[];
+    excludedBasenames?: readonly string[];
     /**
      * The directory to sweep. Defaults to the monorepo root found from the working directory, so one call covers the
      * whole repo from whichever package Vitest started in.
      */
     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 {
-    misplaced: string[];
+    misplacedFiles: string[];
     rootDir: string;
-    untiered: string[];
+    untieredFiles: string[];
 }