@williamthorsen/nmr 0.34.0 → 0.36.0

package/README.md

@@ -3,25 +3,36 @@
 Context-aware script runner for pnpm monorepos. Ships an `nmr` (node-monorepo run) binary that provides centralized, consistent script execution across workspace packages and the monorepo root.
 
 <!-- section:release-notes -->
-## Release notes — v0.34.0 (2026-08-24)
+## Release notes — v0.36.0 (2026-09-08)
 
 ### 🎉 Features
 
-- 🚨 **Breaking:** Make defineVitestConfig resolve from source and isolate git (#749)
+- Report a package whose tarball would omit its changelog (#768)
 
-  Adds two defaults to `defineVitestConfig` and `defineRootVitestConfig` in `@williamthorsen/nmr/vitest`: Workspace packages resolve through their `source` export condition, so a suite runs without a prior build; and every project loads a setup file that keeps the developer's git configuration out of the subprocesses a test spawns.
+  Adds ReadyUp checks to verify that every published package bundles its changelog files: the human-readable `CHANGELOG.md` and the machine-readable `changelog.json`.
 
-  Each is individually opt-out-able through the new `isolateGit` and `resolveFromSource` options. A consumer's own `resolve.conditions` and `setupFiles` compose alongside what the factory supplies.
+- Reject a checkCache command name that matches no command (#778)
 
-  Migration: A workspace package declaring a `source` condition is resolved from source in tests that previously read its `dist`. A package that publishes only its build output takes a bespoke condition name instead, as `@williamthorsen/nmr-core` does with `nmr-source`.
+  Modifies `nmr` so that it rejects a `checkCache.extraCommands` or `checkCache.excludeCommands` name that matches no command, so a misspelt entry fails config load instead of silently having no effect.
 
-### 🐛 Bug fixes
+  Modifies `nmr` so that it resolves names listed in either field against nmr's default scripts, the repo config's script registries, and each package's `package.json` scripts, so a name that only a package declares is accepted.
+
+  Migration: Correct or remove any `checkCache.extraCommands` or `checkCache.excludeCommands` entry that names no command, and any entry that names a hook, which is rejected too. The error reports the field, the offending name, and the closest command where there is one.
+
+- Report a bin target that is not a committed wrapper (#780)
 
-- Stop nmr upgrade from timing out against a proxying registry (#744)
+  - Adds `every bin target is a committed wrapper` to nmr's readyup kit, which reports a workspace `bin` target naming a path under `dist/`, or one that git does not track, because pnpm links a package's bins before anything is built and never retries a failed link.
+  - Adds `every bin wrapper's build-output target is covered by files`, which reports a wrapper loading build output that `files` omits, since that publishes a bin resolving to nothing.
+
+  Migration: Replace a `bin` target naming a path under `dist/` with a committed wrapper under `bin/` that imports the build entry, commit the wrapper, and extend `files` to cover the output that the wrapper loads.
+
+### 🐛 Bug fixes
 
-  Fixes an issue where `nmr upgrade` timed out intermittently against a registry that proxies npm. Every `upgrade` script now calls taze with a 30-second request timeout in place of the 5-second default; a different request timeout specified by the caller is respected.
+- Keep global git ignore rules and attributes out of test subprocesses (#773)
 
-  The ReadyUp kit bundled with nmr now warns when a taze config sets a value that the taze CLI will not use.
+  Fixes an issue where a test that spawns `git` read ignore rules and attributes from outside the repository, so a suite could pass or fail on whatever a developer or their machine happened to have configured. The setup file that `defineVitestConfig` loads by default now isolates both, alongside the git configuration already covered.
+  
+  Migration: Where a test needs its own `core.excludesFile` or `core.attributesFile`, pass it on the invocation as `git -c core.excludesFile=<path>`. An environment-injected key now outranks repository-local config.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -49,7 +60,7 @@ From a package directory:
 
 ```bash
 nmr test  # Run tests for the current package
-nmr build # Compile to .js and .d.ts in one pass
+nmr build # Compile to .js and .d.ts
 nmr check # Typecheck, format check, lint check, and tests
 ```
 
@@ -511,6 +522,10 @@ export default defineConfig({
 
 `extraCommands` extends the default set rather than replacing it, so naming one command cannot silently drop the rest; `excludeCommands` is applied afterwards, so a name in both is excluded. `enabled: false` turns the gate off entirely. The key is `checkCache`, in the monorepo-root config.
 
+**A name in either list must resolve to a command**, whether through nmr's defaults, the repo config's script records, or a package's own `package.json` scripts. Both lists are read by name alone, so a misspelt entry would otherwise be inert: the command it meant to name would go on running, indistinguishable from one that cannot be cached at all. A name that resolves nowhere fails config load, naming the closest command where there is one. A hook name is rejected too, since a hook is never gated on its own -- it runs as part of the chain of the command it wraps, and is skipped or run with it.
+
+The test is resolvability rather than membership of the cacheable set, so an `excludeCommands` entry keeps standing after a release moves its name out of the defaults.
+
 ```ts
 export default defineConfig({
   output: {
@@ -801,7 +816,7 @@ Position determines ownership: flags before the command name are nmr's own, and
 ```bash
 # From a package directory
 nmr test  # Run workspace test script
-nmr build # Compile to .js and .d.ts in one pass
+nmr build # Compile to .js and .d.ts
 
 # From the monorepo root
 nmr test    # Root tests + recursive workspace tests
@@ -878,7 +893,7 @@ nmr-clean
 
 ### `nmr-compile`
 
-Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` and `.d.ts` in one pass. Because the compiler parses each source file, every relative import form — static, re-export, dynamic `import()`, and bare side-effect — is rewritten from `.ts` to `.js` in both outputs, and `.ts` occurrences inside strings and comments are left intact. tsconfig `paths` aliases are resolved to runnable relative `.js` specifiers in both outputs, sourced from the package's tsconfig. An aliased import whose target resolves outside the package's `src/` and is not resolvable without the alias mapping fails the build with a diagnostic, rather than being emitted verbatim to produce output that fails at runtime. The build is skipped when no input has changed and the previous output is still on disk (the key is cached under `node_modules/.cache/nmr-compile/`, outside the published output). Deleting the output by any means — `nmr clean`, `rm -rf dist`, `git clean` — therefore forces a rebuild rather than a skip. This is the default `compile` script — run it from a package directory.
+Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` from one program and `.d.ts` from a second that reuses it. The package's own `removeComments` governs the `.js` emit; the declarations emit forces it off, so `.d.ts` files carry their doc comments either way. Because the compiler parses each source file, every relative import form — static, re-export, dynamic `import()`, and bare side-effect — is rewritten from `.ts` to `.js` in both outputs, and `.ts` occurrences inside strings and comments are left intact. tsconfig `paths` aliases are resolved to runnable relative `.js` specifiers in both outputs, sourced from the package's tsconfig. An aliased import whose target resolves outside the package's `src/` and is not resolvable without the alias mapping fails the build with a diagnostic, rather than being emitted verbatim to produce output that fails at runtime. The build is skipped when no input has changed and the previous output is still on disk (the key is cached under `node_modules/.cache/nmr-compile/`, outside the published output). Deleting the output by any means — `nmr clean`, `rm -rf dist`, `git clean` — therefore forces a rebuild rather than a skip. This is the default `compile` script — run it from a package directory.
 
 **What it compiles.** Entry points are `src/**/*.ts` less the directories that hold test scaffolding rather than shipped code: `__fixtures__/`, `__mocks__/`, `__tests__/`, and `test-utils/`. Add to that list per package with [`build.extraIgnorePatterns`](#package-level-configuration). Ignoring a directory drops it as an _entry point_, not from the emit: the compiler still emits whatever the surviving entry points import, so a helper that production code uses is still compiled and its importer never emits a dangling specifier. This list is deliberately not the Vitest [coverage exclusions](#what-the-config-excludes) — helpers live in `test-utils/` precisely so they stay covered.
 
@@ -937,7 +952,7 @@ ensure-prepublish-hooks
 
 ## Conformance checks
 
-nmr publishes a `readyup` kit that checks a consuming repo against the current release: the shared Vitest and Prettier configs, the workspace layout, the root script registry, the [test-tier convention](#test-tiers), and that no `package.json` in the tree declares a `pnpm` field, which pnpm 11 reads no key from. Those settings belong in `pnpm-workspace.yaml`, and `pnpx codemod run pnpm-v10-to-v11` moves them. The kit ships inside the package, so it checks against the nmr version installed rather than whatever a repository ref happens to point at, and a tier added or renamed in nmr reaches the repo on upgrade.
+nmr publishes a `readyup` kit that checks a consuming repo against the current release: the shared Vitest and Prettier configs, the workspace layout, the root script registry, the [test-tier convention](#test-tiers), that every `bin` target is a committed wrapper rather than build output that pnpm cannot link at install time, that `files` covers the output each wrapper loads, and that no `package.json` in the tree declares a `pnpm` field, which pnpm 11 reads no key from. Those settings belong in `pnpm-workspace.yaml`, and `pnpx codemod run pnpm-v10-to-v11` moves them. The kit ships inside the package, so it checks against the nmr version installed rather than whatever a repository ref happens to point at, and a tier added or renamed in nmr reaches the repo on upgrade. A repo that wants the tier convention in its own gate rather than in a command run by hand declares the [conventions check](#gating-the-test-file-conventions) instead, which also covers the half the kit does not.
 
 Add `readyup` as a devDependency, then name nmr in its config:
 
@@ -1059,7 +1074,7 @@ import { defineVitestConfig } from '@williamthorsen/nmr/vitest';
 export default defineVitestConfig();
 ```
 
-`vitest` is a peer dependency (`>=4.0.0 <5`), declared optional — the consuming repo provides it, and repos that never import this subpath are unaffected.
+`vitest` is a peer dependency (`>=4.0.0 <5`), declared optional — the consuming repo provides it, and repos that never import this subpath are unaffected. `vite` is an optional peer as well (`>=8.0.0 <9`), required only by the [`tsconfigPaths` setting](#resolving-through-tsconfig-paths); a repo that declares a `vite` of its own below that range sees an unmet-peer warning whether or not it sets the flag.
 
 ### Test tiers
 
@@ -1086,7 +1101,7 @@ vitest                               # every project
 
 **Every test file names its tier**, in the form `<subject>[.<aspect>].<tier>.test.ts`. Only the segment immediately before `.test.` selects a project, so an earlier one is free for documentation: `resolveConfig.packaged.unit.test.ts` reads as a companion to `resolveConfig.unit.test.ts` and still names `unit`.
 
-`unit` is defined by subtracting the tiers rather than by an allow-list of infixes, so a file such as `parser.smoke.test.ts` runs under `unit` instead of being silently dropped. That is a safety net, not a licence to omit the tier: a file whose tier segment is missing or misspelt runs under `unit` and reports success, so no test run distinguishes it from a conformant one. [nmr's readyup kit](#conformance-checks) reports those files, which is the only thing that does.
+`unit` is defined by subtracting the tiers rather than by an allow-list of infixes, so a file such as `parser.smoke.test.ts` runs under `unit` instead of being silently dropped. That is a safety net, not a licence to omit the tier: a file whose tier segment is missing or misspelt runs under `unit` and reports success, so no test run distinguishes it from a conformant one until the repo declares the [conventions check](#gating-the-test-file-conventions). In a repo that has not, [nmr's readyup kit](#conformance-checks) is what reports those files.
 
 `localhost` and `remote` have no test script of their own. They are declared anyway, so that a `*.remote.test.ts` file cannot fall into `unit` and run in the default gate unnoticed.
 
@@ -1094,12 +1109,46 @@ Every tier above `unit` carries a 30-second `testTimeout` and `hookTimeout`, whe
 
 To raise a budget for one tier and no other, use the `tiers` seam below. The `project` seam merges over both budgets as well, but like every option passed through it the value reaches all four projects at once -- raising a tier's budget raises `unit`'s with it. To lift the ceiling for a single file rather than a whole tier, pass a timeout to the individual test or hook, which stays the narrower tool.
 
+### Gating the test-file conventions
+
+Both halves of the convention are silent on their own: an untiered file runs under the residual `unit` and passes, and a file outside `__tests__` is collected by nothing at all. `@williamthorsen/nmr/tests` exports a check that reports both, which a repo declares from a one-line test of its own:
+
+```ts
+// __tests__/test-file-conventions.unit.test.ts
+import { checkTestFileConventions } from '@williamthorsen/nmr/tests';
+
+checkTestFileConventions();
+```
+
+It declares one suite with an assertion per half, each carrying the remedy that fixes it: the four tier names and the rename form, or the `__tests__` directory the file belongs in. The guard names its own tier like any other test file, so a misnamed guard reports itself.
+
+A repo linting with `vitest/require-hook` needs a disable directive on that call, which the rule reads as setup work where it declares the suite:
+
+```ts
+// eslint-disable-next-line vitest/require-hook -- the call declares the suite, where the rule reads it as setup work.
+checkTestFileConventions();
+```
+
+The sweep starts at the monorepo root rather than at the directory Vitest supplies, so one call covers the whole repo from whichever package the run began in. `rootDir` overrides that, for a check pointed at a tree other than the repo's own.
+
+An exported check rather than a step nmr runs for you, because nothing nmr runs reaches the whole tree: `nmr test` fans out per package, and a direct `vitest` invocation runs no nmr script at all. A test the repo owns also lets the repo scope what the sweep covers.
+
+`exclude` names directory basenames the sweep prunes at any depth, additive to the ones nmr always prunes:
+
+```ts
+checkTestFileConventions({ exclude: ['cypress', 'generated'] });
+```
+
+**Pass the same array to [`testCollectionExclude`](#what-the-config-excludes).** The two describe one scope, and naming a directory in only one is a defect in either direction. Pruned from the sweep alone, the directory's test files still run and still report nothing, which is the silence this check exists to end. Excluded from collection alone, the sweep reports files a consumer has no reason to act on.
+
+Expect the first run to fail in a repo that has never gated this. Vitest 4 excludes only `node_modules` and `.git` by default, so a `__tests__` tree under a generated or vendored directory is collected and runs today; naming that directory in both lists is the fix, rather than widening what nmr prunes for everyone.
+
 ### What the config supplies
 
 Two settings a workspace test runner needs almost universally are part of what the factory produces, so a config file declares neither:
 
 - **Workspace packages resolve from source.** `source` leads the emitted `resolve.conditions` and `ssr.resolve.conditions`, so a cross-package import reaches the dependency's `.ts` rather than its `dist/` and a suite runs without a prior build. A package declaring no such condition is unaffected.
-- **Git subprocesses are isolated.** Every project loads a setup file that points `GIT_CONFIG_GLOBAL` and `GIT_CONFIG_SYSTEM` at the null device and sets `GIT_CONFIG_NOSYSTEM`, so a test that spawns `git` reads neither the developer's identity nor a signing config that can block on a passphrase. It leads each project's `setupFiles`, ahead of every entry the layers add, because a shared setup establishes the environment the rest run in.
+- **Git subprocesses are isolated.** Every project loads a setup file that points `GIT_CONFIG_GLOBAL` and `GIT_CONFIG_SYSTEM` at the null device, sets `GIT_CONFIG_NOSYSTEM` and `GIT_ATTR_NOSYSTEM`, and injects `core.excludesFile` and `core.attributesFile` through `GIT_CONFIG_COUNT` and its key/value pairs, so a test that spawns `git` reads neither the developer's identity, nor a signing config that can block on a passphrase, nor their global ignore rules and attributes. Those last two need a step of their own: neither path is config-derived, so git resolves each from `$XDG_CONFIG_HOME/git/`, or from `~/.config/git/` where that variable is unset, whatever the config variables say. `GIT_CONFIG_GLOBAL` already replaces `$XDG_CONFIG_HOME/git/config`, so those two are the rest of what that directory supplies; the system attributes file at `$(prefix)/etc/gitattributes` is reached by no config variable at all, which is what `GIT_ATTR_NOSYSTEM` covers. Redirecting `XDG_CONFIG_HOME` would reach the per-user pair as well, and is not used, because other tools spawned by a test read that variable for configuration of their own: pnpm fails to start under `XDG_CONFIG_HOME=/dev/null`. An injected key outranks repository-local config, so a repository setting its own `core.excludesFile` is overridden under the isolation; a test needing its own value passes it on the invocation as `git -c core.excludesFile=...`, which outranks the injection. The setup file leads each project's `setupFiles`, ahead of every entry the layers add, because a shared setup establishes the environment the rest run in.
 
 Both defaults exist because omitting either is silent rather than loud: the tiers still exist and the suite still runs green, testing `dist/` and the developer's git identity instead. Turn either off through its own option, which folds across layers like any other, the last layer to declare it winning:
 
@@ -1113,6 +1162,20 @@ export default defineVitestConfig({ isolateGit: false, resolveFromSource: false
 
 **A package declaring a `source` condition must ship its sources.** Every nmr consumer now resolves that condition, so a published package whose `files` carries `dist` alone resolves to a path that is not in the tarball. A package that publishes only its build output takes a bespoke condition name instead, the way `@williamthorsen/nmr-core` uses `nmr-source` for the build's own bootstrap.
 
+### Resolving through tsconfig paths
+
+A third resolution setting sits alongside those two, and this one is off. `tsconfigPaths: true` emits Vite's `resolve.tsconfigPaths`, so a test reaches an aliased specifier through the `paths` its `tsconfig.json` declares, the way `tsc` does:
+
+```ts
+export default defineVitestConfig({ tsconfigPaths: true });
+```
+
+It folds across layers like the other two, the last layer to declare it winning. It needs no `ssr` counterpart the way a condition does: Vite holds this setting outside its per-environment resolve options, so the single key reaches the environment a test's own imports resolve through.
+
+**It is an opt-in because its silent direction is the reverse of the two defaults'.** Leaving it off fails loudly, with an unresolved import naming the specifier. Turning it on is the silent direction, for a repo that declares `paths` for `tsc` alone: a specifier that resolved through a package's `exports` starts resolving through the alias instead, and nothing in the run reports the switch. A repo declaring no `paths` is unaffected either way.
+
+**It requires Vite 8**, where `resolve.tsconfigPaths` arrived. nmr declares `vite` as an optional peer at `>=8.0.0 <9`, so a repo holding a stale `vite` of its own hears about it at install time. That check does not reach a repo whose only Vite comes in through Vitest's own dependency, and Vitest 4 accepts Vite 6 and 7: on those, the emitted key does nothing and the aliased import fails exactly as it would with the flag off.
+
 ### Customizing by scope
 
 Vitest applies some options at the root of a `projects` config and others per project, and placing one at the wrong level is silent rather than loud. The factory therefore takes separate override surfaces instead of one merged config:
@@ -1167,6 +1230,8 @@ Both factories fold any number of layers left to right: a later layer wins on a
 
 Order is the point where `setupFiles` is concerned, since a shared setup file establishes the environment the package's own then runs in. A later layer's `project` block likewise wins over an earlier layer's `tiers` target: the nearer config is the more deliberate.
 
+**A package's own `vite.config.ts` fills that one slot too.** Vitest searches for a config by ascending from the run root and stopping at the first directory holding any of `vitest.config.*` or `vite.config.*`, so a package carrying only a Vite config ends the search there and never reaches the root config. Within a directory `vitest.config.*` is tried first, which makes the fix a Vitest config beside the Vite one, calling `defineVitestConfig()` as any other package config does. Without it the package declares no projects and every tier-selecting command fails with `No projects matched the filter`, `nmr ci` among them. [nmr's readyup kit](#conformance-checks) reports a package in that state.
+
 **A path in a shared layer must be absolute.** Vitest resolves `setupFiles` against each project's own root, not against the module that declared the path, so a bare `'./vitest.setup.ts'` in a shared module names a different file in every package that consumes it -- and a package that happens to own a file by that name loads the wrong one instead of failing. The co-located form stays correct in a config file that declares the path directly.
 
 **Do not merge two returned configs.** `mergeConfig(defineVitestConfig(), defineVitestConfig(mine))` looks like the idiomatic recovery and fails at startup: both sides declare the same four project names, which Vitest rejects with `Project name "unit" ... is not unique`. Layers merge the factory's inputs instead, which is why they yield four projects however many fold.
@@ -1175,7 +1240,15 @@ A config file that omits the shared layer still loses those settings, silently -
 
 ### What the config excludes
 
-Collection skips `**/node_modules/**`, `**/.git/**`, and `**/dist/**`. Coverage skips `**/__{fixtures,mocks,tests}__/**`, `**/index.ts`, and `**/*.d.ts`.
+Collection skips `**/node_modules/**`, `**/.git/**`, `**/coverage/**`, and `**/dist/**`. Coverage skips `**/__{fixtures,mocks,tests}__/**`, `**/index.ts`, and `**/*.d.ts`.
+
+`testCollectionExclude` adds to the collection list. It takes directory basenames rather than globs, matched at any depth, so the same array serves the [conventions check](#gating-the-test-file-conventions):
+
+```ts
+export default defineVitestConfig({ testCollectionExclude: ['cypress', 'generated'] });
+```
+
+Every layer's entries are concatenated, and a name the shared config already prunes is emitted once. A repo needing a glob rather than a directory name has the `project` seam's own `exclude`.
 
 Because both seams concatenate, a consumer can add an exclusion but never remove one. A pattern therefore earns its place in these lists only by preventing a _silent_ failure, one a consumer cannot self-diagnose. A visible failure, such as a stray file sitting at 0% in the coverage report, is left to the consumer's own `project` seam.
 
@@ -1212,7 +1285,7 @@ The projects were once named `unit`, `integration`, and `app`, for what a test _
 2. Rename every `*.app.test.ts` onto the convention. `app` was never a tier, so keep it as the aspect segment and add the tier after it: `scaffold.app.test.ts` becomes `scaffold.app.unit.test.ts`.
 3. Replace `nmr test:integration` with `nmr test:tool`, and `nmr root:test:integration` with `nmr root:test:tool`, wherever a script or workflow names them.
 
-**A file left without a tier is a silent failure.** The residual `unit` claims it and it runs in the default gate -- green, with nothing reporting that the separation was lost. [nmr's readyup kit](#conformance-checks) reports every such file; a passing test run does not. Run it before treating the migration as done.
+**A file left without a tier is a silent failure.** The residual `unit` claims it and it runs in the default gate -- green, with nothing reporting that the separation was lost. Declare the [conventions check](#gating-the-test-file-conventions), which turns that state into a failing test run, or run [nmr's readyup kit](#conformance-checks), which reports every such file. Do one of the two before treating the migration as done.
 
 `nmr test` also runs the `tool` tier, which the old `test` excluded. Those tests previously ran in no default selection at all: `check`, `check:strict`, and `ci` all inherited the exclusion, so a green pipeline said nothing about them. Expect `nmr test` to take longer and to surface failures that were never gated.
 

package/agents/guidance/rulebooks/nmr.md

@@ -13,5 +13,5 @@ delivery: ambient
 - A check that already passed on the current working tree skips, printing `⏭️ <scope>: <command>: passed …` and, where the recalled run left one, `— replayed: <excerpt>` of what that run concluded. Any edit, addition, or deletion re-runs it, so read the replayed excerpt rather than paying for the answer again: never pass `--no-cache` to get a "real" run, which costs the command's full runtime to reach the same answer. Its one use is a file rather than an exit status -- a skipped command writes none, so a fresh `coverage/` needs `nmr --no-cache test:coverage`. A composite replays its constituents' excerpts, each attributed as `<scope>: <command>: <excerpt>` and cut at the line's ceiling where there are too many to fit. A skip carrying no excerpt is one whose run wrote to a terminal, or one whose constituents recorded none.
 - `nmr --log <command>` prints the whole run behind that excerpt -- up to 256 KiB, led by when it was recorded, how long it ran, and the command string that produced it -- so output you need in full is a recording to read rather than a run to pay for again. It runs nothing, and it is held to the tree rather than to the terminal: a recording a piped run made prints for a reader at one. A composite prints its constituents' excerpts, so the transcript of one of them is `nmr -F <pkg> --log <command>` or that constituent's own name. Nothing to show is said on one line and exits non-zero, naming which it is.
 - Every command nmr runs reports one line -- `✅ <scope>: <command>: passed in 12.4s`, `❌ … failed in 1.2s (exit 1)`, `⏭️ … passed 4m ago on this tree`, or `⛔ … skipped, the override is empty` -- and a composite reports alongside every command it expands into. The lines print in every verbosity, so `-q` is the low-noise way to run rather than a silent one: it withholds the output of the commands nmr runs and keeps nmr's own verdicts, which is how a pass, a cached skip, and a `""`/`":"` override stay distinguishable. Expect a run to be quiet already without the flag: nmr recognizes a known agent harness in the environment and takes quiet from that, as it does from `NMR_COMMAND_VERBOSITY` or the repo's `output.commandVerbosity`. A command whose output you need in full is one to run with `NMR_COMMAND_VERBOSITY=full`, which outranks both.
-- Every test file lives under a `__tests__` directory and names its isolation tier last: `<subject>[.<aspect>].<tier>.test.ts`, where any earlier segment is free-form documentation. A tier is the furthest thing the test reaches -- `tool` (a program the environment supplies), `localhost` (a service on this machine), `remote` (a machine that isn't this one), or `unit`, the residual claiming everything else. Neither a file outside `__tests__` nor one whose tier segment is missing or misspelt fails anything: the first is collected by nothing and the second runs under `unit`, and no test run distinguishes either from a conformant file. `rdy run --packages` reports the misspelt tier, and nothing reports the misplaced file.
+- Every test file lives under a `__tests__` directory and names its isolation tier last: `<subject>[.<aspect>].<tier>.test.ts`, where any earlier segment is free-form documentation. A tier is the furthest thing the test reaches -- `tool` (a program the environment supplies), `localhost` (a service on this machine), `remote` (a machine that isn't this one), or `unit`, the residual claiming everything else. A file outside `__tests__`, or one whose tier segment is missing or misspelt, fails the test run in a repo that declares nmr's exported conventions check, which reports both. In a repo that has not, neither fails anything -- the first is collected by nothing and the second runs under `unit` -- and `rdy run --packages` reports the misspelt tier alone.
 - The rest is in `node_modules/@williamthorsen/nmr/README.md`: pre/post hooks (every `nmr X` auto-wraps as `nmr X:pre && nmr X && nmr X:post`), script overrides and their `""`/`":"` skip values, `nmr upgrade` ceilings (report-only until `nmr upgrade --write`), the `nmr-compile` build (there is no repo-local build script), the test tiers' timeout budgets and the `tiers` seam that raises one, which script reaches which tier, and the check-result cache's key, the retention key a replayed excerpt is additionally held to, the retention ceiling `--log` prints within, its `checkCache` config, and every condition that disables it.

package/dist/esm/UserError.d.ts

@@ -1,3 +1,9 @@
+/**
+ * A failure in what the user declared -- a config file, a `package.json` -- rather than a fault in nmr.
+ *
+ * The CLI boundary prints one of these as its message alone. A stack trace records where nmr noticed the
+ * problem, which says nothing about the file the reader has to edit.
+ */
 export declare class UserError extends Error {
     constructor(message: string);
 }

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