@vitest-agent/reporter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LiveInkRenderer.js

@@ -0,0 +1,119 @@
+import { SPINNER_FRAME_MS, StreamApp, reduceRenderState, spinnerFrameForTime } from "@vitest-agent/ui";
+import { initialRenderState } from "@vitest-agent/sdk";
+import { Box, render, renderToString } from "ink";
+import { createElement } from "react";
+
+//#region src/LiveInkRenderer.tsx
+/**
+* Create a {@link LiveInkRenderer} that drives a live Ink mount for
+* `consoleMode: "stream"`. Call `event(e)` for each `RunEvent` published
+* by the plugin; the renderer mounts on `RunStarted`, rerenders on each
+* subsequent event, and commits the final frame on `RunFinished` /
+* `RunTimedOut`.
+*
+* @public
+*/
+const createLiveInk = (options = {}) => {
+	let state = initialRenderState;
+	let instance = null;
+	let clock = null;
+	let firstRunStarted = false;
+	const targetStream = options.stream ?? process.stdout;
+	const frameWidth = () => {
+		const cols = targetStream.columns;
+		return typeof cols === "number" && cols > 1 ? cols - 1 : void 0;
+	};
+	const frameElement = () => {
+		const now = Date.now();
+		return createElement(Box, {
+			flexDirection: "column",
+			width: frameWidth()
+		}, createElement(StreamApp, {
+			state,
+			frameIndex: spinnerFrameForTime(now),
+			nowMs: now
+		}));
+	};
+	const mount = () => {
+		if (instance !== null) return;
+		instance = render(frameElement(), { stdout: targetStream });
+	};
+	const stopClock = () => {
+		if (clock === null) return;
+		clearInterval(clock);
+		clock = null;
+	};
+	const startClock = () => {
+		if (clock !== null) return;
+		clock = setInterval(() => {
+			if (instance === null) return;
+			try {
+				instance.rerender(frameElement());
+			} catch {
+				instance = null;
+				stopClock();
+			}
+		}, SPINNER_FRAME_MS);
+		clock.unref?.();
+	};
+	const tearDown = () => {
+		stopClock();
+		if (instance === null) return;
+		instance.unmount();
+		instance = null;
+		firstRunStarted = false;
+	};
+	return {
+		event(event) {
+			const previousPhase = state.phase;
+			state = reduceRenderState(state, event);
+			if (event._tag === "RunStarted" || previousPhase === "idle" && state.phase !== "idle") {
+				if (firstRunStarted) {
+					if (instance !== null) try {
+						instance.clear();
+					} catch {}
+				} else try {
+					mount();
+				} catch (err) {
+					process.stderr.write(`@vitest-agent/reporter: live ink renderer failed; falling back silently (${err.message})\n`);
+					instance = null;
+				}
+				firstRunStarted = true;
+				startClock();
+			} else if (instance !== null) try {
+				instance.rerender(frameElement());
+			} catch (err) {
+				process.stderr.write(`@vitest-agent/reporter: live ink renderer failed; falling back silently (${err.message})\n`);
+				instance = null;
+				stopClock();
+			}
+			if (event._tag === "RunFinished" || event._tag === "RunTimedOut") {
+				stopClock();
+				if (instance !== null) {
+					try {
+						instance.unmount();
+					} catch {}
+					instance = null;
+				} else {
+					const now = Date.now();
+					const finalFrameText = renderToString(createElement(StreamApp, {
+						state,
+						frameIndex: spinnerFrameForTime(now),
+						nowMs: now
+					}));
+					targetStream.write(`${finalFrameText}\n`);
+				}
+				firstRunStarted = false;
+			}
+		},
+		unmount() {
+			tearDown();
+		},
+		snapshot() {
+			return state;
+		}
+	};
+};
+
+//#endregion
+export { createLiveInk };

package/README.md

