@williamthorsen/nmr 0.48.0 → 0.49.0

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

@@ -0,0 +1,57 @@
+import type { StreamStyles } from '@williamthorsen/nmr-core';
+import { type TreeSnapshot } from './check-cache.js';
+import type { Invocation } from './invocation.js';
+import { type MachineLock } from './machine-lock.js';
+import { type ReportFormat } from './report-format.js';
+import { type CommandVerbosity } from './verbosity.js';
+/**
+ * Returns the environment that tells the processes below this one what the lock came to: They run under its hold,
+ * or, when the chain runs unlocked, they skip the lock.
+ */
+export declare function addLockEnv(env: NodeJS.ProcessEnv, lock: MachineLock | undefined): NodeJS.ProcessEnv;
+/**
+ * Builds the environment that every process below this one inherits. The snapshot travels down to make a chain
+ * of nmr invocations gate on one observation of the tree; a bypass, to cover the whole chain rather than only the
+ * command next to which it was typed; the verbosity, to make each process suppress the output of the command
+ * that it runs rather than of the subtree beneath it; and the run's identity, to mark the excerpts that a run
+ * records at every scope as one run's.
+ *
+ * The verbosity is written in both modes, so that a chain's loudness is decided once at the top rather than
+ * re-derived at every link from an environment that a caller may have set.
+ *
+ * Trailing arguments bypass the cache for the whole chain, as `--no-cache` does. `openGate` disables this
+ * invocation's own gate for them, but the steps below it are separate nmr invocations that do not receive any
+ * arguments of their own, and without the bypass a narrowed command would serve part of its work from a recorded
+ * pass.
+ *
+ * `NMR_DELEGATE` is set empty: a command that runs here runs its whole chain here, so that a step or a `-F`/`-R`
+ * child of a local run passes itself on neither to the host that the variable names nor to the user config's.
+ *
+ * The style written down is the resolved one and never `auto`: a child on a pipe renders as this process does
+ * rather than detecting plain on its own descriptor. It is the style to which stdout resolved: the verdicts and
+ * nearly every other line that a child prints go there.
+ */
+export declare function buildChildEnv(options: {
+    env: NodeJS.ProcessEnv;
+    format: ReportFormat;
+    passthrough: readonly string[];
+    runId: string;
+    shouldBypassCache: boolean;
+    shouldBypassLock: boolean;
+    snapshot: TreeSnapshot | undefined;
+    styles: StreamStyles;
+    verbosity: CommandVerbosity;
+}): NodeJS.ProcessEnv;
+/**
+ * Returns the variables of a child environment that the host's nmr receives: those that decide how it reports, whether
+ * it bypasses its cache, whether it writes debug notes, and which run it belongs to. The rest describe this machine,
+ * such as the tree snapshot and the lock token, or would disable the host's lock on the strength of a local
+ * workaround, as an inherited `NMR_NO_LOCK` would; the `--no-lock` flag still reaches the host as an argument.
+ */
+export declare function buildRemoteEnv(childEnv: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * Takes the machine lock for a heavy command that runs, or returns `undefined` for any other invocation. A delegated
+ * `--log` reads recordings and runs nothing. A `--no-lock` written after the command name is an argument to the
+ * command, so it is reported rather than read.
+ */
+export declare function takeMachineLock(invocation: Invocation): Promise<MachineLock | undefined>;

package/dist/esm/child-env.js

@@ -0,0 +1,59 @@
+import { DEBUG_ENV_VAR, encodeTreeSnapshot, NO_CACHE_ENV_VAR, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, } from "./check-cache.js";
+import { acquireMachineLock, formatMisplacedNoLockWarning, HEAVY_COMMANDS, LOCK_TOKEN_ENV_VAR, NO_LOCK_ENV_VAR, } from "./machine-lock.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) {
+    if (lock?.token !== undefined) {
+        return { ...env, [LOCK_TOKEN_ENV_VAR]: lock.token };
+    }
+    if (lock?.isChainUnlocked === true) {
+        return { ...env, [NO_LOCK_ENV_VAR]: '1' };
+    }
+    return env;
+}
+export function buildChildEnv(options) {
+    const { env, format, passthrough, runId, shouldBypassCache, shouldBypassLock, snapshot, styles, verbosity } = options;
+    const bypassesCache = shouldBypassCache || passthrough.length > 0;
+    return {
+        ...env,
+        [DELEGATE_ENV_VAR]: '',
+        ...(snapshot !== undefined && { [TREE_SNAPSHOT_ENV_VAR]: encodeTreeSnapshot(snapshot) }),
+        ...(bypassesCache && { [NO_CACHE_ENV_VAR]: '1' }),
+        ...(shouldBypassLock && { [NO_LOCK_ENV_VAR]: '1' }),
+        [COMMAND_VERBOSITY_ENV_VAR]: verbosity,
+        [OUTPUT_STYLE_ENV_VAR]: styles.stdout,
+        [REPORT_FORMAT_ENV_VAR]: format,
+        [RUN_ID_ENV_VAR]: runId,
+    };
+}
+export function buildRemoteEnv(childEnv) {
+    return Object.fromEntries(REMOTE_ENV_VARS.flatMap((name) => {
+        const value = childEnv[name];
+        return value === undefined ? [] : [[name, value]];
+    }));
+}
+export async function takeMachineLock(invocation) {
+    const { anchorDir, command, env, parsedArgs, stderr, styles } = invocation;
+    if (!HEAVY_COMMANDS.has(command) || parsedArgs.shouldPrintLog) {
+        return undefined;
+    }
+    if (parsedArgs.passthrough.includes('--no-lock')) {
+        stderr.write(`${formatMisplacedNoLockWarning(command, styles.stderr)}\n`);
+    }
+    return acquireMachineLock({
+        command,
+        dir: anchorDir,
+        env: parsedArgs.shouldBypassLock ? { ...env, [NO_LOCK_ENV_VAR]: '1' } : env,
+        stderr,
+    });
+}
+const REMOTE_ENV_VARS = [
+    COMMAND_VERBOSITY_ENV_VAR,
+    DEBUG_ENV_VAR,
+    NO_CACHE_ENV_VAR,
+    OUTPUT_STYLE_ENV_VAR,
+    REPORT_FORMAT_ENV_VAR,
+    RUN_ID_ENV_VAR,
+];

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

