@williamthorsen/nmr 0.39.0 → 0.41.0

package/dist/esm/tiers.d.ts

@@ -1,30 +1,30 @@
-/** Collection patterns for the residual project, which claims every test file the named tiers leave. */
+/** Collection patterns for the residual project, which claims every test file that 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[];
 /**
- * Walks `rootDir` for every `*.test.ts` or `*.test.tsx` file sitting outside a `__tests__` directory, returning
- * paths relative to it, POSIX-separated and sorted.
+ * Walks `rootDir` for every `*.test.ts` or `*.test.tsx` file 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.
+ * The shared config's projects do not collect 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,
+ * Walks `rootDir` for every test file that 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.
+ * A walk, because `node:fs` `globSync` does not descend into a dot-directory and does not honour any 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,
+ * Walks `rootDir` for every collected test file whose name does not select a 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.
+ * Because `unit` is the residual project, such a file runs under it and reports success: A test run cannot tell it
+ * apart from a conformant file.
  */
 export declare function findUntieredTestFiles(rootDir: string, options?: TestFileScanOptions): string[];
 /**
@@ -35,27 +35,31 @@ export declare function findUntieredTestFiles(rootDir: string, options?: TestFil
  */
 export declare function hasTierInfix(filePath: string): boolean;
 /**
- * Directory names that hold no test worth collecting: dependencies, build output, and generated reports.
+ * Names of directories that do not contain any 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.
+ * These and the paths that git ignores are the scope on which the collection glob and the walk must agree.
+ * Over-reporting is a failure that a consumer cannot fix; under-reporting hides the violations that a conformance
+ * check exists to report.
  */
 export declare const TEST_COLLECTION_EXCLUDE: string[];
