@williamthorsen/nmr 0.39.0 → 0.41.0

package/dist/esm/commands/taze.d.ts

@@ -15,15 +15,16 @@ export interface RunTazeOptions {
  * Runs taze from nmr's own dependency tree, forwarding `args`, and returns its exit code.
  *
  * Consumers depend on nmr, not on taze, so taze is transitive and its bin is absent from the consumer's
- * root `node_modules/.bin`. This launcher is what bridges that gap: pnpm links nmr's own bins into the
- * consumer root, and nmr resolves taze from the tree it does control.
+ * root `node_modules/.bin`. This launcher runs taze without that bin: pnpm links nmr's own bins into the
+ * consumer root, and nmr resolves taze from the tree that it does control.
  *
- * A request timeout is the one argument added, and only where `args` carries none. Neither other site can hold
- * it: an invocation's trailing arguments are appended to the resolved command string, so the same flag in the
- * `upgrade` script would be doubled by `nmr upgrade --request-timeout ...`, and taze's parser collects the pair
- * into an array it reads as a near-zero deadline; a `taze.config.ts` setting lands in the object taze's own CLI
- * defaults overwrite. Every other argument is forwarded untouched, so invocation policy (`--recursive`) stays in
- * the script registry, visible in `nmr` help output and overridable per repo, and upgrade policy in `taze.ts`.
+ * A request timeout is the one argument added, and only when `args` does not set one. Neither other site can
+ * declare it: Because an invocation's trailing arguments are appended to the resolved command string, the same
+ * flag in the `upgrade` script would be doubled by `nmr upgrade --request-timeout ...`, and taze's parser
+ * collects the pair into an array that it reads as a near-zero deadline; a `taze.config.ts` setting goes into
+ * the object that taze's own CLI defaults overwrite. Because every other argument is forwarded untouched,
+ * invocation policy (`--recursive`) stays in the script registry, visible in `nmr` help output and overridable
+ * per repo, and upgrade policy stays in `taze.ts`.
  */
 export declare function runTaze(args: string[], options?: RunTazeOptions): number;
 /** Resolves the absolute path of taze's CLI entry from nmr's own dependency tree. */

package/dist/esm/config.d.ts

@@ -9,15 +9,15 @@ export declare function loadConfig(baseDir: string): Promise<NmrConfig>;
  * Loads the monorepo-root `.config/nmr.config.ts`, the tier that feeds script resolution and `devBin`.
  * Returns an empty config if the file doesn't exist.
  *
- * Throws on a recognized key this tier does not honor. `build` governs one package's compile, which reads the
+ * Throws on a recognized key that this tier does not honor. `build` governs one package's compile, which reads the
  * package's own config alone, so a `build` accepted here would apply its patterns nowhere.
  */
 export declare function loadRootConfig(monorepoRoot: string): Promise<NmrConfig>;
 /**
- * Loads a single package's `.config/nmr.config.ts`, the tier `nmr-compile` reads from its working directory.
- * Returns an empty config if the file doesn't exist.
+ * Loads a single package's `.config/nmr.config.ts`, the tier that `nmr-compile` reads from its working
+ * directory. Returns an empty config if the file doesn't exist.
  *
- * Throws on a recognized key this tier does not honor. Dropping one would leave a package building on
- * settings its own config file appears to change, which nothing in the build's output would reveal.
+ * Throws on a recognized key that this tier does not honor. Dropping one would leave a package building on
+ * settings that its own config file appears to change, which nothing in the build's output would reveal.
  */
 export declare function loadWorkspaceConfig(packageDir: string): Promise<NmrConfig>;

package/dist/esm/config.js

@@ -79,7 +79,7 @@ function assertValidElements(scripts, fieldName, configPath) {
             const token = findUnexpressibleToken(element);
             if (token === undefined)
                 continue;
-            throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}.${command}\` element \`${element}\` carries ` +
+            throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}.${command}\` element \`${element}\` contains ` +
                 `\`${token}\`, which is neither a command name nor an nmr flag. Name it as a script of its own and ` +
                 `reference that name here.`);
         }
