@williamthorsen/nmr 0.34.0 → 0.36.0

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

@@ -1,5 +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.
+ *
+ * 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.
+ */
 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.
+ *
+ * Applied where the bytes are stored rather than where they are captured. The copy 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;
+/**
+ * Composes what a pass persists from what its command wrote, or `undefined` where 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.
+ */
 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 formatElisionMarker(byteCount: number): string;

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

@@ -1,2 +1,3 @@
 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/helpers/workspace-patterns.d.ts

@@ -1 +1,8 @@
+/**
+ * Resolves pnpm workspace patterns to absolute package directories.
+ *
+ * Applies pnpm's algorithm: every pattern is rewritten to match a manifest, `!`-prefixed patterns become
+ * exclusions, and the matcher decides the rest. Exclusions filter the entire positive match set
+ * irrespective of declaration order.
+ */
 export declare function resolvePackageDirs(monorepoRoot: string, patterns: string[]): string[];

package/dist/esm/prettier.d.ts

@@ -1,8 +1,16 @@
 import type { Config } from 'prettier';
 export interface PrettierConfigOptions extends Omit<Config, 'overrides' | 'plugins'> {
+    /** Appended to the plugins this config registers. */
     additionalPlugins?: NonNullable<Config['plugins']>;
+    /** Appended to the overrides this config declares, so a later entry wins over nmr's own. */
     additionalOverrides?: NonNullable<Config['overrides']>;
+    /** Replacing the override list is inexpressible; append through `additionalOverrides`. */
     overrides?: never;
+    /** Replacing the plugin list is inexpressible; append through `additionalPlugins`. */
     plugins?: never;
 }
+/**
+ * Builds the shared Prettier config, registering shell and Dockerfile support alongside the house options.
+ * Every option other than `plugins` and `overrides` spreads over the defaults.
+ */
 export declare function definePrettierConfig(options?: PrettierConfigOptions): Config;

package/dist/esm/recording.d.ts