@@ -0,0 +1,55 @@
+import { type ChildProcess } from 'node:child_process';
+import type { Writable } from 'node:stream';
+import type { OutputChannels } from './output-channel.js';
+export interface RunCommandOptions {
+    /** The channel on which each of the child's output streams runs. */
+    channels: OutputChannels;
+    /** When true, suppresses output on success and writes captured output to stderr on failure. */
+    quiet?: boolean;
+    /** Stream that subprocess stdout flows to in non-quiet mode. Defaults to `process.stdout`. */
+    stdout?: Writable;
+    /** Stream that subprocess stderr flows to (and that quiet-mode failure output is written to). Defaults to `process.stderr`. */
+    stderr?: Writable;
+    /** Environment for the subprocess. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+export type RunCommandResult = CommandCompletion & {
+    /**
+     * Output retained while the command ran, elided in the middle when it overran the bound.
+     * `undefined` when the stream was handed to the child directly, or when capture stopped early
+     * and the retained copy would understate what the command produced.
+     */
+    stdout: Buffer | undefined;
+    stderr: Buffer | undefined;
+};
+/** What to hand `spawn`: a whole command line for a shell to parse, or a file and the arguments that it receives. */
+export interface SpawnSpec {
+    args: readonly string[];
+    file: string;
+    /** Whether the child reads nmr's own stdin or the null device. */
+    input: 'ignore' | 'inherit';
+    shouldUseShell: boolean;
+}
+/** A spawned child and a promise of how it ended. */
+export interface StartedCommand {
+    child: ChildProcess;
+    result: Promise<RunCommandResult>;
+}
+/** Returns the exit code that a shell reports for a death by the signal. */
+export declare function describeSignalExitCode(signal: NodeJS.Signals): number;
+/** Spawns one child on the caller's channels, returning the child and a promise of how it ended. */
+export declare function startSpawned({ args, file, input, shouldUseShell }: SpawnSpec, cwd: string | undefined, options: RunCommandOptions): StartedCommand;
+/** How a command ended, and the exit code that reports that ending to nmr's own caller. */
+type CommandCompletion = {
+    outcome: 'exited';
+    exitCode: number;
+} | {
+    outcome: 'signaled';
+    exitCode: number;
+    signal: NodeJS.Signals;
+} | {
+    outcome: 'spawn-failed';
+    exitCode: number;
+    error: Error;
+};
+export {};

