@williamthorsen/nmr 2.0.0 → 2.0.2

package/dist/esm/{check-cache-gate.js → check-cache/check-cache-gate.js}

@@ -1,20 +1,19 @@
 import { startTimer } from '@williamthorsen/nmr-core';
+import { addLockEnv, takeMachineLock } from "../child-env.js";
+import { runPlanOnHost } from "../delegation/delegate-host.js";
+import { VERSION } from "../invocation.js";
+import { formatFlagSpelling } from "../nmr-flags.js";
+import { resolveChannel } from "../output-channel.js";
+import { splitSegments } from "../shell-syntax.js";
 import { formatMisplacedNoCacheWarning, isCacheableCommand, resolveTreeSnapshot, writeDebugNote, } from "./check-cache.js";
 import { findStaleBuildOutput, readBuildOutputState } from "./check-cache-build-output.js";
 import { recordDelegatedPass } from "./check-cache-delegation.js";
 import { certifyRetention, readCheckCacheEntry } from "./check-cache-entries.js";
 import { computeCacheKey, computeRetentionKey } from "./check-cache-key.js";
 import { recordPass } from "./check-cache-record.js";
-import { addLockEnv, takeMachineLock } from "./child-env.js";
-import { runPlanOnHost } from "./delegate-host.js";
-import { VERSION } from "./invocation.js";
-import { formatFlagSpelling } from "./nmr-flags.js";
-import { resolveChannel } from "./output-channel.js";
 import { writePassManifestEntry } from "./pass-manifest.js";
