@c9up/helix 0.1.4 → 0.1.6

package/src/cli/watch/loop.ts

@@ -1,159 +0,0 @@
-/**
- * Watch-mode run loop: runs `runOnce` once on startup, installs the
- * watcher, and re-invokes `runOnce` whenever a coalesced change burst
- * fires. Re-runs are serialised — at most one queued follow-up while a
- * run is in flight; further bursts during that window are dropped (the
- * queued run will pick up the latest disk state).
- *
- * On SIGINT (or an aborted external `AbortSignal`), the loop closes
- * the watcher, waits for any in-flight run, and resolves with the
- * LAST `RunOutcome` (with `exitCode: 0`, since a failing run during
- * interactive watch should not poison the exit status — failures
- * already surface as test output).
- */
-
-import type { RunOutcome } from "../run.js";
-import { createWatcher, type WatcherHandle } from "./watcher.js";
-
-export interface RunWatchOptions {
-	root: string;
-	include: string[];
-	exclude: string[];
-	debounceMs: number;
-	/** Optional external abort. When triggered, behaves like SIGINT.
-	 *  Lets tests drive shutdown without `process.emit("SIGINT")` (which
-	 *  collides with vitest's own signal handlers). */
-	signal?: AbortSignal;
-}
-
-const BANNER_WAITING = "[helix] watching for changes… (Ctrl-C to exit)";
-const BANNER_RERUN = "[helix] change detected, re-running…";
-
-function fallbackOutcome(): RunOutcome {
-	return {
-		summary: {
-			totals: { pass: 0, fail: 0, skip: 0, todo: 0, fileErrors: 0 },
-			files: [],
-			fileErrors: [],
-			durationMs: 0,
-		},
-		exitCode: 0,
-	};
-}
-
-export async function runWatch(
-	opts: RunWatchOptions,
-	runOnce: () => Promise<RunOutcome>,
-): Promise<RunOutcome> {
-	// Initialise upfront so the final return never reads `undefined`,
-	// even if `runOnce` throws and the catch path's fallback construction
-	// itself throws (defence-in-depth against a brittle cast).
-	let lastOutcome: RunOutcome = fallbackOutcome();
-	let inFlight: Promise<void> | undefined;
-	let queued = false;
-	let closing = false;
-	let watcher: WatcherHandle | undefined;
-	let resolveSettled: () => void;
-	const settled = new Promise<void>((resolve) => {
-		resolveSettled = resolve;
-	});
-
-	function beginShutdown(): void {
-		if (closing) return;
-		closing = true;
-		void (async () => {
-			if (watcher) await watcher.close();
-			if (inFlight) await inFlight;
-			resolveSettled();
-		})();
-	}
-
-	const onSigint = (): void => beginShutdown();
-	const onAbort = (): void => beginShutdown();
-	process.on("SIGINT", onSigint);
-	if (opts.signal) {
-		if (opts.signal.aborted) {
-			closing = true;
-		} else {
-			opts.signal.addEventListener("abort", onAbort, { once: true });
-		}
-	}
-
-	function trigger(): void {
-		if (closing) return;
-		if (inFlight) {
-			queued = true;
-			return;
-		}
-		process.stdout.write(`${BANNER_RERUN}\n`);
-		inFlight = (async () => {
-			try {
-				lastOutcome = await runOnce();
-			} catch (err) {
-				process.stderr.write(
-					`helix-watch: run failed: ${err instanceof Error ? err.message : String(err)}\n`,
-				);
-			} finally {
-				inFlight = undefined;
-				if (!closing) {
-					process.stdout.write(`${BANNER_WAITING}\n`);
-				}
-				if (queued && !closing) {
-					queued = false;
-					trigger();
-				}
-			}
-		})();
-	}
-
-	// Initial run — drive it through the same in-flight machinery so a
-	// SIGINT/abort arriving during the first run is handled exactly like
-	// one arriving during a re-run (handler awaits `inFlight`, then
-	// resolves).
-	inFlight = (async () => {
-		try {
-			lastOutcome = await runOnce();
-		} catch (err) {
-			process.stderr.write(
-				`helix-watch: run failed: ${err instanceof Error ? err.message : String(err)}\n`,
-			);
-		} finally {
-			inFlight = undefined;
-		}
-	})();
-	await inFlight;
-
-	if (closing) {
-		process.off("SIGINT", onSigint);
-		opts.signal?.removeEventListener("abort", onAbort);
-		return { ...lastOutcome, exitCode: 0 };
-	}
-
-	process.stdout.write(`${BANNER_WAITING}\n`);
-
-	let watcherFatalError: Error | undefined;
-	watcher = createWatcher({
-		root: opts.root,
-		include: opts.include,
-		exclude: opts.exclude,
-		debounceMs: opts.debounceMs,
-		onChange: () => trigger(),
-		onError: (err) => {
-			watcherFatalError = err;
-			beginShutdown();
-		},
-	});
-
-	await settled;
-
-	process.off("SIGINT", onSigint);
-	opts.signal?.removeEventListener("abort", onAbort);
-
-	if (watcherFatalError) {
-		process.stderr.write(
-			`helix-watch: watcher error — ${watcherFatalError.message}\n`,
-		);
-	}
-
-	return { ...lastOutcome, exitCode: 0 };
-}