@@ -1,14 +1,26 @@
-import type { CheckCacheEntry } from './check-cache.js';
+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.
+ */
 export interface RunIdentity {
     commandString: string;
     nmrVersion: string;
     nodeVersion: string;
+    /** Absent where no snapshot was taken, 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. */
 export interface Recording {
     entry: CheckCacheEntry;
+    /** What the command wrote, absent on a composite, which retains nothing of its own. */
     transcript?: string;
 }
+/**
+ * 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.
+ */
 export type KeyDifference = {
     ingredient: 'tree';
 } | {
@@ -24,6 +36,7 @@ export type KeyDifference = {
 } | {
     ingredient: 'other';
 };
+/** What `--log` found for one command at one scope. */
 export type RecordingLookup = {
     ok: true;
     recording: Recording;
@@ -31,6 +44,11 @@ export type RecordingLookup = {
     ok: false;
     refusal: RecordingRefusal;
 };
+/**
+ * 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.
+ */
 export type RecordingRefusal = {
     kind: 'uncacheable';
 } | {
@@ -45,16 +63,36 @@ export type RecordingRefusal = {
     kind: 'no-output';
     ageMs: number;
 };
+/**
+ * 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.
+ */
 export declare function renderRecording(options: {
     command: string;
     recording: Recording;
     scope: string;
 }): 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.
+ */
 export declare function renderRefusal(options: {
     command: string;
     refusal: RecordingRefusal;
     scope: string;
 }): string;
+/**
+ * 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.
+ */
 export declare function resolveRecording(options: {
     anchorDir: string;
     command: string;

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

@@ -1,5 +1,21 @@
-import type { ReplayLine } from './check-cache.js';
-import type { Step } from './steps.js';
+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.
+ *
+ * A constituent that is itself a composite holds 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
 export declare function assembleReplay(options: {
     anchorDir: string;
     monorepoRoot: string;

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

@@ -1,9 +1,32 @@
+/**
+ * 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.
+ */
 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.
+ *
+ * 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.
+ */
 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.
+ */
 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.
+ */
 export declare const REPORT_FORMATS: readonly ["text", "json"];
+/** How nmr renders its own verdicts, which is never the output of the commands 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. */
 export type ReportFormatRead = {
     ok: true;
     format?: ReportFormat;
@@ -11,6 +34,16 @@ export type ReportFormatRead = {
     ok: false;
     error: string;
 };
+/**
+ * Resolves the format this process reports in: 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.
+ */
 export declare function resolveReportFormat(options: ResolveReportFormatOptions): ReportFormat;
 export interface ResolveReportFormatOptions {
     envFormat: ReportFormat | undefined;

package/dist/esm/reportCliFailure.d.ts

@@ -1,2 +1,10 @@
 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.
+ */
 export declare function reportCliFailure(error: unknown, stderr: Writable): void;

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

@@ -1,4 +1,13 @@
-import type { ScriptRegistry } from './default-scripts.js';
+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.
+ */
 export declare function getDefaultWorkspaceScripts(): ScriptRegistry;
+/**
+ * Return the default root scripts.
+ */
 export declare function getDefaultRootScripts(): ScriptRegistry;

package/dist/esm/resolver.d.ts

@@ -1,8 +1,24 @@
-import type { ScriptRegistry, ScriptValue } from './resolve-scripts.js';
-import type { Step } from './steps.js';
+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.
+ * 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.
+ */
 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.
+ */
 export type ScriptOrigin = {
     tier: 'registry';
     key: string;
@@ -15,11 +31,60 @@ export interface ResolvedScript {
     origin: ScriptOrigin;
     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
+ * 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.
+ */
 export declare function expandScript(script: ScriptValue, workspaceRoot: boolean): readonly Step[];
+/**
+ * Returns a description of a script for help output.
+ */
 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.
+ */
 export declare function readPackageJsonScripts(packageDir: string): Record<string, string> | undefined;
+/**
+ * Builds the merged workspace script registry:
+ * tier 1 (defaults) + tier 2 (config overrides)
+ */
 export declare function buildWorkspaceRegistry(config: NmrConfig): ScriptRegistry;
+/**
+ * Builds the merged root script registry:
+ * tier 1 (defaults) + tier 2 (config overrides)
+ */
 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.
+ *
+ * Resolution discards a self-referential entry however it reads, so an entry that chains loses the steps 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.
+ */
 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.
+ */
 export declare function isSelfReferential(script: string, commandName: string, packageDir: string): boolean;
+/**
+ * Resolves a script command using the three-tier override system:
+ * 1. Package defaults (built-in registry)
+ * 2. Repo-wide config (.config/nmr.config.ts)
+ * 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.
+ */
 export declare function resolveScript(commandName: string, registry: ScriptRegistry, packageDir: string | undefined, workspaceRoot: boolean): ResolvedScript | undefined;

package/dist/esm/resolver.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { hasErrnoCode } from '@williamthorsen/nmr-core';
 import { parsePackageJson, readScriptRecord, resolvePackageJsonPath } from "./helpers/package-json.js";
 import { isObject } from "./helpers/type-guards.js";
-import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
+import { getDefaultRootScripts, getDefaultWorkspaceScripts, } from "./resolve-scripts.js";
 import { composeNmrStep, readSelfReference } from "./steps.js";
 import { isMonorepoRoot } from "./workspace.js";
 export function applyDevBin(command, devBin, monorepoRoot) {

package/dist/esm/runCli.d.ts

@@ -1,13 +1,30 @@
 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.
+ */
 export declare const RUN_IF_PRESENT_ENV_VAR = "NMR_RUN_IF_PRESENT";
+/** @internal */
 export interface RunCliOptions {
+    /** Post-slice CLI arguments (equivalent to `process.argv.slice(2)`). */
     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). */
     env: NodeJS.ProcessEnv;
+    /** Stream for normal output (help text, override messages). */
     stdout: Writable;
+    /** Stream for error output (unknown command, parse errors). */
     stderr: Writable;
 }
+/** @internal */
 export interface RunCliResult {
     exitCode: number;
 }
+/**
+ * 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`.
+ *
+ * @internal
+ */
 export declare function runCli(options: RunCliOptions): Promise<RunCliResult>;

package/dist/esm/runCli.js

@@ -2,9 +2,9 @@ import path from 'node:path';
 import { readPackageVersion, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { certifyRetention, computeCacheKey, computeRetentionKey, CURRENT_RUNTIME, encodeTreeSnapshot, findStaleBuildOutput, formatMisplacedNoCacheWarning, isCacheableCommand, NO_CACHE_ENV_VAR, readBuildOutputState, readCheckCacheEntry, recordTranscript, resolveRunId, resolveTreeSnapshot, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, writeCheckCacheEntry, writeDebugNote, } from "./check-cache.js";
-import { resolveConfigPath } from "./config.js";
 import { resolveContext } from "./context.js";
 import { generateHelp } from "./help.js";
+import { resolveConfigPath } from "./helpers/config-path.js";
 import { deriveExcerpt } from "./helpers/deriveExcerpt.js";
 import { isHookName } from "./helpers/hook-name.js";
 import { resolvePackageJsonPath } from "./helpers/package-json.js";
@@ -16,7 +16,7 @@ import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandSc
 import { resolveChannel, runSteps } from "./runner.js";
 import { composeNmrStep, findNmrCrossing, renderChain } from "./steps.js";
 import { UserError } from "./UserError.js";
-import { COMMAND_VERBOSITY_ENV_VAR, readVerbosityEnv, resolveVerbosity } from "./verbosity.js";
+import { COMMAND_VERBOSITY_ENV_VAR, readVerbosityEnv, resolveVerbosity, } from "./verbosity.js";
 import { writeVerdict } from "./verdict.js";
 const VERSION = readPackageVersion(import.meta.url);
 const CROSSING_CONSEQUENCE = "so nmr handles the nested run's output as a tool's.";

package/dist/esm/runner.d.ts

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

package/dist/esm/scripts.d.ts

@@ -1,2 +1,3 @@
+/** Public API for inspecting nmr's built-in script registries. */
 export type { ScriptRegistry, ScriptValue, StepSpec } from './default-scripts.js';
 export { getDefaultRootScripts, getDefaultWorkspaceScripts } from './resolve-scripts.js';

package/dist/esm/steps.d.ts

@@ -1,3 +1,13 @@
+/**
+ * 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.
+ *
+ * A structural step's argv leads with the file to spawn, so the runner has one to hand `spawn` without a shell.
+ *
+ * `declinesArgs` 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.
+ */
 export type Step = {
     kind: 'opaque';
     command: string;
@@ -6,19 +16,80 @@ export type Step = {
     argv: readonly [string, ...(readonly string[])];
     declinesArgs?: boolean;
 };
+/** What a structural step asks of the nmr process it spawns. */
 export interface NmrStepTarget {
     command: string;
+    /** Whether the command is fanned out to other scopes, where a `-R` or `-F` sends it. */
     isDelegate: boolean;
+    /** Whether the command runs against the root registry, where 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.
+ */
 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.
+ *
+ * `declinesArgs` 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.
+ */
 export declare function composeNmrStep(element: string, workspaceRoot: boolean, declinesArgs?: boolean): Step;
+/**
+ * Returns the text of the first opaque step that reaches 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.
+ *
+ * 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.
+ */
 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.
+ */
 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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: {
     anchoredAtRoot: boolean;
     commandName: string;
     script: string;
 }): SelfReference | undefined;
+/**
+ * Renders a step list as the `&&` chain 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.
+ */
 export declare function renderChain(steps: readonly Step[]): string;

package/dist/esm/taze.d.ts

@@ -1,5 +1,21 @@
 import type { CheckOptions } from 'taze';
+/**
+ * A taze configuration.
+ *
+ * Every property admits `undefined` explicitly, unlike `Partial<CheckOptions>`, which rejects it under
+ * `exactOptionalPropertyTypes`. Passing `undefined` is how a consumer clears `maturityPeriod`, so the type
+ * has to allow it.
+ */
 export type TazeConfig = {
     [K in keyof CheckOptions]?: CheckOptions[K] | undefined;
 };
+/**
+ * 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
+ * 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
+ * than merge, so adding one means revisiting this.
+ */
 export declare function defineConfig(config: TazeConfig): TazeConfig;

package/dist/esm/tests.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * `exclude` names directory basenames 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.
+ */
+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.
+ *
+ * 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.
+ *
+ * @internal - Exported only to enable testing
+ */
+export declare function reportTestFileConventions({ exclude, rootDir, }?: 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`.
+     */
+    exclude?: readonly string[];
+    /**
+     * The directory to sweep. Defaults to the monorepo root found from the working directory, so one call covers the
+     * whole repo from whichever package Vitest started in.
+     */
+    rootDir?: string;
+}
+/** What one sweep found, and the root it found it in. Paths are relative to that root and POSIX-separated. */
+export interface TestFileConventionsReport {
+    misplaced: string[];
+    rootDir: string;
+    untiered: string[];
+}