@@ -0,0 +1,61 @@
+# @vitest-agent/reporter
+
+[![npm](https://img.shields.io/npm/v/@vitest-agent/reporter?label=npm&color=cb3837)](https://www.npmjs.com/package/@vitest-agent/reporter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+> **Part of the [vitest-agent](https://vitest-agent.dev) ecosystem.** Most users want **[@vitest-agent/plugin](https://www.npmjs.com/package/@vitest-agent/plugin)**, which pulls this package in automatically. Install `@vitest-agent/reporter` directly only if you are writing a custom reporter.
+
+The default reporter package and the reference for custom-reporter authors. Ships `DefaultVitestAgentReporter`, owns the live React Ink mount lifecycle, and re-exports the reporter contract types and dispatch helpers — everything a custom factory needs in one import.
+
+## Features
+
+- **`DefaultVitestAgentReporter`** — the production default `VitestAgentReporterFactory` the plugin wires automatically; classifies runs into one of 12 shape × outcome cells, owns the Ink live-mount lifecycle, and emits a GitHub Actions Step Summary in CI
+- **Dispatch helpers** — `buildDispatchInputs`, `resolveCellOptions`, `renderAgentStringForReport`, `renderHumanStringForReport`
+- **Contract re-exports** — `VitestAgentReporterFactory`, `ReporterKit`, `ReporterRenderInput`, `RenderedOutput`, `VitestAgentReporter`, `ResolvedReporterConfig` all re-exported from `@vitest-agent/sdk` so you only need one import
+- **Worked example** — `DefaultVitestAgentReporter` source in this package is the canonical reference for the `VitestAgentReporterFactory` contract
+
+## Install
+
+```bash
+npm install --save-dev @vitest-agent/reporter
+# or
+pnpm add -D @vitest-agent/reporter
+```
+
+`@vitest-agent/reporter` arrives automatically as a dependency of `@vitest-agent/plugin`. Install it directly only when authoring a custom reporter.
+
+## Quick start
+
+```ts
+import type {
+  ReporterKit,
+  ReporterRenderInput,
+  RenderedOutput,
+  VitestAgentReporter,
+  VitestAgentReporterFactory,
+} from "@vitest-agent/reporter";
+
+const myReporter: VitestAgentReporterFactory = (kit: ReporterKit): VitestAgentReporter => ({
+  render(input: ReporterRenderInput): ReadonlyArray<RenderedOutput> {
+    const passed = input.reports.reduce((n, r) => n + r.summary.passed, 0);
+    return [{ target: "stdout", content: `${passed} passed\n` }];
+  },
+});
+```
+
+Pass the factory to the plugin:
+
+```ts
+import { AgentPlugin } from "@vitest-agent/plugin";
+
+AgentPlugin({ reporter: myReporter });
+```
+
+## Documentation
+
+Custom-reporter guide at [vitest-agent.dev/reporter](https://vitest-agent.dev/reporter).
+
+## License
+
+[MIT](LICENSE)

package/defaultReporter.js

@@ -0,0 +1,208 @@
+import { createLiveInk } from "./LiveInkRenderer.js";
+import { classifyOutcome, classifyRunShape, dispatch, dispatcherTable, reduceRenderStateAll, synthesizeFromAgentReport } from "@vitest-agent/ui";
+import { Effect, PubSub, Queue } from "effect";
+
+//#region src/defaultReporter.ts
+const summarizeProject = (report) => {
+	const collapsedTagCounts = report.tagCounts !== void 0 ? collapseTagCounts(report.tagCounts) : void 0;
+	const tagCountsHasEntries = collapsedTagCounts !== void 0 && Object.keys(collapsedTagCounts).length > 0;
+	const belowTargetCount = report.coverage?.belowTargetFiles?.length;
+	const violationsCount = report.coverage !== void 0 && report.coverage.lowCoverage.length > 0 ? report.coverage.lowCoverage.length : void 0;
+	return {
+		name: report.project ?? "default",
+		passCount: report.summary.passed,
+		failCount: report.summary.failed,
+		skipCount: report.summary.skipped,
+		durationMs: report.summary.duration,
+		...tagCountsHasEntries && collapsedTagCounts !== void 0 ? { tagCounts: collapsedTagCounts } : {},
+		...belowTargetCount !== void 0 ? { belowTarget: belowTargetCount } : {},
+		...violationsCount !== void 0 ? { violations: violationsCount } : {}
+	};
+};
+const collapseTagCounts = (entries) => {
+	const out = {};
+	if (entries === void 0) return out;
+	for (const [tag, entry] of Object.entries(entries)) {
+		const total = (entry.passed ?? 0) + (entry.failed ?? 0) + (entry.skipped ?? 0);
+		if (total > 0) out[tag] = total;
+	}
+	return out;
+};
+const collectBelowTarget = (reports) => {
+	const out = [];
+	for (const r of reports) {
+		const list = r.coverage?.belowTarget;
+		if (list !== void 0) out.push(...list);
+	}
+	return out;
+};
+const liftTrendSummary = (input) => {
+	const trend = input.trendSummary;
+	if (trend === void 0) return null;
+	return {
+		direction: trend.direction,
+		runCount: trend.runCount,
+		...trend.firstMetric !== void 0 ? { firstMetric: trend.firstMetric } : {}
+	};
+};
+/**
+* Build a `DispatchInputs` from a {@link ReporterRenderInput} and
+* the reduced `RenderState`.
+*
+* Exported so a custom reporter built on the same dispatcher can reuse
+* this assembly step without rebuilding it from scratch.
+*
+* @public
+*/
+const buildDispatchInputs = (state, input, overrides = {}) => {
+	const projects = input.reports.map((r) => summarizeProject(r));
+	return {
+		state,
+		shape: overrides.shape ?? classifyRunShape(state, projects),
+		outcome: overrides.outcome ?? classifyOutcome(state),
+		projects,
+		trend: liftTrendSummary(input),
+		belowTarget: collectBelowTarget(input.reports),
+		runCommand: overrides.runCommand ?? null
+	};
+};
+/**
+* Build `CellOptions` from a {@link ReporterKit}. Picks the kit's
+* resolved `noColor` value and the pre-bound OSC-8 hyperlink helper.
+*
+* @public
+*/
+const resolveCellOptions = (kit) => ({
+	noColor: kit.config.noColor,
+	osc8: kit.stdOsc8
+});
+const shouldRenderForMode = (mode) => mode === "agent";
+/**
+* Convenience helper for one-shot consumers (e.g. a CLI command
+* replaying a stored run). Synthesizes a minimal `ReporterRenderInput`
+* from a single `AgentReport`, classifies the shape and outcome, and
+* returns the dispatched agent-string for the matching cell. Equivalent
+* to the pre-2.0 `renderRun(events, "agent")` shortcut.
+*
+* @public
+*/
+const renderAgentStringForReport = (report) => {
+	const state = reduceRenderStateAll(synthesizeFromAgentReport(report));
+	const projects = [summarizeProject(report)];
+	return dispatch({
+		state,
+		shape: classifyRunShape(state, projects),
+		outcome: classifyOutcome(state),
+		projects,
+		trend: null,
+		belowTarget: collectBelowTarget([report]),
+		runCommand: null
+	}, {
+		noColor: true,
+		osc8: (_url, label) => label
+	});
+};
+/**
+* Same as {@link renderAgentStringForReport} but returns the Ink-half
+* rendered to a string via Ink's `renderToString`. ANSI escape
+* sequences are preserved so a terminal renders the colors live.
+* Returns the agent-string fallback when the matched cell has no Ink
+* half.
+*
+* @public
+*/
+const renderHumanStringForReport = async (report, options = {}) => {
+	const { renderToString } = await import("ink");
+	const state = reduceRenderStateAll(synthesizeFromAgentReport(report));
+	const projects = [summarizeProject(report)];
+	const inputs = {
+		state,
+		shape: classifyRunShape(state, projects),
+		outcome: classifyOutcome(state),
+		projects,
+		trend: null,
+		belowTarget: collectBelowTarget([report]),
+		runCommand: null
+	};
+	const opts = {
+		noColor: false,
+		osc8: (_url, label) => label
+	};
+	const cell = dispatcherTable[inputs.shape][inputs.outcome];
+	if (cell.ink === void 0) return dispatch(inputs, opts);
+	return renderToString(cell.ink(inputs, opts), { columns: options.width ?? 80 });
+};
+const renderGithubSummary = (input) => {
+	const out = [];
+	for (const report of input.reports) {
+		const body = `${`## ${report.project ?? "Vitest Results"}`}\n\n${`${report.summary.passed}/${report.summary.total} passed, ${report.summary.failed} failed, ${report.summary.skipped} skipped`}\n`;
+		out.push({
+			target: "github-summary",
+			content: body,
+			contentType: "text/markdown"
+		});
+	}
+	return out;
+};
+/**
+* Subscribe a live Ink mount to the kit's run-event channel.
+*
+* Called from the factory when `consoleMode` is `stream`. The factory runs
+* at run start — before the plugin publishes the first `RunStarted`
+* event — so the subscription is registered in time. `Effect.runFork`
+* advances the forked fiber up to its first suspension (the
+* `Queue.take` below); that suspension point is past `PubSub.subscribe`,
+* so the subscription is live before this function returns. The drain
+* loop runs forever: `createLiveInk` handles `RunFinished` (schedules
+* unmount) and a subsequent `RunStarted` (remounts) itself, so the loop
+* stays open across watch-mode reruns and ends only when the process
+* exits.
+*
+* @internal
+*/
+const subscribeLiveInk = (channel) => {
+	const live = createLiveInk();
+	Effect.runFork(Effect.scoped(Effect.gen(function* () {
+		const dequeue = yield* PubSub.subscribe(channel);
+		yield* Effect.forever(Queue.take(dequeue).pipe(Effect.flatMap((event) => Effect.sync(() => live.event(event)))));
+	})));
+};
+/**
+* The default reporter factory.
+*
+* The plugin uses this as its built-in when no user `reporter` option
+* is supplied, and a custom-reporter author reads it as the canonical
+* worked example of the `VitestAgentReporterFactory` contract.
+*
+* The factory is invoked once at run start with the run-start kit. In
+* `consoleMode: "stream"` it subscribes a live Ink mount to the kit's
+* run-event channel and owns that mount's lifecycle end to end.
+*
+* The `render` call (invoked once at run end with the health-aware kit)
+* assembles the reduced state, classifies the shape and outcome, and
+* dispatches to the matching cell. Output is one stdout entry carrying
+* the cell's string. When `kit.config.githubActions` is true a GFM
+* step-summary payload is appended for routing to GITHUB_STEP_SUMMARY.
+* In `stream` mode `render` emits nothing — the live mount painted the run.
+*
+* @public
+*/
+const DefaultVitestAgentReporter = (kit) => {
+	if (kit.config.consoleMode === "stream" && kit.runEvents !== void 0) subscribeLiveInk(kit.runEvents);
+	return { render(input, renderKit) {
+		const out = [];
+		if (shouldRenderForMode(renderKit.config.consoleMode)) {
+			const content = dispatch(buildDispatchInputs(reduceRenderStateAll(input.reports.flatMap((r) => synthesizeFromAgentReport(r))), input, { runCommand: renderKit.config.runCommand ?? null }), resolveCellOptions(renderKit));
+			if (content.length > 0) out.push({
+				target: "stdout",
+				content,
+				contentType: "text/plain"
+			});
+		}
+		if (renderKit.config.githubActions === true) out.push(...renderGithubSummary(input));
+		return out;
+	} };
+};
+
+//#endregion
+export { DefaultVitestAgentReporter, buildDispatchInputs, renderAgentStringForReport, renderHumanStringForReport, resolveCellOptions };