@williamthorsen/nmr 0.35.0 → 0.36.0

package/README.md

@@ -3,33 +3,36 @@
 Context-aware script runner for pnpm monorepos. Ships an `nmr` (node-monorepo run) binary that provides centralized, consistent script execution across workspace packages and the monorepo root.
 
 <!-- section:release-notes -->
-## Release notes — v0.35.0 (2026-09-01)
+## Release notes — v0.36.0 (2026-09-08)
 
 ### 🎉 Features
 
-- Expose tsconfigPaths as a first-class Vitest config flag (#751)
+- Report a package whose tarball would omit its changelog (#768)
 
-  Adds a `tsconfigPaths` option to `defineVitestConfig` and `defineRootVitestConfig` in `@williamthorsen/nmr/vitest`. It emits Vite's `resolve.tsconfigPaths`, so a test resolves an aliased specifier through the `paths` its own `tsconfig.json` declares, the way `tsc` does.
+  Adds ReadyUp checks to verify that every published package bundles its changelog files: the human-readable `CHANGELOG.md` and the machine-readable `changelog.json`.
 
-  The option defaults to `false` and requires Vite 8, which `@williamthorsen/nmr` now declares as an optional peer dependency at `>=8.0.0 <9`.
+- Reject a checkCache command name that matches no command (#778)
 
-- Publish a test-file conventions check consuming repos can gate in CI (#753)
+  Modifies `nmr` so that it rejects a `checkCache.extraCommands` or `checkCache.excludeCommands` name that matches no command, so a misspelt entry fails config load instead of silently having no effect.
 
-  Adds `checkTestFileConventions` at `@williamthorsen/nmr/tests`, which a consuming repo calls from a test of its own. It fails the run on any test file that names no isolation tier or sits outside `__tests__`. Both passed silently before.
+  Modifies `nmr` so that it resolves names listed in either field against nmr's default scripts, the repo config's script registries, and each package's `package.json` scripts, so a name that only a package declares is accepted.
 
-  Adds `testCollectionExclude` to `defineVitestConfig` and `defineRootVitestConfig`. The same array of directory names goes to the check's `exclude`, so one declaration scopes both the sweep and what Vitest collects.
+  Migration: Correct or remove any `checkCache.extraCommands` or `checkCache.excludeCommands` entry that names no command, and any entry that names a hook, which is rejected too. The error reports the field, the offending name, and the closest command where there is one.
 
-- Keep doc comments in published declaration files (#762)
+- Report a bin target that is not a committed wrapper (#780)
 
-  Changes the behavior of `nmr-compile` so that it preserves doc comments in `.d.ts` files.
+  - Adds `every bin target is a committed wrapper` to nmr's readyup kit, which reports a workspace `bin` target naming a path under `dist/`, or one that git does not track, because pnpm links a package's bins before anything is built and never retries a failed link.
+  - Adds `every bin wrapper's build-output target is covered by files`, which reports a wrapper loading build output that `files` omits, since that publishes a bin resolving to nothing.
 
-  TypeScript's `removeComments` governs a whole emit, so a TS configuration that kept comments out of JavaScript also kept them out of declaration files. `nmr-compile` now emits from two programs: The first produces the `.js` under the package's own `removeComments`, and the second produces the declarations with comments.
+  Migration: Replace a `bin` target naming a path under `dist/` with a committed wrapper under `bin/` that imports the build entry, commit the wrapper, and extend `files` to cover the output that the wrapper loads.
 
-- Report workspaces whose Vitest config bypasses the projects model (#763)
+### 🐛 Bug fixes
 
-  Adds a check to nmr's ReadyUp kit to report every workspace that holds a Vite config without a Vitest config beside it, and widens the existing content check from the repo root to every workspace, so a Vitest config that does not build on `defineVitestConfig` is reported. The purpose of these checks is to ensure that tier-selecting test commands are supported.
+- Keep global git ignore rules and attributes out of test subprocesses (#773)
 
-  Also fixes an issue where the `no package re-exports the ancestor Vitest config` check incorrectly advised a consumer to delete a config.
+  Fixes an issue where a test that spawns `git` read ignore rules and attributes from outside the repository, so a suite could pass or fail on whatever a developer or their machine happened to have configured. The setup file that `defineVitestConfig` loads by default now isolates both, alongside the git configuration already covered.
+  
+  Migration: Where a test needs its own `core.excludesFile` or `core.attributesFile`, pass it on the invocation as `git -c core.excludesFile=<path>`. An environment-injected key now outranks repository-local config.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -519,6 +522,10 @@ export default defineConfig({
 
 `extraCommands` extends the default set rather than replacing it, so naming one command cannot silently drop the rest; `excludeCommands` is applied afterwards, so a name in both is excluded. `enabled: false` turns the gate off entirely. The key is `checkCache`, in the monorepo-root config.
 
+**A name in either list must resolve to a command**, whether through nmr's defaults, the repo config's script records, or a package's own `package.json` scripts. Both lists are read by name alone, so a misspelt entry would otherwise be inert: the command it meant to name would go on running, indistinguishable from one that cannot be cached at all. A name that resolves nowhere fails config load, naming the closest command where there is one. A hook name is rejected too, since a hook is never gated on its own -- it runs as part of the chain of the command it wraps, and is skipped or run with it.
+
+The test is resolvability rather than membership of the cacheable set, so an `excludeCommands` entry keeps standing after a release moves its name out of the defaults.
+
 ```ts
 export default defineConfig({
   output: {
@@ -945,7 +952,7 @@ ensure-prepublish-hooks
 
 ## Conformance checks
 
-nmr publishes a `readyup` kit that checks a consuming repo against the current release: the shared Vitest and Prettier configs, the workspace layout, the root script registry, the [test-tier convention](#test-tiers), and that no `package.json` in the tree declares a `pnpm` field, which pnpm 11 reads no key from. Those settings belong in `pnpm-workspace.yaml`, and `pnpx codemod run pnpm-v10-to-v11` moves them. The kit ships inside the package, so it checks against the nmr version installed rather than whatever a repository ref happens to point at, and a tier added or renamed in nmr reaches the repo on upgrade. A repo that wants the tier convention in its own gate rather than in a command run by hand declares the [conventions check](#gating-the-test-file-conventions) instead, which also covers the half the kit does not.
+nmr publishes a `readyup` kit that checks a consuming repo against the current release: the shared Vitest and Prettier configs, the workspace layout, the root script registry, the [test-tier convention](#test-tiers), that every `bin` target is a committed wrapper rather than build output that pnpm cannot link at install time, that `files` covers the output each wrapper loads, and that no `package.json` in the tree declares a `pnpm` field, which pnpm 11 reads no key from. Those settings belong in `pnpm-workspace.yaml`, and `pnpx codemod run pnpm-v10-to-v11` moves them. The kit ships inside the package, so it checks against the nmr version installed rather than whatever a repository ref happens to point at, and a tier added or renamed in nmr reaches the repo on upgrade. A repo that wants the tier convention in its own gate rather than in a command run by hand declares the [conventions check](#gating-the-test-file-conventions) instead, which also covers the half the kit does not.
 
 Add `readyup` as a devDependency, then name nmr in its config:
 
@@ -1141,7 +1148,7 @@ Expect the first run to fail in a repo that has never gated this. Vitest 4 exclu
 Two settings a workspace test runner needs almost universally are part of what the factory produces, so a config file declares neither:
 
 - **Workspace packages resolve from source.** `source` leads the emitted `resolve.conditions` and `ssr.resolve.conditions`, so a cross-package import reaches the dependency's `.ts` rather than its `dist/` and a suite runs without a prior build. A package declaring no such condition is unaffected.
-- **Git subprocesses are isolated.** Every project loads a setup file that points `GIT_CONFIG_GLOBAL` and `GIT_CONFIG_SYSTEM` at the null device and sets `GIT_CONFIG_NOSYSTEM`, so a test that spawns `git` reads neither the developer's identity nor a signing config that can block on a passphrase. It leads each project's `setupFiles`, ahead of every entry the layers add, because a shared setup establishes the environment the rest run in.
+- **Git subprocesses are isolated.** Every project loads a setup file that points `GIT_CONFIG_GLOBAL` and `GIT_CONFIG_SYSTEM` at the null device, sets `GIT_CONFIG_NOSYSTEM` and `GIT_ATTR_NOSYSTEM`, and injects `core.excludesFile` and `core.attributesFile` through `GIT_CONFIG_COUNT` and its key/value pairs, so a test that spawns `git` reads neither the developer's identity, nor a signing config that can block on a passphrase, nor their global ignore rules and attributes. Those last two need a step of their own: neither path is config-derived, so git resolves each from `$XDG_CONFIG_HOME/git/`, or from `~/.config/git/` where that variable is unset, whatever the config variables say. `GIT_CONFIG_GLOBAL` already replaces `$XDG_CONFIG_HOME/git/config`, so those two are the rest of what that directory supplies; the system attributes file at `$(prefix)/etc/gitattributes` is reached by no config variable at all, which is what `GIT_ATTR_NOSYSTEM` covers. Redirecting `XDG_CONFIG_HOME` would reach the per-user pair as well, and is not used, because other tools spawned by a test read that variable for configuration of their own: pnpm fails to start under `XDG_CONFIG_HOME=/dev/null`. An injected key outranks repository-local config, so a repository setting its own `core.excludesFile` is overridden under the isolation; a test needing its own value passes it on the invocation as `git -c core.excludesFile=...`, which outranks the injection. The setup file leads each project's `setupFiles`, ahead of every entry the layers add, because a shared setup establishes the environment the rest run in.
 
 Both defaults exist because omitting either is silent rather than loud: the tiers still exist and the suite still runs green, testing `dist/` and the developer's git identity instead. Turn either off through its own option, which folds across layers like any other, the last layer to declare it winning:
 

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 = '⏭️';

package/dist/esm/config.d.ts

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

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/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/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/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/runCli.js

@@ -2,9 +2,9 @@ import path from 'node:path';
 import { readPackageVersion, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { certifyRetention, computeCacheKey, computeRetentionKey, CURRENT_RUNTIME, encodeTreeSnapshot, findStaleBuildOutput, formatMisplacedNoCacheWarning, isCacheableCommand, NO_CACHE_ENV_VAR, readBuildOutputState, readCheckCacheEntry, recordTranscript, resolveRunId, resolveTreeSnapshot, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, writeCheckCacheEntry, writeDebugNote, } from "./check-cache.js";
-import { resolveConfigPath } from "./config.js";
 import { resolveContext } from "./context.js";
 import { generateHelp } from "./help.js";
+import { resolveConfigPath } from "./helpers/config-path.js";
 import { deriveExcerpt } from "./helpers/deriveExcerpt.js";
 import { isHookName } from "./helpers/hook-name.js";
 import { resolvePackageJsonPath } from "./helpers/package-json.js";

package/dist/esm/types.d.ts

@@ -17,13 +17,14 @@ export interface CheckCacheConfig {
     enabled?: boolean;
     /**
      * Command names removed from the cacheable set, applied after `extraCommands`. This is how a repo retires a
-     * name whose chain turned out to do more than report an exit status.
+     * name whose chain turned out to do more than report an exit status. Every name has to resolve to a command.
      */
     excludeCommands?: string[];
     /**
      * Command names added to the cacheable set. Extends rather than replaces, so that declaring one command
      * cannot silently drop the defaults. A name listed here promises exit-status-only semantics through its whole
-     * chain, hooks included.
+     * chain, hooks included, and has to resolve to a command: both lists are read by name alone, so a misspelt
+     * entry would otherwise be inert.
      */
     extraCommands?: string[];
 }

package/dist/esm/vitest-git-isolation.js

@@ -2,3 +2,9 @@ import os from 'node:os';
 process.env['GIT_CONFIG_GLOBAL'] = os.devNull;
 process.env['GIT_CONFIG_SYSTEM'] = os.devNull;
 process.env['GIT_CONFIG_NOSYSTEM'] = '1';
+process.env['GIT_ATTR_NOSYSTEM'] = '1';
+process.env['GIT_CONFIG_COUNT'] = '2';
+process.env['GIT_CONFIG_KEY_0'] = 'core.excludesFile';
+process.env['GIT_CONFIG_VALUE_0'] = os.devNull;
+process.env['GIT_CONFIG_KEY_1'] = 'core.attributesFile';
+process.env['GIT_CONFIG_VALUE_1'] = os.devNull;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -66,24 +66,26 @@
     "nmr-taze": "bin/nmr-taze.js"
   },
   "files": [
+    ".meta/changelog.json",
     ".readyup/kits/*.js",
     ".readyup/manifest.json",
+    "CHANGELOG.md",
     "agents",
     "bin",
     "dist"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.10.4",
-    "@williamthorsen/toolbelt.errors": "0.6.3",
+    "@williamthorsen/nmr-core": "0.11.0",
+    "@williamthorsen/toolbelt.errors": "0.7.0",
     "glob": "13.0.6",
     "prettier-plugin-sh": "0.19.0",
     "taze": "21.1.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {
-    "@williamthorsen/toolbelt.filesystem": "0.8.2",
-    "@williamthorsen/toolbelt.testing": "0.5.0",
-    "@williamthorsen/toolbelt.vitest": "0.8.0",
+    "@williamthorsen/toolbelt.filesystem": "0.8.3",
+    "@williamthorsen/toolbelt.testing": "0.5.1",
+    "@williamthorsen/toolbelt.vitest": "0.9.0",
     "prettier": "3.9.6",
     "readyup": "0.35.0",
     "tinyglobby": "0.2.17",