@williamthorsen/nmr 0.39.0 → 0.40.0

package/dist/esm/steps.d.ts

@@ -1,15 +1,15 @@
 /**
- * One element of a resolved command chain, carrying how it was composed rather than how its text reads.
- * A `structural` step is nmr's own composition, held as argv; an `opaque` step is a command nmr does not parse.
+ * One element of a resolved command chain, recording how it was composed rather than how its text reads.
+ * A `structural` step is nmr's own composition, stored as argv; an `opaque` step is a command that nmr does not
+ * parse.
  *
  * A structural step's argv leads with the file to spawn, so the runner has one to hand `spawn` without a shell.
  *
- * `shouldDeclineArguments` travels from the composite element that composed the step to the one reader that acts on it,
- * the binding of the invocation's trailing arguments. Every stage between the two -- the devBin substitution,
- * the chain rendering, the replay assembly, the runner -- passes it through and asks nothing of it.
+ * `shouldDeclineArguments` is passed from the composite element that composed the step to the one reader that acts
+ * on it, the binding of the invocation's trailing arguments. Every stage between the two passes it through unread.
  *
  * `shouldWithholdInput` is read by the runner alone, which gives the step's child the null device as stdin rather
- * than nmr's own. Like `shouldDeclineArguments`, it is set only where it holds and leaves the rendered chain unchanged.
+ * than nmr's own. Like `shouldDeclineArguments`, it is set only when it holds and leaves the rendered chain unchanged.
  */
 export type Step = {
     kind: 'opaque';
@@ -20,81 +20,82 @@ export type Step = {
     shouldDeclineArguments?: boolean;
     shouldWithholdInput?: boolean;
 };
-/** What a structural step asks of the nmr process it spawns. */
+/** What a structural step asks of the nmr process that it spawns. */
 export interface NmrStepTarget {
     command: string;
-    /** Whether the command is fanned out to other scopes, where a `-R` or `-F` sends it. */
+    /** Whether the command is fanned out to other scopes, as it is when a `-R` or `-F` sends it. */
     isDelegate: boolean;
     /**
-     * Whether the command is fanned out to every package, where a `-R` sends it. A separate field rather than a
-     * narrowing of `isDelegate`, whose reader surveys the scopes a `-F` may also have reached.
+     * Whether the command is fanned out to every package, as it is when a `-R` sends it. A separate field rather
+     * than a narrowing of `isDelegate`, whose reader surveys the scopes that a `-F` may also have reached.
      */
     isRecursive: boolean;
-    /** Whether the command runs against the root registry, where a `-w` anchors it. */
+    /** Whether the command runs against the root registry, as it does when a `-w` anchors it. */
     isWorkspaceRoot: boolean;
 }
 /**
- * How a `package.json` entry names the command it is declared under: as its whole value, or alongside other
- * steps. `sole` covers an entry carrying trailing arguments, which declare no step of their own.
+ * How a `package.json` entry names the command under which it is declared: as its whole value, or alongside
+ * other steps. `sole` covers an entry with trailing arguments, which do not declare a step of their own.
  */
 export type SelfReference = 'chained' | 'sole';
 /**
  * Composes the structural step that re-invokes nmr for one composite element.
  *
- * The element tokenizes on whitespace, so it may carry nmr's own flags but cannot carry a space-bearing token.
- * `-w` is prepended as its own token, so the child selects the root registry on its own.
+ * The element tokenizes on whitespace, so it may contain nmr's own flags but cannot contain a space-bearing
+ * token. `-w` is prepended as its own token: The child selects the root registry on its own.
  *
- * `shouldDeclineArguments` is set only where it holds, so a step that takes the trailing arguments renders and compares
- * exactly as it did before any element declared anything.
+ * Because `shouldDeclineArguments` is set only when it holds, a step that takes the trailing arguments compares
+ * equal to one composed without the option.
  */
 export declare function composeNmrStep(element: string, isWorkspaceRoot: boolean, shouldDeclineArguments?: boolean): Step;
 /**
- * Returns the steps that still run in a workspace holding no package: every step but the ones a `-R` fans out.
+ * Returns the steps that still run in a workspace without any package: every step but the ones that a `-R` fans
+ * out.
  *
- * A `-F` step is left standing. It names one package, and its absence is a real error whoever composed the
- * step, where a `-R` asked for every package and a workspace with none has nothing for it to do.
+ * A `-F` step is kept. It names one package, and its absence is a real error whoever composed the step, whereas
+ * a `-R` asked for every package and a workspace with none has nothing for it to do.
  */
 export declare function dropRecursiveSteps(steps: readonly Step[]): Step[];
 /**
- * Returns the text of the first opaque step that reaches nmr through a shell, or `undefined` when none does.
+ * Returns the text of the first opaque step that runs nmr through a shell, or `undefined` when none does.
  *
  * Recognizes nmr in command position: at the start of the step, after `&&`, `||`, `;`, `|`, or a newline, past
  * any leading environment assignments, and behind a launcher such as `npx` or `pnpm exec`. A separator inside
- * quotes opens no position, so a command merely naming nmr in an argument is not a crossing.
+ * quotes does not open a command position, so a command merely naming nmr in an argument is not a crossing.
  *
- * Partial by construction, and partial in stated ways rather than arbitrary ones: a value-taking flag standing
+ * Partial by construction, and partial in stated ways rather than arbitrary ones: A value-taking flag standing
  * immediately before the program name hides it (`npx -p foo nmr`), and a launcher outside `LAUNCHERS` goes
- * unreported. What it finds is the boundary below which nmr cannot tell its own processes from the tools it
- * runs.
+ * unreported. What it finds is the boundary below which nmr cannot tell its own processes from the tools that
+ * it runs.
  */
 export declare function findNmrCrossing(steps: readonly Step[]): string | undefined;
 /**
  * Returns the first token of a composite element that falls outside the grammar, or `undefined` when the
- * element is a command name optionally preceded by nmr's own flags. A token the shell would not read
- * literally is one the rendering would quote whole, turning the element into a command nobody wrote.
+ * element is a command name optionally preceded by nmr's own flags. A token that the shell would not read
+ * literally would be quoted whole by the rendering, turning the element into a command that nobody wrote.
  */
 export declare function findUnexpressibleToken(element: string): string | undefined;
 /**
- * Returns the command a structural step's nmr process runs, whether the step hands that command to other
- * scopes rather than running it where it stands, and whether it anchors the command at the monorepo root.
- * Reports nothing for a step that names no nmr command.
+ * Returns the command that a structural step's nmr process runs, whether the step hands that command to other
+ * scopes rather than running it in its own scope, and whether it anchors the command at the monorepo root.
+ * Reports nothing for a step that does not name an nmr command.
  *
- * The inverse of `composeNmrStep`, and beside it because the two share one grammar: an element may lead with
+ * The inverse of `composeNmrStep`, and beside it because the two share one grammar: An element may lead with
  * nmr's own flags, and the command is the first token that is not one.
  */
 export declare function readNmrStep(step: Step): NmrStepTarget | undefined;
 /**
- * Reports whether a `package.json` entry re-invokes the command it is declared under, and whether it declares
- * anything besides. Reports nothing for an entry that names another command, or none.
+ * Reports whether a `package.json` entry re-invokes the command under which it is declared, and whether it
+ * declares anything besides. Reports nothing for an entry that names another command, or none.
  *
- * Honouring such an entry would spawn a shell running the same command in the same directory, reaching the
- * same entry again without bound, so resolution discards it however it reads. `chained` is what separates an
- * entry that thereby loses steps from one that declares nothing to lose.
+ * Honouring such an entry would spawn a shell running the same command in the same directory, which reads the
+ * same entry again without bound, so resolution discards it however it reads. `chained` separates an entry that
+ * thereby loses steps from one that declares nothing to lose.
  *
- * A segment that delegates carries the command to other scopes rather than back to this one. `-w` re-enters
- * only from the root, a package's entry reaching the root's registry and `package.json` instead of its own.
+ * A segment that delegates sends the command to other scopes rather than back to this one. `-w` re-enters
+ * only from the root, a package's `-w` entry resolving against the root's registry and `package.json` instead of its own.
  *
- * Partial in the same ways `findNmrCrossing` is, and for the same reason: what goes unrecognized re-enters
+ * Partial in the same ways `findNmrCrossing` is, and for the same reason: What goes unrecognized re-enters
  * without bound, which hangs rather than passing quietly.
  */
 export declare function readSelfReference(options: {
@@ -103,9 +104,9 @@ export declare function readSelfReference(options: {
     script: string;
 }): SelfReference | undefined;
 /**
- * Renders a step list as the `&&` chain a shell runs.
+ * Renders a step list as the `&&` chain that a shell runs.
  *
- * The sole producer of a chain string: the check-result cache keys on that string, so a change to the rendering
- * invalidates every recorded pass by construction rather than by anyone remembering to.
+ * The sole producer of a chain string: The check-result cache keys on that string, so a change to the rendering
+ * invalidates every recorded pass.
  */
 export declare function renderChain(steps: readonly Step[]): string;

package/dist/esm/taze.d.ts

@@ -12,7 +12,7 @@ export type TazeConfig = {
 /**
  * Builds a taze configuration from nmr's shared upgrade policy and a repo's own settings.
  *
- * Any property the caller supplies wins, including `0` and an explicit `undefined` — the latter restores
+ * Any property that the caller supplies wins, including `0` and an explicit `undefined`. The latter restores
  * taze's inheritance of pnpm's `minimumReleaseAge`, which only applies while `maturityPeriod` is unset.
  *
  * The merge is shallow, which suits a policy of scalar defaults. A nested default would clobber rather

package/dist/esm/tests.d.ts

@@ -1,29 +1,34 @@
 /**
- * Declares a suite asserting that a repo's test files hold to nmr's conventions: every collected file names an
- * isolation tier, and every test file sits under a `__tests__` directory.
+ * Declares a suite asserting that a repo's test files follow nmr's conventions: Every collected file names an
+ * isolation tier, and every test file is under a `__tests__` directory.
  *
- * Wire it from a one-line test of the repo's own, so the file stays under the repo's `__tests__` and the repo
- * scopes what the sweep covers. Both halves are silent without it: `unit` is the residual project, so an untiered
- * file runs and passes, and a file outside `__tests__` is collected by nothing at all.
+ * Call it from a one-line test of the repo's own, so that the file stays under the repo's `__tests__` and the repo
+ * scopes what the sweep covers. Without it, a violation of either half goes unreported: `unit` is the residual
+ * project, so an untiered file runs and passes, and a file outside `__tests__` is collected by nothing at all.
  *
- * `excludedBasenames` names directory basenames the sweep prunes at any depth, additive to the ones nmr always
+ * `excludedBasenames` names directory basenames that the sweep prunes at any depth, additive to the ones nmr always
  * prunes. Pass the same array to `defineVitestConfig`'s `testCollectionExclude`, or the sweep and the collection
- * glob describe different trees: a directory pruned here alone still runs the files this suite stopped reporting.
+ * glob describe different trees: Vitest still runs the files in a directory pruned here alone, and this suite no
+ * longer reports them.
+ *
+ * Because untracked paths that git ignores are out of scope for the sweep and the shared configs' collection alike,
+ * a directory that `.gitignore` covers does not need an entry in `excludedBasenames`. Outside a git repository, only
+ * the named directories are pruned.
  */
 export declare function checkTestFileConventions(options?: TestFileConventionsOptions): void;
 /**
- * Sweeps a repo for both halves of the convention, reporting the root it swept alongside what it found.
+ * Sweeps a repo for both halves of the convention, reporting the root that it swept alongside what it found.
  *
- * The root is what makes the result trustworthy, and it is the one thing an assertion cannot check: a sweep
- * started from the directory Vitest supplies covers one package, finds nothing, and passes.
+ * The root makes the result trustworthy, and it is the one thing that an assertion cannot check: A sweep started
+ * from the directory that Vitest supplies covers one package, finds nothing, and passes.
  *
  * @internal - Exported only to enable testing
  */
 export declare function reportTestFileConventions(options?: TestFileConventionsOptions): TestFileConventionsReport;
 export interface TestFileConventionsOptions {
     /**
-     * Directory basenames the sweep prunes at any depth, additive to the ones nmr always prunes. The array a repo
-     * passes here is the array it passes to `defineVitestConfig`'s `testCollectionExclude`.
+     * Directory basenames that the sweep prunes at any depth, additive to the ones nmr always prunes and to the paths
+     * that git ignores. A repo passes the same array here and to `defineVitestConfig`'s `testCollectionExclude`.
      */
     excludedBasenames?: readonly string[];
     /**
@@ -32,7 +37,7 @@ export interface TestFileConventionsOptions {
      */
     rootDir?: string;
 }
-/** What one sweep found, and the root it found it in. Paths are relative to that root and POSIX-separated. */
+/** What one sweep found, and the root in which it found it. Paths are relative to that root and POSIX-separated. */
 export interface TestFileConventionsReport {
     misplacedFiles: string[];
     rootDir: string;

package/dist/esm/tests.js

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { findMisplacedTestFiles, findUntieredTestFiles, TIER_NAMES } from "./tiers.js";
 import { findMonorepoRoot } from "./workspace.js";
-const MISPLACED_REMEDY = 'Every test file must sit under a `__tests__` directory, the only place the shared Vitest config collects from. Move each file below into one, or name its directory in `excludedBasenames`.';
+const MISPLACED_REMEDY = 'Every test file must be under a `__tests__` directory, the only place from which the shared Vitest config collects. Move each file below into one, or name its directory in `excludedBasenames`.';
 const UNTIERED_REMEDY = `Every collected test file must name its isolation tier in the segment before \`.test.\`, one of: ${TIER_NAMES.join(', ')}. Rename each file below to <subject>[.<aspect>].<tier>.test.ts.`;
 const RETIRED_OPTION_KEYS = new Map([['exclude', 'excludedBasenames']]);
 export function checkTestFileConventions(options = {}) {
@@ -11,7 +11,7 @@ export function checkTestFileConventions(options = {}) {
         it('every collected test file names its tier', () => {
             expect(untieredFiles, `${UNTIERED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
         });
-        it('every test file sits under a __tests__ directory', () => {
+        it('every test file is under a __tests__ directory', () => {
             expect(misplacedFiles, `${MISPLACED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
         });
     });

package/dist/esm/tiers.d.ts

@@ -1,30 +1,30 @@
-/** Collection patterns for the residual project, which claims every test file the named tiers leave. */
+/** Collection patterns for the residual project, which claims every test file that the named tiers leave. */
 export declare const ALL_TEST_PATTERNS: string[];
 /** Builds the collection patterns for one tier. */
 export declare function buildTierPatterns(tier: string): string[];
 /**
- * Walks `rootDir` for every `*.test.ts` or `*.test.tsx` file sitting outside a `__tests__` directory, returning
- * paths relative to it, POSIX-separated and sorted.
+ * Walks `rootDir` for every `*.test.ts` or `*.test.tsx` file outside a `__tests__` directory, returning paths
+ * relative to it, POSIX-separated and sorted.
  *
- * No project collects such a file, so it runs nowhere and reports nothing. Only a sweep of the tree tells it apart
- * from a file that runs and passes.
+ * The shared config's projects do not collect such a file, so it runs nowhere and reports nothing. Only a sweep of
+ * the tree tells it apart from a file that runs and passes.
  */
 export declare function findMisplacedTestFiles(rootDir: string, options?: TestFileScanOptions): string[];
 /**
- * Walks `rootDir` for every test file the shared config's projects collect, returning paths relative to it,
+ * Walks `rootDir` for every test file that the shared config's projects collect, returning paths relative to it,
  * POSIX-separated and sorted.
  *
- * A walk, because `node:fs` `globSync` does not descend into a dot-directory and honours no option that would make
- * it. Vitest's globber does, so the same pattern string means different things to the two: a check built on the glob
- * would report clean over every test file under a dot-directory.
+ * A walk, because `node:fs` `globSync` does not descend into a dot-directory and does not honour any option that
+ * would make it. Vitest's globber does, so the same pattern string means different things to the two: A check built
+ * on the glob would report clean over every test file under a dot-directory.
  */
 export declare function findTestFiles(rootDir: string, options?: TestFileScanOptions): string[];
 /**
- * Walks `rootDir` for every collected test file whose name selects no tier, returning paths relative to it,
+ * Walks `rootDir` for every collected test file whose name does not select a tier, returning paths relative to it,
  * POSIX-separated and sorted.
  *
- * `unit` is the residual project, so such a file runs under it and reports success: no test run tells it apart from
- * a conformant file.
+ * Because `unit` is the residual project, such a file runs under it and reports success: A test run cannot tell it
+ * apart from a conformant file.
  */
 export declare function findUntieredTestFiles(rootDir: string, options?: TestFileScanOptions): string[];
 /**
@@ -35,27 +35,31 @@ export declare function findUntieredTestFiles(rootDir: string, options?: TestFil
  */
 export declare function hasTierInfix(filePath: string): boolean;
 /**
- * Directory names that hold no test worth collecting: dependencies, build output, and generated reports.
+ * Names of directories that do not contain any test worth collecting: dependencies, build output, and generated
+ * reports.
  *
- * The one point where the collection glob and the walk must agree about scope. Over-reporting is a failure a
- * consumer cannot fix; under-reporting is the silence a conformance check exists to end.
+ * These and the paths that git ignores are the scope on which the collection glob and the walk must agree.
+ * Over-reporting is a failure that a consumer cannot fix; under-reporting hides the violations that a conformance
+ * check exists to report.
  */
 export declare const TEST_COLLECTION_EXCLUDE: string[];
-/** Options every sweep over a repo's test files takes. */
+/** Options that every sweep over a repo's test files takes. */
 export interface TestFileScanOptions {
     /**
-     * Directory basenames pruned at any depth, additive to `TEST_COLLECTION_EXCLUDE`.
+     * Directory basenames pruned at any depth, additive to `TEST_COLLECTION_EXCLUDE` and to the paths that git
+     * ignores.
      *
-     * Basenames rather than globs, so the array a repo passes here is the array it passes to the shared Vitest
-     * config's `testCollectionExclude`. A directory pruned from the sweep but still collected by Vitest is the
-     * silence these sweeps exist to end.
+     * Basenames rather than globs, so that a repo can pass the same array here and to the shared Vitest config's
+     * `testCollectionExclude`. Vitest still runs the files in a directory pruned from the sweep alone, and the sweep
+     * does not report them.
      */
     excludedBasenames?: readonly string[];
 }
 /**
- * The isolation ladder, ordered by the furthest thing a test reaches. A tier names what a test reaches, never how it
- * invokes it: a test driving a compiler through its JavaScript API is `tool`, exactly as one spawning `tsc` would be.
- * Each named tier's name is also its filename infix, so `parse.tool.test.ts` lands in `tool`.
+ * The isolation ladder, ordered by the furthest thing that a test reaches. A tier names what a test reaches, never
+ * how it invokes it: A test driving a compiler through its JavaScript API is `tool`, exactly as one spawning `tsc`
+ * would be. Each named tier's name is also its filename infix, so `parse.tool.test.ts` is collected by the `tool`
+ * project.
  */
 export declare const TIER_NAMES: readonly ["unit", "tool", "localhost", "remote"];
 /** One of the four isolation tiers. */

package/dist/esm/tiers.js

@@ -1,5 +1,6 @@
 import { readdirSync } from 'node:fs';
 import path from 'node:path';
+import { listGitIgnoredPaths } from "./git-ignored-paths.js";
 const TEST_DIR = '__tests__';
 const TEST_EXTENSIONS = '{ts,tsx}';
 const TEST_GLOB_PREFIX = `**/${TEST_DIR}/**`;
@@ -28,11 +29,13 @@ function collectTestFiles(dir, relativeDir, isInTestDir, context) {
     for (const entry of entries) {
         const relativePath = relativeDir === '' ? entry.name : `${relativeDir}/${entry.name}`;
         if (entry.isDirectory()) {
-            if (context.pruned.has(entry.name))
+            if (context.pruned.has(entry.name) || context.ignoredPaths.has(`${relativePath}/`))
                 continue;
             collectTestFiles(path.join(dir, entry.name), relativePath, isInTestDir || entry.name === TEST_DIR, context);
         }
-        else if (isInTestDir !== context.misplaced && TEST_FILE_PATTERN.test(entry.name)) {
+        else if (isInTestDir !== context.misplaced &&
+            TEST_FILE_PATTERN.test(entry.name) &&
+            !context.ignoredPaths.has(relativePath)) {
             context.foundPaths.push(relativePath);
         }
     }
@@ -40,6 +43,7 @@ function collectTestFiles(dir, relativeDir, isInTestDir, context) {
 function walkTestFiles(rootDir, { excludedBasenames = [] }, misplaced) {
     const context = {
         foundPaths: [],
+        ignoredPaths: new Set(listGitIgnoredPaths(rootDir)),
         misplaced,
         pruned: new Set([...TEST_COLLECTION_EXCLUDE, ...excludedBasenames]),
     };

package/dist/esm/types.d.ts

@@ -6,7 +6,7 @@ export type { CommandVerbosity } from './verbosity.js';
 export interface BuildConfig {
     /**
      * Patterns added to the build's default ignore set. Extends rather than replaces, so that declaring one pattern
-     * cannot silently drop the defaults and start shipping a package's own tests.
+     * cannot silently drop the defaults and start publishing a package's own tests.
      * The programmatic `buildPackage` option of the same name behaves identically; its bare `ignorePatterns` replaces.
      */
     extraIgnorePatterns?: string[];
@@ -23,7 +23,7 @@ export interface CheckCacheConfig {
     /**
      * Command names added to the cacheable set. Extends rather than replaces, so that declaring one command
      * cannot silently drop the defaults. A name listed here promises exit-status-only semantics through its whole
-     * chain, hooks included, and has to resolve to a command: both lists are read by name alone, so a misspelt
+     * chain, hooks included, and has to resolve to a command: Both lists are read by name alone, so a misspelt
      * entry would otherwise be inert.
      */
     extraCommands?: string[];
@@ -31,13 +31,13 @@ export interface CheckCacheConfig {
 /** Output settings honored at the monorepo root. */
 export interface OutputConfig {
     /**
-     * The verbosity a run takes when neither `-q` nor the environment named one. Both of those outrank it, and it
-     * outranks agent-harness detection, so `full` here is also how a repo declines to be detected.
+     * The verbosity that a run takes when neither `-q` nor the environment named one. Both of those outrank it.
+     * Because it outranks agent-harness detection, `full` here is also how a repo declines to be detected.
      */
     commandVerbosity?: CommandVerbosity;
     /**
      * Environment-variable names added to the set whose presence marks an agent harness. Extends rather than
-     * replaces, so that declaring one name cannot silently drop the shipped list, and a repo absorbs a harness's
+     * replaces, so that declaring one name cannot silently drop the built-in list, and a repo handles a harness's
      * rename without waiting for an nmr release.
      */
     extraAgentEnvVars?: string[];

package/dist/esm/verbosity.d.ts

@@ -1,55 +1,57 @@
 import type { OutputConfig } from './types.js';
 /**
- * Environment variables a known agent harness sets, whose presence selects quiet when no level above them chose.
- * The identifiers belong to ecosystems nmr does not control and that rename, so `output.extraAgentEnvVars` extends
- * this list rather than a repo waiting for a release. `ROVO_CLI` anticipates a rename of `ROVODEV_CLI` that Rovo
- * has signalled but not made; a variable nobody sets never fires.
+ * Environment variables that a known agent harness sets, whose presence selects quiet when every level above them
+ * left the verbosity unset. `output.extraAgentEnvVars` extends the list. `ROVO_CLI` anticipates a rename of
+ * `ROVODEV_CLI` that Rovo has signalled but not made.
  */
 export declare const AGENT_ENV_VARS: readonly ["CLAUDECODE", "ROVODEV_CLI", "ROVO_CLI"];
 /**
  * The points on the loudness ladder. Both are spelled out rather than leaving `full` implicit in the variable's
- * absence, so a repo-level default is overridable from the environment in either direction.
+ * absence, so that a repo-level default is overridable from the environment in either direction.
  */
 export declare const COMMAND_VERBOSITIES: readonly ["full", "quiet"];
 /**
- * Carries the resolved verbosity down the spawned chain, so `-q` reaches every process rather than the first.
- * Deliberately not a keyed variable: it changes what a run prints and never what a command concludes, so folding
- * it into the cache key would stop a quiet run from hitting a pass a loud one recorded.
+ * Passes the resolved verbosity down the chain of spawned processes, so that `-q` applies to every process rather
+ * than only the first. The pass key does not include it: It changes what a run prints and never what a command
+ * concludes, so a quiet run can reuse a pass that a full run recorded.
  */
 export declare const COMMAND_VERBOSITY_ENV_VAR = "NMR_COMMAND_VERBOSITY";
-/** How loudly nmr reports the output of the commands it runs, which is never its own verdicts. */
+/** How loudly nmr reports the output of the commands that it runs, which is never its own verdicts. */
 export type CommandVerbosity = (typeof COMMAND_VERBOSITIES)[number];
 /**
- * Renders the rejection of a value off the loudness ladder, naming where it was written. Every source that accepts
- * a verbosity renders through this, so no two of them can come to name different ladders.
+ * Renders the rejection of a value off the loudness ladder, naming where it was written. Because every source that
+ * accepts a verbosity renders through this, the sources cannot come to name different ladders.
  */
 export declare function formatVerbosityRejection(source: string, value: string): string;
 /** Narrows a raw value to a point on the loudness ladder. */
 export declare function isCommandVerbosity(value: string): value is CommandVerbosity;
 /**
- * Reads the verbosity the environment names. An unrecognized value resolves to nothing at all, since falling back
- * would pick a mode nobody chose and hide a misspelling for the life of the shell.
+ * Reads the verbosity that the environment names. An unrecognized value is returned as an error, since a fallback
+ * would pick a mode that nobody chose and hide a misspelling for the life of the shell.
  *
- * An unset or empty variable names no verbosity rather than resolving to `full`, which is what leaves the config
- * and detection levels reachable: a floor written in here would outrank both of them.
+ * For an unset or empty variable, this returns a result without a verbosity rather than resolving to `full`, which
+ * is what leaves the config and detection levels reachable: A floor written in here would outrank both of them.
  */
 export declare function readVerbosityEnv(env: NodeJS.ProcessEnv): VerbosityRead;
 export interface ResolveVerbosityOptions {
-    /** Read for the detection level, and for that alone: the variable this module owns arrives as `envVerbosity`. */
+    /**
+     * Read for the detection level, and for that alone: The caller passes the variable that this module owns as
+     * `envVerbosity`.
+     */
     env: NodeJS.ProcessEnv;
     envVerbosity: CommandVerbosity | undefined;
     hasQuietFlag: boolean;
     output: OutputConfig | undefined;
 }
 /**
- * Resolves the verbosity this process runs at: the flag, then the environment, then the repo's config, then
+ * Resolves the verbosity at which this process runs: the flag, then the environment, then the repo's config, then
  * detection of a known agent harness, then `full`.
  *
- * Total by construction. The environment was validated as it was read and the config as it was loaded, 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 and the config as it was loaded, so this does
+ * not have any rejection left to report, and the whole ladder can be read in one place.
  */
 export declare function resolveVerbosity(options: ResolveVerbosityOptions): CommandVerbosity;
-/** The verbosity the environment names, if any, or the message naming why its value could not be read. */
+/** The verbosity that the environment names, if any, or the message naming why its value could not be read. */
 export type VerbosityRead = {
     ok: true;
     verbosity?: CommandVerbosity;

package/dist/esm/verdict.d.ts

@@ -3,40 +3,41 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { ReplayLine } from './check-cache.js';
 import type { ReportFormat } from './report-format.js';
 /**
- * The ceiling a rendered verdict, its newline included, is held to.
+ * The ceiling to which a rendered verdict, its newline included, is held.
  *
- * POSIX guarantees a write at or below `PIPE_BUF` reaches a pipe whole, and 512 is the smallest bound the
- * standard permits, so one write of a line this size cannot be interleaved by a concurrent scope under
- * `pnpm --recursive`. No Node API reports the platform's own bound, and a per-platform table would move the
- * truncation point from one machine to the next. The ceiling governs pipes: a terminal offers no such
- * guarantee at any size.
+ * POSIX guarantees that a write at or below `PIPE_BUF` arrives in a pipe whole, and 512 is the smallest bound that
+ * the standard permits, so one write of a line this size cannot be interleaved by a concurrent scope under
+ * `pnpm --recursive`. Node does not have an API that reports the platform's own bound, and a per-platform table
+ * would move the truncation point from one machine to the next. The ceiling applies to pipes: A terminal does not
+ * offer that guarantee at any size.
  */
 export declare const VERDICT_LINE_LIMIT_BYTES = 512;
 /**
- * Why a command ran nothing, which the `no-op` outcome carries and `--json` serializes.
+ * Why a command ran nothing, which the `no-op` outcome includes and `--json` serializes.
  *
- * `empty-workspace` and `empty-override` both leave a chain with no step in it, so the reason is what tells
- * a command emptied by the workspace apart from one emptied by an override.
+ * `empty-workspace` and `empty-override` both leave a chain without any step in it, so the reason tells a command
+ * emptied by the workspace apart from one emptied by an override.
  */
 export type NoOpReason = 'empty-override' | 'empty-workspace' | 'noop-override';
 /**
- * What a command nmr ran came to, holding the facts a reporting line is rendered from rather than the line
- * itself, so a machine-readable rendering spends the same record a human-readable one does.
+ * The result of a command that nmr ran. It contains the facts from which a reporting line is rendered rather than
+ * the line itself, which lets a machine-readable rendering use the same record as a human-readable one.
  *
- * A recalled pass carries its saving as a duration and not as a decision about whether to mention it: whether
- * one is worth naming belongs to rendering, and a consumer bypassing the renderer inherits neither the
- * threshold nor an obligation to restate it.
+ * A recalled pass records its saving as a duration and not as a decision about whether to mention it: Whether
+ * one is worth naming belongs to rendering, and a consumer bypassing the renderer inherits neither the threshold
+ * nor an obligation to restate it.
  */
 export type Verdict = {
     command: string;
     scope: string;
 } & VerdictOutcome;
 /**
- * How a command ended, together with the facts that ending carries and no other does, and the trailing detail
- * a line reserves room for.
+ * How a command ended, together with the facts specific to that ending, and the trailing detail for which a line
+ * reserves room.
  *
- * A recalled pass carries the excerpts it replays rather than a composed detail string, so the marker naming
- * them a recording, and the ceiling they are held to, stay with the module that owns the line's grammar.
+ * A recalled pass contains the excerpts that it replays rather than a composed detail string, so that the marker
+ * naming them a recording, and the ceiling to which they are held, stay with the module that owns the line's
+ * grammar.
  */
 export type VerdictOutcome = {
     detail?: string;
@@ -57,29 +58,28 @@ export type VerdictOutcome = {
     reason: NoOpReason;
 });
 /**
- * Renders a verdict as the line nmr reports it on, without the newline that terminates it.
+ * Renders a verdict as the line on which nmr reports it, without the newline that terminates it.
  *
- * The line ends without terminal punctuation and reserves its tail for `detail`, so a later change appends to
- * the grammar rather than rewriting it. A detail carrying nothing but line breaks takes its whole clause with
- * it, rather than leaving a separator pointing at nothing.
+ * The line ends without terminal punctuation and reserves its tail for `detail`, so that a later change appends to
+ * the grammar rather than rewriting it. When a detail contains nothing but line breaks, the line omits the detail's
+ * whole clause rather than leaving a separator pointing at nothing.
  *
- * The marker takes no padding column: every plain marker a verdict reaches for is four characters, so the
- * lines align by construction. `formatStatusLine` pads to a column that `BLOCK` widens, and no verdict is one.
+ * The marker does not take a padding column. Because every plain marker that a verdict uses is four characters,
+ * the lines align by construction. `formatStatusLine` pads to a column that `BLOCK` widens, and a verdict is never
+ * one.
  */
 export declare function renderVerdict(verdict: Verdict, style: OutputStyle): string;
 /**
- * Renders a verdict as the JSON object a machine consumer reads, without the newline that terminates it.
+ * Renders a verdict as the JSON object that a machine consumer reads, without the newline that terminates it.
  *
- * Held to the ceiling the prose line is held to, so one write still reaches a pipe whole where concurrent
- * scopes share a descriptor. Cuts land inside the record's text rather than across its structure, which is
- * what leaves the line parseable, and a record is fitted by rungs, each shedding what a reader can better
- * spare than the rung below it. What the ceiling costs is [documented](../docs/reporting.md#reporting-for-a-machine)
- * in the same order.
+ * Held to the same ceiling as the prose line, so that one write still arrives in a pipe whole when concurrent
+ * scopes share a descriptor. It cuts inside the record's text rather than across its structure, which leaves the
+ * line parseable, and fits a record by rungs, each shedding what a reader can better spare than the rung below it.
+ * Each rung is [documented](../docs/reporting.md#reporting-for-a-machine) in the same order.
  */
 export declare function serializeVerdict(verdict: Verdict): string;
 /**
- * Writes a verdict to a stream as a single write, which is what holds a line together when concurrent scopes
- * share one descriptor. Both renderings spend the one record, so neither can come to report what the other
- * does not.
+ * Writes a verdict to a stream as a single write, which keeps a line intact when concurrent scopes share one
+ * descriptor. Both renderings use the one record, so neither can come to report what the other does not.
  */
 export declare function writeVerdict(verdict: Verdict, stream: Writable, format: ReportFormat, style: OutputStyle): void;

package/dist/esm/verdict.js

@@ -52,7 +52,7 @@ function describeNoOpReason(reason) {
         case 'empty-override':
             return 'the override is empty';
         case 'empty-workspace':
-            return 'the workspace declares no package';
+            return 'the workspace does not declare any package';
         case 'noop-override':
             return 'the override is a no-op';
         default: {