package/dist/esm/child-process.js

@@ -0,0 +1,112 @@
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import process from 'node:process';
+import { reportError } from '@williamthorsen/nmr-core';
+import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
+const SIGNAL_EXIT_BASE = 128;
+const PIPE_DRAIN_GRACE_MS = 2_000;
+export function describeSignalExitCode(signal) {
+    return SIGNAL_EXIT_BASE + os.constants.signals[signal];
+}
+export function startSpawned({ args, file, input, shouldUseShell }, cwd, options) {
+    const quiet = options.quiet === true;
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    const env = options.env ?? process.env;
+    const child = spawn(file, args, {
+        shell: shouldUseShell,
+        stdio: [input, options.channels.stdout, options.channels.stderr],
+        cwd,
+        env,
+    });
+    return { child, result: collectResult(child, { quiet, stderr, stdout }) };
+}
+function awaitCompletion(child, stopReading) {
+    return new Promise((resolve) => {
+        let exitCompletion;
+        let graceTimer;
+        let isSettled = false;
+        function settle(completion) {
+            if (isSettled)
+                return;
+            isSettled = true;
+            if (graceTimer !== undefined)
+                clearTimeout(graceTimer);
+            resolve(completion);
+        }
+        child.on('error', (error) => {
+            settle({ outcome: 'spawn-failed', exitCode: 1, error });
+        });
+        child.on('exit', (code, signal) => {
+            const exitDescription = describeExit(code, signal);
+            exitCompletion = exitDescription;
+            graceTimer = setTimeout(() => {
+                stopReading();
+                settle(exitDescription);
+            }, PIPE_DRAIN_GRACE_MS);
+        });
+        child.on('close', () => {
+            settle(exitCompletion ?? { outcome: 'exited', exitCode: 1 });
+        });
+    });
+}
+function captureStream(source, destination) {
+    const retainedCopy = createBoundedBuffer();
+    let isComplete = true;
+    function stopReading() {
+        if (destination !== undefined)
+            source.unpipe(destination);
+        source.destroy();
+    }
+    function abandon() {
+        isComplete = false;
+        stopReading();
+    }
+    source.on('error', abandon);
+    if (destination !== undefined) {
+        destination.on('error', abandon);
+        source.pipe(destination, { end: false });
+    }
+    source.on('data', (chunk) => retainedCopy.append(chunk));
+    return {
+        readBuffer: () => (isComplete ? retainedCopy.readBuffer() : undefined),
+        detach: () => {
+            destination?.off('error', abandon);
+        },
+        stopReading,
+    };
+}
+async function collectResult(child, { quiet, stderr, stdout }) {
+    const stdoutCapture = child.stdout === null ? undefined : captureStream(child.stdout, quiet ? undefined : stdout);
+    const stderrCapture = child.stderr === null ? undefined : captureStream(child.stderr, quiet ? undefined : stderr);
+    const commandCompletion = await awaitCompletion(child, () => {
+        stdoutCapture?.stopReading();
+        stderrCapture?.stopReading();
+    });
+    stdoutCapture?.detach();
+    stderrCapture?.detach();
+    const result = {
+        ...commandCompletion,
+        stdout: stdoutCapture?.readBuffer(),
+        stderr: stderrCapture?.readBuffer(),
+    };
+    if (result.outcome === 'spawn-failed') {
+        reportError(result.error.message, stderr);
+        return result;
+    }
+    if (quiet && result.exitCode !== 0) {
+        writeBuffer(result.stdout, stderr);
+        writeBuffer(result.stderr, stderr);
+    }
+    return result;
+}
+function describeExit(code, signal) {
+    if (signal !== null) {
+        return { outcome: 'signaled', exitCode: describeSignalExitCode(signal), signal };
+    }
+    return { outcome: 'exited', exitCode: code ?? 1 };
+}
+function writeBuffer(buffer, destination) {
+    if (buffer !== undefined && buffer.length > 0)
+        destination.write(buffer);
+}

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