-import { runSteps } from "./runner.js";
-import { splitSegments } from "./shell-syntax.js";
 export function openGate(options) {
-    const { command, config, env, monorepoRoot, passthrough, stderr, style } = options;
+    const { command, config, env, monorepoRoot, passthrough, readTree, stderr, style } = options;
     if (!isCacheableCommand(config.checkCache, command)) {
         return undefined;
     }
@@ -25,7 +24,7 @@ export function openGate(options) {
         writeDebugNote(`gate disabled: ${command} was passed arguments`, env, stderr);
         return undefined;
     }
-    const snapshot = resolveTreeSnapshot({ monorepoRoot, env });
+    const snapshot = resolveTreeSnapshot({ monorepoRoot, env, readTree });
     if (!snapshot.ok) {
         writeDebugNote(`gate disabled: ${snapshot.reason}`, env, stderr);
         return undefined;
@@ -83,7 +82,7 @@ export async function runGated(plan) {
         }
         const runOptions = { ...plan.runOptions, env: addLockEnv(plan.runOptions.env ?? env, lock) };
         const readElapsedMs = startTimer();
-        const { exitCode, retainedOutput, statedOutcomes } = await runSteps(plan.steps, anchorDir, runOptions);
+        const { exitCode, retainedOutput, statedOutcomes } = await plan.invocation.runSteps(plan.steps, anchorDir, runOptions);
         const durationMs = readElapsedMs();
         if (exitCode === 0 && gate !== undefined) {
             await recordPass({
@@ -97,6 +96,7 @@ export async function runGated(plan) {
                 key: gate.key,
                 monorepoRoot,
                 ownSteps: plan.ownSteps,
+                readTree: plan.invocation.readTree,
                 retainedOutput,
                 retentionKey: gate.retentionKey,
                 runId: plan.runId,

package/dist/esm/{check-cache-key.d.ts → check-cache/check-cache-key.d.ts}

@@ -1,5 +1,5 @@
+import type { OutputChannels } from '../output-channel.js';
 import type { TreeSnapshot } from './check-cache.js';
-import type { OutputChannels } from './output-channel.js';
 /** The parts of the running interpreter that can change what a check concludes. */
 export interface RuntimeIdentity {
     arch: string;

package/dist/esm/{check-cache-record.d.ts → check-cache/check-cache-record.d.ts}

@@ -1,11 +1,11 @@
 import type { Writable } from 'node:stream';
-import { type TreeSnapshot } from './check-cache.js';
+import { type RunCliResult, type RunPlan } from '../invocation.js';
+import type { RetainedOutput } from '../runner.js';
+import type { Step } from '../steps.js';
+import type { NmrConfig } from '../types.js';
+import { type TreeReader, type TreeSnapshot } from './check-cache.js';
 import { type BuildOutputState } from './check-cache-build-output.js';
 import { type EntryRef, type Retention } from './check-cache-entries.js';
-import { type RunCliResult, type RunPlan } from './invocation.js';
-import type { RetainedOutput } from './runner.js';
-import type { Step } from './steps.js';
-import type { NmrConfig } from './types.js';
 /**
  * Records a pass that `host` earned, unless a pass earned here under the same key would still be recalled, because
  * that pass satisfies every invocation that the host pass would. One whose build output is missing or came from
@@ -53,6 +53,7 @@ export declare function recordPass(options: {
     monorepoRoot: string;
     retainedOutput: RetainedOutput | undefined;
     ownSteps: readonly Step[];
+    readTree: TreeReader;
     retentionKey: string;
     runId: string;
     snapshot: TreeSnapshot;

package/dist/esm/{check-cache-record.js → check-cache/check-cache-record.js}

@@ -1,12 +1,13 @@
 import path from 'node:path';
 import { describeError } from '@williamthorsen/toolbelt.errors';
-import { isCacheableCommand, resolveTreeSnapshot, writeDebugNote } from "./check-cache.js";
+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 { 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 { deriveExcerpt } from "./helpers/deriveExcerpt.js";
-import { composeTranscript } from "./helpers/transcript.js";
-import { RUN_IF_PRESENT_ENV_VAR, VERSION } from "./invocation.js";
 import { writePassManifestEntry } from "./pass-manifest.js";
 import { renderRecording, renderRefusal, resolveRecording } from "./recording.js";
 import { assembleReplay } from "./replay-assembly.js";
@@ -43,7 +44,7 @@ export async function recordHostPass(options) {
 }
 export async function recordPass(options) {
     const { anchorDir, command, env, monorepoRoot, snapshot, stderr } = options;
-    const currentRead = resolveTreeSnapshot({ monorepoRoot, env: {} });
+    const currentRead = resolveTreeSnapshot({ monorepoRoot, env: {}, readTree: options.readTree });
     if (!currentRead.ok) {
         writeDebugNote(`not recording ${command}: ${currentRead.reason}`, env, stderr);
         return;
@@ -124,7 +125,7 @@ export async function reportRecording(plan) {
     });
     if (!lookup.ok) {
         stderr.write(`${renderRefusal({ command, refusal: lookup.refusal, scope, style: styles.stderr })}\n`);
-        return { exitCode: env[RUN_IF_PRESENT_ENV_VAR] === '1' ? 0 : 1 };
+        return { exitCode: isEnvSwitchOn(env, RUN_IF_PRESENT_ENV_VAR) ? 0 : 1 };
     }
     stdout.write(renderRecording({ command, recording: lookup.recording, scope, style: styles.stdout }));
     return { exitCode: 0 };

package/dist/esm/{check-cache.d.ts → check-cache/check-cache.d.ts}

@@ -1,11 +1,18 @@
 import type { Writable } from 'node:stream';
-import { type OutputStyle } from '@williamthorsen/nmr-core';
-import type { CheckCacheConfig } from './types.js';
+import { hashWorkingTree, type OutputStyle, readHeadSha } from '@williamthorsen/nmr-core';
+import type { CheckCacheConfig } from '../types.js';
 /** One working tree, observed once per top-level invocation and shared with every process below it. */
 export interface TreeSnapshot {
     treeId: string;
     headSha: string;
 }
+/** The git reads behind a tree snapshot, which a test replaces with a fake. */
+export interface TreeReader {
+    hashWorkingTree: typeof hashWorkingTree;
+    readHeadSha: typeof readHeadSha;
+}
+/** The tree reader that asks git. */
+export declare const GIT_TREE_READER: TreeReader;
 /** Set to `1` to hear why the gate did not skip, or why it is disabled. */
 export declare const DEBUG_ENV_VAR = "NMR_DEBUG";
 /**
@@ -72,6 +79,7 @@ export declare function resolveRunId(env: NodeJS.ProcessEnv): string;
 export declare function resolveTreeSnapshot(options: {
     monorepoRoot: string;
     env: NodeJS.ProcessEnv;
+    readTree: TreeReader;
 }): {
     ok: true;
     snapshot: TreeSnapshot;

package/dist/esm/{check-cache.js → check-cache/check-cache.js}

@@ -1,7 +1,9 @@
 import { randomUUID } from 'node:crypto';
 import { realpathSync } from 'node:fs';
 import { hashWorkingTree, readHeadSha, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
-import { isHookName } from "./helpers/hook-name.js";
+import { isEnvSwitchOn } from "../env-switch.js";
+import { isHookName } from "../helpers/hook-name.js";
+export const GIT_TREE_READER = { hashWorkingTree, readHeadSha };
 export const DEBUG_ENV_VAR = 'NMR_DEBUG';
 export const DEFAULT_CACHEABLE_COMMANDS = [
     'check',
@@ -54,10 +56,11 @@ export function resolveRunId(env) {
 }
 export function resolveTreeSnapshot(options) {
     const inheritedSnapshot = decodeTreeSnapshot(options.env[TREE_SNAPSHOT_ENV_VAR]);
-    if (inheritedSnapshot !== undefined && readHeadSha(options.monorepoRoot) === inheritedSnapshot.headSha) {
+    if (inheritedSnapshot !== undefined &&
+        options.readTree.readHeadSha(options.monorepoRoot) === inheritedSnapshot.headSha) {
         return { ok: true, snapshot: inheritedSnapshot };
     }
-    const hashedTree = hashWorkingTree(options.monorepoRoot);
+    const hashedTree = options.readTree.hashWorkingTree(options.monorepoRoot);
     if (!hashedTree.ok) {
         return hashedTree;
     }
@@ -74,7 +77,7 @@ export function resolveTreeSnapshot(options) {
     return { ok: true, snapshot: { treeId: hashedTree.treeId, headSha: hashedTree.headSha } };
 }
 export function writeDebugNote(message, env, stderr) {
-    if (env[DEBUG_ENV_VAR] === '1') {
+    if (isEnvSwitchOn(env, DEBUG_ENV_VAR)) {
         stderr.write(`nmr check-cache: ${message}\n`);
     }
 }

package/dist/esm/{config-check-cache.d.ts → check-cache/config-check-cache.d.ts}

@@ -1,4 +1,4 @@
-import type { NmrConfig } from './types.js';
+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

package/dist/esm/{config-check-cache.js → check-cache/config-check-cache.js}

@@ -1,8 +1,8 @@
 import { UserError } from '@williamthorsen/nmr-core';
-import { findClosestName } from "./helpers/findClosestName.js";
-import { isHookName } from "./helpers/hook-name.js";
-import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "./resolver.js";
-import { getWorkspacePackageDirs, isMonorepoRoot } from "./workspace.js";
+import { findClosestName } from "../helpers/findClosestName.js";
+import { isHookName } from "../helpers/hook-name.js";
+import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "../resolver.js";
+import { getWorkspacePackageDirs, isMonorepoRoot } from "../workspace.js";
 export function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
     const { checkCache } = config;
     if (checkCache === undefined || !isMonorepoRoot(baseDir)) {

package/dist/esm/{pass-manifest.d.ts → check-cache/pass-manifest.d.ts}

@@ -1,6 +1,6 @@
 import type { Writable } from 'node:stream';
+import type { CheckCacheConfig } from '../types.js';
 import { type ReplayLine } from './check-cache-entries.js';
-import type { CheckCacheConfig } from './types.js';
 /**
  * One pass that an nmr process on a host recorded or recalled during a delegated run, as the host session returns it
  * to the delegating machine.

package/dist/esm/{pass-manifest.js → check-cache/pass-manifest.js}

@@ -4,9 +4,9 @@ import path from 'node:path';
 import process from 'node:process';
 import { isRecord } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { MAX_EXCERPT_BYTES } from "../helpers/deriveExcerpt.js";
 import { isCacheableCommand, PASS_MANIFEST_DIR_ENV_VAR, writeDebugNote } from "./check-cache.js";
 import { isReplayLine } from "./check-cache-entries.js";
-import { MAX_EXCERPT_BYTES } from "./helpers/deriveExcerpt.js";
 export function formatManifestScope(monorepoRoot, anchorDir) {
     const scope = path.relative(monorepoRoot, anchorDir);
     return scope === '' ? '.' : scope.split(path.sep).join('/');

package/dist/esm/{recording.js → check-cache/recording.js}

@@ -1,7 +1,7 @@
 import { formatGlyphLine, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { NMR_GLYPHS } from "../glyphs.js";
+import { formatDuration } from "../helpers/duration.js";
 import { readCheckCacheEntry, readTranscript } from "./check-cache-entries.js";
-import { NMR_GLYPHS } from "./glyphs.js";
-import { formatDuration } from "./helpers/duration.js";
 export function renderRecording(options) {
     const { entry } = options.recording;
     const age = formatDuration(Math.max(0, Date.now() - Date.parse(entry.recordedAt)));

package/dist/esm/{replay-assembly.d.ts → check-cache/replay-assembly.d.ts}

@@ -1,5 +1,5 @@
+import { type Step } from '../steps.js';
 import { type ReplayLine } from './check-cache-entries.js';
-import { type Step } from './steps.js';
 /**
  * Assembles what a composite's skip replays: the excerpts recorded by its constituents, in the order in which
  * its own steps name them.

package/dist/esm/{replay-assembly.js → check-cache/replay-assembly.js}

@@ -1,6 +1,6 @@
+import { readNmrStep } from "../steps.js";
+import { getWorkspacePackageDirs } from "../workspace.js";
 import { readCheckCacheEntry } from "./check-cache-entries.js";
-import { readNmrStep } from "./steps.js";
-import { getWorkspacePackageDirs } from "./workspace.js";
 export async function assembleReplay(options) {
     const { anchorDir, monorepoRoot, runId, steps, treeHash } = options;
     const candidates = steps.flatMap((step) => {

package/dist/esm/child-env.d.ts

@@ -1,5 +1,5 @@
 import type { StreamStyles } from '@williamthorsen/nmr-core';
-import { type TreeSnapshot } from './check-cache.js';
+import { type TreeSnapshot } from './check-cache/check-cache.js';
 import type { Invocation } from './invocation.js';
 import { type MachineLock } from './machine-lock.js';
 import { type ReportFormat } from './report-format.js';

package/dist/esm/child-env.js

@@ -1,8 +1,8 @@
-import { DEBUG_ENV_VAR, encodeTreeSnapshot, NO_CACHE_ENV_VAR, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, } from "./check-cache.js";
+import { DEBUG_ENV_VAR, encodeTreeSnapshot, NO_CACHE_ENV_VAR, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, } from "./check-cache/check-cache.js";
+import { DELEGATE_ENV_VAR } from "./delegation/remote-run.js";
 import { acquireMachineLock, formatMisplacedNoLockWarning, HEAVY_COMMANDS, LOCK_TOKEN_ENV_VAR, NO_LOCK_ENV_VAR, } from "./machine-lock.js";
 import { formatFlagSpelling } from "./nmr-flags.js";
 import { OUTPUT_STYLE_ENV_VAR } from "./output-style.js";
-import { DELEGATE_ENV_VAR } from "./remote-run.js";
 import { REPORT_FORMAT_ENV_VAR } from "./report-format.js";
 import { COMMAND_VERBOSITY_ENV_VAR } from "./verbosity.js";
 export function addLockEnv(env, lock) {

package/dist/esm/cli-build.js

@@ -1,16 +1,9 @@
+import process from 'node:process';
 import { reportFailure } from '@williamthorsen/nmr-core';
 import { NMR_COMPILE_BIN } from "./bins.js";
-import { buildPackage } from "./commands/build.js";
-import { loadWorkspaceConfig } from "./config.js";
-import { resolveBinStyles } from "./resolveBinStyles.js";
+import { runCompile } from "./commands/compile.js";
 try {
-    const { stdout } = resolveBinStyles();
-    const packageDir = process.cwd();
-    const { build } = await loadWorkspaceConfig(packageDir);
-    await buildPackage(packageDir, {
-        style: stdout,
-        ...(build?.extraIgnorePatterns !== undefined && { extraIgnorePatterns: build.extraIgnorePatterns }),
-    });
+    process.exitCode = await runCompile(process.argv.slice(2), process.cwd());
 }
 catch (error) {
     reportFailure(NMR_COMPILE_BIN, error);

package/dist/esm/cli-clean.js

@@ -2,9 +2,8 @@ import process from 'node:process';
 import { reportFailure } from '@williamthorsen/nmr-core';
 import { NMR_CLEAN_BIN } from "./bins.js";
 import { runClean } from "./commands/clean.js";
-import { resolveBinStyles } from "./resolveBinStyles.js";
 try {
-    await runClean(process.cwd(), resolveBinStyles().stdout);
+    process.exitCode = await runClean(process.argv.slice(2), process.cwd());
 }
 catch (error) {
     reportFailure(NMR_CLEAN_BIN, error);

package/dist/esm/cli-report-catalog.js

@@ -1,10 +1,9 @@
 import process from 'node:process';
 import { reportFailure } from '@williamthorsen/nmr-core';
 import { NMR_REPORT_CATALOG_BIN } from "./bins.js";
-import { reportCatalog } from "./commands/report-catalog.js";
-import { resolveBinStyles } from "./resolveBinStyles.js";
+import { runReportCatalog } from "./commands/report-catalog.js";
 try {
-    reportCatalog(process.cwd(), resolveBinStyles().stderr);
+    process.exitCode = await runReportCatalog(process.argv.slice(2), process.cwd());
 }
 catch (error) {
     reportFailure(NMR_REPORT_CATALOG_BIN, error);

package/dist/esm/cli-report-overrides.js

@@ -1,11 +1,9 @@
+import process from 'node:process';
 import { reportFailure } from '@williamthorsen/nmr-core';
 import { NMR_REPORT_OVERRIDES_BIN } from "./bins.js";
-import { reportOverrides } from "./commands/report-overrides.js";
-import { resolveBinStyles } from "./resolveBinStyles.js";
-import { findMonorepoRoot } from "./workspace.js";
+import { runReportOverrides } from "./commands/report-overrides.js";
 try {
-    const monorepoRoot = findMonorepoRoot();
-    reportOverrides(monorepoRoot, resolveBinStyles().stderr);
+    process.exitCode = await runReportOverrides(process.argv.slice(2), process.cwd());
 }
 catch (error) {
     reportFailure(NMR_REPORT_OVERRIDES_BIN, error);

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

@@ -1,15 +1,10 @@
+import { type SpawnInherited } from './spawn-inherited.js';
 import { type WorkflowTool } from './workflow-tools.js';
-/** How a spawned actionlint ended. */
-export interface ActionlintOutcome {
-    error?: Error | undefined;
-    signal: NodeJS.Signals | null;
-    status: number | null;
-}
 export interface RunActionlintOptions {
     /** Directories under which the pinned tools are cached, in lookup order; defaults to `resolveToolCacheRoots`. */
     cacheRoots?: readonly [string, ...string[]];
     ensure?: (tool: WorkflowTool, cacheRoots: readonly [string, ...string[]]) => Promise<string>;
-    spawn?: (file: string, args: string[], cwd: string) => ActionlintOutcome;
+    spawn?: SpawnInherited;
 }
 /**
  * Lints the monorepo's GitHub Actions workflows with the pinned actionlint, running its shellcheck pass with the

package/dist/esm/commands/actionlint.js

@@ -1,8 +1,7 @@
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { UserError } from '@williamthorsen/nmr-core';
-import { describeSignalExitCode } from "../child-process.js";
+import { resolveInheritedExitCode, spawnInherited } from "./spawn-inherited.js";
 import { ensureTool, resolveToolCacheRoots } from "./workflow-tools.js";
 const WORKFLOWS_DIR = path.join('.github', 'workflows');
 export async function runActionlint(monorepoRoot, args, options = {}) {
@@ -14,19 +13,14 @@ export async function runActionlint(monorepoRoot, args, options = {}) {
     const ensure = options.ensure ?? ((tool, roots) => ensureTool(tool, { cacheRoots: roots }));
     const actionlintPath = await ensure('actionlint', cacheRoots);
     const shellcheckPath = await ensure('shellcheck', cacheRoots);
-    const outcome = (options.spawn ?? spawnInherited)(actionlintPath, buildActionlintArgs(shellcheckPath, args), monorepoRoot);
+    const outcome = (options.spawn ?? spawnInherited)(actionlintPath, buildActionlintArgs(shellcheckPath, args), {
+        cwd: monorepoRoot,
+    });
     if (outcome.error !== undefined) {
         throw new UserError(`Cannot run actionlint: ${outcome.error.message}`, { cause: outcome.error });
     }
-    if (outcome.signal !== null) {
-        return describeSignalExitCode(outcome.signal);
-    }
-    return outcome.status ?? 1;
+    return resolveInheritedExitCode(outcome);
 }
 export function buildActionlintArgs(shellcheckPath, args) {
     return [`-shellcheck=${shellcheckPath}`, '-pyflakes=', ...args];
 }
-function spawnInherited(file, args, cwd) {
-    const result = spawnSync(file, args, { cwd, stdio: 'inherit' });
-    return { error: result.error, signal: result.signal, status: result.status };
-}

package/dist/esm/commands/build-output.d.ts

@@ -6,28 +6,13 @@ export interface BuildOptions {
     ignorePatterns?: string[];
     outdir?: string;
 }
-/** The pair of directories through which a build publishes, both siblings of the emit directory. */
-export interface ScratchDirs {
-    previousDir: string;
-    stagingDir: string;
-}
-export declare const DEFAULT_ENTRY_GLOBS: string[];
-/**
- * Directories holding test scaffolding rather than published code, excluded from entry-point selection so that a
- * package does not publish its own helpers. The list differs from the vitest factory's `COVERAGE_EXCLUDE`, which
- * leaves `test-utils/` inside the coverage include set, and neither list can be derived from the other.
- *
- * Ignoring a file removes it as an entry point, not from the emit. The compiler still emits whatever the
- * surviving entry points import, which keeps a production module that uses a helper from emitting a dangling
- * specifier. Widening this list can therefore only drop files that production code does not import.
- */
-export declare const DEFAULT_IGNORE_PATTERNS: string[];
 export declare const DEFAULT_OUTDIR = "dist/esm/";
 /**
- * Reports whether the output that a build of `packageDir` would produce is currently on disk. Applies the build's
- * own rule, on the same options that the build was given, so a caller probing for output and the build deciding
- * whether to rebuild cannot disagree: A package whose entry points emit nothing does not expect any output, and
- * reports present. Passing options that the build was not given would make the two disagree.
+ * Reports whether the output that a build of `packageDir` would produce is currently on disk. Selects entry points
+ * through `resolveEntryPoints` and tests them through `hasExpectedBuildOutput`, as the build does, so a caller
+ * probing for output and the build deciding whether to rebuild cannot disagree: A package whose entry points emit
+ * nothing does not expect any output, and reports present. Passing options that the build was not given would make
+ * the two disagree.
  */
 export declare function hasBuildOutput(packageDir: string, options?: BuildOptions): Promise<boolean>;
 /**
@@ -65,18 +50,8 @@ export declare function resolveBuildCachePath(packageDir: string): string;
  * `readBuildDigest` returns.
  */
 export declare function resolveEmitDurationPath(packageDir: string): string;
-/**
- * Resolves the two scratch directories through which a build publishes: `staging`, which the emit is written to,
- * and `previous`, which the outgoing output is renamed aside to. Both are siblings of the emit directory, so a
- * rename between them never crosses a filesystem, and both are dot-prefixed so that a leftover stays out of the
- * globs that select sources.
- *
- * The names are fixed rather than unique because the build removes both before use. A unique name would need a
- * sweep to accomplish that removal, and a sweep cannot tell a directory orphaned by a killed run from one that a
- * concurrent build is still writing. Because a directory left behind by a failed build is cleared the same way,
- * the failure path does not need any cleanup of its own.
- */
-export declare function resolveScratchDirs(emitDir: string): ScratchDirs;
+/** Selects the entry points that a build of `packageDir` compiles, as paths relative to `packageDir`. */
+export declare function resolveEntryPoints(packageDir: string, options?: BuildOptions): Promise<string[]>;
 /**
  * Resolves the fingerprint of the nmr compiling `packageDir`, the `BuildToolchain` member that identifies nmr. It
  * is nmr's own build digest when one is on disk, which changes on a dev-loop edit that the version does not

package/dist/esm/commands/build-output.js

@@ -3,17 +3,14 @@ import path from 'node:path';
 import { findPackageRoot, readCacheEntry, readGuardedCacheEntry, resolveCacheEntryPath, writeGuardedCacheEntry, } from '@williamthorsen/nmr-core';
 import { glob } from 'glob';
 import { readPackageJson } from "../helpers/package-json.js";
-export const DEFAULT_ENTRY_GLOBS = ['src/**/*.{ts,tsx}'];
-export const DEFAULT_IGNORE_PATTERNS = ['**/__fixtures__/**', '**/__mocks__/**', '**/__tests__/**', '**/test-utils/**'];
+const DEFAULT_ENTRY_GLOBS = ['src/**/*.{ts,tsx}'];
+const DEFAULT_IGNORE_PATTERNS = ['**/__fixtures__/**', '**/__mocks__/**', '**/__tests__/**', '**/test-utils/**'];
 export const DEFAULT_OUTDIR = 'dist/esm/';
 const BUILD_CACHE_TOOL = 'nmr-compile';
 const SELF_DIR = findPackageRoot(import.meta.url);
 export async function hasBuildOutput(packageDir, options = {}) {
     const outdir = options.outdir ?? DEFAULT_OUTDIR;
-    const entryPoints = await glob(options.entryGlobs ?? DEFAULT_ENTRY_GLOBS, {
-        cwd: packageDir,
-        ignore: [...(options.ignorePatterns ?? DEFAULT_IGNORE_PATTERNS), ...(options.extraIgnorePatterns ?? [])],
-    });
+    const entryPoints = await resolveEntryPoints(packageDir, options);
     return hasExpectedBuildOutput(packageDir, outdir, entryPoints);
 }
 export function hasExpectedBuildOutput(packageDir, outdir, entryPoints) {
@@ -49,13 +46,11 @@ export function resolveEmitDurationPath(packageDir) {
         extension: '.duration.json',
     });
 }
-export function resolveScratchDirs(emitDir) {
-    const parent = path.dirname(emitDir);
-    const name = path.basename(emitDir);
-    return {
-        previousDir: path.join(parent, `.${name}.previous`),
-        stagingDir: path.join(parent, `.${name}.staging`),
-    };
+export async function resolveEntryPoints(packageDir, options = {}) {
+    return glob(options.entryGlobs ?? DEFAULT_ENTRY_GLOBS, {
+        cwd: packageDir,
+        ignore: [...(options.ignorePatterns ?? DEFAULT_IGNORE_PATTERNS), ...(options.extraIgnorePatterns ?? [])],
+    });
 }
 export async function resolveToolchainFingerprint(packageDir, selfDir = SELF_DIR) {
     if (!isSameDir(packageDir, selfDir)) {

package/dist/esm/commands/build-report.d.ts

@@ -0,0 +1,6 @@
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+import type { BuildOutcome, BuildProgress } from './build.js';
+/** Renders the line that closes a build: the skip, naming the saving when it is worth naming, or the emit. */
+export declare function renderBuildOutcome(outcome: BuildOutcome, packageName: string, style: OutputStyle): string;
+/** Renders the line that announces an emit, naming why the build is about to run. */
+export declare function renderBuildProgress(progress: BuildProgress, packageName: string, style: OutputStyle): string;

package/dist/esm/commands/build-report.js

@@ -0,0 +1,21 @@
+import { formatGlyphLine, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { NMR_GLYPHS } from "../glyphs.js";
+import { formatSaving } from "../helpers/duration.js";
+export function renderBuildOutcome(outcome, packageName, style) {
+    if (outcome.kind === 'unchanged') {
+        const saving = formatSaving(outcome.savedMs ?? 0);
+        const savingClause = saving === undefined ? '' : `, ${saving}`;
+        return `${STATUS_GLYPHS[style].skipped.text} ${packageName}: No changes detected. Skipping build${savingClause}.`;
+    }
+    return formatGlyphLine(NMR_GLYPHS, style, 'package', `${packageName}: ${describeEmit(outcome.fileCount, outcome.outdir)}`);
+}
+export function renderBuildProgress(progress, packageName, style) {
+    const message = progress.kind === 'output-missing' ? 'Build output is missing. Rebuilding.' : 'Changes detected.';
+    return formatGlyphLine(NMR_GLYPHS, style, 'package', `${packageName}: ${message}`);
+}
+function describeEmit(fileCount, outdir) {
+    if (fileCount === 0) {
+        return 'Did not emit any output.';
+    }
+    return `Compiled ${fileCount} files to ${outdir.replace(/\/+$/u, '')}.`;
+}

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

@@ -1,6 +1,23 @@
-import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type * as TypeScript from 'typescript';
 import { type BuildOptions } from './build-output.js';
+/**
+ * How a build ended: skipped because its inputs and output were unchanged, with the emit time recorded for those
+ * inputs when one was; or emitted, with the count of files that it published to `outdir`.
+ */
+export type BuildOutcome = {
+    kind: 'unchanged';
+    savedMs?: number;
+} | {
+    kind: 'emitted';
+    fileCount: number;
+    outdir: string;
+};
+/** Why a build is about to emit: its inputs changed, or its inputs match the cache and its output is missing. */
+export type BuildProgress = {
+    kind: 'inputs-changed';
+} | {
+    kind: 'output-missing';
+};
 /**
  * The toolchain from which a build's emit comes: the resolved compiler and the nmr running it. `computeBuildHash`
  * folds both into the build hash, because the same sources can compile to different output under a different
@@ -10,9 +27,10 @@ export interface BuildToolchain {
     compilerVersion: string;
     fingerprint: string;
 }
-/** What a build needs beyond its sources: the options shaping the emit, and the style in which it reports. */
+/** What a build needs beyond its sources: the options shaping the emit, and a listener for its progress. */
 export interface BuildPackageOptions extends BuildOptions {
-    style: OutputStyle;
+    /** Called before the emit begins, so that a caller can report the build ahead of a slow compile. */
+    onProgress?: (progress: BuildProgress) => void;
     /**
      * Overridable so that a missing `typescript` peer is reachable without uninstalling it.
      *
@@ -30,10 +48,15 @@ export interface BuildPackageOptions extends BuildOptions {
  * current inputs rather than an accumulation of every build that ever ran. Assets belong outside it, or in a
  * `build:post` hook, which runs after the output is published.
  */
-export declare function buildPackage(packageDir: string, options: BuildPackageOptions): Promise<void>;
+export declare function buildPackage(packageDir: string, options?: BuildPackageOptions): Promise<BuildOutcome>;
 /**
  * Produces a digest of the given files (paths and contents), the emit config, and the toolchain.
  * The file list is sorted so that the digest is order-invariant, and each path is folded in so that renames are
  * detected.
  */
 export declare function computeBuildHash(packageDir: string, files: string[], emitConfig: object, toolchain: BuildToolchain): Promise<string>;
+/**
+ * Records a build skipped on unchanged inputs: states the `build-unchanged` outcome with the emit time recorded under
+ * `digest`, and returns that time, which is absent when none was recorded.
+ */
+export declare function recordUnchangedBuild(packageDir: string, digest: string, env: NodeJS.ProcessEnv): Promise<number | undefined>;