@williamthorsen/nmr 0.48.0 → 0.50.0

package/dist/esm/commands/compiler.js

@@ -0,0 +1,49 @@
+import { hasErrnoCode } from '@williamthorsen/nmr-core';
+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.";
+let ts;
+export function assertSupportedTypeScript() {
+    const compiler = getCompiler();
+    const versionMajorMinor = compiler.versionMajorMinor;
+    const version = compiler.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}`);
+    }
+}
+export function formatDiagnostics(diagnostics) {
+    const compiler = getCompiler();
+    return compiler.formatDiagnosticsWithColorAndContext(diagnostics, {
+        getCurrentDirectory: () => process.cwd(),
+        getCanonicalFileName: (fileName) => fileName,
+        getNewLine: () => compiler.sys.newLine,
+    });
+}
+export function getCompiler() {
+    if (ts === undefined) {
+        throw new Error('nmr-compile: the compiler is not loaded; call loadCompiler first.');
+    }
+    return ts;
+}
+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;
+    }
+}
+async function importTypeScript() {
+    return await import('typescript');
+}

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

@@ -1,27 +1,4 @@
 export type FormatMode = 'check' | 'write';
-export interface FormatTargets {
-    /** Listed paths that Prettier cannot be handed, such as symlinks and submodule gitlinks. */
-    excludedFiles: string[];
-    /** Paths relative to the working directory, as `git ls-files` emits them. */
-    files: string[];
-    /** Absolute paths to every `.prettierignore` governing the repository, root-most first. */
-    ignorePaths: string[];
-    /** The repository's top-level directory, as git reports it. */
-    repositoryRoot: string;
-    /** Listed paths that this process is denied access to, each with the errno code that its stat raised. */
-    unreadableFiles: UnreadableFile[];
-}
-export interface UnreadableFile {
-    file: string;
-    code: string;
-}
-export type ResolveTargetsResult = {
-    ok: true;
-    targets: FormatTargets;
-} | {
-    ok: false;
-    error: string;
-};
 /**
  * Formats or checks the files that git reports for `cwd`, and returns the exit code to report. A repository
  * without a Prettier config of its own is formatted with the house config. The run uses Prettier's content-keyed
@@ -32,22 +9,6 @@ export type ResolveTargetsResult = {
  * success over an empty selection.
  */
 export declare function runFmt(argv: string[], cwd?: string): Promise<number>;
-/**
- * Resolves what Prettier should format and which ignore files govern it, using git rather than Prettier's
- * own discovery. Prettier reads `.gitignore` and `.prettierignore` from the working directory only, so a
- * pattern in `packages/<pkg>/.gitignore` is invisible to a root-level run; git knows the whole hierarchy,
- * along with `.git/info/exclude` and `core.excludesFile`, which Prettier cannot read under any flag.
- *
- * Because file selection is anchored at `cwd` and ignore discovery at the repository root, scoping follows
- * `cwd` while the ignore rules applied to a given file are the same from every directory.
- *
- * `pathspecs` narrow the selection and are passed to git verbatim: They have git pathspec semantics rather
- * than shell glob semantics.
- *
- * A listed path that Prettier cannot be handed is set aside in `excludedFiles`, and one that this process is denied
- * access to in `unreadableFiles`; any other stat failure fails the resolution.
- */
-export declare function resolveFormatTargets(cwd: string, pathspecs?: string[]): ResolveTargetsResult;
 /** @internal */
 export interface RunPrettierOptions {
     cliPath: string;

package/dist/esm/commands/fmt.js

@@ -1,20 +1,17 @@
 import { Buffer } from 'node:buffer';
 import { spawnSync } from 'node:child_process';
-import { lstatSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
-import { hasErrnoCode, reportError } from '@williamthorsen/nmr-core';
+import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { isObject } from "../helpers/type-guards.js";
 import { prepareFmtCache } from "./fmt-cache.js";
-const IGNORE_FILENAME = '.prettierignore';
-const LIST_FILES_ARGS = ['ls-files', '-z', '--cached', '--others', '--exclude-standard'];
-const IGNORE_FILE_PATHSPEC = `*${IGNORE_FILENAME}`;
-const UNREADABLE_CODES = ['EACCES', 'EPERM'];
+import { resolveFormatTargets } from "./format-targets.js";
 const PRETTIER_PACKAGE = 'prettier';
-const DEFAULT_CONFIG_PATH = fileURLToPath(new URL(`../prettier-default-config${path.extname(fileURLToPath(import.meta.url))}`, import.meta.url));
+const DEFAULT_CONFIG_PATH = fileURLToPath(new URL(`../prettier-default.config${path.extname(fileURLToPath(import.meta.url))}`, import.meta.url));
 const ARGUMENT_BUDGET_BYTES = 100_000;
 const USAGE = 'Usage: nmr-fmt (--check | --write) [--no-cache] [pathspec...]';
 const MODE_ARGS = {
@@ -78,63 +75,6 @@ export async function runFmt(argv, cwd = process.cwd()) {
         cwd,
     });
 }
-export function resolveFormatTargets(cwd, pathspecs = []) {
-    const toplevel = runGit(['rev-parse', '--show-toplevel'], cwd);
-    if (!toplevel.ok)
-        return toplevel;
-    const repositoryRoot = toplevel.stdout.trim();
-    const listedFiles = runGit([...LIST_FILES_ARGS, '--', ...pathspecs], cwd);
-    if (!listedFiles.ok)
-        return listedFiles;
-    const ignoreFiles = runGit([...LIST_FILES_ARGS, '--', IGNORE_FILE_PATHSPEC], repositoryRoot);
-    if (!ignoreFiles.ok)
-        return ignoreFiles;
-    const excludedFiles = [];
-    const files = [];
-    const unreadableFiles = [];
-    const listedPaths = dedupe(splitNulSeparated(listedFiles.stdout));
-    for (const file of listedPaths) {
-        const status = classifyListedFile(cwd, file);
-        switch (status.kind) {
-            case 'excluded':
-                excludedFiles.push(file);
-                break;
-            case 'failed':
-                return { ok: false, error: status.error };
-            case 'formattable':
-                files.push(file);
-                break;
-            case 'unreadable':
-                unreadableFiles.push({ file, code: status.code });
-                break;
-        }
-    }
-    const discoveredIgnorePaths = splitNulSeparated(ignoreFiles.stdout)
-        .filter((file) => path.basename(file) === IGNORE_FILENAME)
-        .map((file) => path.resolve(repositoryRoot, file));
-    return {
-        ok: true,
-        targets: {
-            excludedFiles: excludedFiles.toSorted(),
-            files: files.toSorted(),
-            ignorePaths: dedupe([path.join(repositoryRoot, IGNORE_FILENAME), ...discoveredIgnorePaths]),
-            repositoryRoot,
-            unreadableFiles,
-        },
-    };
-}
-function classifyListedFile(cwd, file) {
-    try {
-        const stats = lstatSync(path.resolve(cwd, file), { throwIfNoEntry: false });
-        return { kind: stats?.isFile() === true ? 'formattable' : 'excluded' };
-    }
-    catch (error) {
-        const code = UNREADABLE_CODES.find((candidate) => hasErrnoCode(error, candidate));
-        if (code !== undefined)
-            return { kind: 'unreadable', code };
-        return { kind: 'failed', error: `could not stat ${file}: ${describeError(error)}` };
-    }
-}
 function parseFmtArgs(argv) {
     let mode;
     let shouldBypassCache = false;
@@ -248,20 +188,3 @@ function resolveFrom(parent, specifier) {
         return undefined;
     }
 }
-function runGit(args, cwd) {
-    const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
-    if (result.error) {
-        return { ok: false, error: result.error.message };
-    }
-    if (result.status !== 0) {
-        const stderr = result.stderr.trim();
-        return { ok: false, error: stderr || `\`git ${args.join(' ')}\` failed with exit code ${result.status}.` };
-    }
-    return { ok: true, stdout: result.stdout };
-}
-function splitNulSeparated(output) {
-    return output.split('\0').filter((entry) => entry !== '');
-}
-function dedupe(items) {
-    return [...new Set(items)];
-}