-/** Options every sweep over a repo's test files takes. */
+/** Options that every sweep over a repo's test files takes. */
 export interface TestFileScanOptions {
     /**
-     * Directory basenames pruned at any depth, additive to `TEST_COLLECTION_EXCLUDE`.
+     * Directory basenames pruned at any depth, additive to `TEST_COLLECTION_EXCLUDE` and to the paths that git
+     * ignores.
      *
-     * 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.
+     * Basenames rather than globs, so that a repo can pass the same array here and to the shared Vitest config's
+     * `testCollectionExclude`. Vitest still runs the files in a directory pruned from the sweep alone, and the sweep
+     * does not report them.
      */
     excludedBasenames?: 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`.
+ * The isolation ladder, ordered by the furthest thing that 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` is collected by the `tool`
+ * project.
  */
 export declare const TIER_NAMES: readonly ["unit", "tool", "localhost", "remote"];
 /** One of the four isolation tiers. */

package/dist/esm/tiers.js

@@ -1,5 +1,6 @@
 import { readdirSync } from 'node:fs';
 import path from 'node:path';
+import { listGitIgnoredPaths } from "./git-ignored-paths.js";
 const TEST_DIR = '__tests__';
 const TEST_EXTENSIONS = '{ts,tsx}';
 const TEST_GLOB_PREFIX = `**/${TEST_DIR}/**`;
@@ -28,11 +29,13 @@ function collectTestFiles(dir, relativeDir, isInTestDir, context) {
     for (const entry of entries) {
         const relativePath = relativeDir === '' ? entry.name : `${relativeDir}/${entry.name}`;
         if (entry.isDirectory()) {
-            if (context.pruned.has(entry.name))
+            if (context.pruned.has(entry.name) || context.ignoredPaths.has(`${relativePath}/`))
                 continue;
             collectTestFiles(path.join(dir, entry.name), relativePath, isInTestDir || entry.name === TEST_DIR, context);
         }
-        else if (isInTestDir !== context.misplaced && TEST_FILE_PATTERN.test(entry.name)) {
+        else if (isInTestDir !== context.misplaced &&
+            TEST_FILE_PATTERN.test(entry.name) &&
+            !context.ignoredPaths.has(relativePath)) {
             context.foundPaths.push(relativePath);
         }
     }
@@ -40,6 +43,7 @@ function collectTestFiles(dir, relativeDir, isInTestDir, context) {
 function walkTestFiles(rootDir, { excludedBasenames = [] }, misplaced) {
     const context = {
         foundPaths: [],
+        ignoredPaths: new Set(listGitIgnoredPaths(rootDir)),
         misplaced,
         pruned: new Set([...TEST_COLLECTION_EXCLUDE, ...excludedBasenames]),
     };

package/dist/esm/types.d.ts

@@ -6,7 +6,7 @@ export type { CommandVerbosity } from './verbosity.js';
 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.
+     * cannot silently drop the defaults and start publishing a package's own tests.
      * The programmatic `buildPackage` option of the same name behaves identically; its bare `ignorePatterns` replaces.
      */
     extraIgnorePatterns?: string[];
@@ -23,7 +23,7 @@ export interface CheckCacheConfig {
     /**
      * 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, and has to resolve to a command: both lists are read by name alone, so a misspelt
+     * 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[];
@@ -31,13 +31,13 @@ export interface CheckCacheConfig {
 /** 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.
+     * The verbosity that a run takes when neither `-q` nor the environment named one. Both of those outrank it.
+     * Because it outranks agent-harness detection, `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
+     * replaces, so that declaring one name cannot silently drop the built-in list, and a repo handles a harness's
      * rename without waiting for an nmr release.
      */
     extraAgentEnvVars?: string[];

package/dist/esm/verbosity.d.ts

@@ -1,55 +1,57 @@
 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.
+ * Environment variables that a known agent harness sets, whose presence selects quiet when every level above them
+ * left the verbosity unset. `output.extraAgentEnvVars` extends the list. `ROVO_CLI` anticipates a rename of
+ * `ROVODEV_CLI` that Rovo has signalled but not made.
  */
 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.
+ * absence, so that 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.
+ * Passes the resolved verbosity down the chain of spawned processes, so that `-q` applies to every process rather
+ * than only the first. The pass key does not include it: It changes what a run prints and never what a command
+ * concludes, so a quiet run can reuse a pass that a full run 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. */
+/** How loudly nmr reports the output of the commands that 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.
+ * Renders the rejection of a value off the loudness ladder, naming where it was written. Because every source that
+ * accepts a verbosity renders through this, the sources cannot 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.
+ * Reads the verbosity that the environment names. An unrecognized value is returned as an error, since a fallback
+ * would pick a mode that 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.
+ * For an unset or empty variable, this returns a result without a 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`. */
+    /**
+     * Read for the detection level, and for that alone: The caller passes the variable that this module owns as
+     * `envVerbosity`.
+     */
     env: NodeJS.ProcessEnv;
     envVerbosity: CommandVerbosity | undefined;
     hasQuietFlag: boolean;
     output: OutputConfig | undefined;
 }
 /**
- * Resolves the verbosity this process runs at: the flag, then the environment, then the repo's config, then
+ * Resolves the verbosity at which this process runs: 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.
+ * Total by construction. The environment was validated as it was read and the config as it was loaded, so this does
+ * not have any rejection left to report, and the whole ladder can be read 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. */
+/** The verbosity that 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

@@ -3,40 +3,41 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
 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.
+ * The ceiling to which a rendered verdict, its newline included, is held.
  *
- * 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.
+ * POSIX guarantees that a write at or below `PIPE_BUF` arrives in a pipe whole, and 512 is the smallest bound that
+ * the standard permits, so one write of a line this size cannot be interleaved by a concurrent scope under
+ * `pnpm --recursive`. Node does not have an API that reports the platform's own bound, and a per-platform table
+ * would move the truncation point from one machine to the next. The ceiling applies to pipes: A terminal does not
+ * offer that guarantee at any size.
  */
 export declare const VERDICT_LINE_LIMIT_BYTES = 512;
 /**
- * Why a command ran nothing, which the `no-op` outcome carries and `--json` serializes.
+ * Why a command ran nothing, which the `no-op` outcome includes and `--json` serializes.
  *
- * `empty-workspace` and `empty-override` both leave a chain with no step in it, so the reason is what tells
- * a command emptied by the workspace apart from one emptied by an override.
+ * `empty-workspace` and `empty-override` both leave a chain without any step in it, so the reason tells a command
+ * emptied by the workspace apart from one emptied by an override.
  */
 export type NoOpReason = 'empty-override' | 'empty-workspace' | 'noop-override';
 /**
- * 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.
+ * The result of a command that nmr ran. It contains the facts from which a reporting line is rendered rather than
+ * the line itself, which lets a machine-readable rendering use the same record as a human-readable one.
  *
- * 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.
+ * A recalled pass records 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.
+ * How a command ended, together with the facts specific to that ending, and the trailing detail for which a line
+ * reserves room.
  *
- * 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.
+ * A recalled pass contains the excerpts that it replays rather than a composed detail string, so that the marker
+ * naming them a recording, and the ceiling to which they are held, stay with the module that owns the line's
+ * grammar.
  */
 export type VerdictOutcome = {
     detail?: string;
@@ -57,29 +58,28 @@ export type VerdictOutcome = {
     reason: NoOpReason;
 });
 /**
- * Renders a verdict as the line nmr reports it on, without the newline that terminates it.
+ * Renders a verdict as the line on which nmr reports it, 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.
+ * The line ends without terminal punctuation and reserves its tail for `detail`, so that a later change appends to
+ * the grammar rather than rewriting it. When a detail contains nothing but line breaks, the line omits the detail's
+ * whole clause rather than leaving a separator pointing at nothing.
  *
- * The marker takes no padding column: every plain marker a verdict reaches for is four characters, so the
- * lines align by construction. `formatStatusLine` pads to a column that `BLOCK` widens, and no verdict is one.
+ * The marker does not take a padding column. Because every plain marker that a verdict uses is four characters,
+ * the lines align by construction. `formatStatusLine` pads to a column that `BLOCK` widens, and a verdict is never
+ * one.
  */
 export declare function renderVerdict(verdict: Verdict, style: OutputStyle): string;
 /**
- * Renders a verdict as the JSON object a machine consumer reads, without the newline that terminates it.
+ * Renders a verdict as the JSON object that 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](../docs/reporting.md#reporting-for-a-machine)
- * in the same order.
+ * Held to the same ceiling as the prose line, so that one write still arrives in a pipe whole when concurrent
+ * scopes share a descriptor. It cuts inside the record's text rather than across its structure, which leaves the
+ * line parseable, and fits a record by rungs, each shedding what a reader can better spare than the rung below it.
+ * Each rung is [documented](../docs/reporting.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.
+ * Writes a verdict to a stream as a single write, which keeps a line intact when concurrent scopes share one
+ * descriptor. Both renderings use the one record, so neither can come to report what the other does not.
  */
 export declare function writeVerdict(verdict: Verdict, stream: Writable, format: ReportFormat, style: OutputStyle): void;

package/dist/esm/verdict.js

@@ -52,7 +52,7 @@ function describeNoOpReason(reason) {
         case 'empty-override':
             return 'the override is empty';
         case 'empty-workspace':
-            return 'the workspace declares no package';
+            return 'the workspace does not declare any package';
         case 'noop-override':
             return 'the override is a no-op';
         default: {

package/dist/esm/vitest-source-resolution.d.ts

@@ -1,10 +1,10 @@
 import type { Plugin } from 'vite';
 /**
- * Builds the plugin that resolves a package's `source` export condition, for a package whose files sit outside
+ * Builds the plugin that resolves a package's `source` export condition, for a package whose files are outside
  * every `node_modules`.
  *
  * The condition cannot be emitted as a `resolve.conditions` entry instead: Vitest turns the server environment's
- * conditions into `--conditions` flags on the worker process, where Node applies them to every package it
+ * conditions into `--conditions` flags on the worker process, where Node applies them to every package that it
  * resolves natively. Node refuses to strip types from a file under `node_modules`, so a dependency declaring a
  * TypeScript `source` entry fails to load as soon as the condition reaches that far.
  *
@@ -22,16 +22,16 @@ export interface SourceResolutionContext {
     packageDirs?: Map<string, string | undefined>;
 }
 /**
- * Resolves a bare specifier to the file that its package's `source` condition names, or nothing where the condition
- * does not reach it.
+ * Resolves a bare specifier to the file that its package's `source` condition names, or to nothing when the
+ * condition does not reach it.
  *
- * Answers a bare specifier naming a package whose real directory sits outside every `node_modules`. Every other
- * specifier returns nothing -- such as a relative or absolute path, a virtual module, a builtin, or a package under
- * `node_modules` -- so Vite resolves the specifier through its own conditions. Throws where the condition reaches no
- * file, because falling through to the build output is the staleness that resolving from source exists to prevent,
- * and nothing in a run reports it.
+ * Answers a bare specifier naming a package whose real directory is outside every `node_modules`. Returns nothing
+ * for every other specifier -- such as a relative or absolute path, a virtual module, a builtin, or a package under
+ * `node_modules` -- so Vite resolves the specifier through its own conditions. Throws when the condition does not
+ * reach any file, because falling through to the build output is the staleness that resolving from source exists
+ * to prevent, and nothing in a run reports it.
  *
- * A query or hash suffix is split off before the `exports` lookup and re-appended to the resolved path, as Vite
- * does, so `pkg/icon.svg?raw` matches the `./icon.svg` entry and still reaches the plugin that reads the suffix.
+ * Because a query or hash suffix is split off before the `exports` lookup and re-appended to the resolved path, as
+ * Vite does, `pkg/icon.svg?raw` matches the `./icon.svg` entry and still reaches the plugin that reads the suffix.
  */
 export declare function resolveSourceTarget(specifier: string, importer: string | undefined, context: SourceResolutionContext): string | undefined;

package/dist/esm/vitest-source-resolution.js

@@ -114,9 +114,9 @@ function findTargetFile(declaredPath) {
 }
 function formatMissingTarget(name, subpath, declaredTarget, target) {
     return [
-        `Package "${name}" declares a \`source\` export for "${subpath}" at "${declaredTarget}", which reaches no file.`,
+        `Package "${name}" declares a \`source\` export for "${subpath}" at "${declaredTarget}", which does not reach any file.`,
         `Looked for ${target}, the same path under each of ${TARGET_EXTENSIONS.join(', ')}, and an index under it.`,
-        'Point the condition at a file that exists, or remove it so the package resolves through its other conditions.',
+        'Point the condition at a file that exists, or remove it so that the package resolves through its other conditions.',
     ].join(' ');
 }
 function isFile(candidate) {

package/dist/esm/vitest.d.ts

@@ -3,8 +3,8 @@ import type { InlineConfig, ProjectConfig } from 'vitest/node';
 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.
+ * Test options that Vitest honours only at the root of a `projects` config. Derived from Vitest's own types, 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. */
@@ -16,7 +16,7 @@ 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
+     * condition meant for them goes under `ssr`; a top-level `resolve.conditions` entry applies to the client
      * environment, which only browser-mode tests resolve through.
      */
     root?: RootOverrides;
@@ -29,41 +29,42 @@ export interface VitestConfigOptions {
      */
     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.
+     * Directory basenames kept out of every project's collection, additive to the ones that the shared config always
+     * prunes and to the paths that git ignores. 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
+     * reports nothing; excluding it from collection alone leaves a report that 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.
+     * Loads nmr's git-isolation setup file into every project, ahead of any that the layers supply. Defaults to `true`.
+     * Turn it off only when a suite is meant to read the developer's own git configuration.
      */
     shouldIsolateGit?: boolean;
     /**
-     * Resolves a package whose files sit outside every `node_modules` through its `source` export condition, so a
-     * suite runs without a prior build. Defaults to `true`. A package declaring no such condition is unaffected,
-     * and so is every package under `node_modules`, which Node resolves and which the condition never reaches.
+     * Resolves a package whose files are outside every `node_modules` through its `source` export condition, so a
+     * suite runs without a prior build. Defaults to `true`. A package that does not declare a `source` condition is
+     * unaffected, and so is every package under `node_modules`, which Node resolves and to which the condition never
+     * applies.
      */
     shouldResolveFromSource?: 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.
+     * Resolves a test's aliased specifier through the `paths` that a `tsconfig.json` declares, 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.
+     * Without it, an alias fails loudly as an unresolved import. With it, a repo that declares `paths` for `tsc` alone
+     * changes which module a specifier reaches, and nothing in the run reports the change. A repo that does not declare
+     * `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
+     * An absolute path to the monorepo root, which must contain `pnpm-workspace.yaml`. A root config is in 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;
@@ -75,18 +76,18 @@ type RootConfigLayers = [...(VitestConfigOptions | undefined)[], RootVitestConfi
  * 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
+ * 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.
+ * An `undefined` layer is skipped, which lets `defineVitestConfig(shared, isCI ? ciLayer : undefined)` compose.
  */
 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.
+ * does not report any 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
+ * `monorepoRoot` is set 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.
+ * still catches the JavaScript config that type checking never covers.
  */
 export declare function defineRootVitestConfig(...layers: RootConfigLayers): ViteUserConfig;

package/dist/esm/vitest.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defaultExclude, mergeConfig } from 'vitest/config';
+import { listGitIgnoredPaths } from "./git-ignored-paths.js";
 import { isObject } from "./helpers/type-guards.js";
 import { ALL_TEST_PATTERNS, buildTierPatterns, TEST_COLLECTION_EXCLUDE, TIER_NAMES } from "./tiers.js";
 import { createSourceResolutionPlugin } from "./vitest-source-resolution.js";
@@ -13,6 +14,7 @@ const CLIENT_CONDITIONS = ['module', 'browser', 'development|production'];
 const SERVER_CONDITIONS = ['module', 'node', 'development|production'];
 const COVERAGE_EXCLUDE = ['**/__{fixtures,mocks,tests}__/**', '**/index.ts', '**/*.d.ts'];
 const PACKAGE_COVERAGE_INCLUDE = ['**/src/**/*.{ts,tsx}'];
+const GLOB_SYNTAX_PATTERN = /[!()*+?@[\]{}]/g;
 const RECOGNIZED_OPTIONS = {
     project: true,
     root: true,
@@ -32,10 +34,10 @@ const RETIRED_OPTION_KEYS = new Map([
     ['isolateGit', 'shouldIsolateGit'],
     ['resolveFromSource', 'shouldResolveFromSource'],
 ]);
-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.';
+const MISSING_MONOREPO_ROOT = 'defineRootVitestConfig requires `monorepoRoot`, an absolute path to the directory that contains pnpm-workspace.yaml. Pass `import.meta.dirname` in the last options layer, from the root config.';
 export function defineVitestConfig(...layers) {
     assertOptionKeys(layers, RECOGNIZED_OPTION_KEYS);
-    return buildConfig(layers, { coverageInclude: PACKAGE_COVERAGE_INCLUDE });
+    return buildConfig(layers, { coverageInclude: PACKAGE_COVERAGE_INCLUDE, ignoredPathsRoot: process.cwd() });
 }
 export function defineRootVitestConfig(...layers) {
     const lastLayer = layers.at(-1);
@@ -46,11 +48,12 @@ export function defineRootVitestConfig(...layers) {
     assertOptionKeys(layers, RECOGNIZED_ROOT_OPTION_KEYS);
     return buildConfig(layers, {
         coverageInclude: [],
+        ignoredPathsRoot: monorepoRoot,
         projectExclude: getWorkspaceExcludePatterns(monorepoRoot),
         projectRoot: monorepoRoot,
     });
 }
-function buildConfig(declaredLayers, { coverageInclude, projectExclude = [], projectRoot }) {
+function buildConfig(declaredLayers, { coverageInclude, ignoredPathsRoot, projectExclude = [], projectRoot }) {
     const layers = declaredLayers.filter((layer) => layer !== undefined);
     assertKnownTiers(layers);
     const resolve = {
@@ -69,7 +72,7 @@ function buildConfig(declaredLayers, { coverageInclude, projectExclude = [], pro
                 provider: 'v8',
             },
             passWithNoTests: true,
-            projects: buildProjects(layers, projectExclude, projectRoot),
+            projects: buildProjects(layers, projectExclude, projectRoot, ignoredPathsRoot),
             silent: 'passed-only',
             watch: false,
         },
@@ -81,7 +84,7 @@ function buildConfig(declaredLayers, { coverageInclude, projectExclude = [], pro
     }
     return mergedConfig;
 }
-function buildProjects(layers, extraExclude, projectRoot) {
+function buildProjects(layers, extraExclude, projectRoot, ignoredPathsRoot) {
     const projectTiers = [
         { exclude: TIERED_PATTERNS, include: ALL_TEST_PATTERNS, name: RESIDUAL_TIER },
         ...NAMED_TIERS.map((tier) => ({
@@ -91,7 +94,7 @@ function buildProjects(layers, extraExclude, projectRoot) {
             timeoutMs: TIER_TIMEOUT_MS,
         })),
     ];
-    const collectionExclude = buildCollectionExclude(layers);
+    const collectionExclude = buildCollectionExclude(layers, ignoredPathsRoot);
     const shouldIsolateGit = resolveFlag(layers, 'shouldIsolateGit', true);
     return projectTiers.map(({ exclude, include, name, timeoutMs }) => {
         const project = {
@@ -150,10 +153,15 @@ function assertOptionKeys(layers, lastLayerKeys) {
             `${formatOptionKeys(unrecognizedKeys)}. Recognized: ${formatOptionKeys(recognizedKeys)}.`);
     });
 }
-function buildCollectionExclude(layers) {
+function buildCollectionExclude(layers, ignoredPathsRoot) {
     const declaredDirs = layers.flatMap((layer) => layer.testCollectionExclude ?? []);
     const globs = [...TEST_COLLECTION_EXCLUDE, ...declaredDirs].map((dir) => `**/${dir}/**`);
-    return [...new Set([...defaultExclude, ...globs])];
+    const ignoredGlobs = listGitIgnoredPaths(ignoredPathsRoot).map(buildIgnoredPathGlob);
+    return [...new Set([...defaultExclude, ...globs, ...ignoredGlobs])];
+}
+function buildIgnoredPathGlob(ignoredPath) {
+    const escapedPath = ignoredPath.replaceAll(GLOB_SYNTAX_PATTERN, String.raw `\$&`);
+    return escapedPath.endsWith('/') ? `${escapedPath}**` : escapedPath;
 }
 function formatOptionKeys(keys) {
     return keys

package/dist/esm/workspace.d.ts

@@ -2,14 +2,14 @@ export type { EmptyWorkspaceCause, WorkspaceResolution } from '@williamthorsen/n
 export { isMonorepoRoot, readWorkspaceOverrides, readWorkspacePackageNames, resolveWorkspace, } from '@williamthorsen/nmr-core/workspace';
 /**
  * Finds the monorepo root by walking up from `startDir` to find `pnpm-workspace.yaml`.
- * Throws if no workspace root is found.
+ * Throws if it does not find a workspace root in `startDir` or any of its parent directories.
  */
 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.
+ * 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.
+ * Returns an empty array when the manifest does not declare a usable `packages` list, and throws when
+ * `monorepoRoot` does not contain a manifest at all.
  */
 export declare function getWorkspacePackageDirs(monorepoRoot: string): string[];