@vitest-agent/plugin 1.0.0

package/index.d.ts

@@ -0,0 +1,1216 @@
+import { TestTagDefinition } from "@vitest/runner";
+import { AgentPluginOptions, AgentReporterOptions, ConsoleMode, CoverageBaselines, CoverageInput, CoverageLevel, CoverageLevelName, CoverageLevelName as CoverageLevelName$1, CoverageReport, EnvironmentDetector, OutputFormat, ResolvedReporterConfig, ResolvedThresholds, RunEvent, SettingsInput, StackFrameInput, Transport, VitestAgentReporterFactory, resolveCoverageInput, validateCoverageConfig } from "@vitest-agent/sdk";
+import { Context, Effect, Layer, LogLevel, Option } from "effect";
+import { TestProjectInlineConfiguration } from "vitest/config";
+import { ResolvedConfig, VitestPluginContext } from "vitest/node";
+import { SourceMap } from "magic-string";
+import * as NodeContext from "@effect/platform-node/NodeContext";
+import * as SqliteMigrator from "@effect/sql-sqlite-node/SqliteMigrator";
+
+//#region src/utils/tag.d.ts
+/**
+ * Options for a `Tag`, mirroring `TestTagDefinition` minus the `name` field.
+ * @public
+ */
+type TagOptions = Omit<TestTagDefinition, "name">;
+/**
+ * A validated Vitest tag with its `name` string and a `TestTagDefinition` for registration.
+ * @public
+ */
+declare class Tag {
+  /** The tag name string (validated on construction). */
+  readonly name: string;
+  /** The full `TestTagDefinition` object to pass to Vitest's `test.tags` config. */
+  readonly definition: TestTagDefinition;
+  private constructor();
+  /**
+   * Create a validated `Tag`.
+   * @param name - Tag identifier; must not be empty, reserved, or contain forbidden characters
+   * @param options - Optional timeout, retry, and other Vitest tag settings
+   * @returns A new `Tag` instance
+   */
+  static make(name: string, options?: TagOptions): Tag;
+}
+//#endregion
+//#region src/utils/discover-strategy.d.ts
+/**
+ * Resolved metadata about a discovered test module.
+ * @public
+ */
+interface ModuleInfo {
+  /** Absolute path to the module file. */
+  readonly path: string;
+  /** Path relative to the workspace root, using forward slashes. */
+  readonly relativePath: string;
+  /** Basename of the file (e.g. `"foo.test.ts"`). */
+  readonly filename: string;
+  /** The `name` field from the nearest `package.json`. */
+  readonly packageName: string;
+  /** Absolute path to the package directory. */
+  readonly packagePath: string;
+}
+/**
+ * Parsed `package.json` fields that strategies may inspect.
+ * @public
+ */
+interface PackageJson {
+  readonly name?: string;
+  readonly version?: string;
+  readonly private?: boolean;
+  readonly [key: string]: unknown;
+}
+/**
+ * Input passed to `DiscoverStrategy.buildProject` for each workspace package.
+ * @public
+ */
+interface DiscoverInput {
+  /** Package name from `package.json`. */
+  readonly name: string;
+  /** Absolute path to the package directory. */
+  readonly path: string;
+  /** Path relative to the workspace root, using forward slashes. */
+  readonly relativePath: string;
+  /** Absolute path to the workspace root. */
+  readonly workspaceRoot: string;
+  /** Parsed `package.json` contents, when available. */
+  readonly packageJson?: PackageJson;
+}
+/**
+ * Context object passed to a `ClassifyFn`.
+ * @public
+ */
+interface ClassifyContext {
+  /** Metadata for the module being classified. */
+  readonly module: ModuleInfo;
+  /** All tags registered on the active strategy. */
+  readonly tags: ReadonlyArray<Tag>;
+  /** Tag names returned by the previous classifier layer (empty for the base layer). */
+  readonly inherited: ReadonlyArray<string>;
+}
+/**
+ * A function that maps a module to an array of tag names.
+ * @public
+ */
+type ClassifyFn = (ctx: ClassifyContext) => ReadonlyArray<string>;
+/**
+ * Options for `DiscoverStrategy.create`.
+ * @public
+ */
+interface DiscoverStrategyCreateOptions {
+  /** Tags to register on the strategy. */
+  readonly tags: ReadonlyArray<Tag>;
+  /** Function that produces a Vitest project config for a package, or `null` to skip it. */
+  readonly buildProject: (input: DiscoverInput) => Promise<TestProjectInlineConfiguration | null>;
+  /** Function that maps a module to tag names. */
+  readonly classify: ClassifyFn;
+}
+/**
+ * Options for `DiscoverStrategy.extend`.
+ * @public
+ */
+interface DiscoverStrategyExtendOptions {
+  /** Extra tags to append to the strategy's tag list. */
+  readonly additionalTags?: ReadonlyArray<Tag>;
+  /** Override or supplement the project-building logic. Receives the inherited result as a second argument. */
+  readonly buildProject?: (input: DiscoverInput, inherited: TestProjectInlineConfiguration | null) => Promise<TestProjectInlineConfiguration | null>;
+  /** Override or supplement the classification logic. */
+  readonly classify?: ClassifyFn;
+}
+/**
+ * Abstract base for workspace discovery strategies. Implement `buildProject` and
+ * `classify` to control which packages become Vitest projects and how their test
+ * files are tagged. Use `DiscoverStrategy.create` to build a concrete instance
+ * from plain functions, or extend `DefaultDiscoverStrategy` to layer on top of
+ * the built-in unit/int/e2e heuristics.
+ * @public
+ */
+declare abstract class DiscoverStrategy {
+  abstract readonly tags: ReadonlyArray<Tag>;
+  abstract get tagDefinitions(): ReadonlyArray<TestTagDefinition>;
+  abstract buildProject(input: DiscoverInput): Promise<TestProjectInlineConfiguration | null>;
+  abstract classify(ctx: {
+    module: ModuleInfo;
+  }): ReadonlyArray<string>;
+  abstract extend(options: DiscoverStrategyExtendOptions): DiscoverStrategy;
+  static create(options: DiscoverStrategyCreateOptions): DiscoverStrategy;
+}
+/**
+ * The built-in `DiscoverStrategy` used by `AgentPlugin.discover` when no custom
+ * strategy is supplied. Registers `unit`, `int` (60 s timeout), and `e2e`
+ * (120 s timeout, retry in CI) tags and classifies test files by filename suffix
+ * (`.int.test.*` → `"int"`, `.e2e.test.*` → `"e2e"`, everything else → `"unit"`).
+ * @public
+ */
+declare class DefaultDiscoverStrategy extends DiscoverStrategy {
+  readonly tags: ReadonlyArray<Tag>;
+  get tagDefinitions(): ReadonlyArray<TestTagDefinition>;
+  classify(ctx: {
+    module: ModuleInfo;
+  }): ReadonlyArray<string>;
+  buildProject(input: DiscoverInput): Promise<TestProjectInlineConfiguration | null>;
+  extend(options: DiscoverStrategyExtendOptions): DiscoverStrategy;
+}
+//#endregion
+//#region src/utils/inject-tags.d.ts
+/**
+ * Return value of the Vite `transform` hook — the rewritten source code and its source map.
+ * @public
+ */
+interface InjectTagsResult {
+  /** The transformed source code string with injected `tags` arguments. */
+  code: string;
+  /** Source map correlating transformed positions back to the original source. */
+  map: SourceMap;
+}
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * Plugin options shape with the (function-typed) `reporter` factory added
+ * on top of the schema-defined `AgentPluginOptions`. Schema can't
+ * easily encode functions, so the factory lives outside the published
+ * Effect Schema.
+ * @public
+ */
+interface AgentPluginConstructorOptions extends AgentPluginOptions {
+  /**
+   * Factory that builds the reporter(s) the plugin will dispatch to.
+   * Defaults to the built-in `defaultReporter` from this package.
+   *
+   * Returning an array of reporters is supported: each is called once per
+   * run and their `RenderedOutput[]` results are concatenated and routed.
+   *
+   * Pass a factory function to swap out the default rendering pipeline:
+   * ```ts
+   * agentPlugin({ reporter: () => myReporter })
+   * ```
+   */
+  reporter?: VitestAgentReporterFactory;
+  /**
+   * Optional live event tap. The plugin forwards every per-test and
+   * per-module `RunEvent` to this callback as the test run
+   * progresses. Hosts drive a live renderer (Ink, debug logging) from
+   * here. Throwing taps are caught and logged to stderr.
+   */
+  onRunEvent?: (event: RunEvent) => void;
+  /**
+   * Controls the Vite transform hook that rewrites test() and it() call
+   * options to inject filename-derived tags. Pass a DiscoverStrategy
+   * instance to customize classification, or false to disable the
+   * transform entirely.
+   *
+   * Defaults to a fresh DefaultDiscoverStrategy (unit / int / e2e by
+   * filename suffix).
+   */
+  discoverStrategy?: DiscoverStrategy | false;
+}
+/**
+ * The version of this package, inlined at build time from
+ * `package.json#version` via rslib-builder's `__PACKAGE_VERSION__` substitution.
+ * Re-exported from the package barrel as the public symbol; defined here so
+ * the drift-check code path can read it without a circular import.
+ *
+ * @public
+ */
+declare const CURRENT_PLUGIN_VERSION: string;
+/**
+ * Vitest plugin that injects `AgentReporter` into the reporter chain.
+ *
+ * @param options - Plugin configuration options
+ * @param _layer - Internal: override the EnvironmentDetector layer (for testing)
+ * @returns Vitest plugin object with `configureVitest` hook
+ *
+ * @public
+ */
+declare function AgentPlugin(options?: AgentPluginConstructorOptions, _layer?: Layer.Layer<EnvironmentDetector>): {
+  name: "vitest-agent";
+  configureVitest(ctx: VitestPluginContext): Promise<void>;
+  transform?: (code: string, id: string) => InjectTagsResult | null;
+};
+/**
+ * Dual-output preset shape returned by `AgentPlugin.COVERAGE_LEVELS` and
+ * `AgentPlugin.COVERAGE_LEVELS_PER_FILE`. The `thresholds` half is
+ * passed to Vitest's native `coverage.thresholds`; the `coverageTargets`
+ * half is passed to `AgentPlugin({ coverageTargets })`.
+ *
+ * `thresholds` carries the optional `perFile` flag; `coverageTargets`
+ * does not — it inherits `perFile` from `coverage.thresholds.perFile`.
+ * @public
+ */
+interface CoverageLevelPreset {
+  readonly thresholds: {
+    readonly lines: number;
+    readonly functions: number;
+    readonly branches: number;
+    readonly statements: number;
+    readonly perFile?: boolean;
+  };
+  readonly coverageTargets: {
+    readonly lines: number;
+    readonly functions: number;
+    readonly branches: number;
+    readonly statements: number;
+  };
+}
+/**
+ * An entry added via {@link DiscoverBuilder.addProject}.
+ * @public
+ */
+interface AddProjectInput {
+  readonly name: string;
+  readonly path: string;
+}
+/**
+ * The resolved result of a {@link DiscoverBuilder} — a drop-in replacement for
+ * the old `DiscoverProjectsResult` on the public surface.
+ * @public
+ */
+interface DiscoverResult {
+  readonly projects: TestProjectInlineConfiguration[] | undefined;
+  readonly tags: TestTagDefinition[];
+}
+/**
+ * Thenable builder returned by `AgentPlugin.discover`. Calling `.then()`
+ * (or `await`-ing) materializes the discovery: workspace packages + added
+ * entries are each run through the active strategy's `buildProject`, with
+ * conflict detection on `name` or normalized path collisions.
+ *
+ * The builder is **immutable** — each `.addProject()` call returns a new
+ * builder; the original is unchanged.
+ *
+ * @public
+ */
+interface DiscoverBuilder extends PromiseLike<DiscoverResult> {
+  addProject(input: AddProjectInput): DiscoverBuilder;
+}
+/**
+ * Static namespace attached to the `AgentPlugin` factory function.
+ * Exposes coverage-level preset maps, auto-update tolerance functions, and the `discover` thenable builder.
+ * @public
+ */
+declare namespace AgentPlugin {
+  const COVERAGE_LEVELS: Readonly<Record<CoverageLevelName$1, CoverageLevelPreset>>;
+  const COVERAGE_LEVELS_PER_FILE: Readonly<Record<CoverageLevelName$1, CoverageLevelPreset>>;
+  /**
+   * Tolerance functions for Vitest's `coverage.thresholds.autoUpdate` field.
+   *
+   * Vitest's contract: `autoUpdate?: boolean | ((newThreshold: number) => number)`.
+   * Pass one of these functions directly. `standard` floors; `strict` ceils;
+   * `lenient` floors and subtracts 2 (clamped to 0) to leave a slack buffer.
+   *
+   * ```ts
+   * defineConfig({
+   *   test: { coverage: { thresholds: {
+   *     autoUpdate: AgentPlugin.COVERAGE_AUTOUPDATE.standard,
+   *     lines: 80,
+   *   } } },
+   * });
+   * ```
+   */
+  const COVERAGE_AUTOUPDATE: Readonly<{
+    standard: (n: number) => number;
+    strict: (n: number) => number;
+    lenient: (n: number) => number;
+  }>;
+  /**
+   * Discover Vitest project configs and tag definitions from the workspace layout.
+   * Returns a thenable {@link DiscoverBuilder} that supports `.addProject()` for
+   * non-package folders that hold tests.
+   *
+   * Awaiting (or calling `.then`) materializes the result. Each `.addProject()`
+   * returns a new immutable builder; the original is unchanged.
+   *
+   * Process-level cache: only the no-arg, no-added-projects call path caches by
+   * workspace root. Any `.addProject()` chain or explicit strategy bypasses it.
+   *
+   * ```ts
+   * export default async () => {
+   *   const { projects, tags } = await AgentPlugin.discover()
+   *     .addProject({ name: "integration", path: "./test-only" });
+   *   return defineConfig({
+   *     plugins: [AgentPlugin()],
+   *     test: { ...(projects ? { projects } : {}), tags },
+   *   });
+   * };
+   * ```
+   *
+   * @param strategy - Optional strategy or options object `{ strategy?, cwd? }`.
+   *   Pass a {@link DiscoverStrategy} directly, or an options object to also
+   *   specify a custom workspace root via `cwd`.
+   */
+  function discover(strategy?: DiscoverStrategy | {
+    strategy?: DiscoverStrategy;
+    cwd?: string;
+  }): DiscoverBuilder;
+  /**
+   * Run a shell command, suppressing all output unless the command fails.
+   * Designed for use in Vitest `globalSetup` files to run build steps or
+   * other preparatory scripts without polluting agent stdout.
+   *
+   * On failure the captured stderr and stdout are written to their respective
+   * streams before rethrowing, so the error is still visible to humans and
+   * surfaced in CI logs.
+   *
+   * ```ts
+   * // vitest.setup.ts
+   * import { AgentPlugin } from "@vitest-agent/plugin";
+   * export function setup() {
+   *   AgentPlugin.runScript("pnpm exec turbo run build:dev --output-logs=errors-only");
+   * }
+   * ```
+   */
+  function runScript(command: string): void;
+}
+//#endregion
+//#region src/reporter.d.ts
+/**
+ * Constructor argument shape for {@link AgentReporter}.
+ *
+ * The reporter is constructed by `AgentPlugin` in production with a
+ * fully-resolved set of plugin-internal values; tests sometimes
+ * construct it directly with a subset, so every field is optional and
+ * the constructor applies internal defaults. Public consumers building
+ * custom reporters do not touch this — they implement
+ * `VitestAgentReporterFactory` and the plugin calls them with a
+ * resolved `ReporterKit`.
+ *
+ * Extends the schema-defined `AgentReporterOptions` (which after
+ * the 2.0 cleanup carries only `projectFilter`) plus the function-typed
+ * and plugin-resolved fields the reporter needs at construction.
+ * @public
+ */
+interface AgentReporterConstructorOptions extends AgentReporterOptions {
+  reporter?: VitestAgentReporterFactory;
+  /**
+   * Optional event tap. The reporter constructs a `RunEvent` for
+   * each Vitest streaming callback (`onTestRunStart`,
+   * `onTestModuleQueued`, `onTestModuleStart`, `onTestCaseResult`,
+   * `onTestModuleEnd`, `onTestRunEnd`) and invokes this callback with
+   * the event. Hosts drive a live renderer (Ink, debug logging, etc.)
+   * from here without coupling the reporter to a specific transport.
+   *
+   * Errors thrown by the callback are caught and written to stderr —
+   * a malfunctioning tap must not break persistence.
+   */
+  onRunEvent?: (event: RunEvent) => void;
+  /**
+   * Operating mode resolved by AgentPlugin from Vitest's coverage.enabled.
+   * Defaults to "full" when AgentReporter is constructed directly (without
+   * the plugin). Phase 5 uses this to short-circuit persistence when ui-only.
+   *
+   * @internal
+   */
+  coverageMode?: "full" | "ui-only";
+  consoleMode?: ConsoleMode;
+  format?: OutputFormat;
+  mcp?: boolean;
+  githubActions?: boolean;
+  transport?: Transport;
+  /**
+   * Optional `test.passWithNoTests` value the plugin captured from the
+   * resolved Vitest config. The reporter forwards it onto the
+   * `ResolvedReporterConfig` it surfaces to renderers and the MCP
+   * `run_tests` tool.
+   */
+  passWithNoTests?: boolean;
+  coverageThresholds?: ResolvedThresholds | Record<string, unknown>;
+  coverageTargets?: ResolvedThresholds | Record<string, unknown>;
+  /**
+   * Test-only override: when set, bypasses the XDG path resolver and
+   * writes the SQLite database to `${cacheDir}/data.db`. Not a public
+   * user option — production deployments resolve the database path
+   * via the XDG / `vitest-agent.config.toml` stack inside the plugin.
+   *
+   * @internal
+   */
+  cacheDir?: string;
+}
+/**
+ * Vitest Reporter that produces structured output for LLM coding agents.
+ *
+ * @remarks
+ * `AgentReporter` implements three Vitest Reporter lifecycle hooks:
+ *
+ * - {@link AgentReporter.onInit | onInit} -- stores the Vitest instance
+ *   for project enumeration (used in Phase 2 overview generation)
+ * - {@link AgentReporter.onCoverage | onCoverage} -- stashes the istanbul
+ *   CoverageMap for merging into reports
+ * - {@link AgentReporter.onTestRunEnd | onTestRunEnd} -- groups test
+ *   modules by project, builds reports, writes data to SQLite,
+ *   updates the manifest, and emits console/GFM output
+ *
+ * The reporter handles both single-package repos and monorepos by grouping
+ * results via Vitest's native `TestProject` API. In single-project mode,
+ * results are written with project name "default".
+ *
+ * @privateRemarks
+ * The `onCoverage` hook fires **before** `onTestRunEnd` in Vitest's lifecycle.
+ * Coverage data must be stashed as instance state and merged during
+ * `onTestRunEnd`. This ordering is a Vitest design constraint, not a bug.
+ *
+ * @example
+ * ```typescript
+ * import { AgentReporter } from "@vitest-agent/plugin";
+ * import { defineConfig } from "vitest/config";
+ *
+ * export default defineConfig({
+ *   test: {
+ *     reporters: [
+ *       new AgentReporter({
+ *         cacheDir: ".vitest-agent",
+ *         consoleOutput: "failures",
+ *         coverageThresholds: { global: { lines: 80 } },
+ *       }),
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * @see `AgentPlugin` for the convenience plugin wrapper
+ * @see {@link https://vitest.dev/api/advanced/reporters.html | Vitest Reporter API}
+ * @public
+ */
+declare class AgentReporter {
+  private options;
+  private dbPath;
+  /**
+   * Set to `true` after the first `onTestRunEnd` invocation completes.
+   *
+   * Vitest can fire `onTestRunEnd` more than once per `vitest run` in
+   * some multi-project configurations (e.g., once per project group, with
+   * the same `testModules` array each time). The plugin pushes only ONE
+   * AgentReporter per run, so a fresh instance always starts with this
+   * flag `false`; the first call does the work and the flag prevents
+   * subsequent invocations from re-rendering and re-writing to the DB.
+   */
+  private rendered;
+  /**
+   * Stored Vitest instance from {@link AgentReporter.onInit | onInit}.
+   *
+   * @remarks
+   * Available for Phase 2 overview generation. Exposed as a public
+   * property (prefixed with `_`) for testing and extension purposes.
+   *
+   * @internal
+   */
+  _vitest: unknown;
+  private coverage;
+  private logLevel;
+  private logFile;
+  private onRunEvent;
+  /**
+   * Run-event channel. The plugin publishes one `RunEvent` per
+   * Vitest streaming callback onto this `PubSub`; the reporter factory
+   * receives it on the `ReporterKit` and a live-painting reporter
+   * (the default reporter in `stream` mode) subscribes to drive its mount.
+   * The plugin no longer owns any render mount itself.
+   *
+   * @internal
+   */
+  private runEvents;
+  /**
+   * Reporters resolved from the factory at run start (`onInit`). Reused
+   * by `onTestRunEnd` for the `render` call. Undefined when `onInit` did
+   * not run (tests invoking `onTestRunEnd` directly) — `onTestRunEnd`
+   * then resolves the factory itself.
+   *
+   * @internal
+   */
+  private reporters;
+  /**
+   * Whether the user supplied a custom `reporter` factory. A custom
+   * reporter may subscribe to the run-event channel in any console mode,
+   * so the streaming hooks publish events whenever this is true.
+   *
+   * @internal
+   */
+  private readonly hasCustomReporter;
+  private currentRunId;
+  private moduleStartedAt;
+  /**
+   * Wall-clock start stamp (`Date.now()`) for an in-flight Vitest
+   * setup/teardown hook, keyed `modulePath::hookType::scopeName`.
+   * `onHookStart` writes it, `onHookEnd` reads and clears it to derive
+   * `HookFinished.durationMs` — `ReportedHookContext` carries no
+   * duration of its own.
+   *
+   * @internal
+   */
+  private hookStartedAt;
+  constructor(options?: AgentReporterConstructorOptions);
+  /**
+   * The resolved reporter config built at construction time. Exposed for
+   * test inspection and Phase 5 short-circuit logic.
+   *
+   * This getter is @internal — do not reference in user-facing docs.
+   * @internal
+   */
+  get resolvedConfig(): ResolvedReporterConfig;
+  /**
+   * Store the Vitest instance for project enumeration.
+   *
+   * @remarks
+   * Called once at the start of the test run. The instance is stored
+   * for Phase 2 overview generation via `vitest.projects`.
+   *
+   * @param vitest - The Vitest instance
+   */
+  onInit(vitest: unknown): Promise<void>;
+  /**
+   * Resolve the reporter factory at run start.
+   *
+   * The factory is invoked here — before any streaming hook fires — so a
+   * reporter that paints live (the default reporter's Ink mount in `stream`
+   * mode) can subscribe to {@link AgentReporter.runEvents | the run-event
+   * channel} before the first `RunStarted` event. The kit built here
+   * carries neutral run health; `detail` is resolved health-aware again
+   * for the render kit at `onTestRunEnd`, and that kit is the one handed
+   * to `render`.
+   *
+   * A resolution failure degrades silently: `this.reporters` stays unset
+   * and `onTestRunEnd` resolves the factory itself from the render kit.
+   *
+   * @internal
+   */
+  private initReporters;
+  /**
+   * Should the streaming Vitest hooks publish `RunEvent`s? The
+   * hooks short-circuit when this is false to skip constructing event
+   * objects nothing will read: the default reporter consumes the channel
+   * only in `stream` mode, a custom reporter may consume it in any mode,
+   * and the user `onRunEvent` tap is fed off the same stream.
+   *
+   * @internal
+   */
+  private wantsRunEvents;
+  /**
+   * Publish a `RunEvent` onto the run-event channel and the
+   * user-supplied tap. A throwing publish or tap is caught and logged to
+   * stderr — a live-render bug must not break persistence.
+   *
+   * @internal
+   */
+  private emit;
+  /**
+   * Walk the suite parent chain to produce the suite-path array used
+   * in `RunEvent.TestStarted` / `RunEvent.TestFinished`.
+   *
+   * @internal
+   */
+  private collectSuitePath;
+  /**
+   * Vitest streaming hook: a test run is about to start. Mints a
+   * synthetic `runId` for the duration of this run and emits a
+   * `RunStarted` event for live subscribers.
+   */
+  onTestRunStart(_specifications: ReadonlyArray<unknown>): void;
+  /**
+   * Read the owning Vitest project name off a `TestModule`. Vitest 4.x
+   * attaches `project` to every module; an empty name (the unnamed
+   * default project) collapses to `undefined` so the renderer treats it
+   * as a single anonymous project.
+   *
+   * @internal
+   */
+  private moduleProjectName;
+  /**
+   * Vitest streaming hook: a test module has been queued.
+   */
+  onTestModuleQueued(testModule: {
+    relativeModuleId: string;
+    project?: {
+      name?: string;
+    };
+  }): void;
+  /**
+   * Vitest streaming hook: a test module is starting execution.
+   */
+  onTestModuleStart(testModule: {
+    relativeModuleId: string;
+    project?: {
+      name?: string;
+    };
+  }): void;
+  /**
+   * Vitest streaming hook: a test module has finished collecting its
+   * tests and suites, before execution begins.
+   */
+  onTestModuleCollected(testModule: {
+    relativeModuleId: string;
+    children: {
+      allTests(filter?: string): Iterable<unknown>;
+      allSuites(): Iterable<unknown>;
+    };
+  }): void;
+  /**
+   * Vitest streaming hook: a test case is about to run.
+   *
+   * Emits a standalone `TestStarted` so the renderer gets a render
+   * frame for the transient "running" state. `onTestCaseReady` fires
+   * before `onTestCaseResult`; emitting here — rather than synthesizing
+   * `TestStarted` back-to-back with `TestFinished` inside
+   * `onTestCaseResult` — gives the running state a real lifetime in the
+   * event stream and is the prerequisite for any future per-test
+   * animation.
+   */
+  onTestCaseReady(testCase: {
+    name: string;
+    parent?: {
+      type: string;
+      name: string;
+      parent?: unknown;
+    };
+    module?: {
+      relativeModuleId: string;
+    };
+  }): void;
+  /**
+   * Vitest streaming hook: a test case has produced a result.
+   *
+   * Emits only `TestFinished` — the matching `TestStarted` is emitted
+   * by `onTestCaseReady`, which fires earlier in the lifecycle.
+   */
+  onTestCaseResult(testCase: {
+    name: string;
+    parent?: {
+      type: string;
+      name: string;
+      parent?: unknown;
+    };
+    module?: {
+      relativeModuleId: string;
+    };
+    result(): {
+      state: string;
+      errors?: ReadonlyArray<{
+        message: string;
+        diff?: string;
+        expected?: unknown;
+        actual?: unknown;
+        stacks?: ReadonlyArray<unknown>;
+      }>;
+    } | undefined;
+    diagnostic(): {
+      duration: number;
+    } | undefined;
+  }): void;
+  /**
+   * Vitest streaming hook: a test module has finished. Emits a
+   * `ModuleFinished` carrying the tallied counts plus a duration
+   * derived from the module's diagnostic.
+   */
+  onTestModuleEnd(testModule: {
+    relativeModuleId: string;
+    project?: {
+      name?: string;
+    };
+    children: {
+      allTests(filter?: string): Iterable<{
+        result(): {
+          state: string;
+          errors?: ReadonlyArray<{
+            message: string;
+            name?: string;
+          }>;
+        } | undefined;
+        tags?: ReadonlyArray<string>;
+      }>;
+    };
+    diagnostic(): {
+      duration: number;
+    } | undefined;
+  }): void;
+  /**
+   * Walk a suite/test entity's parent chain to its owning module path.
+   *
+   * @internal
+   */
+  private entityModulePath;
+  /**
+   * Vitest streaming hook: a test suite is about to run.
+   */
+  onTestSuiteReady(testSuite: {
+    name: string;
+    module?: {
+      relativeModuleId?: string;
+    };
+    parent?: {
+      type: string;
+      name: string;
+      parent?: unknown;
+    };
+  }): void;
+  /**
+   * Vitest streaming hook: a test suite has finished running.
+   */
+  onTestSuiteResult(testSuite: {
+    name: string;
+    module?: {
+      relativeModuleId?: string;
+    };
+    parent?: {
+      type: string;
+      name: string;
+      parent?: unknown;
+    };
+    children: {
+      allTests(filter?: string): Iterable<{
+        result(): {
+          state: string;
+        } | undefined;
+      }>;
+    };
+  }): void;
+  /**
+   * Derive `modulePath` / `scopeName` / a stable key for a Vitest
+   * setup/teardown hook from its `ReportedHookContext` entity.
+   *
+   * @internal
+   */
+  private hookScope;
+  /**
+   * Vitest streaming hook: a `beforeAll` / `afterAll` / `beforeEach` /
+   * `afterEach` hook is starting.
+   */
+  onHookStart(hook: {
+    name: string;
+    entity?: {
+      name?: string;
+      relativeModuleId?: string;
+      module?: {
+        relativeModuleId?: string;
+      };
+    };
+  }): void;
+  /**
+   * Vitest streaming hook: a setup/teardown hook has finished. Duration
+   * is derived from the stamp `onHookStart` recorded — `ReportedHookContext`
+   * carries none of its own. Status is a best-effort read of the
+   * entity's collected errors.
+   */
+  onHookEnd(hook: {
+    name: string;
+    entity?: {
+      name?: string;
+      relativeModuleId?: string;
+      module?: {
+        relativeModuleId?: string;
+      };
+      errors?: () => ReadonlyArray<{
+        message: string;
+        stack?: string;
+        diff?: string;
+      }>;
+    };
+  }): void;
+  /**
+   * Vitest streaming hook: a captured `console.log` / `console.error`
+   * from user test code. The Vitest log carries a `taskId` rather than
+   * a module/test path; resolving it back to one would need the task
+   * registry, so `modulePath` / `testName` are left unset.
+   */
+  onUserConsoleLog(log: {
+    content: string;
+    type: "stdout" | "stderr";
+    time: number;
+  }): void;
+  /**
+   * Vitest streaming hook: the run exceeded its configured process
+   * timeout. Terminal — moves the renderer to a final frame.
+   */
+  onProcessTimeout(): void;
+  /**
+   * Vitest streaming hook: a test case recorded an annotation.
+   */
+  onTestCaseAnnotate(testCase: {
+    name: string;
+    parent?: {
+      type: string;
+      name: string;
+      parent?: unknown;
+    };
+    module?: {
+      relativeModuleId: string;
+    };
+  }, annotation: {
+    message: string;
+  }): void;
+  /**
+   * Vitest streaming hook: a test case recorded an artifact.
+   */
+  onTestCaseArtifactRecord(testCase: {
+    name: string;
+    parent?: {
+      type: string;
+      name: string;
+      parent?: unknown;
+    };
+    module?: {
+      relativeModuleId: string;
+    };
+  }, artifact: {
+    type?: string;
+  }): void;
+  /**
+   * Vitest streaming hook: watch mode has finished its initial run and
+   * is waiting for file changes.
+   */
+  onWatcherStart(): void;
+  /**
+   * Vitest streaming hook: watch mode is re-running because tracked
+   * files changed.
+   */
+  onWatcherRerun(files: ReadonlyArray<string>, trigger?: string): void;
+  private ensureDbPath;
+  /**
+   * Stash coverage data for merging into reports.
+   *
+   * @privateRemarks
+   * This hook fires **before** `onTestRunEnd` in Vitest's lifecycle.
+   * The coverage value is an istanbul CoverageMap that will be duck-typed
+   * and processed during `onTestRunEnd`.
+   *
+   * @param coverage - Istanbul CoverageMap (duck-typed at processing time)
+   *
+   * @see `processCoverage` for the duck-typing logic
+   */
+  onCoverage(coverage: unknown): void;
+  /**
+   * Process test results, write reports, and emit formatted output.
+   *
+   * @remarks
+   * This is the main lifecycle hook where all output is generated.
+   * Processing steps:
+   *
+   * 1. Group test modules by `testModule.project.name`
+   * 2. Process stashed coverage data (if available)
+   * 3. Build per-project `AgentReport` objects
+   * 4. Classify tests via HistoryTracker and attach classifications
+   * 5. Write settings, run, modules, test cases, and errors to SQLite
+   * 6. Write per-test history entries
+   * 7. Write baselines and trends
+   * 8. Emit console markdown (unless `"silent"`)
+   * 9. Write GFM summary to `GITHUB_STEP_SUMMARY` (if GitHub Actions)
+   *
+   * File write failures are logged to stderr but do not crash the test run.
+   *
+   * @param testModules - All test modules from the completed run
+   * @param unhandledErrors - Any unhandled errors during the run
+   * @param reason - Overall outcome: `"passed"`, `"failed"`, or `"interrupted"`
+   */
+  onTestRunEnd(testModules: ReadonlyArray<unknown>, unhandledErrors: ReadonlyArray<unknown>, reason: "passed" | "failed" | "interrupted"): Promise<void>;
+}
+//#endregion
+//#region src/utils/discover-projects.d.ts
+/**
+ * The resolved output of `discoverProjects` — projects and tag definitions ready for `defineConfig`.
+ * @public
+ */
+interface DiscoverProjectsResult {
+  readonly projects: TestProjectInlineConfiguration[] | undefined;
+  readonly tags: TestTagDefinition[];
+}
+/**
+ * Options for `discoverProjects`.
+ * @public
+ */
+interface DiscoverProjectsOptions {
+  readonly strategy?: DiscoverStrategy;
+  readonly cwd?: string;
+  readonly additionalEntries?: ReadonlyArray<{
+    readonly name: string;
+    readonly path: string;
+  }>;
+}
+/**
+ * Scan all workspace packages and additional entries through the active strategy and return projects + tags.
+ * @param options - Optional strategy, working directory, and extra project entries
+ * @returns Resolved projects and tag definitions
+ * @public
+ */
+declare function discoverProjects(options?: DiscoverProjectsOptions): Promise<DiscoverProjectsResult>;
+//#endregion
+//#region src/utils/classify-helpers.d.ts
+/**
+ * Creates a ClassifyFn that maps filename suffix patterns to tag arrays.
+ *
+ * Accepts two forms:
+ * - `Record<string, ReadonlyArray<string>>` — keys are exact suffix strings
+ *   (e.g. ".int.test.ts"); matched via `String.prototype.endsWith` against
+ *   `module.filename`.
+ * - `ReadonlyArray<readonly [RegExp, ReadonlyArray<string>]>` — each tuple is a
+ *   `[pattern, tags]` pair; matched via `RegExp.test` against `module.filename`.
+ *   First match wins.
+ *
+ * No match returns an empty array.
+ * @public
+ */
+declare function classifyByFilename(suffixMap: Record<string, ReadonlyArray<string>> | ReadonlyArray<readonly [RegExp, ReadonlyArray<string>]>): ClassifyFn;
+/**
+ * Creates a ClassifyFn that maps directory segment paths to tag arrays.
+ *
+ * Keys are directory-segment paths (e.g. `__test__/integration`). A module
+ * matches when `module.relativePath` contains the segment with `/` boundaries.
+ * Key `"integration"` matches `"integration/foo.test.ts"` and
+ * `"src/integration/foo.test.ts"` but NOT `"my-integration-tests/foo.test.ts"`.
+ *
+ * No match returns `[]`.
+ * @public
+ */
+declare function classifyByDirectory(dirMap: Record<string, ReadonlyArray<string>>): ClassifyFn;
+/**
+ * Composes multiple `ClassifyFn` values into one. Each classifier is called with
+ * the same context; results are concatenated in order and deduplicated by tag
+ * name (first occurrence wins). An empty list returns a function that always
+ * returns `[]`.
+ * @public
+ */
+declare function combineClassifiers(...fns: ReadonlyArray<ClassifyFn>): ClassifyFn;
+//#endregion
+//#region src/utils/find-test-files.d.ts
+/**
+ * Async file walker that returns matched absolute paths.
+ *
+ * Walks `dir` recursively via `node:fs/promises`. Skips `node_modules`, `.git`,
+ * and `dist` directories. Matches files against the supplied glob patterns
+ * relative to `dir` (e.g. `"src/**\/*.test.ts"`).
+ *
+ * Returns an empty array if `dir` does not exist or no files match.
+ * @param dir - Absolute path to the directory to walk
+ * @param patterns - Glob patterns to match against (relative to `dir`)
+ * @returns Absolute paths of matched test files
+ * @public
+ */
+declare function findTestFiles(dir: string, patterns: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
+//#endregion
+//#region src/layers/ReporterLive.d.ts
+/**
+ * Composition layer for a single `AgentReporter` run. Wires SQLite, migrations, and all service layers.
+ * @public
+ */
+declare const ReporterLive: (dbPath: string, logLevel?: LogLevel.LogLevel, logFile?: string) => Layer.Layer<import("@vitest-agent/sdk").DataStore | import("@effect/sql/SqlClient").SqlClient | CoverageAnalyzer | import("@vitest-agent/sdk").HistoryTracker | import("@vitest-agent/sdk").DataReader | import("@vitest-agent/sdk").DetailResolver | import("@vitest-agent/sdk").EnvironmentDetector | import("@vitest-agent/sdk").ExecutorResolver | import("@vitest-agent/sdk").FormatSelector | import("@vitest-agent/sdk").OutputRenderer | import("@effect/sql-sqlite-node/SqliteClient").SqliteClient | NodeContext.NodeContext, import("@effect/sql/SqlError").SqlError | SqliteMigrator.MigrationError | import("effect/ConfigError").ConfigError, never>;
+//#endregion
+//#region src/services/CoverageAnalyzer.d.ts
+interface CoverageOptions {
+  readonly thresholds: ResolvedThresholds;
+  readonly targets?: ResolvedThresholds;
+  readonly baselines?: CoverageBaselines;
+  readonly includeBareZero: boolean;
+}
+declare const CoverageAnalyzer_base: Context.TagClass<CoverageAnalyzer, "vitest-agent/CoverageAnalyzer", {
+  readonly process: (coverage: unknown, options: CoverageOptions) => Effect.Effect<Option.Option<CoverageReport>>;
+  readonly processScoped: (coverage: unknown, options: CoverageOptions, testedFiles: ReadonlyArray<string>) => Effect.Effect<Option.Option<CoverageReport>>;
+}>;
+/**
+ * Effect service for processing istanbul coverage maps into structured reports.
+ * @public
+ */
+declare class CoverageAnalyzer extends CoverageAnalyzer_base {}
+//#endregion
+//#region src/layers/CoverageAnalyzerLive.d.ts
+/**
+ * Live implementation of the CoverageAnalyzer service backed by istanbul.
+ * @public
+ */
+declare const CoverageAnalyzerLive: Layer.Layer<CoverageAnalyzer>;
+//#endregion
+//#region src/layers/CoverageAnalyzerTest.d.ts
+/**
+ * Test-double layer factory for CoverageAnalyzer. Pass a pre-built `CoverageReport` to inject.
+ * @public
+ */
+declare const CoverageAnalyzerTest: {
+  readonly layer: (data?: CoverageReport) => Layer.Layer<CoverageAnalyzer>;
+};
+//#endregion
+//#region src/services/ConfigValidation.d.ts
+/**
+ * A validation error produced by the ConfigValidation service.
+ * @public
+ */
+interface ValidationError {
+  readonly code: string;
+  readonly path?: string;
+  readonly message: string;
+  readonly remediation?: string;
+}
+/**
+ * A validation warning produced by the ConfigValidation service.
+ * @public
+ */
+interface ValidationWarning {
+  readonly code: string;
+  readonly path?: string;
+  readonly message: string;
+  readonly remediation?: string;
+}
+/**
+ * An informational message produced by the ConfigValidation service.
+ * @public
+ */
+interface ValidationInfo {
+  readonly code: string;
+  readonly message: string;
+}
+/**
+ * The aggregated result of a ConfigValidation run.
+ * @public
+ */
+interface ValidationResult {
+  readonly errors: ReadonlyArray<ValidationError>;
+  readonly warnings: ReadonlyArray<ValidationWarning>;
+  readonly info: ReadonlyArray<ValidationInfo>;
+}
+/**
+ * Input consumed by `ConfigValidation.validate`.
+ * @public
+ */
+interface ValidationInput {
+  readonly vitestConfig: ResolvedConfig;
+  readonly pluginOptions: AgentPluginOptions;
+}
+declare const ConfigValidation_base: Context.TagClass<ConfigValidation, "vitest-agent/ConfigValidation", {
+  readonly validate: (input: ValidationInput) => Effect.Effect<ValidationResult, never, never>;
+}>;
+/**
+ * Effect service for validating Vitest + plugin coverage configuration.
+ * @public
+ */
+declare class ConfigValidation extends ConfigValidation_base {}
+//#endregion
+//#region src/layers/ConfigValidationLive.d.ts
+/**
+ * Live implementation of the ConfigValidation service running the built-in rule registry.
+ * @public
+ */
+declare const ConfigValidationLive: Layer.Layer<ConfigValidation>;
+//#endregion
+//#region src/layers/ConfigValidationTest.d.ts
+/**
+ * Test-double layer factory for ConfigValidation. Pass a pre-built `ValidationResult` to inject.
+ * @public
+ */
+declare const ConfigValidationTest: {
+  readonly layer: (override?: ValidationResult) => Layer.Layer<ConfigValidation>;
+};
+//#endregion
+//#region src/utils/capture-env.d.ts
+/**
+ * Capture CI and GitHub Actions environment variables for persistence.
+ * @param env - The process environment record to read from
+ * @returns A filtered map of relevant environment variable keys and values
+ * @public
+ */
+declare function captureEnvVars(env: Record<string, string | undefined>): Record<string, string>;
+//#endregion
+//#region src/utils/capture-settings.d.ts
+/**
+ * Extract a serializable settings snapshot from the resolved Vitest config.
+ * @param config - The resolved Vitest config record
+ * @param vitestVersion - The running Vitest version string
+ * @returns A `SettingsInput` ready for persistence
+ * @public
+ */
+declare function captureSettings(config: Record<string, unknown>, vitestVersion: string): SettingsInput;
+/**
+ * Compute a stable SHA-256 hash of a settings record for change detection.
+ * @param settings - The settings record to hash (keys are sorted for stability)
+ * @returns A hex-encoded SHA-256 digest
+ * @public
+ */
+declare function hashSettings(settings: Record<string, unknown>): string;
+//#endregion
+//#region src/utils/process-failure.d.ts
+/**
+ * A single parsed stack frame as Vitest represents it.
+ * @public
+ */
+interface VitestStackFrameLike {
+  /** Absolute file path for the frame. */
+  readonly file?: string;
+  /** 1-based source line number. */
+  readonly line?: number;
+  /** 1-based source column number. */
+  readonly column?: number;
+  /** Function or method name at the call site. */
+  readonly method?: string;
+}
+/**
+ * A Vitest error object as passed to reporter hooks.
+ * @public
+ */
+interface VitestErrorLike {
+  readonly name?: string;
+  readonly message: string;
+  readonly stack?: string;
+  readonly stacks?: ReadonlyArray<VitestStackFrameLike>;
+}
+/**
+ * Convert a Vitest error into structured frame inputs (with source-map and
+ * function-boundary annotations) plus a stable failure signature.
+ *
+ * Returns `null` for the signature when no usable top frame is found
+ * (error has no stack, or every frame is in framework code). Frames may
+ * still be populated even when the signature is null.
+ * @public
+ */
+declare const processFailure: (error: VitestErrorLike) => {
+  frames: ReadonlyArray<StackFrameInput>;
+  signatureHash: string | null;
+};
+//#endregion
+//#region src/utils/resolve-thresholds.d.ts
+/**
+ * Loose record type matching Vitest's `coverage.thresholds` config input.
+ * @public
+ */
+type VitestThresholdsInput = Record<string, unknown>;
+/**
+ * Parse Vitest `coverage.thresholds` format into a normalized `ResolvedThresholds`.
+ * @param input - The raw `coverage.thresholds` object from Vitest config
+ * @returns Normalized thresholds with global, perFile, and pattern entries
+ * @public
+ */
+declare function resolveThresholds(input: VitestThresholdsInput | undefined): ResolvedThresholds;
+//#endregion
+//#region src/utils/strip-console-reporters.d.ts
+/**
+ * Built-in Vitest reporters that write to the console (stdout).
+ * These are the reporters suppressed when an agent takes over console output.
+ *
+ * @privateRemarks
+ * `"agent"` is the built-in Vitest reporter added in v4.1 that reduces
+ * console noise for AI agents. We strip it because our reporter replaces
+ * its functionality with structured markdown output.
+ *
+ * @see {@link https://vitest.dev/api/advanced/reporters.html | Vitest Reporter docs}
+ * @internal
+ */
+declare const CONSOLE_REPORTERS: Set<string>;
+/**
+ * Filter out built-in console reporters from a Vitest reporters array.
+ *
+ * Keeps custom reporters (class instances, file paths) and non-console
+ * built-in reporters (`json`, `junit`, `html`, `blob`, `github-actions`).
+ * Used by `AgentPlugin` in agent mode to suppress noisy console output.
+ *
+ * @param reporters - The Vitest `config.reporters` array
+ * @returns Filtered array with console reporters removed
+ *
+ * @internal
+ */
+declare function stripConsoleReporters(reporters: unknown[]): unknown[];
+//#endregion
+//#region src/index.d.ts
+/** Preset map for coverage levels without per-file enforcement. Mirrors `AgentPlugin.COVERAGE_LEVELS`. @public */
+declare const COVERAGE_LEVELS: Readonly<Record<import("@vitest-agent/sdk").CoverageLevelName, CoverageLevelPreset>>;
+/** Preset map for coverage levels with per-file enforcement. Mirrors `AgentPlugin.COVERAGE_LEVELS_PER_FILE`. @public */
+declare const COVERAGE_LEVELS_PER_FILE: Readonly<Record<import("@vitest-agent/sdk").CoverageLevelName, CoverageLevelPreset>>;
+/** Auto-update tolerance functions for `coverage.thresholds.autoUpdate`. Mirrors `AgentPlugin.COVERAGE_AUTOUPDATE`. @public */
+declare const COVERAGE_AUTOUPDATE: Readonly<{
+  standard: (n: number) => number;
+  strict: (n: number) => number;
+  lenient: (n: number) => number;
+}>;
+//#endregion
+export { type AddProjectInput, AgentPlugin, type AgentPluginConstructorOptions, AgentReporter, type AgentReporterConstructorOptions, CONSOLE_REPORTERS, COVERAGE_AUTOUPDATE, COVERAGE_LEVELS, COVERAGE_LEVELS_PER_FILE, CURRENT_PLUGIN_VERSION, type ClassifyContext, type ClassifyFn, ConfigValidation, ConfigValidationLive, ConfigValidationTest, CoverageAnalyzer, CoverageAnalyzerLive, CoverageAnalyzerTest, type CoverageInput, CoverageLevel, type CoverageLevelName, type CoverageLevelPreset, DefaultDiscoverStrategy, type DiscoverBuilder, type DiscoverInput, type PackageJson as DiscoverPackageJson, type DiscoverProjectsOptions, type DiscoverProjectsResult, type DiscoverResult, DiscoverStrategy, type DiscoverStrategyCreateOptions, type DiscoverStrategyExtendOptions, type InjectTagsResult, type ModuleInfo, ReporterLive, Tag, type TagOptions, type ValidationError, type ValidationInfo, type ValidationInput, type ValidationResult, type ValidationWarning, type VitestErrorLike, type VitestStackFrameLike, type VitestThresholdsInput, captureEnvVars, captureSettings, classifyByDirectory, classifyByFilename, combineClassifiers, discoverProjects, findTestFiles, hashSettings, processFailure, resolveCoverageInput, resolveThresholds, stripConsoleReporters, validateCoverageConfig };
+//# sourceMappingURL=index.d.ts.map