@williamthorsen/nmr 0.34.0 → 0.35.0

package/dist/esm/steps.d.ts

@@ -1,3 +1,13 @@
+/**
+ * One element of a resolved command chain, carrying how it was composed rather than how its text reads.
+ * A `structural` step is nmr's own composition, held as argv; an `opaque` step is a command nmr does not parse.
+ *
+ * A structural step's argv leads with the file to spawn, so the runner has one to hand `spawn` without a shell.
+ *
+ * `declinesArgs` travels from the composite element that composed the step to the one reader that acts on it,
+ * the binding of the invocation's trailing arguments. Every stage between the two -- the devBin substitution,
+ * the chain rendering, the replay assembly, the runner -- passes it through and asks nothing of it.
+ */
 export type Step = {
     kind: 'opaque';
     command: string;
@@ -6,19 +16,80 @@ export type Step = {
     argv: readonly [string, ...(readonly string[])];
     declinesArgs?: boolean;
 };
+/** What a structural step asks of the nmr process it spawns. */
 export interface NmrStepTarget {
     command: string;
+    /** Whether the command is fanned out to other scopes, where a `-R` or `-F` sends it. */
     isDelegate: boolean;
+    /** Whether the command runs against the root registry, where a `-w` anchors it. */
     isWorkspaceRoot: boolean;
 }
+/**
+ * How a `package.json` entry names the command it is declared under: as its whole value, or alongside other
+ * steps. `sole` covers an entry carrying trailing arguments, which declare no step of their own.
+ */
 export type SelfReference = 'chained' | 'sole';
+/**
+ * Composes the structural step that re-invokes nmr for one composite element.
+ *
+ * The element tokenizes on whitespace, so it may carry nmr's own flags but cannot carry a space-bearing token.
+ * `-w` is prepended as its own token, so the child selects the root registry on its own.
+ *
+ * `declinesArgs` is set only where it holds, so a step that takes the trailing arguments renders and compares
+ * exactly as it did before any element declared anything.
+ */
 export declare function composeNmrStep(element: string, workspaceRoot: boolean, declinesArgs?: boolean): Step;
+/**
+ * Returns the text of the first opaque step that reaches nmr through a shell, or `undefined` when none does.
+ *
+ * Recognizes nmr in command position: at the start of the step, after `&&`, `||`, `;`, `|`, or a newline, past
+ * any leading environment assignments, and behind a launcher such as `npx` or `pnpm exec`. A separator inside
+ * quotes opens no position, so a command merely naming nmr in an argument is not a crossing.
+ *
+ * Partial by construction, and partial in stated ways rather than arbitrary ones: a value-taking flag standing
+ * immediately before the program name hides it (`npx -p foo nmr`), and a launcher outside `LAUNCHERS` goes
+ * unreported. What it finds is the boundary below which nmr cannot tell its own processes from the tools it
+ * runs.
+ */
 export declare function findNmrCrossing(steps: readonly Step[]): string | undefined;
+/**
+ * Returns the first token of a composite element that falls outside the grammar, or `undefined` when the
+ * element is a command name optionally preceded by nmr's own flags. A token the shell would not read
+ * literally is one the rendering would quote whole, turning the element into a command nobody wrote.
+ */
 export declare function findUnexpressibleToken(element: string): string | undefined;
+/**
+ * Returns the command a structural step's nmr process runs, whether the step hands that command to other
+ * scopes rather than running it where it stands, and whether it anchors the command at the monorepo root.
+ * Reports nothing for a step that names no nmr command.
+ *
+ * The inverse of `composeNmrStep`, and beside it because the two share one grammar: an element may lead with
+ * nmr's own flags, and the command is the first token that is not one.
+ */
 export declare function readNmrStep(step: Step): NmrStepTarget | undefined;
+/**
+ * Reports whether a `package.json` entry re-invokes the command it is declared under, and whether it declares
+ * anything besides. Reports nothing for an entry that names another command, or none.
+ *
+ * Honouring such an entry would spawn a shell running the same command in the same directory, reaching the
+ * same entry again without bound, so resolution discards it however it reads. `chained` is what separates an
+ * entry that thereby loses steps from one that declares nothing to lose.
+ *
+ * A segment that delegates carries the command to other scopes rather than back to this one. `-w` re-enters
+ * only from the root, a package's entry reaching the root's registry and `package.json` instead of its own.
+ *
+ * Partial in the same ways `findNmrCrossing` is, and for the same reason: what goes unrecognized re-enters
+ * without bound, which hangs rather than passing quietly.
+ */
 export declare function readSelfReference(options: {
     anchoredAtRoot: boolean;
     commandName: string;
     script: string;
 }): SelfReference | undefined;
+/**
+ * Renders a step list as the `&&` chain a shell runs.
+ *
+ * The sole producer of a chain string: the check-result cache keys on that string, so a change to the rendering
+ * invalidates every recorded pass by construction rather than by anyone remembering to.
+ */
 export declare function renderChain(steps: readonly Step[]): string;

package/dist/esm/taze.d.ts

@@ -1,5 +1,21 @@
 import type { CheckOptions } from 'taze';
+/**
+ * A taze configuration.
+ *
+ * Every property admits `undefined` explicitly, unlike `Partial<CheckOptions>`, which rejects it under
+ * `exactOptionalPropertyTypes`. Passing `undefined` is how a consumer clears `maturityPeriod`, so the type
+ * has to allow it.
+ */
 export type TazeConfig = {
     [K in keyof CheckOptions]?: CheckOptions[K] | undefined;
 };
+/**
+ * Builds a taze configuration from nmr's shared upgrade policy and a repo's own settings.
+ *
+ * Any property the caller supplies wins, including `0` and an explicit `undefined` — the latter restores
+ * taze's inheritance of pnpm's `minimumReleaseAge`, which only applies while `maturityPeriod` is unset.
+ *
+ * The merge is shallow, which suits a policy of scalar defaults. A nested default would clobber rather
+ * than merge, so adding one means revisiting this.
+ */
 export declare function defineConfig(config: TazeConfig): TazeConfig;

package/dist/esm/tests.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Declares a suite asserting that a repo's test files hold to nmr's conventions: every collected file names an
+ * isolation tier, and every test file sits under a `__tests__` directory.
+ *
+ * Wire it from a one-line test of the repo's own, so the file stays under the repo's `__tests__` and the repo
+ * scopes what the sweep covers. Both halves are silent without it: `unit` is the residual project, so an untiered
+ * file runs and passes, and a file outside `__tests__` is collected by nothing at all.
+ *
+ * `exclude` names directory basenames the sweep prunes at any depth, additive to the ones nmr always prunes. Pass
+ * the same array to `defineVitestConfig`'s `testCollectionExclude`, or the sweep and the collection glob describe
+ * different trees: a directory pruned here alone still runs the files this suite stopped reporting.
+ */
+export declare function checkTestFileConventions(options?: TestFileConventionsOptions): void;
+/**
+ * Sweeps a repo for both halves of the convention, reporting the root it swept alongside what it found.
+ *
+ * The root is what makes the result trustworthy, and it is the one thing an assertion cannot check: a sweep
+ * started from the directory Vitest supplies covers one package, finds nothing, and passes.
+ *
+ * @internal - Exported only to enable testing
+ */
+export declare function reportTestFileConventions({ exclude, rootDir, }?: TestFileConventionsOptions): TestFileConventionsReport;
+export interface TestFileConventionsOptions {
+    /**
+     * Directory basenames the sweep prunes at any depth, additive to the ones nmr always prunes. The array a repo
+     * passes here is the array it passes to `defineVitestConfig`'s `testCollectionExclude`.
+     */
+    exclude?: readonly string[];
+    /**
+     * The directory to sweep. Defaults to the monorepo root found from the working directory, so one call covers the
+     * whole repo from whichever package Vitest started in.
+     */
+    rootDir?: string;
+}
+/** What one sweep found, and the root it found it in. Paths are relative to that root and POSIX-separated. */
+export interface TestFileConventionsReport {
+    misplaced: string[];
+    rootDir: string;
+    untiered: string[];
+}

package/dist/esm/tests.js

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { findMisplacedTestFiles, findUntieredTestFiles, TIER_NAMES } from "./tiers.js";
+import { findMonorepoRoot } from "./workspace.js";
+const MISPLACED_REMEDY = 'Every test file must sit under a `__tests__` directory, the only place the shared Vitest config collects from. Move each file below into one, or name its directory in `exclude`.';
+const UNTIERED_REMEDY = `Every collected test file must name its isolation tier in the segment before \`.test.\`, one of: ${TIER_NAMES.join(', ')}. Rename each file below to <subject>[.<aspect>].<tier>.test.ts.`;
+export function checkTestFileConventions(options = {}) {
+    describe('test file conventions', () => {
+        const { misplaced, rootDir, untiered } = reportTestFileConventions(options);
+        it('every collected test file names its tier', () => {
+            expect(untiered, `${UNTIERED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
+        });
+        it('every test file sits under a __tests__ directory', () => {
+            expect(misplaced, `${MISPLACED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
+        });
+    });
+}
+export function reportTestFileConventions({ exclude, rootDir, } = {}) {
+    const sweptRoot = rootDir ?? findMonorepoRoot();
+    const scanOptions = { ...(exclude !== undefined && { exclude }) };
+    return {
+        misplaced: findMisplacedTestFiles(sweptRoot, scanOptions),
+        rootDir: sweptRoot,
+        untiered: findUntieredTestFiles(sweptRoot, scanOptions),
+    };
+}

package/dist/esm/tiers.d.ts

@@ -1,7 +1,62 @@
+/** Collection patterns for the residual project, which claims every test file the named tiers leave. */
 export declare const ALL_TEST_PATTERNS: string[];
+/** Builds the collection patterns for one tier. */
 export declare function buildTierPatterns(tier: string): string[];
-export declare function findTestFiles(rootDir: string): string[];
+/**
+ * Walks `rootDir` for every `*.test.ts` or `*.test.tsx` file sitting outside a `__tests__` directory, returning
+ * paths relative to it, POSIX-separated and sorted.
+ *
+ * No project collects such a file, so it runs nowhere and reports nothing. Only a sweep of the tree tells it apart
+ * from a file that runs and passes.
+ */
+export declare function findMisplacedTestFiles(rootDir: string, options?: TestFileScanOptions): string[];
+/**
+ * Walks `rootDir` for every test file the shared config's projects collect, returning paths relative to it,
+ * POSIX-separated and sorted.
+ *
+ * A walk, because `node:fs` `globSync` does not descend into a dot-directory and honours no option that would make
+ * it. Vitest's globber does, so the same pattern string means different things to the two: a check built on the glob
+ * would report clean over every test file under a dot-directory.
+ */
+export declare function findTestFiles(rootDir: string, options?: TestFileScanOptions): string[];
+/**
+ * Walks `rootDir` for every collected test file whose name selects no tier, returning paths relative to it,
+ * POSIX-separated and sorted.
+ *
+ * `unit` is the residual project, so such a file runs under it and reports success: no test run tells it apart from
+ * a conformant file.
+ */
+export declare function findUntieredTestFiles(rootDir: string, options?: TestFileScanOptions): string[];
+/**
+ * Reports whether a test file's name selects a tier.
+ *
+ * Only the dot-delimited segment immediately before `.test.` selects one, so any earlier segment is free-form
+ * documentation: `scaffold.packaged.unit.test.ts` names the `unit` tier.
+ */
 export declare function hasTierInfix(filePath: string): boolean;
+/**
+ * Directory names that hold no test worth collecting: dependencies, build output, and generated reports.
+ *
+ * The one point where the collection glob and the walk must agree about scope. Over-reporting is a failure a
+ * consumer cannot fix; under-reporting is the silence a conformance check exists to end.
+ */
 export declare const TEST_COLLECTION_EXCLUDE: string[];
+/** Options every sweep over a repo's test files takes. */
+export interface TestFileScanOptions {
+    /**
+     * Directory basenames pruned at any depth, additive to `TEST_COLLECTION_EXCLUDE`.
+     *
+     * Basenames rather than globs, so the array a repo passes here is the array it passes to the shared Vitest
+     * config's `testCollectionExclude`. A directory pruned from the sweep but still collected by Vitest is the
+     * silence these sweeps exist to end.
+     */
+    exclude?: readonly string[];
+}
+/**
+ * The isolation ladder, ordered by the furthest thing a test reaches. 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 `tsc` would be.
+ * Each named tier's name is also its filename infix, so `parse.tool.test.ts` lands in `tool`.
+ */
 export declare const TIER_NAMES: readonly ["unit", "tool", "localhost", "remote"];
+/** One of the four isolation tiers. */
 export type TierName = (typeof TIER_NAMES)[number];

package/dist/esm/tiers.js

@@ -8,10 +8,14 @@ export const ALL_TEST_PATTERNS = [`${TEST_GLOB_PREFIX}/*.test.${TEST_EXTENSIONS}
 export function buildTierPatterns(tier) {
     return [`${TEST_GLOB_PREFIX}/*.${tier}.test.${TEST_EXTENSIONS}`];
 }
-export function findTestFiles(rootDir) {
-    const found = [];
-    collectTestFiles(rootDir, '', false, found);
-    return found.toSorted();
+export function findMisplacedTestFiles(rootDir, options = {}) {
+    return walkTestFiles(rootDir, options, true);
+}
+export function findTestFiles(rootDir, options = {}) {
+    return walkTestFiles(rootDir, options, false);
+}
+export function findUntieredTestFiles(rootDir, options = {}) {
+    return findTestFiles(rootDir, options).filter((file) => !hasTierInfix(file));
 }
 export function hasTierInfix(filePath) {
     const tiers = TIER_NAMES;
@@ -19,17 +23,26 @@ export function hasTierInfix(filePath) {
 }
 export const TEST_COLLECTION_EXCLUDE = ['.git', 'coverage', 'dist', 'node_modules'];
 export const TIER_NAMES = ['unit', 'tool', 'localhost', 'remote'];
-function collectTestFiles(dir, relativeDir, inTestDir, found) {
+function collectTestFiles(dir, relativeDir, inTestDir, context) {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
         const relativePath = relativeDir === '' ? entry.name : `${relativeDir}/${entry.name}`;
         if (entry.isDirectory()) {
-            if (TEST_COLLECTION_EXCLUDE.includes(entry.name))
+            if (context.pruned.has(entry.name))
                 continue;
-            collectTestFiles(path.join(dir, entry.name), relativePath, inTestDir || entry.name === TEST_DIR, found);
+            collectTestFiles(path.join(dir, entry.name), relativePath, inTestDir || entry.name === TEST_DIR, context);
         }
-        else if (inTestDir && TEST_FILE_PATTERN.test(entry.name)) {
-            found.push(relativePath);
+        else if (inTestDir !== context.misplaced && TEST_FILE_PATTERN.test(entry.name)) {
+            context.found.push(relativePath);
         }
     }
 }
+function walkTestFiles(rootDir, { exclude = [] }, misplaced) {
+    const context = {
+        found: [],
+        misplaced,
+        pruned: new Set([...TEST_COLLECTION_EXCLUDE, ...exclude]),
+    };
+    collectTestFiles(rootDir, '', false, context);
+    return context.found.toSorted();
+}

package/dist/esm/types.d.ts

@@ -2,16 +2,43 @@ import type { ScriptValue } from './default-scripts.js';
 import type { CommandVerbosity } from './verbosity.js';
 export type { ScriptValue, StepSpec } from './default-scripts.js';
 export type { CommandVerbosity } from './verbosity.js';
+/** Build settings honored by `nmr-compile`. */
 export interface BuildConfig {
+    /**
+     * Patterns added to the build's default ignore set. Extends rather than replaces, so that declaring one pattern
+     * cannot silently drop the defaults and start shipping a package's own tests.
+     * The programmatic `buildPackage` option of the same name behaves identically; its bare `ignorePatterns` replaces.
+     */
     extraIgnorePatterns?: string[];
 }
+/** Check-result cache settings honored at the monorepo root. */
 export interface CheckCacheConfig {
+    /** Set to `false` to turn the gate off entirely, so every command runs. */
     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.
+     */
     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.
+     */
     extraCommands?: string[];
 }
+/** Output settings honored at the monorepo root. */
 export interface OutputConfig {
+    /**
+     * The verbosity a run takes when neither `-q` nor the environment named one. Both of those outrank it, and it
+     * outranks agent-harness detection, so `full` here is also how a repo declines to be detected.
+     */
     commandVerbosity?: CommandVerbosity;
+    /**
+     * Environment-variable names added to the set whose presence marks an agent harness. Extends rather than
+     * replaces, so that declaring one name cannot silently drop the shipped list, and a repo absorbs a harness's
+     * rename without waiting for an nmr release.
+     */
     extraAgentEnvVars?: string[];
 }
 export interface NmrConfig {

package/dist/esm/verbosity.d.ts

@@ -1,18 +1,55 @@
 import type { OutputConfig } from './types.js';
+/**
+ * Environment variables a known agent harness sets, whose presence selects quiet when no level above them chose.
+ * The identifiers belong to ecosystems nmr does not control and that rename, so `output.extraAgentEnvVars` extends
+ * this list rather than a repo waiting for a release. `ROVO_CLI` anticipates a rename of `ROVODEV_CLI` that Rovo
+ * has signalled but not made; a variable nobody sets never fires.
+ */
 export declare const AGENT_ENV_VARS: readonly ["CLAUDECODE", "ROVODEV_CLI", "ROVO_CLI"];
+/**
+ * The points on the loudness ladder. Both are spelled out rather than leaving `full` implicit in the variable's
+ * absence, so a repo-level default is overridable from the environment in either direction.
+ */
 export declare const COMMAND_VERBOSITIES: readonly ["full", "quiet"];
+/**
+ * Carries the resolved verbosity down the spawned chain, so `-q` reaches every process rather than the first.
+ * Deliberately not a keyed variable: it changes what a run prints and never what a command concludes, so folding
+ * it into the cache key would stop a quiet run from hitting a pass a loud one recorded.
+ */
 export declare const COMMAND_VERBOSITY_ENV_VAR = "NMR_COMMAND_VERBOSITY";
+/** How loudly nmr reports the output of the commands it runs, which is never its own verdicts. */
 export type CommandVerbosity = (typeof COMMAND_VERBOSITIES)[number];
+/**
+ * Renders the rejection of a value off the loudness ladder, naming where it was written. Every source that accepts
+ * a verbosity renders through this, so no two of them can come to name different ladders.
+ */
 export declare function formatVerbosityRejection(source: string, value: string): string;
+/** Narrows a raw value to a point on the loudness ladder. */
 export declare function isCommandVerbosity(value: string): value is CommandVerbosity;
+/**
+ * Reads the verbosity the environment names. An unrecognized value resolves to nothing at all, since falling back
+ * would pick a mode nobody chose and hide a misspelling for the life of the shell.
+ *
+ * An unset or empty variable names no verbosity rather than resolving to `full`, which is what leaves the config
+ * and detection levels reachable: a floor written in here would outrank both of them.
+ */
 export declare function readVerbosityEnv(env: NodeJS.ProcessEnv): VerbosityRead;
 export interface ResolveVerbosityOptions {
+    /** Read for the detection level, and for that alone: the variable this module owns arrives as `envVerbosity`. */
     env: NodeJS.ProcessEnv;
     envVerbosity: CommandVerbosity | undefined;
     output: OutputConfig | undefined;
     quietFlag: boolean;
 }
+/**
+ * Resolves the verbosity this process runs at: the flag, then the environment, then the repo's config, then
+ * detection of a known agent harness, then `full`.
+ *
+ * Total by construction. The environment was validated as it was read and the config as it was loaded, so no
+ * rejection is left for this to report and the whole ladder reads in one place.
+ */
 export declare function resolveVerbosity(options: ResolveVerbosityOptions): CommandVerbosity;
+/** The verbosity the environment names, if any, or the message naming why its value could not be read. */
 export type VerbosityRead = {
     ok: true;
     verbosity?: CommandVerbosity;

package/dist/esm/verdict.d.ts

@@ -1,11 +1,35 @@
 import type { Writable } from 'node:stream';
 import type { ReplayLine } from './check-cache.js';
 import type { ReportFormat } from './report-format.js';
+/**
+ * The ceiling a rendered verdict, its newline included, is held to.
+ *
+ * POSIX guarantees a write at or below `PIPE_BUF` reaches a pipe whole, and 512 is the smallest bound the
+ * standard permits, so one write of a line this size cannot be interleaved by a concurrent scope under
+ * `pnpm --recursive`. No Node API reports the platform's own bound, and a per-platform table would move the
+ * truncation point from one machine to the next. The ceiling governs pipes: a terminal offers no such
+ * guarantee at any size.
+ */
 export declare const VERDICT_LINE_LIMIT = 512;
+/**
+ * What a command nmr ran came to, holding the facts a reporting line is rendered from rather than the line
+ * itself, so a machine-readable rendering spends the same record a human-readable one does.
+ *
+ * A recalled pass carries its saving as a duration and not as a decision about whether to mention it: whether
+ * one is worth naming belongs to rendering, and a consumer bypassing the renderer inherits neither the
+ * threshold nor an obligation to restate it.
+ */
 export type Verdict = {
     command: string;
     scope: string;
 } & VerdictOutcome;
+/**
+ * How a command ended, together with the facts that ending carries and no other does, and the trailing detail
+ * a line reserves room for.
+ *
+ * A recalled pass carries the excerpts it replays rather than a composed detail string, so the marker naming
+ * them a recording, and the ceiling they are held to, stay with the module that owns the line's grammar.
+ */
 export type VerdictOutcome = {
     detail?: string;
 } & ({
@@ -24,6 +48,27 @@ export type VerdictOutcome = {
     outcome: 'no-op';
     reason: 'empty-override' | 'noop-override';
 });
+/**
+ * Renders a verdict as the line nmr reports it on, without the newline that terminates it.
+ *
+ * The line ends without terminal punctuation and reserves its tail for `detail`, so a later change appends to
+ * the grammar rather than rewriting it. A detail carrying nothing but line breaks takes its whole clause with
+ * it, rather than leaving a separator pointing at nothing.
+ */
 export declare function renderVerdict(verdict: Verdict): string;
+/**
+ * Renders a verdict as the JSON object a machine consumer reads, without the newline that terminates it.
+ *
+ * Held to the ceiling the prose line is held to, so one write still reaches a pipe whole where concurrent
+ * scopes share a descriptor. Cuts land inside the record's text rather than across its structure, which is
+ * what leaves the line parseable, and a record is fitted by rungs, each shedding what a reader can better
+ * spare than the rung below it. What the ceiling costs is [documented](../README.md#reporting-for-a-machine)
+ * in the same order.
+ */
 export declare function serializeVerdict(verdict: Verdict): string;
+/**
+ * Writes a verdict to a stream as a single write, which is what holds a line together when concurrent scopes
+ * share one descriptor. Both renderings spend the one record, so neither can come to report what the other
+ * does not.
+ */
 export declare function writeVerdict(verdict: Verdict, stream: Writable, format: ReportFormat): void;

package/dist/esm/vitest.d.ts

@@ -1,21 +1,91 @@
-import type { ViteUserConfig } from 'vitest/config';
+import { type ViteUserConfig } from 'vitest/config';
 import type { InlineConfig, ProjectConfig } from 'vitest/node';
-import type { TierName } from './tiers.js';
+import { type TierName } from './tiers.js';
 export type { TierName } from './tiers.js';
+/**
+ * Test options Vitest honours only at the root of a `projects` config. Derived from Vitest's own types rather than
+ * hand-listed, so an option that changes scope in a later release changes scope here too.
+ */
 export type RootTestOptions = Omit<InlineConfig, keyof ProjectConfig>;
+/** Root-scoped overrides: Vite-level options plus the test options that survive at the root. */
 export type RootOverrides = Omit<ViteUserConfig, 'test'> & {
     test?: RootTestOptions;
 };
 export interface VitestConfigOptions {
+    /**
+     * Merged into the root config, which every project inherits because each declares `extends: true`.
+     *
+     * `resolve` is per-environment. Vitest resolves a test's own imports through the server environment, so a
+     * condition meant for them goes under `ssr`; a top-level `resolve.conditions` entry reaches the client
+     * environment, which only browser-mode tests resolve through.
+     */
     root?: RootOverrides;
+    /** Merged into every declared project. This is where per-project options such as `setupFiles` go. */
     project?: ProjectConfig;
+    /**
+     * Merged into one tier's project alone, after this layer's `project` block. Raising a budget for `tool` here
+     * leaves `unit` on the tight default that makes a hung unit test fail fast, which a uniform `project` override
+     * would flatten.
+     */
     tiers?: Partial<Record<TierName, ProjectConfig>>;
+    /**
+     * Directory basenames kept out of every project's collection, additive to the ones the shared config always
+     * prunes. Each name is matched at any depth, and every layer's entries are concatenated rather than the last
+     * winning, matching the config's rule for arrays.
+     *
+     * The same array declares the scope of nmr's exported test-file conventions check, so the sweep and the
+     * collection glob cannot drift. Excluding a directory from the sweep alone leaves a test file that runs and
+     * reports nothing; excluding it from collection alone leaves a report a consumer cannot act on. A repo wanting
+     * a glob rather than a directory name has the `project` seam's own `exclude`.
+     */
+    testCollectionExclude?: readonly string[];
+    /**
+     * Loads nmr's git-isolation setup file into every project, ahead of any the layers supply. Defaults to `true`.
+     * Turn it off only where a suite is meant to read the developer's own git configuration.
+     */
     isolateGit?: boolean;
+    /**
+     * Resolves workspace packages through their `source` export condition, so a suite runs without a prior build.
+     * Defaults to `true`. A package declaring no such condition is unaffected.
+     */
     resolveFromSource?: boolean;
+    /**
+     * Resolves a specifier through the `paths` a `tsconfig.json` declares, so a test reaches an alias the way `tsc`
+     * does. Defaults to `false`, matching Vite, and requires Vite 8.
+     *
+     * Not a default, because both directions are safe to leave to the consumer: omitting it fails loudly with an
+     * unresolved import, while turning it on for a repo that declares `paths` for `tsc` alone changes which module a
+     * specifier reaches with nothing in the run reporting it. A repo declaring no `paths` is unaffected either way.
+     */
+    tsconfigPaths?: boolean;
 }
 export interface RootVitestConfigOptions extends VitestConfigOptions {
+    /**
+     * An absolute path to the monorepo root, which must hold `pnpm-workspace.yaml`. A root config sits at that
+     * directory by construction, so this is `import.meta.dirname`. Stated rather than searched for: resolving it
+     * from the working directory would make the config describe whichever monorepo the run happened to start in.
+     */
     monorepoRoot: string;
 }
+/** Any number of shared layers, then the config file's own, which states the monorepo root. */
 type RootConfigLayers = [...(VitestConfigOptions | undefined)[], RootVitestConfigOptions];
+/**
+ * Builds the shared Vitest config for a workspace package, declaring the `unit`, `tool`, `localhost`, and `remote`
+ * projects. Select them at run time with `--project`, which unions when repeated and accepts negation.
+ *
+ * Layers fold left to right, later winning and arrays composing, so a config file shares settings by passing a
+ * layer ahead of its own. Merging two of this function's *outputs* is not the way: both declare the same four
+ * project names, which Vitest rejects at startup.
+ *
+ * An `undefined` layer is skipped, so `defineVitestConfig(shared, isCI ? ciLayer : undefined)` composes.
+ */
 export declare function defineVitestConfig(...layers: (VitestConfigOptions | undefined)[]): ViteUserConfig;
+/**
+ * Builds the shared Vitest config for repo-root tests. Excludes every workspace package from all projects, and
+ * reports no coverage of its own — packages cover their own sources.
+ *
+ * `monorepoRoot` rides on the last layer, which is the config file's own: a shared layer describes settings, not
+ * which repo they belong to, and only the root config's `import.meta.dirname` states this one. The guard below
+ * still catches the JavaScript config that types never reach.
+ */
 export declare function defineRootVitestConfig(...layers: RootConfigLayers): ViteUserConfig;

package/dist/esm/vitest.js

@@ -11,7 +11,6 @@ const GIT_ISOLATION_SETUP_FILE = resolveGitIsolationSetupFile();
 const SOURCE_CLIENT_CONDITIONS = ['source', 'module', 'browser', 'development|production'];
 const SOURCE_SERVER_CONDITIONS = ['source', 'module', 'node', 'development|production'];
 const COVERAGE_EXCLUDE = ['**/__{fixtures,mocks,tests}__/**', '**/index.ts', '**/*.d.ts'];
-const COLLECTION_EXCLUDE = [...new Set([...defaultExclude, ...TEST_COLLECTION_EXCLUDE.map((dir) => `**/${dir}/**`)])];
 const PACKAGE_COVERAGE_INCLUDE = ['**/src/**/*.{ts,tsx}'];
 const MISSING_MONOREPO_ROOT = 'defineRootVitestConfig requires `monorepoRoot`, an absolute path to the directory holding pnpm-workspace.yaml. Pass `import.meta.dirname` in the last options layer, from the root config.';
 export function defineVitestConfig(...layers) {
@@ -32,11 +31,14 @@ export function defineRootVitestConfig(...layers) {
 function buildConfig(declaredLayers, { coverageInclude, projectExclude = [], projectRoot }) {
     const layers = declaredLayers.filter((layer) => layer !== undefined);
     assertKnownTiers(layers);
+    const resolveFromSource = resolveFlag(layers, 'resolveFromSource', true);
+    const resolve = {
+        ...(resolveFromSource && { conditions: SOURCE_CLIENT_CONDITIONS }),
+        ...(resolveFlag(layers, 'tsconfigPaths', false) && { tsconfigPaths: true }),
+    };
     const config = {
-        ...(resolveFlag(layers, 'resolveFromSource') && {
-            resolve: { conditions: SOURCE_CLIENT_CONDITIONS },
-            ssr: { resolve: { conditions: SOURCE_SERVER_CONDITIONS } },
-        }),
+        ...(Object.keys(resolve).length > 0 && { resolve }),
+        ...(resolveFromSource && { ssr: { resolve: { conditions: SOURCE_SERVER_CONDITIONS } } }),
         test: {
             coverage: {
                 enabled: false,
@@ -67,13 +69,14 @@ function buildProjects(layers, extraExclude, projectRoot) {
             timeout: TIER_TIMEOUT,
         })),
     ];
-    const isolateGit = resolveFlag(layers, 'isolateGit');
+    const collectionExclude = buildCollectionExclude(layers);
+    const isolateGit = resolveFlag(layers, 'isolateGit', true);
     return projectTiers.map(({ exclude, include, name, timeout }) => {
         const project = {
             extends: true,
             ...(projectRoot !== undefined && { root: projectRoot }),
             test: {
-                exclude: [...COLLECTION_EXCLUDE, ...exclude, ...extraExclude],
+                exclude: [...collectionExclude, ...exclude, ...extraExclude],
                 include,
                 name,
                 ...(isolateGit && { setupFiles: [GIT_ISOLATION_SETUP_FILE] }),
@@ -103,13 +106,18 @@ function assertKnownTiers(layers) {
         }
     }
 }
+function buildCollectionExclude(layers) {
+    const declared = layers.flatMap((layer) => layer.testCollectionExclude ?? []);
+    const globs = [...TEST_COLLECTION_EXCLUDE, ...declared].map((dir) => `**/${dir}/**`);
+    return [...new Set([...defaultExclude, ...globs])];
+}
 function getWorkspaceExcludePatterns(monorepoRoot) {
     return getWorkspacePackageDirs(monorepoRoot)
         .map((dir) => `${path.relative(monorepoRoot, dir).split(path.sep).join('/')}/**`)
         .toSorted();
 }
-function resolveFlag(layers, name) {
-    let resolved = true;
+function resolveFlag(layers, name, fallback) {
+    let resolved = fallback;
     for (const layer of layers) {
         const declared = layer[name];
         if (declared !== undefined)

package/dist/esm/workspace.d.ts

@@ -1,4 +1,22 @@
+/** Reports whether a directory is the monorepo root, which the workspace manifest's presence marks. */
 export declare function isMonorepoRoot(dir: string): boolean;
+/**
+ * Finds the monorepo root by walking up from `startDir` to find `pnpm-workspace.yaml`.
+ * Throws if no workspace root is found.
+ */
 export declare function findMonorepoRoot(startDir?: string): string;
+/**
+ * Reads the workspace patterns from `pnpm-workspace.yaml` and resolves them to absolute package
+ * directories, applying pnpm's pattern semantics — including `!`-prefixed exclusions.
+ *
+ * Returns an empty array when the manifest declares no usable `packages` list, and throws when
+ * `monorepoRoot` holds no manifest at all — the caller named a directory that is not a monorepo root.
+ */
 export declare function getWorkspacePackageDirs(monorepoRoot: string): string[];
+/**
+ * Reads the `overrides` block from the monorepo root's `pnpm-workspace.yaml`, the site pnpm reads an override
+ * from.
+ *
+ * Returns nothing when the manifest or the block is missing, and drops an entry whose value is not a string.
+ */
 export declare function readWorkspaceOverrides(monorepoRoot: string): Record<string, string> | undefined;