package/src/cli/watch/types.ts

@@ -1,22 +0,0 @@
-/**
- * Watch-mode public types. Kept in their own file so `bin/helix.js` and
- * `run.ts` can import without pulling in the watcher implementation.
- */
-
-export interface WatchOptions {
-	enabled: boolean;
-	/** Debounce window in ms — events within the window collapse to one
-	 *  re-run. Default 200, range [1, 5_000]. */
-	debounceMs?: number;
-	/** Override the watcher's include globs. Defaults to `coverage.include`
-	 *  when set, otherwise the watch defaults (`src/**`, `tests/**`,
-	 *  `test/**`). */
-	include?: string[];
-	/** Override the watcher's exclude globs. Defaults to `coverage.exclude`
-	 *  when set, otherwise the watch defaults (`node_modules/**`,
-	 *  `.helix-coverage/**`, etc.). */
-	exclude?: string[];
-	/** Optional `AbortSignal` to drive shutdown without a real SIGINT —
-	 *  primarily a test seam. */
-	signal?: AbortSignal;
-}

package/src/cli/watch/watcher.ts

@@ -1,145 +0,0 @@
-/**
- * Recursive file watcher for `helix test --watch`. Wraps Node's
- * `fs.watch(root, { recursive: true })` with a glob filter (reusing the
- * coverage glob translator) and a single-timer debounce that coalesces
- * burst events into one `onChange` call.
- *
- * The shape (`createWatcher` returning a `{ close }` handle) is the
- * abstraction a future Rust `notify`-NAPI implementation slots into
- * without touching the loop.
- */
-
-import { type FSWatcher, watch as fsWatch, realpathSync } from "node:fs";
-import path from "node:path";
-import { compileGlobs, matchesAnyGlob } from "../coverage/glob.js";
-
-export interface CreateWatcherOptions {
-	root: string;
-	include: string[];
-	exclude: string[];
-	debounceMs: number;
-	onChange: (paths: Set<string>) => void;
-	/** Surfaces `FSWatcher` errors (recursive unsupported, EMFILE, etc.)
-	 *  so the loop can stop instead of waiting forever on a dead handle. */
-	onError?: (err: Error) => void;
-}
-
-export interface WatcherHandle {
-	close(): Promise<void>;
-}
-
-const DEBOUNCE_MIN = 1;
-const DEBOUNCE_MAX = 5_000;
-
-function tryRealpath(p: string): string {
-	try {
-		return realpathSync(p);
-	} catch {
-		return p;
-	}
-}
-
-export function createWatcher(opts: CreateWatcherOptions): WatcherHandle {
-	if (
-		opts.debounceMs < DEBOUNCE_MIN ||
-		opts.debounceMs > DEBOUNCE_MAX ||
-		!Number.isFinite(opts.debounceMs)
-	) {
-		throw new Error(
-			`createWatcher: debounceMs must be in [${DEBOUNCE_MIN}, ${DEBOUNCE_MAX}], got ${opts.debounceMs}`,
-		);
-	}
-	if (opts.include.length === 0) {
-		throw new Error(
-			"createWatcher: include must be non-empty (an empty include matches nothing — silent watcher).",
-		);
-	}
-
-	const include = compileGlobs(opts.include);
-	const exclude = compileGlobs(opts.exclude);
-	// Realpath the root so events delivered with the canonical path
-	// (macOS `/tmp` → `/private/tmp`, Docker bind-mounts, pnpm worktree
-	// symlinks) don't get filtered out as "outside root". Mirrors what
-	// `coverage/filter.ts` does for the same reason.
-	const root = tryRealpath(path.resolve(opts.root));
-
-	const pending = new Set<string>();
-	let timer: NodeJS.Timeout | undefined;
-	let closed = false;
-
-	function flush(): void {
-		timer = undefined;
-		if (closed) return;
-		if (pending.size === 0) return;
-		const batch = new Set(pending);
-		pending.clear();
-		opts.onChange(batch);
-	}
-
-	function arm(): void {
-		if (timer) clearTimeout(timer);
-		timer = setTimeout(flush, opts.debounceMs);
-	}
-
-	function shouldNotify(filename: string | null): string | undefined {
-		if (!filename) return undefined;
-		const abs = path.resolve(root, filename);
-		const rel = path.relative(root, abs).split(path.sep).join("/");
-		if (rel.length === 0 || rel.startsWith("..") || path.isAbsolute(rel)) {
-			return undefined;
-		}
-		if (matchesAnyGlob(exclude, rel)) return undefined;
-		if (!matchesAnyGlob(include, rel)) return undefined;
-		return abs;
-	}
-
-	let watcher: FSWatcher;
-	try {
-		watcher = fsWatch(root, { recursive: true }, (_event, filename) => {
-			if (closed) return;
-			const abs = shouldNotify(typeof filename === "string" ? filename : null);
-			if (!abs) return;
-			pending.add(abs);
-			arm();
-		});
-	} catch (err) {
-		throw new Error(
-			`createWatcher: fs.watch failed on ${root}: ${
-				err instanceof Error ? err.message : String(err)
-			}`,
-		);
-	}
-
-	// On `'error'`, surface the failure to the caller and shut down so
-	// the loop doesn't sit on a dead handle. Without this, recursive
-	// watch failures on Linux<20 leave the user staring at a "watching…"
-	// banner that will never tick.
-	watcher.on("error", (err) => {
-		if (closed) return;
-		closed = true;
-		if (timer) {
-			clearTimeout(timer);
-			timer = undefined;
-		}
-		try {
-			watcher.close();
-		} catch {
-			/* already torn down */
-		}
-		opts.onError?.(err instanceof Error ? err : new Error(String(err)));
-	});
-
-	return {
-		async close(): Promise<void> {
-			if (closed) return;
-			closed = true;
-			if (timer) {
-				clearTimeout(timer);
-				timer = undefined;
-			}
-			pending.clear();
-			watcher.close();
-			await new Promise<void>((resolve) => setImmediate(resolve));
-		},
-	};
-}