@@ -142,7 +142,7 @@ function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
     const hook = entries.find(({ command }) => isHookName(command));
     if (hook !== undefined) {
         throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.${hook.field}\` names the hook \`${hook.command}\`, ` +
-            'which is never gated on its own: it runs as part of the chain of the command it wraps.');
+            'which is never gated on its own: It runs as part of the chain of the command that it wraps.');
     }
     const registeredNames = new Set([
         ...Object.keys(buildRootRegistry(config)),
@@ -158,7 +158,7 @@ function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
         return;
     }
     const closestName = findClosestName(unresolvableEntry.command, [...registeredNames, ...declaredNames]);
-    throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.${unresolvableEntry.field}\` names no command: ` +
+    throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.${unresolvableEntry.field}\` does not name any command: ` +
         `\`${unresolvableEntry.command}\`.${closestName === undefined ? '' : ` Did you mean \`${closestName}\`?`}`);
 }
 function readDeclaredScriptNames(monorepoRoot) {

package/dist/esm/context.d.ts

@@ -3,7 +3,6 @@ export interface ResolvedContext {
     monorepoRoot: string;
     isRoot: boolean;
     packageDir?: string;
-    /** The workspace's package directories, resolved once here rather than swept for again by each reader. */
     workspacePackageDirs: string[];
     config: NmrConfig;
 }
@@ -11,7 +10,7 @@ export interface ResolvedContext {
  * Determines whether a directory is inside a workspace package.
  * Returns the package directory if so, or `undefined` if in root context.
  *
- * A workspace may nest one package inside another, so the deepest containing directory wins — matching
+ * A workspace may nest one package inside another, so the deepest containing directory wins. This matches
  * pnpm, which resolves a cwd to the package that encloses it most nearly.
  */
 export declare function findContainingPackageDir(dir: string, workspacePackageDirs: string[]): string | undefined;

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

@@ -6,18 +6,17 @@ export interface StepSpec {
     /** A command name, optionally preceded by nmr's own flags, as it would be typed after `nmr`. */
     run: string;
     /**
-     * Set where the trailing arguments cannot narrow this step's work: it is a prerequisite the narrowed steps
-     * run against, or the tool it reaches would be misled by them. A declining step runs unnarrowed.
+     * Set when the trailing arguments cannot narrow this step's work: It is a prerequisite against which the
+     * narrowed steps run, or the tool that it invokes would be misled by them. A declining step runs unnarrowed.
      */
     shouldDeclineArguments?: boolean;
 }
 export type ScriptValue = string | ReadonlyArray<string | StepSpec>;
 export type ScriptRegistry = Record<string, ScriptValue>;
 /**
- * Workspace scripts, identical for every package.
- * Four Vitest projects are recognized: `tool`, `localhost`, `remote`, and `unit`. The latter is also a catch-all.
- * Name a test file with the matching infix to associate it with a project.
- * Example: `nmr test:tool` runs every file carrying the `tool` infix, such as `my-file.tool.test.ts`.
+ * Workspace scripts, identical for every package. A `test:<tier>` script runs the Vitest project of that tier, which
+ * collects the test files that name it: `nmr test:tool` runs `my-file.tool.test.ts`. The `unit` project also
+ * collects every file that does not name any other tier.
  */
 export declare const workspaceScripts: ScriptRegistry;
 export declare const rootScripts: ScriptRegistry;

package/dist/esm/defineConfig.d.ts

@@ -1,7 +1,7 @@
 import type { NmrConfig } from './types.js';
 export type { BuildConfig, CheckCacheConfig, CommandVerbosity, NmrConfig, OutputConfig, ScriptValue, StepSpec, } from './types.js';
 /**
- * Type-safe identity function for configuration files.
+ * Returns `config` unchanged, typing a configuration file's default export as `NmrConfig`.
  *
  * Usage in `.config/nmr.config.ts`:
  * ```ts

