@williamthorsen/nmr 0.38.0 → 0.39.0

package/dist/esm/workspace.js

@@ -1,76 +1,18 @@
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
-import { parse } from 'yaml';
-import { readStringValues } from "./helpers/readStringValues.js";
-import { isObject } from "./helpers/type-guards.js";
-import { resolvePackageDirs } from "./helpers/workspace-patterns.js";
+import { findMonorepoRoot as findMonorepoRootOrNothing, resolveWorkspace } from '@williamthorsen/nmr-core/workspace';
 import { UserError } from "./UserError.js";
-const PACKAGE_MANIFEST = 'package.json';
 const WORKSPACE_MANIFEST = 'pnpm-workspace.yaml';
-export function isMonorepoRoot(dir) {
-    return existsSync(path.join(dir, WORKSPACE_MANIFEST));
-}
+export { isMonorepoRoot, readWorkspaceOverrides, readWorkspacePackageNames, resolveWorkspace, } from '@williamthorsen/nmr-core/workspace';
 export function findMonorepoRoot(startDir) {
-    let dir = path.resolve(startDir ?? process.cwd());
-    for (;;) {
-        if (isMonorepoRoot(dir)) {
-            return dir;
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir) {
-            throw new UserError(`Could not find monorepo root: no ${WORKSPACE_MANIFEST} found in any parent directory`);
-        }
-        dir = parent;
+    const monorepoRoot = findMonorepoRootOrNothing(startDir);
+    if (monorepoRoot === undefined) {
+        throw new UserError(`Could not find monorepo root: no ${WORKSPACE_MANIFEST} found in any parent directory`);
     }
+    return monorepoRoot;
 }
 export function getWorkspacePackageDirs(monorepoRoot) {
-    const workspaceFile = path.join(monorepoRoot, WORKSPACE_MANIFEST);
-    if (!existsSync(workspaceFile)) {
+    const resolution = resolveWorkspace(monorepoRoot);
+    if (resolution.kind === 'not-a-workspace') {
         throw new UserError(`Not a monorepo root: no ${WORKSPACE_MANIFEST} in ${monorepoRoot}`);
     }
-    const content = readFileSync(workspaceFile, 'utf8');
-    const parsed = parse(content);
-    const packages = getPackagesFromParsedYaml(parsed);
-    if (!packages) {
-        return [];
-    }
-    return resolvePackageDirs(monorepoRoot, packages);
-}
-export function readWorkspaceOverrides(monorepoRoot) {
-    const workspaceFile = path.join(monorepoRoot, WORKSPACE_MANIFEST);
-    if (!existsSync(workspaceFile)) {
-        return undefined;
-    }
-    const parsed = parse(readFileSync(workspaceFile, 'utf8'));
-    if (!isObject(parsed)) {
-        return undefined;
-    }
-    const overrides = parsed['overrides'];
-    return isObject(overrides) ? readStringValues(overrides) : undefined;
-}
-export function readWorkspacePackageNames(packageDirs) {
-    const names = [];
-    for (const dir of packageDirs) {
-        let parsed;
-        try {
-            parsed = JSON.parse(readFileSync(path.join(dir, PACKAGE_MANIFEST), 'utf8'));
-        }
-        catch {
-            continue;
-        }
-        if (isObject(parsed) && typeof parsed['name'] === 'string') {
-            names.push(parsed['name']);
-        }
-    }
-    return names;
-}
-function getPackagesFromParsedYaml(parsed) {
-    if (!isObject(parsed))
-        return undefined;
-    const packages = parsed['packages'];
-    if (!Array.isArray(packages))
-        return undefined;
-    if (!packages.every((p) => typeof p === 'string'))
-        return undefined;
-    return packages;
+    return resolution.kind === 'packages' ? resolution.packageDirs : [];
 }

package/docs/reporting.md

@@ -10,7 +10,11 @@ The scope is the directory the command's registry belongs to: a package's own di
 
 Verdicts nest. A composite reports, and so does every command it expands into; a `:pre` or `:post` hook reports nothing of its own, since the command it wraps already reports for the chain, though a hook that delegates to a named command reports under that name. A `-R` or `-F` invocation reports nothing either, every scope it fans out to reporting instead. A cold repo-wide `nmr ci` in this package's own monorepo spends 26 lines on a run that prints roughly 250.
 
-**A fan-out that selects no scope fails.** A `-F` pattern matches a package's manifest `name` rather than its directory name, so a plausible directory name selects nothing, and pnpm exits 0 over an empty selection as it does over a passing one. nmr asks pnpm what the pattern selects and refuses the invocation where the answer is nothing, naming the pattern and, where the pattern carries a name, the names it could have named. A pattern of another form states the rule its own shape answers to: a directory (`./dir`, `/dir`, `{dir}`), an exclusion (`!`), or a changed-since selector (`[<ref>]`), none of which a workspace name repairs. A pattern pnpm rejects rather than resolves, such as a bad git ref in a `[since]` selector, is left to pnpm to report. `-R` is refused on the same ground where the workspace declares no package at all, which is its only empty selection.
+**A fan-out that selects no scope fails.** A `-F` pattern matches a package's manifest `name` rather than its directory name, so a plausible directory name selects nothing, and pnpm exits 0 over an empty selection as it does over a passing one. nmr asks pnpm what the pattern selects and refuses the invocation where the answer is nothing, naming the pattern and, where the pattern carries a name, the names it could have named. A pattern of another form states the rule its own shape answers to: a directory (`./dir`, `/dir`, `{dir}`), an exclusion (`!`), or a changed-since selector (`[<ref>]`), none of which a workspace name repairs. A pattern pnpm rejects rather than resolves, such as a bad git ref in a `[since]` selector, is left to pnpm to report. A `-R` typed on the invocation is refused on the same ground where the workspace declares no package at all, which is its only empty selection. That condition answers ahead of the pattern rules above: where the workspace holds no package, no `-F` pattern would have matched, so the refusal reports the workspace rather than the shape of the pattern.
+
+**A workspace that holds no package is reported as one of four conditions.** `pnpm-workspace.yaml` may declare no positive pattern, declare patterns that match no directory holding a `package.json`, declare `!` exclusions that remove every directory matched by the positive patterns, or hold no valid YAML at all. Each refusal names its own condition and states a remedy, and each quotes the `packages` list the manifest declares, apart from the last, whose manifest nmr could not read. The second is the likeliest, because nmr [counts a directory as a package](workspace.md) only where it holds `package.json` and recognizes neither `package.yaml` nor `package.json5`.
+
+**A `-R` that nmr composed into a script is not a fan-out the caller asked for.** In a workspace that holds no package, such a step -- in nmr's own default script or in a repo override alike -- is dropped from the chain, the steps beside it run, and the dropped step reports nothing of its own, as the rule above gives a `-R` invocation whose scopes report instead. Where the drop leaves the command with no step at all, as it does the root `build`, the command reports a no-op naming the workspace. A repo that holds no workspace package therefore runs the default root commands with no entry in `.config/nmr.config.ts`.
 
 A verdict is one write of at most 512 bytes, the smallest `PIPE_BUF` POSIX permits, so packages running concurrently under `pnpm --recursive` cannot interleave within a line. A line longer than that is cut and marked with `…`; nothing nmr reports today comes near it.
 
@@ -32,7 +36,7 @@ Every object carries `command`, `scope`, and `outcome`, and then what that outco
 | `passed`   | `durationMs`                                                                                                             |
 | `failed`   | `durationMs`, `exitCode`                                                                                                 |
 | `recalled` | `ageMs`, `savedMs`, and `replay` where the skip has excerpts to [replay](check-cache.md#replaying-a-skipped-runs-output) |
-| `no-op`    | `reason`, either `empty-override` or `noop-override`                                                                     |
+| `no-op`    | `reason`, one of `empty-override`, `empty-workspace`, or `noop-override`                                                 |
 
 Both renderings are produced from one record, so neither reports what the other does not. Where the prose line makes a presentation decision the record does not — a saving too small to be worth a clause, say — the object carries the fact and leaves the decision to whoever reads it.
 

package/docs/vitest.md

@@ -84,17 +84,17 @@ The sweep starts at the monorepo root rather than at the directory Vitest suppli
 
 An exported check rather than a step nmr runs for you, because nothing nmr runs reaches the whole tree: `nmr test` fans out per package, and a direct `vitest` invocation runs no nmr script at all. A test the repo owns also lets the repo scope what the sweep covers.
 
-`exclude` names directory basenames the sweep prunes at any depth, additive to the ones nmr always prunes:
+`excludedBasenames` names directory basenames the sweep prunes at any depth, additive to the ones nmr always prunes:
 
 ```ts
-checkTestFileConventions({ exclude: ['cypress', 'generated'] });
+checkTestFileConventions({ excludedBasenames: ['cypress', 'generated'] });
 ```
 
 **Pass the same array to [`testCollectionExclude`](#what-the-config-excludes).** The two describe one scope, and naming a directory in only one is a defect in either direction. Pruned from the sweep alone, the directory's test files still run and still report nothing, which is the silence this check exists to end. Excluded from collection alone, the sweep reports files a consumer has no reason to act on.
 
 Expect the first run to fail in a repo that has never gated this. Vitest 4 excludes only `node_modules` and `.git` by default, so a `__tests__` tree under a generated or vendored directory is collected and runs today; naming that directory in both lists is the fix, rather than widening what nmr prunes for everyone.
 
-In a repo that has not declared the check, [nmr's readyup kit](../README.md#conformance-checks) reports both halves and warns that the check is missing. Once a test file under `__tests__` imports it, the kit skips both reports and names that file as the reason. Only the check reads the repo's `exclude`, and a kit report beside it could only repeat its findings or name a directory that the repo has pruned.
+In a repo that has not declared the check, [nmr's readyup kit](../README.md#conformance-checks) reports both halves and warns that the check is missing. Once a test file under `__tests__` imports it, the kit skips both reports and names that file as the reason. Only the check reads the repo's `excludedBasenames`, and a kit report beside it could only repeat its findings or name a directory that the repo has pruned.
 
 ## What the config supplies
 
@@ -106,12 +106,12 @@ Two settings a workspace test runner needs almost universally are part of what t
 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:
 
 ```ts
-export default defineVitestConfig({ isolateGit: false, resolveFromSource: false });
+export default defineVitestConfig({ shouldIsolateGit: false, shouldResolveFromSource: false });
 ```
 
-`resolveFromSource: false` is for a repo whose own packages declare a `source` condition that it does not want in tests; `isolateGit: false` is for a suite meant to read the developer's own git configuration.
+`shouldResolveFromSource: false` is for a repo whose own packages declare a `source` condition that it does not want in tests; `shouldIsolateGit: false` is for a suite meant to read the developer's own git configuration.
 
-**Vite replaces its condition defaults rather than extending them.** A config writing `conditions: ['my-condition']` by hand therefore drops `module`, so a dependency exposing a `module` entry falls through to whatever its `exports` lists next. A replaced list still resolves `node` and `development` under Vitest, which is why nothing in a test run reports the loss. The factory emits Vite's defaults for each environment, whichever way `resolveFromSource` is set, so a layer adding a condition extends a complete list rather than replacing one.
+**Vite replaces its condition defaults rather than extending them.** A config writing `conditions: ['my-condition']` by hand therefore drops `module`, so a dependency exposing a `module` entry falls through to whatever its `exports` lists next. A replaced list still resolves `node` and `development` under Vitest, which is why nothing in a test run reports the loss. The factory emits Vite's defaults for each environment, whichever way `shouldResolveFromSource` is set, so a layer adding a condition extends a complete list rather than replacing one.
 
 **The condition is resolved by a plugin rather than named as a Vite condition, which is what bounds its reach.** Vitest turns `ssr.resolve.conditions` into `--conditions` flags on the worker process, where Node applies every entry to each package that it resolves natively. Node refuses to strip types from a file under `node_modules`, so a `source` condition reaching that far makes any dependency declaring a TypeScript entry fail to load, the dependency of a dependency included. Resolving inside Vite keeps the condition where nmr decides its reach, and leaves a published package to resolve through its other conditions however it declares `source`.
 

package/docs/workspace.md

@@ -1,6 +1,8 @@
 # Workspace introspection
 
-The two pnpm-workspace lookups that `@williamthorsen/nmr/workspace` publishes.
+The pnpm-workspace lookups that `@williamthorsen/nmr/workspace` publishes. The resolution itself lives in
+`@williamthorsen/nmr-core/workspace`, which release-kit reads too; nmr re-exports the total primitives and adds
+two projections that throw, so a CLI caller keeps nmr's error boundary.
 
 `findMonorepoRoot(startDir?)` walks up from `startDir`, defaulting to `process.cwd()`, until it reaches a directory containing `pnpm-workspace.yaml`. It throws if it runs out of parent directories without finding one.
 
@@ -8,4 +10,25 @@ The two pnpm-workspace lookups that `@williamthorsen/nmr/workspace` publishes.
 
 One divergence from pnpm: a directory counts as a package only if it holds a `package.json`, not a `package.yaml` or `package.json5`.
 
+`resolveWorkspace(monorepoRoot)` is the primitive both projections read, and the one a caller reaches for when an empty workspace is not a failure. It throws nothing, returning a discriminated result instead:
+
+| `kind`            | What it carries                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `not-a-workspace` | Nothing. The directory holds no `pnpm-workspace.yaml`, so it declares no workspace at all.                   |
+| `packages`        | `packageDirs`, the resolved absolute directories, and `patterns`, the `packages` list the manifest declares. |
+| `empty`           | `cause`, which of four conditions emptied the resolution, and the same `patterns`.                           |
+
+| `cause`               | What left the workspace empty                                                                                                           |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `no-packages-list`    | The manifest declares no `packages` list: it holds no document, no `packages` key, a null value, or an empty list. `patterns` is empty. |
+| `no-pattern`          | The list reaches the matcher with nothing positive, holding only `!` entries or entries YAML left empty.                                |
+| `no-package`          | The patterns reach the matcher and match no directory holding a `package.json`, which is the divergence above.                          |
+| `all-excluded`        | The `!` entries exclude every directory matched by the positive patterns.                                                               |
+| `unreadable-packages` | The `packages` value is not a list of strings, so nothing it declares reaches the matcher. `patterns` is empty.                         |
+| `unreadable-manifest` | The manifest holds no valid YAML, so nothing it declares reaches the matcher. `patterns` is empty, and no other cause is decided.       |
+
+Three causes separate what the manifest declares from what the reader could make of it, because one remedy does not answer them all: `no-packages-list` is a manifest asking for nothing, which pnpm resolves to the root package alone; `unreadable-packages` is a manifest asking for something the reader refused; and `no-pattern` is a list read in full whose every entry failed to become a positive pattern. A caller treating an empty resolution as a failure needs the first held apart from the other two. A manifest the parser rejects outright is `unreadable-manifest`, because the pattern remedies repair nothing for a reader whose manifest declares a pattern above a syntax error. `all-excluded` is decided by matching the positive patterns a second time without the exclusion set, which reaches the filesystem only on this path, and only where the first resolution came back empty.
+
+`isMonorepoRoot(dir)`, `readWorkspaceOverrides(monorepoRoot)`, and `readWorkspacePackageNames(packageDirs)` are re-exported unchanged. Each returns a value rather than throwing: `readWorkspaceOverrides` returns nothing where the manifest is missing, unreadable, unparseable, or declares no `overrides` block, and `readWorkspacePackageNames` passes over a manifest it cannot read.
+
 Quote exclusion patterns in the manifest — `- '!packages/legacy'`. An unquoted `!` opens a YAML tag rather than a string, so the entry never reaches nmr (or pnpm) as a pattern.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -77,12 +77,11 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.12.0",
+    "@williamthorsen/nmr-core": "0.13.0",
     "@williamthorsen/toolbelt.errors": "0.8.1",
     "glob": "13.0.6",
     "prettier-plugin-sh": "0.19.0",
-    "taze": "21.1.0",
-    "yaml": "2.9.0"
+    "taze": "21.1.0"
   },
   "devDependencies": {
     "@williamthorsen/toolbelt.filesystem": "0.9.1",

package/dist/esm/helpers/workspace-patterns.d.ts

@@ -1,8 +0,0 @@
-/**
- * Resolves pnpm workspace patterns to absolute package directories.
- *
- * Applies pnpm's algorithm: every pattern is rewritten to match a manifest, `!`-prefixed patterns become
- * exclusions, and the matcher decides the rest. Exclusions filter the entire positive match set
- * irrespective of declaration order.
- */
-export declare function resolvePackageDirs(monorepoRoot: string, patterns: string[]): string[];

package/dist/esm/helpers/workspace-patterns.js

@@ -1,29 +0,0 @@
-import { globSync } from 'node:fs';
-import path from 'node:path';
-const MANIFEST = 'package.json';
-const ALWAYS_EXCLUDED = ['**/node_modules/**'];
-export function resolvePackageDirs(monorepoRoot, patterns) {
-    const included = [];
-    const excluded = [];
-    for (const pattern of patterns) {
-        if (pattern.trim() === '')
-            continue;
-        const isNegated = pattern.startsWith('!');
-        const target = isNegated ? excluded : included;
-        target.push(toManifestPattern(isNegated ? pattern.slice(1) : pattern));
-    }
-    if (included.length === 0) {
-        return [];
-    }
-    const options = {
-        cwd: monorepoRoot,
-        exclude: [...excluded, ...ALWAYS_EXCLUDED],
-        followSymlinks: true,
-    };
-    const matches = globSync(included, options);
-    const dirs = matches.map((match) => path.dirname(path.resolve(monorepoRoot, match)));
-    return [...new Set(dirs)].toSorted();
-}
-function toManifestPattern(pattern) {
-    return `${pattern.replace(/\/?$/, '')}/${MANIFEST}`;
-}