package/src/container/index.ts

@@ -1,16 +0,0 @@
-/**
- * `@c9up/helix/container` — barrel for the test-container facade.
- */
-
-export type {
-	ContainerLike,
-	ContainerToken,
-} from "../runtime/vi/index.js";
-export {
-	clearActiveContainer,
-	type HelixContainer,
-	override,
-	overrideOn,
-	useContainer,
-} from "./override.js";
-export { spy } from "./spy.js";

package/src/container/override.ts

@@ -1,86 +0,0 @@
-/**
- * Helix facade over `@c9up/ream`'s `Container.override(token, value)`.
- *
- * Adds two things to the raw container call:
- *   1. The override is registered against the active test context's
- *      auto-restore queue, so it's undone after the test even if the
- *      test body never calls `restore()` itself.
- *   2. A clear error when called outside a test (no AsyncLocalStorage
- *      frame) — the queued cleanup would never fire there.
- *
- * The active container is passed via `useContainer(container)` (called
- * by the host app's test bootstrap). For bare unit tests with no host
- * app, callers can pass the container explicitly to `overrideOn`.
- */
-
-import { inTestContext, registerTestCleanup } from "../runtime/test-context.js";
-import type { ContainerLike, ContainerToken } from "../runtime/vi/index.js";
-
-/** Container surface helix needs: a value-based override + a restore. */
-export interface HelixContainer extends ContainerLike {
-	override(token: ContainerToken, value: unknown): void;
-}
-
-let activeContainer: HelixContainer | undefined;
-
-/**
- * Bind a container instance as active for `helix.override(...)` calls.
- *
- * If called inside a test frame, the previous active container is
- * captured and restored when the frame ends — so swapping the active
- * container mid-test does not leak into the next test. Outside a test
- * frame the assignment is permanent until the next `useContainer` /
- * `clearActiveContainer` call.
- */
-export function useContainer(container: HelixContainer): void {
-	const previous = activeContainer;
-	activeContainer = container;
-	registerTestCleanup(() => {
-		activeContainer = previous;
-	});
-}
-
-/** Reset the active container binding. Typically not needed in user
- *  code — `useContainer` already auto-restores when called inside a
- *  test. Exposed so `afterEach` blocks (and unit tests) can clear the
- *  module-scoped slot explicitly. */
-export function clearActiveContainer(): void {
-	activeContainer = undefined;
-}
-
-/**
- * Override a binding on the active container with a value, and queue
- * the restore for end-of-test. Use `overrideOn` when you need to
- * target a specific container instance.
- *
- * Throws if called outside a test frame: a queued cleanup would never
- * fire there, so the override would leak across tests silently.
- */
-export function override(token: ContainerToken, value: unknown): void {
-	if (!inTestContext()) {
-		throw new Error(
-			"helix.override: must be called inside a test (no active test frame). Calls from top-level setup leak across tests — use container.override() directly with manual restore() if that is what you want.",
-		);
-	}
-	if (!activeContainer) {
-		throw new Error(
-			"helix.override: no active container. Call helix.useContainer(container) before invoking override(), or use overrideOn(container, token, value).",
-		);
-	}
-	overrideOn(activeContainer, token, value);
-}
-
-/** Override on a specific container instance. */
-export function overrideOn(
-	container: HelixContainer,
-	token: ContainerToken,
-	value: unknown,
-): void {
-	container.override(token, value);
-	// `registerTestCleanup` returns false when called outside a test
-	// frame (e.g. raw vitest tests, REPL, top-level setup). In that
-	// case the caller is responsible for `container.restore(token)` —
-	// we don't queue a fallback that might fire in an unexpected
-	// frame.
-	registerTestCleanup(() => container.restore(token));
-}