package/dist/esm/git-ignored-paths.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lists the untracked paths that git ignores under `dir`, relative to it and POSIX-separated, sorted. An ignored
+ * directory is one entry ending in `/`, standing for everything beneath it; a tracked file never appears, whatever
+ * pattern it matches.
+ *
+ * Returns an empty list whenever git does not answer, outside a repository or with git missing, so that a caller
+ * excluding these paths over-reports rather than hides a path.
+ */
+export declare function listGitIgnoredPaths(dir: string): string[];

package/dist/esm/git-ignored-paths.js

@@ -0,0 +1,10 @@
+import { spawnSync } from 'node:child_process';
+export function listGitIgnoredPaths(dir) {
+    const result = spawnSync('git', ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--directory', '--no-empty-directory'], { cwd: dir, encoding: 'utf8' });
+    if (result.error !== undefined || result.status !== 0)
+        return [];
+    return result.stdout
+        .split('\0')
+        .filter((entry) => entry !== '')
+        .toSorted();
+}

package/dist/esm/glyphs.d.ts

@@ -1,8 +1,8 @@
 /**
- * Glyphs that name no status; a status marker comes from nmr-core's `STATUS_GLYPHS`. A plain variant is empty
- * where a word always follows the glyph, and a word where the glyph opens a line of its own.
+ * Glyphs that do not name a status; a status marker comes from nmr-core's `STATUS_GLYPHS`. A plain variant is
+ * empty when a word always follows the glyph, and a word when the glyph opens a line of its own.
  *
- * `noop` is a neutral circle: nothing ran because the repo asked for nothing to run, which is neither a
+ * `noop` is a neutral circle: Nothing ran because the repo asked for nothing to run, which is neither a
  * failure nor a block.
  */
 export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "clean" | "package" | "catalog" | "noop" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;

package/dist/esm/help.d.ts

@@ -1,12 +1,12 @@
 import type { NmrConfig } from './types.js';
 /**
- * Generates the help text for the `nmr` CLI. Renders only nmr commands —
+ * Generates the help text for the `nmr` CLI. Renders only nmr commands:
  * names from the workspace and root registries, excluding hooks (`*:pre`,
  * `*:post`).
  *
  * When `packageDir` is provided, tier-3 entries from that package's
  * `package.json:scripts` that match a registry name in the active section
- * are inlined as overrides: the registry value is replaced with the
+ * are inlined as overrides: The registry value is replaced with the
  * override value and the row's command name is suffixed with `*`. The
  * active section is the root section when `shouldUseRoot` is true (root cwd
  * or `-w`), otherwise the workspace section. A footnote is appended once

package/dist/esm/helpers/clampToBytes.d.ts

@@ -1,14 +1,13 @@
-/** Marks a value that was cut, so a reader can tell a truncated one from a complete one. */
+/** Marks a value that was cut, so that a reader can tell a truncated one from a complete one. */
 export declare const TRUNCATION_MARK = "\u2026";
 /**
  * Cuts a string that would overrun a byte budget, marking the cut. What comes back is at most `budgetBytes`
  * long, the mark included.
  *
  * Cuts between code points rather than between bytes, so a multi-byte character is never left in halves.
- * Graphemes are left unconsidered, which can separate an emoji from a modifier following it -- a cost paid
- * only at a budget no caller here comes near.
+ * Graphemes are left unconsidered, which can separate an emoji from a modifier following it -- a risk only
+ * at a budget that the callers here never come near.
  *
- * A budget too small to hold the mark yields nothing at all, rather than a return that overruns what the
- * caller asked for.
+ * The return never exceeds the budget: A budget too small to hold the mark yields an empty string.
  */
 export declare function clampToBytes(value: string, budgetBytes: number): string;

package/dist/esm/helpers/config-path.d.ts

@@ -2,7 +2,5 @@
 export declare const CONFIG_RELATIVE_PATH: string;
 /**
  * Resolves the config-file path for a directory, whether that is the monorepo root or a package.
- * Callers that only need to know whether a config exists -- the build, which folds it into its cache digest -- go
- * through this rather than spelling the path again, so that the two cannot drift into hashing a file nothing reads.
  */
 export declare function resolveConfigPath(baseDir: string): string;

package/dist/esm/helpers/createBoundedBuffer.d.ts

@@ -9,8 +9,8 @@ export interface BoundedBuffer {
     readBuffer: () => Buffer;
 }
 /**
- * Creates an accumulator that retains the first and last bytes it is fed and drops the middle.
- * Both ends are kept because a failing command's first error and its trailing summary each carry signal
+ * Creates an accumulator that retains the first and last bytes that it is fed and drops the middle.
+ * Both ends are kept because a failing command's first error and its trailing summary each contain information
  * that the other end does not.
  */
 export declare function createBoundedBuffer(options?: BoundedBufferOptions): BoundedBuffer;

package/dist/esm/helpers/deriveExcerpt.d.ts

@@ -1,11 +1,10 @@
 /**
- * Reduces a transcript to the one line a verdict's detail slot carries, or `undefined` when it held nothing.
+ * Reduces a transcript to the one line shown in a verdict's detail slot, or `undefined` when it contained nothing.
  *
  * The excerpt is the last blank-line-delimited block: a tool that prints progress separates its closing
- * statement with a blank line, so the blank line is the tool naming where its summary starts. A fixed count of
- * trailing lines fits vitest's four-line summary and v8's six-line coverage summary only by coincidence.
+ * statement with a blank line, and that blank line is the tool's own mark of where its summary starts.
  *
- * The line carries a byte bound of its own, so what a caller persists is bounded. The 512-byte ceiling a
- * verdict line is held to is not applied here, which leaves that line's grammar with the module that owns it.
+ * The line is bounded by `MAX_EXCERPT_BYTES` alone; the ceiling on a verdict line is applied where that line is
+ * composed.
  */
 export declare function deriveExcerpt(transcript: string): string | undefined;

package/dist/esm/helpers/duration.d.ts

@@ -1,17 +1,16 @@
 /**
- * Renders a duration at the two coarsest units that say something, for a line a reader skims.
+ * Renders a duration at the two coarsest units that say something, for a line that a reader skims.
  *
- * Truncates at every unit rather than rounding, so a value never reads as more time than elapsed: 90 seconds is
- * `1m 30s`, where rounding would claim `2m`. Below a minute the tenth is kept, since that is the scale at which
- * one check's runtime differs from another's; a whole number sheds the `.0` rather than reading `12.0s`.
+ * Truncates at every unit rather than rounding, so that a value never reads as more time than elapsed: 119.9
+ * seconds is `1m 59s`, whereas rounding would claim `2m`. Below a minute the tenth is kept, since that is the
+ * scale at which one check's runtime differs from another's; a whole number is rendered without the `.0`, as
+ * `12s` rather than `12.0s`.
  */
 export declare function formatDuration(durationMs: number): string;
 /**
- * Renders the clause a skip spends on the time it saved, or `undefined` when there is no saving worth naming.
- * A skip that can say what it saved earns the clause; one that cannot says nothing, and the caller drops it
- * rather than printing a saving of `~0s`.
+ * Renders the clause stating the time that a skip saved, or `undefined` for a saving under a second.
  *
- * Guards its own input rather than trusting the caller's, because the clause is shared: a non-finite duration
- * compares false against the threshold, and would reach a reader as `saved ~NaNs`.
+ * A non-finite duration also returns `undefined`: It compares false against the threshold and would otherwise
+ * render as `saved ~NaNs`.
  */
 export declare function formatSaving(durationMs: number): string | undefined;

package/dist/esm/helpers/filter-selection.d.ts

@@ -1,40 +1,40 @@
 /**
- * Asks pnpm what a `-F` pattern selects, so an invocation that would select nothing is caught before it
- * delegates, and one selecting several packages is told from one selecting a single package.
+ * Asks pnpm what a `-F` pattern selects, so that an invocation that would select nothing is caught before it
+ * delegates, and one selecting several packages is distinguished from one selecting a single package.
  *
- * pnpm's own selector answers rather than a matcher of nmr's: `-F` means the whole selector language, names
- * and globs alongside `./path`, `{dir}`, `pkg...`, `!negation`, and `[since]`, and a matcher here would leave
- * every form but the simplest silently unchecked.
+ * pnpm answers because `-F` accepts pnpm's whole selector language: names and globs alongside `./path`, `{dir}`,
+ * `pkg...`, `!negation`, and `[since]`.
  *
- * Runs from the monorepo root, where the delegate runs, so a path pattern resolves against the same directory
- * in the probe as in the run it stands in for.
+ * Runs from the monorepo root, where the delegate runs, so that a path pattern resolves against the same
+ * directory in the probe as in the run that it stands in for.
  *
- * The listing counts the root project wherever the filter leaves it standing, while the `exec` a delegation
- * composes runs there only where the pattern selects the root positively: `-F '!./packages/*'` lists the root
- * and executes nowhere. A listing of the root alone is therefore the one reading the listing cannot settle,
- * and it is put to `exec` itself. Every other listing settles on its own, and counts the packages beside the
- * root: two of them run in two scopes, while one beside the root may run in that package alone.
+ * The listing counts the root project wherever the filter does not exclude it, while the `exec` that a
+ * delegation composes runs there only when the pattern selects the root positively: `-F '!./packages/*'` lists
+ * the root and executes nowhere. A listing of the root alone is therefore the one reading that the listing
+ * cannot settle, and that reading is checked against `exec` itself. Every other listing settles on its own, and
+ * counts the packages beside the root: two of them run in two scopes, while one beside the root may run in that
+ * package alone.
  */
 export declare function readFilterSelection(pattern: string, monorepoRoot: string): FilterSelection;
 /**
  * Reduces a listing to what it proves about the selection.
  *
- * Every outcome the probe cannot read resolves to `unresolved`, which claims nothing about the selection, and the
- * invocation delegates as it would have. A pattern pnpm rejects rather than resolves, such as a bad git ref in
- * a changed-since selector, is pnpm's to report, and reporting it here as a match failure would name a
- * different fault than the one the user has.
+ * Every outcome that the probe cannot read resolves to `unresolved`, which claims nothing about the selection,
+ * and the invocation delegates as it would have. A pattern that pnpm rejects rather than resolves, such as a bad
+ * git ref in a changed-since selector, is pnpm's to report, and reporting it here as a match failure would name a
+ * different fault than the one that the user has.
  */
 export declare function interpretSelectionProbe(probe: SelectionProbe, monorepoRoot: string): ProbeReading;
 /**
- * Reduces a marked delegate run to what it proves: a scope that wrote the marker is a scope the run reached. The
- * run is made only for a listing of the root alone, so that scope is the only one.
+ * Reduces a marked delegate run to what it proves: a scope that wrote the marker is a scope that the run
+ * reached. Because the run is made only for a listing of the root alone, that scope is the only one.
  */
 export declare function interpretDelegateProbe(probe: SelectionProbe): FilterSelection;
 /** What a `-F` pattern selected, as far as pnpm could be asked. `multiple` is two or more packages beside the root. */
 export type FilterSelection = 'empty' | 'multiple' | 'single' | 'unresolved';
 /** What a listing proves, `root-only` being the reading that only the delegate can settle. */
 export type ProbeReading = FilterSelection | 'root-only';
-/** The part of a probe's completion a selection is read from. */
+/** The part of a probe's completion from which a selection is read. */
 export interface SelectionProbe {
     error: Error | undefined;
     status: number | null;

package/dist/esm/helpers/findClosestName.d.ts

@@ -1,5 +1,5 @@
 /**
- * Finds the candidate closest to a name, or `undefined` where none is near enough to be worth naming.
+ * Finds the candidate closest to a name, or `undefined` when none is near enough to be worth naming.
  *
  * The ceiling scales with the name's length, so a short name admits one slip and a long one a few. A fixed
  * ceiling would either miss a typo in `root:test:coverage` or offer `fix` for `ci`.

package/dist/esm/helpers/hook-name.d.ts

@@ -1,9 +1,6 @@
 /**
- * Returns true when `key` is a hook script name — that is, ends with the
- * `:pre` or `:post` suffix preceded by at least one character.
+ * Reports whether `key` is a hook script name: a `:pre` or `:post` suffix preceded by at least one character.
  *
- * Bare `:pre` and `:post` (no parent name) return false. The predicate is
- * purely about suffix shape; it does not consult the registry or care
- * whether the parent command exists.
+ * Reads the suffix alone, without consulting the registry for the parent command.
  */
 export declare function isHookName(key: string): boolean;

package/dist/esm/helpers/package-json.d.ts

@@ -1,8 +1,8 @@
 /**
- * The `package.json` fields that carry a dependency's version specifier.
+ * The `package.json` fields that contain a dependency's version specifier.
  *
  * pnpm accepts the `catalog:` protocol in all four, so a reader looking for catalogued dependencies has to
- * sweep the whole set rather than the two that carry most of them.
+ * sweep the whole set rather than the two that contain most of them.
  */
 export declare const DEPENDENCY_FIELDS: readonly ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
 export type DependencyField = (typeof DEPENDENCY_FIELDS)[number];
@@ -19,26 +19,27 @@ export type PackageJson = {
     [K in DependencyField]?: Record<string, string>;
 };
 /**
- * Reads and parses the package.json at the given directory, keeping only the fields nmr reads.
+ * Reads and parses the package.json at the given directory, keeping only the fields that nmr reads.
  */
 export declare function readPackageJson(dir: string): PackageJson;
 /**
- * Returns the `pnpm.overrides` block a package.json declares, every key it holds and each value as written.
+ * Returns the `pnpm.overrides` block declared by a package.json, every key that it contains and each value as
+ * written.
  */
 export declare function getPnpmOverrides(packageJson: PackageJson): Record<string, unknown> | undefined;
 /**
  * Parses a `package.json`'s text, rejecting what does not parse.
  *
- * A file the user wrote by hand is theirs to fix, so the failure names it rather than reporting the parser's
+ * A file that the user wrote by hand is theirs to fix, so the failure names it rather than reporting the parser's
  * own stack.
  */
 export declare function parsePackageJson(rawText: string, file: string): unknown;
 /**
  * Narrows a `scripts` record to strings, rejecting any value that is not one.
  *
- * 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 let a caller run something else in its place and report nothing.
+ * A value of any other type is malformed however it got there, because npm and pnpm read a script as a string
+ * too. Dropping one silently would let a caller run something else in its place and report nothing.
  */
 export declare function readScriptRecord(dir: string, scripts: Record<string, unknown>): Record<string, string>;
-/** Resolves the `package.json` path for a directory: the file tier-3 scripts are read from. */
+/** Resolves the `package.json` path for a directory: the file from which tier-3 scripts are read. */
 export declare function resolvePackageJsonPath(dir: string): string;

package/dist/esm/helpers/readStringValues.d.ts

@@ -1,8 +1,7 @@
 /**
  * Keeps the entries whose value is a string, dropping the rest.
  *
- * A manifest reader that rejected the whole record over one bad value would report nothing about the entries
- * beside it, which for a reporter is silence where there is something to say. YAML's implicit typing makes
- * that easy to reach without malformed intent: an unquoted `18` parses as a number.
+ * Drops rather than rejects, so that one malformed value does not hide the entries beside it. YAML's implicit
+ * typing makes such a value easy to write: An unquoted `18` parses as a number.
  */
 export declare function readStringValues(record: Record<string, unknown>): Record<string, string>;

package/dist/esm/helpers/reportClosing.d.ts

@@ -1,16 +1,15 @@
 /**
  * Reports the line that closes a bin's output, separated from the items above it by a blank line.
  *
- * A bin that prints one line per item leaves a reader who reaches the end holding whichever item happened to
- * be last. The convention this writes: the header says what the list is, and the closing statement says what
- * the run came to, so the count and the remedy live here rather than in the header. The blank line is what
- * makes the statement findable once the lines are flattened.
+ * When a bin prints one line per item, the last line that a reader sees is whichever item happened to be last.
+ * The convention that this implements: The header says what the list is, and the closing statement says what
+ * the run concluded, so the count and the remedy are stated here rather than in the header. The blank line makes
+ * the statement findable once the lines are flattened.
  *
- * The blank line rides in the same call as the statement, so the closer is one write and cannot be
- * interleaved. `log` is what puts the closer on the stream its items went to: a bin reporting to stderr
- * passes `console.warn`.
+ * The closer is one write and cannot be interleaved: The blank line goes in the same call as the statement.
+ * `log` writes the closer to the stream that its items went to: A bin reporting to stderr passes `console.warn`.
  *
- * A bin whose whole output is one or two statements about one subject has no items to be separated from, and
- * closes by printing plainly rather than through here.
+ * A bin whose whole output is one or two statements about one subject does not have any items to be separated
+ * from, and closes by printing plainly rather than through here.
  */
 export declare function reportClosing(message: string, log?: (line: string) => void): void;

package/dist/esm/helpers/transcript.d.ts

@@ -1,30 +1,30 @@
 import type { RetainedOutput } from '../runner.js';
 /**
- * The bound on what one recorded pass persists, and so on what `nmr --log` can print back.
+ * The bound on what one recorded pass persists, and therefore on what `nmr --log` can print back.
  *
- * A quantity of its own, distinct from the two that bound the same bytes elsewhere: the in-memory copy a
- * command's capture keeps is bounded per stream, for a failure this run may still have to report, and a
- * verdict line is bounded at what a pipe carries atomically. This one bounds what a cache directory
- * accumulates over every scope and command a repo records.
+ * A quantity of its own, distinct from the two that bound the same bytes elsewhere: the in-memory copy kept by a
+ * command's capture is bounded per stream, for a failure that this run may still have to report, and a verdict
+ * line is bounded at the size of an atomic pipe write. This one bounds what a cache directory accumulates over
+ * every scope and command recorded in a repo.
  */
 export declare const TRANSCRIPT_LIMIT_BYTES = 262144;
 /**
- * Reduces a command's raw output to the form nmr persists: escape sequences dropped, and a line the command
- * redrew reduced to what a reader was left looking at.
+ * Reduces a command's raw output to the form that nmr persists: escape sequences dropped, and a line redrawn by
+ * the command reduced to what a reader was left looking at.
  *
- * Applied where the bytes are stored rather than where they are captured. The copy a quiet run writes to
+ * Applied where the bytes are stored rather than where they are captured. The copy that a quiet run writes to
  * stderr on failure is the command's own output going to a stream that may be a terminal, and stripping its
  * color there would be a loss.
  */
 export declare function cleanTranscript(rawText: string): string;
 /**
- * Composes what a pass persists from what its command wrote, or `undefined` where it wrote nothing worth
+ * Composes what a pass persists from what its command wrote, or `undefined` when it wrote nothing worth
  * keeping.
  *
- * The streams follow one another rather than interleaving, in the order a quiet run already dumps them on
- * failure: nmr reads each through a pipe of its own, so their true interleaving is not among the facts it
- * holds. A stream carrying nothing contributes neither content nor marker.
+ * The streams follow one another rather than interleaving, in the order in which a quiet run already prints them
+ * on failure: nmr reads each through a pipe of its own, so it does not know their true interleaving. An empty
+ * stream contributes neither content nor marker.
  */
 export declare function composeTranscript(retainedOutput: RetainedOutput): string | undefined;
-/** Renders the line that stands in for dropped bytes, in nmr's voice so it is not mistaken for the tool's. */
+/** Renders the line that stands in for dropped bytes, in nmr's voice so that it is not mistaken for the tool's. */
 export declare function formatElisionMarker(byteCount: number): string;

package/dist/esm/helpers/type-guards.d.ts

@@ -1,3 +1,4 @@
+/** Narrows an unknown value to a plain object, excluding `null` and arrays. */
 export declare function isObject(value: unknown): value is Record<string, unknown>;
 /** Narrows an unknown value to a record of plain strings. */
 export declare function isStringRecord(value: unknown): value is Record<string, string>;

package/dist/esm/output-style.d.ts

@@ -1,40 +1,39 @@
 import type { Writable } from 'node:stream';
 import { type StreamStyleResolution } from '@williamthorsen/nmr-core';
 /**
- * Reports whether a stream is backed by a terminal, which is what detection reads where no source names a
- * style. A stream carrying no `isTTY`, which is the one a test injects, is not one.
+ * Reports whether a stream is backed by a terminal, which detection reads when the flag and `NMR_OUTPUT_STYLE`
+ * do not name a style. A stream without an `isTTY` property is not one.
  */
 export declare function isTerminalStream(stream: Writable): boolean;
 /**
- * Carries the resolved style down the spawned chain, so the flag reaches every process rather than the first
- * and a child writing to a pipe renders as its parent does rather than detecting plain on its own descriptor.
+ * Passes the resolved style down the spawned chain, so that the flag's value is available to every process rather
+ * than the first and a child writing to a pipe renders as its parent does rather than detecting plain on its own
+ * descriptor.
  *
- * Deliberately not a keyed variable, on neither the pass key nor the retention key: it changes how a run
- * renders and never what a command concludes, so folding it into either would stop a plain run from hitting a
- * pass a rich one recorded.
+ * Neither the pass key nor the retention key includes it: It changes how a run renders and never what a command
+ * concludes, so a plain run can reuse a pass that a rich run recorded.
  */
 export declare const OUTPUT_STYLE_ENV_VAR = "NMR_OUTPUT_STYLE";
 /**
  * The flag naming a style for one invocation, which outranks `OUTPUT_STYLE_ENV_VAR`.
  *
- * `nmr` alone carries it. A standalone bin takes the variable, which `nmr <command>` exports to it, so adding
- * a style to a bin does not mean adding a flag to each bin's own parser.
+ * Only `nmr` accepts it. A standalone bin reads the variable, which `nmr <command>` exports to it.
  */
 export declare const OUTPUT_STYLE_FLAG = "--output-style";
 /**
  * Resolves the style of each output stream: the flag, then `NMR_OUTPUT_STYLE`, then detection from `CI`, the
  * stream's terminal state, and `TERM`.
  *
- * Never throws. A value naming no style is returned in `invalid`, for the caller to report with
+ * Never throws. A value that does not name any style is returned in `invalid`, for the caller to report with
  * `describeInvalidOutputStyle`, because the caller has to render that complaint in some style.
  *
- * The flag's raw value is handed to nmr-core as an assignment rather than narrowed here, so nmr rejects a
- * misspelling in the words its siblings use and no second ladder can come to name a different one.
+ * Passes the flag's raw value to nmr-core unnarrowed, so that nmr rejects a misspelling in the same words as
+ * its sibling CLIs.
  */
 export declare function resolveOutputStyles(options: ResolveOutputStylesOptions): StreamStyleResolution;
 export interface ResolveOutputStylesOptions {
     env: NodeJS.ProcessEnv;
-    /** The value the flag was given, absent where the invocation carries none, as a bin's invocation always does. */
+    /** The value given to the flag, absent when the invocation omits the flag, as a bin's invocation always does. */
     flagValue?: string | undefined;
     stderrIsTty: boolean;
     stdoutIsTty: boolean;

package/dist/esm/prettier.d.ts

@@ -1,8 +1,8 @@
 import type { Config } from 'prettier';
 export interface PrettierConfigOptions extends Omit<Config, 'overrides' | 'plugins'> {
-    /** Appended to the plugins this config registers. */
+    /** Appended to the plugins registered by this config. */
     additionalPlugins?: NonNullable<Config['plugins']>;
-    /** Appended to the overrides this config declares, so a later entry wins over nmr's own. */
+    /** Appended to the overrides declared by this config, so a later entry wins over nmr's own. */
     additionalOverrides?: NonNullable<Config['overrides']>;
     /** Replacing the override list is inexpressible; append through `additionalOverrides`. */
     overrides?: never;