@williamthorsen/nmr 0.44.0 → 0.45.0

package/docs/scripts.md

@@ -22,7 +22,13 @@ If the package does not declare its own override, the highest-tier value that is
 
 A `package.json` entry that re-invokes the command under which it is declared is never honored. Honoring `"build": "nmr build"` would spawn a shell running `nmr build` in the same directory, reaching the same entry again without bound, so nmr discards the entry and resolves the command from the tier below. An entry that contains only the self-reference, trailing arguments included, is discarded in silence: It does not declare any step that nmr would lose. Because discarding an entry that chains anything else onto it (`"build": "nmr build && rdy compile"`, or `"build": "rdy compile && nmr build"`) would lose those steps, nmr rejects the invocation instead, naming the file, the key, and where the steps belong. For an ordinary command that is a `<command>:pre` or `<command>:post` script: `"build:pre": "rdy verify"` and `"build:post": "rdy compile"` wrap nmr's own `build` rather than replacing it. For a hook entry it is the entry itself, since nmr does not wrap a `:pre` or `:post` script in any hooks of its own: `"build:post": "nmr build:post && rdy compile"` becomes `"build:post": "rdy compile"`.
 
-nmr recognizes the re-invocation wherever it appears in the entry, on the grammar that [the shelled-nmr line](#script-values) uses, and a segment containing `-F` or `-R` is not one: It hands the command to other scopes rather than back to this one. Nor is `-w` from inside a package, which targets the root's registry and the root's `package.json`. A filter that selects the declaring package is the hole in that exemption: `nmr -F own-pkg build` in `own-pkg`'s own `build` re-enters without bound, and nmr does not recognize it.
+nmr recognizes the re-invocation wherever it appears in the entry, on the grammar that [the shelled-nmr line](#script-values) uses, and decides from the scope flags whether it returns to the entry. At the root, a segment containing `-F` or `-R` is not one: It hands the command to the packages, and pnpm's recursion leaves the root out. Inside a package, `-w` is not one, since it targets the root's registry and the root's `package.json`, and `-R` is, since it fans out to every package, the declaring one included. pnpm's own `-r`, `--filter`, and `-w`, standing ahead of `exec nmr`, count as nmr's. A filter that selects the declaring package is the hole in the `-F` exemption: `nmr -F own-pkg build` in `own-pkg`'s own `build` re-enters the entry, and nmr does not recognize it.
+
+A `.config/nmr.config.ts` entry that names the key under which it is declared, as a shell segment of a string value or as a step-list element, is rejected when the config loads, so every command fails until it is fixed. Discarding it, as tier 3 does, would run the built-in default, which is a command that the repo did not declare. A `rootScripts` entry resolves at the root, so the root's scope rule applies to it. A `workspaceScripts` entry resolves in every package that does not override the command, so `-R` and `-F` re-enter it and only `-w` leaves it: `workspaceScripts: { build: ['-R build'] }` sends each package back to the same entry. The error names the file, the field, and the key, and the edit depends on the key. When nmr's built-in defaults define the key, delete the entry and move the steps that it adds to a `<command>:pre` or `<command>:post` script, which wraps nmr's own command: `workspaceScripts: { build: 'nmr build && rdy compile' }` becomes `workspaceScripts: { 'build:post': 'rdy compile' }`. For a hook, or a command that only the config defines, delete the re-invocation: The steps beside it are the command.
+
+Neither tier detects a cycle through two entries, such as `workspaceScripts: { build: ['-w build'] }` against the root's default `build: ['-R build']`, which also re-enters the entry.
+
+What recognition misses, the run itself stops. Each nmr process that resolves a command passes that command, with the directory from whose registry it resolved it, to the processes that it starts, in `NMR_ENTRY_CHAIN`. A process that finds its own command and directory already on that chain fails with an error naming both and listing the chain, outermost first, instead of running the entry again. Only the ancestors on the chain count, so a command that runs twice in sequence and a `<command>:pre` or `<command>:post` hook are unaffected, and a `-R` or `-F` fan-out, which resolves nothing itself, neither checks the chain nor extends it.
 
 ### Script values
 
@@ -71,9 +77,11 @@ A string value is spawned through a shell as one command. An `nmr` invocation in
 
 The line names the declaration to which it is an edit (the file, the field, and the key), and its remedy follows from that site. In a `.config/nmr.config.ts` entry, keep the nmr steps as a step list and move anything else to a `<command>:pre` or `<command>:post` script: A step-list element can name only an nmr command, because nmr composes it into `nmr <element>`. A `package.json` entry has to go, since `package.json` cannot declare a step list: Delete it outright when it restates what nmr already runs for that command, and move the steps that it adds to a `<command>:pre` or `<command>:post` script when they are the package's own. When the registry does not define that command, both apply: Name the command in `.config/nmr.config.ts`, and put the package-specific steps in a hook. The pair is named rather than `:post` alone because an entry's extra steps may run on either side of the chain: `rdy verify && nmr compile` puts them first. A hook is the exception at both tiers: nmr does not wrap a `:pre` or `:post` script in any hooks of its own. Move a hook's other steps to a script of their own, and name that script in the step list.
 
+One kind of `package.json` entry is resolved in its own file: an entry whose whole value is `nmr <name>`, without flags, arguments, assignments, or a launcher, where `<name>` is a script in the same `package.json` that runs a command other than nmr and does not have a `:pre` or `:post` hook. Replace the entry's value with that command, and delete the script: `"build:pre": "nmr compile:ports"` beside `"compile:ports": "node scripts/compile-ports.ts"` becomes `"build:pre": "node scripts/compile-ports.ts"`. Keep the script when the registry also defines `<name>`, because the script then overrides nmr's own command. The script must come from the same file: Inlining a command that resolves from the registry would copy nmr's own command text into the package, where nmr's later changes do not reach it.
+
 nmr recognizes `nmr` in command position: at the start of a step, after an unquoted `&&`, `||`, `;`, `|`, or a newline, past any leading `NAME=value` assignments, and behind `npx`, `bunx`, or an `exec`, `dlx`, or `x` subcommand of `npm`, `pnpm`, `yarn`, or `bun`. This line reports a boundary rather than enforcing a rule: It covers a step that nmr runs as written, and only the reporting of the nested run is degraded. The line is also partial in three ways: a value-taking flag standing immediately before the program name hides it (`npx -p foo nmr`), a launcher outside that set goes unreported, and a `devBin` substitution that introduces `nmr` itself is not reported, the line being an edit to a declaration rather than to a substitution.
 
-A [self-referential `package.json` entry](#three-tier-override-system) is the shape that nmr cannot run as written, and it is rejected rather than reported. The same recognition finds it, so the same residuals apply: What goes unrecognized there re-enters nmr without bound, which hangs rather than passing quietly.
+A [self-referential entry](#three-tier-override-system), in `package.json` or in `.config/nmr.config.ts`, is the shape that nmr cannot run as written, and it is rejected rather than reported. The same recognition finds it, so the same residuals apply: What goes unrecognized there re-enters nmr once, and the run then fails with an error naming the command and the directory that it re-entered.
 
 ## Pre and post hooks
 

package/docs/utilities.md

@@ -47,9 +47,9 @@ nmr-fmt --write packages/nmr
 
 `fmt` and `fmt:check` format the files that git reports: tracked files, plus untracked files that git does not ignore. Prettier reads `.gitignore` and `.prettierignore` from the working directory alone, so a pattern in `packages/<pkg>/.gitignore` never applies to a run started at the monorepo root. Because git knows the whole hierarchy, including `.git/info/exclude` and `core.excludesFile`, and every `.prettierignore` in the tree is discovered from the repository root, package-level exclusions apply from any directory as well.
 
-A file that git ignores is never formatted, even when named directly. Because trailing arguments are git pathspecs rather than Prettier flags, `nmr fmt:check packages/nmr` narrows the run, while an unrecognized option and a pathspec that does not match any formattable file both fail it. Running outside a git repository fails rather than reporting a clean run.
+A file that git ignores is never formatted, even when named directly. Because trailing arguments are git pathspecs rather than Prettier flags, `nmr fmt:check packages/nmr` narrows the run, while an unrecognized option and a pathspec for which git lists no file both fail it. Running outside a git repository fails rather than reporting a clean run.
 
-`nmr-fmt` drops paths that the index names but the filesystem does not have (a file deleted but not yet staged), submodule gitlinks, and symlinks whatever they point at, before calling Prettier, which rejects a symlink named explicitly. It also skips a path that it is denied access to, such as a `.envrc` that a sandbox shields, and names each one on stderr, so that a check that passes does not hide a file that it never read. Any other failure to stat a listed path fails the run, with an error that names the path.
+`nmr-fmt` drops paths that the index names but the filesystem does not have (a file deleted but not yet staged), submodule gitlinks, and symlinks whatever they point at, before calling Prettier, which rejects a symlink named explicitly. It also skips a path that it is denied access to, such as a `.envrc` that a sandbox shields, and names each one on stderr, so that a check that passes does not hide a file that it never read. A pathspec whose every match is skipped still counts as matched: The run passes and names the skipped paths on stderr, so that a pre-commit hook passing only staged symlinks or a submodule bump does not fail. Any other failure to stat a listed path fails the run, with an error that names the path.
 
 ### Cache
 

package/docs/vitest.md

@@ -10,16 +10,20 @@ The [README](../README.md#shared-vitest-config) shows the one-line config file.
 
 The config declares four projects, an ordered ladder named for the furthest thing that a test reaches:
 
-| Project     | Matches                                     | Reaches                                              |
-| ----------- | ------------------------------------------- | ---------------------------------------------------- |
-| `unit`      | every test file that the others don't claim | nothing outside the package's own dependency closure |
-| `tool`      | `*.tool.test.{ts,tsx}`                      | a program that the environment must supply           |
-| `localhost` | `*.localhost.test.{ts,tsx}`                 | a service running on this machine                    |
-| `remote`    | `*.remote.test.{ts,tsx}`                    | a machine that isn't this one                        |
+| Project     | Matches                                     | Reaches                                                                    |
+| ----------- | ------------------------------------------- | -------------------------------------------------------------------------- |
+| `unit`      | every test file that the others don't claim | nothing outside the package's own dependency closure                       |
+| `tool`      | `*.tool.test.{ts,tsx}`                      | a process that the test starts, or a program that the environment supplies |
+| `localhost` | `*.localhost.test.{ts,tsx}`                 | a service already running on this machine                                  |
+| `remote`    | `*.remote.test.{ts,tsx}`                    | a machine that isn't this one                                              |
 
 All four match only under a `__tests__` directory.
 
-**A tier names what a test reaches, never how it invokes it.** A test driving a compiler through its JavaScript API is `tool`, exactly as one spawning the compiler binary is; whether a program ships as a library or an executable is an accident of packaging, not a property of the test. A package's `peerDependencies`, plus whatever binaries it spawns, are a good statement of where its `tool` boundary is: A bundled dependency is inside the package's own closure and is always present, so reaching one is `unit`.
+**A tier names what the environment must supply for a test to run.** A test is `tool` when it reaches a process that it starts, or a program that the environment supplies. A spawned process is itself something that the test reaches, even when it runs the package's own code, because the machine sets how long the process takes to start and to run.
+
+**A tier names what a test reaches, never how it invokes it.** A test driving a compiler through its JavaScript API is `tool`, exactly as one spawning the compiler binary is; whether a program ships as a library or an executable is an accident of packaging, not a property of the test. What decides is who supplies the program, and a package declares that in its `peerDependencies`. Those, plus whatever binaries it spawns, mark where its `tool` boundary lies: A bundled dependency is inside the package's own closure and is always present, so reaching one in-process is `unit`.
+
+**A service that the test starts itself takes the tier of the code that runs it.** A test that calls `net.Server.listen(0)` on a server from its own dependency closure and reaches it with `fetch` is `unit`: Both ends of the loopback connection are inside the test process, and the connection is how the test invokes that code. The same server started as a child process is `tool`, as is a service whose program the environment supplies, such as a `postgres` binary. `localhost` is for a service that is already running when the test starts, such as a separately started backend or a seeded database.
 
 **A tier is not a statement about preconditions.** A `unit` test may still need something set up before it runs: a build, a generated fixture, a seeded file. It is `unit` because it reaches nothing beyond the test process _while running_. The filesystem belongs to `unit` for the same reason the tiers exist: They gate on what must be available, and the filesystem always is.
 
@@ -103,7 +107,7 @@ In a repo that has not declared the check, [nmr's readyup kit](../README.md#conf
 Two settings that a workspace test runner needs almost universally are part of what the factory produces, so a config file declares neither:
 
 - **A package outside `node_modules` resolves from source.** Because a cross-package import resolves to the dependency's `.ts` rather than its `dist/`, through the `source` condition declared by its `exports` map, a suite runs without a prior build. The reach is what the boundary names: a workspace package, or one linked into the repo from elsewhere, whose real path is outside every `node_modules`. A package that does not declare a `source` condition is unaffected, and so is every package under `node_modules`, whatever its `exports` map declares.
-- **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: Because neither path is config-derived, git resolves each from `$XDG_CONFIG_HOME/git/`, or from `~/.config/git/` when that variable is unset, whatever the config variables say. `GIT_CONFIG_GLOBAL` already replaces `$XDG_CONFIG_HOME/git/config`; those two are the rest of what that directory supplies. The system attributes file at `$(prefix)/etc/gitattributes` is not named by any config variable at all, which is what `GIT_ATTR_NOSYSTEM` covers. Redirecting `XDG_CONFIG_HOME` would cover the per-user pair as well, but the setup file does not redirect it, 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 that the layers add, because a shared setup establishes the environment in which the rest run.
+- **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`, `core.attributesFile`, and `maintenance.auto=false` 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, and a command such as `git commit` does not start a detached `git maintenance` process that could still be writing under `.git` when the test removes the repository. Those last two need a step of their own: Because neither path is config-derived, git resolves each from `$XDG_CONFIG_HOME/git/`, or from `~/.config/git/` when that variable is unset, whatever the config variables say. `GIT_CONFIG_GLOBAL` already replaces `$XDG_CONFIG_HOME/git/config`; those two are the rest of what that directory supplies. The system attributes file at `$(prefix)/etc/gitattributes` is not named by any config variable at all, which is what `GIT_ATTR_NOSYSTEM` covers. Redirecting `XDG_CONFIG_HOME` would cover the per-user pair as well, but the setup file does not redirect it, 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 that the layers add, because a shared setup establishes the environment in which the rest run.
 
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -77,7 +77,7 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.13.2",
+    "@williamthorsen/nmr-core": "0.13.3",
     "@williamthorsen/toolbelt.errors": "0.8.3",
     "@williamthorsen/toolbelt.filesystem": "0.9.3",
     "glob": "13.0.6",