@williamthorsen/nmr 0.39.0 → 0.40.0

package/dist/esm/recording.d.ts

@@ -2,16 +2,22 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
 import { type CheckCacheEntry } from './check-cache.js';
 /**
  * What this invocation would be recorded under, insofar as an entry records the same facts. A mismatch is read
- * against these, so a refusal names the ingredient that moved rather than blaming the tree for all of them.
+ * against these so that a refusal names the ingredient that moved rather than blaming the tree for all of them.
  */
 export interface RunIdentity {
     commandString: string;
     nmrVersion: string;
     nodeVersion: string;
-    /** Absent where no snapshot was taken, which leaves the tree unattributable rather than assumed equal. */
+    /**
+     * Absent when this invocation did not take a snapshot, which leaves the tree unattributable rather than assumed
+     * equal.
+     */
     treeHash: string | undefined;
 }
-/** A recorded pass and what it left a reader: its command's own transcript, or the assembly a composite holds. */
+/**
+ * A recorded pass and what it left a reader: its command's own transcript, or the assembly that a composite
+ * stores.
+ */
 export interface Recording {
     entry: CheckCacheEntry;
     /** What the command wrote, absent on a composite, which retains nothing of its own. */
@@ -19,8 +25,8 @@ export interface Recording {
 }
 /**
  * Which of the pass key's ingredients a recorded pass and this invocation disagree on, insofar as an entry
- * records enough to tell: the residual covers what it does not, which is the install, the platform, and the
- * environment variables the key folds in.
+ * records enough to tell: The residual covers what it does not, which is the install, the platform, and the
+ * environment variables that the key folds in.
  */
 export type KeyDifference = {
     ingredient: 'tree';
@@ -48,12 +54,12 @@ export type RecordingLookup = {
 /**
  * Why there is nothing to print. Each is a separate answer to a reader asking for the last run's output, and
  * each names a different next move: run the command, run it on this tree, run it through a pipe, or stop
- * asking for a command no run records.
+ * asking for a command that the check-result cache does not record.
  */
 export type RecordingRefusal = {
     kind: 'uncacheable';
 } | {
-    kind: 'gate-aside';
+    kind: 'cache-inapplicable';
 } | {
     kind: 'unrecorded';
 } | {
@@ -68,9 +74,9 @@ export type RecordingRefusal = {
  * Renders a recording as the reader sees it: a header dating what follows, the command string that produced
  * it, and then the run's own bytes.
  *
- * The header is what presents the body as a recording rather than as this invocation's output, which is what
- * lets a reader at a terminal be shown what a piped run wrote. The command string is the whole chain, hooks
- * included, so the header names what earned the pass and not merely what was typed.
+ * The header presents the body as a recording rather than as this invocation's output, which lets nmr show a
+ * reader at a terminal what a piped run wrote. The command string is the whole chain, hooks included, so the
+ * header names what earned the pass and not merely what was typed.
  */
 export declare function renderRecording(options: {
     command: string;
@@ -79,8 +85,8 @@ export declare function renderRecording(options: {
     style: OutputStyle;
 }): string;
 /**
- * Renders a refusal on the one line a fan-out can attribute, in the grammar a verdict uses: the scope, the
- * command, and what is missing.
+ * Renders a refusal on the one line that a fan-out can attribute, in the grammar used by a verdict: the scope,
+ * the command, and what is missing.
  */
 export declare function renderRefusal(options: {
     command: string;
@@ -92,9 +98,8 @@ export declare function renderRefusal(options: {
  * Resolves what one scope has to show for one command.
  *
  * Admitted on the pass key alone, so `--log` prints exactly what a skip would have recalled and never a
- * recording of some other tree. The retention key is deliberately not consulted: it certifies that a recording
- * describes this presentation environment, which is what a replayed excerpt needs and what a dated recording
- * does not.
+ * recording of some other tree. The retention key is not consulted: It certifies that a recording describes
+ * this presentation environment, which a replayed excerpt needs and a dated recording does not.
  */
 export declare function resolveRecording(options: {
     anchorDir: string;

package/dist/esm/recording.js

@@ -19,7 +19,7 @@ export async function resolveRecording(options) {
         return { ok: false, refusal: { kind: 'uncacheable' } };
     }
     if (options.key === undefined) {
-        return { ok: false, refusal: { kind: 'gate-aside' } };
+        return { ok: false, refusal: { kind: 'cache-inapplicable' } };
     }
     const entry = await readCheckCacheEntry({ anchorDir, command, monorepoRoot });
     if (entry === undefined) {
@@ -44,15 +44,15 @@ function appendNewline(body) {
 function describeDifference(difference) {
     switch (difference.ingredient) {
         case 'tree':
-            return 'on a tree this is not';
+            return 'on a tree that this is not';
         case 'command-string':
-            return 'over a command chain this is not';
+            return 'over a command chain that this is not';
         case 'nmr-version':
             return `under nmr ${difference.recordedVersion}, not ${difference.currentVersion}`;
         case 'node-version':
             return `under Node ${difference.recordedVersion}, not ${difference.currentVersion}`;
         case 'other':
-            return 'under an install or environment this run does not share';
+            return 'under an install or environment that this run does not share';
         default: {
             const unhandledDifference = difference;
             throw new Error(`Unhandled key difference: ${JSON.stringify(unhandledDifference)}`);
@@ -62,9 +62,9 @@ function describeDifference(difference) {
 function describeRefusal(command, refusal) {
     switch (refusal.kind) {
         case 'uncacheable':
-            return `\`${command}\` is outside the check-result cache, so no run of it is recorded`;
-        case 'gate-aside':
-            return 'the check-result cache is standing aside here (NMR_DEBUG=1 reports why)';
+            return `\`${command}\` is outside the check-result cache, so the cache does not record any run of it`;
+        case 'cache-inapplicable':
+            return 'the check-result cache does not apply here (NMR_DEBUG=1 reports why)';
         case 'unrecorded':
             return 'nothing has recorded a pass for this scope';
         case 'mismatched':

package/dist/esm/replay-assembly.d.ts

@@ -1,20 +1,20 @@
 import { type ReplayLine } from './check-cache.js';
 import { type Step } from './steps.js';
 /**
- * Assembles what a composite's skip replays: the excerpts its constituents recorded, in the order its own
- * steps name them.
+ * Assembles what a composite's skip replays: the excerpts recorded by its constituents, in the order in which
+ * its own steps name them.
  *
- * A constituent that is itself a composite holds a flat, attributed list of its own, so splicing one in keeps
+ * A constituent that is itself a composite has a flat, attributed list of its own, so splicing one in keeps
  * the assembly flat and a skipped `ci` replays a package's `test` rather than one opaque `check:strict`
- * line. Nothing is computed and nothing is inferred: a constituent with no admissible entry is absent from
- * the assembly.
+ * line. Nothing is computed and nothing is inferred: A constituent without an admissible entry is absent
+ * from the assembly.
  *
- * A constituent is looked up at the scope its own process anchors at: the composite's anchor, or the monorepo
- * root for an element carrying `-w`, which is how a package-scoped composite reaches a root command.
+ * A constituent is looked up at the scope at which its own process anchors: the composite's anchor, or the
+ * monorepo root for an element that passes `-w`, which is how a package-scoped composite finds a root command's entry.
  *
- * An entry is admissible where the run that certified it is this one and the tree it describes is this one.
- * The witness is what a run stamps on an excerpt it records and on one it recalls and replays; the tree hash
- * is what bounds an identity a process carried out of the run that issued it.
+ * An entry is admissible when the run that certified it is this one and the tree that it describes is this one.
+ * The witness is what a run stamps on an excerpt that it records and on one that it recalls and replays; the
+ * tree hash bounds an identity carried by a process out of the run that issued it.
  */
 export declare function assembleReplay(options: {
     anchorDir: string;

package/dist/esm/report-format.d.ts

@@ -1,32 +1,31 @@
 /**
  * Renders the rejection of a value off the format ladder, naming where it was written. Every source that
- * accepts a format renders through this, so no two of them can come to name different ladders.
+ * accepts a format renders through this, so two of them can never come to name different ladders.
  */
 export declare function formatReportFormatRejection(source: string, value: string): string;
 /** Narrows a raw value to a point on the format ladder. */
 export declare function isReportFormat(value: string): value is ReportFormat;
 /**
- * Reads the format the environment names. An unrecognized value resolves to nothing at all, since falling back
- * would pick a rendering nobody chose and hide a misspelling for the life of the shell.
+ * Reads the format that the environment names. An unrecognized value is returned as an error, which keeps a
+ * misspelling from going unnoticed for the life of the shell.
  *
- * An unset or empty variable names no format rather than resolving to `text`, which keeps the read symmetric
- * with the one the loudness ladder performs and leaves room for a level below the environment.
+ * An unset or empty variable does not name a format, and `resolveReportFormat` supplies the default.
  */
 export declare function readReportFormatEnv(env: NodeJS.ProcessEnv): ReportFormatRead;
 /**
- * Carries the resolved format down the spawned chain, so `--json` reaches every process rather than the first.
- * Deliberately not a keyed variable: it changes how a run reports and never what a command concludes, so
- * folding it into the cache key would stop a machine-readable run from hitting a pass a prose one recorded.
+ * Passes the resolved format down the spawned chain, so that `--json` takes effect in every process and not only
+ * the first. It is not a keyed variable: It changes how a run reports and never what a command concludes, so a
+ * machine-readable run recalls a pass that a prose run recorded.
  */
 export declare const REPORT_FORMAT_ENV_VAR = "NMR_REPORT_FORMAT";
 /**
- * The points on the format ladder. Both are spelled out rather than leaving `text` implicit in the variable's
- * absence, so a format exported for a shell is overridable on one invocation in either direction.
+ * The points on the format ladder. `text` is a named point, so that one invocation can override a format
+ * exported for the shell in either direction.
  */
 export declare const REPORT_FORMATS: readonly ["text", "json"];
-/** How nmr renders its own verdicts, which is never the output of the commands it runs. */
+/** How nmr renders its own verdicts, which is never the output of the commands that it runs. */
 export type ReportFormat = (typeof REPORT_FORMATS)[number];
-/** The format the environment names, if any, or the message naming why its value could not be read. */
+/** The format that the environment names, if any, or the message naming why its value could not be read. */
 export type ReportFormatRead = {
     ok: true;
     format?: ReportFormat;
@@ -35,14 +34,10 @@ export type ReportFormatRead = {
     error: string;
 };
 /**
- * Resolves the format this process reports in: the flag, then the environment, then `text`.
+ * Resolves the format in which this process reports: the flag, then the environment, then `text`.
  *
- * Two levels where the loudness ladder has four. A repo wanting JSON for everyone working in it is not a case
- * anyone has, and detecting a harness would hand every agent JSON in place of the prose the shipped guidance
- * teaches; either is additive later.
- *
- * Total by construction. The environment was validated as it was read, so no rejection is left for this to
- * report and the whole ladder reads in one place.
+ * Total by construction. The environment was validated as it was read, so this does not have any rejection left
+ * to report and the whole ladder reads in one place.
  */
 export declare function resolveReportFormat(options: ResolveReportFormatOptions): ReportFormat;
 export interface ResolveReportFormatOptions {

package/dist/esm/reportCliFailure.d.ts

@@ -3,8 +3,7 @@ import type { Writable } from 'node:stream';
  * Writes a failure to the CLI's error stream: as its message alone when the user's own declaration caused it,
  * and with its stack otherwise.
  *
- * A stack records where nmr noticed a problem, which says nothing about the file a user has to edit; for nmr's
- * own fault it is where a report has to start. `describeError` covers an `Error` carrying no stack and a thrown
- * non-`Error` alike.
+ * A stack records where nmr noticed a problem, which says nothing about the file that a user has to edit; for
+ * nmr's own fault it is where a report has to start.
  */
 export declare function reportCliFailure(error: unknown, stderr: Writable): void;

package/dist/esm/resolve-scripts.d.ts

@@ -1,13 +1,12 @@
 import { type ScriptRegistry } from './default-scripts.js';
 export type { ScriptRegistry, ScriptValue, StepSpec } from './default-scripts.js';
 /**
- * Return the default workspace scripts.
- *
- * A function rather than the exported table itself: callers merge overrides into the result, and `generateHelp`
- * rewrites entries in place, so each caller needs a copy the module does not share.
+ * Returns a shallow copy of the default workspace scripts, whose entries a caller may replace without changing the
+ * defaults.
  */
 export declare function getDefaultWorkspaceScripts(): ScriptRegistry;
 /**
- * Return the default root scripts.
+ * Returns a shallow copy of the default root scripts, whose entries a caller may replace without changing the
+ * defaults.
  */
 export declare function getDefaultRootScripts(): ScriptRegistry;

package/dist/esm/resolveBinStyles.d.ts

@@ -1,12 +1,11 @@
 import { type StreamStyles } from '@williamthorsen/nmr-core';
 /**
- * Resolves the style of the running process's own output streams, and rejects a variable naming no style.
+ * Resolves the style of the running process's own output streams, and rejects a variable that does not name any
+ * style.
  *
- * What a standalone bin calls. A bin carries no `--output-style` of its own: the flag is `nmr`'s, and what
- * reaches a bin is the variable that `nmr <command>` exports to it, so a bin run through nmr renders as nmr
- * does and one run on its own detects its streams.
+ * Each standalone bin calls this and does not pass a flag value, because only `nmr` accepts `OUTPUT_STYLE_FLAG`.
  *
- * Throws rather than exiting, so the bin's own boundary reports the message and sets the exit code, as it does
+ * Throws rather than exiting, so that the bin's own boundary reports the message and sets the exit code, as it does
  * for every other failure in what the caller declared.
  */
 export declare function resolveBinStyles(): StreamStyles;

package/dist/esm/resolver.d.ts

@@ -2,22 +2,22 @@ import { type ScriptRegistry, type ScriptValue } from './resolve-scripts.js';
 import { type Step } from './steps.js';
 import type { NmrConfig } from './types.js';
 /**
- * Replace the first token of a command with a `devBin` substitute.
+ * Replaces the first token of a command with a `devBin` substitute.
  * Relative paths in the replacement are resolved from `monorepoRoot`.
  */
 export declare function applyDevBin(command: string, devBin: Record<string, string> | undefined, monorepoRoot: string): string;
 /**
  * Applies a `devBin` substitution to each opaque step, leaving nmr's own compositions alone.
  *
- * A structural step names a command nmr resolves for itself, so substituting its first token would replace the
- * `nmr` that carries the composite rather than the leaf tool `devBin` documents replacing.
+ * A structural step names a command that nmr resolves for itself, so substituting its first token would replace
+ * the `nmr` that runs the composite rather than the leaf tool that `devBin` documents replacing.
  */
 export declare function applyDevBinToSteps(steps: readonly Step[], devBin: Record<string, string> | undefined, monorepoRoot: string): readonly Step[];
 /**
  * Where a resolved script was read from.
  *
  * `registry` covers the built-in defaults and the repo-wide config together, which resolution cannot tell
- * apart: it receives the two already merged. A caller holding the config refines the two.
+ * apart: It receives the two already merged. A caller that has the config refines the two.
  */
 export type ScriptOrigin = {
     tier: 'registry';
@@ -32,11 +32,11 @@ export interface ResolvedScript {
     steps: readonly Step[];
 }
 /**
- * Expands a script value into the ordered steps it runs as: a string is one opaque step, and an array is one
+ * Expands a script value into the ordered steps that it runs as: a string is one opaque step, and an array is one
  * structural step per element.
  *
  * A bare string element and the `{ run }` spec compose the same step. The spec's only addition is the
- * declaration of what the step does with the invocation's trailing arguments, which position cannot carry.
+ * declaration of what the step does with the invocation's trailing arguments, which position cannot express.
  */
 export declare function expandScript(script: ScriptValue, isWorkspaceRoot: boolean): readonly Step[];
 /**
@@ -47,8 +47,7 @@ export declare function describeScript(script: ScriptValue): string;
  * Reads a package.json's `scripts`, rejecting any value that is not a string.
  *
  * npm and pnpm read a script as a string too, so a value of any other type is malformed however it got there.
- * Dropping one silently would run the registry's entry in its place, which is what an array written here after
- * being told a step list resolves a shelled-nmr crossing would otherwise do.
+ * Dropping one silently would run the registry's entry in its place.
  */
 export declare function readPackageJsonScripts(packageDir: string): Record<string, string> | undefined;
 /**
@@ -62,20 +61,17 @@ export declare function buildWorkspaceRegistry(config: NmrConfig): ScriptRegistr
  */
 export declare function buildRootRegistry(config: NmrConfig): ScriptRegistry;
 /**
- * Returns a `package.json` entry that re-invokes the command it is declared under alongside other steps, or
- * `undefined` where the entry declares no such thing.
+ * Returns a `package.json` entry that re-invokes the command under which it is declared alongside other steps,
+ * or `undefined` when the entry does not.
  *
- * Resolution discards a self-referential entry however it reads, so an entry that chains loses the steps it
+ * Resolution discards a self-referential entry however it reads, so an entry that chains loses the steps that it
  * chained. This is what an invocation rejects on, read where the command runs rather than raised from
- * resolution: the same scripts are resolved speculatively, for packages nobody named.
+ * resolution: The same scripts are resolved speculatively, for packages that nobody named.
  */
 export declare function findChainedSelfReference(packageDir: string | undefined, commandName: string): string | undefined;
 /**
- * Reports whether a `package.json` entry re-invokes the command it is declared under, wherever the
- * re-invocation stands in it, e.g. `"build": "nmr build"` or `"build": "rdy compile && nmr build"`.
- *
- * Honouring one spawns a shell that runs the same command in the same directory, reaching the same entry
- * again without bound, so resolution discards it.
+ * Reports whether a `package.json` entry re-invokes the command under which it is declared, wherever the
+ * re-invocation appears in it, e.g. `"build": "nmr build"` or `"build": "rdy compile && nmr build"`.
  */
 export declare function isSelfReferential(script: string, commandName: string, packageDir: string): boolean;
 /**
@@ -85,6 +81,6 @@ export declare function isSelfReferential(script: string, commandName: string, p
  * 3. Per-package overrides (package.json scripts)
  *
  * Returns undefined if the command is not found in the registry. A package.json override of `""` (indicating
- * skip) resolves to a single opaque step carrying it, which renders back to the empty string.
+ * skip) resolves to a single opaque step containing it, which renders back to the empty string.
  */
 export declare function resolveScript(commandName: string, registry: ScriptRegistry, packageDir: string | undefined, isWorkspaceRoot: boolean): ResolvedScript | undefined;

package/dist/esm/runCli.d.ts

@@ -1,7 +1,7 @@
 import type { Writable } from 'node:stream';
 /**
- * Marks a run made on a delegating caller's behalf, where a command the registry does not define exits 0
- * rather than failing.
+ * Marks a run made on a delegating caller's behalf, in which a command that the registry does not define, and a
+ * `--log` with nothing to show, exit 0 rather than failing.
  */
 export declare const RUN_IF_PRESENT_ENV_VAR = "NMR_RUN_IF_PRESENT";
 /** @internal */
@@ -10,11 +10,11 @@ export interface RunCliOptions {
     args: string[];
     /** Working directory used to resolve the nmr execution context. */
     cwd: string;
-    /** Environment for `runCli` (used for `NMR_RUN_IF_PRESENT` reads and `-R` writes). */
+    /** Environment from which `runCli` reads its settings, and the base of the one that its children inherit. */
     env: NodeJS.ProcessEnv;
-    /** Stream for normal output (help text, override messages). */
+    /** Stream for normal output: help, version, verdicts, recordings, and override notices. */
     stdout: Writable;
-    /** Stream for error output (unknown command, parse errors). */
+    /** Stream for errors, warnings, and debug notes. */
     stderr: Writable;
 }
 /** @internal */
@@ -23,7 +23,7 @@ export interface RunCliResult {
 }
 /**
  * Executes the nmr CLI flow in-process and returns the resulting exit code.
- * Holds no global state, reads no `process.*` globals, never calls `process.exit`.
+ * Does not hold global state, does not read `process.*` globals, and never calls `process.exit`.
  *
  * @internal
  */

package/dist/esm/runCli.js

@@ -25,7 +25,7 @@ import { writeVerdict } from "./verdict.js";
 import { readWorkspacePackageNames, resolveWorkspace } from "./workspace.js";
 const VERSION = readPackageVersion(import.meta.url);
 const CROSSING_CONSEQUENCE = "so nmr handles the nested run's output as a tool's.";
-const RECURSIVE_REJECTION = '-R/--recursive matched no workspace:';
+const RECURSIVE_REJECTION = '-R/--recursive did not match any workspace:';
 const LIST_CEILING = 10;
 const NAMED_ESCAPES = new Map([
     ['\n', String.raw `\n`],
@@ -249,7 +249,7 @@ function bindPassthrough(steps, passthrough, command) {
     return { ok: true, steps: boundSteps };
 }
 function formatUnroutableArgumentsError(command) {
-    return (`\`${command}\` takes no trailing arguments: every step of its chain declines them. ` +
+    return (`\`${command}\` does not take trailing arguments: every step of its chain declines them. ` +
         'Running it unnarrowed is not what the arguments asked for, so nothing ran.');
 }
 function composeDelegation(options) {
@@ -320,7 +320,7 @@ function describeCrossingRemedy(options) {
 }
 function describeStepDestination(key) {
     if (isHookName(key)) {
-        return 'a script of their own that the step list names, because a hook has no `:pre` or `:post` of its own';
+        return 'a script of their own that the step list names, because a hook does not have a `:pre` or `:post` of its own';
     }
     return `a \`${key}:pre\` or \`${key}:post\` script`;
 }
@@ -357,7 +357,7 @@ function formatOverrideNotice(resolvedScript, registry, command, anchorDir, quie
 function formatSelfReferenceRemedy(options) {
     const { command, isWorkspaceRoot, monorepoRoot, registry, script } = options;
     if (isHookName(command)) {
-        return `Delete the re-invocation: \`${command}\` runs the steps standing beside it.`;
+        return `Delete the re-invocation: \`${command}\` runs the steps beside it.`;
     }
     const configSite = path.relative(monorepoRoot, resolveConfigPath(monorepoRoot));
     return formatPackageRemedy({ configSite, crossingStep: script, isWorkspaceRoot, key: command, registry });
@@ -366,14 +366,14 @@ function formatPackageRemedy(options) {
     const { configSite, crossingStep, isWorkspaceRoot, key, registry } = options;
     const registryEntry = Object.hasOwn(registry, key) ? registry[key] : undefined;
     if (registryEntry === undefined) {
-        return (`A \`package.json\` script holds no step list: define \`${key}\` in \`${configSite}\` and move the ` +
+        return (`A \`package.json\` script cannot contain a step list: define \`${key}\` in \`${configSite}\` and move the ` +
             `package-specific steps to ${describeStepDestination(key)}.`);
     }
     const registryChain = renderChain(expandScript(registryEntry, isWorkspaceRoot));
     if (registryChain === crossingStep) {
         return `Delete the entry: nmr's own \`${key}\` already runs \`${escapeControlCharacters(registryChain)}\`.`;
     }
-    return `Delete the entry and move the steps it adds to ${describeStepDestination(key)}.`;
+    return `Delete the entry and move the steps that it adds to ${describeStepDestination(key)}.`;
 }
 function findArgError(parsedArgs) {
     if (parsedArgs.shouldPrintLog &&
@@ -401,15 +401,15 @@ function findEmptySelectionRefusal(options) {
 function formatEmptyFilterError(pattern, names) {
     const rejection = formatFilterRejection(pattern);
     if (pattern.startsWith('!')) {
-        return `${rejection} A pattern beginning with \`!\` excludes what it matches, and this one leaves no package standing.`;
+        return `${rejection} A pattern beginning with \`!\` excludes what it matches, and this one excludes every package.`;
     }
     if (pattern.includes('[')) {
-        return `${rejection} A pattern carrying \`[<ref>]\` selects the packages changed since a git ref, and none has changed.`;
+        return `${rejection} A pattern containing \`[<ref>]\` selects the packages changed since a git ref, and none has changed.`;
     }
     if (pattern.startsWith('.') || pattern.startsWith('/') || pattern.startsWith('{')) {
         return (`${rejection} ` +
             'A pattern written `./dir`, `/dir`, or `{dir}` selects the packages under a directory, ' +
-            'and no package sits under this one.');
+            'and this directory does not contain any package.');
     }
     return (`${rejection} A pattern matches a package's manifest \`name\`, ` +
         `not its directory name.${suggestWorkspaceNames(pattern, names)}`);
@@ -426,23 +426,23 @@ function describeEmptyWorkspace(monorepoRoot) {
             return (`pnpm-workspace.yaml ${declaredClause}, whose \`!\` entries exclude every directory matched by the positive ` +
                 'patterns. Drop or narrow the exclusion.');
         case 'no-package':
-            return (`pnpm-workspace.yaml ${declaredClause}, and the matcher found no directory holding a \`package.json\`. ` +
-                'nmr counts a directory as a package only where it holds `package.json`; unlike pnpm, it recognizes ' +
+            return (`pnpm-workspace.yaml ${declaredClause}, and the matcher did not find any directory containing a \`package.json\`. ` +
+                'nmr counts a directory as a package only when it contains `package.json`; unlike pnpm, it recognizes ' +
                 'neither `package.yaml` nor `package.json5`. Add a `package.json` to the directory that should be a ' +
-                'package, or declare a pattern reaching a directory that holds one.');
+                'package, or declare a pattern reaching a directory that contains one.');
         case 'no-packages-list':
-            return (`pnpm-workspace.yaml at ${monorepoRoot} declares no \`packages\` list, so the workspace holds the root ` +
+            return (`pnpm-workspace.yaml at ${monorepoRoot} does not declare a \`packages\` list, so the workspace contains the root ` +
                 'package alone. Declare a positive pattern such as `packages/*` to reach the packages beneath it.');
         case 'no-pattern':
-            return (`pnpm-workspace.yaml ${declaredClause}, so no pattern reaches the matcher. Declare a positive pattern such ` +
-                'as `packages/*`, and quote any `!` entry, which YAML reads as a tag rather than a string where it ' +
-                'stands bare.');
+            return (`pnpm-workspace.yaml ${declaredClause}, so the matcher does not receive any pattern. Declare a positive ` +
+                'pattern such as `packages/*`, and quote any `!` entry, which YAML reads as a tag rather than a string ' +
+                'when it is unquoted.');
         case 'unreadable-packages':
             return (`pnpm-workspace.yaml at ${monorepoRoot} declares a \`packages\` value that is not a list of strings, so ` +
                 'nothing it declares reaches the matcher. Make it a list whose every entry is a quoted pattern; a bare ' +
                 'value and an entry YAML read as a number or a map are the usual ones.');
         case 'unreadable-manifest':
-            return (`pnpm-workspace.yaml at ${monorepoRoot} holds no valid YAML, so nothing it declares reaches the matcher. ` +
+            return (`pnpm-workspace.yaml at ${monorepoRoot} is not valid YAML, so the matcher does not receive anything that it declares. ` +
                 'Repair the syntax error and run the command again. An unterminated quoted string and a mis-indented ' +
                 'entry are the usual ones.');
         default: {
@@ -463,7 +463,7 @@ function describeDeclaredPatterns(patterns) {
         : `declares ${renderQuotedList(quotablePatterns)}, beside ${emptiedClause}`;
 }
 function formatFilterRejection(pattern) {
-    return `-F/--filter matched no workspace: \`${pattern}\`.`;
+    return `-F/--filter did not match any workspace: \`${pattern}\`.`;
 }
 function suggestWorkspaceNames(pattern, names) {
     if (names.length === 0) {
@@ -511,7 +511,7 @@ function assertNoSelfReference(options) {
     const remedy = formatSelfReferenceRemedy({ command, isWorkspaceRoot, monorepoRoot, registry, script });
     const site = path.relative(monorepoRoot, resolvePackageJsonPath(anchorDir));
     throw new UserError(`${site}: \`scripts.${command}\` re-invokes \`nmr ${command}\` (\`${escapeControlCharacters(script)}\`), ` +
-        `so nmr cannot run the steps it chains. ${remedy}`);
+        `so nmr cannot run the steps that it chains. ${remedy}`);
 }
 function hasRunnableHook(hookName, registry, anchorDir, isWorkspaceRoot) {
     if (findChainedSelfReference(anchorDir, hookName) !== undefined) {
@@ -536,7 +536,7 @@ async function lookUpRecordedPass(options) {
     }
     const [missingPackage] = buildOutput.missingPackages;
     if (missingPackage !== undefined) {
-        writeDebugNote(`running ${command}: ${missingPackage} has no build output`, env, stderr);
+        writeDebugNote(`running ${command}: ${missingPackage} does not have build output`, env, stderr);
         return undefined;
     }
     const stalePackage = findStaleBuildOutput(entry.buildDigests, buildOutput.digests);
@@ -715,7 +715,7 @@ async function recordPass(options) {
     const output = await readBuildOutputState(monorepoRoot, options.config);
     const [missingPackage] = output.missingPackages;
     if (missingPackage !== undefined) {
-        writeDebugNote(`not recording ${command}: ${missingPackage} has no build output`, env, stderr);
+        writeDebugNote(`not recording ${command}: ${missingPackage} does not have build output`, env, stderr);
         return;
     }
     const changedPackage = findStaleBuildOutput(options.buildOutputBefore.digests, output.digests);

package/dist/esm/runner.d.ts

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