@williamthorsen/nmr 0.39.0 → 0.40.0

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

@@ -2,9 +2,9 @@ import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 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. */
+/** A recorded pass: what ran, on which tree, and how long it took. */
 export interface CheckCacheEntry {
-    /** The full cache key the pass was recorded under; a hit is this matching the key computed now. */
+    /** The full cache key under which the pass was recorded; a hit is this key matching the key computed now. */
     key: string;
     treeHash: string;
     headSha: string;
@@ -15,12 +15,12 @@ export interface CheckCacheEntry {
     /** 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.
+     * The build digest that each covered package's output had when the pass was recorded. Build output is
+     * git-ignored, so the tree hash cannot describe it; comparing these separates output built from this tree from
+     * output that 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. */
+    /** What a skip replays in place of the run that 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. */
@@ -39,11 +39,11 @@ export interface ReplayLine {
  * 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.
+ * A list rather than one excerpt: a composite's entry contains its constituents' lines, and a nested one's are
+ * spliced into its parent's, after which the attribution cannot be re-derived from the entry that contains 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.
+ * The witness admits a constituent's line into the assembly that 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;
@@ -54,7 +54,7 @@ export interface Retention {
 export interface BuildOutputState {
     /** Covered packages whose output is absent. */
     missingPackages: string[];
-    /** The digest of the inputs each covered package's output was built from, keyed by package name. */
+    /** The digest of the inputs from which each covered package's output was built, keyed by package name. */
     digests: Record<string, string>;
 }
 /** The parts of the running interpreter that can change what a check concludes. */
@@ -68,7 +68,7 @@ export interface TreeSnapshot {
     hash: string;
     headSha: string;
 }
-/** The interpreter this process is running on, folded into every key and recorded alongside every pass. */
+/** The interpreter on which this process is running, 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";
@@ -76,29 +76,30 @@ 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
+ * Excluded commands: `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` have a cache
+ * of their own. `fix`, `fmt`, `lint`, and `upgrade` mutate the tree about which they are asked. `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. */
+/** Passes one run's identity down the spawned chain, so that 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. */
+/** Passes the top-level tree snapshot down the spawned chain, to make one invocation hash the tree only 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.
+ * Restamps a recalled entry's retention with the run that is replaying it, so that an excerpt certified by this
+ * run can join the assembly recorded by a composite above it.
  *
- * 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 recall certifies as surely as a recording does. Because the pass key matched, the excerpt describes this
+ * tree; because the caller calls this only when the retention key matched too, the excerpt also 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.
+ * A cache that cannot be written is not worth failing a green run over: `certifyRetention` reports that failure
+ * in the debug note.
  */
 export declare function certifyRetention(options: {
     anchorDir: string;
@@ -111,8 +112,8 @@ export declare function certifyRetention(options: {
 }): 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
+ * string that would run, the scope in which it would run, nmr's own version, the interpreter, what is installed,
+ * and the environment variables that 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.
@@ -134,13 +135,12 @@ export declare function computeCacheKey(options: {
     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.
+ * Folds what changes a transcript without changing a conclusion onto the pass key: the channel on which each of
+ * the command's output streams ran, and the environment variables through which a tool presents itself.
  *
- * 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.
+ * The channel kind keeps a run at a terminal from replaying a piped recording. It is the channel's kind and not
+ * whether a terminal is attached: under quiet mode the child writes to pipes at a terminal, and its transcript
+ * is reproducible.
  */
 export declare function computeRetentionKey(options: {
     channels: OutputChannels;
@@ -152,39 +152,38 @@ 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.
+ * the output that the earlier observation describes is not the output that the later one found.
  */
 export declare function findStaleBuildOutput(earlierDigests: Record<string, string>, laterDigests: 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.
+ * Renders the warning for a `--no-cache` that appears after the command name, which makes it an argument to
+ * the command rather than a flag to nmr. nmr passes the argument on unchanged, so the warning is the only sign
+ * that nmr did not read it.
  */
 export declare function formatMisplacedNoCacheWarning(command: string, style: OutputStyle): 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.
+ * Reports whether a command's passes are recorded at all, which separates a command without a 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.
+ * A hook is never cacheable, even when a repo names one in `extraCommands`: nothing records a hook, and
+ * excluding it here keeps the gate and every reader of its entries in agreement.
  */
 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
+ * Reads the state of the build output that 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.
+ * Because a package whose `build` or `compile` is overridden emits to a location that this function does not
+ * know about, 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.
+ * Retention is vouched for separately from the pass that contains it: an excerpt of a shape that this function
+ * cannot read is dropped, leaving a pass that skips cleanly and reports its verdict alone.
  */
 export declare function readCheckCacheEntry(options: {
     anchorDir: string;
@@ -192,9 +191,9 @@ export declare function readCheckCacheEntry(options: {
     monorepoRoot: string;
 }): Promise<CheckCacheEntry | undefined>;
 /**
- * Reads the whole output one recorded pass retained, or `undefined` where it retained none.
+ * Reads the whole output that one recorded pass retained, or `undefined` when it retained none.
  *
- * Held to nothing on its own: the entry beside it is what says which tree the bytes describe, and a caller
+ * Held to nothing on its own: the entry beside it 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>;
@@ -202,33 +201,32 @@ export declare function readTranscript(ref: EntryRef): Promise<string | undefine
  * 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
+ * A composite retains nothing of its own, so without the removal a leaf's transcript would remain 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.
+ * Merges a repo's `checkCache` configuration into the default set: `extraCommands` adds to the defaults, and
+ * `excludeCommands` removes a command whose chain does 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.
+ * Resolves the identity of the run to which this invocation belongs: the one that an ancestor nmr process passed
+ * down, and otherwise a fresh one, because the run starts at this invocation.
  *
- * 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.
+ * Unbounded, whereas the tree snapshot is bounded by a HEAD comparison: a process that outlives its run hands a
+ * stale identity to the invocations that it later makes, and the tree hash keeps that harmless, because every
+ * constituent entry is held to it 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.
+ * Resolves the tree snapshot on which this invocation gates: the one that a parent nmr process already took,
+ * when there is one, and otherwise a fresh hash of the working tree. Reports a reason instead when a snapshot
+ * cannot be taken, which disables the gate.
  *
- * The monorepo root must be the git toplevel. A repository holding the monorepo inside a subdirectory has
+ * The monorepo root must be the git toplevel. A repository containing 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.
  */

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

@@ -6,42 +6,42 @@ export interface BuildOptions {
     ignorePatterns?: string[];
     outdir?: string;
 }
-/** The pair of directories a build publishes through, both siblings of the emit directory. */
+/** The pair of directories through which a build publishes, both siblings of the emit directory. */
 export interface ScratchDirs {
     previousDir: string;
     stagingDir: 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.
+ * Directories holding test scaffolding rather than published code, excluded from entry-point selection so that a
+ * package does not publish its own helpers. The list differs from the vitest factory's `COVERAGE_EXCLUDE`, which
+ * leaves `test-utils/` inside the coverage include set, and neither list 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.
+ * surviving entry points import, which keeps a production module that uses a helper from emitting a dangling
+ * specifier. Widening this list can therefore only drop files that production code does not import.
  */
 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.
+ * Reports whether the output that a build of `packageDir` would produce is currently on disk. Applies the build's
+ * own rule, on the same options that 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 does not expect any output, and
+ * reports present. Passing options that the build was not given 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.
+ * Reports whether the output that a previous build would have produced is still on disk. Because entry points
+ * that emit nothing do not expect any output, 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 creates an outdir, so the test 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.
+ * Returns the digest of the inputs from which the output currently on disk was built, or `undefined` when the
+ * package has never been built. Two packages containing the same sources report the same digest, and a package
+ * whose output came from a different tree reports a different one, which distinguishes a stale `dist` from a
+ * current one.
  */
 export declare function readBuildDigest(packageDir: string): Promise<string | undefined>;
 /**
@@ -49,35 +49,34 @@ export declare function readBuildDigest(packageDir: string): Promise<string | un
  * 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.
+ * Three things keep the path pointing at every previously written entry: the `.hash` extension, the
+ * package's own directory name as the slug, and the absence of `discriminators`, which would otherwise be added
+ * to the digest. Changing any of them leaves every entry on disk unreachable.
  */
 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
+ * Resolves the two scratch directories through which a build publishes: `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 that 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.
+ * The names are fixed rather than unique because the build removes both before use. A unique name would need a
+ * sweep to accomplish that removal, and a sweep cannot tell a directory orphaned by a killed run from one that a
+ * concurrent build is still writing. Because a directory left behind by a failed build is cleared the same way,
+ * the failure path does not need any 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
+ * Resolves the fingerprint of the nmr compiling `packageDir`, the `BuildToolchain` member that identifies nmr. It
+ * is nmr's own build digest when one is on disk, which changes on a dev-loop edit that 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.
+ * A build of nmr itself takes the version too. Its digest is the entry that the build is about to overwrite, so
+ * including it would make the key a function of its own previous value, which never stops changing: nmr would
+ * rebuild on every invocation and change the fingerprint that 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.
+ * Because the fingerprint names the nmr that produced the output, not the sources in `src`, a package compiled by
+ * the pre-rebuild binary keeps the old fingerprint and rebuilds on the next run.
  */
 export declare function resolveToolchainFingerprint(packageDir: string, selfDir?: string): Promise<string>;

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

@@ -1,41 +1,40 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 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.
+ * The toolchain from which a build's emit comes: the resolved compiler and the nmr running it. `computeBuildHash`
+ * folds both into the build hash, because the same sources can compile to different output under a different
+ * compiler or nmr.
  */
 export interface BuildToolchain {
     compilerVersion: string;
     fingerprint: string;
 }
-/** What a build needs beyond its sources: the options shaping the emit, and the style it reports in. */
+/** What a build needs beyond its sources: the options shaping the emit, and the style in which it reports. */
 export interface BuildPackageOptions extends BuildOptions {
     style: OutputStyle;
 }
 /**
  * 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.
+ * runnable relative `.js` specifiers in both outputs. Skips the build only when every input is
+ * unchanged 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
+ * 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: BuildPackageOptions): 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.
+ * The file list is sorted so that the digest is order-invariant, and each path is folded in so that renames are
+ * detected.
  */
 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.
+ * each base that 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 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 be released. The
+ * relative paths give `computeBuildHash` a location-independent path string to fold into the digest.
  */
 export declare function resolveTsconfigChain(packageDir: string, configFileName?: string): string[];

package/dist/esm/commands/build.js

@@ -142,7 +142,7 @@ function resolveEmitDir(packageDir, outdir) {
         relativePathFromPackage.startsWith('..') ||
         path.isAbsolute(relativePathFromPackage)) {
         throw new Error(`nmr-compile: refusing to build into '${outdir}', which does not resolve inside the package. ` +
-            'The build replaces its output directory on each emit, so the directory must sit below the package root.');
+            'The build replaces its output directory on each emit, so the directory must be below the package root.');
     }
     return resolvedDir;
 }
@@ -216,7 +216,7 @@ function rewriteSpecifiers(outputFile, text, compilerOptions, sourceRoot) {
     if (edits.length === 0) {
         return text;
     }
-    const orderedEdits = [...edits].sort((a, b) => b.startOffset - a.startOffset);
+    const orderedEdits = edits.toSorted((a, b) => b.startOffset - a.startOffset);
     let updatedText = text;
     for (const edit of orderedEdits) {
         updatedText = updatedText.slice(0, edit.startOffset) + edit.text + updatedText.slice(edit.endOffset);
@@ -309,7 +309,7 @@ function collectAliasPrefixes(compilerOptions) {
 }
 function describeEmit(fileCount, outdir) {
     if (fileCount === 0) {
-        return 'Emitted no output.';
+        return 'Did not emit any output.';
     }
     return `Compiled ${fileCount} files to ${outdir.replace(/\/+$/u, '')}.`;
 }

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

@@ -1,7 +1,8 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 /**
- * 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.
+ * Removes a package's build output and the build-cache entry that describes it, so the package does not keep
+ * any state that would make the next build skip. Removal is idempotent: An already-clean package is a silent
+ * no-op.
  */
 export declare function cleanPackage(packageDir: string, style: OutputStyle): Promise<void>;
 /**
@@ -10,9 +11,8 @@ export declare function cleanPackage(packageDir: string, style: OutputStyle): Pr
  * 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.
+ * This is the default `clean` script, and it is published as a bin because, under pnpm's isolated layout,
+ * `pnpm exec` resolves only the bins of the consuming project's direct dependencies: pnpm links nmr's own bins
+ * into the consumer's `node_modules/.bin`, but not the bins of nmr's dependencies.
  */
 export declare function runClean(cwd: string, style: OutputStyle): Promise<void>;

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

@@ -12,7 +12,7 @@ export interface EnsurePrepublishHooksResult {
 }
 export declare const DEFAULT_HOOK = "npm run build";
 /**
- * Check (and optionally fix) whether all publishable workspace packages
+ * Checks (and optionally fixes) whether all publishable workspace packages
  * have a `prepublishOnly` script.
  */
 export declare function ensurePrepublishHooks(monorepoRoot: string, options: {
@@ -21,10 +21,10 @@ export declare function ensurePrepublishHooks(monorepoRoot: string, options: {
     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.
+ * Reports one line per publishable package and closes with a summary of the run. Private packages appear in
+ * neither: They publish nothing, so they do not need a `prepublishOnly`.
  *
- * Every line goes to stdout, a failure's included, and the exit code is what carries a failure. A report split
- * across two streams leaves no reader holding the whole list.
+ * Every line goes to stdout, a failure's included, and the exit code signals a failure. When a report is split
+ * across two streams, a reader of either stream does not see the whole list.
  */
 export declare function reportPrepublishHooks(result: EnsurePrepublishHooksResult, hookCommand: string, style: OutputStyle): void;

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

@@ -13,7 +13,7 @@ export type ResolveTargetsResult = {
     error: string;
 };
 /**
- * Formats or checks the files git reports for `cwd`, and returns the exit code to report.
+ * Formats or checks the files that 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
@@ -26,11 +26,11 @@ export declare function runFmt(argv: string[], cwd?: string): number;
  * 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.
+ * Because file selection is anchored at `cwd` and ignore discovery at the repository root, scoping follows
+ * `cwd` while the ignore rules applied to a given file are the same from every directory.
  *
- * `pathspecs` narrow the selection and are passed to git verbatim, so they carry git pathspec semantics
- * rather than shell glob semantics.
+ * `pathspecs` narrow the selection and are passed to git verbatim: They have git pathspec semantics rather
+ * than shell glob semantics.
  */
 export declare function resolveFormatTargets(cwd: string, pathspecs?: string[]): ResolveTargetsResult;
 /** @internal */
@@ -40,15 +40,15 @@ export interface RunPrettierOptions {
     files: string[];
     ignorePaths: string[];
     cwd: string;
-    /** Overridable so the multi-batch path is reachable without a fixture that hits the real ceiling. */
+    /** Overridable so that 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`.
+ * Because the CLI runs under this process's own Node rather than through its shebang, it does not depend
+ * on the file's execute bit or on PATH containing a `node`.
  *
  * @internal
  */

package/dist/esm/commands/fmt.js

@@ -32,7 +32,7 @@ export function runFmt(argv, cwd = process.cwd()) {
     const { files, ignorePaths } = resolvedTargets.targets;
     if (files.length === 0) {
         if (parsedArgs.pathspecs.length > 0) {
-            reportError(`nmr-fmt: no formattable files matched: ${parsedArgs.pathspecs.join(', ')}`);
+            reportError(`nmr-fmt: the pathspecs did not match any formattable file: ${parsedArgs.pathspecs.join(', ')}`);
             return 1;
         }
         return 0;

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

@@ -1,12 +1,10 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 /**
- * Reports the catalogued dependencies a package-scoped upgrade pass cannot see.
+ * Reports the catalogued dependencies that a package-scoped upgrade pass does not read.
  *
- * 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.
+ * The upgrade tool reads `pnpm-workspace.yaml` only when the file is in the working directory, so a pass run
+ * inside a package drops every dependency declared by a catalog -- and the tool reports a package whose
+ * dependencies are all catalogued as up to date. This report names them, and the root from which a covering
+ * pass runs, to keep the reader from taking that result to mean that every dependency is up to date.
  */
 export declare function reportCatalog(cwd: string, style: OutputStyle): void;

package/dist/esm/commands/report-catalog.js

@@ -15,7 +15,7 @@ export function reportCatalog(cwd, style) {
     if (dependencies.length === 0) {
         return;
     }
-    console.warn(formatGlyphLine(NMR_GLYPHS, style, 'catalog', 'WARN: A package-scoped upgrade does not read the catalogs these come from:'));
+    console.warn(formatGlyphLine(NMR_GLYPHS, style, 'catalog', 'WARN: A package-scoped upgrade does not read the catalogs from which these come:'));
     for (const { name, specifier } of dependencies) {
         console.warn(`- ${name} → ${specifier}`);
     }

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

@@ -2,7 +2,5 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
 /**
  * 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, style: OutputStyle): void;

package/dist/esm/commands/report-overrides.js

@@ -29,7 +29,7 @@ function rejectLegacyOverrides(monorepoRoot) {
         return;
     }
     throw new UserError([
-        'pnpm 11 reads no `pnpm.overrides` from package.json, so these pin nothing while an upgrade run with `--write` goes on rewriting them:',
+        'pnpm 11 does not read `pnpm.overrides` from package.json, so these pin nothing while an upgrade run with `--write` goes on rewriting them:',
         ...legacyOverrides.map(([name, version]) => `- ${name} → ${String(version)}`),
         'Move them to the `overrides` block in pnpm-workspace.yaml, quoting each version, or run `pnpx codemod run pnpm-v10-to-v11`.',
     ].join('\n'));