/** * vapor-chamber/vitest/mcp - a Vitest MCP server built on a schema command bus. * * Three tools. Their names are the bus's action names, camelCase as a schema * bus normalizes them (vitest-community/mcp's run_tests is runTests here): * * - `runTests` runs test files (all, or the `files` filters) in a Vitest that * stays warm between calls, and returns counts and each failure's message; * - `getTestResults` returns the last run again, and which files changed * since, so an agent knows when it is stale; * - `getCoverageGaps` runs the suite once with coverage, in a separate * `vitest run`, and lists per source file the uncovered lines, functions and * branch arms. * * WHAT AN AGENT CAN CHOOSE, AND WHAT IT CANNOT. The project root and the config * are fixed by whoever starts the server. An agent passes only `files`: Vitest * filters that select among the test files the project's own config already * includes. A filter that starts with `-` is refused, because the coverage run * passes filters on a command line, where it would be read as an option. * * WARM RUNS SEE EDITS BECAUSE THIS FILE WATCHES FOR THEM. Measured on Vitest * 5.0.1: `runTestSpecifications` on a warm instance re-ran the old module * after a test file and a source file were edited, until each path was passed * to `vitest.invalidateFile()`. The server records changed paths with * `fs.watch` and invalidates them just before each run; Vitest runs nothing on * its own. * * COVERAGE RUNS COLD, IN A CHILD PROCESS. A coverage provider initialised in a * warm instance slows every run, and in a Vitest created inside a Vitest test * worker it wrote no report at all (measured), so the one path that could not * be tested for real would be the one that reports coverage. * * Vitest's own output goes to stderr: on stdio, stdout is the protocol. * * @example * // an MCP client's server entry, in the project root * { "command": "npx", "args": ["vc-vitest-mcp"] } */ import { type BusSchema, createAsyncSchemaCommandBus } from 'vapor-chamber'; /** The tools, as a bus schema: `tools/list` is derived from it. */ export declare const VITEST_MCP_SCHEMA: BusSchema; /** Every tool name. */ export declare const VITEST_MCP_ACTIONS: string[]; export interface VitestMcpOptions { /** The project root. Default: the working directory. */ root?: string; /** A Vitest config file, as `--config` takes it. Default: Vitest's own lookup from the root. */ config?: string; } /** One failed test, as `runTests` reports it. */ export interface VitestMcpFailure { file: string; test: string; message: string; } /** What `runTests` returns. */ export interface VitestMcpRun { files: number; passed: number; failed: number; skipped: number; failures: VitestMcpFailure[]; /** Errors outside any test (a file that failed to load, an unhandled rejection). */ errors: string[]; } /** One source file with something uncovered, as `getCoverageGaps` reports it. */ export interface VitestMcpGap { file: string; /** Uncovered statement lines, as ranges: `"3, 8-9"`. */ uncoveredLines: string; uncoveredFunctions: string[]; uncoveredBranches: { line: number; type: string; uncoveredArms: number[]; arms: number; }[]; } /** A running server: the bus to serve, and `disposeAsync()`, which stops the watcher and closes Vitest. */ export interface VitestMcpServer { bus: ReturnType>; disposeAsync(): Promise; } type Loc = { start: { line: number; }; end: { line: number; }; }; type FileCoverage = { s: Record; statementMap: Record; f: Record; fnMap: Record; b: Record; branchMap: Record; }; /** Gaps from an Istanbul `coverage-final.json`, files with none left out. */ export declare function coverageGaps(report: Record, root: string): VitestMcpGap[]; /** * Start the server: a warm Vitest on `root`, a file watcher, and a schema bus * whose handlers are the three tools. Serve `bus` with `createMcpHandler` or * `serveMcpStdio`, passing an `actionFilter` that allows the tools * ({@link VITEST_MCP_ACTIONS}, or fewer). */ export declare function createVitestMcp(options?: VitestMcpOptions): Promise; /** * {@link createVitestMcp}, served over stdio with every tool allowed. Resolves * to its async dispose: it detaches from stdin and closes Vitest. */ export declare function serveVitestMcp(options?: VitestMcpOptions): Promise<() => Promise>; export {}; //# sourceMappingURL=vitest-mcp.d.ts.map