@hautajoki/hexagon 0.1.0

package/src/protocol.ts

@@ -0,0 +1,189 @@
+export const REPORT_SCHEMA_VERSION = 1 as const;
+
+export interface FailureReport {
+	readonly kind: 'test' | 'bench';
+	readonly labels: string[];
+	readonly message: string;
+	readonly source: string;
+	readonly line: number;
+	readonly trace: string;
+}
+
+export interface TestReport {
+	readonly labels: string[];
+	readonly duration_seconds: number;
+}
+
+export interface SkippedReport {
+	readonly kind: 'test' | 'bench';
+	readonly labels: string[];
+	readonly reason: string;
+}
+
+export interface BenchReport {
+	readonly labels: string[];
+	readonly iterations: number;
+	readonly samples: number;
+	readonly calibration_iterations: number;
+	readonly total_seconds: number;
+	readonly mean_seconds: number;
+	readonly median_seconds: number;
+	readonly p95_seconds: number;
+	readonly min_seconds: number;
+	readonly max_seconds: number;
+	readonly margin_percent: number;
+}
+
+export interface RunReport {
+	readonly schema_version: 1;
+	readonly ok: boolean;
+	readonly mode: string;
+	readonly filter?: string;
+	readonly focused: boolean;
+	readonly duration_seconds: number;
+	readonly discovered: number;
+	readonly selected: number;
+	readonly test_total: number;
+	readonly test_pass: number;
+	readonly test_fail: number;
+	readonly test_skip: number;
+	readonly bench_total: number;
+	readonly bench_pass: number;
+	readonly bench_fail: number;
+	readonly bench_skip: number;
+	readonly failures: FailureReport[];
+	readonly skipped: SkippedReport[];
+	readonly tests: TestReport[];
+	readonly benchmarks: BenchReport[];
+}
+
+export interface TesseraRunResult {
+	readonly environment: string;
+	readonly place: string;
+	readonly placeId: number;
+	readonly version?: number;
+	readonly taskPath: string;
+	readonly state: string;
+	readonly results?: unknown[];
+	readonly logs?: string[];
+}
+
+function object(value: unknown, label: string): Record<string, unknown> {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+		throw new TypeError(`${label} must be an object`);
+	}
+	return value as Record<string, unknown>;
+}
+
+function number(value: unknown, label: string): number {
+	if (typeof value !== 'number' || !Number.isFinite(value)) {
+		throw new TypeError(`${label} must be a finite number`);
+	}
+	return value;
+}
+
+function array(value: unknown, label: string): unknown[] {
+	if (!Array.isArray(value)) throw new TypeError(`${label} must be an array`);
+	return value;
+}
+
+export function parseRunReport(payload: string): RunReport {
+	const value = object(JSON.parse(payload), 'Hexagon report');
+	if (value.schema_version !== REPORT_SCHEMA_VERSION) {
+		throw new TypeError(`unsupported Hexagon report schema ${String(value.schema_version)}`);
+	}
+	if (typeof value.ok !== 'boolean' || typeof value.focused !== 'boolean') {
+		throw new TypeError('Hexagon report status fields are invalid');
+	}
+	for (const key of [
+		'duration_seconds',
+		'discovered',
+		'selected',
+		'test_total',
+		'test_pass',
+		'test_fail',
+		'test_skip',
+		'bench_total',
+		'bench_pass',
+		'bench_fail',
+		'bench_skip',
+	] as const) {
+		number(value[key], `Hexagon report ${key}`);
+	}
+	for (const key of ['failures', 'skipped', 'tests', 'benchmarks'] as const) {
+		array(value[key], `Hexagon report ${key}`);
+	}
+	return value as unknown as RunReport;
+}
+
+export function parseTesseraRun(payload: string): TesseraRunResult {
+	const value = object(JSON.parse(payload), 'Tessera run result');
+	if (
+		typeof value.environment !== 'string' ||
+		typeof value.place !== 'string' ||
+		typeof value.taskPath !== 'string' ||
+		typeof value.state !== 'string'
+	) {
+		throw new TypeError('Tessera run result metadata is invalid');
+	}
+	number(value.placeId, 'Tessera run result placeId');
+	if (value.version !== undefined) number(value.version, 'Tessera run result version');
+	if (value.results !== undefined) array(value.results, 'Tessera run result results');
+	if (value.logs !== undefined) array(value.logs, 'Tessera run result logs');
+	return value as unknown as TesseraRunResult;
+}
+
+export function returnedString(result: TesseraRunResult, label: string): string {
+	const values = result.results ?? [];
+	if (values.length !== 1 || typeof values[0] !== 'string') {
+		throw new TypeError(`${label} must return exactly one JSON string`);
+	}
+	return values[0];
+}
+
+export function aggregateReports(mode: 'test' | 'bench', filter: string | undefined, reports: readonly RunReport[]): RunReport {
+	const aggregate: {
+		-readonly [Key in keyof RunReport]: RunReport[Key];
+	} = {
+		schema_version: REPORT_SCHEMA_VERSION,
+		ok: true,
+		mode,
+		...(filter === undefined ? {} : { filter }),
+		focused: false,
+		duration_seconds: 0,
+		discovered: 0,
+		selected: 0,
+		test_total: 0,
+		test_pass: 0,
+		test_fail: 0,
+		test_skip: 0,
+		bench_total: 0,
+		bench_pass: 0,
+		bench_fail: 0,
+		bench_skip: 0,
+		failures: [],
+		skipped: [],
+		tests: [],
+		benchmarks: [],
+	};
+	for (const report of reports) {
+		aggregate.ok &&= report.ok;
+		aggregate.focused ||= report.focused;
+		aggregate.duration_seconds += report.duration_seconds;
+		aggregate.discovered += report.discovered;
+		aggregate.selected += report.selected;
+		aggregate.test_total += report.test_total;
+		aggregate.test_pass += report.test_pass;
+		aggregate.test_fail += report.test_fail;
+		aggregate.test_skip += report.test_skip;
+		aggregate.bench_total += report.bench_total;
+		aggregate.bench_pass += report.bench_pass;
+		aggregate.bench_fail += report.bench_fail;
+		aggregate.bench_skip += report.bench_skip;
+		aggregate.failures.push(...report.failures);
+		aggregate.skipped.push(...report.skipped);
+		aggregate.tests.push(...report.tests);
+		aggregate.benchmarks.push(...report.benchmarks);
+	}
+	return aggregate;
+}

