@savvy-web/vitest 0.2.2 → 1.0.0

package/README.md

@@ -1,9 +1,21 @@
 # @savvy-web/vitest
 
-Automatic Vitest project discovery and configuration for pnpm monorepo
-workspaces. Define your test config once at the root and let every workspace
-package with a `src/` directory be discovered, classified, and configured
-automatically.
+[![npm version](https://img.shields.io/npm/v/@savvy-web/vitest)](https://www.npmjs.com/package/@savvy-web/vitest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Automatic Vitest project configuration discovery for pnpm monorepo
+workspaces. Scans workspace packages, classifies test files as unit,
+e2e, or integration by filename convention, and generates multi-project
+Vitest configs with coverage thresholds, `vitest-agent-reporter`
+integration, and CI-aware reporters.
+
+## Features
+
+- Zero-config workspace discovery with automatic test classification
+- Named coverage levels (`none`, `basic`, `standard`, `strict`, `full`)
+- Per-kind and per-project override support with chainable mutation API
+- Built-in `vitest-agent-reporter` integration for AI-assisted workflows
+- CI-aware reporters with automatic `github-actions` reporter in CI
 
 ## Installation
 
@@ -11,140 +23,78 @@ automatically.
 pnpm add @savvy-web/vitest
 ```
 
-Peer dependencies: `vitest`, `@vitest/coverage-v8`
+Peer dependencies: `vitest` >=4.1.0, `@vitest/coverage-v8` >=4.1.0, `vitest-agent-reporter` >=0.2.0
 
 ## Quick Start
 
-Create a single `vitest.config.ts` at your workspace root:
-
 ```typescript
 import { VitestConfig } from "@savvy-web/vitest";
 
-export default VitestConfig.create(
-  ({ projects, coverage, reporters }) => ({
-    test: {
-      reporters,
-      projects: projects.map((p) => p.toConfig()),
-      coverage: { provider: "v8", ...coverage },
-    },
-  }),
-);
+// Zero config -- everything automatic
+export default VitestConfig.create();
 ```
 
-Every workspace package containing a `src/` directory is discovered and
-configured. No per-package Vitest config files needed.
-
-## Manual Projects
+## Directory Structure
+
+```text
+project-root/                   # or monorepo leaf workspace
+  lib/                          # Configs, scripts -- linted, typechecked, no tests
+  src/                          # Module source -- may contain co-located tests
+  __test__/                     # Dedicated test directory
+    utils/                      # Shared test helpers (excluded from discovery)
+    fixtures/                   # Test fixtures (excluded from lint/typecheck/discovery)
+    *.test.ts                   # Unit tests (no signifier)
+    *.unit.test.ts              # Unit tests (explicit signifier)
+    unit/                       # Optional unit subdirectory
+      utils/                    # Excluded
+      fixtures/                 # Excluded
+    e2e/
+      utils/                    # Excluded
+      fixtures/                 # Excluded
+      *.e2e.test.ts
+    integration/
+      utils/                    # Excluded
+      fixtures/                 # Excluded
+      *.int.test.ts
+  vitest.setup.ts               # Optional -- auto-detected, added to all projects
+```
 
-When you need explicit control, use the factory methods directly:
+## Examples
 
 ```typescript
-import { VitestProject } from "@savvy-web/vitest";
+// Named coverage level
+export default VitestConfig.create({ coverage: "standard" });
 
-const unit = VitestProject.unit({
-  name: "@savvy-web/my-lib",
-  include: ["src/**/*.test.ts"],
+// Per-kind overrides (object form)
+export default VitestConfig.create({
+  unit: { environment: "jsdom" },
 });
 
-const e2e = VitestProject.e2e({
-  name: "@savvy-web/my-lib:e2e",
-  include: ["test/e2e/**/*.test.ts"],
-  overrides: {
-    test: { testTimeout: 60_000 },
+// Per-project overrides (callback form)
+export default VitestConfig.create({
+  e2e: (projects) => {
+    projects.get("@savvy-web/auth:e2e")
+      ?.override({ test: { testTimeout: 300_000 } })
+      .addCoverageExclude("src/generated/**");
   },
 });
-```
-
-## API Reference
 
-### `VitestConfig.create(callback, options?)`
-
-Entry point for automatic workspace discovery. The callback receives:
-
-- **`projects`** -- discovered `VitestProject[]` instances
-- **`coverage`** -- `CoverageConfig` with include/exclude globs and thresholds
-- **`reporters`** -- reporter names (adds `"github-actions"` in CI)
-- **`isCI`** -- `true` when running in GitHub Actions
-
-Returns whatever `ViteUserConfig` the callback produces (sync or async).
-
-### `VitestProject.unit(options)` / `.e2e(options)` / `.custom(kind, options)`
-
-Factory methods that create projects with preset defaults:
-
-| Factory | Environment | Test Timeout | Hook Timeout | Max Concurrency |
-| --- | --- | --- | --- | --- |
-| `unit()` | `"node"` | vitest default | vitest default | vitest default |
-| `e2e()` | `"node"` | 120 s | 60 s | `floor(cpus / 2)` clamped 1--8 |
-| `custom(kind)` | none | none | none | none |
-
-### `VitestProjectOptions`
-
-```typescript
-interface VitestProjectOptions {
-  name: string;
-  include: string[];
-  kind?: VitestProjectKind;
-  overrides?: Partial<TestProjectInlineConfiguration>;
-}
-```
-
-`name` and `include` always take precedence over values in `overrides`.
-
-### `VitestConfigCreateOptions`
-
-```typescript
-interface VitestConfigCreateOptions {
-  thresholds?: {
-    lines?: number;      // default 80
-    functions?: number;   // default 80
-    branches?: number;    // default 80
-    statements?: number;  // default 80
-  };
-}
-```
-
-### `CoverageConfig`
-
-```typescript
-interface CoverageConfig {
-  include: string[];   // source globs (e.g., "pkgs/my-lib/src/**/*.ts")
-  exclude: string[];   // test file globs
-  thresholds: {
-    lines: number;
-    functions: number;
-    branches: number;
-    statements: number;
-  };
-}
+// Escape hatch for Vite-level config
+export default VitestConfig.create(
+  { coverage: "standard" },
+  (config) => {
+    config.resolve = { alias: { "@": "/src" } };
+  },
+);
 ```
 
-## Test Discovery Conventions
-
-### Filename Patterns
-
-| Pattern | Kind |
-| --- | --- |
-| `*.test.ts` / `*.spec.ts` | unit |
-| `*.e2e.test.ts` / `*.e2e.spec.ts` | e2e |
-
-### Directory Scanning
-
-Each workspace package is scanned if it contains a `src/` directory. An
-optional `__test__/` directory at the package root is also included when
-present.
-
-### Naming Suffixes
-
-When a package has both unit and e2e test files, projects are automatically
-suffixed with `:unit` and `:e2e` (e.g., `@savvy-web/my-lib:unit`). Packages
-with only one kind use the bare package name.
+## Documentation
 
-## CI Integration
+For configuration, API reference, and advanced usage, see [docs/](./docs/).
 
-When the `GITHUB_ACTIONS` environment variable is set, `VitestConfig.create`
-automatically adds the `"github-actions"` reporter and sets `isCI: true` in the
-callback. No additional configuration required.
+- [API Reference](./docs/api.md) -- Complete reference for all exports
+- [Test Discovery](./docs/discovery.md) -- Workspace scanning, test classification, and coverage scoping
+- [Usage Guides](./docs/guides.md) -- Recipes for kind overrides, per-project mutation, coverage, agent reporter, and escape hatches
 
 ## License
 

package/index.d.ts

@@ -15,48 +15,70 @@
  * ```typescript
  * import { VitestConfig } from "@savvy-web/vitest";
  *
- * export default VitestConfig.create(
- *   ({ projects, coverage, reporters }) => ({
- *     test: {
- *       reporters,
- *       projects: projects.map((p) => p.toConfig()),
- *       coverage: { provider: "v8", ...coverage },
- *     },
- *   }),
- * );
+ * export default VitestConfig.create();
  * ```
  *
  * @packageDocumentation
  */
 
+import type { AgentPluginOptions } from 'vitest-agent-reporter';
 import { TestProjectInlineConfiguration } from 'vitest/config';
 import type { ViteUserConfig } from 'vitest/config';
 
 /**
- * Coverage configuration passed to the {@link VitestConfigCallback}.
+ * Pass-through configuration for `vitest-agent-reporter`'s `AgentPlugin`.
  *
- * @see {@link VitestConfig.create} for how this is generated
+ * @see {@link VitestConfigOptions.agentReporter}
  *
  * @public
  */
-export declare interface CoverageConfig {
-    /** Glob patterns for files to include in coverage reporting. */
-    include: string[];
-    /** Glob patterns for files to exclude from coverage reporting. */
-    exclude: string[];
-    /** Resolved coverage thresholds with all metrics populated. */
-    thresholds: {
-        /** Minimum line coverage percentage. */
-        lines: number;
-        /** Minimum function coverage percentage. */
-        functions: number;
-        /** Minimum branch coverage percentage. */
-        branches: number;
-        /** Minimum statement coverage percentage. */
-        statements: number;
-    };
+export declare type AgentReporterConfig = AgentPluginOptions;
+
+/**
+ * Named coverage level presets available on {@link VitestConfig.COVERAGE_LEVELS}.
+ *
+ * @public
+ */
+export declare type CoverageLevelName = "none" | "basic" | "standard" | "strict" | "full";
+
+/**
+ * Coverage thresholds with all four metrics required.
+ *
+ * @public
+ */
+export declare interface CoverageThresholds {
+    /** Minimum line coverage percentage. */
+    lines: number;
+    /** Minimum function coverage percentage. */
+    functions: number;
+    /** Minimum branch coverage percentage. */
+    branches: number;
+    /** Minimum statement coverage percentage. */
+    statements: number;
 }
 
+/**
+ * Override for a specific test kind (unit, e2e, int).
+ *
+ * @remarks
+ * When an object is provided, it is merged into every project of that kind.
+ * When a callback is provided, it receives a Map of project name to
+ * {@link VitestProject} for fine-grained per-project mutation.
+ *
+ * @public
+ */
+export declare type KindOverride = Partial<TestProjectInlineConfiguration["test"]> | ((projects: Map<string, VitestProject>) => void);
+
+/**
+ * Post-process callback for escape-hatch customization of the assembled config.
+ *
+ * @param config - The assembled Vitest configuration
+ * @returns A replacement config, or void to use the mutated original
+ *
+ * @public
+ */
+export declare type PostProcessCallback = (config: ViteUserConfig) => ViteUserConfig | undefined;
+
 export { TestProjectInlineConfiguration }
 
 /**
@@ -82,47 +104,62 @@ export { TestProjectInlineConfiguration }
  * ```typescript
  * import { VitestConfig } from "@savvy-web/vitest";
  *
- * export default VitestConfig.create(
- *   ({ projects, coverage, reporters }) => ({
- *     test: {
- *       reporters,
- *       projects: projects.map((p) => p.toConfig()),
- *       coverage: { provider: "v8", ...coverage },
- *     },
- *   }),
- * );
+ * export default VitestConfig.create();
  * ```
  *
  * @public
  */
 export declare class VitestConfig {
-    /** Default coverage threshold percentage applied when not overridden. */
-    static readonly DEFAULT_THRESHOLD = 80;
+    /** Default glob patterns excluded from coverage reporting. */
+    private static readonly DEFAULT_COVERAGE_EXCLUDE;
+    /**
+     * Named coverage level presets.
+     *
+     * @remarks
+     * Use a level name with the `coverage` option in {@link VitestConfig.create}
+     * to apply a preset. The object is frozen and cannot be mutated.
+     *
+     * | Level    | lines | branches | functions | statements |
+     * | -------- | ----- | -------- | --------- | ---------- |
+     * | none     | 0     | 0        | 0         | 0          |
+     * | basic    | 50    | 50       | 50        | 50         |
+     * | standard | 70    | 65       | 70        | 70         |
+     * | strict   | 80    | 75       | 80        | 80         |
+     * | full     | 90    | 85       | 90        | 90         |
+     */
+    static readonly COVERAGE_LEVELS: Readonly<Record<CoverageLevelName, CoverageThresholds>>;
     private static cachedProjects;
     private static cachedVitestProjects;
     /**
      * Creates a complete Vitest configuration by discovering workspace projects
      * and generating appropriate settings.
      *
-     * @param callback - Receives discovered projects, coverage config,
-     *   reporters, and CI flag; returns a Vitest config
-     * @param options - Optional configuration including coverage thresholds
-     * @returns The Vitest configuration returned by the callback
+     * @param options - Optional declarative configuration
+     * @param postProcess - Optional escape-hatch callback for full config control
+     * @returns The assembled Vitest configuration
      *
-     * @see {@link VitestConfigCallback} for the callback signature
-     * @see {@link VitestConfigCreateOptions} for available options
+     * @see {@link VitestConfigOptions} for available options
+     * @see {@link PostProcessCallback} for the post-process callback signature
+     */
+    static create(options?: VitestConfigOptions, postProcess?: PostProcessCallback): Promise<ViteUserConfig>;
+    /**
+     * Applies kind-specific overrides to discovered projects.
+     *
+     * @privateRemarks
+     * When the override is an object, it is merged into every project of the
+     * matching kind. When it is a callback, it receives a Map of project name
+     * to {@link VitestProject} for fine-grained per-project mutation.
      */
-    static create(callback: VitestConfigCallback, options?: VitestConfigCreateOptions): Promise<ViteUserConfig> | ViteUserConfig;
+    private static applyKindOverrides;
     /**
-     * Extracts the specific project name from command line arguments.
+     * Extracts all specific project names from command line arguments.
      *
      * @privateRemarks
      * Supports both `--project=value` and `--project value` formats to match
-     * Vitest's own argument parsing behavior. Only the first `--project` flag
-     * is returned; repeated flags (e.g. `--project foo --project bar`) are
-     * ignored since multi-project coverage scoping is not supported.
+     * Vitest's own argument parsing behavior. All `--project` flags are
+     * collected to support multi-project coverage scoping.
      */
-    private static getSpecificProject;
+    private static getSpecificProjects;
     /**
      * Reads the `name` field from a package's `package.json`.
      *
@@ -139,12 +176,22 @@ export declare class VitestConfig {
      * pattern used throughout workspace discovery.
      */
     private static isDirectory;
+    /** Extensions probed (in order) when detecting a setup file. */
+    private static readonly SETUP_FILE_EXTENSIONS;
+    /**
+     * Detects a `vitest.setup.{ts,tsx,js,jsx}` file at the package root.
+     *
+     * @privateRemarks
+     * First match wins. Returns just the filename (e.g. `"vitest.setup.ts"`)
+     * so the caller can prepend the relative prefix as needed.
+     */
+    private static detectSetupFile;
     /**
      * Recursively scans a directory for test files and classifies them by kind.
      *
      * @privateRemarks
-     * Short-circuits as soon as both unit and e2e files are found, avoiding
-     * unnecessary filesystem traversal.
+     * Short-circuits as soon as all three kinds (unit, e2e, and int) are
+     * found, avoiding unnecessary filesystem traversal.
      */
     private static scanForTestFiles;
     /**
@@ -152,6 +199,19 @@ export declare class VitestConfig {
      * test directory.
      */
     private static buildIncludes;
+    /**
+     * Conventional subdirectories under `__test__/` that hold helpers, not
+     * test files, and should be excluded from test discovery.
+     */
+    private static readonly TEST_DIR_EXCLUSIONS;
+    /**
+     * Returns exclusion patterns for fixture/utils directories under
+     * `__test__/`, scoped to the given package prefix.
+     *
+     * @param prefix - Either `"<relativePath>/"` for non-root packages or
+     *   `""` for the workspace root.
+     */
+    private static buildTestDirExclusions;
     /**
      * Discovers all packages in the workspace that contain a `src/` directory
      * and generates {@link VitestProject} instances based on filename conventions.
@@ -162,63 +222,68 @@ export declare class VitestConfig {
      * test files still get a unit project entry as a forward-looking placeholder.
      */
     private static discoverWorkspaceProjects;
+    /**
+     * Resolves coverage thresholds from options.
+     *
+     * @privateRemarks
+     * Priority: `options.coverage` (name or object) \> `COVERAGE_LEVELS.strict`.
+     */
+    private static resolveThresholds;
     /**
      * Generates coverage configuration including thresholds.
      *
      * @privateRemarks
-     * Strips `:unit`/`:e2e` suffix when looking up project paths for
+     * Strips `:unit`/`:e2e`/`:int` suffix when looking up project paths for
      * `--project` filtering, since coverage applies to the entire package
-     * regardless of test kind.
+     * regardless of test kind. When multiple `--project` flags are provided,
+     * coverage includes are unioned across all matched packages.
      */
     private static getCoverageConfig;
 }
 
-/**
- * Callback that receives discovered configuration and returns a Vitest config.
- *
- * @param config - Object containing discovered projects, coverage settings,
- *   reporters array, and CI detection flag
- * @returns A Vitest user configuration, optionally async
- *
- * @see {@link VitestConfig.create} for the entry point that invokes this callback
- *
- * @public
- */
-export declare type VitestConfigCallback = (config: {
-    /** Discovered {@link VitestProject} instances for the workspace. */
-    projects: VitestProject[];
-    /** Generated coverage configuration with thresholds. */
-    coverage: CoverageConfig;
-    /** Reporter names based on environment (adds `"github-actions"` in CI). */
-    reporters: string[];
-    /** Whether the current environment is GitHub Actions CI. */
-    isCI: boolean;
-}) => ViteUserConfig | Promise<ViteUserConfig>;
-
 /**
  * Options for {@link VitestConfig.create}.
  *
  * @public
  */
-export declare interface VitestConfigCreateOptions {
+export declare interface VitestConfigOptions {
     /**
-     * Coverage thresholds applied per-file.
+     * Coverage level name or explicit thresholds object.
      *
      * @remarks
-     * Any omitted metric defaults to {@link VitestConfig.DEFAULT_THRESHOLD | 80}.
-     *
-     * @defaultValue `{ lines: 80, functions: 80, branches: 80, statements: 80 }`
-     */
-    thresholds?: {
-        /** Minimum line coverage percentage. */
-        lines?: number;
-        /** Minimum function coverage percentage. */
-        functions?: number;
-        /** Minimum branch coverage percentage. */
-        branches?: number;
-        /** Minimum statement coverage percentage. */
-        statements?: number;
-    };
+     * When a {@link CoverageLevelName} string is provided, the corresponding
+     * preset from {@link VitestConfig.COVERAGE_LEVELS} is used. When a
+     * {@link CoverageThresholds} object is provided, it is used directly.
+     *
+     * @defaultValue `"strict"` (lines: 80, branches: 75, functions: 80, statements: 80)
+     */
+    coverage?: CoverageLevelName | CoverageThresholds;
+    /** Additional glob patterns to exclude from coverage reporting. */
+    coverageExclude?: string[];
+    /**
+     * Whether to inject the vitest-agent-reporter plugin.
+     *
+     * @remarks
+     * When `true` or an {@link AgentReporterConfig} object, the plugin is
+     * injected with the given options (with `strategy` defaulting to `"own"`
+     * and `coverageThresholds` populated from the resolved coverage level).
+     * When `false`, the plugin is not injected.
+     *
+     * @defaultValue `true`
+     */
+    agentReporter?: boolean | AgentReporterConfig;
+    /**
+     * Vitest pool mode.
+     *
+     * @defaultValue Uses Vitest's default (threads)
+     */
+    pool?: "threads" | "forks" | "vmThreads" | "vmForks";
+    /** Override configuration for all unit test projects. */
+    unit?: KindOverride;
+    /** Override configuration for all e2e test projects. */
+    e2e?: KindOverride;
+    /** Override configuration for all integration test projects. */
+    int?: KindOverride;
 }
 
 /**
@@ -266,6 +331,14 @@ export declare class VitestProject {
      * @see {@link VitestProjectKind}
      */
     get kind(): VitestProjectKind;
+    /**
+     * Coverage exclusion patterns accumulated via {@link addCoverageExclude}.
+     *
+     * @remarks
+     * These patterns are not embedded in the inline project config but are
+     * made available for the workspace-level coverage configuration to consume.
+     */
+    get coverageExcludes(): readonly string[];
     /**
      * Returns the vitest-native inline configuration object.
      *
@@ -273,6 +346,54 @@ export declare class VitestProject {
      *   with all defaults and overrides merged
      */
     toConfig(): TestProjectInlineConfiguration;
+    /**
+     * Creates a clone of this project with independent config state.
+     *
+     * @remarks
+     * The clone has its own config object so mutations via
+     * {@link override}, {@link addInclude}, {@link addExclude}, and
+     * {@link addCoverageExclude} do not affect the original.
+     *
+     * @returns A new {@link VitestProject} with the same configuration
+     */
+    clone(): VitestProject;
+    /**
+     * Merges additional configuration over the current config.
+     *
+     * @remarks
+     * The {@link VitestProjectOptions.name | name} and
+     * {@link VitestProjectOptions.include | include} fields are preserved
+     * and cannot be overridden.
+     *
+     * @param config - Partial configuration to merge
+     * @returns `this` for chaining
+     */
+    override(config: Partial<TestProjectInlineConfiguration>): this;
+    /**
+     * Appends glob patterns to the test include list.
+     *
+     * @param patterns - Glob patterns to add
+     * @returns `this` for chaining
+     */
+    addInclude(...patterns: string[]): this;
+    /**
+     * Appends glob patterns to the test exclude list.
+     *
+     * @param patterns - Glob patterns to add
+     * @returns `this` for chaining
+     */
+    addExclude(...patterns: string[]): this;
+    /**
+     * Appends glob patterns to the coverage exclusion list.
+     *
+     * @remarks
+     * These patterns are exposed via {@link coverageExcludes} for the
+     * workspace-level coverage configuration to consume.
+     *
+     * @param patterns - Glob patterns to exclude from coverage
+     * @returns `this` for chaining
+     */
+    addCoverageExclude(...patterns: string[]): this;
     /**
      * Creates a unit test project with sensible defaults.
      *
@@ -315,6 +436,28 @@ export declare class VitestProject {
      * ```
      */
     static e2e(options: VitestProjectOptions): VitestProject;
+    /**
+     * Creates an integration test project with sensible defaults.
+     *
+     * @remarks
+     * Defaults applied: `extends: true`, `environment: "node"`,
+     * `testTimeout: 60_000`, `hookTimeout: 30_000`,
+     * `maxConcurrency: clamp(floor(cpus / 2), 1, 8)`.
+     *
+     * @param options - Project options (the `kind` field is forced to `"int"`)
+     * @returns A new {@link VitestProject} configured for integration tests
+     *
+     * @example
+     * ```typescript
+     * import { VitestProject } from "@savvy-web/vitest";
+     *
+     * const project = VitestProject.int({
+     *   name: "@savvy-web/my-lib:int",
+     *   include: ["__test__/integration/**\/*.int.test.ts"],
+     * });
+     * ```
+     */
+    static int(options: VitestProjectOptions): VitestProject;
     /**
      * Creates a custom test project with no preset defaults beyond `extends: true`.
      *
@@ -351,7 +494,7 @@ export declare class VitestProject {
  *
  * @public
  */
-export declare type VitestProjectKind = "unit" | "e2e" | (string & {});
+export declare type VitestProjectKind = "unit" | "e2e" | "int" | (string & {});
 
 /**
  * Options for constructing a {@link VitestProject}.

package/index.js

@@ -1,11 +1,13 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { cpus } from "node:os";
 import { join, relative } from "node:path";
+import { AgentPlugin } from "vitest-agent-reporter";
 import { getWorkspaceManagerRoot, getWorkspacePackagePaths } from "workspace-tools";
 class VitestProject {
     #name;
     #kind;
     #config;
+    #coverageExcludes = [];
     constructor(options, defaults){
         this.#name = options.name;
         this.#kind = options.kind ?? "unit";
@@ -29,9 +31,75 @@ class VitestProject {
     get kind() {
         return this.#kind;
     }
+    get coverageExcludes() {
+        return this.#coverageExcludes;
+    }
     toConfig() {
         return this.#config;
     }
+    clone() {
+        const { test, ...rest } = this.#config;
+        const cloned = new VitestProject({
+            name: this.#name,
+            include: test?.include ?? [],
+            kind: this.#kind
+        }, {});
+        cloned.#config = {
+            ...rest,
+            test: test ? {
+                ...test
+            } : void 0
+        };
+        cloned.#coverageExcludes.push(...this.#coverageExcludes);
+        return cloned;
+    }
+    override(config) {
+        const { test: overrideTest, ...overrideRest } = config;
+        const { test: existingTest, ...existingRest } = this.#config;
+        this.#config = {
+            ...existingRest,
+            ...overrideRest,
+            test: {
+                ...existingTest,
+                ...overrideTest,
+                name: this.#name,
+                include: existingTest?.include
+            }
+        };
+        return this;
+    }
+    addInclude(...patterns) {
+        const { test: existingTest, ...rest } = this.#config;
+        this.#config = {
+            ...rest,
+            test: {
+                ...existingTest,
+                include: [
+                    ...existingTest?.include ?? [],
+                    ...patterns
+                ]
+            }
+        };
+        return this;
+    }
+    addExclude(...patterns) {
+        const { test: existingTest, ...rest } = this.#config;
+        this.#config = {
+            ...rest,
+            test: {
+                ...existingTest,
+                exclude: [
+                    ...existingTest?.exclude ?? [],
+                    ...patterns
+                ]
+            }
+        };
+        return this;
+    }
+    addCoverageExclude(...patterns) {
+        this.#coverageExcludes.push(...patterns);
+        return this;
+    }
     static unit(options) {
         return new VitestProject({
             ...options,
@@ -56,6 +124,20 @@ class VitestProject {
             }
         });
     }
+    static int(options) {
+        const concurrency = Math.max(1, Math.min(8, Math.floor(cpus().length / 2)));
+        return new VitestProject({
+            ...options,
+            kind: "int"
+        }, {
+            test: {
+                environment: "node",
+                testTimeout: 60000,
+                hookTimeout: 30000,
+                maxConcurrency: concurrency
+            }
+        });
+    }
     static custom(kind, options) {
         return new VitestProject({
             ...options,
@@ -64,13 +146,52 @@ class VitestProject {
     }
 }
 class VitestConfig {
-    static DEFAULT_THRESHOLD = 80;
+    static DEFAULT_COVERAGE_EXCLUDE = [
+        "**/*.{test,spec}.{ts,tsx,js,jsx}",
+        "**/__test__/**",
+        "**/generated/**"
+    ];
+    static COVERAGE_LEVELS = Object.freeze({
+        none: {
+            lines: 0,
+            branches: 0,
+            functions: 0,
+            statements: 0
+        },
+        basic: {
+            lines: 50,
+            branches: 50,
+            functions: 50,
+            statements: 50
+        },
+        standard: {
+            lines: 70,
+            branches: 65,
+            functions: 70,
+            statements: 70
+        },
+        strict: {
+            lines: 80,
+            branches: 75,
+            functions: 80,
+            statements: 80
+        },
+        full: {
+            lines: 90,
+            branches: 85,
+            functions: 90,
+            statements: 90
+        }
+    });
     static cachedProjects = null;
     static cachedVitestProjects = null;
-    static create(callback, options) {
-        const specificProject = VitestConfig.getSpecificProject();
+    static async create(options, postProcess) {
+        const specificProjects = VitestConfig.getSpecificProjects();
         const { projects, vitestProjects } = VitestConfig.discoverWorkspaceProjects();
-        const coverage = VitestConfig.getCoverageConfig(specificProject, projects, options);
+        const thresholds = VitestConfig.resolveThresholds(options);
+        const coverageConfig = VitestConfig.getCoverageConfig(specificProjects, projects, options);
+        const workingProjects = vitestProjects.map((p)=>p.clone());
+        VitestConfig.applyKindOverrides(workingProjects, options);
         const isCI = Boolean(process.env.GITHUB_ACTIONS);
         const reporters = isCI ? [
             "default",
@@ -78,20 +199,76 @@ class VitestConfig {
         ] : [
             "default"
         ];
-        return callback({
-            projects: vitestProjects,
-            coverage,
-            reporters,
-            isCI
-        });
+        let config = {
+            test: {
+                reporters,
+                projects: workingProjects.map((p)=>p.toConfig()),
+                ...options?.pool ? {
+                    pool: options.pool
+                } : {},
+                coverage: {
+                    provider: "v8",
+                    ...coverageConfig,
+                    enabled: true
+                }
+            }
+        };
+        if (options?.agentReporter !== false) {
+            const agentOpts = "object" == typeof options?.agentReporter ? options.agentReporter : {};
+            const plugin = AgentPlugin({
+                strategy: "own",
+                ...agentOpts,
+                reporter: {
+                    coverageThresholds: {
+                        ...thresholds
+                    },
+                    ...agentOpts.reporter
+                }
+            });
+            config.plugins = [
+                plugin
+            ];
+        }
+        if (postProcess) {
+            const result = postProcess(config);
+            if (void 0 !== result) config = result;
+        }
+        return config;
+    }
+    static applyKindOverrides(vitestProjects, options) {
+        if (!options) return;
+        const kindOptions = {
+            unit: options.unit,
+            e2e: options.e2e,
+            int: options.int
+        };
+        for (const [kind, override] of Object.entries(kindOptions)){
+            if (void 0 === override) continue;
+            const projectsOfKind = vitestProjects.filter((p)=>p.kind === kind);
+            if ("function" == typeof override) {
+                const map = new Map();
+                for (const p of projectsOfKind)map.set(p.name, p);
+                override(map);
+            } else for (const p of projectsOfKind)p.override({
+                test: override
+            });
+        }
     }
-    static getSpecificProject() {
+    static getSpecificProjects() {
         const args = process.argv;
-        const projectArg = args.find((arg)=>arg.startsWith("--project="));
-        if (projectArg) return projectArg.split("=")[1] ?? null;
-        const projectIndex = args.indexOf("--project");
-        if (-1 !== projectIndex && projectIndex + 1 < args.length) return args[projectIndex + 1] ?? null;
-        return null;
+        const projects = [];
+        for(let i = 0; i < args.length; i++){
+            const arg = args[i];
+            if (arg.startsWith("--project=")) {
+                const value = arg.split("=")[1];
+                if (value) projects.push(value);
+            } else if ("--project" === arg && i + 1 < args.length) {
+                const value = args[i + 1];
+                if (value) projects.push(value);
+                i++;
+            }
+        }
+        return projects;
     }
     static getPackageNameFromPath(packagePath) {
         try {
@@ -108,9 +285,26 @@ class VitestConfig {
             return false;
         }
     }
+    static SETUP_FILE_EXTENSIONS = [
+        "ts",
+        "tsx",
+        "js",
+        "jsx"
+    ];
+    static detectSetupFile(packagePath) {
+        for (const ext of VitestConfig.SETUP_FILE_EXTENSIONS){
+            const candidate = join(packagePath, `vitest.setup.${ext}`);
+            try {
+                const stat = statSync(candidate);
+                if (stat.isFile()) return `vitest.setup.${ext}`;
+            } catch  {}
+        }
+        return null;
+    }
     static scanForTestFiles(dirPath) {
         let hasUnit = false;
         let hasE2e = false;
+        let hasInt = false;
         try {
             const entries = readdirSync(dirPath, {
                 withFileTypes: true
@@ -120,16 +314,19 @@ class VitestConfig {
                     const sub = VitestConfig.scanForTestFiles(join(dirPath, entry.name));
                     hasUnit = hasUnit || sub.hasUnit;
                     hasE2e = hasE2e || sub.hasE2e;
+                    hasInt = hasInt || sub.hasInt;
                 } else if (entry.isFile()) {
-                    if (/\.e2e\.(test|spec)\.ts$/.test(entry.name)) hasE2e = true;
-                    else if (/\.(test|spec)\.ts$/.test(entry.name)) hasUnit = true;
+                    if (/\.e2e\.(test|spec)\.(ts|tsx|js|jsx)$/.test(entry.name)) hasE2e = true;
+                    else if (/\.int\.(test|spec)\.(ts|tsx|js|jsx)$/.test(entry.name)) hasInt = true;
+                    else if (/\.(test|spec)\.(ts|tsx|js|jsx)$/.test(entry.name)) hasUnit = true;
                 }
-                if (hasUnit && hasE2e) break;
+                if (hasUnit && hasE2e && hasInt) break;
             }
         } catch  {}
         return {
             hasUnit,
-            hasE2e
+            hasE2e,
+            hasInt
         };
     }
     static buildIncludes(srcGlob, testGlob, pattern) {
@@ -139,6 +336,21 @@ class VitestConfig {
         if (testGlob) includes.push(`${testGlob}/**/${pattern}`);
         return includes;
     }
+    static TEST_DIR_EXCLUSIONS = [
+        "__test__/fixtures/**",
+        "__test__/utils/**",
+        "__test__/unit/fixtures/**",
+        "__test__/unit/utils/**",
+        "__test__/e2e/fixtures/**",
+        "__test__/e2e/utils/**",
+        "__test__/int/fixtures/**",
+        "__test__/int/utils/**",
+        "__test__/integration/fixtures/**",
+        "__test__/integration/utils/**"
+    ];
+    static buildTestDirExclusions(prefix) {
+        return VitestConfig.TEST_DIR_EXCLUSIONS.map((pattern)=>`${prefix}${pattern}`);
+    }
     static discoverWorkspaceProjects() {
         if (VitestConfig.cachedProjects && VitestConfig.cachedVitestProjects) return {
             projects: VitestConfig.cachedProjects,
@@ -161,32 +373,83 @@ class VitestConfig {
             const srcScan = VitestConfig.scanForTestFiles(srcDirPath);
             const testScan = hasTestDir ? VitestConfig.scanForTestFiles(testDirPath) : {
                 hasUnit: false,
-                hasE2e: false
+                hasE2e: false,
+                hasInt: false
             };
             const hasUnit = srcScan.hasUnit || testScan.hasUnit;
             const hasE2e = srcScan.hasE2e || testScan.hasE2e;
-            const hasBoth = hasUnit && hasE2e;
+            const hasInt = srcScan.hasInt || testScan.hasInt;
+            const kindCount = [
+                hasUnit,
+                hasE2e,
+                hasInt
+            ].filter(Boolean).length;
+            const shouldSuffix = kindCount >= 2;
             const prefix = "." === relativePath ? "" : `${relativePath}/`;
             const srcGlob = `${prefix}src`;
             const testGlob = hasTestDir ? `${prefix}__test__` : null;
+            const testDirExcludes = hasTestDir ? VitestConfig.buildTestDirExclusions(prefix) : [];
+            const setupFile = VitestConfig.detectSetupFile(pkgPath);
+            const setupFiles = setupFile ? [
+                `${prefix}${setupFile}`
+            ] : void 0;
             if (hasUnit) vitestProjects.push(VitestProject.unit({
-                name: hasBoth ? `${packageName}:unit` : packageName,
-                include: VitestConfig.buildIncludes(srcGlob, testGlob, "*.{test,spec}.ts"),
+                name: shouldSuffix ? `${packageName}:unit` : packageName,
+                include: VitestConfig.buildIncludes(srcGlob, testGlob, "*.{test,spec}.{ts,tsx,js,jsx}"),
                 overrides: {
                     test: {
+                        ...setupFiles ? {
+                            setupFiles
+                        } : {},
                         exclude: [
-                            "**/*.e2e.{test,spec}.ts"
+                            "**/*.e2e.{test,spec}.*",
+                            "**/*.int.{test,spec}.*",
+                            ...testDirExcludes
                         ]
                     }
                 }
             }));
             if (hasE2e) vitestProjects.push(VitestProject.e2e({
-                name: hasBoth ? `${packageName}:e2e` : packageName,
-                include: VitestConfig.buildIncludes(srcGlob, testGlob, "*.e2e.{test,spec}.ts")
+                name: shouldSuffix ? `${packageName}:e2e` : packageName,
+                include: VitestConfig.buildIncludes(srcGlob, testGlob, "*.e2e.{test,spec}.{ts,tsx,js,jsx}"),
+                overrides: {
+                    test: {
+                        ...setupFiles ? {
+                            setupFiles
+                        } : {},
+                        exclude: [
+                            ...testDirExcludes
+                        ]
+                    }
+                }
+            }));
+            if (hasInt) vitestProjects.push(VitestProject.int({
+                name: shouldSuffix ? `${packageName}:int` : packageName,
+                include: VitestConfig.buildIncludes(srcGlob, testGlob, "*.int.{test,spec}.{ts,tsx,js,jsx}"),
+                overrides: {
+                    test: {
+                        ...setupFiles ? {
+                            setupFiles
+                        } : {},
+                        exclude: [
+                            ...testDirExcludes
+                        ]
+                    }
+                }
             }));
-            if (!hasUnit && !hasE2e) vitestProjects.push(VitestProject.unit({
+            if (!hasUnit && !hasE2e && !hasInt) vitestProjects.push(VitestProject.unit({
                 name: packageName,
-                include: VitestConfig.buildIncludes(srcGlob, testGlob, "*.{test,spec}.ts")
+                include: VitestConfig.buildIncludes(srcGlob, testGlob, "*.{test,spec}.{ts,tsx,js,jsx}"),
+                overrides: {
+                    test: {
+                        ...setupFiles ? {
+                            setupFiles
+                        } : {},
+                        exclude: [
+                            ...testDirExcludes
+                        ]
+                    }
+                }
             }));
         }
         VitestConfig.cachedProjects = projects;
@@ -196,28 +459,36 @@ class VitestConfig {
             vitestProjects
         };
     }
-    static getCoverageConfig(specificProject, projects, options) {
+    static resolveThresholds(options) {
+        if (options?.coverage === void 0) return {
+            ...VitestConfig.COVERAGE_LEVELS.strict
+        };
+        if ("string" == typeof options.coverage) return {
+            ...VitestConfig.COVERAGE_LEVELS[options.coverage]
+        };
+        return {
+            ...options.coverage
+        };
+    }
+    static getCoverageConfig(specificProjects, projects, options) {
         const exclude = [
-            "**/*.{test,spec}.ts"
+            ...VitestConfig.DEFAULT_COVERAGE_EXCLUDE,
+            ...options?.coverageExclude ?? []
         ];
-        const t = VitestConfig.DEFAULT_THRESHOLD;
-        const thresholds = {
-            lines: options?.thresholds?.lines ?? t,
-            functions: options?.thresholds?.functions ?? t,
-            branches: options?.thresholds?.branches ?? t,
-            statements: options?.thresholds?.statements ?? t
-        };
+        const thresholds = VitestConfig.resolveThresholds(options);
         const toSrcGlob = (relPath)=>{
             const prefix = "." === relPath ? "" : `${relPath}/`;
             return `${prefix}src/**/*.ts`;
         };
-        if (specificProject) {
-            const baseName = specificProject.replace(/:(unit|e2e)$/, "");
-            const relPath = projects[baseName];
-            if (void 0 !== relPath) return {
-                include: [
-                    toSrcGlob(relPath)
-                ],
+        if (specificProjects.length > 0) {
+            const includes = [];
+            for (const sp of specificProjects){
+                const baseName = sp.replace(/:(unit|e2e|int)$/, "");
+                const relPath = projects[baseName];
+                if (void 0 !== relPath) includes.push(toSrcGlob(relPath));
+            }
+            if (includes.length > 0) return {
+                include: includes,
                 exclude,
                 thresholds
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@savvy-web/vitest",
-  "version": "0.2.2",
+  "version": "1.0.0",
   "private": false,
   "description": "Vitest utility functions for Silk Suite deployment system",
   "homepage": "https://github.com/savvy-web/vitest#readme",
@@ -25,11 +25,12 @@
     "workspace-tools": "^0.41.0"
   },
   "peerDependencies": {
-    "@types/node": "^25.2.0",
+    "@types/node": "^25.5.0",
     "@typescript/native-preview": "^7.0.0-dev.20260124.1",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^4.1.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0",
+    "vitest-agent-reporter": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "@types/node": {
@@ -46,6 +47,9 @@
     },
     "vitest": {
       "optional": false
+    },
+    "vitest-agent-reporter": {
+      "optional": false
     }
   },
   "files": [