@williamthorsen/nmr 0.34.0 → 0.35.0

package/dist/esm/check-cache.d.ts

@@ -1,7 +1,9 @@
 import type { Writable } from 'node:stream';
 import type { OutputChannels } from './runner.js';
 import type { CheckCacheConfig, NmrConfig } from './types.js';
+/** A recorded pass: what ran, on which tree, and what it cost. */
 export interface CheckCacheEntry {
+    /** The full cache key the pass was recorded under; a hit is this matching the key computed now. */
     key: string;
     treeHash: string;
     headSha: string;
@@ -9,44 +11,94 @@ export interface CheckCacheEntry {
     nmrVersion: string;
     nodeVersion: string;
     durationMs: number;
+    /** ISO-8601 instant the pass completed. */
     recordedAt: string;
+    /**
+     * The build digest each covered package's output carried when the pass was recorded. Build output is
+     * git-ignored, so the tree hash cannot describe it; comparing these is what separates output built from this
+     * tree from output another tree left behind.
+     */
     buildDigests: Record<string, string>;
+    /** What a skip replays in place of the run it recalls, absent on a pass that retained nothing. */
     retention?: Retention;
 }
+/** What locates one command's recorded pass at one scope, and the transcript beside it. */
 export interface EntryRef {
     anchorDir: string;
     command: string;
     monorepoRoot: string;
 }
+/** One command's excerpt, attributed to the scope and the command that produced it. */
 export interface ReplayLine {
     command: string;
     excerpt: string;
     scope: string;
 }
+/**
+ * What a recalled pass replays, the key certifying the excerpts describe this environment's output, and the
+ * run that last vouched for them.
+ *
+ * A list rather than one excerpt: a composite's entry carries its constituents' lines, and a nested one's are
+ * spliced into its parent's, where the attribution cannot be re-derived from the entry that holds them.
+ *
+ * The witness is what admits a constituent's line into the assembly its parent records: a run writes it when
+ * it records an excerpt, and restamps it when it recalls one and replays it.
+ */
 export interface Retention {
     key: string;
     replay: ReplayLine[];
     runId: string;
 }
+/** What nmr's own build has left on disk across the workspace. */
 export interface BuildOutputState {
+    /** Covered packages whose output is absent. */
     missing: string[];
+    /** The digest of the inputs each covered package's output was built from, keyed by package name. */
     digests: Record<string, string>;
 }
+/** The parts of the running interpreter that can change what a check concludes. */
 export interface RuntimeIdentity {
     arch: string;
     nodeVersion: string;
     platform: string;
 }
+/** One working tree, observed once per top-level invocation and shared with every process below it. */
 export interface TreeSnapshot {
     hash: string;
     headSha: string;
 }
+/** The interpreter this process is running on, folded into every key and recorded alongside every pass. */
 export declare const CURRENT_RUNTIME: RuntimeIdentity;
+/** Set to `1` to hear why the gate did not skip, or why it is disabled. */
 export declare const DEBUG_ENV_VAR = "NMR_DEBUG";
+/**
+ * The commands cacheable without configuration: those whose whole contribution is an exit status, and that
+ * reach nothing beyond a checkout and an install.
+ *
+ * Excluded on purpose. `audit` and `prepush` consult a vulnerability database that changes without the tree
+ * (`prepush`'s `ci` constituent still skips while its `audit` always runs). `build` and `compile` carry a cache
+ * of their own. `fix`, `fmt`, `lint`, and `upgrade` mutate the tree they are asked about. `test:all` reaches
+ * whatever the environment supplies. Anything a repo adds here promises exit-status-only semantics through its
+ * whole chain, hooks included.
+ */
 export declare const DEFAULT_CACHEABLE_COMMANDS: string[];
+/** Set to `1` for the standing equivalent of `--no-cache`: skip the lookup, still record on success. */
 export declare const NO_CACHE_ENV_VAR = "NMR_NO_CACHE";
+/** Carries one run's identity down the spawned chain, so an entry can name the run that vouched for it. */
 export declare const RUN_ID_ENV_VAR = "NMR_RUN_ID";
+/** Carries the top-level tree snapshot down the spawned chain, so one invocation hashes the tree once. */
 export declare const TREE_SNAPSHOT_ENV_VAR = "NMR_TREE_SNAPSHOT";
+/**
+ * Restamps a recalled entry's retention with the run that is replaying it, so an excerpt this run certified
+ * can join the assembly a composite above it records.
+ *
+ * A recall certifies as surely as a recording does: the pass key matched, so the excerpt describes this tree,
+ * and the caller reaches this only where the retention key matched too, so it describes this presentation
+ * environment. Everything else the entry records stands -- the instant and the duration belong to the run that
+ * earned the pass, and a recall must not make it read as later or longer than it was.
+ *
+ * A cache that cannot be written is not worth failing a green run over, so that failure goes to the debug note.
+ */
 export declare function certifyRetention(options: {
     anchorDir: string;
     command: string;
@@ -56,6 +108,14 @@ export declare function certifyRetention(options: {
     runId: string;
     stderr: Writable;
 }): Promise<void>;
+/**
+ * Folds everything that can change what a command concludes into one key: the tree's content, the command
+ * string that would run, the scope it would run in, nmr's own version, the interpreter, what is installed, and
+ * the environment variables a check can read. A hit is this key matching a recorded one, so an ingredient left
+ * out here is an ingredient that could change while the cache still claims a pass.
+ *
+ * Reports a reason instead of a key when the install fingerprint cannot be read, which disables the gate.
+ */
 export declare function computeCacheKey(options: {
     anchorDir: string;
     command: string;
@@ -72,26 +132,105 @@ export declare function computeCacheKey(options: {
     ok: false;
     reason: string;
 };
+/**
+ * Folds what changes a transcript without changing a conclusion onto the pass key: the channel each of the
+ * command's output streams ran on, and the environment variables a tool presents itself through.
+ *
+ * Taking the pass key as an ingredient rather than recomputing its parts is what keeps the two from drifting
+ * apart. The channel kind is what keeps a run at a terminal from replaying a piped recording; folding in raw
+ * TTY-ness instead would be wrong under quiet mode, where the child sees pipes at a terminal and the
+ * transcript is reproducible.
+ */
 export declare function computeRetentionKey(options: {
     channels: OutputChannels;
     env: NodeJS.ProcessEnv;
     passKey: string;
 }): string;
+/** Renders a snapshot for the environment of every process below this one. */
 export declare function encodeTreeSnapshot(snapshot: TreeSnapshot): string;
+/**
+ * Names a covered package whose output differs between two observations of it, or `undefined` when every
+ * package agrees. A package that has appeared or disappeared between them counts as a disagreement, because
+ * the output the earlier observation describes is not the output the later one found.
+ */
 export declare function findStaleBuildOutput(earlier: Record<string, string>, later: Record<string, string>): string | undefined;
+/**
+ * Renders the warning for a `--no-cache` that landed after the command name, where it is an argument to the
+ * command rather than a flag to nmr. Passing it on unchanged is the honest thing to do with an argument, so
+ * the warning is all that separates this from a silently un-bypassed run.
+ */
 export declare function formatMisplacedNoCacheWarning(command: string): string;
+/**
+ * Reports whether a command's passes are recorded at all, which is what separates a command with no recording
+ * from one that could never have had one.
+ *
+ * A hook is excluded here rather than at one caller: it is not a command anyone asks for, so nothing records
+ * it, and a repo naming one in `extraCommands` must not make the gate and a reader of its entries disagree.
+ */
 export declare function isCacheableCommand(checkCache: CheckCacheConfig | undefined, command: string): boolean;
+/**
+ * Reads the state of the build output nmr's own build covers. Build output is git-ignored, so the tree hash
+ * says nothing about it: a `ci` whose `build` constituent is cached would otherwise skip on a tree whose `dist`
+ * had been deleted, or whose `dist` was compiled from a different tree, and hand back a green exit over a
+ * repository that cannot run.
+ *
+ * A package whose `build` or `compile` is overridden emits somewhere this does not know about, so it is left
+ * out rather than made a permanent miss.
+ */
 export declare function readBuildOutputState(monorepoRoot: string, config: NmrConfig): Promise<BuildOutputState>;
+/**
+ * Reads the entry recorded for one command at one scope, or `undefined` when there is none to trust.
+ *
+ * Retention is vouched for separately from the pass it rides on: an excerpt of a shape this cannot read is
+ * dropped, leaving a pass that skips cleanly and reports its verdict alone. Voiding the pass instead would
+ * cost a full run to avoid a line nobody would have printed.
+ */
 export declare function readCheckCacheEntry(options: {
     anchorDir: string;
     command: string;
     monorepoRoot: string;
 }): Promise<CheckCacheEntry | undefined>;
+/**
+ * Reads the whole output one recorded pass retained, or `undefined` where it retained none.
+ *
+ * Held to nothing on its own: the entry beside it is what says which tree the bytes describe, and a caller
+ * that has not matched the entry's key is reading a transcript of some other tree.
+ */
 export declare function readTranscript(ref: EntryRef): Promise<string | undefined>;
+/**
+ * Makes the transcript beside one entry be exactly what this pass retained, removing what an earlier pass
+ * left when this one retained nothing.
+ *
+ * A composite retains nothing of its own, so without the removal a leaf's transcript would stand beside an
+ * entry that never produced it, and `--log` would date another run's bytes by this one's instant.
+ */
 export declare function recordTranscript(ref: EntryRef, transcript: string | undefined): Promise<void>;
+/** Removes every recorded pass for a monorepo, or for a standalone package outside one. */
 export declare function removeCheckCache(scopeDir: string): Promise<void>;
+/**
+ * Merges a repo's `checkCache` configuration into the default set. Extending rather than replacing means
+ * declaring one command cannot silently drop the defaults; excluding is how a repo retires a name whose chain
+ * turned out to do more than report an exit status.
+ */
 export declare function resolveCacheableCommands(checkCache: CheckCacheConfig | undefined): Set<string>;
+/**
+ * Resolves the identity of the run this invocation belongs to: the one an ancestor nmr process passed down,
+ * and otherwise a fresh one, this invocation being where the run starts.
+ *
+ * Unbounded where the tree snapshot is bounded by a HEAD comparison: a process that outlives its run hands a
+ * stale identity to the invocations it later makes, and what keeps that harmless is the tree hash every
+ * constituent entry is held to before its excerpt joins an assembly.
+ */
 export declare function resolveRunId(env: NodeJS.ProcessEnv): string;
+/**
+ * Resolves the tree snapshot this invocation gates on: the one a parent nmr process already took, when there
+ * is one, and otherwise a fresh hash of the working tree. Reports a reason instead when no snapshot can be
+ * had, which disables the gate.
+ *
+ * The monorepo root must be the git toplevel. A repository holding the monorepo inside a subdirectory has
+ * content outside it that the checks may still read, and a hash covering more than the monorepo would move
+ * for edits that cannot affect it.
+ */
 export declare function resolveTreeSnapshot(options: {
     monorepoRoot: string;
     env: NodeJS.ProcessEnv;
@@ -102,10 +241,16 @@ export declare function resolveTreeSnapshot(options: {
     ok: false;
     reason: string;
 };
+/** Records a pass, replacing whatever this command last recorded at this scope. */
 export declare function writeCheckCacheEntry(options: {
     anchorDir: string;
     command: string;
     entry: CheckCacheEntry;
     monorepoRoot: string;
 }): Promise<void>;
+/**
+ * Writes a note explaining a gate decision, but only when `NMR_DEBUG=1`. The gate is silent by default: a
+ * reason to run is not news, and a line per invocation explaining why nothing was skipped would bury the
+ * output of the command that did run.
+ */
 export declare function writeDebugNote(message: string, env: NodeJS.ProcessEnv, stderr: Writable): void;

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