package/src/container/spy.ts

@@ -1,25 +0,0 @@
-/**
- * `helix.spy()` — Jest-like spy factory.
- *
- * Thin alias over `vi.fn()` so the documented one-liner from FR69 /
- * Story 42.3 reads:
- *
- *   const fakeMail = { send: spy() };
- *   override('mail', fakeMail);
- *   // ...
- *   expect(fakeMail.send).toHaveBeenCalledOnce();
- */
-
-import { vi } from "../runtime/vi/index.js";
-import type { AnyFn, Spy } from "../runtime/vi/spy.js";
-
-/**
- * Wrap (don't bind) `vi.fn` so `spy` always reaches through to the
- * current `vi.fn` even if it gets replaced at runtime — and so the
- * captured reference can never go stale relative to the live `vi`
- * object. The cost over `export const spy = vi.fn` is one extra
- * function call per spawn.
- */
-export function spy<Fn extends AnyFn>(implementation?: Fn): Spy<Fn> {
-	return vi.fn(implementation);
-}

package/src/index.ts

@@ -1,42 +0,0 @@
-/**
- * `@c9up/helix` — the framework-agnostic test runtime for the Ream ecosystem.
- *
- * This barrel exposes the Vitest-compatible runtime (describe/test/expect/vi/
- * spies/lifecycle), the container facade, and time-travel — none of which import
- * an ecosystem package. It is fully agnostic: usable in any project.
- *
- * Per-package test fakes/helpers live in EACH package's own `/testing` subpath
- * (a package owns its test surface, not helix): `@c9up/ream/testing`
- * (TestClient, FakeBus, assertEmitted), `@c9up/atlas/testing` (factory,
- * useTransaction), `@c9up/rover/testing` (FakeMail), `@c9up/bay/testing`
- * (FakeQueue), `@c9up/spectrum/testing` (FakeLogger), `@c9up/nova/testing`
- * (FakeNova), `@c9up/relay/testing` (FakeRelay), `@c9up/archive/testing`
- * (FakeStorage). Install a package → you get its testing surface.
- */
-
-export * from "./container/index.js";
-export type {
-	Assertion,
-	FileResult,
-	Hook,
-	HookType,
-	MatcherName,
-	MatcherResult,
-	Spy,
-	SuiteResult,
-	TestResult,
-	Vi,
-} from "./runtime/index.js";
-export {
-	AssertionError,
-	afterAll,
-	afterEach,
-	beforeAll,
-	beforeEach,
-	describe,
-	expect,
-	it,
-	test,
-	vi,
-} from "./runtime/index.js";
-export * as time from "./time/index.js";

