@c9up/helix 0.1.4 → 0.1.6

package/src/runtime/worker.ts

@@ -1,239 +0,0 @@
-/**
- * Worker entry — loads a single test file, collects its `describe`/`test`
- * declarations, executes them, and emits a `FileResult`.
- *
- * Usage modes:
- *   1. Direct (unit tests): `runTestFile("/abs/path.test.ts")` → `FileResult`
- *   2. Child process (orchestrator): `main()` reads file paths from IPC
- *      messages and replies on `process.send`. Exactly one `main()` runs
- *      per worker process (guarded); IPC runs are serialized so concurrent
- *      messages cannot race on internal state.
- *
- * File collection is scoped per invocation via AsyncLocalStorage (see
- * `suite.ts#withCollection`) — no shared mutable state across concurrent
- * `runTestFile` calls.
- */
-
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { type ExecuteOptions, executeRoot, type FileResult } from "./run.js";
-import { withCollection } from "./suite.js";
-import { withViContext } from "./vi/index.js";
-
-export interface RunFileOptions extends ExecuteOptions {
-	/**
-	 * Bust the ESM module cache so repeated runs of the same path re-execute
-	 * the file body and re-collect tests. Default: true.
-	 */
-	freshImport?: boolean;
-}
-
-function assertAbsolute(p: string): void {
-	if (!path.isAbsolute(p)) {
-		throw new Error(
-			`runTestFile: expected absolute path, got "${p}". Resolve against cwd or __dirname before calling.`,
-		);
-	}
-}
-
-/** Turn values that `JSON.stringify` rejects into readable fallbacks. */
-function safeValue(v: unknown, seen = new WeakSet<object>()): unknown {
-	if (v === null || v === undefined) return v;
-	if (typeof v === "bigint") return `${v}n`;
-	if (typeof v === "function") return `[Function ${v.name || "anonymous"}]`;
-	if (typeof v === "symbol") return v.toString();
-	if (typeof v !== "object") return v;
-	if (seen.has(v)) return "[Circular]";
-	seen.add(v);
-	if (Array.isArray(v)) return v.map((item) => safeValue(item, seen));
-	if (v instanceof Map) {
-		const out: Array<[unknown, unknown]> = [];
-		for (const [k, val] of v)
-			out.push([safeValue(k, seen), safeValue(val, seen)]);
-		return { __type: "Map", entries: out };
-	}
-	if (v instanceof Set) {
-		return { __type: "Set", values: [...v].map((x) => safeValue(x, seen)) };
-	}
-	if (v instanceof Date) return { __type: "Date", iso: v.toISOString() };
-	if (v instanceof RegExp)
-		return { __type: "RegExp", src: v.source, flags: v.flags };
-	if (v instanceof Error) {
-		return {
-			__type: "Error",
-			name: v.name,
-			message: v.message,
-			stack: v.stack,
-		};
-	}
-	const rec: Record<string, unknown> = {};
-	for (const key of Object.keys(v)) {
-		rec[key] = safeValue(Reflect.get(v, key), seen);
-	}
-	return rec;
-}
-
-function sanitizeTest(
-	t: FileResult["tests"][number],
-): FileResult["tests"][number] {
-	if (!t.error) return t;
-	return {
-		...t,
-		error: {
-			...t.error,
-			actual: safeValue(t.error.actual),
-			expected: safeValue(t.error.expected),
-		},
-	};
-}
-
-function sanitizeSuite(
-	s: FileResult["suites"][number],
-): FileResult["suites"][number] {
-	return {
-		...s,
-		hookErrors: s.hookErrors.map((e) => ({
-			...e,
-			actual: safeValue(e.actual),
-			expected: safeValue(e.expected),
-		})),
-		children: s.children.map((c) =>
-			"children" in c ? sanitizeSuite(c) : sanitizeTest(c),
-		),
-	};
-}
-
-function sanitize(result: FileResult): FileResult {
-	return {
-		...result,
-		tests: result.tests.map(sanitizeTest),
-		suites: result.suites.map(sanitizeSuite),
-	};
-}
-
-let importCounter = 0;
-
-export async function runTestFile(
-	absolutePath: string,
-	options: RunFileOptions = {},
-): Promise<FileResult> {
-	assertAbsolute(absolutePath);
-	const baseUrl = pathToFileURL(absolutePath).href;
-	// Cache-busting query param so the ESM loader re-evaluates the module on
-	// every call — otherwise `describe`/`test` would only register on the
-	// first call and subsequent runs would see an empty suite tree.
-	const url =
-		options.freshImport === false
-			? baseUrl
-			: `${baseUrl}?helix=${Date.now()}-${++importCounter}`;
-	return withViContext(async () => {
-		const root = await withCollection(async () => {
-			await import(url);
-		});
-		const raw = await executeRoot(root, absolutePath, {
-			timeoutMs: options.timeoutMs,
-		});
-		return sanitize(raw);
-	});
-}
-
-interface WorkerIncoming {
-	type: "run";
-	file: string;
-	timeoutMs?: number;
-}
-
-interface WorkerOutgoing {
-	type: "result";
-	result: FileResult;
-}
-
-interface WorkerError {
-	type: "error";
-	file: string | undefined;
-	message: string;
-	stack?: string;
-}
-
-type WorkerMessage = WorkerOutgoing | WorkerError;
-
-const FRAME_PREFIX = "__HELIX_RESULT__";
-
-function send(msg: WorkerMessage): void {
-	if (typeof process.send === "function") {
-		process.send(msg);
-		return;
-	}
-	// Fallback: framed line on stderr so it doesn't collide with test
-	// console.log output on stdout. Parent parses lines starting with the
-	// `FRAME_PREFIX` magic.
-	process.stderr.write(`${FRAME_PREFIX}${JSON.stringify(msg)}\n`);
-}
-
-function isWorkerIncoming(v: unknown): v is WorkerIncoming {
-	if (!v || typeof v !== "object") return false;
-	const r = v as { type?: unknown; file?: unknown };
-	return r.type === "run" && typeof r.file === "string";
-}
-
-let mainStarted = false;
-
-export async function main(): Promise<void> {
-	if (mainStarted) return;
-	mainStarted = true;
-
-	// Unhandled rejections from test code (e.g. a dangling Promise.reject)
-	// would crash the worker on Node 15+ or leak silently. Log them and keep
-	// the process alive so currently-running tests can complete.
-	process.on("unhandledRejection", (reason) => {
-		process.stderr.write(
-			`${FRAME_PREFIX}${JSON.stringify({
-				type: "error",
-				file: undefined,
-				message: `unhandledRejection: ${reason instanceof Error ? reason.message : String(reason)}`,
-				stack: reason instanceof Error ? reason.stack : undefined,
-			})}\n`,
-		);
-	});
-
-	// IPC mode: parent drives us via `{ type: "run", file }` messages.
-	if (typeof process.send === "function") {
-		let pending: Promise<unknown> = Promise.resolve();
-		process.on("message", (raw: unknown) => {
-			if (!isWorkerIncoming(raw)) return;
-			const msg = raw;
-			// Serialize IPC runs: a second message waits for the first to
-			// finish so module-scoped watchers / handlers don't race.
-			pending = pending
-				.then(() => runTestFile(msg.file, { timeoutMs: msg.timeoutMs }))
-				.then((result) => send({ type: "result", result }))
-				.catch((err: unknown) => {
-					const e = err instanceof Error ? err : new Error(String(err));
-					send({
-						type: "error",
-						file: msg.file,
-						message: e.message,
-						stack: e.stack,
-					});
-				});
-		});
-		return;
-	}
-
-	// CLI fallback: `node worker.js <file>`.
-	const file = process.argv[2];
-	if (!file) {
-		process.stderr.write("helix worker: missing file arg\n");
-		process.exit(2);
-	}
-	try {
-		const abs = path.resolve(file);
-		const result = await runTestFile(abs);
-		send({ type: "result", result });
-		process.exit(result.totals.fail > 0 ? 1 : 0);
-	} catch (err) {
-		const e = err instanceof Error ? err : new Error(String(err));
-		send({ type: "error", file, message: e.message, stack: e.stack });
-		process.exit(2);
-	}
-}

