@savvy-web/vitest 1.4.0 → 1.5.1

package/index.js

@@ -3,520 +3,786 @@ 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";
-        const { test: defaultTest, ...defaultRest } = defaults;
-        const { test: overrideTest, ...overrideRest } = options.overrides ?? {};
-        this.#config = {
-            extends: true,
-            ...defaultRest,
-            ...overrideRest,
-            test: {
-                ...defaultTest,
-                ...overrideTest,
-                name: options.name,
-                include: options.include
-            }
-        };
-    }
-    get name() {
-        return this.#name;
-    }
-    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,
-            kind: "unit"
-        }, {
-            test: {
-                environment: "node"
-            }
-        });
-    }
-    static e2e(options) {
-        const concurrency = Math.max(1, Math.min(8, Math.floor(cpus().length / 2)));
-        return new VitestProject({
-            ...options,
-            kind: "e2e"
-        }, {
-            test: {
-                environment: "node",
-                testTimeout: 120000,
-                hookTimeout: 60000,
-                maxConcurrency: concurrency
-            }
-        });
-    }
-    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,
-            kind
-        }, {});
-    }
-}
-class VitestConfig {
-    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 async create(options, postProcess) {
-        const specificProjects = VitestConfig.getSpecificProjects();
-        const { projects, vitestProjects } = VitestConfig.discoverWorkspaceProjects();
-        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",
-            "github-actions"
-        ] : [
-            "default"
-        ];
-        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 targets = VitestConfig.resolveTargets(options);
-            const hasExplicitTargets = agentOpts.reporter?.coverageTargets !== void 0;
-            if (hasExplicitTargets && options?.coverageTargets !== void 0) console.warn("[@savvy-web/vitest] Both top-level coverageTargets and agentReporter.reporter.coverageTargets are set. Using agentReporter.reporter.coverageTargets.");
-            const plugin = AgentPlugin({
-                strategy: "own",
-                ...agentOpts,
-                reporter: {
-                    coverageThresholds: {
-                        ...thresholds
-                    },
-                    ...!hasExplicitTargets ? {
-                        coverageTargets: {
-                            ...targets
-                        }
-                    } : {},
-                    ...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 getSpecificProjects() {
-        const args = process.argv;
-        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 {
-            const content = readFileSync(join(packagePath, "package.json"), "utf8");
-            return JSON.parse(content).name ?? null;
-        } catch  {
-            return null;
-        }
-    }
-    static isDirectory(dirPath) {
-        try {
-            return statSync(dirPath).isDirectory();
-        } catch  {
-            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
-            });
-            for (const entry of entries){
-                if (entry.isDirectory()) {
-                    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|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 && hasInt) break;
-            }
-        } catch  {}
-        return {
-            hasUnit,
-            hasE2e,
-            hasInt
-        };
-    }
-    static buildIncludes(srcGlob, testGlob, pattern) {
-        const includes = [
-            `${srcGlob}/**/${pattern}`
-        ];
-        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,
-            vitestProjects: VitestConfig.cachedVitestProjects
-        };
-        const cwd = process.cwd();
-        const workspaceRoot = getWorkspaceManagerRoot(cwd) ?? cwd;
-        const workspacePaths = getWorkspacePackagePaths(workspaceRoot) ?? [];
-        const projects = {};
-        const vitestProjects = [];
-        for (const pkgPath of workspacePaths){
-            const packageName = VitestConfig.getPackageNameFromPath(pkgPath);
-            if (!packageName) continue;
-            const srcDirPath = join(pkgPath, "src");
-            if (!VitestConfig.isDirectory(srcDirPath)) continue;
-            const relativePath = relative(workspaceRoot, pkgPath) || ".";
-            projects[packageName] = relativePath;
-            const testDirPath = join(pkgPath, "__test__");
-            const hasTestDir = VitestConfig.isDirectory(testDirPath);
-            const srcScan = VitestConfig.scanForTestFiles(srcDirPath);
-            const testScan = hasTestDir ? VitestConfig.scanForTestFiles(testDirPath) : {
-                hasUnit: false,
-                hasE2e: false,
-                hasInt: false
-            };
-            const hasUnit = srcScan.hasUnit || testScan.hasUnit;
-            const hasE2e = srcScan.hasE2e || testScan.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: shouldSuffix ? `${packageName}:unit` : packageName,
-                include: VitestConfig.buildIncludes(srcGlob, testGlob, "*.{test,spec}.{ts,tsx,js,jsx}"),
-                overrides: {
-                    test: {
-                        ...setupFiles ? {
-                            setupFiles
-                        } : {},
-                        exclude: [
-                            "**/*.e2e.{test,spec}.*",
-                            "**/*.int.{test,spec}.*",
-                            ...testDirExcludes
-                        ]
-                    }
-                }
-            }));
-            if (hasE2e) vitestProjects.push(VitestProject.e2e({
-                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 && !hasInt) vitestProjects.push(VitestProject.unit({
-                name: packageName,
-                include: VitestConfig.buildIncludes(srcGlob, testGlob, "*.{test,spec}.{ts,tsx,js,jsx}"),
-                overrides: {
-                    test: {
-                        ...setupFiles ? {
-                            setupFiles
-                        } : {},
-                        exclude: [
-                            ...testDirExcludes
-                        ]
-                    }
-                }
-            }));
-        }
-        VitestConfig.cachedProjects = projects;
-        VitestConfig.cachedVitestProjects = vitestProjects;
-        return {
-            projects,
-            vitestProjects
-        };
-    }
-    static resolveThresholds(options) {
-        if (options?.coverage === void 0) return {
-            ...VitestConfig.COVERAGE_LEVELS.none
-        };
-        if ("string" == typeof options.coverage) return {
-            ...VitestConfig.COVERAGE_LEVELS[options.coverage]
-        };
-        return {
-            ...options.coverage
-        };
-    }
-    static resolveTargets(options) {
-        if (options?.coverageTargets === void 0) return {
-            ...VitestConfig.COVERAGE_LEVELS.basic
-        };
-        if ("string" == typeof options.coverageTargets) return {
-            ...VitestConfig.COVERAGE_LEVELS[options.coverageTargets]
-        };
-        return {
-            ...options.coverageTargets
-        };
-    }
-    static getCoverageConfig(specificProjects, projects, options) {
-        const exclude = [
-            ...VitestConfig.DEFAULT_COVERAGE_EXCLUDE,
-            ...options?.coverageExclude ?? []
-        ];
-        const thresholds = VitestConfig.resolveThresholds(options);
-        const toSrcGlob = (relPath)=>{
-            const prefix = "." === relPath ? "" : `${relPath}/`;
-            return `${prefix}src/**/*.ts`;
-        };
-        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
-            };
-        }
-        return {
-            include: Object.values(projects).map(toSrcGlob),
-            exclude,
-            thresholds
-        };
-    }
-}
-export { VitestConfig, VitestProject };
+
+//#region src/index.ts
+/**
+* Vitest utility functions for automatic project configuration discovery
+* in pnpm monorepo workspaces.
+*
+* @remarks
+* This package provides two main classes:
+*
+* - {@link VitestProject} - Represents a single Vitest project with sensible
+*   defaults per test kind (unit, e2e, or custom).
+*
+* - {@link VitestConfig} - Orchestrates workspace discovery, coverage
+*   configuration, reporter selection, and callback invocation.
+*
+* @example
+* ```typescript
+* import { VitestConfig } from "@savvy-web/vitest";
+*
+* export default VitestConfig.create();
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* Represents a single Vitest project with sensible defaults per test kind.
+*
+* @remarks
+* Instances are created through static factory methods. The private constructor
+* enforces that all projects are built with validated merge semantics.
+*
+* Override merge precedence (highest wins):
+* 1. `name` and `include` from options (always win)
+* 2. `overrides.test` fields
+* 3. Factory defaults for `test`
+* 4. Top-level: `overrides` rest spreads over factory defaults rest
+*
+* @example
+* ```typescript
+* import { VitestProject } from "@savvy-web/vitest";
+*
+* const unitProject = VitestProject.unit({
+*   name: "@savvy-web/my-lib",
+*   include: ["src/**\/*.test.ts"],
+* });
+*
+* const e2eProject = VitestProject.e2e({
+*   name: "@savvy-web/my-lib:e2e",
+*   include: ["test/e2e/**\/*.test.ts"],
+* });
+*
+* const config = unitProject.toConfig();
+* ```
+*
+* @public
+*/
+var VitestProject = class VitestProject {
+	#name;
+	#kind;
+	#config;
+	#coverageExcludes = [];
+	constructor(options, defaults) {
+		this.#name = options.name;
+		this.#kind = options.kind ?? "unit";
+		const { test: defaultTest, ...defaultRest } = defaults;
+		const { test: overrideTest, ...overrideRest } = options.overrides ?? {};
+		this.#config = {
+			extends: true,
+			...defaultRest,
+			...overrideRest,
+			test: {
+				...defaultTest,
+				...overrideTest,
+				name: options.name,
+				include: options.include
+			}
+		};
+	}
+	/**
+	* The project name.
+	* @see {@link VitestProjectOptions.name}
+	*/
+	get name() {
+		return this.#name;
+	}
+	/**
+	* The test kind (e.g., `"unit"`, `"e2e"`, or a custom string).
+	* @see {@link VitestProjectKind}
+	*/
+	get kind() {
+		return this.#kind;
+	}
+	/**
+	* 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() {
+		return this.#coverageExcludes;
+	}
+	/**
+	* Returns the vitest-native inline configuration object.
+	*
+	* @returns A {@link https://vitest.dev/config/ | TestProjectInlineConfiguration}
+	*   with all defaults and overrides merged
+	*/
+	toConfig() {
+		return this.#config;
+	}
+	/**
+	* 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() {
+		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;
+	}
+	/**
+	* 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) {
+		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;
+	}
+	/**
+	* Appends glob patterns to the test include list.
+	*
+	* @param patterns - Glob patterns to add
+	* @returns `this` for chaining
+	*/
+	addInclude(...patterns) {
+		const { test: existingTest, ...rest } = this.#config;
+		this.#config = {
+			...rest,
+			test: {
+				...existingTest,
+				include: [...existingTest?.include ?? [], ...patterns]
+			}
+		};
+		return this;
+	}
+	/**
+	* Appends glob patterns to the test exclude list.
+	*
+	* @param patterns - Glob patterns to add
+	* @returns `this` for chaining
+	*/
+	addExclude(...patterns) {
+		const { test: existingTest, ...rest } = this.#config;
+		this.#config = {
+			...rest,
+			test: {
+				...existingTest,
+				exclude: [...existingTest?.exclude ?? [], ...patterns]
+			}
+		};
+		return 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) {
+		this.#coverageExcludes.push(...patterns);
+		return this;
+	}
+	/**
+	* Creates a unit test project with sensible defaults.
+	*
+	* @remarks
+	* Defaults applied: `extends: true`, `environment: "node"`.
+	*
+	* @param options - Project options (the `kind` field is forced to `"unit"`)
+	* @returns A new {@link VitestProject} configured for unit tests
+	*
+	* @example
+	* ```typescript
+	* import { VitestProject } from "@savvy-web/vitest";
+	*
+	* const project = VitestProject.unit({
+	*   name: "@savvy-web/my-lib",
+	*   include: ["src/**\/*.test.ts"],
+	* });
+	* ```
+	*/
+	static unit(options) {
+		return new VitestProject({
+			...options,
+			kind: "unit"
+		}, { test: { environment: "node" } });
+	}
+	/**
+	* Creates an e2e test project with sensible defaults.
+	*
+	* @remarks
+	* Defaults applied: `extends: true`, `environment: "node"`,
+	* `testTimeout: 120_000`, `hookTimeout: 60_000`,
+	* `maxConcurrency: clamp(floor(cpus / 2), 1, 8)`.
+	*
+	* @param options - Project options (the `kind` field is forced to `"e2e"`)
+	* @returns A new {@link VitestProject} configured for e2e tests
+	*
+	* @example
+	* ```typescript
+	* import { VitestProject } from "@savvy-web/vitest";
+	*
+	* const project = VitestProject.e2e({
+	*   name: "@savvy-web/my-lib:e2e",
+	*   include: ["test/e2e/**\/*.test.ts"],
+	* });
+	* ```
+	*/
+	static e2e(options) {
+		const concurrency = Math.max(1, Math.min(8, Math.floor(cpus().length / 2)));
+		return new VitestProject({
+			...options,
+			kind: "e2e"
+		}, { test: {
+			environment: "node",
+			testTimeout: 12e4,
+			hookTimeout: 6e4,
+			maxConcurrency: concurrency
+		} });
+	}
+	/**
+	* 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) {
+		const concurrency = Math.max(1, Math.min(8, Math.floor(cpus().length / 2)));
+		return new VitestProject({
+			...options,
+			kind: "int"
+		}, { test: {
+			environment: "node",
+			testTimeout: 6e4,
+			hookTimeout: 3e4,
+			maxConcurrency: concurrency
+		} });
+	}
+	/**
+	* Creates a custom test project with no preset defaults beyond `extends: true`.
+	*
+	* @remarks
+	* Use this factory when the built-in `unit()` and `e2e()` presets do not
+	* match your needs. The `kind` string is stored on the instance but does
+	* not influence any default configuration.
+	*
+	* @param kind - A custom kind string (e.g., `"integration"`, `"smoke"`)
+	* @param options - Project options
+	* @returns A new {@link VitestProject} with no preset defaults
+	*
+	* @example
+	* ```typescript
+	* import { VitestProject } from "@savvy-web/vitest";
+	*
+	* const project = VitestProject.custom("integration", {
+	*   name: "@savvy-web/my-lib:integration",
+	*   include: ["test/integration/**\/*.test.ts"],
+	* });
+	* ```
+	*/
+	static custom(kind, options) {
+		return new VitestProject({
+			...options,
+			kind
+		}, {});
+	}
+};
+/**
+* Utility class for generating Vitest configuration in monorepo workspaces.
+*
+* @remarks
+* This class automatically discovers packages in a workspace that contain a
+* `src/` directory and generates appropriate {@link VitestProject} configurations.
+* Tests are discovered by filename convention:
+*
+* | Pattern | Kind |
+* | --- | --- |
+* | `*.test.ts` / `*.spec.ts` | unit |
+* | `*.e2e.test.ts` / `*.e2e.spec.ts` | e2e |
+*
+* It supports both running all tests and targeting specific projects via the
+* `--project` command line argument.
+*
+* Results are cached in static properties so that repeated config evaluations
+* during watch mode or HMR do not re-scan the filesystem.
+*
+* @example
+* ```typescript
+* import { VitestConfig } from "@savvy-web/vitest";
+*
+* export default VitestConfig.create();
+* ```
+*
+* @public
+*/
+var VitestConfig = class VitestConfig {
+	/** Default glob patterns excluded from coverage reporting. */
+	static DEFAULT_COVERAGE_EXCLUDE = [
+		"**/*.{test,spec}.{ts,tsx,js,jsx}",
+		"**/__test__/**",
+		"**/generated/**"
+	];
+	/**
+	* 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 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;
+	/**
+	* Creates a complete Vitest configuration by discovering workspace projects
+	* and generating appropriate settings.
+	*
+	* @param options - Optional declarative configuration
+	* @param postProcess - Optional escape-hatch callback for full config control
+	* @returns The assembled Vitest configuration
+	*
+	* @see {@link VitestConfigOptions} for available options
+	* @see {@link PostProcessCallback} for the post-process callback signature
+	*/
+	static async create(options, postProcess) {
+		const specificProjects = VitestConfig.getSpecificProjects();
+		const { projects, vitestProjects } = VitestConfig.discoverWorkspaceProjects();
+		const thresholds = VitestConfig.resolveThresholds(options);
+		const coverageConfig = VitestConfig.getCoverageConfig(specificProjects, projects, options);
+		const workingProjects = vitestProjects.map((p) => p.clone());
+		VitestConfig.applyKindOverrides(workingProjects, options);
+		let config = { test: {
+			reporters: Boolean(process.env.GITHUB_ACTIONS) ? ["default", "github-actions"] : ["default"],
+			projects: workingProjects.map((p) => p.toConfig()),
+			...options?.pool ? { pool: options.pool } : {},
+			coverage: {
+				provider: "v8",
+				...coverageConfig,
+				enabled: true
+			}
+		} };
+		if (options?.agentReporter !== false) {
+			const agentOpts = typeof options?.agentReporter === "object" ? options.agentReporter : {};
+			const targets = VitestConfig.resolveTargets(options);
+			const hasExplicitTargets = agentOpts.reporter?.coverageTargets !== void 0;
+			if (hasExplicitTargets && options?.coverageTargets !== void 0) console.warn("[@savvy-web/vitest] Both top-level coverageTargets and agentReporter.reporter.coverageTargets are set. Using agentReporter.reporter.coverageTargets.");
+			const plugin = AgentPlugin({
+				strategy: "own",
+				...agentOpts,
+				reporter: {
+					coverageThresholds: { ...thresholds },
+					...!hasExplicitTargets ? { coverageTargets: { ...targets } } : {},
+					...agentOpts.reporter
+				}
+			});
+			config.plugins = [plugin];
+		}
+		if (postProcess) {
+			const result = postProcess(config);
+			if (result !== void 0) config = result;
+		}
+		return config;
+	}
+	/**
+	* 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 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 (override === void 0) continue;
+			const projectsOfKind = vitestProjects.filter((p) => p.kind === kind);
+			if (typeof override === "function") {
+				const map = /* @__PURE__ */ new Map();
+				for (const p of projectsOfKind) map.set(p.name, p);
+				override(map);
+			} else for (const p of projectsOfKind) p.override({ test: override });
+		}
+	}
+	/**
+	* 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. All `--project` flags are
+	* collected to support multi-project coverage scoping.
+	*/
+	static getSpecificProjects() {
+		const args = process.argv;
+		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 (arg === "--project" && i + 1 < args.length) {
+				const value = args[i + 1];
+				if (value) projects.push(value);
+				i++;
+			}
+		}
+		return projects;
+	}
+	/**
+	* Reads the `name` field from a package's `package.json`.
+	*
+	* @privateRemarks
+	* Uses try/catch because the package.json may not exist or may be malformed.
+	* Returns `null` to signal the caller should skip this package.
+	*/
+	static getPackageNameFromPath(packagePath) {
+		try {
+			const content = readFileSync(join(packagePath, "package.json"), "utf8");
+			return JSON.parse(content).name ?? null;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Checks whether a path is an existing directory.
+	*
+	* @privateRemarks
+	* Consolidates the repeated `statSync` + `isDirectory()` + try/catch
+	* pattern used throughout workspace discovery.
+	*/
+	static isDirectory(dirPath) {
+		try {
+			return statSync(dirPath).isDirectory();
+		} catch {
+			return false;
+		}
+	}
+	/** Extensions probed (in order) when detecting a setup file. */
+	static SETUP_FILE_EXTENSIONS = [
+		"ts",
+		"tsx",
+		"js",
+		"jsx"
+	];
+	/**
+	* 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.
+	*/
+	static detectSetupFile(packagePath) {
+		for (const ext of VitestConfig.SETUP_FILE_EXTENSIONS) {
+			const candidate = join(packagePath, `vitest.setup.${ext}`);
+			try {
+				if (statSync(candidate).isFile()) return `vitest.setup.${ext}`;
+			} catch {}
+		}
+		return null;
+	}
+	/**
+	* Recursively scans a directory for test files and classifies them by kind.
+	*
+	* @privateRemarks
+	* Short-circuits as soon as all three kinds (unit, e2e, and int) are
+	* found, avoiding unnecessary filesystem traversal.
+	*/
+	static scanForTestFiles(dirPath) {
+		let hasUnit = false;
+		let hasE2e = false;
+		let hasInt = false;
+		try {
+			const entries = readdirSync(dirPath, { withFileTypes: true });
+			for (const entry of entries) {
+				if (entry.isDirectory()) {
+					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|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 && hasInt) break;
+			}
+		} catch {}
+		return {
+			hasUnit,
+			hasE2e,
+			hasInt
+		};
+	}
+	/**
+	* Builds include glob patterns for a given relative path and optional
+	* test directory.
+	*/
+	static buildIncludes(srcGlob, testGlob, pattern) {
+		const includes = [`${srcGlob}/**/${pattern}`];
+		if (testGlob) includes.push(`${testGlob}/**/${pattern}`);
+		return includes;
+	}
+	/**
+	* Conventional subdirectories under `__test__/` that hold helpers, not
+	* test files, and should be excluded from test discovery.
+	*/
+	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/**"
+	];
+	/**
+	* 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.
+	*/
+	static buildTestDirExclusions(prefix) {
+		return VitestConfig.TEST_DIR_EXCLUSIONS.map((pattern) => `${prefix}${pattern}`);
+	}
+	/**
+	* Discovers all packages in the workspace that contain a `src/` directory
+	* and generates {@link VitestProject} instances based on filename conventions.
+	*
+	* @privateRemarks
+	* When a package has both unit and e2e test files, projects are suffixed
+	* with `:unit` and `:e2e` to disambiguate. Packages with `src/` but no
+	* test files still get a unit project entry as a forward-looking placeholder.
+	*/
+	static discoverWorkspaceProjects() {
+		if (VitestConfig.cachedProjects && VitestConfig.cachedVitestProjects) return {
+			projects: VitestConfig.cachedProjects,
+			vitestProjects: VitestConfig.cachedVitestProjects
+		};
+		const cwd = process.cwd();
+		const workspaceRoot = getWorkspaceManagerRoot(cwd) ?? cwd;
+		const workspacePaths = getWorkspacePackagePaths(workspaceRoot) ?? [];
+		const projects = {};
+		const vitestProjects = [];
+		for (const pkgPath of workspacePaths) {
+			const packageName = VitestConfig.getPackageNameFromPath(pkgPath);
+			if (!packageName) continue;
+			const srcDirPath = join(pkgPath, "src");
+			if (!VitestConfig.isDirectory(srcDirPath)) continue;
+			const relativePath = relative(workspaceRoot, pkgPath) || ".";
+			projects[packageName] = relativePath;
+			const testDirPath = join(pkgPath, "__test__");
+			const hasTestDir = VitestConfig.isDirectory(testDirPath);
+			const srcScan = VitestConfig.scanForTestFiles(srcDirPath);
+			const testScan = hasTestDir ? VitestConfig.scanForTestFiles(testDirPath) : {
+				hasUnit: false,
+				hasE2e: false,
+				hasInt: false
+			};
+			const hasUnit = srcScan.hasUnit || testScan.hasUnit;
+			const hasE2e = srcScan.hasE2e || testScan.hasE2e;
+			const hasInt = srcScan.hasInt || testScan.hasInt;
+			const shouldSuffix = [
+				hasUnit,
+				hasE2e,
+				hasInt
+			].filter(Boolean).length >= 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: shouldSuffix ? `${packageName}:unit` : packageName,
+				include: VitestConfig.buildIncludes(srcGlob, testGlob, "*.{test,spec}.{ts,tsx,js,jsx}"),
+				overrides: { test: {
+					...setupFiles ? { setupFiles } : {},
+					exclude: [
+						"**/*.e2e.{test,spec}.*",
+						"**/*.int.{test,spec}.*",
+						...testDirExcludes
+					]
+				} }
+			}));
+			if (hasE2e) vitestProjects.push(VitestProject.e2e({
+				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 && !hasInt) vitestProjects.push(VitestProject.unit({
+				name: packageName,
+				include: VitestConfig.buildIncludes(srcGlob, testGlob, "*.{test,spec}.{ts,tsx,js,jsx}"),
+				overrides: { test: {
+					...setupFiles ? { setupFiles } : {},
+					exclude: [...testDirExcludes]
+				} }
+			}));
+		}
+		VitestConfig.cachedProjects = projects;
+		VitestConfig.cachedVitestProjects = vitestProjects;
+		return {
+			projects,
+			vitestProjects
+		};
+	}
+	/**
+	* Resolves coverage thresholds from options.
+	*
+	* @privateRemarks
+	* Priority: `options.coverage` (name or object) \> `COVERAGE_LEVELS.none`.
+	*/
+	static resolveThresholds(options) {
+		if (options?.coverage === void 0) return { ...VitestConfig.COVERAGE_LEVELS.none };
+		if (typeof options.coverage === "string") return { ...VitestConfig.COVERAGE_LEVELS[options.coverage] };
+		return { ...options.coverage };
+	}
+	/**
+	* Resolves coverage targets from options.
+	*
+	* @privateRemarks
+	* Priority: `options.coverageTargets` (name or object) \> `COVERAGE_LEVELS.basic`.
+	*/
+	static resolveTargets(options) {
+		if (options?.coverageTargets === void 0) return { ...VitestConfig.COVERAGE_LEVELS.basic };
+		if (typeof options.coverageTargets === "string") return { ...VitestConfig.COVERAGE_LEVELS[options.coverageTargets] };
+		return { ...options.coverageTargets };
+	}
+	/**
+	* Generates coverage configuration including thresholds.
+	*
+	* @privateRemarks
+	* Strips `:unit`/`:e2e`/`:int` suffix when looking up project paths for
+	* `--project` filtering, since coverage applies to the entire package
+	* regardless of test kind. When multiple `--project` flags are provided,
+	* coverage includes are unioned across all matched packages.
+	*/
+	static getCoverageConfig(specificProjects, projects, options) {
+		const exclude = [...VitestConfig.DEFAULT_COVERAGE_EXCLUDE, ...options?.coverageExclude ?? []];
+		const thresholds = VitestConfig.resolveThresholds(options);
+		const toSrcGlob = (relPath) => {
+			return `${relPath === "." ? "" : `${relPath}/`}src/**/*.ts`;
+		};
+		if (specificProjects.length > 0) {
+			const includes = [];
+			for (const sp of specificProjects) {
+				const relPath = projects[sp.replace(/:(unit|e2e|int)$/, "")];
+				if (relPath !== void 0) includes.push(toSrcGlob(relPath));
+			}
+			if (includes.length > 0) return {
+				include: includes,
+				exclude,
+				thresholds
+			};
+		}
+		return {
+			include: Object.values(projects).map(toSrcGlob),
+			exclude,
+			thresholds
+		};
+	}
+};
+
+//#endregion
+export { VitestConfig, VitestProject };