@williamthorsen/nmr 2.0.3 → 2.1.0

package/dist/esm/check-cache/check-cache-record.js

@@ -4,13 +4,13 @@ import { isEnvSwitchOn } from "../env-switch.js";
 import { deriveExcerpt } from "../helpers/deriveExcerpt.js";
 import { composeTranscript } from "../helpers/transcript.js";
 import { RUN_IF_PRESENT_ENV_VAR, VERSION } from "../invocation.js";
+import { assembleReplay } from "./assembleReplay.js";
 import { isCacheableCommand, resolveTreeSnapshot, writeDebugNote, } from "./check-cache.js";
 import { findStaleBuildOutput, readBuildOutputState } from "./check-cache-build-output.js";
 import { readCheckCacheEntry, recordTranscript, writeCheckCacheEntry, } from "./check-cache-entries.js";
 import { CURRENT_RUNTIME } from "./check-cache-key.js";
 import { writePassManifestEntry } from "./pass-manifest.js";
 import { renderRecording, renderRefusal, resolveRecording } from "./recording.js";
-import { assembleReplay } from "./replay-assembly.js";
 export async function recordHostPass(options) {
     const { env, host, key, ref, retention, snapshot, stderr } = options;
     const recorded = await readCheckCacheEntry(ref);

package/dist/esm/check-cache/check-cache.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { realpathSync } from 'node:fs';
 import { hashWorkingTree, readHeadSha, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
 import { isEnvSwitchOn } from "../env-switch.js";
-import { isHookName } from "../helpers/hook-name.js";
+import { isHookName } from "../helpers/isHookName.js";
 export const GIT_TREE_READER = { hashWorkingTree, readHeadSha };
 export const DEBUG_ENV_VAR = 'NMR_DEBUG';
 export const DEFAULT_CACHEABLE_COMMANDS = [

package/dist/esm/commands/build.js

@@ -8,8 +8,8 @@ import { writeStatedOutcome } from "../stated-outcome.js";
 import { DEFAULT_OUTDIR, hasExpectedBuildOutput, readEmitDuration, resolveBuildCachePath, resolveEntryPoints, resolveToolchainFingerprint, writeEmitDuration, } from "./build-output.js";
 import { assertSupportedTypeScript, formatDiagnostics, getCompiler, loadCompiler } from "./compiler.js";
 import { discardScratchDirs, publishOutput, removeScratchDirs } from "./publish-output.js";
+import { resolveTsconfigChain } from "./resolveTsconfigChain.js";
 import { rewriteSpecifiers } from "./rewrite-specifiers.js";
-import { resolveTsconfigChain } from "./tsconfig-chain.js";
 const SOURCE_ROOT = 'src';
 export async function buildPackage(packageDir, options = {}) {
     await loadCompiler(options.loadTypeScript);

package/dist/esm/commands/fmt.js

@@ -10,8 +10,8 @@ import { NMR_FMT_BIN } from "../bins.js";
 import { NO_CACHE_ENV_VAR } from "../check-cache/check-cache.js";
 import { readEnvSwitch } from "../env-switch.js";
 import { prepareFmtCache } from "./fmt-cache.js";
-import { resolveFormatTargets } from "./format-targets.js";
 import { BROKEN_MANIFEST_FIX, findPackageManifest, resolveDeclaredCli, } from "./package-manifest.js";
+import { resolveFormatTargets } from "./resolveFormatTargets.js";
 import { resolveInheritedExitCode, spawnInherited } from "./spawn-inherited.js";
 const PRETTIER_PACKAGE = 'prettier';
 const DEFAULT_CONFIG_PATH = fileURLToPath(new URL(`../prettier-default.config${path.extname(fileURLToPath(import.meta.url))}`, import.meta.url));

package/dist/esm/commands/taze.js

@@ -4,11 +4,11 @@ import { fileURLToPath } from 'node:url';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { NMR_TAZE_BIN } from "../bins.js";
-import { loadPackageMaturityPeriod } from "./load-package-maturity-period.js";
+import { loadPackageMaturityPeriod } from "./loadPackageMaturityPeriod.js";
 import { checkNodePin as checkNodePinDefault } from "./node-pin.js";
+import { planTazePasses } from "./planTazePasses.js";
 import { resolveInheritedExitCode, spawnInherited } from "./spawn-inherited.js";
 import { isSilent, readFlag } from "./taze-args.js";
-import { planTazePasses } from "./taze-passes.js";
 const TAZE_CLI_SPECIFIER = 'taze/cli';
 const REQUEST_TIMEOUT_FLAG = '--request-timeout';
 const REQUEST_TIMEOUT_FLAGS = [REQUEST_TIMEOUT_FLAG, '--requestTimeout'];

package/dist/esm/config-validation.js

@@ -1,11 +1,11 @@
 import { isRecord, UserError } from '@williamthorsen/nmr-core';
-import { assertResolvableCheckCacheCommands } from "./check-cache/config-check-cache.js";
+import { assertResolvableCommandLists } from "./assertResolvableCommandLists.js";
 import { findUnexpressibleToken } from "./steps.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 export const CONFIG_TIERS = {
     root: {
         label: 'a monorepo-root config',
-        honoredKeys: ['checkCache', 'delegate', 'output', 'rootScripts', 'selfHostedRunner', 'workspaceScripts'],
+        honoredKeys: ['checkCache', 'delegate', 'fanOut', 'output', 'rootScripts', 'selfHostedRunner', 'workspaceScripts'],
         elsewhere: "the package's own config",
     },
     workspace: {
@@ -17,6 +17,7 @@ export const CONFIG_TIERS = {
 const RECOGNIZED_KEYS = [...CONFIG_TIERS.root.honoredKeys, ...CONFIG_TIERS.workspace.honoredKeys];
 const RECOGNIZED_BUILD_KEYS = ['extraIgnorePatterns'];
 const RECOGNIZED_CHECK_CACHE_KEYS = ['enabled', 'excludeCommands', 'extraCommands'];
+const RECOGNIZED_FAN_OUT_KEYS = ['extraSortedCommands'];
 const RECOGNIZED_OUTPUT_KEYS = ['commandVerbosity', 'extraAgentEnvVars'];
 const RECOGNIZED_SELF_HOSTED_RUNNER_KEYS = ['exempt'];
 const RECOGNIZED_STEP_KEYS = ['run', 'shouldDeclineArguments', 'shouldRunInBackground'];
@@ -43,6 +44,9 @@ export function validateConfig(value, configPath, baseDir) {
         config.checkCache = checkCache;
     if (value['delegate'] !== undefined)
         config.delegate = validateDelegateField(value['delegate'], configPath);
+    const fanOut = validateFanOutField(value, configPath);
+    if (fanOut)
+        config.fanOut = fanOut;
     const output = validateOutputField(value, configPath);
     if (output)
         config.output = output;
@@ -55,7 +59,7 @@ export function validateConfig(value, configPath, baseDir) {
     const selfHostedRunner = validateSelfHostedRunnerField(value, configPath);
     if (selfHostedRunner)
         config.selfHostedRunner = selfHostedRunner;
-    assertResolvableCheckCacheCommands(config, configPath, baseDir);
+    assertResolvableCommandLists(config, configPath, baseDir);
     return config;
 }
 function assertNoRetiredKeys(value, retiredKeys, configPath, prefix) {
@@ -166,6 +170,24 @@ function validateDelegateField(delegate, configPath) {
     throw new UserError(`Invalid nmr config at ${configPath}: \`delegate\` accepts only \`false\`, which keeps the repo's checks on the ` +
         'machine that has the tree. Hosts and `when` belong in the user config, `~/.config/nmr/config.ts`.');
 }
+function validateFanOutField(value, configPath) {
+    const fanOut = value['fanOut'];
+    if (fanOut === undefined) {
+        return undefined;
+    }
+    if (!isRecord(fanOut)) {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`fanOut\` must be an object`);
+    }
+    assertRecognizedKeys(fanOut, RECOGNIZED_FAN_OUT_KEYS, configPath, 'fanOut.');
+    const extraSortedCommands = fanOut['extraSortedCommands'];
+    if (extraSortedCommands === undefined) {
+        return {};
+    }
+    if (!isStringArray(extraSortedCommands)) {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`fanOut.extraSortedCommands\` must be a string[]`);
+    }
+    return { extraSortedCommands };
+}
 function validateOutputField(value, configPath) {
     const output = value['output'];
     if (output === undefined) {

package/dist/esm/config.js

@@ -3,8 +3,8 @@ import { UserError } from '@williamthorsen/nmr-core';
 import { CONFIG_TIERS, validateConfig } from "./config-validation.js";
 import { resolveConfigPath } from "./helpers/config-path.js";
 import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
-import { isHookName } from "./helpers/hook-name.js";
 import { importConfigDefault } from "./helpers/importConfigDefault.js";
+import { isHookName } from "./helpers/isHookName.js";
 import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
 import { describeScript } from "./resolver.js";
 import { readSelfReference, readStepListSelfReference } from "./steps.js";

package/dist/esm/crossing-diagnostics.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { STATUS_GLYPHS, UserError } from '@williamthorsen/nmr-core';
 import { resolveConfigPath } from "./helpers/config-path.js";
 import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
-import { isHookName } from "./helpers/hook-name.js";
+import { isHookName } from "./helpers/isHookName.js";
 import { resolvePackageJsonPath } from "./helpers/package-json.js";
 import { hasRunnableHook } from "./hooks.js";
 import { expandScript, findChainedSelfReference, readPackageJsonScripts, } from "./resolver.js";

package/dist/esm/defineConfig.d.ts

@@ -1,5 +1,5 @@
 import type { NmrConfig } from './types.js';
-export type { BuildConfig, CheckCacheConfig, CommandVerbosity, NmrConfig, OutputConfig, ScriptValue, SelfHostedRunnerConfig, StepSpec, } from './types.js';
+export type { BuildConfig, CheckCacheConfig, CommandVerbosity, FanOutConfig, NmrConfig, OutputConfig, ScriptValue, SelfHostedRunnerConfig, StepSpec, } from './types.js';
 /**
  * Returns `config` unchanged, typing a configuration file's default export as `NmrConfig`.
  *

package/dist/esm/delegation/delegate-host.js

@@ -9,10 +9,10 @@ import { createBoundedBuffer } from "../helpers/createBoundedBuffer.js";
 import { USAGE_EXIT_CODE, } from "../invocation.js";
 import { isDelegationFlag } from "../invocation-args.js";
 import { reportVerdict } from "../presentation.js";
-import { resolveDelegationTarget } from "./delegation-target.js";
+import { createSnapshot } from "./createSnapshot.js";
 import { chooseHost, probeHost } from "./remote-probe.js";
 import { DELEGATE_ENV_VAR, DELEGATE_FLAG, DELEGATE_TO_FLAG, DELEGATION_FAILURE_EXIT_CODE, deriveCheckoutPath, formatMisplacedDelegationWarning, readLastLine, runRemotely, } from "./remote-run.js";
-import { createSnapshot } from "./remote-snapshot.js";
+import { resolveDelegationTarget } from "./resolveDelegationTarget.js";
 import { formatDisplayPath, loadUserConfig } from "./user-config.js";
 export async function resolveExecutionTarget(invocation) {
     const { command, context, env, parsedArgs, stderr, styles } = invocation;

package/dist/esm/delegation/remote-probe.js

@@ -2,8 +2,8 @@ import path from 'node:path';
 import { isRecord } from '@williamthorsen/nmr-core';
 import { quoteForShell } from "../helpers/quoteForShell.js";
 import { LOCK_DIR_ENV_VAR, LOCK_FILE, STALE_AFTER_MS } from "../machine-lock.js";
+import { probeHostLocks } from "./probeHostLocks.js";
 import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
-import { probeHostLocks } from "./remote-probe-host.js";
 import { DELEGATION_FAILURE_EXIT_CODE, readLastLine, runSsh } from "./remote-run.js";
 export function chooseHost(options) {
     const { hosts, onSettled, probe } = options;

package/dist/esm/delegation/user-config.d.ts

@@ -1,6 +1,6 @@
 import type { HostList } from './remote-run.js';
 /** The values that `delegate.when` accepts, each naming the runs that delegate without being asked. */
-export declare const DELEGATE_WHEN_VALUES: readonly ["agent", "always"];
+declare const DELEGATE_WHEN_VALUES: readonly ["agent", "always"];
 export type DelegateWhen = (typeof DELEGATE_WHEN_VALUES)[number];
 /**
  * Renders a path for a message, with `~` standing for the home directory that `env` names when the path lies under
@@ -32,3 +32,4 @@ export interface UserDelegateConfig {
     hosts: HostList;
     when?: DelegateWhen;
 }
+export {};

package/dist/esm/delegation/user-config.js

@@ -4,7 +4,7 @@ import { isRecord, UserError } from '@williamthorsen/nmr-core';
 import { assertRecognizedKeys } from "../config-validation.js";
 import { importConfigDefault } from "../helpers/importConfigDefault.js";
 import { resolveXdgBaseDir } from "../helpers/resolveXdgBaseDir.js";
-export const DELEGATE_WHEN_VALUES = ['agent', 'always'];
+const DELEGATE_WHEN_VALUES = ['agent', 'always'];
 export function formatDisplayPath(filePath, env) {
     const home = env['HOME'];
     if (home === undefined || !path.isAbsolute(home)) {

package/dist/esm/{help.js → describeHelp.js}

@@ -1,5 +1,5 @@
 import { DELEGATE_ENV_VAR } from "./delegation/remote-run.js";
-import { isHookName } from "./helpers/hook-name.js";
+import { isHookName } from "./helpers/isHookName.js";
 import { OUTPUT_STYLE_ENV_VAR } from "./output-style.js";
 import { buildRootRegistry, buildWorkspaceRegistry, describeScript, isSelfReferential, readPackageJsonScripts, } from "./resolver.js";
 const LIFECYCLE_SCRIPT_NAMES = new Set([

package/dist/esm/fan-out.d.ts

@@ -5,6 +5,7 @@ import { type RunCliResult } from './invocation.js';
 import type { ParsedArgs } from './nmr-flags.js';
 import type { RunSteps, RunStepsOptions } from './runner.js';
 import type { Step } from './steps.js';
+import type { NmrConfig } from './types.js';
 /**
  * Composes the delegation that an `-F` or `-R` calls for, or `undefined` when the invocation runs here.
  *
@@ -15,10 +16,16 @@ import type { Step } from './steps.js';
  *
  * A `--log` fan-out surveys the scopes selected, so a scope with nothing to show is a gap in the survey rather
  * than a failure of it, however that scope was selected.
+ *
+ * pnpm runs the selected packages in topological order unless told otherwise, which holds each package's run until
+ * its workspace dependencies have finished theirs. Only a command that reads what its dependencies' runs produce
+ * needs that, so the order is kept for `build` and for the commands in `fanOut.extraSortedCommands`, and every
+ * other fan-out runs with `--no-sort`.
  */
 export declare function composeDelegation(options: {
     childEnv: NodeJS.ProcessEnv;
     command: string;
+    config: NmrConfig;
     parsedArgs: ParsedArgs;
 }): {
     env: NodeJS.ProcessEnv;

package/dist/esm/fan-out.js

@@ -6,8 +6,9 @@ import { RUN_IF_PRESENT_ENV_VAR } from "./invocation.js";
 import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "./resolver.js";
 import { readWorkspacePackageNames, resolveWorkspace } from "./workspace.js";
 const RECURSIVE_REJECTION = '-R/--recursive did not match any workspace:';
+const DEFAULT_SORTED_COMMANDS = new Set(['build']);
 export function composeDelegation(options) {
-    const { childEnv, command, parsedArgs } = options;
+    const { childEnv, command, config, parsedArgs } = options;
     let scope;
     let shouldRunIfPresent = parsedArgs.shouldPrintLog;
     if (parsedArgs.filter) {
@@ -20,12 +21,13 @@ export function composeDelegation(options) {
     if (scope === undefined) {
         return undefined;
     }
+    const sortFlags = isSortedCommand(command, config) ? [] : ['--no-sort'];
     const flags = parsedArgs.shouldPrintLog ? ['--log'] : [];
     return {
         env: shouldRunIfPresent ? { ...childEnv, [RUN_IF_PRESENT_ENV_VAR]: '1' } : childEnv,
         step: {
             kind: 'structural',
-            argv: ['pnpm', ...scope, 'exec', 'nmr', ...flags, command, ...parsedArgs.passthrough],
+            argv: ['pnpm', ...scope, ...sortFlags, 'exec', 'nmr', ...flags, command, ...parsedArgs.passthrough],
         },
     };
 }
@@ -136,6 +138,9 @@ function formatEmptyFilterError(pattern, names) {
 function formatFilterRejection(pattern) {
     return `-F/--filter did not match any workspace: \`${pattern}\`.`;
 }
+function isSortedCommand(command, config) {
+    return DEFAULT_SORTED_COMMANDS.has(command) || (config.fanOut?.extraSortedCommands ?? []).includes(command);
+}
 function suggestWorkspaceNames(pattern, names) {
     if (names.length === 0) {
         return '';

package/dist/esm/invocation.d.ts

@@ -2,7 +2,7 @@ import type { Writable } from 'node:stream';
 import { type StreamStyles } from '@williamthorsen/nmr-core';
 import type { TreeReader, TreeSnapshot } from './check-cache/check-cache.js';
 import type { ResolvedContext } from './context.js';
-import type { DelegationTarget } from './delegation/delegation-target.js';
+import type { DelegationTarget } from './delegation/resolveDelegationTarget.js';
 import type { ReadFilterSelection } from './helpers/filter-selection.js';
 import type { ParsedArgs } from './nmr-flags.js';
 import type { ReportFormat } from './report-format.js';

package/dist/esm/machine-lock.d.ts

@@ -1,7 +1,5 @@
 import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
-/** How often a holder refreshes the lock file's mtime. */
-export declare const HEARTBEAT_INTERVAL_MS = 10000;
 /**
  * The commands that take the machine lock: the ones whose memory peak makes two concurrent runs slower than two in
  * sequence. `test:watch` is absent because it runs until it is stopped, and holding the lock would block every other
@@ -16,8 +14,6 @@ export declare const LOCK_FILE = "heavy.lock";
 export declare const LOCK_TOKEN_ENV_VAR = "NMR_MACHINE_LOCK_TOKEN";
 /** Set to `1` to run without the lock, for the whole chain. */
 export declare const NO_LOCK_ENV_VAR = "NMR_NO_LOCK";
-/** How often a waiter checks the lock again. */
-export declare const POLL_INTERVAL_MS = 1000;
 /**
  * Age at which an unrefreshed lock file is abandoned. It covers a holder whose pid was reused by another process,
  * and a file left half-written, neither of which a liveness check detects.

package/dist/esm/machine-lock.js

@@ -8,7 +8,7 @@ import { isRecord, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
 import { isEnvSwitchOn } from "./env-switch.js";
 const RECLAIM_GUARD = 'heavy.lock.reclaim';
 const RECLAIM_GUARD_STALE_AFTER_MS = 10_000;
-export const HEARTBEAT_INTERVAL_MS = 10_000;
+const HEARTBEAT_INTERVAL_MS = 10_000;
 export const HEAVY_COMMANDS = new Set([
     'check',
     'check:strict',
@@ -28,7 +28,7 @@ export const LOCK_DIR_ENV_VAR = 'NMR_LOCK_DIR';
 export const LOCK_FILE = 'heavy.lock';
 export const LOCK_TOKEN_ENV_VAR = 'NMR_MACHINE_LOCK_TOKEN';
 export const NO_LOCK_ENV_VAR = 'NMR_NO_LOCK';
-export const POLL_INTERVAL_MS = 1000;
+const POLL_INTERVAL_MS = 1000;
 export const STALE_AFTER_MS = 60_000;
 export async function acquireMachineLock(options) {
     const { command, dir, env, stderr } = options;

package/dist/esm/presentation.js

@@ -1,5 +1,5 @@
 import { describeInvalidOutputStyle } from '@williamthorsen/nmr-core';
-import { isHookName } from "./helpers/hook-name.js";
+import { isHookName } from "./helpers/isHookName.js";
 import { resolveOutputStyles } from "./output-style.js";
 import { readReportFormatEnv } from "./report-format.js";
 import { readVerbosityEnv, resolveVerbosity, } from "./verbosity.js";

package/dist/esm/report-format.d.ts

@@ -1,10 +1,3 @@
-/**
- * Renders the rejection of a value off the format ladder, naming where it was written. Every source that
- * accepts a format renders through this, so two of them can never come to name different ladders.
- */
-export declare function formatReportFormatRejection(source: string, value: string): string;
-/** Narrows a raw value to a point on the format ladder. */
-export declare function isReportFormat(value: string): value is ReportFormat;
 /**
  * Reads the format that the environment names. An unrecognized value is returned as an error, which keeps a
  * misspelling from going unnoticed for the life of the shell.
@@ -22,7 +15,7 @@ export declare const REPORT_FORMAT_ENV_VAR = "NMR_REPORT_FORMAT";
  * The points on the format ladder. `text` is a named point, so that one invocation can override a format
  * exported for the shell in either direction.
  */
-export declare const REPORT_FORMATS: readonly ["text", "json"];
+declare const REPORT_FORMATS: readonly ["text", "json"];
 /** How nmr renders its own verdicts, which is never the output of the commands that it runs. */
 export type ReportFormat = (typeof REPORT_FORMATS)[number];
 /** The format that the environment names, if any, or the message naming why its value could not be read. */
@@ -44,3 +37,4 @@ export interface ResolveReportFormatOptions {
     envFormat: ReportFormat | undefined;
     hasJsonFlag: boolean;
 }
+export {};

package/dist/esm/report-format.js

@@ -1,10 +1,3 @@
-export function formatReportFormatRejection(source, value) {
-    return `${source} is \`${value}\`, which is not one of: ${REPORT_FORMATS.join(', ')}`;
-}
-export function isReportFormat(value) {
-    const names = REPORT_FORMATS;
-    return names.includes(value);
-}
 export function readReportFormatEnv(env) {
     const rawValue = env[REPORT_FORMAT_ENV_VAR];
     if (rawValue === undefined || rawValue === '') {
@@ -16,10 +9,17 @@ export function readReportFormatEnv(env) {
     return { ok: true, format: rawValue };
 }
 export const REPORT_FORMAT_ENV_VAR = 'NMR_REPORT_FORMAT';
-export const REPORT_FORMATS = ['text', 'json'];
+const REPORT_FORMATS = ['text', 'json'];
 export function resolveReportFormat(options) {
     const { envFormat, hasJsonFlag } = options;
     if (hasJsonFlag)
         return 'json';
     return envFormat ?? 'text';
 }
+function formatReportFormatRejection(source, value) {
+    return `${source} is \`${value}\`, which is not one of: ${REPORT_FORMATS.join(', ')}`;
+}
+function isReportFormat(value) {
+    const names = REPORT_FORMATS;
+    return names.includes(value);
+}

package/dist/esm/resolve-scripts.js

@@ -1,6 +1,6 @@
 import { buildRootScripts, workspaceScripts } from "./default-scripts.js";
+import { toWorkspacePackageGlobs } from "./toWorkspacePackageGlobs.js";
 import { resolveWorkspace } from "./workspace.js";
-import { toWorkspacePackageGlobs } from "./workspace-globs.js";
 export function getDefaultWorkspaceScripts() {
     return { ...workspaceScripts };
 }

package/dist/esm/route.js

@@ -1,9 +1,9 @@
 import path from 'node:path';
 import { createCli, UsageError } from '@williamthorsen/nmr-core/cli';
 import { DEBUG_ENV_VAR, NO_CACHE_ENV_VAR } from "./check-cache/check-cache.js";
+import { describeHelp } from "./describeHelp.js";
 import { readEnvSwitch, readEnvSwitches } from "./env-switch.js";
 import { listDefinedCommands } from "./fan-out.js";
-import { describeHelp } from "./help.js";
 import { RUN_IF_PRESENT_ENV_VAR } from "./invocation.js";
 import { NO_LOCK_ENV_VAR } from "./machine-lock.js";
 import { NMR_FLAGS, toParsedArgs } from "./nmr-flags.js";

package/dist/esm/run-chain.js

@@ -4,7 +4,7 @@ import { NMR_BIN } from "./bins.js";
 import { resolveCacheKey } from "./check-cache/check-cache-gate.js";
 import { reportNmrCrossing } from "./crossing-diagnostics.js";
 import { NMR_GLYPHS } from "./glyphs.js";
-import { isHookName } from "./helpers/hook-name.js";
+import { isHookName } from "./helpers/isHookName.js";
 import { quoteForShell } from "./helpers/quoteForShell.js";
 import { wrapWithHooks } from "./hooks.js";
 import { USAGE_EXIT_CODE } from "./invocation.js";

package/dist/esm/runCli.js

@@ -1,6 +1,5 @@
 import { reportError } from '@williamthorsen/nmr-core';
 import { runCli as runRouter } from '@williamthorsen/nmr-core/cli';
-import { prependBinDirs } from "./bin-path.js";
 import { NMR_BIN } from "./bins.js";
 import { GIT_TREE_READER, NO_CACHE_ENV_VAR, resolveRunId, RUN_ID_ENV_VAR, } from "./check-cache/check-cache.js";
 import { openGate, runGated } from "./check-cache/check-cache-gate.js";
@@ -17,6 +16,7 @@ import { readFilterSelection as readFilterSelectionDefault, } from "./helpers/fi
 import { RUN_IF_PRESENT_ENV_VAR, USAGE_EXIT_CODE, VERSION, } from "./invocation.js";
 import { formatMisplacedFlagHint } from "./invocation-args.js";
 import { readInvocationFlags } from "./nmr-flags.js";
+import { prependBinDirs } from "./prependBinDirs.js";
 import { reportVerdict } from "./presentation.js";
 import { buildRootRegistry, buildWorkspaceRegistry, resolveScript } from "./resolver.js";
 import { buildRoot, buildVersionRoot } from "./route.js";
@@ -104,7 +104,7 @@ async function planRun(invocation, target) {
         stderr,
         env: childEnv,
     };
-    const delegation = composeDelegation({ childEnv, command, parsedArgs });
+    const delegation = composeDelegation({ childEnv, command, config: context.config, parsedArgs });
     if (delegation !== undefined) {
         const lock = await takeMachineLock(invocation);
         let result;

package/dist/esm/tiers.js

@@ -1,6 +1,6 @@
 import { readdirSync } from 'node:fs';
 import path from 'node:path';
-import { listGitIgnoredPaths } from "./git-ignored-paths.js";
+import { listGitIgnoredPaths } from "./listGitIgnoredPaths.js";
 const TEST_DIR = '__tests__';
 const TEST_EXTENSIONS = '{ts,tsx}';
 const TEST_GLOB_PREFIX = `**/${TEST_DIR}/**`;

package/dist/esm/types.d.ts

@@ -28,6 +28,17 @@ export interface CheckCacheConfig {
      */
     extraCommands?: string[];
 }
+/** Fan-out settings honored at the monorepo root. */
+export interface FanOutConfig {
+    /**
+     * Command names added to the set whose `-R` and `-F` fan-outs run packages in topological order, which holds
+     * `build` by default; every other fan-out starts each package without waiting for its workspace dependencies.
+     * Extends rather than replaces, so that declaring one command cannot drop `build`. List a command whose run in a
+     * package reads what the same command produces in that package's workspace dependencies. Every name has to
+     * resolve to a command, because a misspelt entry would otherwise be inert.
+     */
+    extraSortedCommands?: string[];
+}
 /** Self-hosted runner settings honored at the monorepo root, read by nmr's readyup kit. */
 export interface SelfHostedRunnerConfig {
     /**
@@ -59,6 +70,7 @@ export interface NmrConfig {
      * config says. A delegation flag still sends a run elsewhere.
      */
     delegate?: false;
+    fanOut?: FanOutConfig;
     output?: OutputConfig;
     workspaceScripts?: Record<string, ScriptValue>;
     rootScripts?: Record<string, ScriptValue>;

package/dist/esm/verbosity.d.ts

@@ -9,7 +9,7 @@ export declare const AGENT_ENV_VARS: readonly ["CLAUDECODE", "ROVODEV_CLI", "ROV
  * The points on the loudness ladder. Both are spelled out rather than leaving `full` implicit in the variable's
  * absence, so that a repo-level default is overridable from the environment in either direction.
  */
-export declare const COMMAND_VERBOSITIES: readonly ["full", "quiet"];
+declare const COMMAND_VERBOSITIES: readonly ["full", "quiet"];
 /**
  * Passes the resolved verbosity down the chain of spawned processes, so that `-q` applies to every process rather
  * than only the first. The pass key does not include it: It changes what a run prints and never what a command
@@ -65,3 +65,4 @@ export type VerbosityRead = {
     ok: false;
     error: string;
 };
+export {};

package/dist/esm/verbosity.js

@@ -1,5 +1,5 @@
 export const AGENT_ENV_VARS = ['CLAUDECODE', 'ROVODEV_CLI', 'ROVO_CLI'];
-export const COMMAND_VERBOSITIES = ['full', 'quiet'];
+const COMMAND_VERBOSITIES = ['full', 'quiet'];
 export const COMMAND_VERBOSITY_ENV_VAR = 'NMR_COMMAND_VERBOSITY';
 export function formatVerbosityRejection(source, value) {
     return `${source} is \`${value}\`, which is not one of: ${COMMAND_VERBOSITIES.join(', ')}`;

package/dist/esm/vitest.js

@@ -3,12 +3,12 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isRecord } from '@williamthorsen/nmr-core';
 import { defaultExclude, mergeConfig } from 'vitest/config';
-import { listGitIgnoredPaths } from "./git-ignored-paths.js";
+import { listGitIgnoredPaths } from "./listGitIgnoredPaths.js";
 import { ALL_TEST_PATTERNS, buildTierPatterns, TEST_COLLECTION_EXCLUDE, TIER_NAMES } from "./tiers.js";
+import { toWorkspacePackageGlobs } from "./toWorkspacePackageGlobs.js";
 import { deriveDefaultMaxWorkers, readMaxWorkersFlag } from "./vitest-max-workers.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;

package/docs/scripts.md

@@ -41,6 +41,17 @@ 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.
 
+#### Package order in a fan-out
+
+An `-R` or `-F` fan-out of `build` runs the packages in topological order, so that each package builds after its workspace dependencies. Every other fan-out passes `--no-sort` to pnpm and starts each package's command without waiting for its dependencies to finish theirs: `test`, the `test:*` commands, and `typecheck` read the `dist` that an earlier `build` wrote, not anything that the same command writes in another package. A command that does read what its dependencies' runs of it produce, such as a code generator whose output a dependent package imports, keeps the order once `fanOut.extraSortedCommands` lists it:
+
+```ts
+// .config/nmr.config.ts
+export default defineConfig({ fanOut: { extraSortedCommands: ['generate'] } });
+```
+
+The list adds to `build` and cannot remove it, and a name in it that does not resolve to any command fails when the config loads.
+
 #### 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:
@@ -125,6 +136,7 @@ A minimal `.config/nmr.config.ts` is in the [README](../README.md#configuration)
 | `delegate`         | `false`                                                                       | Keeps every check on the machine that has the tree, whatever `NMR_DELEGATE` or the [user config](delegate.md#the-user-config) says; a delegation flag still sends a run elsewhere (root config only)                                                                                                                                         |
 | `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)                                                                                                                                                                                                                                                                                    |
+| `fanOut`           | `{ extraSortedCommands?: string[] }`                                          | Commands whose fan-out runs packages in topological order, besides `build`; see [package order in a fan-out](#package-order-in-a-fan-out) (root config only)                                                                                                                                                                                 |
 | `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 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -81,8 +81,8 @@
   ],
   "dependencies": {
     "@williamthorsen/nmr-core": "0.16.2",
-    "@williamthorsen/toolbelt.errors": "0.9.1",
-    "@williamthorsen/toolbelt.filesystem": "0.10.1",
+    "@williamthorsen/toolbelt.errors": "0.10.0",
+    "@williamthorsen/toolbelt.filesystem": "0.10.2",
     "glob": "14.0.4",
     "prettier": "3.9.10",
     "prettier-plugin-sh": "0.20.2",
@@ -90,13 +90,13 @@
     "unconfig": "7.5.0"
   },
   "devDependencies": {
-    "@williamthorsen/toolbelt.testing": "0.8.1",
-    "@williamthorsen/toolbelt.vitest": "0.13.3",
+    "@williamthorsen/toolbelt.testing": "0.8.2",
+    "@williamthorsen/toolbelt.vitest": "0.13.4",
     "esbuild": "0.28.2",
-    "readyup": "0.45.1",
+    "readyup": "0.46.1",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
-    "vite": "8.3.7",
+    "vite": "8.3.8",
     "vitest": "5.1.0",
     "yaml": "2.9.1"
   },

package/dist/esm/check-cache/config-check-cache.d.ts

@@ -1,17 +0,0 @@
-import type { NmrConfig } from '../types.js';
-/**
- * Rejects a `checkCache` name that does not resolve to any command. Both fields are read by name alone, so a
- * misspelt entry is inert: The command that it meant to name goes on running, indistinguishable from one that
- * cannot be cached at all.
- *
- * Because the test is resolvability rather than membership of the cacheable set, an `excludeCommands` entry
- * written against a name that a later release moves out of the defaults remains valid.
- *
- * Reads nothing while every name resolves in the merged registries, and reads a package's own `scripts` only
- * once a name is missing from them: Those are a resolution tier of their own; a name declared only there is
- * valid.
- *
- * Does nothing outside a monorepo root, where `checkCache` is a key that this tier does not honor. `assertTierKeys`
- * reports that, and of the two messages it is the one that names the real mistake.
- */
-export declare function assertResolvableCheckCacheCommands(config: NmrConfig, configPath: string, baseDir: string): void;