package/src/reporter.ts

@@ -0,0 +1,105 @@
+import type { BenchReport, FailureReport, RunReport, SkippedReport, TestReport } from './protocol.ts';
+
+export interface ReporterOptions {
+	readonly color: boolean;
+	readonly write?: (text: string) => void;
+}
+
+function painter(enabled: boolean) {
+	return (code: string, text: string): string => (enabled ? `\u001b[${code}m${text}\u001b[0m` : text);
+}
+
+function labelPath(labels: readonly string[], dim: (text: string) => string) {
+	return labels.join(dim(' › '));
+}
+
+function duration(seconds: number): string {
+	if (seconds >= 1) return `${seconds.toFixed(2).padStart(7)} s `;
+	if (seconds >= 1e-3) return `${(seconds * 1e3).toFixed(2).padStart(7)} ms`;
+	if (seconds >= 1e-6) return `${(seconds * 1e6).toFixed(2).padStart(7)} µs`;
+	return `${(seconds * 1e9).toFixed(2).padStart(7)} ns`;
+}
+
+function reportFailures(lines: string[], failures: readonly FailureReport[], paint: ReturnType<typeof painter>) {
+	if (failures.length === 0) return;
+	lines.push('', paint('1;31', `Failures (${failures.length})`));
+	for (const failure of failures) {
+		lines.push(
+			`  ${paint('31', '✗')} ${labelPath(failure.labels, (value) => paint('2', value))} ${paint('2', `[${failure.kind}]`)}`,
+			`      ${failure.message}`,
+			paint('2', `      ${failure.source}:${failure.line}`),
+		);
+		if (failure.trace !== '') lines.push(paint('2', failure.trace));
+	}
+}
+
+function reportSkipped(lines: string[], skipped: readonly SkippedReport[], paint: ReturnType<typeof painter>) {
+	if (skipped.length === 0) return;
+	lines.push('', paint('1;33', `Skipped (${skipped.length})`));
+	for (const item of skipped) {
+		lines.push(`  ${paint('33', '○')} ${labelPath(item.labels, (value) => paint('2', value))} ${paint('2', `— ${item.reason}`)}`);
+	}
+}
+
+function reportSlowest(lines: string[], tests: readonly TestReport[], paint: ReturnType<typeof painter>) {
+	const slowest = [...tests].sort((left, right) => right.duration_seconds - left.duration_seconds).slice(0, 5);
+	if (slowest.length === 0 || slowest[0]!.duration_seconds < 0.01) return;
+	lines.push('', paint('1', `Slowest tests (${slowest.length})`));
+	for (const test of slowest) {
+		lines.push(`  ${paint('33', duration(test.duration_seconds))}  ${labelPath(test.labels, (value) => paint('2', value))}`);
+	}
+}
+
+function reportBenchmarks(lines: string[], benchmarks: readonly BenchReport[], paint: ReturnType<typeof painter>) {
+	if (benchmarks.length === 0) return;
+	lines.push('', paint('1;36', `Benchmarks (${benchmarks.length})`));
+	for (const benchmark of [...benchmarks].sort((left, right) => left.labels.join('\0').localeCompare(right.labels.join('\0')))) {
+		const rate = benchmark.mean_seconds > 0 ? `${(1 / benchmark.mean_seconds).toFixed(2)} ops/s` : '—';
+		lines.push(
+			`  ${labelPath(benchmark.labels, (value) => paint('2', value))}`,
+			`      ${paint('36', duration(benchmark.mean_seconds))} mean · ${duration(benchmark.p95_seconds)} p95 · ${rate} · ±${benchmark.margin_percent.toFixed(1)}% · ${benchmark.iterations}×${benchmark.samples}`,
+		);
+	}
+}
+
+function tally(label: string, pass: number, fail: number, skip: number, total: number, paint: ReturnType<typeof painter>): string {
+	const parts: string[] = [];
+	if (fail > 0) parts.push(paint('1;31', `${fail} failed`));
+	if (pass > 0) parts.push(paint('32', `${pass} passed`));
+	if (skip > 0) parts.push(paint('33', `${skip} skipped`));
+	parts.push(paint('2', `${total} total`));
+	return `${label}: ${parts.join(paint('2', ' · '))}`;
+}
+
+export function formatReport(report: RunReport, options: ReporterOptions): string {
+	const paint = painter(options.color);
+	const lines: string[] = [];
+	reportFailures(lines, report.failures, paint);
+	reportSkipped(lines, report.skipped, paint);
+	reportSlowest(lines, report.tests, paint);
+	reportBenchmarks(lines, report.benchmarks, paint);
+	lines.push('');
+	if (report.selected === 0) {
+		lines.push(paint('33', `no cases matched${report.filter ? ` “${report.filter}”` : ''} (${report.discovered} discovered)`));
+		return `${lines.join('\n')}\n`;
+	}
+	const totals: string[] = [];
+	if (report.test_total > 0) {
+		totals.push(tally('tests', report.test_pass, report.test_fail, report.test_skip, report.test_total, paint));
+	}
+	if (report.bench_total > 0) {
+		totals.push(tally('benches', report.bench_pass, report.bench_fail, report.bench_skip, report.bench_total, paint));
+	}
+	lines.push(
+		`${report.ok ? paint('32', '✓') : paint('31', '✗')} ${totals.join(paint('2', '  |  '))}`,
+		paint(
+			report.focused ? '33' : '2',
+			`  ${report.selected}/${report.discovered} selected${report.focused ? ' · focused run' : ''} · ${duration(report.duration_seconds)}`,
+		),
+	);
+	return `${lines.join('\n')}\n`;
+}
+
+export function printReport(report: RunReport, options: ReporterOptions): void {
+	(options.write ?? process.stdout.write.bind(process.stdout))(formatReport(report, options));
+}

