@williamthorsen/nmr 0.44.0 → 0.46.0

package/dist/esm/steps.d.ts

@@ -41,10 +41,18 @@ export interface NmrStepTarget {
     isWorkspaceRoot: boolean;
 }
 /**
- * How a `package.json` entry names the command under which it is declared: as its whole value, or alongside
- * other steps. `sole` covers an entry with trailing arguments, which do not declare a step of their own.
+ * How an entry names the command under which it is declared: as its whole value, or alongside other steps.
+ * `sole` covers an entry with trailing arguments, which do not declare a step of their own.
  */
 export type SelfReference = 'chained' | 'sole';
+/**
+ * Where an entry resolves, which decides the scopes that `-w`, `-R`, and `-F` send its command to:
+ * - `root`: the root's `package.json` or the config's `rootScripts`, resolved at the monorepo root.
+ * - `package`: a non-root package's own `package.json`, resolved in that package alone.
+ * - `workspaceRegistry`: the config's `workspaceScripts`, resolved in every package that does not override the
+ *   command.
+ */
+export type SelfReferenceScope = 'package' | 'root' | 'workspaceRegistry';
 /**
  * Composes the structural step that re-invokes nmr for one composite element.
  *
@@ -94,24 +102,41 @@ export declare function quoteToken(token: string): string;
  */
 export declare function readNmrStep(step: Step): NmrStepTarget | undefined;
 /**
- * Reports whether a `package.json` entry re-invokes the command under which it is declared, and whether it
- * declares anything besides. Reports nothing for an entry that names another command, or none.
- *
- * Honouring such an entry would spawn a shell running the same command in the same directory, which reads the
- * same entry again without bound, so resolution discards it however it reads. `chained` separates an entry that
- * thereby loses steps from one that declares nothing to lose.
+ * Reports whether a string entry re-invokes the command under which it is declared, and whether it declares
+ * anything besides. Reports nothing for an entry that names another command, or none.
  *
- * A segment that delegates sends the command to other scopes rather than back to this one. `-w` re-enters
- * only from the root, a package's `-w` entry resolving against the root's registry and `package.json` instead of its own.
+ * Honouring such an entry would spawn a shell running the same command in a scope that reads the same entry
+ * again, without bound. `chained` separates an entry that thereby loses steps from one that declares nothing to
+ * lose.
  *
- * Partial in the same ways `findNmrCrossing` is, and for the same reason: What goes unrecognized re-enters
- * without bound, which hangs rather than passing quietly.
+ * Partial in the same ways `findNmrCrossing` is, and for the same reason: What goes unrecognized re-enters once,
+ * and the run fails when `enterChain` finds the command repeated in the same directory.
  */
 export declare function readSelfReference(options: {
-    anchoredAtRoot: boolean;
     commandName: string;
+    scope: SelfReferenceScope;
     script: string;
 }): SelfReference | undefined;