package/dist/esm/commands/format-targets.d.ts

@@ -0,0 +1,39 @@
+export interface FormatTargets {
+    /** Listed paths that Prettier cannot be handed, such as symlinks and submodule gitlinks. */
+    excludedFiles: string[];
+    /** Paths relative to the working directory, as `git ls-files` emits them. */
+    files: string[];
+    /** Absolute paths to every `.prettierignore` governing the repository, root-most first. */
+    ignorePaths: string[];
+    /** The repository's top-level directory, as git reports it. */
+    repositoryRoot: string;
+    /** Listed paths that this process is denied access to, each with the errno code that its stat raised. */
+    unreadableFiles: UnreadableFile[];
+}
+export interface UnreadableFile {
+    file: string;
+    code: string;
+}
+export type ResolveTargetsResult = {
+    ok: true;
+    targets: FormatTargets;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolves what Prettier should format and which ignore files govern it, using git rather than Prettier's
+ * own discovery. Prettier reads `.gitignore` and `.prettierignore` from the working directory only, so a
+ * pattern in `packages/<pkg>/.gitignore` is invisible to a root-level run; git knows the whole hierarchy,
+ * along with `.git/info/exclude` and `core.excludesFile`, which Prettier cannot read under any flag.
+ *
+ * Because file selection is anchored at `cwd` and ignore discovery at the repository root, scoping follows
+ * `cwd` while the ignore rules applied to a given file are the same from every directory.
+ *
+ * `pathspecs` narrow the selection and are passed to git verbatim: They have git pathspec semantics rather
+ * than shell glob semantics.
+ *
+ * A listed path that Prettier cannot be handed is set aside in `excludedFiles`, and one that this process is denied
+ * access to in `unreadableFiles`; any other stat failure fails the resolution.
+ */
+export declare function resolveFormatTargets(cwd: string, pathspecs?: string[]): ResolveTargetsResult;

package/dist/esm/commands/format-targets.js

@@ -0,0 +1,83 @@
+import { spawnSync } from 'node:child_process';
+import { lstatSync } from 'node:fs';
+import path from 'node:path';
+import { hasErrnoCode } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+const IGNORE_FILENAME = '.prettierignore';
+const LIST_FILES_ARGS = ['ls-files', '-z', '--cached', '--others', '--exclude-standard'];
+const IGNORE_FILE_PATHSPEC = `*${IGNORE_FILENAME}`;
+const UNREADABLE_CODES = ['EACCES', 'EPERM'];
+export function resolveFormatTargets(cwd, pathspecs = []) {
+    const toplevel = runGit(['rev-parse', '--show-toplevel'], cwd);
+    if (!toplevel.ok)
+        return toplevel;
+    const repositoryRoot = toplevel.stdout.trim();
+    const listedFiles = runGit([...LIST_FILES_ARGS, '--', ...pathspecs], cwd);
+    if (!listedFiles.ok)
+        return listedFiles;
+    const ignoreFiles = runGit([...LIST_FILES_ARGS, '--', IGNORE_FILE_PATHSPEC], repositoryRoot);
+    if (!ignoreFiles.ok)
+        return ignoreFiles;
+    const excludedFiles = [];
+    const files = [];
+    const unreadableFiles = [];
+    const listedPaths = dedupe(splitNulSeparated(listedFiles.stdout));
+    for (const file of listedPaths) {
+        const status = classifyListedFile(cwd, file);
+        switch (status.kind) {
+            case 'excluded':
+                excludedFiles.push(file);
+                break;
+            case 'failed':
+                return { ok: false, error: status.error };
+            case 'formattable':
+                files.push(file);
+                break;
+            case 'unreadable':
+                unreadableFiles.push({ file, code: status.code });
+                break;
+        }
+    }
+    const discoveredIgnorePaths = splitNulSeparated(ignoreFiles.stdout)
+        .filter((file) => path.basename(file) === IGNORE_FILENAME)
+        .map((file) => path.resolve(repositoryRoot, file));
+    return {
+        ok: true,
+        targets: {
+            excludedFiles: excludedFiles.toSorted(),
+            files: files.toSorted(),
+            ignorePaths: dedupe([path.join(repositoryRoot, IGNORE_FILENAME), ...discoveredIgnorePaths]),
+            repositoryRoot,
+            unreadableFiles,
+        },
+    };
+}
+function classifyListedFile(cwd, file) {
+    try {
+        const stats = lstatSync(path.resolve(cwd, file), { throwIfNoEntry: false });
+        return { kind: stats?.isFile() === true ? 'formattable' : 'excluded' };
+    }
+    catch (error) {
+        const code = UNREADABLE_CODES.find((candidate) => hasErrnoCode(error, candidate));
+        if (code !== undefined)
+            return { kind: 'unreadable', code };
+        return { kind: 'failed', error: `could not stat ${file}: ${describeError(error)}` };
+    }
+}
+function runGit(args, cwd) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+    if (result.error) {
+        return { ok: false, error: result.error.message };
+    }
+    if (result.status !== 0) {
+        const stderr = result.stderr.trim();
+        return { ok: false, error: stderr || `\`git ${args.join(' ')}\` failed with exit code ${result.status}.` };
+    }
+    return { ok: true, stdout: result.stdout };
+}
+function splitNulSeparated(output) {
+    return output.split('\0').filter((entry) => entry !== '');
+}
+function dedupe(items) {
+    return [...new Set(items)];
+}

