@williamthorsen/nmr 0.38.0 → 0.40.0

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(raw: string): string;
+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(retained: 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. */
+export declare function composeTranscript(retainedOutput: RetainedOutput): string | undefined;
+/** 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/transcript.js

@@ -2,15 +2,15 @@ export const TRANSCRIPT_LIMIT_BYTES = 262_144;
 const ANSI_PATTERN = /\u{1B}(?:\[[\u{30}-\u{3F}]*[\u{20}-\u{2F}]*[\u{40}-\u{7E}]|\][^\u{7}\u{1B}]*(?:\u{7}|\u{1B}\\))/gu;
 const END_LIMIT_BYTES = TRANSCRIPT_LIMIT_BYTES / 2;
 const STREAM_MARKER = '\n… nmr: stderr …\n';
-export function cleanTranscript(raw) {
-    return raw
+export function cleanTranscript(rawText) {
+    return rawText
         .replaceAll(ANSI_PATTERN, '')
         .split('\n')
         .map((line) => renderCarriageReturns(line))
         .join('\n');
 }
-export function composeTranscript(retained) {
-    const streams = [retained.stdout, retained.stderr]
+export function composeTranscript(retainedOutput) {
+    const streams = [retainedOutput.stdout, retainedOutput.stderr]
         .map((stream) => cleanTranscript(stream.toString('utf8')))
         .filter((stream) => stream.trim() !== '');
     if (streams.length === 0) {
@@ -22,19 +22,19 @@ export function formatElisionMarker(byteCount) {
     const unit = byteCount === 1 ? 'byte' : 'bytes';
     return `\n… nmr elided ${byteCount.toLocaleString('en-US')} ${unit} …\n`;
 }
-function alignEnd(buffer, end) {
-    let aligned = Math.min(buffer.length, end);
-    while (aligned > 0 && isContinuationByte(buffer[aligned])) {
-        aligned--;
+function alignEnd(buffer, endOffset) {
+    let alignedOffset = Math.min(buffer.length, endOffset);
+    while (alignedOffset > 0 && isContinuationByte(buffer[alignedOffset])) {
+        alignedOffset--;
     }
-    return aligned;
+    return alignedOffset;
 }
-function alignStart(buffer, start) {
-    let aligned = Math.max(0, start);
-    while (aligned < buffer.length && isContinuationByte(buffer[aligned])) {
-        aligned++;
+function alignStart(buffer, startOffset) {
+    let alignedOffset = Math.max(0, startOffset);
+    while (alignedOffset < buffer.length && isContinuationByte(buffer[alignedOffset])) {
+        alignedOffset++;
     }
-    return aligned;
+    return alignedOffset;
 }
 function clampTranscript(transcript) {
     const buffer = Buffer.from(transcript, 'utf8');

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;

package/dist/esm/prettier.js

@@ -57,23 +57,23 @@ export function definePrettierConfig(options = {}) {
 function buildShellPlugin() {
     return {
         ...shPlugin,
-        languages: shPlugin.languages.filter(isInferredLanguage).map(withoutExcludedFilenames),
+        languages: shPlugin.languages.filter(isInferredLanguage).map(dropExcludedFilenames),
     };
 }
 function isInferredLanguage(language) {
     return INFERRED_LANGUAGES.has(language.name);
 }
-function withoutExcludedFilenames(language) {
+function dropExcludedFilenames(language) {
     if (language.filenames === undefined)
         return language;
     return { ...language, filenames: language.filenames.filter((name) => !EXCLUDED_FILENAMES.has(name)) };
 }
 function assertNoReplacement(options) {
     if ('overrides' in options)
-        throw ownedKeyError('overrides', 'additionalOverrides');
+        throw buildOwnedKeyError('overrides', 'additionalOverrides');
     if ('plugins' in options)
-        throw ownedKeyError('plugins', 'additionalPlugins');
+        throw buildOwnedKeyError('plugins', 'additionalPlugins');
 }
-function ownedKeyError(key, seam) {
+function buildOwnedKeyError(key, seam) {
     return new TypeError(`definePrettierConfig: \`${key}\` is owned by this config. Use \`${seam}\` to append to it.`);
 }

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';
@@ -28,12 +34,12 @@ export type KeyDifference = {
     ingredient: 'command-string';
 } | {
     ingredient: 'nmr-version';
-    current: string;
-    recorded: string;
+    currentVersion: string;
+    recordedVersion: string;
 } | {
     ingredient: 'node-version';
-    current: string;
-    recorded: string;
+    currentVersion: string;
+    recordedVersion: string;
 } | {
     ingredient: 'other';
 };
@@ -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,14 +98,13 @@ 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;
     command: string;
-    current: RunIdentity;
+    currentIdentity: RunIdentity;
     isCacheable: boolean;
     key: string | undefined;
     monorepoRoot: 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) {
@@ -27,7 +27,10 @@ export async function resolveRecording(options) {
     }
     const ageMs = Math.max(0, Date.now() - Date.parse(entry.recordedAt));
     if (entry.key !== options.key) {
-        return { ok: false, refusal: { kind: 'mismatched', ageMs, difference: findKeyDifference(entry, options.current) } };
+        return {
+            ok: false,
+            refusal: { kind: 'mismatched', ageMs, difference: findKeyDifference(entry, options.currentIdentity) },
+        };
     }
     const transcript = await readTranscript({ anchorDir, command, monorepoRoot });
     if (transcript === undefined && (entry.retention?.replay.length ?? 0) === 0) {
@@ -41,27 +44,27 @@ 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.recorded}, not ${difference.current}`;
+            return `under nmr ${difference.recordedVersion}, not ${difference.currentVersion}`;
         case 'node-version':
-            return `under Node ${difference.recorded}, not ${difference.current}`;
+            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 unhandled = difference;
-            throw new Error(`Unhandled key difference: ${JSON.stringify(unhandled)}`);
+            const unhandledDifference = difference;
+            throw new Error(`Unhandled key difference: ${JSON.stringify(unhandledDifference)}`);
         }
     }
 }
 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':
@@ -69,23 +72,27 @@ function describeRefusal(command, refusal) {
         case 'no-output':
             return `the pass ${formatDuration(refusal.ageMs)} ago retained none, as a run printing nothing or writing to a terminal does`;
         default: {
-            const unhandled = refusal;
-            throw new Error(`Unhandled refusal: ${JSON.stringify(unhandled)}`);
+            const unhandledRefusal = refusal;
+            throw new Error(`Unhandled refusal: ${JSON.stringify(unhandledRefusal)}`);
         }
     }
 }
-function findKeyDifference(entry, current) {
-    if (current.treeHash !== undefined && entry.treeHash !== current.treeHash) {
+function findKeyDifference(entry, currentIdentity) {
+    if (currentIdentity.treeHash !== undefined && entry.treeHash !== currentIdentity.treeHash) {
         return { ingredient: 'tree' };
     }
-    if (entry.commandString !== current.commandString) {
+    if (entry.commandString !== currentIdentity.commandString) {
         return { ingredient: 'command-string' };
     }
-    if (entry.nmrVersion !== current.nmrVersion) {
-        return { ingredient: 'nmr-version', current: current.nmrVersion, recorded: entry.nmrVersion };
+    if (entry.nmrVersion !== currentIdentity.nmrVersion) {
+        return { ingredient: 'nmr-version', currentVersion: currentIdentity.nmrVersion, recordedVersion: entry.nmrVersion };
     }
-    if (entry.nodeVersion !== current.nodeVersion) {
-        return { ingredient: 'node-version', current: current.nodeVersion, recorded: entry.nodeVersion };
+    if (entry.nodeVersion !== currentIdentity.nodeVersion) {
+        return {
+            ingredient: 'node-version',
+            currentVersion: currentIdentity.nodeVersion,
+            recordedVersion: entry.nodeVersion,
+        };
     }
     return { ingredient: 'other' };
 }

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,17 +34,13 @@ 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 {
     envFormat: ReportFormat | undefined;
-    jsonFlag: boolean;
+    hasJsonFlag: boolean;
 }

package/dist/esm/report-format.js

@@ -6,20 +6,20 @@ export function isReportFormat(value) {
     return names.includes(value);
 }
 export function readReportFormatEnv(env) {
-    const raw = env[REPORT_FORMAT_ENV_VAR];
-    if (raw === undefined || raw === '') {
+    const rawValue = env[REPORT_FORMAT_ENV_VAR];
+    if (rawValue === undefined || rawValue === '') {
         return { ok: true };
     }
-    if (!isReportFormat(raw)) {
-        return { ok: false, error: formatReportFormatRejection(REPORT_FORMAT_ENV_VAR, raw) };
+    if (!isReportFormat(rawValue)) {
+        return { ok: false, error: formatReportFormatRejection(REPORT_FORMAT_ENV_VAR, rawValue) };
     }
-    return { ok: true, format: raw };
+    return { ok: true, format: rawValue };
 }
 export const REPORT_FORMAT_ENV_VAR = 'NMR_REPORT_FORMAT';
 export const REPORT_FORMATS = ['text', 'json'];
 export function resolveReportFormat(options) {
-    const { envFormat, jsonFlag } = options;
-    if (jsonFlag)
+    const { envFormat, hasJsonFlag } = options;
+    if (hasJsonFlag)
         return 'json';
     return envFormat ?? 'text';
 }

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/resolveBinStyles.js

@@ -3,14 +3,14 @@ import { describeInvalidOutputStyle } from '@williamthorsen/nmr-core';
 import { resolveOutputStyles } from "./output-style.js";
 import { UserError } from "./UserError.js";
 export function resolveBinStyles() {
-    const { invalid, styles } = resolveOutputStyles({
+    const { invalid: invalidStyle, styles } = resolveOutputStyles({
         env: process.env,
         flagValue: undefined,
         stderrIsTty: process.stderr.isTTY,
         stdoutIsTty: process.stdout.isTTY,
     });
-    if (invalid !== undefined) {
-        throw new UserError(describeInvalidOutputStyle(invalid));
+    if (invalidStyle !== undefined) {
+        throw new UserError(describeInvalidOutputStyle(invalidStyle));
     }
     return styles;
 }