+/**
+ * Returns the command that a string script names when its whole value is `nmr <command>`, or `undefined` for any
+ * other value.
+ *
+ * Exact by design: A flag, an argument, an environment assignment, or a launcher each change what the invocation
+ * runs, or where, so a value that contains one is not interchangeable with the script that it names.
+ */
+export declare function readSoleNmrCommand(script: string): string | undefined;
+/**
+ * Reports whether a step list names the command under which it is declared, and whether it declares anything
+ * besides. Takes each element's instruction: the bare string, or a spec's `run`.
+ *
+ * Reads an element as the instruction that nmr composes into `nmr <element>`, and applies the declaring scope
+ * directly rather than through the `-w` that composition adds at the root.
+ */
+export declare function readStepListSelfReference(options: {
+    commandName: string;
+    elements: readonly string[];
+    scope: SelfReferenceScope;
+}): SelfReference | undefined;
 /**
  * Renders a step list as the `&&` chain that a shell runs.
  *

package/dist/esm/steps.js

@@ -49,18 +49,50 @@ export function readNmrStep(step) {
     return file === 'nmr' ? readNmrTarget(rest) : undefined;
 }
 export function readSelfReference(options) {
-    const { anchoredAtRoot, commandName, script } = options;
+    const { commandName, scope, script } = options;
     const segments = splitSegments(script).filter((segment) => segment.trim() !== '');
     const doesReenter = segments.some((segment) => {
-        const tail = readNmrTail(segment);
-        const target = tail === undefined ? undefined : readNmrTarget(tail);
-        return target?.command === commandName && !target.isDelegate && (anchoredAtRoot || !target.isWorkspaceRoot);
+        const invocation = readNmrTail(segment);
+        const target = invocation === undefined ? undefined : readNmrTarget(invocation.tail);
+        if (invocation === undefined || target === undefined) {
+            return false;
+        }
+        const launcherScope = readLauncherScope(invocation.launcher, invocation.launcherArgs);
+        const effectiveTarget = {
+            command: target.command,
+            isDelegate: target.isDelegate || launcherScope.isDelegate,
+            isRecursive: target.isRecursive || launcherScope.isRecursive,
+            isWorkspaceRoot: target.isWorkspaceRoot || launcherScope.isWorkspaceRoot,
+        };
+        return isReentry(effectiveTarget, commandName, scope);
     });
     if (!doesReenter) {
         return undefined;
     }
     return segments.length === 1 ? 'sole' : 'chained';
 }
+export function readSoleNmrCommand(script) {
+    const segments = splitSegments(script).filter((segment) => segment.trim() !== '');
+    if (segments.length !== 1) {
+        return undefined;
+    }
+    const [program, command, ...rest] = tokenizeSegment(segments[0] ?? '');
+    if (program !== 'nmr' || command === undefined || rest.length > 0) {
+        return undefined;
+    }
+    return SHELL_SAFE_TOKEN.test(command) && !command.startsWith('-') ? command : undefined;
+}
+export function readStepListSelfReference(options) {
+    const { commandName, elements, scope } = options;
+    const doesReenter = elements.some((element) => {
+        const target = readNmrTarget(tokenize(element));
+        return target !== undefined && isReentry(target, commandName, scope);
+    });
+    if (!doesReenter) {
+        return undefined;
+    }
+    return elements.length === 1 ? 'sole' : 'chained';
+}
 export function renderChain(steps) {
     return steps.map(renderStep).join(' && ');
 }
@@ -74,24 +106,59 @@ function isRedirectionOperator(char, precedingText, nextChar) {
     }
     return (char === '&' && nextChar === '>') || /[<>]\s*$/.test(precedingText);
 }
+function isReentry(target, commandName, scope) {
+    if (target.command !== commandName) {
+        return false;
+    }
+    switch (scope) {
+        case 'root':
+            return !target.isDelegate;
+        case 'package':
+            return target.isRecursive || (!target.isDelegate && !target.isWorkspaceRoot);
+        case 'workspaceRegistry':
+            return target.isDelegate || !target.isWorkspaceRoot;
+    }
+}
+function readLauncherScope(launcher, launcherArgs) {
+    const scope = { isDelegate: false, isRecursive: false, isWorkspaceRoot: false };
+    if (launcher !== 'pnpm') {
+        return scope;
+    }
+    for (const token of launcherArgs) {
+        if (token === '-r' || token === '--recursive') {
+            scope.isDelegate = true;
+            scope.isRecursive = true;
+        }
+        else if (token === '-F' || token === '--filter' || token.startsWith('--filter=')) {
+            scope.isDelegate = true;
+        }
+        else if (token === '-w' || token === '--workspace-root') {
+            scope.isWorkspaceRoot = true;
+        }
+    }
+    return scope;
+}
 function readNmrTail(segment) {
     const [head, ...rest] = dropLeadingAssignments(tokenizeSegment(segment));
     if (head === undefined) {
         return undefined;
     }
     if (head === 'nmr') {
-        return rest;
+        return { launcher: undefined, launcherArgs: [], tail: rest };
     }
     const subcommands = LAUNCHERS.get(head);
     if (subcommands === undefined) {
         return undefined;
     }
-    if (subcommands.size === 0) {
-        const nameIndex = rest.findIndex((token) => !token.startsWith('-'));
-        return nameIndex !== -1 && rest[nameIndex] === 'nmr' ? rest.slice(nameIndex + 1) : undefined;
+    const nmrIndex = subcommands.size === 0
+        ? rest.findIndex((token) => !token.startsWith('-'))
+        : rest.findIndex((token) => subcommands.has(token)) + 1;
+    if (nmrIndex <= 0 && subcommands.size > 0) {
+        return undefined;
     }
-    const subcommandIndex = rest.findIndex((token) => subcommands.has(token));
-    return subcommandIndex !== -1 && rest[subcommandIndex + 1] === 'nmr' ? rest.slice(subcommandIndex + 2) : undefined;
+    return rest[nmrIndex] === 'nmr'
+        ? { launcher: head, launcherArgs: rest.slice(0, nmrIndex), tail: rest.slice(nmrIndex + 1) }
+        : undefined;
 }
 function readNmrTarget(tokens) {
     let isDelegate = false;

package/dist/esm/taze.d.ts

@@ -8,6 +8,13 @@ import type { CheckOptions } from 'taze';
  */
 export type TazeConfig = {
     [K in keyof CheckOptions]?: CheckOptions[K] | undefined;
+} & {
+    /**
+     * Maturity period in days for each package pattern, read by `nmr-taze` rather than by taze. A key is a package
+     * name in which `*` matches any run of characters, and the first key that matches a package decides its period.
+     * Every other dependency keeps `maturityPeriod`.
+     */
+    packageMaturityPeriod?: Record<string, number> | undefined;
 };
 /**
  * Builds a taze configuration from nmr's shared upgrade policy and a repo's own settings.

package/dist/esm/tiers.d.ts

@@ -56,10 +56,12 @@ export interface TestFileScanOptions {
     excludedBasenames?: readonly string[];
 }
 /**
- * The isolation ladder, ordered by the furthest thing that a test reaches. A tier names what a test reaches, never
- * how it invokes it: A test driving a compiler through its JavaScript API is `tool`, exactly as one spawning `tsc`
- * would be. Each named tier's name is also its filename infix, so `parse.tool.test.ts` is collected by the `tool`
- * project.
+ * The isolation ladder, ordered by the furthest thing that a test reaches: `unit` runs only the package's own code
+ * and the libraries that it calls, and `tool` starts a process or makes another program do its work. A tier names
+ * what a test reaches, never how it invokes it: A test driving a compiler through its JavaScript API is `tool`,
+ * exactly as one spawning `tsc` would be, and so is an embedded test, which runs in-process an engine that the
+ * package installs, such as PGlite. Each named tier's name is also its filename infix, so `parse.tool.test.ts` is
+ * collected by the `tool` project.
  */
 export declare const TIER_NAMES: readonly ["unit", "tool", "localhost", "remote"];
 /** One of the four isolation tiers. */

