@williamthorsen/nmr 0.39.0 → 0.41.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
  */