@c9up/helix 0.1.3 → 0.1.5

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/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();