package/dist/esm/vitest-git-isolation.js

@@ -3,8 +3,10 @@ process.env['GIT_CONFIG_GLOBAL'] = os.devNull;
 process.env['GIT_CONFIG_SYSTEM'] = os.devNull;
 process.env['GIT_CONFIG_NOSYSTEM'] = '1';
 process.env['GIT_ATTR_NOSYSTEM'] = '1';
-process.env['GIT_CONFIG_COUNT'] = '2';
+process.env['GIT_CONFIG_COUNT'] = '3';
 process.env['GIT_CONFIG_KEY_0'] = 'core.excludesFile';
 process.env['GIT_CONFIG_VALUE_0'] = os.devNull;
 process.env['GIT_CONFIG_KEY_1'] = 'core.attributesFile';
 process.env['GIT_CONFIG_VALUE_1'] = os.devNull;
+process.env['GIT_CONFIG_KEY_2'] = 'maintenance.auto';
+process.env['GIT_CONFIG_VALUE_2'] = 'false';

package/docs/reporting.md

@@ -65,6 +65,8 @@ Because the format is nmr's own reporting, and nmr does not tell the commands th
 
 `NMR_REPORT_FORMAT` is nmr's own as well, and sets how nmr renders its own verdicts. Its values are `text` and `json`; nmr reports any other non-empty value and exits 1, and an empty value reads as unset. `--json` sets it for the run and outranks an inherited value, and both values are spelled out so that either direction is expressible: Export `NMR_REPORT_FORMAT=json` for a shell whose consumer parses, and set `text` on one invocation to opt back out. The format has two sources, then, whereas a verbosity has four: It does not have a repo-level default or harness detection, because detection would hand every agent JSON in place of the prose that the [bundled guidance](../README.md#agent-guidance) teaches. See [reporting for a machine](#reporting-for-a-machine) for what the objects contain.
 
