@williamthorsen/nmr 0.38.0 → 0.40.0

package/dist/esm/runCli.js

@@ -18,14 +18,15 @@ 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 { resolveChannel, runSteps } from "./runner.js";
-import { composeNmrStep, findNmrCrossing, renderChain } from "./steps.js";
+import { composeNmrStep, dropRecursiveSteps, findNmrCrossing, 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 } from "./workspace.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 NAME_CEILING = 10;
+const RECURSIVE_REJECTION = '-R/--recursive did not match any workspace:';
+const LIST_CEILING = 10;
 const NAMED_ESCAPES = new Map([
     ['\n', String.raw `\n`],
     ['\r', String.raw `\r`],
@@ -39,56 +40,56 @@ export async function runCli(options) {
         reportError(parseResult.error, stderr);
         return { exitCode: 1 };
     }
-    const { parsed } = parseResult;
-    const inherited = readPresentation({
+    const { parsedArgs } = parseResult;
+    const presentationRead = readPresentation({
         env,
-        flagValue: parsed.outputStyle,
+        flagValue: parsedArgs.outputStyle,
         stderrIsTty: isTerminalStream(stderr),
         stdoutIsTty: isTerminalStream(stdout),
     });
-    if (!inherited.ok) {
-        reportError(inherited.error, stderr);
+    if (!presentationRead.ok) {
+        reportError(presentationRead.error, stderr);
         return { exitCode: 1 };
     }
-    const { styles } = inherited;
-    if (parsed.version) {
+    const { styles } = presentationRead;
+    if (parsedArgs.shouldShowVersion) {
         stdout.write(`${VERSION}\n`);
         return { exitCode: 0 };
     }
     const context = await resolveContext(cwd);
-    const format = resolveReportFormat({ envFormat: inherited.format, jsonFlag: parsed.json });
+    const format = resolveReportFormat({ envFormat: presentationRead.format, hasJsonFlag: parsedArgs.shouldEmitJson });
     const verbosity = resolveReportingVerbosity({
         env,
-        envVerbosity: inherited.verbosity,
+        envVerbosity: presentationRead.verbosity,
         format,
         output: context.config.output,
-        quietFlag: parsed.quiet,
+        hasQuietFlag: parsedArgs.quiet,
     });
     const quiet = verbosity === 'quiet';
-    const useRoot = parsed.workspaceRoot || context.isRoot;
-    const anchorDir = useRoot ? context.monorepoRoot : (context.packageDir ?? context.monorepoRoot);
-    if (parsed.help || !parsed.command) {
-        stdout.write(`${generateHelp(context.config, anchorDir, useRoot)}\n`);
+    const shouldUseRoot = parsedArgs.isWorkspaceRoot || context.isRoot;
+    const anchorDir = shouldUseRoot ? context.monorepoRoot : (context.packageDir ?? context.monorepoRoot);
+    if (parsedArgs.shouldShowHelp || !parsedArgs.command) {
+        stdout.write(`${generateHelp(context.config, anchorDir, shouldUseRoot)}\n`);
         return { exitCode: 0 };
     }
-    const { command } = parsed;
+    const { command } = parsedArgs;
     const scope = path.basename(anchorDir);
     const snapshot = openGate({
         command,
         config: context.config,
         env,
         monorepoRoot: context.monorepoRoot,
-        passthrough: parsed.passthrough,
+        passthrough: parsedArgs.passthrough,
         stderr,
         style: styles.stderr,
     });
-    const noCache = parsed.noCache || env[NO_CACHE_ENV_VAR] === '1';
+    const shouldBypassCache = parsedArgs.shouldBypassCache || env[NO_CACHE_ENV_VAR] === '1';
     const runId = resolveRunId(env);
     const childEnv = buildChildEnv({
         env,
         format,
-        noCache,
-        passthrough: parsed.passthrough,
+        shouldBypassCache,
+        passthrough: parsedArgs.passthrough,
         runId,
         snapshot,
         styles,
@@ -100,56 +101,57 @@ export async function runCli(options) {
         stderr,
         env: childEnv,
     };
-    const delegation = composeDelegation({ childEnv, command, parsed });
+    const delegation = composeDelegation({ childEnv, command, parsedArgs });
     if (delegation !== undefined) {
-        return runDelegation({ context, delegation, parsed, runOptions, stderr });
+        return runDelegation({ context, delegation, parsedArgs, runOptions, stderr });
     }
-    const registry = useRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config);
+    const registry = shouldUseRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config);
     assertNoSelfReference({
         anchorDir,
         command,
-        isReading: parsed.log,
+        isReading: parsedArgs.shouldPrintLog,
+        isWorkspaceRoot: parsedArgs.isWorkspaceRoot,
         monorepoRoot: context.monorepoRoot,
         registry,
-        workspaceRoot: parsed.workspaceRoot,
     });
-    const resolved = resolveScript(command, registry, anchorDir, parsed.workspaceRoot);
-    if (!resolved) {
+    const resolvedScript = resolveScript(command, registry, anchorDir, parsedArgs.isWorkspaceRoot);
+    if (!resolvedScript) {
         if (env[RUN_IF_PRESENT_ENV_VAR] === '1') {
             return { exitCode: 0 };
         }
         reportError(`Unknown command: ${command}`, stderr);
         return { exitCode: 1 };
     }
-    const resolvedCommand = renderChain(resolved.steps);
-    const noOpReason = findNoOpReason(resolvedCommand);
-    if (noOpReason !== undefined && !parsed.log) {
+    const { isEmptiedByWorkspace, steps: runnableSteps } = readRunnableSteps(resolvedScript, context.workspacePackageDirs);
+    const resolvedCommand = renderChain(runnableSteps);
+    const noOpReason = findNoOpReason(resolvedCommand, isEmptiedByWorkspace);
+    if (noOpReason !== undefined && !parsedArgs.shouldPrintLog) {
         reportVerdict({ command, scope, outcome: 'no-op', reason: noOpReason }, stdout, format, styles.stdout);
         return { exitCode: 0 };
     }
-    const substitutedSteps = applyDevBinToSteps(resolved.steps, context.config.devBin, context.monorepoRoot);
+    const substitutedSteps = applyDevBinToSteps(runnableSteps, context.config.devBin, context.monorepoRoot);
     const substitutedCommand = renderChain(substitutedSteps);
-    const bound = bindPassthrough(substitutedSteps, parsed.passthrough, command);
-    if (!bound.ok) {
-        reportError(bound.error, stderr);
+    const bindResult = bindPassthrough(substitutedSteps, parsedArgs.passthrough, command);
+    if (!bindResult.ok) {
+        reportError(bindResult.error, stderr);
         return { exitCode: 1 };
     }
-    const mainSteps = bound.steps;
+    const mainSteps = bindResult.steps;
     const isHookInvocation = isHookName(command);
     const fullSteps = isHookInvocation
         ? mainSteps
-        : wrapWithHooks(command, mainSteps, registry, anchorDir, parsed.workspaceRoot);
+        : wrapWithHooks(command, mainSteps, registry, anchorDir, parsedArgs.isWorkspaceRoot);
     const fullCommand = renderChain(fullSteps);
     reportNmrCrossing({
         config: context.config,
-        isReading: parsed.log,
+        isReading: parsedArgs.shouldPrintLog,
+        isWorkspaceRoot: parsedArgs.isWorkspaceRoot,
         monorepoRoot: context.monorepoRoot,
         registry,
-        resolved,
+        resolvedScript,
+        shouldUseRoot,
         stderr,
         style: styles.stderr,
-        useRoot,
-        workspaceRoot: parsed.workspaceRoot,
     });
     const key = resolveCacheKey({
         anchorDir,
@@ -161,7 +163,7 @@ export async function runCli(options) {
         stderr,
         substitution: substitutedCommand === resolvedCommand ? undefined : substitutedCommand,
     });
-    if (parsed.log) {
+    if (parsedArgs.shouldPrintLog) {
         return reportRecording({
             anchorDir,
             command,
@@ -186,11 +188,11 @@ export async function runCli(options) {
         env,
         key,
         monorepoRoot: context.monorepoRoot,
-        noCache,
-        overrideNotice: formatOverrideNotice(resolved, registry, command, anchorDir, quiet, styles.stdout),
+        overrideNotice: formatOverrideNotice(resolvedScript, registry, command, anchorDir, quiet, styles.stdout),
         ownSteps: mainSteps,
         runId,
         runOptions,
+        shouldBypassCache,
         snapshot,
         stderr,
         stdout,
@@ -199,23 +201,23 @@ export async function runCli(options) {
     return { exitCode };
 }
 const BOOLEAN_FLAGS = new Map([
-    ['-?', 'help'],
-    ['--help', 'help'],
-    ['--json', 'json'],
-    ['--log', 'log'],
-    ['--no-cache', 'noCache'],
+    ['-?', 'shouldShowHelp'],
+    ['--help', 'shouldShowHelp'],
+    ['--json', 'shouldEmitJson'],
+    ['--log', 'shouldPrintLog'],
+    ['--no-cache', 'shouldBypassCache'],
     ['-q', 'quiet'],
     ['--quiet', 'quiet'],
     ['-R', 'recursive'],
     ['--recursive', 'recursive'],
-    ['-V', 'version'],
-    ['--version', 'version'],
-    ['-w', 'workspaceRoot'],
-    ['--workspace-root', 'workspaceRoot'],
+    ['-V', 'shouldShowVersion'],
+    ['--version', 'shouldShowVersion'],
+    ['-w', 'isWorkspaceRoot'],
+    ['--workspace-root', 'isWorkspaceRoot'],
 ]);
 function buildChildEnv(options) {
-    const { env, format, noCache, passthrough, runId, snapshot, styles, verbosity } = options;
-    const bypassesCache = noCache || passthrough.length > 0;
+    const { env, format, passthrough, runId, shouldBypassCache, snapshot, styles, verbosity } = options;
+    const bypassesCache = shouldBypassCache || passthrough.length > 0;
     return {
         ...env,
         ...(snapshot !== undefined && { [TREE_SNAPSHOT_ENV_VAR]: encodeTreeSnapshot(snapshot) }),
@@ -242,41 +244,41 @@ function bindPassthrough(steps, passthrough, command) {
         }
         return step.kind === 'structural'
             ? { ...step, argv: [...step.argv, ...passthrough] }
-            : { kind: 'opaque', command: `${step.command} ${passthrough.map(shellQuote).join(' ')}` };
+            : { kind: 'opaque', command: `${step.command} ${passthrough.map(quoteForShell).join(' ')}` };
     });
     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) {
-    const { childEnv, command, parsed } = options;
+    const { childEnv, command, parsedArgs } = options;
     let scope;
-    let runIfPresent = parsed.log;
-    if (parsed.filter) {
-        scope = ['--filter', parsed.filter];
+    let shouldRunIfPresent = parsedArgs.shouldPrintLog;
+    if (parsedArgs.filter) {
+        scope = ['--filter', parsedArgs.filter];
     }
-    else if (parsed.recursive) {
+    else if (parsedArgs.recursive) {
         scope = ['--recursive'];
-        runIfPresent = true;
+        shouldRunIfPresent = true;
     }
     if (scope === undefined) {
         return undefined;
     }
-    const flags = parsed.log ? ['--log'] : [];
+    const flags = parsedArgs.shouldPrintLog ? ['--log'] : [];
     return {
-        env: runIfPresent ? { ...childEnv, [RUN_IF_PRESENT_ENV_VAR]: '1' } : childEnv,
+        env: shouldRunIfPresent ? { ...childEnv, [RUN_IF_PRESENT_ENV_VAR]: '1' } : childEnv,
         step: {
             kind: 'structural',
-            argv: ['pnpm', ...scope, 'exec', 'nmr', ...flags, command, ...parsed.passthrough],
+            argv: ['pnpm', ...scope, 'exec', 'nmr', ...flags, command, ...parsedArgs.passthrough],
         },
     };
 }
 async function composeRetention(options) {
-    const { anchorDir, command, key, retained, runId } = options;
-    if (retained !== undefined) {
-        const excerpt = deriveExcerpt(retained.stdout.toString('utf8')) ?? deriveExcerpt(retained.stderr.toString('utf8'));
+    const { anchorDir, command, key, retainedOutput, runId } = options;
+    if (retainedOutput !== undefined) {
+        const excerpt = deriveExcerpt(retainedOutput.stdout.toString('utf8')) ?? deriveExcerpt(retainedOutput.stderr.toString('utf8'));
         if (excerpt === undefined) {
             return undefined;
         }
@@ -292,7 +294,7 @@ async function composeRetention(options) {
     return replay.length === 0 ? undefined : { key, replay, runId };
 }
 function describeCrossingRemedy(options) {
-    const { crossing, monorepoRoot, origin, registry, workspaceRoot } = options;
+    const { crossingStep, isWorkspaceRoot, monorepoRoot, origin, registry } = options;
     const configSite = path.relative(monorepoRoot, resolveConfigPath(monorepoRoot));
     switch (origin.tier) {
         case 'default':
@@ -307,131 +309,188 @@ function describeCrossingRemedy(options) {
             };
         case 'package':
             return {
-                remedy: formatPackageRemedy({ configSite, crossing, key: origin.key, registry, workspaceRoot }),
+                remedy: formatPackageRemedy({ configSite, crossingStep, isWorkspaceRoot, key: origin.key, registry }),
                 subject: `${path.relative(monorepoRoot, origin.file)}: \`scripts.${origin.key}\``,
             };
         default: {
-            const unhandled = origin;
-            throw new Error(`Unhandled script origin: ${JSON.stringify(unhandled)}`);
+            const unhandledOrigin = origin;
+            throw new Error(`Unhandled script origin: ${JSON.stringify(unhandledOrigin)}`);
         }
     }
 }
 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`;
 }
-function describeOrigin(origin, config, useRoot) {
+function describeOrigin(origin, config, shouldUseRoot) {
     if (origin.tier === 'package') {
         return origin;
     }
-    const field = useRoot ? 'rootScripts' : 'workspaceScripts';
+    const field = shouldUseRoot ? 'rootScripts' : 'workspaceScripts';
     const configScripts = config[field];
     return configScripts !== undefined && Object.hasOwn(configScripts, origin.key)
         ? { tier: 'config', field, key: origin.key }
         : { tier: 'default', key: origin.key };
 }
 function escapeControlCharacters(text) {
-    let escaped = text;
+    let escapedText = text;
     for (const [char, escape] of NAMED_ESCAPES) {
-        escaped = escaped.split(char).join(escape);
+        escapedText = escapedText.split(char).join(escape);
     }
-    return escaped;
+    return escapedText;
 }
 function formatNmrCrossingWarning(options) {
     const { remedy, subject } = describeCrossingRemedy(options);
     return (`${STATUS_GLYPHS[options.style].warning.text} ${subject} reaches nmr through a shell ` +
-        `(\`${escapeControlCharacters(options.crossing)}\`), ${CROSSING_CONSEQUENCE} ${remedy}`);
+        `(\`${escapeControlCharacters(options.crossingStep)}\`), ${CROSSING_CONSEQUENCE} ${remedy}`);
 }
-function formatOverrideNotice(resolved, registry, command, anchorDir, quiet, style) {
+function formatOverrideNotice(resolvedScript, registry, command, anchorDir, quiet, style) {
     const registryEntry = Object.hasOwn(registry, command) ? registry[command] : undefined;
-    if (quiet || resolved.origin.tier !== 'package' || registryEntry === undefined) {
+    if (quiet || resolvedScript.origin.tier !== 'package' || registryEntry === undefined) {
         return undefined;
     }
-    const notice = `${path.basename(anchorDir)}: Using override script: ${renderChain(resolved.steps)}`;
+    const notice = `${path.basename(anchorDir)}: Using override script: ${renderChain(resolvedScript.steps)}`;
     return `${formatGlyphLine(NMR_GLYPHS, style, 'package', notice)}\n`;
 }
 function formatSelfReferenceRemedy(options) {
-    const { command, monorepoRoot, registry, script, workspaceRoot } = 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, crossing: script, key: command, registry, workspaceRoot });
+    return formatPackageRemedy({ configSite, crossingStep: script, isWorkspaceRoot, key: command, registry });
 }
 function formatPackageRemedy(options) {
-    const { configSite, crossing, key, registry, workspaceRoot } = 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, workspaceRoot));
-    if (registryChain === crossing) {
+    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(parsed) {
-    if (parsed.log && parsed.command === undefined && !parsed.help && !parsed.version) {
+function findArgError(parsedArgs) {
+    if (parsedArgs.shouldPrintLog &&
+        parsedArgs.command === undefined &&
+        !parsedArgs.shouldShowHelp &&
+        !parsedArgs.shouldShowVersion) {
         return '--log requires a command name: `nmr --log <command>`';
     }
     return undefined;
 }
 function findEmptySelectionRefusal(options) {
-    const { context, parsed, selection } = options;
-    if (parsed.filter !== undefined) {
+    const { context, parsedArgs, selection } = options;
+    const isPackageless = context.workspacePackageDirs.length === 0;
+    if (parsedArgs.filter !== undefined) {
         if (selection !== 'empty') {
             return undefined;
         }
-        return formatEmptyFilterError(parsed.filter, readWorkspacePackageNames(context.workspacePackageDirs));
+        if (isPackageless) {
+            return `${formatFilterRejection(parsedArgs.filter)} ${describeEmptyWorkspace(context.monorepoRoot)}`;
+        }
+        return formatEmptyFilterError(parsedArgs.filter, readWorkspacePackageNames(context.workspacePackageDirs));
     }
-    return context.workspacePackageDirs.length === 0 ? formatEmptyWorkspaceError() : undefined;
+    return isPackageless ? `${RECURSIVE_REJECTION} ${describeEmptyWorkspace(context.monorepoRoot)}` : undefined;
 }
 function formatEmptyFilterError(pattern, names) {
-    const rejection = `-F/--filter matched no workspace: \`${pattern}\`.`;
+    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)}`);
 }
-function formatEmptyWorkspaceError() {
-    return ('-R/--recursive matched no workspace: pnpm-workspace.yaml declares no package directory, ' +
-        'so there is no scope to fan out to.');
+function describeEmptyWorkspace(monorepoRoot) {
+    const resolution = resolveWorkspace(monorepoRoot);
+    if (resolution.kind !== 'empty') {
+        return `pnpm-workspace.yaml at ${monorepoRoot} resolves differently now than it did when the run started.`;
+    }
+    const { cause, patterns } = resolution;
+    const declaredClause = describeDeclaredPatterns(patterns);
+    switch (cause) {
+        case 'all-excluded':
+            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 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 contains one.');
+        case 'no-packages-list':
+            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 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} 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: {
+            const unhandledCause = cause;
+            throw new Error(`Unhandled empty-workspace cause: ${String(unhandledCause)}`);
+        }
+    }
+}
+function describeDeclaredPatterns(patterns) {
+    const quotablePatterns = patterns.filter((pattern) => pattern.trim() !== '');
+    const emptiedCount = patterns.length - quotablePatterns.length;
+    if (emptiedCount === 0) {
+        return `declares ${renderQuotedList(patterns)}`;
+    }
+    const emptiedClause = `${emptiedCount} ${emptiedCount === 1 ? 'entry' : 'entries'} that YAML left empty`;
+    return quotablePatterns.length === 0
+        ? `declares ${emptiedClause}`
+        : `declares ${renderQuotedList(quotablePatterns)}, beside ${emptiedClause}`;
+}
+function formatFilterRejection(pattern) {
+    return `-F/--filter did not match any workspace: \`${pattern}\`.`;
 }
 function suggestWorkspaceNames(pattern, names) {
     if (names.length === 0) {
         return '';
     }
-    const containing = names.filter((name) => name.toLowerCase().includes(pattern.toLowerCase()));
-    if (containing.length > 0) {
-        return ` Did you mean ${renderNames(containing)}?`;
+    const containingNames = names.filter((name) => name.toLowerCase().includes(pattern.toLowerCase()));
+    if (containingNames.length > 0) {
+        return ` Did you mean ${renderQuotedList(containingNames)}?`;
     }
-    const closest = findClosestName(pattern, names);
-    if (closest !== undefined) {
-        return ` Did you mean \`${closest}\`?`;
+    const closestName = findClosestName(pattern, names);
+    if (closestName !== undefined) {
+        return ` Did you mean \`${closestName}\`?`;
     }
-    return ` The workspace declares ${renderNames(names)}.`;
+    return ` The workspace declares ${renderQuotedList(names)}.`;
 }
-function renderNames(names) {
-    const shown = names
-        .slice(0, NAME_CEILING)
-        .map((name) => `\`${name}\``)
+function renderQuotedList(items) {
+    const shownItems = items
+        .slice(0, LIST_CEILING)
+        .map((item) => `\`${item}\``)
         .join(', ');
-    const remainder = names.length - NAME_CEILING;
-    return remainder > 0 ? `${shown}, and ${remainder} more` : shown;
+    const remainder = items.length - LIST_CEILING;
+    return remainder > 0 ? `${shownItems}, and ${remainder} more` : shownItems;
 }
-function findNoOpReason(resolvedCommand) {
+function findNoOpReason(resolvedCommand, isEmptiedByWorkspace) {
+    if (isEmptiedByWorkspace) {
+        return 'empty-workspace';
+    }
     if (resolvedCommand === '') {
         return 'empty-override';
     }
@@ -441,7 +500,7 @@ function findNoOpReason(resolvedCommand) {
     return undefined;
 }
 function assertNoSelfReference(options) {
-    const { anchorDir, command, isReading, monorepoRoot, registry, workspaceRoot } = options;
+    const { anchorDir, command, isReading, isWorkspaceRoot, monorepoRoot, registry } = options;
     if (isReading) {
         return;
     }
@@ -449,19 +508,19 @@ function assertNoSelfReference(options) {
     if (script === undefined) {
         return;
     }
-    const remedy = formatSelfReferenceRemedy({ command, monorepoRoot, registry, script, workspaceRoot });
+    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, workspaceRoot) {
+function hasRunnableHook(hookName, registry, anchorDir, isWorkspaceRoot) {
     if (findChainedSelfReference(anchorDir, hookName) !== undefined) {
         return true;
     }
-    const resolved = resolveScript(hookName, registry, anchorDir, workspaceRoot);
-    if (!resolved)
+    const resolvedScript = resolveScript(hookName, registry, anchorDir, isWorkspaceRoot);
+    if (!resolvedScript)
         return false;
-    const chain = renderChain(resolved.steps);
+    const chain = renderChain(resolvedScript.steps);
     return chain !== '' && chain !== ':';
 }
 async function lookUpRecordedPass(options) {
@@ -475,14 +534,14 @@ async function lookUpRecordedPass(options) {
         writeDebugNote(`running ${command}: the tree or its inputs changed since the last pass`, env, stderr);
         return undefined;
     }
-    const [missing] = buildOutput.missing;
-    if (missing !== undefined) {
-        writeDebugNote(`running ${command}: ${missing} has no build output`, env, stderr);
+    const [missingPackage] = buildOutput.missingPackages;
+    if (missingPackage !== undefined) {
+        writeDebugNote(`running ${command}: ${missingPackage} does not have build output`, env, stderr);
         return undefined;
     }
-    const stale = findStaleBuildOutput(entry.buildDigests, buildOutput.digests);
-    if (stale !== undefined) {
-        writeDebugNote(`running ${command}: ${stale}'s build output came from a different tree`, env, stderr);
+    const stalePackage = findStaleBuildOutput(entry.buildDigests, buildOutput.digests);
+    if (stalePackage !== undefined) {
+        writeDebugNote(`running ${command}: ${stalePackage}'s build output came from a different tree`, env, stderr);
         return undefined;
     }
     return {
@@ -512,60 +571,60 @@ function openGate(options) {
     return snapshot.snapshot;
 }
 function parseArgs(args) {
-    const parsed = {
-        json: false,
-        log: false,
-        noCache: false,
+    const parsedArgs = {
+        isWorkspaceRoot: false,
         quiet: false,
         recursive: false,
-        workspaceRoot: false,
-        help: false,
-        version: false,
+        shouldBypassCache: false,
+        shouldEmitJson: false,
+        shouldPrintLog: false,
+        shouldShowHelp: false,
+        shouldShowVersion: false,
         passthrough: [],
     };
-    let i = 0;
-    while (i < args.length) {
-        const arg = args[i];
+    let index = 0;
+    while (index < args.length) {
+        const arg = args[index];
         if (arg === undefined)
             break;
         if (arg === '-F' || arg === '--filter') {
-            i++;
-            const filterValue = args[i];
+            index++;
+            const filterValue = args[index];
             if (!filterValue) {
                 return { ok: false, error: '-F/--filter requires a pattern argument' };
             }
-            parsed.filter = filterValue;
-            i++;
+            parsedArgs.filter = filterValue;
+            index++;
             continue;
         }
         const booleanFlag = BOOLEAN_FLAGS.get(arg);
         if (booleanFlag !== undefined) {
-            parsed[booleanFlag] = true;
-            i++;
+            parsedArgs[booleanFlag] = true;
+            index++;
             continue;
         }
-        const styleArgument = readOutputStyleArgument(args, i);
+        const styleArgument = readOutputStyleArgument(args, index);
         if (styleArgument !== undefined) {
             if (!styleArgument.ok) {
                 return styleArgument;
             }
-            parsed.outputStyle = styleArgument.value;
-            i += styleArgument.consumed;
+            parsedArgs.outputStyle = styleArgument.value;
+            index += styleArgument.consumedCount;
             continue;
         }
-        parsed.command = arg;
-        parsed.passthrough = args.slice(i + 1);
+        parsedArgs.command = arg;
+        parsedArgs.passthrough = args.slice(index + 1);
         break;
     }
-    const error = findArgError(parsed);
-    return error === undefined ? { ok: true, parsed } : { ok: false, error };
+    const error = findArgError(parsedArgs);
+    return error === undefined ? { ok: true, parsedArgs } : { ok: false, error };
 }
 async function reportRecording(options) {
     const { command, config, scope, styles } = options;
     const lookup = await resolveRecording({
         anchorDir: options.anchorDir,
         command,
-        current: {
+        currentIdentity: {
             commandString: options.commandString,
             nmrVersion: VERSION,
             nodeVersion: CURRENT_RUNTIME.nodeVersion,
@@ -592,9 +651,9 @@ function readPresentation(options) {
     if (!format.ok) {
         return format;
     }
-    const { invalid, styles } = resolveOutputStyles(options);
-    if (invalid !== undefined) {
-        return { ok: false, error: describeInvalidOutputStyle(invalid) };
+    const { invalid: invalidStyle, styles } = resolveOutputStyles(options);
+    if (invalidStyle !== undefined) {
+        return { ok: false, error: describeInvalidOutputStyle(invalidStyle) };
     }
     return { ok: true, format: format.format, styles, verbosity: verbosity.verbosity };
 }
@@ -608,20 +667,27 @@ function readOutputStyleArgument(args, index) {
     if (!value) {
         return { ok: false, error: `${OUTPUT_STYLE_FLAG} requires a value argument: auto, plain, or rich` };
     }
-    return { ok: true, value, consumed: assignment === undefined ? 2 : 1 };
+    return { ok: true, value, consumedCount: assignment === undefined ? 2 : 1 };
+}
+function readRunnableSteps(resolvedScript, workspacePackageDirs) {
+    if (workspacePackageDirs.length > 0) {
+        return { isEmptiedByWorkspace: false, steps: resolvedScript.steps };
+    }
+    const steps = dropRecursiveSteps(resolvedScript.steps);
+    return { isEmptiedByWorkspace: steps.length === 0 && resolvedScript.steps.length > 0, steps };
 }
 function reportNmrCrossing(options) {
-    const crossing = findNmrCrossing(options.resolved.steps);
-    if (options.isReading || crossing === undefined) {
+    const crossingStep = findNmrCrossing(options.resolvedScript.steps);
+    if (options.isReading || crossingStep === undefined) {
         return;
     }
     const warning = formatNmrCrossingWarning({
-        crossing,
+        crossingStep,
+        isWorkspaceRoot: options.isWorkspaceRoot,
         monorepoRoot: options.monorepoRoot,
-        origin: describeOrigin(options.resolved.origin, options.config, options.useRoot),
+        origin: describeOrigin(options.resolvedScript.origin, options.config, options.shouldUseRoot),
         registry: options.registry,
         style: options.style,
-        workspaceRoot: options.workspaceRoot,
     });
     options.stderr.write(`${warning}\n`);
 }
@@ -637,24 +703,24 @@ function resolveReportingVerbosity(options) {
 }
 async function recordPass(options) {
     const { anchorDir, command, env, monorepoRoot, snapshot, stderr } = options;
-    const current = resolveTreeSnapshot({ monorepoRoot, env: {} });
-    if (!current.ok) {
-        writeDebugNote(`not recording ${command}: ${current.reason}`, env, stderr);
+    const currentRead = resolveTreeSnapshot({ monorepoRoot, env: {} });
+    if (!currentRead.ok) {
+        writeDebugNote(`not recording ${command}: ${currentRead.reason}`, env, stderr);
         return;
     }
-    if (current.snapshot.hash !== snapshot.hash) {
+    if (currentRead.snapshot.hash !== snapshot.hash) {
         writeDebugNote(`not recording ${command}: the tree changed while it ran`, env, stderr);
         return;
     }
     const output = await readBuildOutputState(monorepoRoot, options.config);
-    const [missing] = output.missing;
-    if (missing !== undefined) {
-        writeDebugNote(`not recording ${command}: ${missing} has no build output`, env, stderr);
+    const [missingPackage] = output.missingPackages;
+    if (missingPackage !== undefined) {
+        writeDebugNote(`not recording ${command}: ${missingPackage} does not have build output`, env, stderr);
         return;
     }
-    const changed = findStaleBuildOutput(options.buildOutputBefore.digests, output.digests);
-    if (changed !== undefined) {
-        writeDebugNote(`not recording ${command}: ${changed}'s build output changed while it ran`, env, stderr);
+    const changedPackage = findStaleBuildOutput(options.buildOutputBefore.digests, output.digests);
+    if (changedPackage !== undefined) {
+        writeDebugNote(`not recording ${command}: ${changedPackage}'s build output changed while it ran`, env, stderr);
         return;
     }
     const retention = await composeRetention({
@@ -662,13 +728,13 @@ async function recordPass(options) {
         command,
         key: options.retentionKey,
         monorepoRoot,
-        retained: options.retained,
+        retainedOutput: options.retainedOutput,
         runId: options.runId,
         steps: options.ownSteps,
         treeHash: snapshot.hash,
     });
     const ref = { anchorDir, command, monorepoRoot };
-    const transcript = options.retained === undefined ? undefined : composeTranscript(options.retained);
+    const transcript = options.retainedOutput === undefined ? undefined : composeTranscript(options.retainedOutput);
     try {
         await recordTranscript(ref, transcript);
         await writeCheckCacheEntry({
@@ -721,14 +787,14 @@ function resolveCacheKey(options) {
     return result.key;
 }
 async function runDelegation(options) {
-    const { context, delegation, parsed, runOptions, stderr } = options;
-    const selection = parsed.filter === undefined ? undefined : readFilterSelection(parsed.filter, context.monorepoRoot);
-    const refusal = findEmptySelectionRefusal({ context, parsed, selection });
+    const { context, delegation, parsedArgs, runOptions, stderr } = options;
+    const selection = parsedArgs.filter === undefined ? undefined : readFilterSelection(parsedArgs.filter, context.monorepoRoot);
+    const refusal = findEmptySelectionRefusal({ context, parsedArgs, selection });
     if (refusal !== undefined) {
         reportError(refusal, stderr);
         return { exitCode: 1 };
     }
-    const shouldWithholdInput = parsed.filter === undefined || selection === 'multiple';
+    const shouldWithholdInput = parsedArgs.filter === undefined || selection === 'multiple';
     const step = shouldWithholdInput ? { ...delegation.step, shouldWithholdInput } : delegation.step;
     return runSteps([step], context.monorepoRoot, { ...runOptions, env: delegation.env });
 }
@@ -747,8 +813,8 @@ async function runGated(options) {
             snapshot,
         }
         : undefined;
-    if (gate !== undefined && !options.noCache) {
-        const recalled = await lookUpRecordedPass({
+    if (gate !== undefined && !options.shouldBypassCache) {
+        const recalledPass = await lookUpRecordedPass({
             anchorDir,
             buildOutput: gate.buildOutputBefore,
             command,
@@ -758,8 +824,8 @@ async function runGated(options) {
             retentionKey: gate.retentionKey,
             stderr,
         });
-        if (recalled !== undefined) {
-            const { entry, ...recall } = recalled;
+        if (recalledPass !== undefined) {
+            const { entry, ...recall } = recalledPass;
             if (recall.replay !== undefined) {
                 await certifyRetention({ anchorDir, command, entry, env, monorepoRoot, runId: options.runId, stderr });
             }
@@ -769,9 +835,9 @@ async function runGated(options) {
     if (options.overrideNotice !== undefined) {
         stdout.write(options.overrideNotice);
     }
-    const startedAt = Date.now();
-    const { exitCode, retained } = await runSteps(options.steps, anchorDir, options.runOptions);
-    const durationMs = Date.now() - startedAt;
+    const startedAtMs = Date.now();
+    const { exitCode, retainedOutput } = await runSteps(options.steps, anchorDir, options.runOptions);
+    const durationMs = Date.now() - startedAtMs;
     if (exitCode === 0 && gate !== undefined) {
         await recordPass({
             anchorDir,
@@ -784,7 +850,7 @@ async function runGated(options) {
             key: gate.key,
             monorepoRoot,
             ownSteps: options.ownSteps,
-            retained,
+            retainedOutput,
             retentionKey: gate.retentionKey,
             runId: options.runId,
             snapshot: gate.snapshot,
@@ -796,17 +862,17 @@ async function runGated(options) {
         outcome: exitCode === 0 ? { outcome: 'passed', durationMs } : { outcome: 'failed', durationMs, exitCode },
     };
 }
-function shellQuote(arg) {
+function quoteForShell(arg) {
     return "'" + arg.replace(/'/g, String.raw `'\''`) + "'";
 }
-function wrapWithHooks(command, mainSteps, registry, anchorDir, workspaceRoot) {
+function wrapWithHooks(command, mainSteps, registry, anchorDir, isWorkspaceRoot) {
     const steps = [];
-    if (hasRunnableHook(`${command}:pre`, registry, anchorDir, workspaceRoot)) {
-        steps.push(composeNmrStep(`${command}:pre`, workspaceRoot));
+    if (hasRunnableHook(`${command}:pre`, registry, anchorDir, isWorkspaceRoot)) {
+        steps.push(composeNmrStep(`${command}:pre`, isWorkspaceRoot));
     }
     steps.push(...mainSteps);
-    if (hasRunnableHook(`${command}:post`, registry, anchorDir, workspaceRoot)) {
-        steps.push(composeNmrStep(`${command}:post`, workspaceRoot));
+    if (hasRunnableHook(`${command}:post`, registry, anchorDir, isWorkspaceRoot)) {
+        steps.push(composeNmrStep(`${command}:post`, isWorkspaceRoot));
     }
     return steps;
 }