@williamthorsen/nmr 0.33.0 → 0.35.0

package/dist/esm/commands/build-output.d.ts

@@ -1,19 +1,83 @@
 export interface BuildOptions {
     entryGlobs?: string[];
+    /** Adds to the effective ignore set, whether that set is the default or an `ignorePatterns` override. */
     extraIgnorePatterns?: string[];
+    /** Replaces the default ignore set. */
     ignorePatterns?: string[];
     outdir?: string;
 }
+/** The pair of directories a build publishes through, both siblings of the emit directory. */
 export interface ScratchDirs {
     previous: string;
     staging: string;
 }
 export declare const DEFAULT_ENTRY_GLOBS: string[];
+/**
+ * Directories holding test scaffolding rather than shipped code, excluded from entry-point selection so a
+ * package does not publish its own helpers. Deliberately not the vitest factory's `COVERAGE_EXCLUDE`: helpers
+ * live in `test-utils/` precisely so they stay inside the coverage include set, so the two lists overlap
+ * without converging and neither can be derived from the other.
+ *
+ * Ignoring a file removes it as an entry point, not from the emit. The compiler still emits whatever the
+ * surviving entry points import, which is what keeps a production module that uses a helper from emitting a
+ * dangling specifier. Widening this list can therefore only drop files nothing in production reaches.
+ */
 export declare const DEFAULT_IGNORE_PATTERNS: string[];
 export declare const DEFAULT_OUTDIR = "dist/esm/";
+/**
+ * Reports whether the output a build of `packageDir` would produce is currently on disk. Applies the rule the
+ * build applies, on the same options the build was given, so a caller probing for output and the build deciding
+ * whether to rebuild cannot disagree: a package whose entry points emit nothing expects no output, and reports
+ * present. Passing options the build was not given is what would make the two disagree.
+ */
 export declare function hasBuildOutput(packageDir: string, options?: BuildOptions): Promise<boolean>;
+/**
+ * Reports whether the output a previous build would have produced is still on disk. Entry points that
+ * emit nothing expect no output, so their absent outdir is not deleted output: a `src` tree holding only
+ * declaration files, or none at all, would otherwise be reported as missing output and recompiled forever.
+ * The emit is what makes an outdir, so what counts is whether any entry point emits, not how many there are.
+ */
 export declare function hasExpectedBuildOutput(packageDir: string, outdir: string, entryPoints: string[]): boolean;
+/**
+ * Returns the digest of the inputs the output currently on disk was built from, or `undefined` when the package
+ * has never been built. Two packages holding the same sources report the same digest, and a package whose output
+ * came from a different tree reports a different one, which is what tells a stale `dist` from a current one.
+ */
 export declare function readBuildDigest(packageDir: string): Promise<string | undefined>;
+/**
+ * Resolves the absolute path of a package's build-cache file, one entry in the shared store. The package
+ * directory is the entry's scope, so the store keys the file to it and packages sharing a hoisted
+ * `node_modules` never collide.
+ *
+ * Three things hold the path where every previously written entry already sits: the `.hash` extension, the
+ * package's own directory name as the slug, and the absence of `discriminators`, which would otherwise fold
+ * into the digest. Changing any of them strands every entry on disk.
+ */
 export declare function resolveBuildCachePath(packageDir: string): string;
+/**
+ * Resolves the two scratch directories a build publishes through: `staging`, which the emit is written to, and
+ * `previous`, which the outgoing output is renamed aside to. Both are siblings of the emit directory, so a
+ * rename between them never crosses a filesystem, and both are dot-prefixed so a leftover stays out of the
+ * globs that select sources.
+ *
+ * The names are fixed rather than unique because the build removes both before use. That removal is what a
+ * unique name would need a sweep to accomplish, and a sweep cannot tell a directory orphaned by a killed run
+ * from one a concurrent build is still writing. A directory left behind by a failed build is cleared the same
+ * way, so the failure path needs no cleanup of its own.
+ */
 export declare function resolveScratchDirs(emitDir: string): ScratchDirs;
