@williamthorsen/nmr 0.51.0 → 0.53.0

package/dist/esm/runner.d.ts

@@ -1,4 +1,5 @@
 import { type RunCommandOptions, type RunCommandResult } from './child-process.js';
+import { type StatedOutcome } from './stated-outcome.js';
 import type { Step } from './steps.js';
 /** What a step list needs to run. Each step's channels follow its kind, so the caller chooses none of them. */
 export type RunStepsOptions = Omit<RunCommandOptions, 'channels'>;
@@ -14,6 +15,8 @@ export interface RunStepsResult {
      * at least one to capture.
      */
     retainedOutput?: RetainedOutput;
+    /** The outcome that each foreground opaque step stated, absent unless a step that exited 0 stated one. */
+    statedOutcomes?: Map<Step, StatedOutcome>;
 }
 /**
  * Runs a step list in order and resolves once one fails or all have run, implementing the `&&` semantics that
@@ -33,6 +36,10 @@ export interface RunStepsResult {
  * Returns a bounded copy of what the list's own commands wrote, so that a caller can retain it. Only opaque
  * steps contribute: A structural step is another nmr process reporting for the subtree beneath it, and its
  * output is that subtree's to account for.
+ *
+ * Each foreground opaque step is handed a file of its own in `NMR_OUTCOME_FILE`, through which an nmr bin states its
+ * outcome. Every other step runs without the variable, as does a step whose value would have been inherited from an
+ * ancestor, so that a statement reaches only the list that handed out its file.
  */
 export declare function runSteps(steps: readonly Step[], cwd: string | undefined, options: RunStepsOptions): Promise<RunStepsResult>;
 /**

package/dist/esm/runner.js

@@ -1,10 +1,16 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
 import process from 'node:process';
+import { writeDebugNote } from "./check-cache.js";
 import { describeSignalExitCode, startSpawned, } from "./child-process.js";
 import { createOutputRecorder } from "./helpers/createOutputRecorder.js";
 import { isTerminal, resolveChannel, resolveInheritedChannel } from "./output-channel.js";
+import { omitOutcomeFile, OUTCOME_FILE_ENV_VAR, readStatedOutcome } from "./stated-outcome.js";
 export async function runSteps(steps, cwd, options) {
     const resolvedOptions = {
         ...options,
+        env: omitOutcomeFile(options.env ?? process.env),
         quiet: options.quiet === true,
         stdout: options.stdout ?? process.stdout,
         stderr: options.stderr ?? process.stderr,
@@ -15,6 +21,8 @@ export async function runSteps(steps, cwd, options) {
     const runningChildren = new Set();
     let receivedSignal;
     let foregroundExitCode = 0;
+    const statedOutcomes = new Map();
+    let outcomeDir;
     function forwardSignal(signal) {
         receivedSignal ??= signal;
         for (const child of runningChildren)
@@ -26,6 +34,24 @@ export async function runSteps(steps, cwd, options) {
         void started.result.finally(() => runningChildren.delete(started.child));
         return started;
     }
+    async function runForeground(step) {
+        if (step.kind !== 'opaque') {
+            return { result: await launch(step, resolvedOptions).result };
+        }
+        outcomeDir ??= await mkdtemp(path.join(os.tmpdir(), 'nmr-outcome-'));
+        const outcomeFile = path.join(outcomeDir, `${steps.indexOf(step)}.json`);
+        const env = { ...resolvedOptions.env, [OUTCOME_FILE_ENV_VAR]: outcomeFile };
+        const started = launch(step, { ...resolvedOptions, env });
+        const result = await started.result;
+        if (result.exitCode !== 0) {
+            return { result };
+        }
+        const parentPids = [process.pid, ...(started.child.pid === undefined ? [] : [started.child.pid])];
+        const statedOutcome = await readStatedOutcome(outcomeFile, parentPids, (reason) => {
+            writeDebugNote(`ignoring the outcome that a step stated: ${reason}`, resolvedOptions.env, resolvedOptions.stderr);
+        });
+        return { result, ...(statedOutcome !== undefined && { statedOutcome }) };
+    }
     function flushEndedBackgroundRuns() {
         for (const run of backgroundRuns) {
             if (run.result === undefined || run.isFlushed)
@@ -48,8 +74,10 @@ export async function runSteps(steps, cwd, options) {
                 backgroundRuns.push(startBackgroundRun(step, resolvedOptions, launch));
                 continue;
             }
-            const result = await launch(step, resolvedOptions).result;
+            const { result, statedOutcome } = await runForeground(step);
             flushEndedBackgroundRuns();
+            if (statedOutcome !== undefined)
+                statedOutcomes.set(step, statedOutcome);
             if (step.kind === 'opaque') {
                 if (result.stderr === undefined || result.stdout === undefined) {
                     isCaptureWhole = false;
@@ -75,9 +103,15 @@ export async function runSteps(steps, cwd, options) {
     finally {
         process.off('SIGINT', forwardSignal);
         process.off('SIGTERM', forwardSignal);
+        if (outcomeDir !== undefined)
+            await rm(outcomeDir, { force: true, recursive: true });
     }
     const exitCode = selectExitCode(foregroundExitCode, receivedSignal, backgroundRuns);
-    return { exitCode, ...composeRetainedOutput(parts, isCaptureWhole) };
+    return {
+        exitCode,
+        ...composeRetainedOutput(parts, isCaptureWhole),
+        ...(statedOutcomes.size > 0 && { statedOutcomes }),
+    };
 }
 export async function runCommand(command, cwd, options) {
     return runSpawned({ args: [], file: command, input: 'inherit', shouldUseShell: true }, cwd, options);
@@ -113,7 +147,7 @@ function composeRetainedOutput(parts, isCaptureWhole) {
     };
 }
 function buildBackgroundEnv(options) {
-    const env = options.env ?? process.env;
+    const { env } = options;
     const shouldForceColor = isTerminal(options.stdout) && (env['NO_COLOR'] ?? '') === '' && env['FORCE_COLOR'] === undefined;
     return shouldForceColor ? { ...env, FORCE_COLOR: '1' } : env;
 }

package/dist/esm/stated-outcome.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Names the file in which an nmr bin states its own outcome to the nmr process that runs it. nmr sets it for each
+ * opaque step and removes it from every other process that it starts.
+ */
+export declare const OUTCOME_FILE_ENV_VAR = "NMR_OUTCOME_FILE";
+/**
+ * An outcome that a bin states about its own run, which a passing verdict reports in its detail slot.
+ *
+ * `build-unchanged` is a build-cache hit. Its `savedMs` is the emit time recorded for the current inputs, whatever
+ * its size, and is absent when none was recorded; whether a saving is worth naming belongs to rendering.
+ */
+export interface StatedOutcome {
+    kind: 'build-unchanged';
+    savedMs?: number;
+}
+/**
+ * Returns the environment without `NMR_OUTCOME_FILE`, for a process that is not the one to which the file was handed,
+ * so that it cannot state an outcome for the step that runs it.
+ */
+export declare function omitOutcomeFile(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Reads the outcome that a step stated in `filePath`, or `undefined` when it stated none. A record that cannot be
+ * read as a stated outcome is reported to `onRejection` and treated as none, so that a bin from another nmr version
+ * cannot break the verdict.
+ *
+ * A record is accepted only from a process whose parent is one of `parentPids`: the process that handed out the file,
+ * or the shell that it spawned for the step. A shell running a single command either replaces itself with it or runs
+ * it as its child, so the step's own bin passes either way. Where the shell replaces itself, a process that the
+ * command starts passes too; a process two levels below the command does not.
+ */
+export declare function readStatedOutcome(filePath: string, parentPids: readonly number[], onRejection: (reason: string) => void): Promise<StatedOutcome | undefined>;
+/**
+ * Writes the outcome into the file that `NMR_OUTCOME_FILE` names, with this process's parent as the one that it is
+ * stated to, and does nothing when the variable is unset. The statement is advisory: A write that fails leaves the
+ * verdict reading as it would without one.
+ */
+export declare function writeStatedOutcome(env: NodeJS.ProcessEnv, outcome: StatedOutcome): Promise<void>;

package/dist/esm/stated-outcome.js

@@ -0,0 +1,60 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import process from 'node:process';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { isObject } from "./helpers/type-guards.js";
+export const OUTCOME_FILE_ENV_VAR = 'NMR_OUTCOME_FILE';
+export function omitOutcomeFile(env) {
+    return Object.fromEntries(Object.entries(env).filter(([name]) => name !== OUTCOME_FILE_ENV_VAR));
+}
+export async function readStatedOutcome(filePath, parentPids, onRejection) {
+    let text;
+    try {
+        text = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return undefined;
+        }
+        onRejection(`could not read ${filePath}: ${describeError(error)}`);
+        return undefined;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        onRejection(`${filePath} does not contain JSON`);
+        return undefined;
+    }
+    if (!isStatedOutcome(value)) {
+        onRejection(`${filePath} does not contain a stated outcome that this nmr knows`);
+        return undefined;
+    }
+    if (!parentPids.includes(value.parentPid)) {
+        onRejection(`${filePath} was written by a process whose parent is not one of ${parentPids.join(', ')}`);
+        return undefined;
+    }
+    return value.savedMs === undefined ? { kind: value.kind } : { kind: value.kind, savedMs: value.savedMs };
+}
+export async function writeStatedOutcome(env, outcome) {
+    const filePath = env[OUTCOME_FILE_ENV_VAR];
+    if (filePath === undefined || filePath === '') {
+        return;
+    }
+    try {
+        const record = { ...outcome, parentPid: process.ppid };
+        await writeFile(filePath, JSON.stringify(record));
+    }
+    catch {
+    }
+}
+function isMissingFileError(error) {
+    return isObject(error) && error['code'] === 'ENOENT';
+}
+function isStatedOutcome(value) {
+    if (!isObject(value) || value['kind'] !== 'build-unchanged' || !Number.isSafeInteger(value['parentPid'])) {
+        return false;
+    }
+    const savedMs = value['savedMs'];
+    return savedMs === undefined || (typeof savedMs === 'number' && Number.isFinite(savedMs) && savedMs >= 0);
+}

