@williamthorsen/nmr 0.43.0 → 0.45.0

package/dist/esm/steps.d.ts

@@ -8,8 +8,9 @@
  * `shouldDeclineArguments` is passed from the composite element that composed the step to the one reader that acts
  * on it, the binding of the invocation's trailing arguments. Every stage between the two passes it through unread.
  *
- * `shouldWithholdInput` is read by the runner alone, which gives the step's child the null device as stdin rather
- * than nmr's own. Like `shouldDeclineArguments`, it is set only when it holds and leaves the rendered chain unchanged.
+ * `shouldRunInBackground` and `shouldWithholdInput` are read by the runner alone. The first starts the step without
+ * waiting for it; the second gives the step's child the null device as stdin rather than nmr's own. Like
+ * `shouldDeclineArguments`, each is set only when it holds and leaves the rendered chain unchanged.
  */
 export type Step = {
     kind: 'opaque';
@@ -18,8 +19,14 @@ export type Step = {
     kind: 'structural';
     argv: readonly [string, ...(readonly string[])];
     shouldDeclineArguments?: boolean;
+    shouldRunInBackground?: boolean;
     shouldWithholdInput?: boolean;
 };
+/** The declarations that a composite element adds to the step that it composes. */
+export interface StepFlags {
+    shouldDeclineArguments?: boolean | undefined;
+    shouldRunInBackground?: boolean | undefined;
+}
 /** What a structural step asks of the nmr process that it spawns. */
 export interface NmrStepTarget {
     command: string;
@@ -34,20 +41,28 @@ 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.
  *
  * The element tokenizes on whitespace, so it may contain nmr's own flags but cannot contain a space-bearing
  * token. `-w` is prepended as its own token: The child selects the root registry on its own.
  *
- * Because `shouldDeclineArguments` is set only when it holds, a step that takes the trailing arguments compares
- * equal to one composed without the option.
+ * Because each flag is set only when it holds, a step composed with a flag at `false` compares equal to one
+ * composed without it.
  */
-export declare function composeNmrStep(element: string, isWorkspaceRoot: boolean, shouldDeclineArguments?: boolean): Step;
+export declare function composeNmrStep(element: string, isWorkspaceRoot: boolean, flags?: StepFlags): Step;
 /**
  * Returns the steps that still run in a workspace without any package: every step but the ones that a `-R` fans
  * out.
@@ -87,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.
+ * 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.
  *
- * 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.
+ * 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.
  *
- * 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.
- *
- * 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

@@ -11,12 +11,14 @@ const QUOTES = new Set(['"', "'"]);
 const SEGMENT_SEPARATORS = new Set([';', '|', '&', '\n', '\r']);
 const SHELL_SAFE_TOKEN = /^[\w@%+=:,./-]+$/;
 const TOKEN_SEPARATORS = new Set([' ', '\t', '\n', '\r']);
-export function composeNmrStep(element, isWorkspaceRoot, shouldDeclineArguments = false) {
-    const flags = isWorkspaceRoot ? ['-w'] : [];
+export function composeNmrStep(element, isWorkspaceRoot, flags = {}) {
+    const { shouldDeclineArguments = false, shouldRunInBackground = false } = flags;
+    const nmrFlags = isWorkspaceRoot ? ['-w'] : [];
     return {
         kind: 'structural',
-        argv: ['nmr', ...flags, ...tokenize(element)],
+        argv: ['nmr', ...nmrFlags, ...tokenize(element)],
         ...(shouldDeclineArguments && { shouldDeclineArguments }),
+        ...(shouldRunInBackground && { shouldRunInBackground }),
     };
 }
 export function dropRecursiveSteps(steps) {
@@ -47,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(' && ');
 }
@@ -72,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

@@ -12,8 +12,11 @@ export type TazeConfig = {
 /**
  * Builds a taze configuration from nmr's shared upgrade policy and a repo's own settings.
  *
- * Any property that the caller supplies wins, including `0` and an explicit `undefined`. The latter restores
- * taze's inheritance of pnpm's `minimumReleaseAge`, which only applies while `maturityPeriod` is unset.
+ * Any property that the caller supplies wins, including `0` and an explicit `undefined`, which clears nmr's
+ * default and hands the setting back to taze. Clearing `maturityPeriod` restores taze's inheritance of pnpm's
+ * `minimumReleaseAge`, which only applies while it is unset. Clearing `mode` yields taze's own `'default'`, which
+ * follows each declared range; passed through as `undefined`, it would overwrite taze's default and leave no
+ * valid range to search.
  *
  * The merge is shallow, which suits a policy of scalar defaults. A nested default would clobber rather
  * than merge, so adding one means revisiting this.

package/dist/esm/taze.js

@@ -4,5 +4,8 @@ const SHARED_POLICY = {
     mode: 'minor',
 };
 export function defineConfig(config) {
-    return { ...SHARED_POLICY, ...config };
+    const merged = { ...SHARED_POLICY, ...config };
+    if ('mode' in config && config.mode === undefined)
+        merged.mode = 'default';
+    return merged;
 }

package/dist/esm/tiers.d.ts

@@ -56,10 +56,11 @@ 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, which decides what the environment must
+ * supply for the test to run. 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 a spawned process is itself
+ * something reached. 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/types.d.ts

@@ -28,6 +28,15 @@ export interface CheckCacheConfig {
      */
     extraCommands?: string[];
 }
+/** Self-hosted runner settings honored at the monorepo root, read by nmr's readyup kit. */
+export interface SelfHostedRunnerConfig {
+    /**
+     * Why the repo keeps its CI off the self-hosted runners although it qualifies, such as a circular dependency on
+     * the runners themselves. Declaring it stops the kit from recommending `CI_RUNS_ON`. A missing tool is not a
+     * reason: A workflow step installs it.
+     */
+    exempt: string;
+}
 /** Output settings honored at the monorepo root. */
 export interface OutputConfig {
     /**
@@ -49,4 +58,5 @@ export interface NmrConfig {
     output?: OutputConfig;
     workspaceScripts?: Record<string, ScriptValue>;
     rootScripts?: Record<string, ScriptValue>;
+    selfHostedRunner?: SelfHostedRunnerConfig;
 }

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/dist/esm/vitest.js

@@ -1,3 +1,4 @@
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defaultExclude, mergeConfig } from 'vitest/config';
@@ -6,9 +7,12 @@ 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";
+import { toWorkspacePackageGlobs } from "./workspace-globs.js";
 const [RESIDUAL_TIER, ...NAMED_TIERS] = TIER_NAMES;
 const TIERED_PATTERNS = NAMED_TIERS.flatMap(buildTierPatterns);
 const TIER_TIMEOUT_MS = 30_000;
+const SMALL_MACHINE_MAX_CORES = 2;
+const SMALL_MACHINE_MAX_WORKERS = 3;
 const GIT_ISOLATION_SETUP_FILE = resolveGitIsolationSetupFile();
 const CLIENT_CONDITIONS = ['module', 'browser', 'development|production'];
 const SERVER_CONDITIONS = ['module', 'node', 'development|production'];
@@ -49,7 +53,7 @@ export function defineRootVitestConfig(...layers) {
     return buildConfig(layers, {
         coverageInclude: [],
         ignoredPathsRoot: monorepoRoot,
-        projectExclude: getWorkspaceExcludePatterns(monorepoRoot),
+        projectExclude: toWorkspacePackageGlobs(monorepoRoot, getWorkspacePackageDirs(monorepoRoot)),
         projectRoot: monorepoRoot,
     });
 }
@@ -95,6 +99,7 @@ function buildProjects(layers, extraExclude, projectRoot, ignoredPathsRoot) {
         })),
     ];
     const collectionExclude = buildCollectionExclude(layers, ignoredPathsRoot);
+    const maxWorkers = resolveDefaultMaxWorkers();
     const shouldIsolateGit = resolveFlag(layers, 'shouldIsolateGit', true);
     return projectTiers.map(({ exclude, include, name, timeoutMs }) => {
         const project = {
@@ -103,6 +108,7 @@ function buildProjects(layers, extraExclude, projectRoot, ignoredPathsRoot) {
             test: {
                 exclude: [...collectionExclude, ...exclude, ...extraExclude],
                 include,
+                ...(maxWorkers !== undefined && { maxWorkers }),
                 name,
                 ...(shouldIsolateGit && { setupFiles: [GIT_ISOLATION_SETUP_FILE] }),
                 ...(timeoutMs !== undefined && { hookTimeout: timeoutMs, testTimeout: timeoutMs }),
@@ -169,10 +175,8 @@ function formatOptionKeys(keys) {
         .map((key) => `\`${key}\``)
         .join(', ');
 }
-function getWorkspaceExcludePatterns(monorepoRoot) {
-    return getWorkspacePackageDirs(monorepoRoot)
-        .map((dir) => `${path.relative(monorepoRoot, dir).split(path.sep).join('/')}/**`)
-        .toSorted();
+function resolveDefaultMaxWorkers() {
+    return os.availableParallelism() <= SMALL_MACHINE_MAX_CORES ? SMALL_MACHINE_MAX_WORKERS : undefined;
 }
 function resolveFlag(layers, name, isOnByDefault) {
     let resolvedFlag = isOnByDefault;

package/dist/esm/workspace-globs.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Renders each package directory as a glob, relative to `monorepoRoot`, that matches everything beneath it, sorted. A
+ * directory that is the root itself is skipped, since its glob would match the whole repo.
+ */
+export declare function toWorkspacePackageGlobs(monorepoRoot: string, packageDirs: readonly string[]): string[];

package/dist/esm/workspace-globs.js

@@ -0,0 +1,8 @@
+import path from 'node:path';
+export function toWorkspacePackageGlobs(monorepoRoot, packageDirs) {
+    return packageDirs
+        .map((dir) => path.relative(monorepoRoot, dir).split(path.sep).join('/'))
+        .filter((relativeDir) => relativeDir !== '')
+        .map((relativeDir) => `${relativeDir}/**`)
+        .toSorted();
+}

package/docs/check-cache.md

@@ -148,6 +148,8 @@ Try these in order; the first is almost always the right one.
 | `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` and `NMR_NO_CACHE=1` also bypass the Prettier cache that `nmr-fmt` keeps, because nmr exports `NMR_NO_CACHE=1` to the commands that it runs. nmr exports it too when a command is given trailing arguments, so `nmr fmt:check <pathspec>` runs uncached. See [`nmr-fmt`'s cache](utilities.md#cache).
+
 `--no-cache` belongs before the command name. After it, it is an argument to the command rather than a flag to nmr; nmr reports this rather than silently ignoring the bypass.
 
 ## Reserved environment variables

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
 
@@ -35,6 +41,21 @@ A script value is a string or an array of steps. Only the built-in defaults and
 
 Each array element is a command name, optionally preceded by nmr's own flags, split on whitespace: `-R test` runs the element in every package, the way `nmr -R test` does. An element containing a quoted argument or shell syntax is rejected when the config loads: Name that command as a script of its own and reference the name.
 
+#### Running a step in the background
+
+A composite runs its steps in series. An element declared with `shouldRunInBackground` starts and is left running while the steps after it run:
+
+```ts
+// "check:strict": [{ run: "lint:strict", shouldRunInBackground: true }, "typecheck", "fmt:check", "test"]
+// nmr lint:strict runs alongside nmr typecheck, then nmr fmt:check, then nmr test
+```
+
+The background step's output is held rather than streamed, and printed whole at the first step boundary after the step ends, so it never interleaves with another step's output. When nmr writes to a terminal, the step receives `FORCE_COLOR=1`, unless `NO_COLOR` or `FORCE_COLOR` is already set, so that its tools keep their colour. Its stdin is the null device.
+
+A failing step in the foreground still ends the sequence, but the composite waits for every background step that has started and prints its output. The composite fails if any step failed, and each step's own verdict line names its failure. While a background step runs, nmr forwards a SIGINT or SIGTERM that it receives to every running step.
+
+Put a step in the background when it uses fewer cores than the machine has and the steps after it do not read what it writes. The default `check` and `check:strict` run their lint step this way, because type-aware lint runs on one core while the test fan-out leaves cores idle.
+
 #### Where trailing arguments go
 
 nmr passes trailing arguments to every step of a composite, so `nmr fix --dry-run` runs `nmr lint --dry-run`, then `nmr fmt --dry-run`. A step whose work the arguments cannot narrow declines them by taking the long form of an element, and runs unnarrowed:
@@ -56,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
 
@@ -91,14 +114,15 @@ A minimal `.config/nmr.config.ts` is in the [README](../README.md#configuration)
 
 ### `defineConfig` fields
 
-| Field              | Type                                                                          | Description                                                                         |
-| ------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `build`            | `{ extraIgnorePatterns?: string[] }`                                          | Patterns added to the build's ignore set (package config only)                      |
-| `checkCache`       | `{ enabled?: boolean; extraCommands?: string[]; excludeCommands?: string[] }` | Which commands the [check-result cache](check-cache.md#check-result-cache) may skip |
-| `workspaceScripts` | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the workspace registry (tier 2)                      |
-| `rootScripts`      | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the root registry (tier 2)                           |
-| `devBin`           | `Record<string, string>`                                                      | Map binary names to source-repo replacement commands                                |
-| `output`           | `{ commandVerbosity?: CommandVerbosity; extraAgentEnvVars?: string[] }`       | How loudly runs report command output; see [configuring](reporting.md#configuring)  |
+| Field              | Type                                                                          | Description                                                                                                                                                                                                                                                                                                                                  |
+| ------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `build`            | `{ extraIgnorePatterns?: string[] }`                                          | Patterns added to the build's ignore set (package config only)                                                                                                                                                                                                                                                                               |
+| `checkCache`       | `{ enabled?: boolean; extraCommands?: string[]; excludeCommands?: string[] }` | Which commands the [check-result cache](check-cache.md#check-result-cache) may skip                                                                                                                                                                                                                                                          |
+| `workspaceScripts` | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the workspace registry (tier 2)                                                                                                                                                                                                                                                                               |
+| `rootScripts`      | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the root registry (tier 2)                                                                                                                                                                                                                                                                                    |
+| `devBin`           | `Record<string, string>`                                                      | Map binary names to source-repo replacement commands                                                                                                                                                                                                                                                                                         |
+| `output`           | `{ commandVerbosity?: CommandVerbosity; extraAgentEnvVars?: string[] }`       | How loudly runs report command output; see [configuring](reporting.md#configuring)                                                                                                                                                                                                                                                           |
+| `selfHostedRunner` | `{ exempt: string }`                                                          | Why a qualifying repo keeps CI off the self-hosted runners; stops [nmr's readyup kit](../README.md#conformance-checks) from recommending `CI_RUNS_ON` (root config only). The reason is structural: a circular dependency, a platform or capacity the runners lack, or network reach. A missing tool is installed by a workflow step instead |
 
 All fields are optional. [Script values](#script-values) describes `ScriptValue` and its step form, and both types are exported from `@williamthorsen/nmr/config`.
 
@@ -153,6 +177,8 @@ Neither is bound to a git hook. `prepush` is named for when a developer runs it,
 
 ### Check and quality
 
+`check` and `check:strict` start their lint step first and [run it in the background](#running-a-step-in-the-background), alongside typecheck, the format check, and the tests.
+
 Neither gate computes coverage: Instrumentation multiplies the wall time of the run that they exist to keep short. Coverage is [`test:coverage`](vitest.md#test-selections), run as a step of its own; a repo that wants it inside the gate [overrides](#configuration) `check:strict`.
 
 ### Lint

package/docs/upgrades.md

@@ -40,7 +40,7 @@ export default defineConfig({
 });
 ```
 
-`defineConfig` supplies nmr's shared upgrade policy, so a repo's config contains only what is specific to that repo. The policy is a seven-day quarantine on brand-new releases and the pair of settings that report a dependency pinned to an exact version: Locked dependencies are included, and the range searched is `minor`. Any setting that a repo's config declares wins over nmr's default. Passing `undefined` clears a default rather than falling back to it; that is how a config hands the quarantine policy back to `pnpm-workspace.yaml`'s `minimumReleaseAge`. `mode` is the exception: The upgrade tool has a default of its own for it, and clearing nmr's leaves the tool without a valid range to search. Name a mode instead.
+`defineConfig` supplies nmr's shared upgrade policy, so a repo's config contains only what is specific to that repo. The policy is a seven-day quarantine on brand-new releases and the pair of settings that report a dependency pinned to an exact version: Locked dependencies are included, and the range searched is `minor`. Any setting that a repo's config declares wins over nmr's default. Passing `undefined` clears a default rather than falling back to it; that is how a config hands the quarantine policy back to `pnpm-workspace.yaml`'s `minimumReleaseAge`. Clearing `mode` hands the range back to the upgrade tool's own default, which follows the range that each dependency declares.
 
 Everything the [taze configuration](https://github.com/antfu-collective/taze#config-file) accepts is accepted here, with five exceptions that the upgrade tool does not read from any config file at all: `concurrency`, `githubActions`, `ignoreOtherWorkspaces`, `nodeVersion`, and `requestTimeout`. The tool's CLI writes a default for each of them over whatever the config declares ([taze#317](https://github.com/antfu-collective/taze/issues/317)), so the command line is the only place they can be set. nmr's ReadyUp kit warns when a repo's config declares one, and [request timeout](#request-timeout) below shows how to set it instead.
 

package/docs/utilities.md

@@ -47,9 +47,21 @@ 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
+
+`nmr-fmt` passes Prettier's content-keyed cache (`--cache --cache-strategy content`), so a run reformats only the files whose content changed since a run that passed them. The cache files live in `node_modules/.cache/prettier/nmr-fmt/` at the repository root, one per directory from which `nmr-fmt` runs, because Prettier keys each entry by its path relative to that directory. A repository whose root does not contain a `node_modules` directory runs uncached rather than having one created.
+
+A cached entry is reused only while the Prettier version, the Node version, the resolved Prettier options, and the repository's lockfile are all unchanged. Prettier's own key covers the first three. It does not cover plugin code, so each cache file's name also contains a fingerprint of the root's lockfile, and a dependency change, a plugin upgrade included, starts a fresh cache. `nmr-fmt` deletes cache files with an outdated fingerprint, and it discards a cache file that is not valid JSON rather than letting Prettier fail on it. A failure to prepare the cache prints a warning and leaves the run uncached; it never fails the run.
+
+Pass `--no-cache`, or set `NMR_NO_CACHE=1`, to run uncached. `nmr --no-cache fmt:check` sets that variable, so it bypasses both nmr's [check cache](check-cache.md) and this one. Because the fingerprint makes a cache from an earlier lockfile harmless, CI can restore the whole `node_modules/.cache/prettier/nmr-fmt/` directory under a fallback key.
+
+```bash
+nmr-fmt --check --no-cache
+```
 
 ## `ensure-prepublish-hooks`