+/**
+ * Resolves the fingerprint of the nmr compiling `packageDir`, which joins the build digest beside the compiler
+ * version: the same sources emit differently across nmr versions as they do across TypeScript versions. It is
+ * nmr's own build digest where one is on disk, which is what moves on a dev-loop edit the version does not
+ * follow, and nmr's package version otherwise -- the case in a consuming repo, whose installed copy was built
+ * elsewhere.
+ *
+ * A build of nmr itself takes the version too. Its digest is the entry that build is about to overwrite, so
+ * folding it would make the key a function of its own previous value, which never settles: nmr would rebuild on
+ * every invocation and move the fingerprint every other package reads.
+ *
+ * What the fingerprint names is the nmr that produced the output, not the sources sitting in `src`, so a package
+ * the pre-rebuild binary compiled keeps the old fingerprint and rebuilds on the run after.
+ */
 export declare function resolveToolchainFingerprint(packageDir: string, selfDir?: string): Promise<string>;

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

@@ -1,8 +1,36 @@
-import type { BuildOptions } from './build-output.js';
+import { type BuildOptions } from './build-output.js';
+/**
+ * The toolchain a build's emit comes from: the resolved compiler and the nmr running it. Both join the build
+ * hash, because the same sources can emit differently across either.
+ */
 export interface BuildToolchain {
     compilerVersion: string;
     fingerprint: string;
 }
+/**
+ * Compiles a package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` and
+ * `.d.ts` from two programs and rewriting relative `.ts` specifiers and tsconfig `paths` aliases to
+ * runnable relative `.js` specifiers in both outputs. Skips the build only when no input has changed
+ * and the previous output is still on disk.
+ *
+ * The build owns its output directory: every emit replaces it wholesale, so `dist` is a function of the
+ * current inputs rather than an accumulation of every build that ever ran. Assets belong outside it, or in a
+ * `build:post` hook, which runs after the output is published.
+ */
 export declare function buildPackage(packageDir: string, options?: BuildOptions): Promise<void>;
+/**
+ * Produces a digest of the given files (paths and contents), the emit config, and the toolchain.
+ * The file list is sorted so the digest is order-invariant, and each path is folded in so renames are detected.
+ * The toolchain joins it because the same sources emit differently across TypeScript versions, and across the
+ * nmr versions whose emit logic drives them.
+ */
 export declare function computeBuildHash(packageDir: string, files: string[], emitConfig: object, toolchain: BuildToolchain): Promise<string>;
+/**
+ * Resolves a package's full tsconfig `extends` chain, returning every config file in it (the leaf `tsconfig.json` and
+ * each base it transitively extends, up to the repo root) as paths relative to `packageDir`.
+ * Emit is driven by the fully-resolved compiler options, so the base configs (where `target`, `module`, `paths`,
+ * `lib`, and `strict` are actually defined) must be in the cache's hashed input set; otherwise a change to a base
+ * config would not bust the cache and stale output could ship. Paths are returned relative to `packageDir`, so
+ * `computeBuildHash` reads them and folds a stable, location-independent path string into the digest.
+ */
 export declare function resolveTsconfigChain(packageDir: string, configFileName?: string): string[];

package/dist/esm/commands/build.js

