@williamthorsen/nmr 0.43.0 → 0.45.0

package/.readyup/manifest.json

@@ -3,21 +3,90 @@
   "kits": [
     {
       "bundledDependencies": {
-        "@williamthorsen/toolbelt.errors": "0.8.2",
+        "@williamthorsen/toolbelt.errors": "0.8.3",
+        "@williamthorsen/toolbelt.filesystem": "0.9.3",
+        "@williamthorsen/toolbelt.packaging": "0.6.3",
+        "@williamthorsen/toolbelt.terminal": "0.2.1",
+        "ansi-regex": "6.4.0",
+        "ansi-styles": "6.2.3",
+        "cli-truncate": "6.1.1",
+        "diff": "9.0.0",
+        "get-east-asian-width": "1.7.0",
+        "is-fullwidth-code-point": "5.1.0",
+        "slice-ansi": "9.0.1",
+        "string-width": "8.3.0",
+        "strip-ansi": "7.2.0",
+        "wrap-ansi": "10.0.2",
         "yaml": "2.9.1"
       },
       "checklists": [
-        "nmr"
+        "nmr",
+        "self-hosted runner"
       ],
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "50b5aac3",
+          "hash": "aed52073",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/cache-store.js"
+        },
+        {
+          "hash": "54384dca",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/gitOutputLimit.js"
+        },
+        {
+          "hash": "6b7d0243",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/hasErrnoCode.js"
+        },
+        {
+          "hash": "211453c6",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/hashWorkingTree.js"
+        },
+        {
+          "hash": "41232d10",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/helpers/workspace-patterns.js"
+        },
+        {
+          "hash": "191f7c24",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/index.js"
+        },
+        {
+          "hash": "2507870d",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/parseArgs.js"
+        },
+        {
+          "hash": "14547f78",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/terminal.js"
+        },
+        {
+          "hash": "3c395f31",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/updateManagedFile.js"
+        },
+        {
+          "hash": "2224ec3a",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/workspace.js"
+        },
+        {
+          "hash": "24bde686",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/writeFileWithCheck.js"
+        },
+        {
+          "hash": "aaeb1a84",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "caf06cd5",
+          "hash": "22efcac6",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -25,7 +94,12 @@
           ]
         },
         {
-          "hash": "9336f4c0",
+          "hash": "7e066d18",
+          "kind": "module",
+          "path": "../src/config.ts"
+        },
+        {
+          "hash": "0fb883a1",
           "kind": "module",
           "path": "../src/default-scripts.ts"
         },
@@ -35,22 +109,87 @@
           "path": "../src/git-ignored-paths.ts"
         },
         {
-          "hash": "23646439",
+          "hash": "ae257d50",
+          "kind": "module",
+          "path": "../src/helpers/config-path.ts"
+        },
+        {
+          "hash": "a663548a",
+          "kind": "module",
+          "path": "../src/helpers/escapeControlCharacters.ts"
+        },
+        {
+          "hash": "47249ca4",
+          "kind": "module",
+          "path": "../src/helpers/findClosestName.ts"
+        },
+        {
+          "hash": "3efe4131",
+          "kind": "module",
+          "path": "../src/helpers/hook-name.ts"
+        },
+        {
+          "hash": "8850834f",
+          "kind": "module",
+          "path": "../src/helpers/package-json.ts"
+        },
+        {
+          "hash": "61629be6",
+          "kind": "module",
+          "path": "../src/helpers/readStringValues.ts"
+        },
+        {
+          "hash": "56d2bb48",
+          "kind": "module",
+          "path": "../src/helpers/type-guards.ts"
+        },
+        {
+          "hash": "78ca6bd4",
           "kind": "module",
           "path": "../src/resolve-scripts.ts"
         },
         {
-          "hash": "19dec003",
+          "hash": "15247f0e",
+          "kind": "module",
+          "path": "../src/resolver.ts"
+        },
+        {
+          "hash": "ed585ab6",
+          "kind": "module",
+          "path": "../src/steps.ts"
+        },
+        {
+          "hash": "d1e8e302",
           "kind": "module",
           "path": "../src/tiers.ts"
+        },
+        {
+          "hash": "faad986a",
+          "kind": "module",
+          "path": "../src/UserError.ts"
+        },
+        {
+          "hash": "857c630c",
+          "kind": "module",
+          "path": "../src/verbosity.ts"
+        },
+        {
+          "hash": "f08b6ff3",
+          "kind": "module",
+          "path": "../src/workspace-globs.ts"
+        },
+        {
+          "hash": "922e7155",
+          "kind": "module",
+          "path": "../src/workspace.ts"
         }
       ],
       "name": "default",
       "path": "kits/default.js",
       "readyupVersion": "0.40.0",
       "source": "kits/default.ts",