package/types.d.ts

@@ -0,0 +1,51 @@
+/** Options shared by tests and benchmarks. */
+export interface TestOptions {
+	only?: boolean;
+	skip?: boolean | string;
+}
+
+export interface BenchOptions extends TestOptions {
+	/** Total measured invocations, distributed across samples. Omit for calibration. */
+	iterations?: number;
+	/** Independent timing samples. Defaults to 12. */
+	samples?: number;
+	/** Reset or prepare state immediately before each calibration or timing sample. */
+	beforeSample?: () => void;
+	/** Clean up after every attempted sample, including failed setup or timing. */
+	afterSample?: () => void;
+}
+
+export interface Expectation {
+	readonly never: Expectation;
+	readonly toBe: (expected: unknown) => Expectation;
+	readonly toEqual: (expected: unknown) => Expectation;
+	readonly toBeNear: (expected: number, tolerance?: number) => Expectation;
+	readonly toBeTruthy: () => Expectation;
+	readonly toExist: () => Expectation;
+	readonly toHaveType: (expected: string) => Expectation;
+	readonly toHaveKey: (expected: unknown) => Expectation;
+	readonly toContain: (expected: unknown) => Expectation;
+	readonly toMatch: (pattern: string) => Expectation;
+	readonly toThrow: (pattern?: string) => Expectation;
+}
+
+export interface SuiteContext {
+	readonly describe: (label: string, body: () => void) => void;
+	readonly test: (label: string, run: () => void, options?: TestOptions) => void;
+	readonly testEach: <T>(
+		values: readonly T[],
+		label: string | ((value: T, index: number) => string),
+		run: (value: T, index: number) => void,
+	) => void;
+	readonly bench: (label: string, run: () => void, options?: BenchOptions) => void;
+	readonly todo: (label: string, reason?: string) => void;
+	readonly beforeEach: (hook: () => void) => void;
+	readonly afterEach: (hook: () => void) => void;
+	/** Register case-scoped cleanup. Every cleanup runs once in LIFO order, even after failures. */
+	readonly cleanup: (hook: () => void) => void;
+	readonly expect: (value: unknown) => Expectation;
+	readonly skip: (reason?: string) => never;
+	readonly fail: (message?: string) => never;
+}
+
+export type Suite = (hexagon: SuiteContext) => void;