@@ -85,14 +85,15 @@ async function emitPackage(packageDir, entryPoints, outdir) {
     const emitDir = resolveEmitDir(packageDir, outdir);
     const scratchDirs = resolveScratchDirs(emitDir);
     await removeScratchDirs(scratchDirs);
-    const program = ts.createProgram(rootNames, compilerOptions);
     const emitted = new Map();
-    const emitResult = program.emit(undefined, (fileName, text, writeByteOrderMark) => {
+    function collect(fileName, text, writeByteOrderMark) {
         emitted.set(fileName, { text, writeByteOrderMark });
-    });
-    if (emitResult.emitSkipped) {
-        throw new Error(`nmr-compile: emit failed.\n${formatDiagnostics(emitResult.diagnostics)}`);
     }
+    const host = createCachingCompilerHost(compilerOptions);
+    const scriptProgram = ts.createProgram(rootNames, { ...compilerOptions, declaration: false }, host);
+    assertEmitSucceeded(scriptProgram.emit(undefined, collect));
+    const declarationProgram = ts.createProgram(rootNames, { ...compilerOptions, emitDeclarationOnly: true, removeComments: false }, host, scriptProgram);
+    assertEmitSucceeded(declarationProgram.emit(undefined, collect));
     const staged = new Map();
     for (const [fileName, file] of emitted) {
         staged.set(fileName, { ...file, text: rewriteSpecifiers(fileName, file.text, compilerOptions, sourceRoot) });
@@ -105,6 +106,25 @@ async function emitPackage(packageDir, entryPoints, outdir) {
     await swapIntoPlace(emitDir, scratchDirs);
     return staged.size;
 }
+function assertEmitSucceeded(result) {
+    if (result.emitSkipped) {
+        throw new Error(`nmr-compile: emit failed.\n${formatDiagnostics(result.diagnostics)}`);
+    }
+}
+function createCachingCompilerHost(compilerOptions) {
+    const host = ts.createCompilerHost(compilerOptions);
+    const parsed = new Map();
+    const readSourceFile = host.getSourceFile.bind(host);
+    host.getSourceFile = (fileName, languageVersionOrOptions, onError, shouldCreateNewSourceFile) => {
+        if (parsed.has(fileName)) {
+            return parsed.get(fileName);
+        }
+        const sourceFile = readSourceFile(fileName, languageVersionOrOptions, onError, shouldCreateNewSourceFile);
+        parsed.set(fileName, sourceFile);
+        return sourceFile;
+    };
+    return host;
+}
 async function discardScratchDirs(scratchDirs) {
     try {
         await removeScratchDirs(scratchDirs);

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

@@ -1,2 +1,17 @@
+/**
+ * Removes a package's build output and the build-cache entry that describes it, so no state survives to
+ * make the next build skip. Removal is idempotent: an already-clean package is a silent no-op.
+ */
 export declare function cleanPackage(packageDir: string): Promise<void>;
+/**
+ * Cleans the package containing `cwd`, or every workspace package when run from the monorepo root.
+ *
+ * From within a package this is the built-in clean itself: `nmr` has already resolved `clean` to this bin
+ * before invoking it, so resolving again would apply the package's own override twice.
+ *
+ * This is the default `clean` script, shipped as a bin rather than delegating to `rimraf`. Under pnpm's
+ * isolated layout, `pnpm exec` resolves only bins of the consuming project's own direct dependencies, so
+ * a `rimraf` in nmr's dependency tree would be unreachable — while nmr's own bins are linked into the
+ * consumer's `node_modules/.bin`, nmr being a direct dependency.
+ */
 export declare function runClean(cwd?: string): Promise<void>;

package/dist/esm/commands/ensure-prepublish-hooks.d.ts

@@ -10,9 +10,20 @@ export interface EnsurePrepublishHooksResult {
     hasFailures: boolean;
 }
 export declare const DEFAULT_HOOK = "npm run build";
+/**
+ * Check (and optionally fix) whether all publishable workspace packages
+ * have a `prepublishOnly` script.
+ */
 export declare function ensurePrepublishHooks(monorepoRoot: string, options: {
     fix: boolean;
     dryRun: boolean;
     command?: string;
 }): EnsurePrepublishHooksResult;
+/**
+ * Reports one line per publishable package and closes with what the run came to. Private packages appear in
+ * neither: they publish nothing, so a `prepublishOnly` is not theirs to carry.
+ *
+ * Every line goes to stdout, the `✗` included, and the exit code is what carries a failure. A report split
+ * across two streams leaves no reader holding the whole list.
+ */
 export declare function reportPrepublishHooks(result: EnsurePrepublishHooksResult, hookCommand: string): void;

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

@@ -1,6 +1,8 @@
 export type FormatMode = 'check' | 'write';
 export interface FormatTargets {
+    /** Paths relative to the working directory, as `git ls-files` emits them. */
     files: string[];
+    /** Absolute paths to every `.prettierignore` governing the repository, root-most first. */
     ignorePaths: string[];
 }
 export type ResolveTargetsResult = {
@@ -10,14 +12,44 @@ export type ResolveTargetsResult = {
     ok: false;
     error: string;
 };
+/**
+ * Formats or checks the files git reports for `cwd`, and returns the exit code to report.
+ *
+ * Trailing arguments are git pathspecs, not Prettier flags; an unrecognized option is rejected rather
+ * than passed along, since git would read it as a pathspec matching nothing and the run would report
+ * success over an empty selection.
+ */
 export declare function runFmt(argv: string[], cwd?: string): number;
+/**
+ * Resolves what Prettier should format and which ignore files govern it, using git rather than Prettier's
+ * own discovery. Prettier reads `.gitignore` and `.prettierignore` from the working directory only, so a
+ * pattern in `packages/<pkg>/.gitignore` is invisible to a root-level run; git knows the whole hierarchy,
+ * along with `.git/info/exclude` and `core.excludesFile`, which Prettier cannot read under any flag.
+ *
+ * File selection is anchored at `cwd` and ignore discovery at the repository root. That split is the point:
+ * scoping still follows where the caller stands, while the rules applied to a given file no longer do.
+ *
+ * `pathspecs` narrow the selection and are passed to git verbatim, so they carry git pathspec semantics
+ * rather than shell glob semantics.
+ */
 export declare function resolveFormatTargets(cwd: string, pathspecs?: string[]): ResolveTargetsResult;
+/** @internal */
 export interface RunPrettierOptions {
     cliPath: string;
     mode: FormatMode;
     files: string[];
     ignorePaths: string[];
     cwd: string;
+    /** Overridable so the multi-batch path is reachable without a fixture that hits the real ceiling. */
     budgetBytes?: number;
 }
+/**
+ * Runs Prettier over the selection, returning the first non-zero exit code. Every batch runs even after
+ * one fails, so a check reports every offending file rather than only those in the first batch.
+ *
+ * The CLI runs under this process's own Node rather than through its shebang, so it does not depend on
+ * the file's execute bit or on PATH holding a `node`.
+ *
+ * @internal
+ */
 export declare function runPrettier(options: RunPrettierOptions): number;

package/dist/esm/commands/report-catalog.d.ts

@@ -1 +1,11 @@
+/**
+ * Reports the catalogued dependencies a package-scoped upgrade pass cannot see.
+ *
+ * The upgrade tool reads `pnpm-workspace.yaml` only when it sits at the working directory, so a pass run
+ * inside a package drops every dependency a catalog declares -- and a package whose dependencies are all
+ * catalogued reports itself up to date. Naming them, and the root a covering pass runs from, is what keeps
+ * that from reading as a clean bill of health.
+ *
+ * Runs ahead of the report produced by the workspace `upgrade` script.
+ */
 export declare function reportCatalog(cwd: string): void;

package/dist/esm/commands/report-overrides.d.ts

@@ -1 +1,7 @@
+/**
+ * Reports the pnpm dependency overrides declared in the monorepo root's `pnpm-workspace.yaml`, and rejects a
+ * `pnpm.overrides` block left behind in the root `package.json`.
+ *
+ * Runs ahead of the report produced by the root `upgrade` script.
+ */
 export declare function reportOverrides(monorepoRoot: string): void;

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

@@ -4,9 +4,27 @@ export interface SpawnOutcome {
     error?: Error | undefined;
 }
 export interface RunTazeOptions {
+    /** Resolves the absolute path of taze's CLI entry. Injected by tests. */
     resolveCliPath?: () => string;
+    /** Runs the CLI and reports how it exited. Injected by tests. */
     spawn?: (nodePath: string, argv: string[]) => SpawnOutcome;
+    /** Stream that error output is written to. Defaults to `process.stderr`. */
     stderr?: Writable;
 }
+/**
+ * Runs taze from nmr's own dependency tree, forwarding `args`, and returns its exit code.
+ *
+ * Consumers depend on nmr, not on taze, so taze is transitive and its bin is absent from the consumer's
+ * root `node_modules/.bin`. This launcher is what bridges that gap: pnpm links nmr's own bins into the
+ * consumer root, and nmr resolves taze from the tree it does control.
+ *
+ * A request timeout is the one argument added, and only where `args` carries none. Neither other site can hold
+ * it: an invocation's trailing arguments are appended to the resolved command string, so the same flag in the
+ * `upgrade` script would be doubled by `nmr upgrade --request-timeout ...`, and taze's parser collects the pair
+ * into an array it reads as a near-zero deadline; a `taze.config.ts` setting lands in the object taze's own CLI
+ * defaults overwrite. Every other argument is forwarded untouched, so invocation policy (`--recursive`) stays in
+ * the script registry, visible in `nmr` help output and overridable per repo, and upgrade policy in `taze.ts`.
+ */
 export declare function runTaze(args: string[], options?: RunTazeOptions): number;
+/** Resolves the absolute path of taze's CLI entry from nmr's own dependency tree. */
 export declare function resolveTazeCliPath(): string;

package/dist/esm/commands/taze.js

@@ -4,6 +4,10 @@ import { fileURLToPath } from 'node:url';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 const TAZE_CLI_SPECIFIER = 'taze/cli';
+const REQUEST_TIMEOUT_FLAG = '--request-timeout';
+const REQUEST_TIMEOUT_FLAGS = [REQUEST_TIMEOUT_FLAG, '--requestTimeout'];
+const REQUEST_TIMEOUT_MS = 30_000;
+const ARGUMENT_TERMINATOR = '--';
 export function runTaze(args, options = {}) {
     const stderr = options.stderr ?? process.stderr;
     const resolveCliPath = options.resolveCliPath ?? resolveTazeCliPath;
@@ -17,7 +21,7 @@ export function runTaze(args, options = {}) {
         reportError(`Could not resolve '${TAZE_CLI_SPECIFIER}' from nmr's dependencies. Reinstall the workspace to restore it. (${detail})`, stderr);
         return 1;
     }
-    const outcome = spawn(process.execPath, [cliPath, ...args]);
+    const outcome = spawn(process.execPath, [cliPath, ...composeRequestTimeoutArgs(args), ...args]);
     if (outcome.error) {
         reportError(`Failed to run taze: ${outcome.error.message}`, stderr);
         return 1;
@@ -27,6 +31,18 @@ export function runTaze(args, options = {}) {
 export function resolveTazeCliPath() {
     return fileURLToPath(import.meta.resolve(TAZE_CLI_SPECIFIER));
 }
+function carriesRequestTimeout(args) {
+    for (const arg of args) {
+        if (arg === ARGUMENT_TERMINATOR)
+            return false;
+        if (REQUEST_TIMEOUT_FLAGS.some((flag) => arg === flag || arg.startsWith(`${flag}=`)))
+            return true;
+    }
+    return false;
+}
+function composeRequestTimeoutArgs(args) {
+    return carriesRequestTimeout(args) ? [] : [REQUEST_TIMEOUT_FLAG, String(REQUEST_TIMEOUT_MS)];
+}
 function spawnNode(nodePath, argv) {
     const result = spawnSync(nodePath, argv, { stdio: 'inherit' });
     return { status: result.status, error: result.error };

package/dist/esm/config.d.ts

@@ -1,6 +1,31 @@
 import type { NmrConfig } from './types.js';
+/** The config's path relative to the directory holding it, for a message composed without one in hand. */
 export declare const CONFIG_RELATIVE_PATH: string;
+/**
+ * Resolves the config-file path for a directory, whether that is the monorepo root or a package.
+ * Callers that only need to know whether a config exists -- the build, which folds it into its cache digest -- go
+ * through this rather than spelling the path again, so that the two cannot drift into hashing a file nothing reads.
+ */
 export declare function resolveConfigPath(baseDir: string): string;
+/**
+ * Loads the nmr configuration from `.config/nmr.config.ts` under `baseDir`, which is the monorepo root for
+ * the repo-wide config and a package directory for the workspace tier. Returns an empty config if the file
+ * doesn't exist.
+ */
 export declare function loadConfig(baseDir: string): Promise<NmrConfig>;
+/**
+ * Loads the monorepo-root `.config/nmr.config.ts`, the tier that feeds script resolution and `devBin`.
+ * Returns an empty config if the file doesn't exist.
+ *
+ * Throws on a recognized key this tier does not honor. `build` governs one package's compile, which reads the
+ * package's own config alone, so a `build` accepted here would apply its patterns nowhere.
+ */
 export declare function loadRootConfig(monorepoRoot: string): Promise<NmrConfig>;
+/**
+ * Loads a single package's `.config/nmr.config.ts`, the tier `nmr-compile` reads from its working directory.
+ * Returns an empty config if the file doesn't exist.
+ *
+ * Throws on a recognized key this tier does not honor. Dropping one would leave a package building on
+ * settings its own config file appears to change, which nothing in the build's output would reveal.
+ */
 export declare function loadWorkspaceConfig(packageDir: string): Promise<NmrConfig>;

package/dist/esm/context.d.ts

@@ -5,5 +5,16 @@ export interface ResolvedContext {
     packageDir?: string;
     config: NmrConfig;
 }
+/**
+ * Determines whether a directory is inside a workspace package.
+ * Returns the package directory if so, or `undefined` if in root context.
+ *
+ * A workspace may nest one package inside another, so the deepest containing directory wins — matching
+ * pnpm, which resolves a cwd to the package that encloses it most nearly.
+ */
 export declare function findContainingPackageDir(dir: string, workspacePackageDirs: string[]): string | undefined;
+/**
+ * Resolves the full execution context: monorepo root, whether we're in a
+ * workspace package or root context, and the loaded configuration.
+ */
 export declare function resolveContext(cwd?: string): Promise<ResolvedContext>;

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

@@ -1,8 +1,23 @@
+/**
+ * One element of a composite, paired with what it does with the invocation's trailing arguments. The bare
+ * string form of an element is this spec with `declinesArgs` left at its default.
+ */
 export interface StepSpec {
+    /** A command name, optionally preceded by nmr's own flags, as it would be typed after `nmr`. */
     run: string;
+    /**
+     * Set where the trailing arguments cannot narrow this step's work: it is a prerequisite the narrowed steps
+     * run against, or the tool it reaches would be misled by them. A declining step runs unnarrowed.
+     */
     declinesArgs?: boolean;
 }
 export type ScriptValue = string | ReadonlyArray<string | StepSpec>;
 export type ScriptRegistry = Record<string, ScriptValue>;
+/**
+ * Workspace scripts, identical for every package.
+ * Four Vitest projects are recognized: `tool`, `localhost`, `remote`, and `unit`. The latter is also a catch-all.
+ * Name a test file with the matching infix to associate it with a project.
+ * Example: `nmr test:tool` runs every file carrying the `tool` infix, such as `my-file.tool.test.ts`.
+ */
 export declare const workspaceScripts: ScriptRegistry;
 export declare const rootScripts: ScriptRegistry;

package/dist/esm/defineConfig.d.ts

@@ -1,3 +1,12 @@
 import type { NmrConfig } from './types.js';
 export type { BuildConfig, CheckCacheConfig, CommandVerbosity, NmrConfig, OutputConfig, ScriptValue, StepSpec, } from './types.js';
+/**
+ * Type-safe identity function for configuration files.
+ *
+ * Usage in `.config/nmr.config.ts`:
+ * ```ts
+ * import { defineConfig } from '@williamthorsen/nmr/config';
+ * export default defineConfig({ ... });
+ * ```
+ */
 export declare function defineConfig(config: NmrConfig): NmrConfig;

package/dist/esm/help.d.ts

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

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

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

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

@@ -3,7 +3,14 @@ export interface BoundedBufferOptions {
     tailLimitBytes?: number;
 }
 export interface BoundedBuffer {
+    /** Retains a chunk, dropping bytes from the middle once both ends are full. */
     append: (chunk: Buffer) => void;
+    /** Renders the retained bytes, with a marker naming the dropped count standing in for what was dropped. */
     toBuffer: () => Buffer;
 }
+/**
+ * Creates an accumulator that retains the first and last bytes it is fed and drops the middle.
+ * Both ends are kept because a failing command's first error and its trailing summary each carry signal
+ * that the other end does not.
+ */
 export declare function createBoundedBuffer(options?: BoundedBufferOptions): BoundedBuffer;

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

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

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

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

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

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

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

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

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

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

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

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

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>;