package/src/runtime/assertion-error.ts

@@ -1,38 +0,0 @@
-/**
- * Assertion error thrown by `expect` — carries structured fields so runners
- * (Vitest-compatible reporters, IDE integrations) can render diffs.
- */
-export interface AssertionErrorInit {
-	message: string;
-	actual?: unknown;
-	expected?: unknown;
-	operator?: string;
-	showDiff?: boolean;
-}
-
-export class AssertionError extends Error {
-	readonly actual: unknown;
-	readonly expected: unknown;
-	readonly operator: string | undefined;
-	readonly showDiff: boolean;
-
-	constructor(init: AssertionErrorInit) {
-		super(init.message);
-		this.name = "AssertionError";
-		this.actual = init.actual;
-		this.expected = init.expected;
-		this.operator = init.operator;
-		this.showDiff = init.showDiff ?? true;
-		// V8 only: strip framework frames so the stack points at user code.
-		const capture = (
-			Error as { captureStackTrace?: (target: object, ctor: object) => void }
-		).captureStackTrace;
-		if (typeof capture === "function") {
-			capture(this, AssertionError);
-		}
-	}
-}
-
-export function isAssertionError(value: unknown): value is AssertionError {
-	return value instanceof AssertionError;
-}

package/src/runtime/cli-worker.ts