@@ -37,19 +37,3 @@ export declare function buildPackage(packageDir: string, options: BuildPackageOp
  * detected.
  */
 export declare function computeBuildHash(packageDir: string, files: string[], emitConfig: object, toolchain: BuildToolchain): Promise<string>;
-/**
- * Loads the compiler API on which every other function in this module relies, reporting a missing `typescript` peer
- * with the version that `nmr-compile` requires. `buildPackage` calls it first; a caller of another export calls it
- * beforehand.
- *
- * @internal
- */
-export declare function loadCompiler(loadTypeScript?: () => Promise<typeof TypeScript>): Promise<void>;
-/**
- * Resolves a package's full tsconfig `extends` chain, returning every config file in it (the leaf `tsconfig.json` and
- * each base that it transitively extends, up to the repo root) as paths relative to `packageDir`.
- * Emit is driven by the fully-resolved compiler options, so the base configs must be in the cache's hashed input
- * set; otherwise a change to a base config would not bust the cache and stale output could be released. The
- * relative paths give `computeBuildHash` a location-independent path string to fold into the digest.
- */
-export declare function resolveTsconfigChain(packageDir: string, configFileName?: string): string[];

package/dist/esm/commands/build.js

@@ -2,20 +2,15 @@ import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { readFile, rename, rm } from 'node:fs/promises';
 import path from 'node:path';
-import { formatGlyphLine, hasErrnoCode, readCacheEntry, STATUS_GLYPHS, writeCacheEntry, } from '@williamthorsen/nmr-core';
+import { formatGlyphLine, readCacheEntry, STATUS_GLYPHS, writeCacheEntry, } from '@williamthorsen/nmr-core';
 import { glob } from 'glob';
 import { NMR_GLYPHS } from "../glyphs.js";
 import { resolveConfigPath } from "../helpers/config-path.js";
 import { DEFAULT_ENTRY_GLOBS, DEFAULT_IGNORE_PATTERNS, DEFAULT_OUTDIR, hasExpectedBuildOutput, resolveBuildCachePath, resolveScratchDirs, resolveToolchainFingerprint, } from "./build-output.js";
+import { assertSupportedTypeScript, formatDiagnostics, getCompiler, loadCompiler } from "./compiler.js";
+import { isWithin, rewriteSpecifiers } from "./rewrite-specifiers.js";
+import { resolveTsconfigChain } from "./tsconfig-chain.js";
 const SOURCE_ROOT = 'src';
-const MINIMUM_TYPESCRIPT_MAJOR = 5;
-const MINIMUM_TYPESCRIPT_MINOR = 7;
-const UNSUPPORTED_TYPESCRIPT_MAJOR = 7;
-const SUPPORTED_TYPESCRIPT_RANGE = `>=${MINIMUM_TYPESCRIPT_MAJOR}.${MINIMUM_TYPESCRIPT_MINOR} <${UNSUPPORTED_TYPESCRIPT_MAJOR}`;
-const INSTALL_TYPESCRIPT_GUIDANCE = "Install a version in that range as the 'typescript' peer dependency.";
-const TS_EXTENSIONS = ['.ts', '.tsx'];
-const JS_EXTENSION = '.js';
-let ts;
 export async function buildPackage(packageDir, options) {
     await loadCompiler(options.loadTypeScript);
     assertSupportedTypeScript();
@@ -34,7 +29,7 @@ export async function buildPackage(packageDir, options) {
         ...resolveTsconfigChain(packageDir),
     ];
     const toolchain = {
-        compilerVersion: ts.version,
+        compilerVersion: getCompiler().version,
         fingerprint: await resolveToolchainFingerprint(packageDir),
     };
     const { changed, currentHash } = await detectBuildChanges(packageDir, [...entryPoints, ...dependencies], emitConfig, toolchain, cachePath, hasExpectedBuildOutput(packageDir, outdir, entryPoints), options.style);
@@ -60,40 +55,8 @@ export async function computeBuildHash(packageDir, files, emitConfig, toolchain)
     hash.update(toolchain.fingerprint);
     return hash.digest('hex');
 }
-export async function loadCompiler(loadTypeScript = importTypeScript) {
-    try {
-        ts = await loadTypeScript();
-    }
-    catch (error) {
-        if (hasErrnoCode(error, 'ERR_MODULE_NOT_FOUND') && error.message.includes("'typescript'")) {
-            throw new Error(`nmr-compile requires TypeScript ${SUPPORTED_TYPESCRIPT_RANGE}, but 'typescript' could not be resolved. ` +
-                INSTALL_TYPESCRIPT_GUIDANCE, { cause: error });
-        }
-        throw error;
-    }
-}
-export function resolveTsconfigChain(packageDir, configFileName = 'tsconfig.json') {
-    const resolvedChain = [];
-    const seen = new Set();
-    function walk(configPath) {
-        const normalizedPath = path.resolve(configPath);
-        if (seen.has(normalizedPath)) {
-            return;
-        }
-        seen.add(normalizedPath);
-        resolvedChain.push(normalizedPath);
-        const configFile = ts.readConfigFile(normalizedPath, (fileName) => ts.sys.readFile(fileName));
-        if (configFile.error) {
-            throw new Error(`nmr-compile: failed to read ${normalizedPath}.\n${formatDiagnostics([configFile.error])}`);
-        }
-        for (const entry of normalizeExtendsField(configFile.config)) {
-            walk(resolveExtendsTarget(entry, normalizedPath));
-        }
-    }
-    walk(path.resolve(packageDir, configFileName));
-    return resolvedChain.map((absolute) => path.relative(packageDir, absolute));
-}
 async function emitPackage(packageDir, entryPoints, outdir) {
+    const ts = getCompiler();
     const compilerOptions = synthesizeCompilerOptions(packageDir, outdir);
     const rootNames = entryPoints.map((entry) => path.resolve(packageDir, entry));
     const sourceRoot = path.resolve(packageDir, SOURCE_ROOT);
@@ -127,6 +90,7 @@ function assertEmitSucceeded(result) {
     }
 }
 function createCachingCompilerHost(compilerOptions) {
+    const ts = getCompiler();
     const host = ts.createCompilerHost(compilerOptions);
     const parsedFiles = new Map();
     const readSourceFile = host.getSourceFile.bind(host);
@@ -179,6 +143,7 @@ async function swapIntoPlace(emitDir, scratchDirs) {
     await discardScratchDirs(scratchDirs);
 }
 function synthesizeCompilerOptions(packageDir, outdir) {
+    const ts = getCompiler();
     const configPath = path.join(packageDir, 'tsconfig.json');
     const configFile = ts.readConfigFile(configPath, (fileName) => ts.sys.readFile(fileName));
     if (configFile.error) {
@@ -204,6 +169,7 @@ function synthesizeCompilerOptions(packageDir, outdir) {
     };
 }
 function writeStagedOutput(stagedFiles, emitDir, stagingDir) {
+    const ts = getCompiler();
     for (const [fileName, file] of stagedFiles) {
         if (!isWithin(emitDir, fileName)) {
             throw new Error(`nmr-compile: the compiler emitted ${fileName}, which is outside the output directory ${emitDir}. ` +
@@ -212,86 +178,6 @@ function writeStagedOutput(stagedFiles, emitDir, stagingDir) {
         ts.sys.writeFile(path.join(stagingDir, path.relative(emitDir, fileName)), file.text, file.writeByteOrderMark);
     }
 }
-function rewriteSpecifiers(outputFile, text, compilerOptions, sourceRoot) {
-    if (!isRewritableOutput(outputFile)) {
-        return text;
-    }
-    const sourceFile = ts.createSourceFile(outputFile, text, ts.ScriptTarget.Latest, false, resolveScriptKind(outputFile));
-    const aliasPrefixes = collectAliasPrefixes(compilerOptions);
-    const sourceContainingFile = mapOutputToSource(outputFile, compilerOptions, sourceRoot);
-    const edits = [];
-    visitModuleSpecifiers(sourceFile, (literal) => {
-        const replacement = resolveSpecifierReplacement(literal.text, sourceContainingFile, compilerOptions, sourceRoot, aliasPrefixes);
-        if (replacement === undefined) {
-            return;
-        }
-        const startOffset = literal.getStart(sourceFile);
-        const quote = text[startOffset] ?? '"';
-        edits.push({ startOffset, endOffset: literal.getEnd(), text: `${quote}${replacement}${quote}` });
-    });
-    if (edits.length === 0) {
-        return text;
-    }
-    const orderedEdits = edits.toSorted((a, b) => b.startOffset - a.startOffset);
-    let updatedText = text;
-    for (const edit of orderedEdits) {
-        updatedText = updatedText.slice(0, edit.startOffset) + edit.text + updatedText.slice(edit.endOffset);
-    }
-    return updatedText;
-}
-function resolveSpecifierReplacement(specifier, sourceContainingFile, compilerOptions, sourceRoot, aliasPrefixes) {
-    if (isRelativeSpecifier(specifier)) {
-        const rewrittenSpecifier = swapTypeScriptExtension(specifier);
-        return rewrittenSpecifier === specifier ? undefined : rewrittenSpecifier;
-    }
-    if (aliasPrefixes.every((prefix) => !(specifier === prefix || specifier.startsWith(prefix)))) {
-        return undefined;
-    }
-    const resolvedModule = ts.resolveModuleName(specifier, sourceContainingFile, compilerOptions, ts.sys).resolvedModule;
-    if (!resolvedModule) {
-        throw new Error(`nmr-compile: could not resolve aliased import '${specifier}' from ${sourceContainingFile}. ` +
-            `Verify the tsconfig 'paths' mapping and that the target file exists.`);
-    }
-    if (!isWithin(sourceRoot, resolvedModule.resolvedFileName)) {
-        const { paths: _paths, baseUrl: _baseUrl, rootDirs: _rootDirs, ...nodeResolutionOptions } = compilerOptions;
-        const bareResolvedModule = ts.resolveModuleName(specifier, sourceContainingFile, nodeResolutionOptions, ts.sys).resolvedModule;
-        if (bareResolvedModule) {
-            return undefined;
-        }
-        throw new Error(`nmr-compile: aliased import '${specifier}' from ${sourceContainingFile} resolves to ` +
-            `${resolvedModule.resolvedFileName}, outside the package source root ${sourceRoot}, and does not resolve ` +
-            `the way Node will at runtime, which ignores tsconfig 'paths', 'baseUrl', and 'rootDirs'. The ` +
-            `emitted specifier would fail at runtime; re-anchor the alias inside the package.`);
-    }
-    const relativeSpecifier = buildRelativeSpecifier(path.dirname(sourceContainingFile), resolvedModule.resolvedFileName);
-    return swapTypeScriptExtension(relativeSpecifier);
-}
-function visitModuleSpecifiers(sourceFile, visit) {
-    function walk(node) {
-        const specifier = getModuleSpecifier(node);
-        if (specifier !== undefined) {
-            visit(specifier);
-        }
-        ts.forEachChild(node, walk);
-    }
-    walk(sourceFile);
-}
-function getModuleSpecifier(node) {
-    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier !== undefined) {
-        return ts.isStringLiteralLike(node.moduleSpecifier) ? node.moduleSpecifier : undefined;
-    }
-    if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) {
-        return ts.isStringLiteralLike(node.moduleReference.expression) ? node.moduleReference.expression : undefined;
-    }
-    if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) {
-        return ts.isStringLiteralLike(node.argument.literal) ? node.argument.literal : undefined;
-    }
-    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
-        const [first] = node.arguments;
-        return first !== undefined && ts.isStringLiteralLike(first) ? first : undefined;
-    }
-    return undefined;
-}
 async function detectBuildChanges(packageDir, files, emitConfig, toolchain, cachePath, isOutputPresent, style) {
     const packageName = path.basename(packageDir);
     const previousHash = await readCacheEntry(cachePath);
@@ -307,100 +193,9 @@ async function detectBuildChanges(packageDir, files, emitConfig, toolchain, cach
     console.info(formatGlyphLine(NMR_GLYPHS, style, 'package', `${packageName}: Changes detected.`));
     return { changed: true, currentHash };
 }
-async function importTypeScript() {
-    return await import('typescript');
-}
-function assertSupportedTypeScript() {
-    const versionMajorMinor = ts.versionMajorMinor;
-    const version = ts.version;
-    const [majorPart, minorPart] = typeof versionMajorMinor === 'string' ? versionMajorMinor.split('.', 2) : [];
-    const major = majorPart === undefined ? 0 : Number(majorPart);
-    const minor = minorPart === undefined ? 0 : Number(minorPart);
-    const tooOld = major < MINIMUM_TYPESCRIPT_MAJOR || (major === MINIMUM_TYPESCRIPT_MAJOR && minor < MINIMUM_TYPESCRIPT_MINOR);
-    if (tooOld || major >= UNSUPPORTED_TYPESCRIPT_MAJOR) {
-        throw new Error(`nmr-compile requires TypeScript ${SUPPORTED_TYPESCRIPT_RANGE}, but found ` +
-            `${typeof version === 'string' ? version : 'a version without the compiler API'}. ${INSTALL_TYPESCRIPT_GUIDANCE}`);
-    }
-}
-function collectAliasPrefixes(compilerOptions) {
-    if (compilerOptions.paths === undefined) {
-        return [];
-    }
-    return Object.keys(compilerOptions.paths).map((pattern) => pattern.replace(/\*$/, ''));
-}
 function describeEmit(fileCount, outdir) {
     if (fileCount === 0) {
         return 'Did not emit any output.';
     }
     return `Compiled ${fileCount} files to ${outdir.replace(/\/+$/u, '')}.`;
 }
-function formatDiagnostics(diagnostics) {
-    return ts.formatDiagnosticsWithColorAndContext(diagnostics, {
-        getCurrentDirectory: () => process.cwd(),
-        getCanonicalFileName: (fileName) => fileName,
-        getNewLine: () => ts.sys.newLine,
-    });
-}
-function isRewritableOutput(file) {
-    return file.endsWith('.d.ts') || file.endsWith('.js');
-}
-function normalizeExtendsField(config) {
-    if (config === null || typeof config !== 'object' || !('extends' in config)) {
-        return [];
-    }
-    const extendsField = config.extends;
-    if (typeof extendsField === 'string') {
-        return [extendsField];
-    }
-    if (Array.isArray(extendsField)) {
-        return extendsField.filter((entry) => typeof entry === 'string');
-    }
-    return [];
-}
-function resolveExtendsTarget(extendsEntry, fromConfigPath) {
-    if (isRelativeSpecifier(extendsEntry) || path.isAbsolute(extendsEntry)) {
-        const base = path.resolve(path.dirname(fromConfigPath), extendsEntry);
-        if (ts.sys.fileExists(base)) {
-            return base;
-        }
-        const withJsonExtension = `${base}.json`;
-        if (ts.sys.fileExists(withJsonExtension)) {
-            return withJsonExtension;
-        }
-        throw new Error(`nmr-compile: ${fromConfigPath} extends '${extendsEntry}', which does not exist.`);
-    }
-    const resolvedPath = resolvePackageSpecifier(extendsEntry, fromConfigPath) ??
-        resolvePackageSpecifier(`${extendsEntry}/tsconfig.json`, fromConfigPath);
-    if (resolvedPath === undefined) {
-        throw new Error(`nmr-compile: ${fromConfigPath} extends '${extendsEntry}', which does not resolve to a file.`);
-    }
-    return resolvedPath;
-}
-function resolvePackageSpecifier(specifier, fromConfigPath) {
-    const { resolvedModule } = ts.resolveModuleName(specifier, fromConfigPath, { moduleResolution: ts.ModuleResolutionKind.NodeNext, resolveJsonModule: true }, ts.sys);
-    return resolvedModule?.resolvedFileName;
-}
-function isRelativeSpecifier(specifier) {
-    return specifier.startsWith('./') || specifier.startsWith('../');
-}
-function isWithin(parent, child) {
-    const relativePath = path.relative(parent, child);
-    return relativePath !== '' && !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
-}
-function mapOutputToSource(outputFile, compilerOptions, sourceRoot) {
-    const outDir = compilerOptions.outDir ?? path.dirname(outputFile);
-    const relativeFromOut = path.relative(outDir, outputFile);
-    const withoutExtension = relativeFromOut.replace(/\.d\.ts$|\.js$/, '');
-    return path.join(sourceRoot, `${withoutExtension}.ts`);
-}
-function buildRelativeSpecifier(fromDir, targetFile) {
-    const relativePath = path.relative(fromDir, targetFile).split(path.sep).join('/');
-    return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;
-}
-function resolveScriptKind(file) {
-    return file.endsWith('.d.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS;
-}
-function swapTypeScriptExtension(specifier) {
-    const extension = TS_EXTENSIONS.find((candidate) => specifier.endsWith(candidate));
-    return extension === undefined ? specifier : `${specifier.slice(0, -extension.length)}${JS_EXTENSION}`;
-}

package/dist/esm/commands/clean.js

@@ -1,13 +1,14 @@
 import { rm } from 'node:fs/promises';
 import path from 'node:path';
 import { formatGlyphLine } from '@williamthorsen/nmr-core';
-import { removeCheckCache } from "../check-cache.js";
+import { removeCheckCache } from "../check-cache-entries.js";
 import { loadRootConfig } from "../config.js";
 import { findContainingPackageDir } from "../context.js";
 import { NMR_GLYPHS } from "../glyphs.js";
 import { reportClosing } from "../helpers/reportClosing.js";
+import { resolveChannel } from "../output-channel.js";
 import { applyDevBin, buildWorkspaceRegistry, resolveScript } from "../resolver.js";
-import { resolveChannel, runCommand } from "../runner.js";
+import { runCommand } from "../runner.js";
 import { renderChain } from "../steps.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
 import { resolveBuildCachePath } from "./build-output.js";

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

@@ -0,0 +1,18 @@
+import type * as TypeScript from 'typescript';
+/**
+ * Asserts the resolved `typescript` peer is new enough for `rewriteRelativeImportExtensions` and old enough to
+ * include the compiler API.
+ */
+export declare function assertSupportedTypeScript(): void;
+/** Renders compiler diagnostics as colored text with source context. */
+export declare function formatDiagnostics(diagnostics: readonly TypeScript.Diagnostic[]): string;
+/** Returns the compiler API that `loadCompiler` loaded, throwing when it has not run. */
+export declare function getCompiler(): typeof TypeScript;
+/**
+ * Loads the compiler API on which every `nmr-compile` module relies, reporting a missing `typescript` peer with the
+ * version that `nmr-compile` requires. `buildPackage` calls it first; a caller of another compiler-dependent export
+ * calls it beforehand.
+ *
+ * @internal
+ */
+export declare function loadCompiler(loadTypeScript?: () => Promise<typeof TypeScript>): Promise<void>;