package/dist/esm/taze.d.ts

@@ -3,8 +3,8 @@ import type { CheckOptions } from 'taze';
  * A taze configuration.
  *
  * Every property admits `undefined` explicitly, unlike `Partial<CheckOptions>`, which rejects it under
- * `exactOptionalPropertyTypes`. Passing `undefined` is how a consumer clears `maturityPeriod`, so the type
- * has to allow it.
+ * `exactOptionalPropertyTypes`. Passing `undefined` is how a consumer clears `mode`, so the type has to allow
+ * it.
  */
 export type TazeConfig = {
     [K in keyof CheckOptions]?: CheckOptions[K] | undefined;
@@ -12,7 +12,7 @@ export type TazeConfig = {
     /**
      * 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`.
+     * Every other dependency keeps `maturityPeriod` or, while that is unset, pnpm's `minimumReleaseAge`.
      */
     packageMaturityPeriod?: Record<string, number> | undefined;
 };
@@ -20,10 +20,12 @@ 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`, 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.
+ * default and hands the setting back to taze. 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 policy leaves `maturityPeriod` unset, because taze inherits pnpm's `minimumReleaseAge` only while it is
+ * unset. A repo that sets it replaces pnpm's period.
  *
  * 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

@@ -1,6 +1,5 @@
 const SHARED_POLICY = {
     includeLocked: true,
-    maturityPeriod: 7,
     mode: 'minor',
 };
 export function defineConfig(config) {

package/dist/esm/verdict.d.ts

@@ -2,6 +2,7 @@ import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { ReplayLine } from './check-cache-entries.js';
 import type { ReportFormat } from './report-format.js';
+import type { StatedOutcome } from './stated-outcome.js';
 /**
  * The ceiling to which a rendered verdict, its newline included, is held.
  *
@@ -46,6 +47,7 @@ export type VerdictOutcome = {
 } & ({
     outcome: 'passed';
     durationMs: number;
+    stated?: StatedOutcome;
 } | {
     outcome: 'failed';
     durationMs: number;

package/dist/esm/verdict.js

@@ -5,7 +5,7 @@ import { formatDuration, formatSaving } from "./helpers/duration.js";
 export const VERDICT_LINE_LIMIT_BYTES = 512;
 export function renderVerdict(verdict, style) {
     const { marker, phrase } = describeOutcome(verdict, style);
-    const detail = flattenDetail(verdict.detail ?? renderReplay(verdict) ?? '');
+    const detail = flattenDetail(verdict.detail ?? renderReplay(verdict) ?? renderStated(verdict) ?? '');
     const detailClause = detail === '' ? '' : ` — ${detail}`;
     return clampToBytes(`${marker} ${verdict.scope}: ${verdict.command}: ${phrase}${detailClause}`, LINE_BUDGET_BYTES);
 }
@@ -23,7 +23,7 @@ const MIN_CUT_BYTES = Buffer.byteLength(TRUNCATION_MARK);
 const REPLAY_MARKER = 'replayed:';
 function describeOutcome(verdict, style) {
     const statuses = STATUS_GLYPHS[style];
-    const onHost = verdict.host === undefined ? '' : ` on ${verdict.host}`;
+    const onHost = verdict.host === undefined ? '' : ` on ${formatHost(verdict.host, style)}`;
     switch (verdict.outcome) {
         case 'passed':
             return { marker: statuses.passed.text, phrase: `passed${onHost} in ${formatDuration(verdict.durationMs)}` };
@@ -35,9 +35,10 @@ function describeOutcome(verdict, style) {
         case 'recalled': {
             const saving = formatSaving(verdict.savedMs);
             const savingClause = saving === undefined ? '' : `, ${saving}`;
+            const source = verdict.host === undefined ? 'this tree' : formatHost(verdict.host, style);
             return {
                 marker: statuses.skipped.text,
-                phrase: `passed ${formatDuration(verdict.ageMs)} ago on ${verdict.host ?? 'this tree'}${savingClause}`,
+                phrase: `passed ${formatDuration(verdict.ageMs)} ago on ${source}${savingClause}`,
             };
         }
         case 'no-op':
@@ -73,6 +74,13 @@ function renderReplay(verdict) {
     const lines = verdict.replay.map((line) => `${line.scope}: ${line.command}: ${line.excerpt}`);
     return `${REPLAY_MARKER} ${lines.join('; ')}`;
 }
+function renderStated(verdict) {
+    if (verdict.outcome !== 'passed' || verdict.stated === undefined) {
+        return undefined;
+    }
+    const saving = formatSaving(verdict.stated.savedMs ?? 0);
+    return saving === undefined ? 'build skipped as unchanged' : `build skipped as unchanged, ${saving}`;
+}
 function flattenDetail(detail) {
     return detail.replaceAll(/[\r\n]+/gu, ' ').trim();
 }
@@ -87,6 +95,10 @@ function findCutTarget(sizesBytes, longestSizeBytes, overrunBytes) {
 function isWithinBudget(renderedLine) {
     return Buffer.byteLength(renderedLine) <= LINE_BUDGET_BYTES;
 }
+function formatHost(host, style) {
+    const glyph = NMR_GLYPHS[style].host.text;
+    return glyph === '' ? host : `${glyph} ${host}`;
+}
 function readAttribution(verdict) {
     if (verdict.outcome !== 'recalled' || verdict.replay === undefined) {
         return [];

package/docs/check-cache.md

@@ -10,7 +10,7 @@ The cache is a working-tree cache, not a build cache: It answers "has this exact
 
 ## What is cached
 
-Cacheable by default: `check`, `check:strict`, `ci`, `fix:check`, `fmt:check`, `lint:check`, `lint:strict`, `test`, `test:coverage`, `test:tool`, `test:unit`, `typecheck`, and the `root:` variants `root:check`, `root:lint:check`, `root:lint:strict`, `root:test`, `root:test:tool`, `root:test:unit`, and `root:typecheck`.
+Cacheable by default: `check`, `check:strict`, `ci`, `fix:check`, `fmt:check`, `lint:check`, `lint:strict`, `lint:workflows`, `test`, `test:coverage`, `test:tool`, `test:unit`, `typecheck`, and the `root:` variants `root:check`, `root:lint:check`, `root:lint:strict`, `root:test`, `root:test:tool`, `root:test:unit`, and `root:typecheck`.
 
 Everything else runs every time:
 

package/docs/delegate.md

@@ -5,7 +5,7 @@ nmr runs a command on another machine over SSH, against the working tree on this
 ```console
 $ nmr --delegate-to imac2 ci
 # ... the host's own output and verdicts ...
-✅ my-repo: ci: passed on imac2 in 1m 48s
+✅ my-repo: ci: passed on 📡 imac2 in 1m 48s
 ```
 
 A machine that runs several worktrees' checks at once runs out of memory, and the [machine lock](machine-lock.md) protects it by making the checks wait for one another. Delegation moves a check to a machine that has the room for it instead. Which hosts a machine can reach is a fact about the machine, so a user config on the machine, not the repo, names them and turns delegation on.
@@ -61,7 +61,7 @@ With several hosts, nmr asks every host at once, with one `ssh` call each, wheth
 
 ```console
 $ NMR_DELEGATE=imac2,imac3 nmr ci
-✅ my-repo: ci: passed on imac3 in 1m 52s
+✅ my-repo: ci: passed on 📡 imac3 in 1m 52s
 ```
 
 - **A single host is not asked.** The delegation goes to it directly.
@@ -98,7 +98,7 @@ $ nmr --delegate-to imac2 ci
 
 nmr records the working tree as it is on disk as a commit: tracked changes, staged or not, and untracked files that git does not ignore. This is the tree that a local run checks. The commit is built in a temporary index, so the repository's index, refs, and stash do not change.
 
-nmr pushes the commit to a checkout on the host under `~/.cache/nmr/delegate/`, without running the repository's `pre-push` hook, then runs `pnpm install --frozen-lockfile` and the command from the directory that corresponds to the local one, with nmr's own flags as they were given. The host keeps one checkout for each repository on each machine that delegates to it, so concurrent delegations from different worktrees do not share one, and `node_modules` and build output persist between runs. nmr does not remove these checkouts.
+nmr pushes the commit to a checkout on the host under `~/.cache/nmr/delegate/`, without running the repository's `pre-push` hook, then runs `pnpm install --frozen-lockfile` and the command from the directory that corresponds to the local one, with nmr's own flags as they were given. The host keeps one checkout for each repository on each machine that delegates to it, so concurrent delegations from different worktrees do not share one, and `node_modules` and build output persist between runs. When the workspace packages' `bin` entries differ from those of the checkout's last successful install, nmr first removes pnpm's workspace state, so that the install links the new bins, which an unchanged lockfile would otherwise let pnpm skip; that install reruns the workspace's `prepare` scripts. nmr does not remove these checkouts.
 
 - **Ignored files stay here.** A command that needs a gitignored file, such as a local `.env`, does not find it on the host.
 - **A repository with submodules cannot be delegated**, nor can a tree containing a nested repository, because the snapshot does not include their content. A delegation flag refuses such a tree; under `NMR_DELEGATE` or the user config, the command runs here, and nmr prints one line saying why.
@@ -123,7 +123,7 @@ The host's nmr prints its output and verdicts, and nmr here adds one verdict for
 A failure of the delegation itself, rather than of the command, exits 255, the status with which `ssh` reports its own failures, and names the step that failed, after what that step printed:
 
 ```console
-❌ my-repo: ci: failed on imac2 in 10.0s (exit 255) — could not prepare imac2
+❌ my-repo: ci: failed on 📡 imac2 in 10.0s (exit 255) — could not prepare imac2
 ```
 
 The steps are `prepare`, which reaches the host and creates the checkout, `push`, `check out`, and `install`. A connection lost while the command runs is reported as `lost connection to <host>`.

package/docs/reporting.md

@@ -6,6 +6,8 @@ The verdict line and its four outcomes are shown in the [README](../README.md#wh
 
 A recalled pass also includes an excerpt of the run that it recalls, if that run left one; see [Replaying a skipped run's output](check-cache.md#replaying-a-skipped-runs-output).
 
+A pass also includes what the command stated about its own run, if the command is an nmr bin that states one, such as `nmr-compile` on a build-cache hit: `PASS nmr-core: compile: passed in 0.3s — build skipped as unchanged, saved ~2.1s`. The line names the saving under the same rule as a recalled pass. Because the bin states it through [`NMR_OUTCOME_FILE`](#reserved-environment-variables) rather than through its output, a quiet run reports it too.
+
 The scope is the directory to which the command's registry belongs: a package's own directory, or the monorepo root. Durations and ages truncate and show at most two units, so a check that passed 119.9 seconds ago reports `1m 59s ago` and never `2m ago`.
 
 Verdicts nest. A composite reports, and so does every command into which it expands; a `:pre` or `:post` hook reports nothing of its own, since the command that it wraps already reports for the chain, though a hook that delegates to a named command reports under that name. A `-R` or `-F` invocation reports nothing either; every scope to which it fans out reports instead. A cold repo-wide `nmr ci` in this package's own monorepo uses 26 verdict lines to report a run that prints roughly 250.
@@ -38,7 +40,7 @@ Every object contains `command`, `scope`, and `outcome`, and then the fields tha
 
 | `outcome`  | Also contains                                                                                                           |
 | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `passed`   | `durationMs`                                                                                                            |
+| `passed`   | `durationMs`, and `stated` when the command stated its own outcome, such as `{"kind":"build-unchanged","savedMs":2100}` |
 | `failed`   | `durationMs`, `exitCode`                                                                                                |
 | `recalled` | `ageMs`, `savedMs`, and `replay` when the skip has excerpts to [replay](check-cache.md#replaying-a-skipped-runs-output) |
 | `no-op`    | `reason`, one of `empty-override`, `empty-workspace`, or `noop-override`                                                |
@@ -72,6 +74,8 @@ Because the format is nmr's own reporting, and nmr does not tell the commands th
 
 `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.
 
+`NMR_OUTCOME_FILE` is nmr's own as well. nmr sets it for each command that it runs through the shell, naming a file of that step's own, in which an nmr bin states its outcome; nmr reads the file once the step exits 0 and removes it afterwards. nmr accepts the statement only from a command whose own script is a single shell command, and only from a process that names as its parent, in the record, nmr or the shell that nmr spawned for the step. A bin therefore cannot speak for a chain or for a hook around it. Whether a process that the step's command starts can state one depends on the shell: Where the shell runs the command as its child, as Debian's and Ubuntu's /bin/sh does, only the command itself can state an outcome; where the shell replaces itself with the command, as bash does, a process that the command starts can state one too, so a wrapper script that runs a bin as its child speaks for its step. `nmr-vitest` withholds the variable from the suite that it runs, so that a test exercising a bin cannot speak for the `test` step. nmr also removes the variable from every other process that it starts. Do not set it: nmr replaces an inherited value, and ignores a record that it cannot read.
+
 ### 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

@@ -182,7 +182,7 @@ 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.
+`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. At the root, both then run [`lint:workflows`](#workflow-lint) before typecheck, and `root:check` runs it after `root:lint:check`.
 
 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`.
 
@@ -194,6 +194,14 @@ Requires `eslint` >= 10 and, for `lint:strict`, `@williamthorsen/strict-lint` >=
 
 The run never enters a package, so per-package `lint:pre` and `lint:post` hooks do not fire from the root. They still run from inside the package and under `nmr -F <package> lint`.
 
+### Workflow lint
+
+`lint:workflows`, a root command, lints the GitHub Actions workflows under `.github/workflows/` with [actionlint](https://github.com/rhysd/actionlint), including its shellcheck pass over every `run:` block, and fails on any finding. A repo without `.github/workflows/` passes. The command runs `nmr-actionlint`, which forwards trailing arguments to actionlint, so `nmr lint:workflows .github/workflows/ci.yaml` lints that file alone; inside `check`, `check:strict`, and `root:check`, the step declines them.
+
+The result does not depend on what the machine has installed. nmr pins actionlint 1.7.12 and shellcheck 0.11.0, downloads each from its upstream GitHub release on first use, verifies it against the SHA-256 recorded in nmr, and caches it under `node_modules/.cache/nmr-tools/` at the monorepo root. The first run therefore needs access to `github.com`, and a failed download or a checksum mismatch fails the command. The pyflakes integration is off. The pins move only with a release of nmr.
+
+The supported platforms are macOS and Linux on x64 and arm64; on any other, the command fails and names the platform. actionlint reads its own configuration from `.github/actionlint.yaml`, through which a repo can ignore a finding.
+
 ### Root-only
 
 The `root:`-prefixed commands operate on root-level code only (not workspace packages).

package/docs/upgrades.md

@@ -40,11 +40,13 @@ 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`. Clearing `mode` hands the range back to the upgrade tool's own default, which follows the range that each dependency declares.
+`defineConfig` supplies nmr's shared upgrade policy, so a repo's config contains only what is specific to that repo. The policy is 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. Clearing `mode` hands the range back to the upgrade tool's own default, which follows the range that each dependency declares.
+
+The policy does not set `maturityPeriod`, so the quarantine on brand-new releases is pnpm's: The upgrade tool applies the `minimumReleaseAge` of `pnpm-workspace.yaml`, or pnpm 11's default when the file does not set one (under pnpm 10 or earlier, a workspace that does not set it is not quarantined), and the packages that its `minimumReleaseAgeExclude` lists skip the quarantine. A `maturityPeriod` in a repo's config replaces pnpm's period.
 
 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.
 
-> **Note:** Only this file activates nmr's upgrade policy. A repo without one gets neither the release quarantine nor the settings that report a dependency pinned to an exact version, and `nmr upgrade` reports nothing in a repo using pnpm's `savePrefix: ''`. nmr's ReadyUp kit warns when the file is missing.
+> **Note:** Only this file activates nmr's upgrade policy. A repo without one does not get the settings that report a dependency pinned to an exact version, and `nmr upgrade` reports nothing in a repo using pnpm's `savePrefix: ''`. nmr's ReadyUp kit warns when the file is missing.
 
 Two consequences of the `minor` range mode declared by the policy:
 
@@ -53,13 +55,13 @@ Two consequences of the `minor` range mode declared by the policy:
 
 ### 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.
+`packageMaturityPeriod` gives the packages that match a pattern a quarantine of their own, in days. Every other dependency keeps `maturityPeriod` or, while that is unset, pnpm's `minimumReleaseAge`. 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.
+  // Propose first-party releases after one day, and third-party ones after pnpm's `minimumReleaseAge`.
   packageMaturityPeriod: {
     '@williamthorsen/*': 1,
     readyup: 1,

package/docs/utilities.md

@@ -1,10 +1,18 @@
 # Standalone utilities
 
-The binaries behind nmr's default `clean`, `compile`, `fmt`, and package `test` commands, and a check for the `prepublishOnly` hooks of publishable packages.
+The binaries behind nmr's default `clean`, `compile`, `fmt`, `lint:workflows`, and package `test` commands, and a check for the `prepublishOnly` hooks of publishable packages.
+
+## `nmr-actionlint`
+
+Lint the monorepo's GitHub Actions workflows with pinned actionlint and shellcheck binaries, forwarding any arguments to actionlint. This is the default root `lint:workflows` script; [Workflow lint](scripts.md#workflow-lint) covers the pins, the download, and the supported platforms.
+
+```bash
+nmr-actionlint
+```
 
 ## `nmr-clean`
 
-Remove a package's build output (`dist`) and its `nmr-compile` cache entry, so that the next build cannot skip on leftover state. Run from a package directory, it cleans that package; run from the monorepo root, it sweeps every workspace package in a single pass, running each package's resolved `clean`, so a package that overrides `clean`, in `.config/nmr.config.ts` or in its own `package.json`, gets its own command rather than the sweep. Removal is idempotent: Cleaning an unbuilt package is a silent no-op. This is the default `clean` script at both levels.
+Remove a package's build output (`dist`) and its `nmr-compile` cache entries, the key and the recorded emit duration, so that the next build cannot skip on leftover state. Run from a package directory, it cleans that package; run from the monorepo root, it sweeps every workspace package in a single pass, running each package's resolved `clean`, so a package that overrides `clean`, in `.config/nmr.config.ts` or in its own `package.json`, gets its own command rather than the sweep. Removal is idempotent: Cleaning an unbuilt package is a silent no-op. This is the default `clean` script at both levels.
 
 ```bash
 nmr-clean
@@ -24,6 +32,8 @@ Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler
 
 **What busts the cache.** The key folds each input's content and path, the emit options, the resolved TypeScript version, and a fingerprint of the nmr running the build -- its own build digest in a workspace checkout, its package version otherwise. Upgrading nmr in a consuming repo therefore rebuilds every package that nmr compiles, and an edit to nmr's own build sources rebuilds each sibling once nmr itself has been rebuilt. A build of nmr's own package folds the version rather than the digest, which is the cache entry that this build is about to write.
 
+**What a skip reports.** Each build records how long its emit took, in a second entry beside the key (`.duration.json`), held to the key under which it was recorded. A skip names that time as the saving, `No changes detected. Skipping build, saved ~2.1s.`, when the recorded emit took at least a second and was recorded for the current inputs; otherwise the line ends at `Skipping build.` The time covers compiling and publishing the output, the work that a skip avoids, and not the hashing that a skip also does. The duration is a separate entry, so it never changes the key. Run through nmr, a skip also appears on the compile verdict line, `passed in 0.3s — build skipped as unchanged, saved ~2.1s`, which a quiet run still prints; see [what nmr reports](reporting.md#what-nmr-reports).
+
 `typescript` is an optional peer dependency (`>=5.7.0 <7`), needed only by `nmr-compile`; the consuming repo provides it, and `nmr-compile` run without it fails with an error naming the peer and the version that it requires. The floor is what `rewriteRelativeImportExtensions` requires; the ceiling exists because TypeScript 7 does not include a compiler API: Its root export is a version constant, so `nmr-compile` cannot run on it. Relative imports in source must use explicit `.ts` or `.tsx` extensions for them to be rewritten.
 
 ```bash
@@ -41,13 +51,14 @@ A repo's own copy must be Prettier 3.0.0 or later. The design requires `--ignore
 ```bash
 nmr-fmt --check
 nmr-fmt --write packages/nmr
+nmr-fmt --check -- -lead.js
 ```
 
 ### File selection
 
 `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 for which git lists no 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. Every argument after `--` is a pathspec, even one that starts with `-`, so an unrecognized option fails the run only before `--`. 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. 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -58,6 +58,7 @@
   "bin": {
     "ensure-prepublish-hooks": "bin/ensure-prepublish-hooks.js",
     "nmr": "bin/nmr.js",
+    "nmr-actionlint": "bin/nmr-actionlint.js",
     "nmr-clean": "bin/nmr-clean.js",
     "nmr-compile": "bin/nmr-compile.js",
     "nmr-fmt": "bin/nmr-fmt.js",
@@ -78,9 +79,9 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.13.6",
-    "@williamthorsen/toolbelt.errors": "0.8.4",
-    "@williamthorsen/toolbelt.filesystem": "0.9.4",
+    "@williamthorsen/nmr-core": "0.14.0",
+    "@williamthorsen/toolbelt.errors": "0.9.0",
+    "@williamthorsen/toolbelt.filesystem": "0.10.0",
     "glob": "13.0.6",
     "prettier": "3.9.10",
     "prettier-plugin-sh": "0.20.2",
@@ -88,10 +89,10 @@
     "unconfig": "7.5.0"
   },
   "devDependencies": {
-    "@williamthorsen/toolbelt.testing": "0.7.0",
-    "@williamthorsen/toolbelt.vitest": "0.12.0",
+    "@williamthorsen/toolbelt.testing": "0.8.0",
+    "@williamthorsen/toolbelt.vitest": "0.13.0",
     "esbuild": "0.28.2",
-    "readyup": "0.43.0",
+    "readyup": "0.44.0",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
     "vite": "8.3.4",