package/dist/esm/commands/rewrite-specifiers.d.ts

@@ -0,0 +1,17 @@
+import type * as TypeScript from 'typescript';
+/** Reports whether a specifier starts with `./` or `../`. */
+export declare function isRelativeSpecifier(specifier: string): boolean;
+/** Reports whether `child` lies strictly inside `parent`. */
+export declare function isWithin(parent: string, child: string): boolean;
+/**
+ * Rewrites module specifiers in a single emitted `.js` or `.d.ts` file's text: relative imports ending
+ * in a TypeScript extension become their `.js` equivalent, and tsconfig `paths` aliases resolve to
+ * runnable relative `.js` specifiers. Parsing the text means only real import/export specifiers are
+ * touched -- text inside strings and comments is never altered. Returns the text unchanged when nothing
+ * needs rewriting.
+ *
+ * `outputFile` names where the emit will be published, not where the text is now: `mapOutputToSource`
+ * reconstructs the originating source file by swapping the `outDir` prefix, and aliases resolve from
+ * that source location. A staging path here would resolve them from the wrong directory.
+ */
+export declare function rewriteSpecifiers(outputFile: string, text: string, compilerOptions: TypeScript.CompilerOptions, sourceRoot: string): string;

package/dist/esm/commands/rewrite-specifiers.js