-      "sourceHash": "50b5aac3",
-      "targetHash": "7a5cd413"
+      "sourceHash": "aaeb1a84",
+      "targetHash": "a8b07f51"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.45.0 — 2026-10-12
+
+### 🎉 Features
+
+- Adds `maintenance.auto=false` to the git config that the Vitest git-isolation setup file injects, so that a git command run by a test does not start a detached `git maintenance` process that can still be writing under `.git` when the test removes the repository. (#1033)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that `nmr-fmt` failed a run in which every path matched by the pathspecs was one that it skips, such as a symlink, a submodule gitlink, or an unreadable file, and makes such a run exit 0 and name the skipped paths on stderr. (#1010)
+- Fixes the issue that a `rootScripts` or `workspaceScripts` entry in `.config/nmr.config.ts` that names its own key, as a shell segment or as a step-list element, re-entered nmr without bound, by rejecting the entry when the config loads with an error that names the file, the field, the key, and the edit that resolves it. (#1011)
+- Fixes the issue that a package's own `package.json` entry running `nmr -R <same command>` re-entered that package without bound instead of being discarded or rejected as a self-reference. (#1011)
+- Fixes the issue that nmr treated a root entry such as `pnpm --recursive exec nmr build` as a re-invocation of its own command, because it ignored the `-r`, `--filter`, and `-w` flags that pnpm applies to the nmr that it launches. (#1011)
+- Fixes the issue that `nmr` hung when a script entry re-entered its own command in the same directory without nmr recognizing the self-reference, as `nmr -F own-pkg build` in `own-pkg`'s own `build` or a cycle through two entries does, by failing the run with an error that names the command and the directory and lists the commands that the run had entered, outermost first. (#1012)
+- Fixes the issue that the test-tier definitions in `vitest.md` gave a test that starts its own loopback server three defensible tiers: `tool` is now a process that the test starts or a program that the environment supplies, `localhost` a service already running on this machine, and an in-process server from the package's own dependency closure `unit`. (#1023)
+- Fixes the issue that `nmr`'s warning about a `package.json` script that runs `nmr` through a shell sent an entry whose whole value is `nmr <name>` to `.config/nmr.config.ts`, when the accurate edit is to replace that value with the command of the `<name>` script in the same file. (#1030)
+
+### ♻️ Refactoring
+
+- Moves the work of `runInvocation` in `nmr` into the phase functions `establishInvocation`, `planRun`, and `executePlan`, which `runCli` calls in order, and changes `runGated` and `reportRecording` to take a named `RunPlan` in place of an options object that repeated its fields. (#1014)
+
+### 🧪 Tests
+
+- Replaces the `GIT_CEILING_DIRECTORIES` stub with a `GIT_DIR` stub that points to a missing path in the no-repository test of `check-cache-gate.tool.test.ts`, and sets `maintenance.auto` to `false` in the file's fixture repository, so that git neither finds a leftover of the removed `repo/.git` nor starts a detached maintenance process that writes under `.git`. (#1032)
+
+## 0.44.0 — 2026-10-11
+
+### 🎉 Features
+
+- Enables Prettier's content-keyed cache in `nmr-fmt` (run by `nmr fmt` and `nmr fmt:check`), which skips each file whose content, Prettier version, resolved options, and lockfile are unchanged since a run that passed it, and adds `--no-cache` and `NMR_NO_CACHE=1` to bypass it. (#993)
+- Adds the `shouldRunInBackground` field to a composite element in `.config/nmr.config.ts`, which starts the step, runs the steps after it without waiting, prints the step's output whole after the step ends, and fails the composite if the step fails. (#1003)
+- Adds a `self-hosted runner` checklist to nmr's readyup kit, which reads the repo's GitHub settings through `gh`, recommends setting `CI_RUNS_ON` when a private repo with an online self-hosted runner and compatible workflows has not set it, and warns about each failing condition once the variable is set. (#1006)
+- Adds the root-only config key `selfHostedRunner.exempt`, a non-empty reason that stops the kit from recommending `CI_RUNS_ON` for a repo that qualifies for the self-hosted runners but stays off them. (#1006)
+
+### 🪦 Removed
+
+- 🚨 **Breaking:** Removes the zero-argument form of `getDefaultRootScripts` from the `@williamthorsen/nmr/scripts` export, which now requires the monorepo root so that it can read the declared workspaces. (#992)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that `root:lint`, `root:lint:check`, and `root:lint:strict` linted every workspace outside `packages/` under the root ESLint config, by excluding each workspace package that `pnpm-workspace.yaml` declares, with its `!` exclusions honored, in place of the fixed `packages/**`. (#992)
+- Fixes the issue that `defineConfig({ mode: undefined })` emptied the `nmr upgrade` report, by translating a cleared `mode` into the `'default'` mode of taze (the upgrade tool that `nmr upgrade` runs), which follows the range that each dependency declares. (#1008)
+
+### ⚡ Performance
+
+- Sets `maxWorkers: 3` on every project built by `defineVitestConfig` and `defineRootVitestConfig` when the machine has 2 or fewer cores, such as GitHub's standard runner for a private repo, on which Vitest's default ran every test file serially on one worker. (#994)
+- Changes the default `check` and `check:strict` to start lint first and run it in the background, so that a local check, `nmr ci`, and `nmr prepush` no longer wait for type-aware lint to finish before typecheck, the format check, and the tests run. (#1003)
+
+### 📚 Documentation
+
+- Documents in `docs/vitest.md` that Vitest's `--maxWorkers` flag has no effect on a machine with 2 or fewer cores, and that `VITEST_MAX_WORKERS`, `--no-file-parallelism`, or `maxWorkers` in the `project` seam overrides the default there. (#994)
+
 ## 0.43.0 — 2026-10-09
 
 ### 🎉 Features

package/README.md

@@ -5,11 +5,21 @@
 Context-aware script runner for pnpm monorepos. Includes 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.43.0 (2026-10-09)
+## Release notes — v0.45.0 (2026-10-12)
 
 ### 🎉 Features
 
-- Extends `nmr-compile` to compile `.tsx` sources and to rewrite relative `.tsx` specifiers to `.js`, and leaves the JSX transform to the package's own tsconfig `jsx` option. (#988)
+- Adds `maintenance.auto=false` to the git config that the Vitest git-isolation setup file injects, so that a git command run by a test does not start a detached `git maintenance` process that can still be writing under `.git` when the test removes the repository. (#1033)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that `nmr-fmt` failed a run in which every path matched by the pathspecs was one that it skips, such as a symlink, a submodule gitlink, or an unreadable file, and makes such a run exit 0 and name the skipped paths on stderr. (#1010)
+- Fixes the issue that a `rootScripts` or `workspaceScripts` entry in `.config/nmr.config.ts` that names its own key, as a shell segment or as a step-list element, re-entered nmr without bound, by rejecting the entry when the config loads with an error that names the file, the field, the key, and the edit that resolves it. (#1011)
+- Fixes the issue that a package's own `package.json` entry running `nmr -R <same command>` re-entered that package without bound instead of being discarded or rejected as a self-reference. (#1011)
+- Fixes the issue that nmr treated a root entry such as `pnpm --recursive exec nmr build` as a re-invocation of its own command, because it ignored the `-r`, `--filter`, and `-w` flags that pnpm applies to the nmr that it launches. (#1011)
+- Fixes the issue that `nmr` hung when a script entry re-entered its own command in the same directory without nmr recognizing the self-reference, as `nmr -F own-pkg build` in `own-pkg`'s own `build` or a cycle through two entries does, by failing the run with an error that names the command and the directory and lists the commands that the run had entered, outermost first. (#1012)
+- Fixes the issue that the test-tier definitions in `vitest.md` gave a test that starts its own loopback server three defensible tiers: `tool` is now a process that the test starts or a program that the environment supplies, `localhost` a service already running on this machine, and an in-process server from the package's own dependency closure `unit`. (#1023)
+- Fixes the issue that `nmr`'s warning about a `package.json` script that runs `nmr` through a shell sent an entry whose whole value is `nmr <name>` to `.config/nmr.config.ts`, when the accurate edit is to replace that value with the command of the `<name>` script in the same file. (#1030)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -107,12 +117,14 @@ Scripts resolve through three tiers. Higher tiers override lower ones:
 2. **Repo-wide config**: Additions and overrides in `.config/nmr.config.ts`
 3. **Per-package overrides**: Scripts in a package's `package.json`
 
-[Scripts and configuration](docs/scripts.md#three-tier-override-system) shows a worked example, how to skip a script for one package, and what nmr does with a `package.json` entry that re-invokes its own command.
+[Scripts and configuration](docs/scripts.md#three-tier-override-system) shows a worked example, how to skip a script for one package, and what nmr does with a `package.json` or `.config/nmr.config.ts` entry that re-invokes its own command.
 
 ## Pre and post hooks
 
 Every `nmr X` invocation auto-wraps as the equivalent of `nmr X:pre && nmr X && nmr X:post`. Hooks are first-class scripts that resolve through the same three tiers as any other script (built-in defaults, then `.config/nmr.config.ts`, then per-package `package.json`). Wrapping is uniform: Nested invocations from composite expansion get their own hook treatment. A failing hook ends the sequence, and its exit code propagates.
 
+A composite runs its steps in series, except a step declared with `shouldRunInBackground`, which runs alongside the steps after it. The default `check` and `check:strict` run lint that way; [Running a step in the background](docs/scripts.md#running-a-step-in-the-background) covers how its output prints and how it fails.
+
 Extend `nmr build` with a pre-build step for every workspace package:
 
 ```ts
@@ -255,6 +267,8 @@ Wiring the sync to `postinstall` keeps it current without a hand-run command:
 
 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-file conventions ([tier names](docs/vitest.md#test-tiers) and `__tests__` placement), that the repo's own suite gates them, that every `bin` target is a committed wrapper rather than build output that pnpm cannot link at install time, that `files` covers the output that each wrapper loads, that the root install scripts do not run `lefthook install` without `lefthook check-install`, and that the `package.json` files in the tree declare neither a `pnpm` field, from which pnpm 11 does not read any key, nor a `workspaces` field, which pnpm ignores. Those settings belong in `pnpm-workspace.yaml`, and `pnpx codemod run pnpm-v10-to-v11` moves the `pnpm` field's. It also checks that every manifest declares a package listed by a `pnpm-workspace.yaml` catalog as `catalog:` rather than as a literal version. A peer range is exempt, and a version that must differ belongs in a named catalog, referenced as `catalog:<name>`. The kit is included in 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 takes effect in the repo when it upgrades nmr. A repo that declares the [conventions check](docs/vitest.md#gating-the-test-file-conventions) gates both conventions in its own test run, and the kit then leaves the test files to that check.
 
+A second checklist, `self-hosted runner`, reads the repo's GitHub settings through `gh` and recommends setting `CI_RUNS_ON` to `"self-hosted"` when the repo is private, has an online `self-hosted` runner, does not pin a code-quality workflow older than v8 or override its `runs-on`, and runs Node.js and pnpm only after a step installs them and does not run `gh`, which the image lacks. Once the variable is set, the checklist warns about each of those conditions that fails. It skips when `gh` is not installed or not authenticated. A repo that qualifies but keeps its CI off the runners records why in the root config's [`selfHostedRunner.exempt`](docs/scripts.md#defineconfig-fields).
+
 Add `readyup` as a devDependency, then name nmr in its config:
 
 ```ts

package/agents/guidance/rulebooks/nmr.md

@@ -13,5 +13,5 @@ delivery: ambient
 - A check that already passed on the current working tree skips, printing `SKIP <scope>: <command>: passed …` and, when the recalled run left one, `— replayed: <excerpt>` of what that run concluded. Any edit, addition, or deletion re-runs it. Read the replayed excerpt rather than running the check again: Never pass `--no-cache` to get a "real" run, which takes 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 when there are too many to fit. A skip without an 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. Output that you need in full is a recording to read rather than a command to run again. It runs nothing, and it is held to the tree rather than to the terminal: A recording made by a piped run prints for a reader at one. A composite prints its constituents' excerpts, not their transcripts, so the transcript of one of them is `nmr -F <pkg> --log <command>` or that constituent's own name. When there is nothing to show, `--log` says so on one line, names which case it is, and exits non-zero.
 - Every command that nmr runs reports one line -- `PASS <scope>: <command>: passed in 12.4s`, `FAIL … failed in 1.2s (exit 1)`, `SKIP … passed 4m ago on this tree`, or `NOOP … skipped, the override is empty` -- and a composite reports alongside every command into which it expands. Those are the words that a pipe and a CI log get; a terminal gets ✅, ❌, ⏩, and ⚪ in their place, and `--output-style rich` or `NMR_OUTPUT_STYLE=rich` forces the emoji on any stream. The lines print in every verbosity, so `nmr -q <command>` is the low-noise way to run rather than a silent one: It withholds the output of the commands that nmr runs and keeps nmr's own verdicts, which is how a pass, a cached skip, and a `""`/`":"` override stay distinguishable. nmr reads its own flags only before the command name and passes everything after the name to the commands that run: `nmr ci -q` hands `-q` to `nmr-fmt`, which rejects it. 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 that the test reaches -- `tool` (a program supplied by the environment), `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 --sources` reports both and warns that the check is missing.
+- 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 that the test reaches -- `tool` (a process that the test starts, or a program that the environment supplies), `localhost` (a service already running 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 --sources` reports both and warns that the check is missing.
 - The rest is in `node_modules/@williamthorsen/nmr/docs/`: `scripts.md` for pre/post hooks (every `nmr X` auto-wraps as `nmr X:pre && nmr X && nmr X:post`) and script overrides and their `""`/`":"` skip values; `upgrades.md` for `nmr upgrade` ceilings (report-only until `nmr upgrade --write`); `utilities.md` for the `nmr-compile` build (the repo does not define a build script of its own); `vitest.md` for the test tiers' timeout budgets, the `tiers` seam that raises one, and which script reaches which tier; and `check-cache.md` for the check-result cache's key, the retention key to which a replayed excerpt is additionally held, the retention ceiling within which `--log` prints, its `checkCache` config, and every condition that disables it.

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

@@ -0,0 +1,26 @@
+/** The directory, relative to the repository root, holding one Prettier cache file per scope. */
+export declare const FMT_CACHE_DIRECTORY: string;
+export interface PrepareFmtCacheOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    repositoryRoot: string;
+    shouldBypassCache: boolean;
+}
+export type PrepareFmtCacheResult = {
+    kind: 'cached';
+    location: string;
+} | {
+    kind: 'uncached';
+} | {
+    kind: 'failed';
+    reason: string;
+};
+/**
+ * Resolves the Prettier cache file for this scope, after pruning cache files keyed to an outdated lockfile and
+ * discarding a corrupt one, or reports why the run goes uncached.
+ *
+ * The file name combines a hash of the scope with a fingerprint of the repository's lockfiles. Prettier keys
+ * entries by path relative to its working directory, so each scope needs a file of its own; Prettier's own key
+ * covers its version and the resolved options but not plugin code, which the lockfile fingerprint covers.
+ */
+export declare function prepareFmtCache(options: PrepareFmtCacheOptions): PrepareFmtCacheResult;

package/dist/esm/commands/fmt-cache.js

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { NO_CACHE_ENV_VAR } from "../check-cache.js";
+export const FMT_CACHE_DIRECTORY = path.join('node_modules', '.cache', 'prettier', 'nmr-fmt');
+const LOCKFILE_NAMES = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lock', 'bun.lockb'];
+const NO_LOCKFILE_MARKER = 'nolock';
+const HASH_LENGTH = 16;
+const CACHE_FILE_PATTERN = /^([0-9a-f]{16})\.([0-9a-f]{16}|nolock)\.json$/;
+export function prepareFmtCache(options) {
+    const { cwd, env, repositoryRoot, shouldBypassCache } = options;
+    if (shouldBypassCache || env[NO_CACHE_ENV_VAR] === '1')
+        return { kind: 'uncached' };
+    try {
+        if (statSync(path.join(repositoryRoot, 'node_modules'), { throwIfNoEntry: false })?.isDirectory() !== true) {
+            return { kind: 'uncached' };
+        }
+        const cacheDirectory = path.join(repositoryRoot, FMT_CACHE_DIRECTORY);
+        mkdirSync(cacheDirectory, { recursive: true });
+        const lockfileHash = hashLockfiles(repositoryRoot);
+        pruneOutdatedCacheFiles(cacheDirectory, lockfileHash);
+        const scope = path.relative(repositoryRoot, realpathSync(cwd)).split(path.sep).join('/');
+        const location = path.join(cacheDirectory, `${hash(scope)}.${lockfileHash}.json`);
+        if (isCorruptCacheFile(location))
+            rmSync(location, { force: true });
+        return { kind: 'cached', location };
+    }
+    catch (error) {
+        return { kind: 'failed', reason: describeError(error) };
+    }
+}
+function hash(input) {
+    return createHash('sha256').update(input).digest('hex').slice(0, HASH_LENGTH);
+}
+function hashLockfiles(repositoryRoot) {
+    const digest = createHash('sha256');
+    let hasLockfile = false;
+    for (const name of LOCKFILE_NAMES) {
+        const lockfilePath = path.join(repositoryRoot, name);
+        if (statSync(lockfilePath, { throwIfNoEntry: false })?.isFile() !== true)
+            continue;
+        digest.update(`${name}\0`).update(readFileSync(lockfilePath)).update('\0');
+        hasLockfile = true;
+    }
+    return hasLockfile ? digest.digest('hex').slice(0, HASH_LENGTH) : NO_LOCKFILE_MARKER;
+}
+function isCorruptCacheFile(location) {
+    let content;
+    try {
+        content = readFileSync(location, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    try {
+        JSON.parse(content);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function pruneOutdatedCacheFiles(cacheDirectory, lockfileHash) {
+    for (const name of readdirSync(cacheDirectory)) {
+        const match = CACHE_FILE_PATTERN.exec(name);
+        if (match !== null && match[2] !== lockfileHash) {
+            rmSync(path.join(cacheDirectory, name), { force: true });
+        }
+    }
+}

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

@@ -1,9 +1,13 @@
 export type FormatMode = 'check' | 'write';
 export interface FormatTargets {
+    /** Listed paths that Prettier cannot be handed, such as symlinks and submodule gitlinks. */
+    excludedFiles: string[];
     /** Paths relative to the working directory, as `git ls-files` emits them. */
     files: string[];
     /** Absolute paths to every `.prettierignore` governing the repository, root-most first. */
     ignorePaths: string[];
+    /** The repository's top-level directory, as git reports it. */
+    repositoryRoot: string;
     /** Listed paths that this process is denied access to, each with the errno code that its stat raised. */
     unreadableFiles: UnreadableFile[];
 }
@@ -20,7 +24,8 @@ export type ResolveTargetsResult = {
 };
 /**
  * Formats or checks the files that git reports for `cwd`, and returns the exit code to report. A repository
- * without a Prettier config of its own is formatted with the house config.
+ * without a Prettier config of its own is formatted with the house config. The run uses Prettier's content-keyed
+ * cache unless `--no-cache` or `NMR_NO_CACHE=1` bypasses it.
  *
  * 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
@@ -39,13 +44,15 @@ export declare function runFmt(argv: string[], cwd?: string): Promise<number>;
  * `pathspecs` narrow the selection and are passed to git verbatim: They have git pathspec semantics rather
  * than shell glob semantics.
  *
- * A listed path that this process is denied access to is set aside in `unreadableFiles`; any other stat failure
- * fails the resolution.
+ * A listed path that Prettier cannot be handed is set aside in `excludedFiles`, and one that this process is denied
+ * access to in `unreadableFiles`; any other stat failure fails the resolution.
  */
 export declare function resolveFormatTargets(cwd: string, pathspecs?: string[]): ResolveTargetsResult;
 /** @internal */
 export interface RunPrettierOptions {
     cliPath: string;
+    /** Absolute path of the cache file to pass to Prettier; the run is uncached when it is absent. */
+    cacheLocation?: string | undefined;
     /** Passed as `--config`, which replaces Prettier's own config discovery. */
     configPath?: string | undefined;
     mode: FormatMode;

package/dist/esm/commands/fmt.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { hasErrnoCode, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { isObject } from "../helpers/type-guards.js";
+import { prepareFmtCache } from "./fmt-cache.js";
 const IGNORE_FILENAME = '.prettierignore';
 const LIST_FILES_ARGS = ['ls-files', '-z', '--cached', '--others', '--exclude-standard'];
 const IGNORE_FILE_PATHSPEC = `*${IGNORE_FILENAME}`;
@@ -15,7 +16,7 @@ const UNREADABLE_CODES = ['EACCES', 'EPERM'];
 const PRETTIER_PACKAGE = 'prettier';
 const DEFAULT_CONFIG_PATH = fileURLToPath(new URL(`../prettier-default-config${path.extname(fileURLToPath(import.meta.url))}`, import.meta.url));
 const ARGUMENT_BUDGET_BYTES = 100_000;
-const USAGE = 'Usage: nmr-fmt (--check | --write) [pathspec...]';
+const USAGE = 'Usage: nmr-fmt (--check | --write) [--no-cache] [pathspec...]';
 const MODE_ARGS = {
     check: ['--check'],
     write: ['--list-different', '--write'],
@@ -32,15 +33,20 @@ export async function runFmt(argv, cwd = process.cwd()) {
         reportError(`nmr-fmt: ${resolvedTargets.error}`);
         return 1;
     }
-    const { files, ignorePaths, unreadableFiles } = resolvedTargets.targets;
+    const { excludedFiles, files, ignorePaths, repositoryRoot, unreadableFiles } = resolvedTargets.targets;
     for (const { file, code } of unreadableFiles) {
         process.stderr.write(`nmr-fmt: skipped ${file}, which cannot be read (${code})\n`);
     }
     if (files.length === 0) {
-        if (parsedArgs.pathspecs.length > 0) {
-            reportError(`nmr-fmt: the pathspecs did not match any formattable file: ${parsedArgs.pathspecs.join(', ')}`);
+        if (parsedArgs.pathspecs.length === 0)
+            return 0;
+        if (excludedFiles.length === 0 && unreadableFiles.length === 0) {
+            reportError(`nmr-fmt: the pathspecs did not match any file that git lists: ${parsedArgs.pathspecs.join(', ')}`);
             return 1;
         }
+        if (excludedFiles.length > 0) {
+            process.stderr.write(`nmr-fmt: nothing to format; skipped paths that are not regular files: ${excludedFiles.join(', ')}\n`);
+        }
         return 0;
     }
     const cli = resolvePrettierCli(cwd);
@@ -53,7 +59,17 @@ export async function runFmt(argv, cwd = process.cwd()) {
         reportError(`nmr-fmt: ${repositoryConfig.error}`);
         return 1;
     }
+    const cache = prepareFmtCache({
+        cwd,
+        env: process.env,
+        repositoryRoot,
+        shouldBypassCache: parsedArgs.shouldBypassCache,
+    });
+    if (cache.kind === 'failed') {
+        process.stderr.write(`nmr-fmt: running without the Prettier cache: ${cache.reason}\n`);
+    }
     return runPrettier({
+        cacheLocation: cache.kind === 'cached' ? cache.location : undefined,
         cliPath: cli.cliPath,
         configPath: repositoryConfig.found ? undefined : DEFAULT_CONFIG_PATH,
         mode: parsedArgs.mode,
@@ -73,6 +89,7 @@ export function resolveFormatTargets(cwd, pathspecs = []) {
     const ignoreFiles = runGit([...LIST_FILES_ARGS, '--', IGNORE_FILE_PATHSPEC], repositoryRoot);
     if (!ignoreFiles.ok)
         return ignoreFiles;
+    const excludedFiles = [];
     const files = [];
     const unreadableFiles = [];
     const listedPaths = dedupe(splitNulSeparated(listedFiles.stdout));
@@ -80,6 +97,7 @@ export function resolveFormatTargets(cwd, pathspecs = []) {
         const status = classifyListedFile(cwd, file);
         switch (status.kind) {
             case 'excluded':
+                excludedFiles.push(file);
                 break;
             case 'failed':
                 return { ok: false, error: status.error };
@@ -97,8 +115,10 @@ export function resolveFormatTargets(cwd, pathspecs = []) {
     return {
         ok: true,
         targets: {
+            excludedFiles: excludedFiles.toSorted(),
             files: files.toSorted(),
             ignorePaths: dedupe([path.join(repositoryRoot, IGNORE_FILENAME), ...discoveredIgnorePaths]),
+            repositoryRoot,
             unreadableFiles,
         },
     };
@@ -117,8 +137,13 @@ function classifyListedFile(cwd, file) {
 }
 function parseFmtArgs(argv) {
     let mode;
+    let shouldBypassCache = false;
     const pathspecs = [];
     for (const arg of argv) {
+        if (arg === '--no-cache') {
+            shouldBypassCache = true;
+            continue;
+        }
         if (arg === '--check' || arg === '--write') {
             const requestedMode = arg === '--check' ? 'check' : 'write';
             if (mode !== undefined && mode !== requestedMode) {
@@ -135,7 +160,7 @@ function parseFmtArgs(argv) {
     if (mode === undefined) {
         return { ok: false, error: 'Pass --check or --write.' };
     }
-    return { ok: true, mode, pathspecs };
+    return { ok: true, mode, pathspecs, shouldBypassCache };
 }
 function resolvePrettierCli(cwd) {
     const missingResult = {
@@ -172,12 +197,15 @@ async function findRepositoryConfig(manifestPath, cwd) {
     }
 }
 export function runPrettier(options) {
-    const { cliPath, configPath, mode, files, ignorePaths, cwd, budgetBytes = ARGUMENT_BUDGET_BYTES } = options;
+    const { cacheLocation, cliPath, configPath, mode, files, ignorePaths, cwd, budgetBytes = ARGUMENT_BUDGET_BYTES, } = options;
     const prettierArgs = [
         cliPath,
         ...(configPath === undefined ? [] : ['--config', configPath]),
         '--ignore-unknown',
         ...ignorePaths.flatMap((ignorePath) => ['--ignore-path', ignorePath]),
+        ...(cacheLocation === undefined
+            ? []
+            : ['--cache', '--cache-strategy', 'content', '--cache-location', cacheLocation]),
         ...MODE_ARGS[mode],
     ];
     let firstFailureStatus = 0;