@williamthorsen/nmr 0.36.0 → 0.38.0

package/dist/esm/vitest-source-resolution.js

@@ -0,0 +1,205 @@
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { isBuiltin } from 'node:module';
+import path from 'node:path';
+import { parsePackageJson } from "./helpers/package-json.js";
+import { isObject } from "./helpers/type-guards.js";
+import { UserError } from "./UserError.js";
+const SHARED_CONDITIONS = ['module', 'import', 'development', 'default'];
+const CLIENT_CONDITION = 'browser';
+const SERVER_CONDITION = 'node';
+const SOURCE_CONDITION = 'source';
+const NODE_MODULES = 'node_modules';
+const TARGET_EXTENSIONS = ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json'];
+export function createSourceResolutionPlugin() {
+    const packageDirs = new Map();
+    const manifests = new Map();
+    return {
+        name: 'nmr:resolve-from-source',
+        enforce: 'pre',
+        resolveId(id, importer) {
+            return resolveSourceTarget(id, importer, { environmentName: this.environment.name, manifests, packageDirs });
+        },
+    };
+}
+export function resolveSourceTarget(specifier, importer, context) {
+    if (importer === undefined)
+        return undefined;
+    const parsed = parseSpecifier(specifier);
+    if (!parsed)
+        return undefined;
+    const packageDir = findPackageDir(parsed.name, path.dirname(importer), context.packageDirs);
+    if (packageDir === undefined || isInsideNodeModules(packageDir))
+        return undefined;
+    const manifest = readManifest(packageDir, context.manifests);
+    if (!isObject(manifest))
+        return undefined;
+    const matched = matchSubpath(manifest['exports'], parsed.subpath);
+    if (!matched)
+        return undefined;
+    const environmentCondition = context.environmentName === 'client' ? CLIENT_CONDITION : SERVER_CONDITION;
+    const conditions = new Set([environmentCondition, ...SHARED_CONDITIONS]);
+    const selected = selectTarget(matched.value, conditions);
+    if (!selected?.usedSource)
+        return undefined;
+    const wildcard = matched.wildcard;
+    const declared = wildcard === undefined ? selected.target : selected.target.replaceAll('*', () => wildcard);
+    if (!declared.startsWith('./'))
+        return undefined;
+    const declaredPath = path.resolve(packageDir, declared);
+    const target = findTargetFile(declaredPath);
+    if (target === undefined) {
+        throw new UserError(formatMissingTarget(parsed.name, parsed.subpath, declared, declaredPath));
+    }
+    return `${target}${parsed.postfix}`;
+}
+function findPackageDir(name, fromDir, cache) {
+    const key = `${fromDir}\0${name}`;
+    if (cache?.has(key))
+        return cache.get(key);
+    let found = findSelfReferenceDir(name, fromDir);
+    let dir = fromDir;
+    while (found === undefined) {
+        const candidate = path.join(dir, NODE_MODULES, name);
+        if (existsSync(path.join(candidate, 'package.json'))) {
+            found = realpathSync(candidate);
+            break;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    cache?.set(key, found);
+    return found;
+}
+function findSelfReferenceDir(name, fromDir) {
+    let dir = fromDir;
+    for (;;) {
+        const file = path.join(dir, 'package.json');
+        if (existsSync(file)) {
+            const parsed = parsePackageJson(readFileSync(file, 'utf8'), file);
+            return isObject(parsed) && parsed['name'] === name && parsed['exports'] !== undefined ? dir : undefined;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function findSuffixIndex(specifier) {
+    const queryIndex = specifier.indexOf('?');
+    const hashIndex = specifier.indexOf('#');
+    if (queryIndex === -1)
+        return hashIndex;
+    if (hashIndex === -1)
+        return queryIndex;
+    return Math.min(queryIndex, hashIndex);
+}
+function findTargetFile(declaredPath) {
+    if (isFile(declaredPath))
+        return declaredPath;
+    for (const extension of TARGET_EXTENSIONS) {
+        const candidate = `${declaredPath}${extension}`;
+        if (isFile(candidate))
+            return candidate;
+    }
+    for (const extension of TARGET_EXTENSIONS) {
+        const candidate = path.join(declaredPath, `index${extension}`);
+        if (isFile(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function formatMissingTarget(name, subpath, declared, target) {
+    return [
+        `Package "${name}" declares a \`source\` export for "${subpath}" at "${declared}", which reaches no file.`,
+        `Looked for ${target}, the same path under each of ${TARGET_EXTENSIONS.join(', ')}, and an index under it.`,
+        'Point the condition at a file that exists, or remove it so the package resolves through its other conditions.',
+    ].join(' ');
+}
+function isFile(candidate) {
+    return statSync(candidate, { throwIfNoEntry: false })?.isFile() === true;
+}
+function isInsideNodeModules(dir) {
+    return dir.split(path.sep).includes(NODE_MODULES);
+}
+function matchSubpath(exportsValue, subpath) {
+    if (exportsValue === undefined)
+        return undefined;
+    if (!isObject(exportsValue) || Object.keys(exportsValue).every((key) => !key.startsWith('.'))) {
+        return subpath === '.' ? { value: exportsValue } : undefined;
+    }
+    const exact = exportsValue[subpath];
+    if (exact !== undefined)
+        return { value: exact };
+    let best;
+    for (const [key, value] of Object.entries(exportsValue)) {
+        const star = key.indexOf('*');
+        if (star === -1)
+            continue;
+        const base = key.slice(0, star);
+        const suffix = key.slice(star + 1);
+        if (!subpath.startsWith(base) || !subpath.endsWith(suffix))
+            continue;
+        if (subpath.length < base.length + suffix.length)
+            continue;
+        if (best !== undefined && best.base.length >= base.length)
+            continue;
+        best = { base, value, wildcard: subpath.slice(base.length, subpath.length - suffix.length) };
+    }
+    return best && { value: best.value, wildcard: best.wildcard };
+}
+function parseSpecifier(specifier) {
+    if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('\0'))
+        return undefined;
+    const suffixIndex = findSuffixIndex(specifier);
+    const bare = suffixIndex === -1 ? specifier : specifier.slice(0, suffixIndex);
+    if (bare.includes(':') || isBuiltin(bare))
+        return undefined;
+    const segments = bare.split('/');
+    const nameLength = bare.startsWith('@') ? 2 : 1;
+    if (segments.length < nameLength || segments.includes(''))
+        return undefined;
+    const rest = segments.slice(nameLength);
+    return {
+        name: segments.slice(0, nameLength).join('/'),
+        postfix: suffixIndex === -1 ? '' : specifier.slice(suffixIndex),
+        subpath: rest.length === 0 ? '.' : `./${rest.join('/')}`,
+    };
+}
+function readManifest(packageDir, cache) {
+    if (cache?.has(packageDir))
+        return cache.get(packageDir);
+    const file = path.join(packageDir, 'package.json');
+    const parsed = parsePackageJson(readFileSync(file, 'utf8'), file);
+    cache?.set(packageDir, parsed);
+    return parsed;
+}
+function selectTarget(value, conditions) {
+    if (typeof value === 'string')
+        return { target: value, usedSource: false };
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const selected = selectTarget(entry, conditions);
+            if (selected)
+                return selected;
+        }
+        return undefined;
+    }
+    if (!isObject(value))
+        return undefined;
+    const source = value[SOURCE_CONDITION];
+    if (source !== undefined) {
+        const selected = selectTarget(source, conditions);
+        if (selected)
+            return { target: selected.target, usedSource: true };
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        if (key === SOURCE_CONDITION || !conditions.has(key))
+            continue;
+        const selected = selectTarget(entry, conditions);
+        if (selected)
+            return selected;
+    }
+    return undefined;
+}

package/dist/esm/vitest.d.ts

@@ -45,8 +45,9 @@ export interface VitestConfigOptions {
      */
     isolateGit?: boolean;
     /**
-     * Resolves workspace packages through their `source` export condition, so a suite runs without a prior build.
-     * Defaults to `true`. A package declaring no such condition is unaffected.
+     * Resolves a package whose files sit outside every `node_modules` through its `source` export condition, so a
+     * suite runs without a prior build. Defaults to `true`. A package declaring no such condition is unaffected,
+     * and so is every package under `node_modules`, which Node resolves and which the condition never reaches.
      */
     resolveFromSource?: boolean;
     /**

package/dist/esm/vitest.js

@@ -3,13 +3,14 @@ import { fileURLToPath } from 'node:url';
 import { defaultExclude, mergeConfig } from 'vitest/config';
 import { isObject } from "./helpers/type-guards.js";
 import { ALL_TEST_PATTERNS, buildTierPatterns, TEST_COLLECTION_EXCLUDE, TIER_NAMES } from "./tiers.js";
+import { createSourceResolutionPlugin } from "./vitest-source-resolution.js";
 import { getWorkspacePackageDirs } from "./workspace.js";
 const [RESIDUAL_TIER, ...NAMED_TIERS] = TIER_NAMES;
 const TIERED_PATTERNS = NAMED_TIERS.flatMap(buildTierPatterns);
 const TIER_TIMEOUT = 30_000;
 const GIT_ISOLATION_SETUP_FILE = resolveGitIsolationSetupFile();
-const SOURCE_CLIENT_CONDITIONS = ['source', 'module', 'browser', 'development|production'];
-const SOURCE_SERVER_CONDITIONS = ['source', 'module', 'node', 'development|production'];
+const CLIENT_CONDITIONS = ['module', 'browser', 'development|production'];
+const SERVER_CONDITIONS = ['module', 'node', 'development|production'];
 const COVERAGE_EXCLUDE = ['**/__{fixtures,mocks,tests}__/**', '**/index.ts', '**/*.d.ts'];
 const PACKAGE_COVERAGE_INCLUDE = ['**/src/**/*.{ts,tsx}'];
 const MISSING_MONOREPO_ROOT = 'defineRootVitestConfig requires `monorepoRoot`, an absolute path to the directory holding pnpm-workspace.yaml. Pass `import.meta.dirname` in the last options layer, from the root config.';
@@ -31,14 +32,14 @@ export function defineRootVitestConfig(...layers) {
 function buildConfig(declaredLayers, { coverageInclude, projectExclude = [], projectRoot }) {
     const layers = declaredLayers.filter((layer) => layer !== undefined);
     assertKnownTiers(layers);
-    const resolveFromSource = resolveFlag(layers, 'resolveFromSource', true);
     const resolve = {
-        ...(resolveFromSource && { conditions: SOURCE_CLIENT_CONDITIONS }),
+        conditions: CLIENT_CONDITIONS,
         ...(resolveFlag(layers, 'tsconfigPaths', false) && { tsconfigPaths: true }),
     };
     const config = {
-        ...(Object.keys(resolve).length > 0 && { resolve }),
-        ...(resolveFromSource && { ssr: { resolve: { conditions: SOURCE_SERVER_CONDITIONS } } }),
+        ...(resolveFlag(layers, 'resolveFromSource', true) && { plugins: [createSourceResolutionPlugin()] }),
+        resolve,
+        ssr: { resolve: { conditions: SERVER_CONDITIONS } },
         test: {
             coverage: {
                 enabled: false,

package/dist/esm/workspace.d.ts

@@ -20,3 +20,12 @@ export declare function getWorkspacePackageDirs(monorepoRoot: string): string[];
  * Returns nothing when the manifest or the block is missing, and drops an entry whose value is not a string.
  */
 export declare function readWorkspaceOverrides(monorepoRoot: string): Record<string, string> | undefined;
+/**
+ * Reads the manifest `name` each of the given package directories declares, which is what a `-F` pattern
+ * matches.
+ *
+ * A directory whose manifest is missing, unparseable, or nameless contributes nothing. The sweep runs for a
+ * diagnostic's sake, so one malformed manifest elsewhere in the workspace must not replace the diagnostic the
+ * reader asked for with a failure of its own.
+ */
+export declare function readWorkspacePackageNames(packageDirs: readonly string[]): string[];

package/dist/esm/workspace.js

@@ -5,6 +5,7 @@ import { readStringValues } from "./helpers/readStringValues.js";
 import { isObject } from "./helpers/type-guards.js";
 import { resolvePackageDirs } from "./helpers/workspace-patterns.js";
 import { UserError } from "./UserError.js";
+const PACKAGE_MANIFEST = 'package.json';
 const WORKSPACE_MANIFEST = 'pnpm-workspace.yaml';
 export function isMonorepoRoot(dir) {
     return existsSync(path.join(dir, WORKSPACE_MANIFEST));
@@ -47,6 +48,22 @@ export function readWorkspaceOverrides(monorepoRoot) {
     const overrides = parsed['overrides'];
     return isObject(overrides) ? readStringValues(overrides) : undefined;
 }
+export function readWorkspacePackageNames(packageDirs) {
+    const names = [];
+    for (const dir of packageDirs) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path.join(dir, PACKAGE_MANIFEST), 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (isObject(parsed) && typeof parsed['name'] === 'string') {
+            names.push(parsed['name']);
+        }
+    }
+    return names;
+}
 function getPackagesFromParsedYaml(parsed) {
     if (!isObject(parsed))
         return undefined;

package/docs/check-cache.md

@@ -0,0 +1,176 @@
+# Check-result cache
+
+How nmr skips a check that already passed on the same working tree, what decides a hit, and how to read, bypass, and configure what it recorded.
+
+The [README](../README.md#check-result-cache) shows a skip in action.
+
+Composite commands expand into child `nmr` processes, so one green `nmr ci` records a pass for every cacheable command in the chain, at every scope it ran at. A later `nmr check`, `nmr typecheck`, or `nmr -F core test` on the same tree skips too. The skip is [reported](reporting.md#what-nmr-reports) in every verbosity.
+
+The cache is a working-tree cache, not a build cache: it answers "has this exact tree already passed this check?" and nothing else. It is also local to one checkout (the install fingerprint in its key is machine-specific), so it saves repeated work in a working copy rather than sharing results across machines or with CI.
+
+## What is cached
+
+Cacheable by default: `check`, `check:strict`, `ci`, `fix:check`, `fmt:check`, `lint:check`, `lint:strict`, `test`, `test:coverage`, `test:tool`, `test:unit`, `typecheck`, and the `root:` variants `root:check`, `root:lint:check`, `root:lint:strict`, `root:test`, `root:test:tool`, `root:test:unit`, and `root:typecheck`.
+
+Everything else runs every time:
+
+| Command                         | Why it is never skipped                                                                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `audit`, `prepush`              | Consult a vulnerability database that moves without the tree. `prepush`'s `ci` constituent still skips while its `audit` runs every time. |
+| `build`, `compile`              | Carry a cache of their own.                                                                                                               |
+| `fix`, `fmt`, `lint`, `upgrade` | Rewrite the tree they were asked about, so a recorded pass would describe a tree that no longer exists.                                   |
+| `test:all`                      | Reaches the `localhost` and `remote` tiers, which the environment supplies rather than the tree.                                          |
+
+## The exit-status-only contract
+
+**A cacheable name promises that its whole contribution is an exit status**, through its entire chain, `:pre` and `:post` hooks included. A hit skips that chain wholesale, so any file a cacheable command was relied on to produce is a file that will not appear.
+
+`test:coverage` is cacheable on exactly this reading: what it contributes is the pass, not the `coverage/` directory, which a skipped run leaves as whatever the last real run wrote. Read `coverage/` after a `test:coverage` that may have skipped, and it may be stale; `--no-cache` is how you insist on a fresh one.
+
+Overriding a cacheable name, in `package.json` or in `workspaceScripts`, inherits its cacheability. An override that writes something anyone depends on belongs in `excludeCommands`.
+
+## What the key is made of
+
+A hit requires all of these to match the run that recorded the pass:
+
+- **The working tree's content**, hashed from the commit's tree object folded with the current content of every path git reports as changed or untracked. Timestamps are not content, so a `touch` that rewrites no bytes leaves the hash alone.
+- **The command string that would run**, hooks and all, and the scope it would run in.
+- **nmr's version**, the **Node version**, and the **platform and architecture**.
+- **What pnpm has installed**, so an install, a prune, or a lockfile change forces a re-run.
+- **`TZ`, `LANG`, `LC_ALL`, and `NODE_OPTIONS`.** This set is fixed, so two machines that differ only in shell decoration still agree.
+
+A hit additionally requires the build output of every package nmr's own build covers to be present, and to have been built from this tree. Output is git-ignored, so neither its removal nor its replacement moves the hash: restoring a tree with `git stash` or `git checkout` restores none of the output that tree was built with. nmr compares each covered package's recorded build digest against the one on disk, so a `dist` compiled from another tree is a miss the following run repairs. A package that overrides `build` or `compile` emits on terms nmr does not know and is exempt.
+
+A pass is recorded only when the command exits 0, only when the tree still matches the one the run started against, only when every covered package's output is present and unchanged since the run started, and never for a run that executed nothing (a `""`/`":"` skip override, or an `NMR_RUN_IF_PRESENT` miss). Output that moves mid-run leaves no answer to which output the pass was earned over, whether another process rebuilt it or the chain built it itself: `nmr ci` is the one default command whose chain does, and it records nothing on a run whose build did work. The `nmr check:strict` inside that chain still records, because its own window opens after the build.
+
+## Out of contract
+
+These change what a check concludes without moving the hash. Where one applies, exclude the affected command:
+
+- **Content filters.** `core.autocrlf` and `.gitattributes` filters mean the bytes on disk differ from the bytes git records; the hash follows what is on disk, but a checkout on another platform may not reproduce it.
+- **Symlinked inputs.** A symlink is hashed by the path it names, not by the content at the far end.
+- **Gitignored inputs.** Anything git does not report is invisible to the hash. The build-output probe is the one exception, and covers only nmr's own build.
+- **`passWithNoTests`.** A suite that collects no files exits 0, and that green is recorded like any other.
+
+Committing an already-checked tree also moves the hash, because the commit's tree object is the base of the fold; the next run does the work again. The reverse holds and is useful: a rebase or an amended message that preserves content leaves the hash alone, as does checking out a branch whose tree is identical.
+
+## When the gate stands aside
+
+The gate never wrongly skips. Where it cannot be sure, it does nothing and the command runs:
+
+- Outside a git repository, when git fails, or when there is no commit at `HEAD`.
+- When the repository declares or contains submodules, whose content the hash does not cover.
+- When the monorepo root is not the git toplevel.
+- When a changed path cannot be read, or is neither a file nor a symlink (an untracked nested repository, for instance).
+- When there is no pnpm install to fingerprint.
+- Under a `devBin` substitution, which runs a binary built from somewhere the hash does not describe.
+- For any invocation carrying arguments after the command name, and for every step below it: the arguments narrow what runs, and a step served from a recorded pass is a step that did not.
+
+`NMR_DEBUG=1` reports why a run did not skip and why the gate stood aside.
+
+## Replaying a skipped run's output
+
+A skip reports an excerpt of the run it recalls, marked as a recording rather than as this run's output:
+
+```console
+$ nmr test
+# ... the suite runs ...
+
+$ nmr test
+⏩ nmr: test: passed 2m ago on this tree, saved ~12s — replayed: Test Files 6 passed (6) Tests 41 passed (41)
+```
+
+The excerpt is the last blank-line-delimited block of what the command wrote, which is the closing statement a tool separates from its progress output. It is flattened onto one line, with escape sequences stripped, table rules dropped, and a redrawn progress line reduced to what a reader was left looking at. Nothing is parsed and no figure is computed: nmr replays bytes it recorded. A block wider than a few kilobytes is cut and marked with `…`, so a command whose closing statement is one long line cannot carry its whole output into the cache.
+
+The excerpt and the whole transcript it is drawn from are written by the same operation that records the pass, so a pass declined because the tree moved or build output changed leaves neither behind, and `nmr clean` clears both along with the passes they belong to.
+
+**Capture happens at the command, and only where nmr can see its output.** A command whose stdout or stderr is a terminal writes where nmr never reads, so an interactive run retains nothing and its progress display is untouched; a piped or redirected run, and any run under `-q`, retains both streams. A composite hands its descriptors to the child `nmr` processes below it and captures nothing of its own, and a `:pre` or `:post` hook contributes nothing to the command it wraps: an excerpt is the command's own output or none.
+
+**A composite replays its constituents' excerpts.** Capturing nothing of its own, a composite assembles what its constituents recorded, each line attributed to the scope and command that produced it:
+
+```console
+$ nmr check
+⏩ nmr-core: check: passed 3m ago on this tree, saved ~48s — replayed: nmr-core: fmt:check: All matched files use Prettier code style!; nmr-core: test: Test Files 6 passed (6) Tests 41 passed (41)
+```
+
+The assembly is flat: a constituent that is itself a composite contributes its own leaves' lines, so a skipped `ci` replays a package's `test` rather than one opaque `check:strict` line. A delegate expands into the scopes it fans out to, and a constituent that recorded no excerpt is absent rather than inferred: `typecheck` and `lint:check` print nothing on success and contribute nothing above, and a command outside the [cacheable set](#what-is-cached) records nothing at all, so `ci` replays what `check:strict` earned and nothing for `build`.
+
+It is assembled when the composite records its pass rather than when it skips, so every excerpt in it was certified during that one run, on that one tree. `NMR_RUN_ID` is what makes that provable; see [reserved environment variables](#reserved-environment-variables).
+
+**A skip certifies what it replays.** Recalling a pass proves the excerpt describes this tree, and a matching retention key proves it describes this presentation environment, so a skip restamps the recalled entry with the run replaying it. A constituent already warm when a composite ran therefore still contributes its line: `nmr check` after `nmr test` replays the test summary. The restamp touches nothing else -- the instant and the duration belong to the run that earned the pass.
+
+**A replay is held to more than the pass is.** Retention carries its own key: the [pass key](#what-the-key-is-made-of) folded with the channel each output stream ran on and with `CI`, `COLUMNS`, `FORCE_COLOR`, `NO_COLOR`, and `TERM`. `NMR_OUTPUT_STYLE` is in neither key, so a rich run and a plain one share a recorded pass and replay each other's excerpts as recorded. A recording made under a different one is recalled as a pass all the same; its excerpt is simply not replayed, and the verdict prints alone, as it does for a pass that retained nothing.
+
+The whole line, excerpt included, is held to the same [512-byte ceiling](reporting.md#what-nmr-reports) every verdict is, so one write still carries it whole under concurrent fan-out. An assembly wide enough to overrun it is cut and marked with `…` rather than spread over several lines.
+
+## Reading a retained run
+
+The excerpt is a line; the run behind it is kept whole. `nmr --log <command>` prints it, led by a header dating what follows:
+
+```console
+$ nmr --log test
+💾 nmr: test — recorded 2026-08-12T15:04:05.412Z (12m ago), ran in 12.4s
+$ pnpm exec vitest --project unit --project tool
+
+ ✓ src/__tests__/resolver.unit.test.ts (18 tests) 12ms
+
+ Test Files  6 passed (6)
+      Tests  41 passed (41)
+```
+
+The header is what presents the body as a recording rather than as this invocation's output. The command string is the whole chain, hooks included, so it names what earned the pass and not merely what was typed. A flag rather than a subcommand, since `log` would collide with the script registry.
+
+**Reading a recording runs nothing.** No hook runs, no verdict prints, and nothing is recorded or restamped. `--no-cache` governs running rather than reading and is ignored.
+
+**A recording is held to the tree, not to the terminal.** `--log` prints exactly what a skip would have recalled: the [pass key](#what-the-key-is-made-of) has to match. The [retention key](#replaying-a-skipped-runs-output) is not consulted, so a recording made under a different terminal width, or through a pipe, still prints -- a reader at a terminal being shown what a piped run wrote is the case the flag exists for.
+
+**A composite prints its assembly.** Retaining nothing of its own, a composite prints the excerpts its constituents recorded, one attributed line each. The transcript of any one of them is that constituent's own `--log` to print.
+
+**Nothing to show is said rather than left blank.** A refusal names which it is -- the command is outside the [cacheable set](#what-is-cached), the gate is [standing aside](#when-the-gate-stands-aside), nothing has recorded a pass, the last pass was recorded under something this run does not share, or the pass retained no output, having printed none or written to a terminal -- and exits non-zero, so a caller can tell an empty `stdout` from a recording. A mismatch names the ingredient that moved, the tree or the chain or a version, so a reader whose `git status` is clean is not sent looking there.
+
+```console
+$ nmr --log test
+🟠 nmr: test: no recording; the last pass was 3m ago, on a tree this is not
+```
+
+**`--log` reaches the scopes `-F` and `-R` select.** The flag rides the delegate, so each scope prints its own recording. There a scope with nothing to show reports its gap and exits 0: partial coverage is a survey's normal shape, and failing on the first gap would hide every scope that had something. A selection of no scope at all is the other case and fails, as it does for a run: there is no survey to be partial.
+
+**Retention has a ceiling of 256 KiB per recorded pass**, distinct from the 512 bytes a verdict line is held to. A transcript overrunning it keeps 128 KiB from each end, because a run's opening and its closing statement each carry what the other does not, and the drop is marked with a line naming the bytes it stands for rather than being cut silently.
+
+## Bypassing and clearing
+
+Reach for these in order; the first is almost always the right one.
+
+| Step                                   | Effect                                                                    |
+| -------------------------------------- | ------------------------------------------------------------------------- |
+| `nmr --no-cache <command>`             | Runs the command, then records the fresh result. Reaches the whole chain. |
+| `NMR_NO_CACHE=1`                       | The same, for every nmr invocation in the shell.                          |
+| `rm -rf node_modules/.cache/nmr-check` | Forgets every recorded pass, leaving build output alone.                  |
+| `nmr clean`                            | Forgets every recorded pass and removes build output, at any scope.       |
+
+`--no-cache` belongs before the command name. After it, it is an argument to the command rather than a flag to nmr; nmr says so rather than letting the bypass silently not happen.
+
+## Reserved environment variables
+
+`NMR_TREE_SNAPSHOT` is nmr's own: it carries one observation of the tree from a top-level invocation down to the processes it spawns, so a chain hashes the tree once rather than at every link. nmr trusts an inherited value only while `HEAD` still stands where it did when the observation was taken, which bounds a process that outlives the run that spawned it. That bound does not extend to a tree edited without committing, so **a process that survives its run and later invokes nmr should clear `NMR_TREE_SNAPSHOT`** — a test suite that shells out to `nmr` is the case worth checking.
+
+`NMR_RUN_ID` is nmr's own too: it carries one run's identity from a top-level invocation down to the processes it spawns, so the excerpts recorded at every scope during one run are recognizable as that run's, and a composite can assemble from them. Where `NMR_TREE_SNAPSHOT` is bounded by `HEAD`, this is bounded by the tree hash each entry records, so a process that outlives its run and carries the identity into a later one contributes nothing to that run's assemblies.
+
+## Configuring
+
+```ts
+export default defineConfig({
+  checkCache: {
+    // Names promising exit-status-only semantics through their whole chain.
+    extraCommands: ['verify:contracts'],
+    // Names that turned out to do more than report an exit status.
+    excludeCommands: ['test:coverage'],
+  },
+});
+```
+
+`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.

package/docs/prettier.md

@@ -0,0 +1,47 @@
+# Shared Prettier config
+
+The Prettier config that `@williamthorsen/nmr/prettier` publishes: what it formats, how it scopes the shell plugin, and how to customize and adopt it.
+
+`prettier` is a peer dependency (`>=3.9.5 <4`), declared optional — the consuming repo provides it. The shell and Dockerfile plugin is a dependency of nmr rather than a peer, so its version is pinned centrally and two repos cannot format the same script differently.
+
+## What it formats
+
+Beyond everything Prettier already handles, this config formats `.sh`, `.bash`, `.zsh`, and the other extensions and dotfile names of the Shell language, plus `Dockerfile` and `Containerfile`. `nmr fmt` therefore covers shell scripts with no extra script, glob, or workflow entry.
+
+Shell output matches `shfmt` run with no flags: `binaryNextLine`, `spaceRedirects`, and `switchCaseIndent` are pinned to shfmt's CLI defaults, which the underlying plugin inverts. A repo whose scripts shfmt already formatted sees no diff on adoption.
+
+Code fences inside Markdown are left alone, in every language rather than shell alone. Registering the shell plugin also routes a fence tagged `bash` to shfmt, where a documented command's angle-bracket placeholders are valid redirections: `cmd --type <type> --harness claude` is reprinted as `cmd --type claude <type >--harness`, which still runs but no longer does what it documents. It cannot be narrowed back to shell, because Prettier matches a fence tag against the same `extensions` its file inference reads, so the `.bash` routing a script also claims the tag `bash`.
+
+## Language scoping
+
+`prettier-plugin-sh` routes 20 further file types to the same shell parser, among them `.gitignore`, `.env`, `.csh`, `.nu`, `.properties`, `.ics`, `.vcf`, `CODEOWNERS`, and `hosts`. Since `nmr fmt` hands git's whole file list to Prettier, registering the plugin as shipped would make every one of them formattable — and the shell parser either fails on them or silently rewrites them. A `.gitignore` pattern such as `a(b)c` fails to parse, and an unquoted `&` in a `.env` or `.properties` value is split across two lines.
+
+This config registers a narrowed plugin, so Prettier infers a parser for the Shell and Dockerfile languages alone. `.flaskenv`, `gradlew`, and `mvnw` are dropped from Shell as well: the first holds dotenv content the plugin misfiles as shell, and the other two are vendored wrappers their generators would overwrite.
+
+The parsers themselves stay registered, so a repo that wants a dropped language back assigns it explicitly:
+
+```js
+export default definePrettierConfig({
+  additionalOverrides: [{ files: ['APKBUILD', '*.ebuild'], options: { parser: 'sh' } }],
+});
+```
+
+## Customizing
+
+Any Prettier option passed to the factory spreads over the defaults:
+
+```js
+export default definePrettierConfig({
+  printWidth: 100,
+  additionalPlugins: [await import('prettier-plugin-tailwindcss')],
+  additionalOverrides: [{ files: ['*.md'], options: { proseWrap: 'always' } }],
+});
+```
+
+`additionalPlugins` and `additionalOverrides` append to what the config declares, so a later override wins over nmr's own and no seam can drop shell support. Passing `plugins` or `overrides` throws, and both are typed `never` — replacement is inexpressible rather than merely discouraged, because a silently ignored key would produce no diff to notice.
+
+## Adoption caveats
+
+- **Indentation follows `.editorconfig`**, as it did under shfmt: Prettier maps `indent_style` and `indent_size` to `useTabs` and `tabWidth`, and the plugin honours both. With no `.editorconfig`, the two disagree — shfmt indents shell with tabs, Prettier with two spaces. Add `indent_style = tab` under `[*.sh]` to keep tabs.
+- **Markdown fences stop being tidied.** The carve-out that protects documented shell commands costs the `ts`, `json`, and `yaml` fences their formatting too. Fences already formatted stay as they are, so nothing churns on adoption; new ones are simply left as written. A repo whose docs hold no shell can take them back for the Markdown paths it actually uses: `additionalOverrides: [{ files: ['*.md'], options: { embeddedLanguageFormatting: 'auto' } }]` restores `.md` alone, and the carve-out still covers every other path Prettier reads as Markdown.
+- **Adopting the house options reformats the repo.** `singleQuote`, `trailingComma`, and the rest apply on the first run; review that diff separately from the shell one.