@williamthorsen/nmr 0.34.0 → 0.36.0

package/dist/esm/commands/build.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import { readCacheEntry, writeCacheEntry } from '@williamthorsen/nmr-core';
 import { glob } from 'glob';
 import * as ts from 'typescript';
-import { resolveConfigPath } from "../config.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";
 const PACKAGE_ICON = '📦';
 const SKIPPED_ICON = '⏭️';
@@ -85,14 +85,15 @@ async function emitPackage(packageDir, entryPoints, outdir) {
     const emitDir = resolveEmitDir(packageDir, outdir);
     const scratchDirs = resolveScratchDirs(emitDir);
     await removeScratchDirs(scratchDirs);
-    const program = ts.createProgram(rootNames, compilerOptions);
     const emitted = new Map();
-    const emitResult = program.emit(undefined, (fileName, text, writeByteOrderMark) => {
+    function collect(fileName, text, writeByteOrderMark) {
         emitted.set(fileName, { text, writeByteOrderMark });
-    });
-    if (emitResult.emitSkipped) {
-        throw new Error(`nmr-compile: emit failed.\n${formatDiagnostics(emitResult.diagnostics)}`);
     }
+    const host = createCachingCompilerHost(compilerOptions);
+    const scriptProgram = ts.createProgram(rootNames, { ...compilerOptions, declaration: false }, host);
+    assertEmitSucceeded(scriptProgram.emit(undefined, collect));
+    const declarationProgram = ts.createProgram(rootNames, { ...compilerOptions, emitDeclarationOnly: true, removeComments: false }, host, scriptProgram);
+    assertEmitSucceeded(declarationProgram.emit(undefined, collect));
     const staged = new Map();
     for (const [fileName, file] of emitted) {
         staged.set(fileName, { ...file, text: rewriteSpecifiers(fileName, file.text, compilerOptions, sourceRoot) });
@@ -105,6 +106,25 @@ async function emitPackage(packageDir, entryPoints, outdir) {
     await swapIntoPlace(emitDir, scratchDirs);
     return staged.size;
 }
+function assertEmitSucceeded(result) {
+    if (result.emitSkipped) {
+        throw new Error(`nmr-compile: emit failed.\n${formatDiagnostics(result.diagnostics)}`);
+    }
+}
+function createCachingCompilerHost(compilerOptions) {
+    const host = ts.createCompilerHost(compilerOptions);
+    const parsed = new Map();
+    const readSourceFile = host.getSourceFile.bind(host);
+    host.getSourceFile = (fileName, languageVersionOrOptions, onError, shouldCreateNewSourceFile) => {
+        if (parsed.has(fileName)) {
+            return parsed.get(fileName);
+        }
+        const sourceFile = readSourceFile(fileName, languageVersionOrOptions, onError, shouldCreateNewSourceFile);
+        parsed.set(fileName, sourceFile);
+        return sourceFile;
+    };
+    return host;
+}
 async function discardScratchDirs(scratchDirs) {
     try {
         await removeScratchDirs(scratchDirs);

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

@@ -1,2 +1,17 @@
+/**
+ * Removes a package's build output and the build-cache entry that describes it, so no state survives to
+ * make the next build skip. Removal is idempotent: an already-clean package is a silent no-op.
+ */
 export declare function cleanPackage(packageDir: string): Promise<void>;
+/**
+ * Cleans the package containing `cwd`, or every workspace package when run from the monorepo root.
+ *
+ * From within a package this is the built-in clean itself: `nmr` has already resolved `clean` to this bin
+ * before invoking it, so resolving again would apply the package's own override twice.
+ *
+ * This is the default `clean` script, shipped as a bin rather than delegating to `rimraf`. Under pnpm's
+ * isolated layout, `pnpm exec` resolves only bins of the consuming project's own direct dependencies, so
+ * a `rimraf` in nmr's dependency tree would be unreachable — while nmr's own bins are linked into the
+ * consumer's `node_modules/.bin`, nmr being a direct dependency.
+ */
 export declare function runClean(cwd?: string): Promise<void>;

package/dist/esm/commands/ensure-prepublish-hooks.d.ts

@@ -10,9 +10,20 @@ export interface EnsurePrepublishHooksResult {
     hasFailures: boolean;
 }
 export declare const DEFAULT_HOOK = "npm run build";
+/**
+ * Check (and optionally fix) whether all publishable workspace packages
+ * have a `prepublishOnly` script.
+ */
 export declare function ensurePrepublishHooks(monorepoRoot: string, options: {
     fix: boolean;
     dryRun: boolean;
     command?: string;
 }): EnsurePrepublishHooksResult;
+/**
+ * Reports one line per publishable package and closes with what the run came to. Private packages appear in
+ * neither: they publish nothing, so a `prepublishOnly` is not theirs to carry.
+ *
+ * Every line goes to stdout, the `✗` included, and the exit code is what carries a failure. A report split
+ * across two streams leaves no reader holding the whole list.
+ */
 export declare function reportPrepublishHooks(result: EnsurePrepublishHooksResult, hookCommand: string): void;

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

@@ -1,6 +1,8 @@
 export type FormatMode = 'check' | 'write';
 export interface FormatTargets {
+    /** 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[];
 }
 export type ResolveTargetsResult = {
@@ -10,14 +12,44 @@ export type ResolveTargetsResult = {
     ok: false;
     error: string;
 };
+/**
+ * Formats or checks the files git reports for `cwd`, and returns the exit code to report.
+ *
+ * Trailing arguments are git pathspecs, not Prettier flags; an unrecognized option is rejected rather
+ * than passed along, since git would read it as a pathspec matching nothing and the run would report
+ * success over an empty selection.
+ */
 export declare function runFmt(argv: string[], cwd?: string): 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.
+ *
+ * File selection is anchored at `cwd` and ignore discovery at the repository root. That split is the point:
+ * scoping still follows where the caller stands, while the rules applied to a given file no longer do.
+ *
+ * `pathspecs` narrow the selection and are passed to git verbatim, so they carry git pathspec semantics
+ * rather than shell glob semantics.
+ */
 export declare function resolveFormatTargets(cwd: string, pathspecs?: string[]): ResolveTargetsResult;
+/** @internal */
 export interface RunPrettierOptions {
     cliPath: string;
     mode: FormatMode;
     files: string[];
     ignorePaths: string[];
     cwd: string;
+    /** Overridable so the multi-batch path is reachable without a fixture that hits the real ceiling. */
     budgetBytes?: number;
 }
+/**
+ * Runs Prettier over the selection, returning the first non-zero exit code. Every batch runs even after
+ * one fails, so a check reports every offending file rather than only those in the first batch.
+ *
+ * The CLI runs under this process's own Node rather than through its shebang, so it does not depend on
+ * the file's execute bit or on PATH holding a `node`.
+ *
+ * @internal
+ */
 export declare function runPrettier(options: RunPrettierOptions): number;

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

@@ -1 +1,11 @@
+/**
+ * Reports the catalogued dependencies a package-scoped upgrade pass cannot see.
+ *
+ * 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.
+ */
 export declare function reportCatalog(cwd: string): void;

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

@@ -1 +1,7 @@
+/**
+ * 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): void;

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

@@ -4,9 +4,27 @@ export interface SpawnOutcome {
     error?: Error | undefined;
 }
 export interface RunTazeOptions {
+    /** Resolves the absolute path of taze's CLI entry. Injected by tests. */
     resolveCliPath?: () => string;
+    /** Runs the CLI and reports how it exited. Injected by tests. */
     spawn?: (nodePath: string, argv: string[]) => SpawnOutcome;
+    /** Stream that error output is written to. Defaults to `process.stderr`. */
     stderr?: Writable;
 }
+/**
+ * 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.
+ *
+ * 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`.
+ */
 export declare function runTaze(args: string[], options?: RunTazeOptions): number;
+/** Resolves the absolute path of taze's CLI entry from nmr's own dependency tree. */
 export declare function resolveTazeCliPath(): string;

package/dist/esm/config.d.ts

@@ -1,6 +1,23 @@
 import type { NmrConfig } from './types.js';
-export declare const CONFIG_RELATIVE_PATH: string;
-export declare function resolveConfigPath(baseDir: string): string;
+/**
+ * Loads the nmr configuration from `.config/nmr.config.ts` under `baseDir`, which is the monorepo root for
+ * the repo-wide config and a package directory for the workspace tier. Returns an empty config if the file
+ * doesn't exist.
+ */
 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
+ * 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.
+ *
+ * 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.
+ */
 export declare function loadWorkspaceConfig(packageDir: string): Promise<NmrConfig>;

package/dist/esm/config.js

@@ -7,15 +7,16 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { existsSync } from 'node:fs';
-import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { resolveConfigPath } from "./helpers/config-path.js";
+import { findClosestName } from "./helpers/findClosestName.js";
+import { isHookName } from "./helpers/hook-name.js";
 import { isObject, isStringRecord } from "./helpers/type-guards.js";
+import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "./resolver.js";
 import { findUnexpressibleToken } from "./steps.js";
 import { UserError } from "./UserError.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
-const CONFIG_FILENAME = 'nmr.config.ts';
-const CONFIG_DIR = '.config';
-export const CONFIG_RELATIVE_PATH = path.join(CONFIG_DIR, CONFIG_FILENAME);
+import { getWorkspacePackageDirs, isMonorepoRoot } from "./workspace.js";
 const CONFIG_TIERS = {
     root: {
         label: 'a monorepo-root config',
@@ -33,9 +34,6 @@ const RECOGNIZED_BUILD_KEYS = ['extraIgnorePatterns'];
 const RECOGNIZED_CHECK_CACHE_KEYS = ['enabled', 'excludeCommands', 'extraCommands'];
 const RECOGNIZED_OUTPUT_KEYS = ['commandVerbosity', 'extraAgentEnvVars'];
 const RECOGNIZED_STEP_KEYS = ['declinesArgs', 'run'];
-export function resolveConfigPath(baseDir) {
-    return path.join(baseDir, CONFIG_DIR, CONFIG_FILENAME);
-}
 function isScriptRecord(value) {
     if (!isObject(value))
         return false;
@@ -132,6 +130,64 @@ function validateCheckCacheField(value, configPath) {
     }
     return config;
 }
+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 it wraps.');
+    }
+    const registered = new Set([
+        ...Object.keys(buildRootRegistry(config)),
+        ...Object.keys(buildWorkspaceRegistry(config)),
+    ]);
+    const missing = entries.filter(({ command }) => !registered.has(command));
+    if (missing.length === 0) {
+        return;
+    }
+    const declared = readDeclaredScriptNames(baseDir);
+    const unresolvable = missing.find(({ command }) => !declared.has(command));
+    if (unresolvable === 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}\`?`}`);
+}
+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;
+    }
+}
 function validateOutputField(value, configPath) {
     const output = value['output'];
     if (output === undefined) {
@@ -168,7 +224,7 @@ function validateStringRecordField(value, fieldName, configPath) {
     }
     return value[fieldName];
 }
-function validateConfig(value, configPath) {
+function validateConfig(value, configPath, baseDir) {
     if (!isObject(value)) {
         throw new UserError(`Invalid nmr config at ${configPath}: expected an object, got ${typeof value}`);
     }
@@ -192,6 +248,7 @@ function validateConfig(value, configPath) {
     const rootScripts = validateScriptField(value, 'rootScripts', configPath);
     if (rootScripts)
         config.rootScripts = rootScripts;
+    assertResolvableCheckCacheCommands(config, configPath, baseDir);
     return config;
 }
 export async function loadConfig(baseDir) {
@@ -201,7 +258,7 @@ export async function loadConfig(baseDir) {
     }
     const imported = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
     const loaded = isObject(imported) ? imported['default'] : undefined;
-    return validateConfig(loaded, configPath);
+    return validateConfig(loaded, configPath, baseDir);
 }
 export async function loadRootConfig(monorepoRoot) {
     const config = await loadConfig(monorepoRoot);

package/dist/esm/context.d.ts

@@ -5,5 +5,16 @@ export interface ResolvedContext {
     packageDir?: string;
     config: NmrConfig;
 }
+/**
+ * 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
+ * pnpm, which resolves a cwd to the package that encloses it most nearly.
+ */
 export declare function findContainingPackageDir(dir: string, workspacePackageDirs: string[]): string | undefined;
+/**
+ * Resolves the full execution context: monorepo root, whether we're in a
+ * workspace package or root context, and the loaded configuration.
+ */
 export declare function resolveContext(cwd?: string): Promise<ResolvedContext>;

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

@@ -1,8 +1,23 @@
+/**
+ * One element of a composite, paired with what it does with the invocation's trailing arguments. The bare
+ * string form of an element is this spec with `declinesArgs` left at its default.
+ */
 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.
+     */
     declinesArgs?: 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`.
+ */
 export declare const workspaceScripts: ScriptRegistry;
 export declare const rootScripts: ScriptRegistry;

package/dist/esm/defineConfig.d.ts

@@ -1,3 +1,12 @@
 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.
+ *
+ * Usage in `.config/nmr.config.ts`:
+ * ```ts
+ * import { defineConfig } from '@williamthorsen/nmr/config';
+ * export default defineConfig({ ... });
+ * ```
+ */
 export declare function defineConfig(config: NmrConfig): NmrConfig;

package/dist/esm/help.d.ts

@@ -1,2 +1,15 @@
 import type { NmrConfig } from './types.js';
+/**
+ * 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
+ * override value and the row's command name is suffixed with `*`. The
+ * active section is the root section when `useRoot` 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;

package/dist/esm/helpers/clampToBytes.d.ts

@@ -1,2 +1,14 @@
+/** Marks a value that was cut, so a reader can tell a truncated one from a complete one. */
 export declare const TRUNCATION_MARK = "\u2026";
+/**
+ * Cuts a string that would overrun a byte budget, marking the cut. What comes back is at most `budgetBytes`
+ * long, the mark included.
+ *
+ * Cuts between code points rather than between bytes, so a multi-byte character is never left in halves.
+ * Graphemes are left unconsidered, which can separate an emoji from a modifier following it -- a cost paid
+ * only at a budget no caller here comes near.
+ *
+ * A budget too small to hold the mark yields nothing at all, rather than a return that overruns what the
+ * caller asked for.
+ */
 export declare function clampToBytes(value: string, budgetBytes: number): string;

package/dist/esm/helpers/config-path.d.ts

@@ -0,0 +1,8 @@
+/** The config's path relative to the directory holding it, for a message composed without one in hand. */
+export declare const CONFIG_RELATIVE_PATH: string;
+/**
+ * Resolves the config-file path for a directory, whether that is the monorepo root or a package.
+ * Callers that only need to know whether a config exists -- the build, which folds it into its cache digest -- go
+ * through this rather than spelling the path again, so that the two cannot drift into hashing a file nothing reads.
+ */
+export declare function resolveConfigPath(baseDir: string): string;

package/dist/esm/helpers/config-path.js

@@ -0,0 +1,7 @@
+import path from 'node:path';
+const CONFIG_DIR = '.config';
+const CONFIG_FILENAME = 'nmr.config.ts';
+export const CONFIG_RELATIVE_PATH = path.join(CONFIG_DIR, CONFIG_FILENAME);
+export function resolveConfigPath(baseDir) {
+    return path.join(baseDir, CONFIG_DIR, CONFIG_FILENAME);
+}

package/dist/esm/helpers/createBoundedBuffer.d.ts

@@ -3,7 +3,14 @@ export interface BoundedBufferOptions {
     tailLimitBytes?: number;
 }
 export interface BoundedBuffer {
+    /** Retains a chunk, dropping bytes from the middle once both ends are full. */
     append: (chunk: Buffer) => void;
+    /** Renders the retained bytes, with a marker naming the dropped count standing in for what was dropped. */
     toBuffer: () => Buffer;
 }
+/**
+ * Creates an accumulator that retains the first and last bytes it is fed and drops the middle.
+ * Both ends are kept because a failing command's first error and its trailing summary each carry signal
+ * that the other end does not.
+ */
 export declare function createBoundedBuffer(options?: BoundedBufferOptions): BoundedBuffer;

package/dist/esm/helpers/deriveExcerpt.d.ts

@@ -1 +1,11 @@
+/**
+ * Reduces a transcript to the one line a verdict's detail slot carries, or `undefined` when it held nothing.
+ *
+ * The excerpt is the last blank-line-delimited block: a tool that prints progress separates its closing
+ * statement with a blank line, so the blank line is the tool naming where its summary starts. A fixed count of
+ * trailing lines fits vitest's four-line summary and v8's six-line coverage summary only by coincidence.
+ *
+ * The line carries a byte bound of its own, so what a caller persists is bounded. The 512-byte ceiling a
+ * verdict line is held to is not applied here, which leaves that line's grammar with the module that owns it.
+ */
 export declare function deriveExcerpt(transcript: string): string | undefined;

package/dist/esm/helpers/duration.d.ts

@@ -1,2 +1,17 @@
+/**
+ * Renders a duration at the two coarsest units that say something, for a line a reader skims.
+ *
+ * Truncates at every unit rather than rounding, so a value never reads as more time than elapsed: 90 seconds is
+ * `1m 30s`, where rounding would claim `2m`. Below a minute the tenth is kept, since that is the scale at which
+ * one check's runtime differs from another's; a whole number sheds the `.0` rather than reading `12.0s`.
+ */
 export declare function formatDuration(milliseconds: number): string;
+/**
+ * Renders the clause a skip spends on the time it saved, or `undefined` when there is no saving worth naming.
+ * A skip that can say what it saved earns the clause; one that cannot says nothing, and the caller drops it
+ * rather than printing a saving of `~0s`.
+ *
+ * Guards its own input rather than trusting the caller's, because the clause is shared: a non-finite duration
+ * compares false against the threshold, and would reach a reader as `saved ~NaNs`.
+ */
 export declare function formatSaving(milliseconds: number): string | undefined;

package/dist/esm/helpers/findClosestName.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Finds the candidate closest to a name, or `undefined` where none is near enough to be worth naming.
+ *
+ * The ceiling scales with the name's length, so a short name admits one slip and a long one a few. A fixed
+ * ceiling would either miss a typo in `root:test:coverage` or offer `fix` for `ci`.
+ */
+export declare function findClosestName(name: string, candidates: Iterable<string>): string | undefined;

package/dist/esm/helpers/findClosestName.js

@@ -0,0 +1,38 @@
+export function findClosestName(name, candidates) {
+    const ceiling = Math.max(1, Math.floor(name.length / 4));
+    let closest;
+    let shortest = Infinity;
+    for (const candidate of candidates) {
+        const distance = measureDistance(name, candidate);
+        if (distance < shortest) {
+            shortest = distance;
+            closest = candidate;
+        }
+    }
+    return shortest <= ceiling ? closest : undefined;
+}
+function measureDistance(first, second) {
+    if (first.length === 0 || second.length === 0) {
+        return Math.max(first.length, second.length);
+    }
+    let previous = Array.from({ length: second.length + 1 }, (_unused, column) => column);
+    let current = Array.from({ length: second.length + 1 }, () => 0);
+    for (let row = 1; row <= first.length; row += 1) {
+        current[0] = row;
+        for (let column = 1; column <= second.length; column += 1) {
+            const substitution = readCell(previous, column - 1) + (first[row - 1] === second[column - 1] ? 0 : 1);
+            current[column] = Math.min(readCell(current, column - 1) + 1, readCell(previous, column) + 1, substitution);
+        }
+        const completed = current;
+        current = previous;
+        previous = completed;
+    }
+    return readCell(previous, second.length);
+}
+function readCell(row, index) {
+    const value = row[index];
+    if (value === undefined) {
+        throw new RangeError(`No cell at index ${index} in a row of ${row.length}`);
+    }
+    return value;
+}

package/dist/esm/helpers/hook-name.d.ts

@@ -1 +1,9 @@
+/**
+ * Returns true when `key` is a hook script name — that is, ends with the
+ * `:pre` or `:post` suffix preceded by at least one character.
+ *
+ * Bare `:pre` and `:post` (no parent name) return false. The predicate is
+ * purely about suffix shape; it does not consult the registry or care
+ * whether the parent command exists.
+ */
 export declare function isHookName(key: string): boolean;

package/dist/esm/helpers/package-json.d.ts

@@ -1,3 +1,9 @@
+/**
+ * The `package.json` fields that carry a dependency's version specifier.
+ *
+ * pnpm accepts the `catalog:` protocol in all four, so a reader looking for catalogued dependencies has to
+ * sweep the whole set rather than the two that carry most of them.
+ */
 export declare const DEPENDENCY_FIELDS: readonly ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
 export type DependencyField = (typeof DEPENDENCY_FIELDS)[number];
 export type PackageJson = {
@@ -12,8 +18,27 @@ export type PackageJson = {
 } & {
     [K in DependencyField]?: Record<string, string>;
 };
+/**
+ * Reads and parses the package.json at the given directory, keeping only the fields nmr reads.
+ */
 export declare function readPackageJson(dir: string): PackageJson;
+/**
+ * Returns the `pnpm.overrides` block a package.json declares, every key it holds and each value as written.
+ */
 export declare function getPnpmOverrides(pkg: PackageJson): Record<string, unknown> | undefined;
+/**
+ * Parses a `package.json`'s text, rejecting what does not parse.
+ *
+ * A file the user wrote by hand is theirs to fix, so the failure names it rather than reporting the parser's
+ * own stack.
+ */
 export declare function parsePackageJson(raw: string, file: string): unknown;
+/**
+ * Narrows a `scripts` record to strings, rejecting any value that is not one.
+ *
+ * npm and pnpm read a script as a string too, so a value of any other type is malformed however it got there.
+ * Dropping one silently would let a caller run something else in its place and report nothing.
+ */
 export declare function readScriptRecord(dir: string, scripts: Record<string, unknown>): Record<string, string>;
+/** Resolves the `package.json` path for a directory: the file tier-3 scripts are read from. */
 export declare function resolvePackageJsonPath(dir: string): string;

package/dist/esm/helpers/package-json.js

@@ -1,9 +1,9 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { describeError } from '@williamthorsen/toolbelt.errors';
-import { CONFIG_RELATIVE_PATH } from "../config.js";
 import { UserError } from "../UserError.js";
 import { isMonorepoRoot } from "../workspace.js";
+import { CONFIG_RELATIVE_PATH } from "./config-path.js";
 import { readStringValues } from "./readStringValues.js";
 import { isObject } from "./type-guards.js";
 export const DEPENDENCY_FIELDS = [

package/dist/esm/helpers/readStringValues.d.ts

@@ -1 +1,8 @@
+/**
+ * Keeps the entries whose value is a string, dropping the rest.
+ *
+ * A manifest reader that rejected the whole record over one bad value would report nothing about the entries
+ * beside it, which for a reporter is silence where there is something to say. YAML's implicit typing makes
+ * that easy to reach without malformed intent: an unquoted `18` parses as a number.
+ */
 export declare function readStringValues(record: Record<string, unknown>): Record<string, string>;

package/dist/esm/helpers/reportClosing.d.ts

@@ -1 +1,16 @@
+/**
+ * Reports the line that closes a bin's output, separated from the items above it by a blank line.
+ *
+ * A bin that prints one line per item leaves a reader who reaches the end holding whichever item happened to
+ * be last. The convention this writes: the header says what the list is, and the closing statement says what
+ * the run came to, so the count and the remedy live here rather than in the header. The blank line is what
+ * makes the statement findable once the lines are flattened.
+ *
+ * The blank line rides in the same call as the statement, so the closer is one write and cannot be
+ * interleaved. `log` is what puts the closer on the stream its items went to: a bin reporting to stderr
+ * passes `console.warn`.
+ *
+ * A bin whose whole output is one or two statements about one subject has no items to be separated from, and
+ * closes by printing plainly rather than through here.
+ */
 export declare function reportClosing(message: string, log?: (line: string) => void): void;