@@ -0,0 +1,122 @@
+import path from 'node:path';
+import { getCompiler } from "./compiler.js";
+const TS_EXTENSIONS = ['.ts', '.tsx'];
+const JS_EXTENSION = '.js';
+export function isRelativeSpecifier(specifier) {
+    return specifier.startsWith('./') || specifier.startsWith('../');
+}
+export function isWithin(parent, child) {
+    const relativePath = path.relative(parent, child);
+    return relativePath !== '' && !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
+}
+export function rewriteSpecifiers(outputFile, text, compilerOptions, sourceRoot) {
+    if (!isRewritableOutput(outputFile)) {
+        return text;
+    }
+    const ts = getCompiler();
+    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 buildRelativeSpecifier(fromDir, targetFile) {
+    const relativePath = path.relative(fromDir, targetFile).split(path.sep).join('/');
+    return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;
+}
+function collectAliasPrefixes(compilerOptions) {
+    if (compilerOptions.paths === undefined) {
+        return [];
+    }
+    return Object.keys(compilerOptions.paths).map((pattern) => pattern.replace(/\*$/, ''));
+}
+function getModuleSpecifier(node) {
+    const ts = getCompiler();
+    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;
+}
+function isRewritableOutput(file) {
+    return file.endsWith('.d.ts') || file.endsWith('.js');
+}
+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 resolveScriptKind(file) {
+    const ts = getCompiler();
+    return file.endsWith('.d.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS;
+}
+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 ts = getCompiler();
+    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 swapTypeScriptExtension(specifier) {
+    const extension = TS_EXTENSIONS.find((candidate) => specifier.endsWith(candidate));
+    return extension === undefined ? specifier : `${specifier.slice(0, -extension.length)}${JS_EXTENSION}`;
+}
+function visitModuleSpecifiers(sourceFile, visit) {
+    const ts = getCompiler();
+    function walk(node) {
+        const specifier = getModuleSpecifier(node);
+        if (specifier !== undefined) {
+            visit(specifier);
+        }
+        ts.forEachChild(node, walk);
+    }
+    walk(sourceFile);
+}

package/dist/esm/commands/tsconfig-chain.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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/tsconfig-chain.js

@@ -0,0 +1,63 @@
+import path from 'node:path';
+import { formatDiagnostics, getCompiler } from "./compiler.js";
+import { isRelativeSpecifier } from "./rewrite-specifiers.js";
+export function resolveTsconfigChain(packageDir, configFileName = 'tsconfig.json') {
+    const ts = getCompiler();
+    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));
+}
+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) {
+    const ts = getCompiler();
+    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 ts = getCompiler();
+    const { resolvedModule } = ts.resolveModuleName(specifier, fromConfigPath, { moduleResolution: ts.ModuleResolutionKind.NodeNext, resolveJsonModule: true }, ts.sys);
+    return resolvedModule?.resolvedFileName;
+}

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