package/src/time/freeze.ts

@@ -1,229 +0,0 @@
-/**
- * Time freeze / travel — ergonomic surface over `vi.setSystemTime`
- * with per-test auto-restore.
- *
- * **Helix is agnostic — no cross-package imports.** This module
- * never imports `@c9up/chronos`. The clock pin happens entirely
- * through `vi.setSystemTime` (which shims `globalThis.Date`); any
- * code in user-land that calls `new Date()` — chronos `DateTime`
- * included — picks up the frozen epoch automatically.
- *
- * Calendar arithmetic for `month` / `year` uses `Date.UTC` math
- * locally so we don't take a runtime dependency on chronos.
- *
- * **Concurrency note.** `vi.setSystemTime` writes to the `vi`
- * context that wraps the current test FILE (`withViContext`), not
- * the per-test frame (`withTestContext`). Two `withTestContext`
- * frames running in parallel inside the same file (e.g. via
- * `Promise.all([withTestContext(A), withTestContext(B)])`) share
- * one Date shim — A's freeze leaks into B. The helix runtime
- * executes tests strictly sequentially (`runSuite`'s for-await
- * loop), so this is not reachable through the documented test
- * path. Callers who manually compose `withTestContext` in parallel
- * inside a single file must serialise their freezes themselves.
- */
-
-import { inTestContext, registerTestCleanup } from "../runtime/test-context.js";
-import { vi } from "../runtime/vi/index.js";
-
-/** Anything with a `toMillis()` method (e.g. chronos `DateTime`,
- *  Luxon `DateTime`) is accepted via duck typing — no import. */
-interface MillisLike {
-	toMillis(): number;
-}
-
-/** Inputs accepted by `freeze` / `travelTo`. */
-export type TimeInput = string | number | Date | MillisLike;
-
-/** Calendar units supported by `time.travel`. `ms` is the bare-metal
- *  fallback; `month` and `year` use `Date.UTC` math; the rest are pure
- *  ms multipliers. UTC-only — tests should freeze to a UTC instant. */
-export type TimeUnit =
-	| "ms"
-	| "second"
-	| "minute"
-	| "hour"
-	| "day"
-	| "week"
-	| "month"
-	| "year";
-
-/** JS `Date` represents instants from `-8.64e15` to `+8.64e15` ms.
- *  Anything beyond becomes "Invalid Date" — refuse early so callers
- *  see a clear error instead of `setSystemTime(NaN)` downstream. */
-const JS_DATE_MAX = 8_640_000_000_000_000;
-
-/**
- * Pin `Date.now()` / `new Date()` (and anything that reads through
- * them — e.g. `DateTime.now()`) to the given moment. Auto-restored
- * at end-of-test via the helix test frame, so a forgotten
- * `unfreeze()` does not leak into the next test.
- *
- * Throws when called outside a test frame — a queued cleanup would
- * never fire there, so the freeze would leak across tests silently.
- */
-export function freeze(input: TimeInput): void {
-	requireTestContext("freeze");
-	const ms = inputToMs(input);
-	vi.setSystemTime(ms);
-	registerTestCleanup(() => {
-		vi.useRealSystemTime();
-	});
-}
-
-/**
- * Advance the clock by `amount` × `unit`. If the clock isn't frozen
- * yet, freezes it relative to the real `Date.now()` first, then
- * applies the delta — so a one-shot `time.travel(7, 'day')` works
- * without an explicit `freeze()`.
- *
- * Always queues a cleanup so the auto-restore path is uniform —
- * cleanups are idempotent (each calls `vi.useRealSystemTime`),
- * accumulating closures across many `travel` calls in one test is
- * intentional and cheap.
- *
- * Throws when called outside a test frame, same reason as `freeze`.
- */
-export function travel(amount: number, unit: TimeUnit = "ms"): void {
-	requireTestContext("travel");
-	if (!Number.isFinite(amount)) {
-		throw new Error(`helix.time.travel: amount must be finite, got ${amount}.`);
-	}
-	if ((unit === "month" || unit === "year") && !Number.isInteger(amount)) {
-		throw new Error(
-			`helix.time.travel: '${unit}' requires an integer amount, got ${amount}. Calendar units don't compose cleanly with fractions.`,
-		);
-	}
-	const base = vi.getMockedSystemTime() ?? Date.now();
-	const next = applyDelta(base, amount, unit);
-	requireInDateRange(next, "travel");
-	vi.setSystemTime(next);
-	// Always queue — `vi.useRealSystemTime` is idempotent so duplicate
-	// cleanups across `freeze + travel` are harmless. Always-queue
-	// guards against the "user pinned via raw `vi.setSystemTime`,
-	// then called `travel`" trap where the heuristic would skip.
-	registerTestCleanup(() => {
-		vi.useRealSystemTime();
-	});
-}
-
-/**
- * Travel TO a specific moment. Equivalent to `freeze(target)` —
- * exists as an explicit verb so "travel to 2026" reads better than
- * "freeze at 2026" in tests.
- */
-export function travelTo(target: TimeInput): void {
-	freeze(target);
-}
-
-/**
- * Restore the real system clock immediately. Idempotent — safe to
- * call when not currently frozen. Auto-restore still fires at
- * end-of-test, so calling `unfreeze` early is purely a
- * test-readability choice.
- */
-export function unfreeze(): void {
-	vi.useRealSystemTime();
-}
-
-/**
- * Read the currently frozen epoch, or `null` when running on real
- * time. Useful for tests that compose `freeze` with their own clock
- * arithmetic.
- */
-export function frozenAt(): number | null {
-	return vi.getMockedSystemTime();
-}
-
-function requireTestContext(verb: string): void {
-	if (!inTestContext()) {
-		throw new Error(
-			`helix.time.${verb}: must be called inside a test (no active test frame). Calls from top-level setup leak across tests — use vi.setSystemTime directly with manual cleanup if that is what you want.`,
-		);
-	}
-}
-
-function inputToMs(input: TimeInput): number {
-	let ms: number;
-	if (typeof input === "number") {
-		ms = input;
-	} else if (input instanceof Date) {
-		ms = input.getTime();
-	} else if (typeof input === "string") {
-		ms = Date.parse(input);
-		if (Number.isNaN(ms)) {
-			throw new Error(
-				`helix.time: cannot parse '${input}' as a date — pass an ISO 8601 string, Date, number (epoch ms), or an object with toMillis().`,
-			);
-		}
-	} else if (
-		typeof input === "object" &&
-		input !== null &&
-		typeof (input as MillisLike).toMillis === "function"
-	) {
-		const result = (input as MillisLike).toMillis();
-		if (typeof result !== "number") {
-			throw new Error(
-				`helix.time: input.toMillis() must return a number, got ${typeof result}.`,
-			);
-		}
-		ms = result;
-	} else {
-		throw new Error(
-			`helix.time: unsupported input type ${typeof input}. Use string / Date / number / { toMillis() }.`,
-		);
-	}
-	requireInDateRange(ms, "freeze");
-	return ms;
-}
-
-function requireInDateRange(ms: number, verb: string): void {
-	if (!Number.isFinite(ms)) {
-		throw new Error(
-			`helix.time.${verb}: epoch must be finite, got ${ms}. (Did you pass an Invalid Date or a NaN?)`,
-		);
-	}
-	if (Math.abs(ms) > JS_DATE_MAX) {
-		throw new Error(
-			`helix.time.${verb}: epoch ${ms} exceeds the JS Date range (±8.64e15 ms). The resulting clock would be 'Invalid Date'.`,
-		);
-	}
-}
-
-function applyDelta(base: number, amount: number, unit: TimeUnit): number {
-	switch (unit) {
-		case "ms":
-			return base + amount;
-		case "second":
-			return base + amount * 1_000;
-		case "minute":
-			return base + amount * 60_000;
-		case "hour":
-			return base + amount * 3_600_000;
-		case "day":
-			return base + amount * 86_400_000;
-		case "week":
-			return base + amount * 604_800_000;
-		case "month":
-		case "year": {
-			// UTC calendar math — JS `Date` mutators handle month
-			// overflow (e.g. month 13 → year+1 month 1) and clamp
-			// month-end days (e.g. Jan 31 + 1 month → Feb 28/29).
-			const d = new Date(base);
-			if (unit === "year") {
-				d.setUTCFullYear(d.getUTCFullYear() + amount);
-			} else {
-				d.setUTCMonth(d.getUTCMonth() + amount);
-			}
-			return d.getTime();
-		}
-		default: {
-			// Defensive — TS narrows this branch to `never`, but a
-			// runtime cast (`unit as TimeUnit`) could land here.
-			const exhaustive: never = unit;
-			throw new Error(
-				`helix.time.travel: unknown unit '${exhaustive as string}'.`,
-			);
-		}
-	}
-}

package/src/time/index.ts

@@ -1,16 +0,0 @@
-/**
- * `@c9up/helix/time` — time freeze / travel for tests.
- *
- * Pins `Date.now()`, `new Date()`, and `DateTime.now()` to a fake
- * epoch. Auto-restored after each test via the per-test frame.
- *
- *   import { time } from "@c9up/helix";
- *
- *   time.freeze("2026-01-01");
- *   // ... test that depends on a fixed clock
- *   time.travel(7, "day");
- *   expect(DateTime.now().toISO()).toMatch(/^2026-01-08/);
- */
-
-export type { TimeUnit } from "./freeze.js";
-export { freeze, frozenAt, travel, travelTo, unfreeze } from "./freeze.js";