@williamthorsen/nmr 0.38.0 → 0.39.0

package/dist/esm/runner.d.ts

@@ -32,7 +32,7 @@ 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. */
 type CommandCompletion = {

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

@@ -25,6 +25,11 @@ export interface NmrStepTarget {
     command: string;
     /** Whether the command is fanned out to other scopes, where 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.
+     */
+    isRecursive: boolean;
     /** Whether the command runs against the root registry, where a `-w` anchors it. */
     isWorkspaceRoot: boolean;
 }
@@ -42,7 +47,14 @@ export type SelfReference = 'chained' | 'sole';
  * `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.
  */
-export declare function composeNmrStep(element: string, workspaceRoot: boolean, shouldDeclineArguments?: boolean): Step;
+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.
+ *
+ * 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.
+ */
+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.
  *

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/tests.d.ts

@@ -6,9 +6,9 @@
  * 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.
  *
- * `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 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.
  */
 export declare function checkTestFileConventions(options?: TestFileConventionsOptions): void;
 /**
@@ -19,13 +19,13 @@ export declare function checkTestFileConventions(options?: TestFileConventionsOp
  *
  * @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`.
      */
-    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.
@@ -34,7 +34,7 @@ export interface TestFileConventionsOptions {
 }
 /** What one sweep found, and the root it found it in. Paths are relative to that root and POSIX-separated. */
 export interface TestFileConventionsReport {
-    misplaced: string[];
+    misplacedFiles: string[];
     rootDir: string;
-    untiered: string[];
+    untieredFiles: string[];
 }

package/dist/esm/tests.js

@@ -1,25 +1,37 @@
 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 `exclude`.';
+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 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 = {}) {
+    assertNoRetiredOptions(options);
     describe('test file conventions', () => {
-        const { misplaced, rootDir, untiered } = reportTestFileConventions(options);
+        const { misplacedFiles, rootDir, untieredFiles } = reportTestFileConventions(options);
         it('every collected test file names its tier', () => {
-            expect(untiered, `${UNTIERED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
+            expect(untieredFiles, `${UNTIERED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
         });
         it('every test file sits under a __tests__ directory', () => {
-            expect(misplaced, `${MISPLACED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
+            expect(misplacedFiles, `${MISPLACED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
         });
     });
 }
-export function reportTestFileConventions({ exclude, rootDir, } = {}) {
+export function reportTestFileConventions(options = {}) {
+    assertNoRetiredOptions(options);
+    const { excludedBasenames, rootDir } = options;
     const sweptRoot = rootDir ?? findMonorepoRoot();
-    const scanOptions = { ...(exclude !== undefined && { exclude }) };
+    const scanOptions = { ...(excludedBasenames !== undefined && { excludedBasenames }) };
     return {
-        misplaced: findMisplacedTestFiles(sweptRoot, scanOptions),
+        misplacedFiles: findMisplacedTestFiles(sweptRoot, scanOptions),
         rootDir: sweptRoot,
-        untiered: findUntieredTestFiles(sweptRoot, scanOptions),
+        untieredFiles: findUntieredTestFiles(sweptRoot, scanOptions),
     };
 }
+function assertNoRetiredOptions(options) {
+    for (const key of Object.keys(options)) {
+        const replacement = RETIRED_OPTION_KEYS.get(key);
+        if (replacement !== undefined) {
+            throw new TypeError(`Invalid test-file-conventions options: \`${key}\` was renamed to \`${replacement}\`.`);
+        }
+    }
+}

package/dist/esm/tiers.d.ts

@@ -50,7 +50,7 @@ export interface TestFileScanOptions {
      * config's `testCollectionExclude`. A directory pruned from the sweep but still collected by Vitest is the
      * silence these sweeps exist to end.
      */
-    exclude?: readonly string[];
+    excludedBasenames?: readonly string[];
 }
 /**
  * The isolation ladder, ordered by the furthest thing a test reaches. A tier names what a test reaches, never how it

package/dist/esm/tiers.js

@@ -23,26 +23,26 @@ export function hasTierInfix(filePath) {
 }
 export const TEST_COLLECTION_EXCLUDE = ['.git', 'coverage', 'dist', 'node_modules'];
 export const TIER_NAMES = ['unit', 'tool', 'localhost', 'remote'];
-function collectTestFiles(dir, relativeDir, inTestDir, context) {
+function collectTestFiles(dir, relativeDir, isInTestDir, context) {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
         const relativePath = relativeDir === '' ? entry.name : `${relativeDir}/${entry.name}`;
         if (entry.isDirectory()) {
             if (context.pruned.has(entry.name))
                 continue;
-            collectTestFiles(path.join(dir, entry.name), relativePath, inTestDir || entry.name === TEST_DIR, context);
+            collectTestFiles(path.join(dir, entry.name), relativePath, isInTestDir || entry.name === TEST_DIR, context);
         }
-        else if (inTestDir !== context.misplaced && TEST_FILE_PATTERN.test(entry.name)) {
-            context.found.push(relativePath);
+        else if (isInTestDir !== context.misplaced && TEST_FILE_PATTERN.test(entry.name)) {
+            context.foundPaths.push(relativePath);
         }
     }
 }
-function walkTestFiles(rootDir, { exclude = [] }, misplaced) {
+function walkTestFiles(rootDir, { excludedBasenames = [] }, misplaced) {
     const context = {
-        found: [],
+        foundPaths: [],
         misplaced,
-        pruned: new Set([...TEST_COLLECTION_EXCLUDE, ...exclude]),
+        pruned: new Set([...TEST_COLLECTION_EXCLUDE, ...excludedBasenames]),
     };
     collectTestFiles(rootDir, '', false, context);
-    return context.found.toSorted();
+    return context.foundPaths.toSorted();
 }

package/dist/esm/verbosity.d.ts

@@ -38,8 +38,8 @@ export interface ResolveVerbosityOptions {
     /** Read for the detection level, and for that alone: the variable this module owns arrives as `envVerbosity`. */
     env: NodeJS.ProcessEnv;
     envVerbosity: CommandVerbosity | undefined;
+    hasQuietFlag: boolean;
     output: OutputConfig | undefined;
-    quietFlag: boolean;
 }
 /**
  * Resolves the verbosity this process runs at: the flag, then the environment, then the repo's config, then

package/dist/esm/verbosity.js

@@ -9,18 +9,18 @@ export function isCommandVerbosity(value) {
     return names.includes(value);
 }
 export function readVerbosityEnv(env) {
-    const raw = env[COMMAND_VERBOSITY_ENV_VAR];
-    if (raw === undefined || raw === '') {
+    const rawValue = env[COMMAND_VERBOSITY_ENV_VAR];
+    if (rawValue === undefined || rawValue === '') {
         return { ok: true };
     }
-    if (!isCommandVerbosity(raw)) {
-        return { ok: false, error: formatVerbosityRejection(COMMAND_VERBOSITY_ENV_VAR, raw) };
+    if (!isCommandVerbosity(rawValue)) {
+        return { ok: false, error: formatVerbosityRejection(COMMAND_VERBOSITY_ENV_VAR, rawValue) };
     }
-    return { ok: true, verbosity: raw };
+    return { ok: true, verbosity: rawValue };
 }
 export function resolveVerbosity(options) {
-    const { env, envVerbosity, output, quietFlag } = options;
-    if (quietFlag)
+    const { env, envVerbosity, hasQuietFlag, output } = options;
+    if (hasQuietFlag)
         return 'quiet';
     if (envVerbosity !== undefined)
         return envVerbosity;

package/dist/esm/verdict.d.ts

@@ -11,7 +11,14 @@ import type { ReportFormat } from './report-format.js';
  * truncation point from one machine to the next. The ceiling governs pipes: a terminal offers no such
  * guarantee at any size.
  */
-export declare const VERDICT_LINE_LIMIT = 512;
+export declare const VERDICT_LINE_LIMIT_BYTES = 512;
+/**
+ * Why a command ran nothing, which the `no-op` outcome carries and `--json` serializes.
+ *
+ * `empty-workspace` and `empty-override` both leave a chain with no step in it, so the reason is what tells
+ * a command emptied by the workspace apart from one emptied by an override.
+ */
+export type NoOpReason = 'empty-override' | 'empty-workspace' | 'noop-override';
 /**
  * What a command nmr ran came to, holding the facts a reporting line is rendered from rather than the line
  * itself, so a machine-readable rendering spends the same record a human-readable one does.
@@ -47,7 +54,7 @@ export type VerdictOutcome = {
     replay?: ReplayLine[];
 } | {
     outcome: 'no-op';
-    reason: 'empty-override' | 'noop-override';
+    reason: NoOpReason;
 });
 /**
  * Renders a verdict as the line nmr reports it on, without the newline that terminates it.