+`NMR_ENTRY_CHAIN` is nmr's own as well. It lists the commands that the current run has entered and the directories in which it entered them, and nmr passes it to every process that it starts, so that a process re-entering a command already running in its directory fails instead of repeating without end; see [self-referential entries](scripts.md#three-tier-override-system). Do not set it: nmr reports a value that it cannot read and exits 1.
+
 ### Output style
 
 `--output-style <auto|plain|rich>` sets the style for one invocation, and `NMR_OUTPUT_STYLE` sets it for a shell: `rich` marks each verdict with an emoji, such as ✅ or ❌, and `plain` prints a word in its place, such as `PASS` or `FAIL`, which a reader of a log can search for. `auto`, the default, defers to detection. Any other value is a usage error, and nmr exits with code 1, whichever source named it. The flag outranks the variable, and both accept `auto` as well as a style, so a shell exporting one style is overridable on one invocation in either direction.

package/docs/scripts.md

@@ -22,7 +22,13 @@ If the package does not declare its own override, the highest-tier value that is
 
 A `package.json` entry that re-invokes the command under which it is declared is never honored. Honoring `"build": "nmr build"` would spawn a shell running `nmr build` in the same directory, reaching the same entry again without bound, so nmr discards the entry and resolves the command from the tier below. An entry that contains only the self-reference, trailing arguments included, is discarded in silence: It does not declare any step that nmr would lose. Because discarding an entry that chains anything else onto it (`"build": "nmr build && rdy compile"`, or `"build": "rdy compile && nmr build"`) would lose those steps, nmr rejects the invocation instead, naming the file, the key, and where the steps belong. For an ordinary command that is a `<command>:pre` or `<command>:post` script: `"build:pre": "rdy verify"` and `"build:post": "rdy compile"` wrap nmr's own `build` rather than replacing it. For a hook entry it is the entry itself, since nmr does not wrap a `:pre` or `:post` script in any hooks of its own: `"build:post": "nmr build:post && rdy compile"` becomes `"build:post": "rdy compile"`.
 