@@ -0,0 +1,17 @@
+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;

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

@@ -0,0 +1,63 @@
+import { findClosestName } from "./helpers/findClosestName.js";
+import { isHookName } from "./helpers/hook-name.js";
+import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "./resolver.js";
+import { UserError } from "./UserError.js";
+import { getWorkspacePackageDirs, isMonorepoRoot } from "./workspace.js";
+export function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
+    const { checkCache } = config;
+    if (checkCache === undefined || !isMonorepoRoot(baseDir)) {
+        return;
+    }
+    const fields = ['excludeCommands', 'extraCommands'];
+    const entries = fields.flatMap((field) => (checkCache[field] ?? []).map((command) => ({ command, field })));
+    const hook = entries.find(({ command }) => isHookName(command));
+    if (hook !== undefined) {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.${hook.field}\` names the hook \`${hook.command}\`, ` +
+            'which is never gated on its own: It runs as part of the chain of the command that it wraps.');
+    }
+    const registeredNames = new Set([
+        ...Object.keys(buildRootRegistry(config, baseDir)),
+        ...Object.keys(buildWorkspaceRegistry(config)),
+    ]);
+    const missingEntries = entries.filter(({ command }) => !registeredNames.has(command));
+    if (missingEntries.length === 0) {
+        return;
+    }
+    const declaredNames = readDeclaredScriptNames(baseDir);
+    const unresolvableEntry = missingEntries.find(({ command }) => !declaredNames.has(command));
+    if (unresolvableEntry === undefined) {
+        return;
+    }
+    const closestName = findClosestName(unresolvableEntry.command, [...registeredNames, ...declaredNames]);
+    throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.${unresolvableEntry.field}\` does not name any command: ` +
+        `\`${unresolvableEntry.command}\`.${closestName === undefined ? '' : ` Did you mean \`${closestName}\`?`}`);
+}
+function readDeclaredScriptNames(monorepoRoot) {
+    let packageDirs;
+    try {
+        packageDirs = getWorkspacePackageDirs(monorepoRoot);
+    }
+    catch {
+        packageDirs = [];
+    }
+    const names = new Set();
+    const dirs = [monorepoRoot, ...packageDirs];
+    for (const dir of dirs) {
+        const scripts = readPackageScripts(dir);
+        for (const name of Object.keys(scripts)) {
+            names.add(name);
+        }
+    }
+    return names;
+}
+function readPackageScripts(packageDir) {
+    try {
+        return readPackageJsonScripts(packageDir) ?? {};
+    }
+    catch (error) {
+        if (error instanceof UserError) {
+            return {};
+        }
+        throw error;
+    }
+}

package/dist/esm/config-validation.d.ts

@@ -0,0 +1,20 @@
+import type { NmrConfig } from './types.js';
+/**
+ * The keys that each tier honors, and where the other tier's belong. Every recognized key belongs to exactly one
+ * tier, and `RECOGNIZED_KEYS` is their union.
+ */
+export declare const CONFIG_TIERS: Record<'root' | 'workspace', ConfigTier>;
+export interface ConfigTier {
+    /** Names the tier in an error message. */
+    label: string;
+    honoredKeys: string[];
+    /** Names where a key that this tier does not honor belongs. */
+    elsewhere: string;
+}
+/**
+ * Throws on any key outside the recognized set, naming the offenders and the file. An unrecognized key is a
+ * typo or a stale spelling, and the setting that it appears to make is one that nothing reads.
+ */
+export declare function assertRecognizedKeys(value: object, recognizedKeys: string[], configPath: string, prefix?: string): void;
+/** Validates that a loaded value conforms to the expected `NmrConfig` shape. */
+export declare function validateConfig(value: unknown, configPath: string, baseDir: string): NmrConfig;