@savvy-web/vitest 1.4.0 → 1.5.0

package/index.d.ts

@@ -1,556 +1,523 @@
-/**
- * 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
- */
-
-import type { AgentPluginOptions } from 'vitest-agent-reporter';
-import { TestProjectInlineConfiguration } from 'vitest/config';
-import type { ViteUserConfig } from 'vitest/config';
-
-/**
- * Pass-through configuration for `vitest-agent-reporter`'s `AgentPlugin`.
- *
- * @see {@link VitestConfigOptions.agentReporter}
- *
- * @public
- */
-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 }
-
-/**
- * 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
- */
-export declare class VitestConfig {
-    /** 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 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 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.
-     */
-    private static applyKindOverrides;
-    /**
-     * 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.
-     */
-    private static getSpecificProjects;
-    /**
-     * 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.
-     */
-    private static getPackageNameFromPath;
-    /**
-     * Checks whether a path is an existing directory.
-     *
-     * @privateRemarks
-     * Consolidates the repeated `statSync` + `isDirectory()` + try/catch
-     * 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 all three kinds (unit, e2e, and int) are
-     * found, avoiding unnecessary filesystem traversal.
-     */
-    private static scanForTestFiles;
-    /**
-     * Builds include glob patterns for a given relative path and optional
-     * 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.
-     *
-     * @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.
-     */
-    private static discoverWorkspaceProjects;
-    /**
-     * Resolves coverage thresholds from options.
-     *
-     * @privateRemarks
-     * Priority: `options.coverage` (name or object) \> `COVERAGE_LEVELS.none`.
-     */
-    private static resolveThresholds;
-    /**
-     * Resolves coverage targets from options.
-     *
-     * @privateRemarks
-     * Priority: `options.coverageTargets` (name or object) \> `COVERAGE_LEVELS.basic`.
-     */
-    private static resolveTargets;
-    /**
-     * 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.
-     */
-    private static getCoverageConfig;
-}
-
-/**
- * Options for {@link VitestConfig.create}.
- *
- * @public
- */
-export declare interface VitestConfigOptions {
-    /**
-     * Coverage level name or explicit thresholds object.
-     *
-     * @remarks
-     * 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 `"none"` (lines: 0, branches: 0, functions: 0, statements: 0)
-     */
-    coverage?: CoverageLevelName | CoverageThresholds;
-    /**
-     * Coverage targets communicated to `vitest-agent-reporter`.
-     *
-     * @remarks
-     * Targets inform the reporter where coverage gaps exist but do **not**
-     * cause test failures. When the agent reporter is enabled, these
-     * thresholds are forwarded to the plugin's `reporter.coverageTargets`.
-     *
-     * If {@link VitestConfigOptions.agentReporter | agentReporter} is an
-     * object with its own `reporter.coverageTargets`, the explicit plugin
-     * option takes precedence and a warning is logged.
-     *
-     * @defaultValue `"basic"` (lines: 50, branches: 50, functions: 50, statements: 50)
-     */
-    coverageTargets?: 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;
-}
-
-/**
- * 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
- */
-export declare class VitestProject {
-    #private;
-    private constructor();
-    /**
-     * The project name.
-     * @see {@link VitestProjectOptions.name}
-     */
-    get name(): string;
-    /**
-     * The test kind (e.g., `"unit"`, `"e2e"`, or a custom string).
-     * @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.
-     *
-     * @returns A {@link https://vitest.dev/config/ | TestProjectInlineConfiguration}
-     *   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.
-     *
-     * @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: VitestProjectOptions): VitestProject;
-    /**
-     * 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: 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`.
-     *
-     * @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: VitestProjectKind, options: VitestProjectOptions): VitestProject;
-}
-
-/**
- * The kind of test a {@link VitestProject} represents.
- *
- * @remarks
- * The built-in factories {@link VitestProject.unit | unit()} and
- * {@link VitestProject.e2e | e2e()} correspond to the `"unit"` and `"e2e"`
- * values respectively. The {@link VitestProject.custom | custom()} factory
- * accepts an arbitrary string that is stored as the kind.
- *
- * @public
- */
-export declare type VitestProjectKind = "unit" | "e2e" | "int" | (string & {});
-
-/**
- * Options for constructing a {@link VitestProject}.
- *
- * @see {@link VitestProject.unit} for creating unit test projects
- * @see {@link VitestProject.e2e} for creating e2e test projects
- * @see {@link VitestProject.custom} for creating custom test projects
- *
- * @public
- */
-export declare interface VitestProjectOptions {
-    /**
-     * The project name, typically a package name optionally suffixed
-     * with `:unit` or `:e2e` when both kinds exist in the same package.
-     */
-    name: string;
-    /** Glob patterns for test file inclusion. */
-    include: string[];
-    /**
-     * The test kind. Defaults to `"unit"`.
-     * @defaultValue `"unit"`
-     */
-    kind?: VitestProjectKind;
-    /**
-     * Vitest-native config fields to merge over the factory defaults.
-     *
-     * @remarks
-     * The {@link VitestProjectOptions.name | name} and
-     * {@link VitestProjectOptions.include | include} fields always take
-     * precedence over any values provided in overrides.
-     *
-     * @see {@link https://vitest.dev/config/ | Vitest Configuration} for available fields
-     */
-    overrides?: Partial<TestProjectInlineConfiguration>;
-}
-
-export { }
+import { TestProjectInlineConfiguration, TestProjectInlineConfiguration as TestProjectInlineConfiguration$1, ViteUserConfig } from "vitest/config";
+import { AgentPluginOptions } from "vitest-agent-reporter";
+
+//#region src/index.d.ts
+/**
+ * The kind of test a {@link VitestProject} represents.
+ *
+ * @remarks
+ * The built-in factories {@link VitestProject.unit | unit()} and
+ * {@link VitestProject.e2e | e2e()} correspond to the `"unit"` and `"e2e"`
+ * values respectively. The {@link VitestProject.custom | custom()} factory
+ * accepts an arbitrary string that is stored as the kind.
+ *
+ * @public
+ */
+type VitestProjectKind = "unit" | "e2e" | "int" | (string & {});
+/**
+ * Options for constructing a {@link VitestProject}.
+ *
+ * @see {@link VitestProject.unit} for creating unit test projects
+ * @see {@link VitestProject.e2e} for creating e2e test projects
+ * @see {@link VitestProject.custom} for creating custom test projects
+ *
+ * @public
+ */
+interface VitestProjectOptions {
+  /**
+   * The project name, typically a package name optionally suffixed
+   * with `:unit` or `:e2e` when both kinds exist in the same package.
+   */
+  name: string;
+  /** Glob patterns for test file inclusion. */
+  include: string[];
+  /**
+   * The test kind. Defaults to `"unit"`.
+   * @defaultValue `"unit"`
+   */
+  kind?: VitestProjectKind;
+  /**
+   * Vitest-native config fields to merge over the factory defaults.
+   *
+   * @remarks
+   * The {@link VitestProjectOptions.name | name} and
+   * {@link VitestProjectOptions.include | include} fields always take
+   * precedence over any values provided in overrides.
+   *
+   * @see {@link https://vitest.dev/config/ | Vitest Configuration} for available fields
+   */
+  overrides?: Partial<TestProjectInlineConfiguration$1>;
+}
+/**
+ * Pass-through configuration for `vitest-agent-reporter`'s `AgentPlugin`.
+ *
+ * @see {@link VitestConfigOptions.agentReporter}
+ *
+ * @public
+ */
+type AgentReporterConfig = AgentPluginOptions;
+/**
+ * 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
+ */
+type KindOverride = Partial<TestProjectInlineConfiguration$1["test"]> | ((projects: Map<string, VitestProject>) => void);
+/**
+ * Options for {@link VitestConfig.create}.
+ *
+ * @public
+ */
+interface VitestConfigOptions {
+  /**
+   * Coverage level name or explicit thresholds object.
+   *
+   * @remarks
+   * 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 `"none"` (lines: 0, branches: 0, functions: 0, statements: 0)
+   */
+  coverage?: CoverageLevelName | CoverageThresholds;
+  /**
+   * Coverage targets communicated to `vitest-agent-reporter`.
+   *
+   * @remarks
+   * Targets inform the reporter where coverage gaps exist but do **not**
+   * cause test failures. When the agent reporter is enabled, these
+   * thresholds are forwarded to the plugin's `reporter.coverageTargets`.
+   *
+   * If {@link VitestConfigOptions.agentReporter | agentReporter} is an
+   * object with its own `reporter.coverageTargets`, the explicit plugin
+   * option takes precedence and a warning is logged.
+   *
+   * @defaultValue `"basic"` (lines: 50, branches: 50, functions: 50, statements: 50)
+   */
+  coverageTargets?: 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;
+}
+/**
+ * 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
+ */
+type PostProcessCallback = (config: ViteUserConfig) => ViteUserConfig | undefined;
+/**
+ * Coverage thresholds with all four metrics required.
+ *
+ * @public
+ */
+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;
+}
+/**
+ * Named coverage level presets available on {@link VitestConfig.COVERAGE_LEVELS}.
+ *
+ * @public
+ */
+type CoverageLevelName = "none" | "basic" | "standard" | "strict" | "full";
+/**
+ * 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
+ */
+declare class VitestProject {
+  #private;
+  private constructor();
+  /**
+   * The project name.
+   * @see {@link VitestProjectOptions.name}
+   */
+  get name(): string;
+  /**
+   * The test kind (e.g., `"unit"`, `"e2e"`, or a custom string).
+   * @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.
+   *
+   * @returns A {@link https://vitest.dev/config/ | TestProjectInlineConfiguration}
+   *   with all defaults and overrides merged
+   */
+  toConfig(): TestProjectInlineConfiguration$1;
+  /**
+   * 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$1>): 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.
+   *
+   * @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: VitestProjectOptions): VitestProject;
+  /**
+   * 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: 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`.
+   *
+   * @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: VitestProjectKind, options: VitestProjectOptions): VitestProject;
+}
+/**
+ * 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
+ */
+declare class VitestConfig {
+  /** 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 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 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.
+   */
+  private static applyKindOverrides;
+  /**
+   * 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.
+   */
+  private static getSpecificProjects;
+  /**
+   * 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.
+   */
+  private static getPackageNameFromPath;
+  /**
+   * Checks whether a path is an existing directory.
+   *
+   * @privateRemarks
+   * Consolidates the repeated `statSync` + `isDirectory()` + try/catch
+   * 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 all three kinds (unit, e2e, and int) are
+   * found, avoiding unnecessary filesystem traversal.
+   */
+  private static scanForTestFiles;
+  /**
+   * Builds include glob patterns for a given relative path and optional
+   * 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.
+   *
+   * @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.
+   */
+  private static discoverWorkspaceProjects;
+  /**
+   * Resolves coverage thresholds from options.
+   *
+   * @privateRemarks
+   * Priority: `options.coverage` (name or object) \> `COVERAGE_LEVELS.none`.
+   */
+  private static resolveThresholds;
+  /**
+   * Resolves coverage targets from options.
+   *
+   * @privateRemarks
+   * Priority: `options.coverageTargets` (name or object) \> `COVERAGE_LEVELS.basic`.
+   */
+  private static resolveTargets;
+  /**
+   * 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.
+   */
+  private static getCoverageConfig;
+}
+//#endregion
+export { AgentReporterConfig, CoverageLevelName, CoverageThresholds, KindOverride, PostProcessCallback, type TestProjectInlineConfiguration, VitestConfig, VitestConfigOptions, VitestProject, VitestProjectKind, VitestProjectOptions };
+//# sourceMappingURL=index.d.ts.map