-nmr recognizes the re-invocation wherever it appears in the entry, on the grammar that [the shelled-nmr line](#script-values) uses, and a segment containing `-F` or `-R` is not one: It hands the command to other scopes rather than back to this one. Nor is `-w` from inside a package, which targets the root's registry and the root's `package.json`. A filter that selects the declaring package is the hole in that exemption: `nmr -F own-pkg build` in `own-pkg`'s own `build` re-enters without bound, and nmr does not recognize it.
+nmr recognizes the re-invocation wherever it appears in the entry, on the grammar that [the shelled-nmr line](#script-values) uses, and decides from the scope flags whether it returns to the entry. At the root, a segment containing `-F` or `-R` is not one: It hands the command to the packages, and pnpm's recursion leaves the root out. Inside a package, `-w` is not one, since it targets the root's registry and the root's `package.json`, and `-R` is, since it fans out to every package, the declaring one included. pnpm's own `-r`, `--filter`, and `-w`, standing ahead of `exec nmr`, count as nmr's. A filter that selects the declaring package is the hole in the `-F` exemption: `nmr -F own-pkg build` in `own-pkg`'s own `build` re-enters the entry, and nmr does not recognize it.
+
+A `.config/nmr.config.ts` entry that names the key under which it is declared, as a shell segment of a string value or as a step-list element, is rejected when the config loads, so every command fails until it is fixed. Discarding it, as tier 3 does, would run the built-in default, which is a command that the repo did not declare. A `rootScripts` entry resolves at the root, so the root's scope rule applies to it. A `workspaceScripts` entry resolves in every package that does not override the command, so `-R` and `-F` re-enter it and only `-w` leaves it: `workspaceScripts: { build: ['-R build'] }` sends each package back to the same entry. The error names the file, the field, and the key, and the edit depends on the key. When nmr's built-in defaults define the key, delete the entry and move the steps that it adds to a `<command>:pre` or `<command>:post` script, which wraps nmr's own command: `workspaceScripts: { build: 'nmr build && rdy compile' }` becomes `workspaceScripts: { 'build:post': 'rdy compile' }`. For a hook, or a command that only the config defines, delete the re-invocation: The steps beside it are the command.
+
+Neither tier detects a cycle through two entries, such as `workspaceScripts: { build: ['-w build'] }` against the root's default `build: ['-R build']`, which also re-enters the entry.
+
+What recognition misses, the run itself stops. Each nmr process that resolves a command passes that command, with the directory from whose registry it resolved it, to the processes that it starts, in `NMR_ENTRY_CHAIN`. A process that finds its own command and directory already on that chain fails with an error naming both and listing the chain, outermost first, instead of running the entry again. Only the ancestors on the chain count, so a command that runs twice in sequence and a `<command>:pre` or `<command>:post` hook are unaffected, and a `-R` or `-F` fan-out, which resolves nothing itself, neither checks the chain nor extends it.
 
 ### Script values
 
@@ -71,9 +77,11 @@ A string value is spawned through a shell as one command. An `nmr` invocation in
 
 The line names the declaration to which it is an edit (the file, the field, and the key), and its remedy follows from that site. In a `.config/nmr.config.ts` entry, keep the nmr steps as a step list and move anything else to a `<command>:pre` or `<command>:post` script: A step-list element can name only an nmr command, because nmr composes it into `nmr <element>`. A `package.json` entry has to go, since `package.json` cannot declare a step list: Delete it outright when it restates what nmr already runs for that command, and move the steps that it adds to a `<command>:pre` or `<command>:post` script when they are the package's own. When the registry does not define that command, both apply: Name the command in `.config/nmr.config.ts`, and put the package-specific steps in a hook. The pair is named rather than `:post` alone because an entry's extra steps may run on either side of the chain: `rdy verify && nmr compile` puts them first. A hook is the exception at both tiers: nmr does not wrap a `:pre` or `:post` script in any hooks of its own. Move a hook's other steps to a script of their own, and name that script in the step list.
 
+One kind of `package.json` entry is resolved in its own file: an entry whose whole value is `nmr <name>`, without flags, arguments, assignments, or a launcher, where `<name>` is a script in the same `package.json` that runs a command other than nmr and does not have a `:pre` or `:post` hook. Replace the entry's value with that command, and delete the script: `"build:pre": "nmr compile:ports"` beside `"compile:ports": "node scripts/compile-ports.ts"` becomes `"build:pre": "node scripts/compile-ports.ts"`. Keep the script when the registry also defines `<name>`, because the script then overrides nmr's own command. The script must come from the same file: Inlining a command that resolves from the registry would copy nmr's own command text into the package, where nmr's later changes do not reach it.
+
 nmr recognizes `nmr` in command position: at the start of a step, after an unquoted `&&`, `||`, `;`, `|`, or a newline, past any leading `NAME=value` assignments, and behind `npx`, `bunx`, or an `exec`, `dlx`, or `x` subcommand of `npm`, `pnpm`, `yarn`, or `bun`. This line reports a boundary rather than enforcing a rule: It covers a step that nmr runs as written, and only the reporting of the nested run is degraded. The line is also partial in three ways: a value-taking flag standing immediately before the program name hides it (`npx -p foo nmr`), a launcher outside that set goes unreported, and a `devBin` substitution that introduces `nmr` itself is not reported, the line being an edit to a declaration rather than to a substitution.
 
-A [self-referential `package.json` entry](#three-tier-override-system) is the shape that nmr cannot run as written, and it is rejected rather than reported. The same recognition finds it, so the same residuals apply: What goes unrecognized there re-enters nmr without bound, which hangs rather than passing quietly.
+A [self-referential entry](#three-tier-override-system), in `package.json` or in `.config/nmr.config.ts`, is the shape that nmr cannot run as written, and it is rejected rather than reported. The same recognition finds it, so the same residuals apply: What goes unrecognized there re-enters nmr once, and the run then fails with an error naming the command and the directory that it re-entered.
 
 ## Pre and post hooks
 

package/docs/upgrades.md

@@ -51,6 +51,34 @@ Two consequences of the `minor` range mode declared by the policy:
 - A `packageMode` entry is honored only by the pass whose mode matches it, or by a `default` pass; every other pass drops that dependency rather than narrowing it. Under the policy's `minor` mode, a `patch` ceiling hides its dependency until a developer runs `nmr upgrade patch`, and a `minor` ceiling hides it from `nmr upgrade major`.
 - A `~` range is searched as `^`, so minor upgrades are proposed for it and `--write` applies them under the original `~`. To hold one dependency to patches, give it a `packageMode` entry of `patch` and read it from `nmr upgrade patch`; to hold the whole repo there, declare `mode: 'patch'`.
 
+### Per-package maturity periods
+
+`packageMaturityPeriod` gives the packages that match a pattern a quarantine of their own, in days. Every other dependency keeps `maturityPeriod`. taze applies one maturity period to a whole run, so `nmr upgrade` runs it once for each entry and once more for every other dependency, each run headed on stderr by the patterns and the period that it covers. The command exits with the first non-zero exit code among the runs.
+
+```ts
+import { defineConfig } from '@williamthorsen/nmr/taze';
+
+export default defineConfig({
+  // Propose first-party releases after one day, and third-party ones after the policy's seven.
+  packageMaturityPeriod: {
+    '@williamthorsen/*': 1,
+    readyup: 1,
+  },
+});
+```
+
+A key is a package name in which `*` matches any run of characters; a regex key, a key containing a comma, or a version selector such as `typescript@7` fails the command before taze runs. When several keys match a package, the first one decides its period. A period of `0` removes the quarantine for those packages.
+
+A package listed in `maturityPeriodExclude`, or in the `minimumReleaseAgeExclude` of `pnpm-workspace.yaml`, which taze inherits into it, skips the quarantine in every run. Remove it from that list before giving it a period here.
+
+`--maturity-period <days>` on the command line applies one period to every dependency for that call, in a single run:
+
+```bash
+nmr upgrade --maturity-period 0
+```
+
+Every other argument reaches every run, and `--include` and `--exclude` narrow each run as they narrow a single one. Because each run reports separately, `--json` prints one document per run, `--interactive` opens one selection per run, and `--install` installs after each run.
+
 ## Request timeout
 
 Every `upgrade` script calls the upgrade tool with a 30-second request timeout, in place of the tool's own 5 seconds.
@@ -101,7 +129,7 @@ nmr report-overrides
 
 ## `nmr-taze`
 
-Run the [taze](https://github.com/antfu-collective/taze) dependency-upgrade tool, forwarding every argument to it untouched and adding one of its own: a 30-second request timeout, unless the invocation already includes one. Every `upgrade` chain ends with it, `root:upgrade` included; see [dependency upgrades](#dependency-upgrades) for the workflow, and [request timeout](#request-timeout) for why the timeout is set here.
+Run the [taze](https://github.com/antfu-collective/taze) dependency-upgrade tool, forwarding every argument to it and adding a 30-second request timeout, unless the invocation already includes one. When the taze config declares [per-package maturity periods](#per-package-maturity-periods), it runs taze once per period, adding to each run the filters and the period that confine it. Every `upgrade` chain ends with it, `root:upgrade` included; see [dependency upgrades](#dependency-upgrades) for the workflow, and [request timeout](#request-timeout) for why the timeout is set here.
 
 Under pnpm's isolated `node_modules`, a transitive package's binary is absent from the consuming repo's `node_modules/.bin`, so a repo that depends on nmr cannot run `taze` directly. `nmr-taze` can, because nmr is a direct dependency, and it resolves the tool from the tree that nmr controls.
 

package/docs/utilities.md

@@ -47,9 +47,9 @@ nmr-fmt --write packages/nmr
 
 `fmt` and `fmt:check` format the files that git reports: tracked files, plus untracked files that git does not ignore. Prettier reads `.gitignore` and `.prettierignore` from the working directory alone, so a pattern in `packages/<pkg>/.gitignore` never applies to a run started at the monorepo root. Because git knows the whole hierarchy, including `.git/info/exclude` and `core.excludesFile`, and every `.prettierignore` in the tree is discovered from the repository root, package-level exclusions apply from any directory as well.
 
-A file that git ignores is never formatted, even when named directly. Because trailing arguments are git pathspecs rather than Prettier flags, `nmr fmt:check packages/nmr` narrows the run, while an unrecognized option and a pathspec that does not match any formattable file both fail it. Running outside a git repository fails rather than reporting a clean run.
+A file that git ignores is never formatted, even when named directly. Because trailing arguments are git pathspecs rather than Prettier flags, `nmr fmt:check packages/nmr` narrows the run, while an unrecognized option and a pathspec for which git lists no file both fail it. Running outside a git repository fails rather than reporting a clean run.
 
-`nmr-fmt` drops paths that the index names but the filesystem does not have (a file deleted but not yet staged), submodule gitlinks, and symlinks whatever they point at, before calling Prettier, which rejects a symlink named explicitly. It also skips a path that it is denied access to, such as a `.envrc` that a sandbox shields, and names each one on stderr, so that a check that passes does not hide a file that it never read. Any other failure to stat a listed path fails the run, with an error that names the path.
+`nmr-fmt` drops paths that the index names but the filesystem does not have (a file deleted but not yet staged), submodule gitlinks, and symlinks whatever they point at, before calling Prettier, which rejects a symlink named explicitly. It also skips a path that it is denied access to, such as a `.envrc` that a sandbox shields, and names each one on stderr, so that a check that passes does not hide a file that it never read. A pathspec whose every match is skipped still counts as matched: The run passes and names the skipped paths on stderr, so that a pre-commit hook passing only staged symlinks or a submodule bump does not fail. Any other failure to stat a listed path fails the run, with an error that names the path.
 
 ### Cache
 

package/docs/vitest.md

@@ -10,18 +10,24 @@ The [README](../README.md#shared-vitest-config) shows the one-line config file.
 
 The config declares four projects, an ordered ladder named for the furthest thing that a test reaches:
 
-| Project     | Matches                                     | Reaches                                              |
-| ----------- | ------------------------------------------- | ---------------------------------------------------- |
-| `unit`      | every test file that the others don't claim | nothing outside the package's own dependency closure |
-| `tool`      | `*.tool.test.{ts,tsx}`                      | a program that the environment must supply           |
-| `localhost` | `*.localhost.test.{ts,tsx}`                 | a service running on this machine                    |
-| `remote`    | `*.remote.test.{ts,tsx}`                    | a machine that isn't this one                        |
+| Project     | Matches                                     | Reaches                                                                                                        |
+| ----------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `unit`      | every test file that the others don't claim | only the package's own code and the libraries that it calls                                                    |
+| `tool`      | `*.tool.test.{ts,tsx}`                      | a process that the test starts, or a program other than the package's own code that the test makes do its work |
+| `localhost` | `*.localhost.test.{ts,tsx}`                 | a service already running on this machine                                                                      |
+| `remote`    | `*.remote.test.{ts,tsx}`                    | a machine that isn't this one                                                                                  |
 
 All four match only under a `__tests__` directory.
 
-**A tier names what a test reaches, never how it invokes it.** A test driving a compiler through its JavaScript API is `tool`, exactly as one spawning the compiler binary is; whether a program ships as a library or an executable is an accident of packaging, not a property of the test. A package's `peerDependencies`, plus whatever binaries it spawns, are a good statement of where its `tool` boundary is: A bundled dependency is inside the package's own closure and is always present, so reaching one is `unit`.
+**A tier names the furthest program that a test makes do its work.** A test is `unit` while everything that it runs is the package's own code or a library that the code calls for a result. It is `tool` when it starts a process, or when it makes a program other than the package's own code do its work, whether the environment supplies that program or the package installs it. The machine sets how long such a program takes to start and to run, which is why a spawned process counts even when it runs the package's own code.
 
-**A tier is not a statement about preconditions.** A `unit` test may still need something set up before it runs: a build, a generated fixture, a seeded file. It is `unit` because it reaches nothing beyond the test process _while running_. The filesystem belongs to `unit` for the same reason the tiers exist: They gate on what must be available, and the filesystem always is.
+**A tier names what a test reaches, never how it invokes it.** A test driving a compiler through its JavaScript API is `tool`, exactly as one spawning the compiler binary is; whether a program ships as a library or an executable is an accident of packaging, not a property of the test. The same holds for an **embedded** test, which runs, inside the test process, an engine that the package installs as a dependency and that is not the package's own code. An engine does a job of its own, such as a database, a compiler, or a bundler; a library is a set of functions that the code calls for a result. Embedded tests are `tool`: A test that starts PGlite (Postgres compiled to WebAssembly) is `tool`, and a test that calls a parsing library is `unit`.
+
+**A service that the test starts itself takes the tier of the code that runs it.** A test that calls `net.Server.listen(0)` on a server implemented by the package's own code and reaches it with `fetch` is `unit`: Both ends of the loopback connection are inside the test process, and the connection is how the test invokes that code. The same server started as a child process is `tool`, as is a service whose program the environment supplies, such as a `postgres` binary, or one that the package installs, such as PGlite. `localhost` is for a service that is already running when the test starts, such as a separately started backend or a seeded database.
+
+**`peerDependencies` name candidate tools; they do not classify a test.** A package's peers, with the binaries that it spawns and the engines that it installs, are the programs that its tests might make do their work, and a test is `tool` only when it does. A test that imports `AST_NODE_TYPES` from `@typescript-eslint/utils` for its constants, or calls a helper that ships beside a tool and does none of the tool's work, stays `unit`; a test that runs ESLint over a fixture is `tool`. That the peer must be installed for the import to succeed is a precondition, not a tier argument, as the next paragraph states.
+
+**A tier is not a statement about preconditions.** A `unit` test may still need something set up before it runs: a build, a generated fixture, a seeded file, an installed peer. It is `unit` because it does not make any program beyond its own code do work _while running_. The filesystem belongs to `unit` for the same reason: Reaching it does not run another program, and it is always available.
 
 **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`.
 
@@ -103,7 +109,7 @@ In a repo that has not declared the check, [nmr's readyup kit](../README.md#conf
 Two settings that a workspace test runner needs almost universally are part of what the factory produces, so a config file declares neither:
 
 - **A package outside `node_modules` resolves from source.** Because a cross-package import resolves to the dependency's `.ts` rather than its `dist/`, through the `source` condition declared by its `exports` map, a suite runs without a prior build. The reach is what the boundary names: a workspace package, or one linked into the repo from elsewhere, whose real path is outside every `node_modules`. A package that does not declare a `source` condition is unaffected, and so is every package under `node_modules`, whatever its `exports` map declares.
-- **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: Because neither path is config-derived, git resolves each from `$XDG_CONFIG_HOME/git/`, or from `~/.config/git/` when that variable is unset, whatever the config variables say. `GIT_CONFIG_GLOBAL` already replaces `$XDG_CONFIG_HOME/git/config`; those two are the rest of what that directory supplies. The system attributes file at `$(prefix)/etc/gitattributes` is not named by any config variable at all, which is what `GIT_ATTR_NOSYSTEM` covers. Redirecting `XDG_CONFIG_HOME` would cover the per-user pair as well, but the setup file does not redirect it, 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 that the layers add, because a shared setup establishes the environment in which the rest run.
+- **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`, `core.attributesFile`, and `maintenance.auto=false` 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, and a command such as `git commit` does not start a detached `git maintenance` process that could still be writing under `.git` when the test removes the repository. Those last two need a step of their own: Because neither path is config-derived, git resolves each from `$XDG_CONFIG_HOME/git/`, or from `~/.config/git/` when that variable is unset, whatever the config variables say. `GIT_CONFIG_GLOBAL` already replaces `$XDG_CONFIG_HOME/git/config`; those two are the rest of what that directory supplies. The system attributes file at `$(prefix)/etc/gitattributes` is not named by any config variable at all, which is what `GIT_ATTR_NOSYSTEM` covers. Redirecting `XDG_CONFIG_HOME` would cover the per-user pair as well, but the setup file does not redirect it, 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 that the layers add, because a shared setup establishes the environment in which the rest run.
 
 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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -77,13 +77,14 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.13.2",
+    "@williamthorsen/nmr-core": "0.13.3",
     "@williamthorsen/toolbelt.errors": "0.8.3",
     "@williamthorsen/toolbelt.filesystem": "0.9.3",
     "glob": "13.0.6",
     "prettier": "3.9.9",
     "prettier-plugin-sh": "0.20.2",
-    "taze": "21.3.0"
+    "taze": "21.3.0",
+    "unconfig": "7.5.0"
   },
   "devDependencies": {
     "@williamthorsen/toolbelt.testing": "0.6.3",
@@ -92,7 +93,7 @@
     "readyup": "0.40.0",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
-    "vite": "8.3.2",
+    "vite": "8.3.3",
     "vitest": "4.1.11",
     "yaml": "2.9.1"
   },