@williamthorsen/nmr 0.38.0 → 0.40.0

package/dist/esm/commands/fmt.js

@@ -18,21 +18,21 @@ const MODE_ARGS = {
     write: ['--list-different', '--write'],
 };
 export function runFmt(argv, cwd = process.cwd()) {
-    const parsed = parseFmtArgs(argv);
-    if (!parsed.ok) {
-        reportError(`nmr-fmt: ${parsed.error}`);
+    const parsedArgs = parseFmtArgs(argv);
+    if (!parsedArgs.ok) {
+        reportError(`nmr-fmt: ${parsedArgs.error}`);
         process.stderr.write(`${USAGE}\n`);
         return 1;
     }
-    const resolved = resolveFormatTargets(cwd, parsed.pathspecs);
-    if (!resolved.ok) {
-        reportError(`nmr-fmt: ${resolved.error}`);
+    const resolvedTargets = resolveFormatTargets(cwd, parsedArgs.pathspecs);
+    if (!resolvedTargets.ok) {
+        reportError(`nmr-fmt: ${resolvedTargets.error}`);
         return 1;
     }
-    const { files, ignorePaths } = resolved.targets;
+    const { files, ignorePaths } = resolvedTargets.targets;
     if (files.length === 0) {
-        if (parsed.pathspecs.length > 0) {
-            reportError(`nmr-fmt: no formattable files matched: ${parsed.pathspecs.join(', ')}`);
+        if (parsedArgs.pathspecs.length > 0) {
+            reportError(`nmr-fmt: the pathspecs did not match any formattable file: ${parsedArgs.pathspecs.join(', ')}`);
             return 1;
         }
         return 0;
@@ -42,29 +42,29 @@ export function runFmt(argv, cwd = process.cwd()) {
         reportError(`nmr-fmt: ${cli.error}`);
         return 1;
     }
-    return runPrettier({ cliPath: cli.cliPath, mode: parsed.mode, files, ignorePaths, cwd });
+    return runPrettier({ cliPath: cli.cliPath, mode: parsedArgs.mode, files, ignorePaths, 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 listed = runGit([...LIST_FILES_ARGS, '--', ...pathspecs], cwd);
-    if (!listed.ok)
-        return listed;
+    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 discovered = splitNulSeparated(ignoreFiles.stdout)
+    const discoveredIgnorePaths = splitNulSeparated(ignoreFiles.stdout)
         .filter((file) => path.basename(file) === IGNORE_FILENAME)
         .map((file) => path.resolve(repositoryRoot, file));
     return {
         ok: true,
         targets: {
-            files: dedupe(splitNulSeparated(listed.stdout))
+            files: dedupe(splitNulSeparated(listedFiles.stdout))
                 .filter((file) => isFormattableFile(cwd, file))
                 .toSorted(),
-            ignorePaths: dedupe([path.join(repositoryRoot, IGNORE_FILENAME), ...discovered]),
+            ignorePaths: dedupe([path.join(repositoryRoot, IGNORE_FILENAME), ...discoveredIgnorePaths]),
         },
     };
 }
@@ -76,11 +76,11 @@ function parseFmtArgs(argv) {
     const pathspecs = [];
     for (const arg of argv) {
         if (arg === '--check' || arg === '--write') {
-            const requested = arg === '--check' ? 'check' : 'write';
-            if (mode !== undefined && mode !== requested) {
+            const requestedMode = arg === '--check' ? 'check' : 'write';
+            if (mode !== undefined && mode !== requestedMode) {
                 return { ok: false, error: 'Pass --check or --write, not both.' };
             }
-            mode = requested;
+            mode = requestedMode;
             continue;
         }
         if (arg.startsWith('-')) {
@@ -94,7 +94,7 @@ function parseFmtArgs(argv) {
     return { ok: true, mode, pathspecs };
 }
 function resolvePrettierCli() {
-    const missing = {
+    const missingResult = {
         ok: false,
         error: `\`${PRETTIER_PACKAGE}\` (${PRETTIER_RANGE}) could not be resolved. Install it in this repository.`,
     };
@@ -103,14 +103,14 @@ function resolvePrettierCli() {
         manifestPath = createRequire(import.meta.url).resolve(`${PRETTIER_PACKAGE}/package.json`);
     }
     catch {
-        return missing;
+        return missingResult;
     }
     const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
     if (!isObject(manifest))
-        return missing;
+        return missingResult;
     const bin = isObject(manifest['bin']) ? manifest['bin'][PRETTIER_PACKAGE] : manifest['bin'];
     if (typeof bin !== 'string')
-        return missing;
+        return missingResult;
     return { ok: true, cliPath: path.resolve(path.dirname(manifestPath), bin) };
 }
 export function runPrettier(options) {
@@ -121,7 +121,7 @@ export function runPrettier(options) {
         ...ignorePaths.flatMap((ignorePath) => ['--ignore-path', ignorePath]),
         ...MODE_ARGS[mode],
     ];
-    let firstFailure = 0;
+    let firstFailureStatus = 0;
     for (const batch of batchWithinBudget(files, budgetBytes)) {
         const result = spawnSync(process.execPath, [...prettierArgs, ...batch], { cwd, stdio: 'inherit' });
         if (result.error) {
@@ -129,25 +129,25 @@ export function runPrettier(options) {
             return 1;
         }
         const status = result.status ?? 1;
-        if (status !== 0 && firstFailure === 0) {
-            firstFailure = status;
+        if (status !== 0 && firstFailureStatus === 0) {
+            firstFailureStatus = status;
         }
     }
-    return firstFailure;
+    return firstFailureStatus;
 }
-function batchWithinBudget(files, budget) {
+function batchWithinBudget(files, budgetBytes) {
     const batches = [];
     let batch = [];
-    let size = 0;
+    let sizeBytes = 0;
     for (const file of files) {
-        const cost = Buffer.byteLength(file) + 1;
-        if (batch.length > 0 && size + cost > budget) {
+        const costBytes = Buffer.byteLength(file) + 1;
+        if (batch.length > 0 && sizeBytes + costBytes > budgetBytes) {
             batches.push(batch);
             batch = [];
-            size = 0;
+            sizeBytes = 0;
         }
         batch.push(file);
-        size += cost;
+        sizeBytes += costBytes;
     }
     if (batch.length > 0)
         batches.push(batch);

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

@@ -1,12 +1,10 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 /**
- * Reports the catalogued dependencies a package-scoped upgrade pass cannot see.
+ * Reports the catalogued dependencies that a package-scoped upgrade pass does not read.
  *
- * The upgrade tool reads `pnpm-workspace.yaml` only when it sits at the working directory, so a pass run
- * inside a package drops every dependency a catalog declares -- and a package whose dependencies are all
- * catalogued reports itself up to date. Naming them, and the root a covering pass runs from, is what keeps
- * that from reading as a clean bill of health.
- *
- * Runs ahead of the report produced by the workspace `upgrade` script.
+ * The upgrade tool reads `pnpm-workspace.yaml` only when the file is in the working directory, so a pass run
+ * inside a package drops every dependency declared by a catalog -- and the tool reports a package whose
+ * dependencies are all catalogued as up to date. This report names them, and the root from which a covering
+ * pass runs, to keep the reader from taking that result to mean that every dependency is up to date.
  */
 export declare function reportCatalog(cwd: string, style: OutputStyle): void;

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

@@ -15,7 +15,7 @@ export function reportCatalog(cwd, style) {
     if (dependencies.length === 0) {
         return;
     }
-    console.warn(formatGlyphLine(NMR_GLYPHS, style, 'catalog', 'WARN: A package-scoped upgrade does not read the catalogs these come from:'));
+    console.warn(formatGlyphLine(NMR_GLYPHS, style, 'catalog', 'WARN: A package-scoped upgrade does not read the catalogs from which these come:'));
     for (const { name, specifier } of dependencies) {
         console.warn(`- ${name} → ${specifier}`);
     }
@@ -27,15 +27,17 @@ function describeCatalog(count, monorepoRoot) {
     return `${subject} unread. Run \`nmr upgrade\` from ${monorepoRoot} to include ${object}.`;
 }
 function findCataloguedDependencies(packageDir) {
-    const pkg = readPackageJson(packageDir);
-    const found = new Map();
+    const packageJson = readPackageJson(packageDir);
+    const foundDependencies = new Map();
     for (const field of DEPENDENCY_FIELDS) {
-        const declared = Object.entries(pkg[field] ?? {});
-        for (const [name, specifier] of declared) {
-            if (specifier.startsWith(CATALOG_PROTOCOL) && !found.has(name)) {
-                found.set(name, specifier);
+        const declaredEntries = Object.entries(packageJson[field] ?? {});
+        for (const [name, specifier] of declaredEntries) {
+            if (specifier.startsWith(CATALOG_PROTOCOL) && !foundDependencies.has(name)) {
+                foundDependencies.set(name, specifier);
             }
         }
     }
-    return [...found].map(([name, specifier]) => ({ name, specifier })).toSorted((a, b) => a.name.localeCompare(b.name));
+    return [...foundDependencies]
+        .map(([name, specifier]) => ({ name, specifier }))
+        .toSorted((a, b) => a.name.localeCompare(b.name));
 }

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

@@ -2,7 +2,5 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
 /**
  * Reports the pnpm dependency overrides declared in the monorepo root's `pnpm-workspace.yaml`, and rejects a
  * `pnpm.overrides` block left behind in the root `package.json`.
- *
- * Runs ahead of the report produced by the root `upgrade` script.
  */
 export declare function reportOverrides(monorepoRoot: string, style: OutputStyle): void;

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

@@ -5,13 +5,13 @@ import { reportClosing } from "../helpers/reportClosing.js";
 import { UserError } from "../UserError.js";
 import { readWorkspaceOverrides } from "../workspace.js";
 export function reportOverrides(monorepoRoot, style) {
-    const declared = listEntries(readWorkspaceOverrides(monorepoRoot));
-    if (declared.length > 0) {
+    const declaredOverrides = listEntries(readWorkspaceOverrides(monorepoRoot));
+    if (declaredOverrides.length > 0) {
         console.warn(formatGlyphLine(NMR_GLYPHS, style, 'overrides', 'WARN: pnpm overrides are active:'));
-        for (const [name, version] of declared) {
+        for (const [name, version] of declaredOverrides) {
             console.warn(`- ${name} → ${version}`);
         }
-        reportClosing(formatGlyphLine(NMR_GLYPHS, style, 'overrides', describeOverrides(declared.length)), console.warn);
+        reportClosing(formatGlyphLine(NMR_GLYPHS, style, 'overrides', describeOverrides(declaredOverrides.length)), console.warn);
     }
     rejectLegacyOverrides(monorepoRoot);
 }
@@ -24,13 +24,13 @@ function listEntries(overrides) {
     return Object.entries(overrides ?? {}).toSorted(([a], [b]) => a.localeCompare(b));
 }
 function rejectLegacyOverrides(monorepoRoot) {
-    const legacy = listEntries(getPnpmOverrides(readPackageJson(monorepoRoot)));
-    if (legacy.length === 0) {
+    const legacyOverrides = listEntries(getPnpmOverrides(readPackageJson(monorepoRoot)));
+    if (legacyOverrides.length === 0) {
         return;
     }
     throw new UserError([
-        'pnpm 11 reads no `pnpm.overrides` from package.json, so these pin nothing while an upgrade run with `--write` goes on rewriting them:',
-        ...legacy.map(([name, version]) => `- ${name} → ${String(version)}`),
+        'pnpm 11 does not read `pnpm.overrides` from package.json, so these pin nothing while an upgrade run with `--write` goes on rewriting them:',
+        ...legacyOverrides.map(([name, version]) => `- ${name} → ${String(version)}`),
         'Move them to the `overrides` block in pnpm-workspace.yaml, quoting each version, or run `pnpx codemod run pnpm-v10-to-v11`.',
     ].join('\n'));
 }

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

@@ -15,15 +15,16 @@ export interface RunTazeOptions {
  * Runs taze from nmr's own dependency tree, forwarding `args`, and returns its exit code.
  *
  * Consumers depend on nmr, not on taze, so taze is transitive and its bin is absent from the consumer's
- * root `node_modules/.bin`. This launcher is what bridges that gap: pnpm links nmr's own bins into the
- * consumer root, and nmr resolves taze from the tree it does control.
+ * root `node_modules/.bin`. This launcher runs taze without that bin: pnpm links nmr's own bins into the
+ * consumer root, and nmr resolves taze from the tree that it does control.
  *
- * A request timeout is the one argument added, and only where `args` carries none. Neither other site can hold
- * it: an invocation's trailing arguments are appended to the resolved command string, so the same flag in the
- * `upgrade` script would be doubled by `nmr upgrade --request-timeout ...`, and taze's parser collects the pair
- * into an array it reads as a near-zero deadline; a `taze.config.ts` setting lands in the object taze's own CLI
- * defaults overwrite. Every other argument is forwarded untouched, so invocation policy (`--recursive`) stays in
- * the script registry, visible in `nmr` help output and overridable per repo, and upgrade policy in `taze.ts`.
+ * A request timeout is the one argument added, and only when `args` does not set one. Neither other site can
+ * declare it: Because an invocation's trailing arguments are appended to the resolved command string, the same
+ * flag in the `upgrade` script would be doubled by `nmr upgrade --request-timeout ...`, and taze's parser
+ * collects the pair into an array that it reads as a near-zero deadline; a `taze.config.ts` setting goes into
+ * the object that taze's own CLI defaults overwrite. Because every other argument is forwarded untouched,
+ * invocation policy (`--recursive`) stays in the script registry, visible in `nmr` help output and overridable
+ * per repo, and upgrade policy stays in `taze.ts`.
  */
 export declare function runTaze(args: string[], options?: RunTazeOptions): number;
 /** Resolves the absolute path of taze's CLI entry from nmr's own dependency tree. */

package/dist/esm/config.d.ts

@@ -9,15 +9,15 @@ export declare function loadConfig(baseDir: string): Promise<NmrConfig>;
  * Loads the monorepo-root `.config/nmr.config.ts`, the tier that feeds script resolution and `devBin`.
  * Returns an empty config if the file doesn't exist.
  *
- * Throws on a recognized key this tier does not honor. `build` governs one package's compile, which reads the
+ * Throws on a recognized key that this tier does not honor. `build` governs one package's compile, which reads the
  * package's own config alone, so a `build` accepted here would apply its patterns nowhere.
  */
 export declare function loadRootConfig(monorepoRoot: string): Promise<NmrConfig>;
 /**
- * Loads a single package's `.config/nmr.config.ts`, the tier `nmr-compile` reads from its working directory.
- * Returns an empty config if the file doesn't exist.
+ * Loads a single package's `.config/nmr.config.ts`, the tier that `nmr-compile` reads from its working
+ * directory. Returns an empty config if the file doesn't exist.
  *
- * Throws on a recognized key this tier does not honor. Dropping one would leave a package building on
- * settings its own config file appears to change, which nothing in the build's output would reveal.
+ * Throws on a recognized key that this tier does not honor. Dropping one would leave a package building on
+ * settings that its own config file appears to change, which nothing in the build's output would reveal.
  */
 export declare function loadWorkspaceConfig(packageDir: string): Promise<NmrConfig>;

package/dist/esm/config.js

@@ -79,7 +79,7 @@ function assertValidElements(scripts, fieldName, configPath) {
             const token = findUnexpressibleToken(element);
             if (token === undefined)
                 continue;
-            throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}.${command}\` element \`${element}\` carries ` +
+            throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}.${command}\` element \`${element}\` contains ` +
                 `\`${token}\`, which is neither a command name nor an nmr flag. Name it as a script of its own and ` +
                 `reference that name here.`);
         }
@@ -113,12 +113,12 @@ function validateCheckCacheField(value, configPath) {
     }
     assertRecognizedKeys(checkCache, RECOGNIZED_CHECK_CACHE_KEYS, configPath, 'checkCache.');
     const config = {};
-    const enabled = checkCache['enabled'];
-    if (enabled !== undefined) {
-        if (typeof enabled !== 'boolean') {
+    const enabledValue = checkCache['enabled'];
+    if (enabledValue !== undefined) {
+        if (typeof enabledValue !== 'boolean') {
             throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.enabled\` must be a boolean`);
         }
-        config.enabled = enabled;
+        config.enabled = enabledValue;
     }
     for (const field of ['excludeCommands', 'extraCommands']) {
         const commands = checkCache[field];
@@ -142,24 +142,24 @@ function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
     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 it wraps.');
+            'which is never gated on its own: It runs as part of the chain of the command that it wraps.');
     }
-    const registered = new Set([
+    const registeredNames = new Set([
         ...Object.keys(buildRootRegistry(config)),
         ...Object.keys(buildWorkspaceRegistry(config)),
     ]);
-    const missing = entries.filter(({ command }) => !registered.has(command));
-    if (missing.length === 0) {
+    const missingEntries = entries.filter(({ command }) => !registeredNames.has(command));
+    if (missingEntries.length === 0) {
         return;
     }
-    const declared = readDeclaredScriptNames(baseDir);
-    const unresolvable = missing.find(({ command }) => !declared.has(command));
-    if (unresolvable === undefined) {
+    const declaredNames = readDeclaredScriptNames(baseDir);
+    const unresolvableEntry = missingEntries.find(({ command }) => !declaredNames.has(command));
+    if (unresolvableEntry === undefined) {
         return;
     }
-    const closest = findClosestName(unresolvable.command, [...registered, ...declared]);
-    throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.${unresolvable.field}\` names no command: ` +
-        `\`${unresolvable.command}\`.${closest === undefined ? '' : ` Did you mean \`${closest}\`?`}`);
+    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;
@@ -203,8 +203,8 @@ function validateOutputField(value, configPath) {
     const commandVerbosity = output['commandVerbosity'];
     if (commandVerbosity !== undefined) {
         if (typeof commandVerbosity !== 'string' || !isCommandVerbosity(commandVerbosity)) {
-            const rendered = typeof commandVerbosity === 'string' ? commandVerbosity : JSON.stringify(commandVerbosity);
-            throw new UserError(`Invalid nmr config at ${configPath}: ${formatVerbosityRejection('`output.commandVerbosity`', rendered)}`);
+            const renderedValue = typeof commandVerbosity === 'string' ? commandVerbosity : JSON.stringify(commandVerbosity);
+            throw new UserError(`Invalid nmr config at ${configPath}: ${formatVerbosityRejection('`output.commandVerbosity`', renderedValue)}`);
         }
         config.commandVerbosity = commandVerbosity;
     }
@@ -258,9 +258,9 @@ export async function loadConfig(baseDir) {
     if (!existsSync(configPath)) {
         return {};
     }
-    const imported = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
-    const loaded = isObject(imported) ? imported['default'] : undefined;
-    return validateConfig(loaded, configPath, baseDir);
+    const importedModule = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
+    const loadedConfig = isObject(importedModule) ? importedModule['default'] : undefined;
+    return validateConfig(loadedConfig, configPath, baseDir);
 }
 export async function loadRootConfig(monorepoRoot) {
     const config = await loadConfig(monorepoRoot);
@@ -281,20 +281,20 @@ function assertNoRetiredKeys(value, retiredKeys, configPath, prefix) {
     }
 }
 function assertRecognizedKeys(value, recognizedKeys, configPath, prefix = '') {
-    const unrecognized = Object.keys(value).filter((key) => !recognizedKeys.includes(key));
-    if (unrecognized.length === 0) {
+    const unrecognizedKeys = Object.keys(value).filter((key) => !recognizedKeys.includes(key));
+    if (unrecognizedKeys.length === 0) {
         return;
     }
-    throw new UserError(`Invalid nmr config at ${configPath}: unrecognized ${unrecognized.length === 1 ? 'key' : 'keys'} ` +
-        `${formatKeyList(unrecognized, prefix)}. Recognized: ${formatKeyList(recognizedKeys, prefix)}.`);
+    throw new UserError(`Invalid nmr config at ${configPath}: unrecognized ${unrecognizedKeys.length === 1 ? 'key' : 'keys'} ` +
+        `${formatKeyList(unrecognizedKeys, prefix)}. Recognized: ${formatKeyList(recognizedKeys, prefix)}.`);
 }
 function assertTierKeys(config, tier, configPath) {
-    const unsupported = Object.keys(config).filter((key) => !tier.honoredKeys.includes(key));
-    if (unsupported.length === 0) {
+    const unsupportedKeys = Object.keys(config).filter((key) => !tier.honoredKeys.includes(key));
+    if (unsupportedKeys.length === 0) {
         return;
     }
     throw new UserError(`Invalid nmr config at ${configPath}: ${tier.label} honors ${tier.honoredKeys.toSorted().join(', ')} alone, ` +
-        `not ${unsupported.toSorted().join(', ')}. Move those keys to ${tier.elsewhere}.`);
+        `not ${unsupportedKeys.toSorted().join(', ')}. Move those keys to ${tier.elsewhere}.`);
 }
 function formatKeyList(keys, prefix) {
     return keys

package/dist/esm/context.d.ts

@@ -3,7 +3,6 @@ export interface ResolvedContext {
     monorepoRoot: string;
     isRoot: boolean;
     packageDir?: string;
-    /** The workspace's package directories, resolved once here rather than swept for again by each reader. */
     workspacePackageDirs: string[];
     config: NmrConfig;
 }
@@ -11,7 +10,7 @@ export interface ResolvedContext {
  * Determines whether a directory is inside a workspace package.
  * Returns the package directory if so, or `undefined` if in root context.
  *
- * A workspace may nest one package inside another, so the deepest containing directory wins — matching
+ * A workspace may nest one package inside another, so the deepest containing directory wins. This matches
  * pnpm, which resolves a cwd to the package that encloses it most nearly.
  */
 export declare function findContainingPackageDir(dir: string, workspacePackageDirs: string[]): string | undefined;

package/dist/esm/context.js

@@ -2,17 +2,17 @@ import path from 'node:path';
 import { loadRootConfig } from "./config.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "./workspace.js";
 export function findContainingPackageDir(dir, workspacePackageDirs) {
-    const resolved = path.resolve(dir);
-    let nearest;
-    for (const pkgDir of workspacePackageDirs) {
-        const resolvedPkgDir = path.resolve(pkgDir);
-        if (resolved !== resolvedPkgDir && !resolved.startsWith(resolvedPkgDir + path.sep))
+    const resolvedDir = path.resolve(dir);
+    let nearestDir;
+    for (const packageDir of workspacePackageDirs) {
+        const resolvedPackageDir = path.resolve(packageDir);
+        if (resolvedDir !== resolvedPackageDir && !resolvedDir.startsWith(resolvedPackageDir + path.sep))
             continue;
-        if (nearest === undefined || resolvedPkgDir.length > nearest.length) {
-            nearest = resolvedPkgDir;
+        if (nearestDir === undefined || resolvedPackageDir.length > nearestDir.length) {
+            nearestDir = resolvedPackageDir;
         }
     }
-    return nearest;
+    return nearestDir;
 }
 export async function resolveContext(cwd) {
     const resolvedCwd = path.resolve(cwd ?? process.cwd());

package/dist/esm/default-scripts.d.ts

@@ -6,18 +6,17 @@ export interface StepSpec {
     /** A command name, optionally preceded by nmr's own flags, as it would be typed after `nmr`. */
     run: string;
     /**
-     * Set where the trailing arguments cannot narrow this step's work: it is a prerequisite the narrowed steps
-     * run against, or the tool it reaches would be misled by them. A declining step runs unnarrowed.
+     * Set when the trailing arguments cannot narrow this step's work: It is a prerequisite against which the
+     * narrowed steps run, or the tool that it invokes would be misled by them. A declining step runs unnarrowed.
      */
     shouldDeclineArguments?: boolean;
 }
 export type ScriptValue = string | ReadonlyArray<string | StepSpec>;
 export type ScriptRegistry = Record<string, ScriptValue>;
 /**
- * Workspace scripts, identical for every package.
- * Four Vitest projects are recognized: `tool`, `localhost`, `remote`, and `unit`. The latter is also a catch-all.
- * Name a test file with the matching infix to associate it with a project.
- * Example: `nmr test:tool` runs every file carrying the `tool` infix, such as `my-file.tool.test.ts`.
+ * Workspace scripts, identical for every package. A `test:<tier>` script runs the Vitest project of that tier, which
+ * collects the test files that name it: `nmr test:tool` runs `my-file.tool.test.ts`. The `unit` project also
+ * collects every file that does not name any other tier.
  */
 export declare const workspaceScripts: ScriptRegistry;
 export declare const rootScripts: ScriptRegistry;

package/dist/esm/defineConfig.d.ts

@@ -1,7 +1,7 @@
 import type { NmrConfig } from './types.js';
 export type { BuildConfig, CheckCacheConfig, CommandVerbosity, NmrConfig, OutputConfig, ScriptValue, StepSpec, } from './types.js';
 /**
- * Type-safe identity function for configuration files.
+ * Returns `config` unchanged, typing a configuration file's default export as `NmrConfig`.
  *
  * Usage in `.config/nmr.config.ts`:
  * ```ts

package/dist/esm/git-ignored-paths.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lists the untracked paths that git ignores under `dir`, relative to it and POSIX-separated, sorted. An ignored
+ * directory is one entry ending in `/`, standing for everything beneath it; a tracked file never appears, whatever
+ * pattern it matches.
+ *
+ * Returns an empty list whenever git does not answer, outside a repository or with git missing, so that a caller
+ * excluding these paths over-reports rather than hides a path.
+ */
+export declare function listGitIgnoredPaths(dir: string): string[];

package/dist/esm/git-ignored-paths.js

@@ -0,0 +1,10 @@
+import { spawnSync } from 'node:child_process';
+export function listGitIgnoredPaths(dir) {
+    const result = spawnSync('git', ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--directory', '--no-empty-directory'], { cwd: dir, encoding: 'utf8' });
+    if (result.error !== undefined || result.status !== 0)
+        return [];
+    return result.stdout
+        .split('\0')
+        .filter((entry) => entry !== '')
+        .toSorted();
+}

package/dist/esm/glyphs.d.ts

@@ -1,8 +1,8 @@
 /**
- * Glyphs that name no status; a status marker comes from nmr-core's `STATUS_GLYPHS`. A plain variant is empty
- * where a word always follows the glyph, and a word where the glyph opens a line of its own.
+ * Glyphs that do not name a status; a status marker comes from nmr-core's `STATUS_GLYPHS`. A plain variant is
+ * empty when a word always follows the glyph, and a word when the glyph opens a line of its own.
  *
- * `noop` is a neutral circle: nothing ran because the repo asked for nothing to run, which is neither a
+ * `noop` is a neutral circle: Nothing ran because the repo asked for nothing to run, which is neither a
  * failure nor a block.
  */
 export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "clean" | "package" | "catalog" | "noop" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;

package/dist/esm/help.d.ts

@@ -1,15 +1,15 @@
 import type { NmrConfig } from './types.js';
 /**
- * Generates the help text for the `nmr` CLI. Renders only nmr commands —
+ * Generates the help text for the `nmr` CLI. Renders only nmr commands:
  * names from the workspace and root registries, excluding hooks (`*:pre`,
  * `*:post`).
  *
  * When `packageDir` is provided, tier-3 entries from that package's
  * `package.json:scripts` that match a registry name in the active section
- * are inlined as overrides: the registry value is replaced with the
+ * are inlined as overrides: The registry value is replaced with the
  * override value and the row's command name is suffixed with `*`. The
- * active section is the root section when `useRoot` is true (root cwd
+ * active section is the root section when `shouldUseRoot` is true (root cwd
  * or `-w`), otherwise the workspace section. A footnote is appended once
  * if any override marker was rendered.
  */
-export declare function generateHelp(config: NmrConfig, packageDir: string | undefined, useRoot: boolean): string;
+export declare function generateHelp(config: NmrConfig, packageDir: string | undefined, shouldUseRoot: boolean): string;