@@ -1,140 +0,0 @@
-/**
- * CLI worker entry — what the orchestrator spawns as a child process.
- *
- * Protocol:
- *   1. Parent writes one `{ "type":"run", "file":"...", "timeoutMs":n, "nonce":"..." }`
- *      line to stdin, then closes stdin.
- *   2. We run the file via `runTestFile`.
- *   3. We emit a single framed line on **stderr** prefixed with
- *      `__HELIX_RESULT__`, with the parent's `nonce` echoed back so a
- *      test that happens to print that prefix can't spoof the result.
- *   4. Exit with code 0 on `result`, 1 on `error`.
- *
- * Pre-handshake errors (e.g. malformed instruction on stdin) are emitted
- * with the `__helix_pre_handshake__` magic nonce — the parent accepts
- * those only for `type === "error"` so a fixture can't use the magic to
- * fake success.
- *
- * Flush discipline: on the happy path we await the stream drain callback
- * before setting `process.exitCode` so the frame always reaches the
- * parent. For the fatal `unhandledRejection` path we use `fs.writeSync`
- * on fd 2 to guarantee the bytes hit the pipe before Node tears the
- * process down.
- */
-
-import { writeSync } from "node:fs";
-import { createInterface } from "node:readline";
-import { runTestFile } from "./worker.js";
-
-const FRAME_PREFIX = "__HELIX_RESULT__";
-const PRE_HANDSHAKE_NONCE = "__helix_pre_handshake__";
-
-interface RunMessage {
-	type: "run";
-	file: string;
-	timeoutMs?: number;
-	nonce: string;
-}
-
-async function emit(msg: unknown): Promise<void> {
-	const line = `${FRAME_PREFIX}${JSON.stringify(msg)}\n`;
-	await new Promise<void>((resolve, reject) => {
-		process.stderr.write(line, (err) => {
-			if (err) reject(err);
-			else resolve();
-		});
-	});
-}
-
-/**
- * Synchronous emit used from fatal handlers (unhandledRejection) where
- * we can't afford to lose the frame to the process tear-down racing the
- * pipe drain. `writeSync` blocks until the kernel accepts the bytes.
- */
-function emitSync(msg: unknown): void {
-	try {
-		writeSync(2, `${FRAME_PREFIX}${JSON.stringify(msg)}\n`);
-	} catch {
-		/* pipe broken — nothing we can do */
-	}
-}
-
-async function readInstruction(): Promise<RunMessage> {
-	const rl = createInterface({ input: process.stdin });
-	for await (const line of rl) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		// Parse inside try so a bad JSON line propagates as a typed error
-		// rather than leaking a SyntaxError that escapes `for await`.
-		let parsed: unknown;
-		try {
-			parsed = JSON.parse(trimmed);
-		} catch (err) {
-			throw new Error(
-				`malformed instruction JSON: ${err instanceof Error ? err.message : String(err)}`,
-			);
-		}
-		if (
-			parsed &&
-			typeof parsed === "object" &&
-			(parsed as { type?: unknown }).type === "run" &&
-			typeof (parsed as { file?: unknown }).file === "string" &&
-			typeof (parsed as { nonce?: unknown }).nonce === "string"
-		) {
-			return parsed as RunMessage;
-		}
-		throw new Error(`invalid instruction shape: ${trimmed}`);
-	}
-	throw new Error("stdin closed before instruction arrived");
-}
-
-async function main(): Promise<void> {
-	let instr: RunMessage;
-	try {
-		instr = await readInstruction();
-	} catch (err) {
-		// We don't know the real nonce yet — emit with the pre-handshake
-		// magic so the parent accepts this specific error path.
-		await emit({
-			type: "error",
-			file: undefined,
-			message: err instanceof Error ? err.message : String(err),
-			stack: err instanceof Error ? err.stack : undefined,
-			nonce: PRE_HANDSHAKE_NONCE,
-		}).catch(() => {});
-		process.exitCode = 1;
-		return;
-	}
-
-	// Installed AFTER the instruction is read so we can echo the right nonce.
-	// Synchronous write so Node's default "crash on unhandledRejection"
-	// behaviour can't evict the frame before the parent reads it.
-	process.on("unhandledRejection", (reason) => {
-		emitSync({
-			type: "error",
-			file: instr.file,
-			message: `unhandledRejection: ${reason instanceof Error ? reason.message : String(reason)}`,
-			stack: reason instanceof Error ? reason.stack : undefined,
-			nonce: instr.nonce,
-		});
-	});
-
-	try {
-		const result = await runTestFile(instr.file, {
-			timeoutMs: instr.timeoutMs,
-		});
-		await emit({ type: "result", result, nonce: instr.nonce });
-		process.exitCode = result.totals.fail > 0 ? 1 : 0;
-	} catch (err) {
-		await emit({
-			type: "error",
-			file: instr.file,
-			message: err instanceof Error ? err.message : String(err),
-			stack: err instanceof Error ? err.stack : undefined,
-			nonce: instr.nonce,
-		}).catch(() => {});
-		process.exitCode = 1;
-	}
-}
-
-void main();