@c9up/helix 0.1.3 → 0.1.5

package/src/runtime/suite.ts

@@ -1,310 +0,0 @@
-/**
- * `describe` / `test` / `it` DSL — builds a suite tree during module load.
- *
- * Collection phase: `describe(name, fn)` runs `fn` synchronously with an
- * active suite on a per-invocation stack. `withCollection(...)` scopes the
- * collection to one `runTestFile` call via AsyncLocalStorage, so parallel
- * invocations never share state.
- */
-
-import { AsyncLocalStorage } from "node:async_hooks";
-
-export type TestFn = () => void | Promise<void>;
-export type SuiteFn = () => void;
-
-export type HookType = "beforeAll" | "afterAll" | "beforeEach" | "afterEach";
-
-export interface Hook {
-	type: HookType;
-	fn: TestFn;
-}
-
-export type RunMode = "run" | "skip" | "only" | "todo";
-
-export interface TestNode {
-	kind: "test";
-	name: string;
-	fn: TestFn | undefined; // undefined for `todo`
-	mode: RunMode;
-	parent: SuiteNode;
-	location?: string;
-}
-
-export interface SuiteNode {
-	kind: "suite";
-	name: string;
-	mode: RunMode;
-	parent: SuiteNode | undefined;
-	children: Array<SuiteNode | TestNode>;
-	hooks: Hook[];
-}
-
-interface CollectionContext {
-	root: SuiteNode;
-	stack: SuiteNode[];
-}
-
-function makeSuite(
-	name: string,
-	mode: RunMode,
-	parent: SuiteNode | undefined,
-): SuiteNode {
-	return {
-		kind: "suite",
-		name,
-		mode,
-		parent,
-		children: [],
-		hooks: [],
-	};
-}
-
-/**
- * Scoped collection context. Each `runTestFile` invocation opens its own
- * store so concurrent runs never see each other's registrations.
- */
-const storage = new AsyncLocalStorage<CollectionContext>();
-
-/**
- * Fallback context used when the DSL is called outside `runTestFile` (e.g.,
- * unit tests that drive `describe`/`test` directly). `resetRoot` replaces
- * this; `getRoot` returns it.
- */
-let fallbackRoot: SuiteNode = makeSuite("", "run", undefined);
-let fallbackStack: SuiteNode[] = [fallbackRoot];
-
-function currentContext(): CollectionContext {
-	const scoped = storage.getStore();
-	if (scoped) return scoped;
-	return { root: fallbackRoot, stack: fallbackStack };
-}
-
-export function resetRoot(): SuiteNode {
-	fallbackRoot = makeSuite("", "run", undefined);
-	fallbackStack = [fallbackRoot];
-	return fallbackRoot;
-}
-
-export function getRoot(): SuiteNode {
-	return currentContext().root;
-}
-
-/**
- * Run `body` inside a fresh, isolated collection context. Returns the root
- * populated by its DSL calls. Safe under concurrent invocation.
- */
-export async function withCollection(
-	body: () => Promise<void> | void,
-): Promise<SuiteNode> {
-	const root = makeSuite("", "run", undefined);
-	const ctx: CollectionContext = { root, stack: [root] };
-	await storage.run(ctx, async () => {
-		await body();
-	});
-	return root;
-}
-
-function current(): SuiteNode {
-	const { stack } = currentContext();
-	const top = stack[stack.length - 1];
-	if (!top) throw new Error("internal: suite stack empty");
-	return top;
-}
-
-function registerTest(
-	name: string,
-	mode: RunMode,
-	fn: TestFn | undefined,
-): void {
-	const parent = current();
-	parent.children.push({
-		kind: "test",
-		name,
-		fn,
-		mode,
-		parent,
-	});
-}
-
-function registerSuite(name: string, mode: RunMode, body: SuiteFn): void {
-	const ctx = currentContext();
-	const parent = current();
-	const suite = makeSuite(name, mode, parent);
-	parent.children.push(suite);
-	ctx.stack.push(suite);
-	let result: unknown;
-	try {
-		result = body();
-	} finally {
-		ctx.stack.pop();
-	}
-	// Async describe bodies would register nested describe/test against the
-	// wrong parent after the first `await` (because we've already popped).
-	// Fail loudly rather than silently mis-collect.
-	if (result && typeof (result as { then?: unknown }).then === "function") {
-		throw new Error(
-			`describe(${JSON.stringify(name)}): body returned a Promise. Async describe is not supported — await the setup in a \`beforeAll\` hook instead.`,
-		);
-	}
-}
-
-type SuiteApi = {
-	(name: string, fn: SuiteFn): void;
-	skip(name: string, fn: SuiteFn): void;
-	only(name: string, fn: SuiteFn): void;
-	todo(name: string): void;
-};
-
-type ArrayRow = readonly unknown[];
-type ObjectRow = Readonly<Record<string, unknown>>;
-type EachRow =
-	| ArrayRow
-	| ObjectRow
-	| null
-	| undefined
-	| string
-	| number
-	| boolean
-	| bigint
-	| symbol;
-
-type TestApi = {
-	(name: string, fn: TestFn): void;
-	skip(name: string, fn?: TestFn): void;
-	only(name: string, fn: TestFn): void;
-	todo(name: string): void;
-	each<Row extends EachRow>(
-		rows: readonly Row[],
-	): (name: string, fn: (row: Row) => void | Promise<void>) => void;
-};
-
-function safeStringify(v: unknown): string {
-	try {
-		const s = JSON.stringify(v);
-		return s === undefined ? String(v) : s;
-	} catch {
-		// Circular / BigInt / etc.
-		return String(v);
-	}
-}
-
-function isArrayRow(row: EachRow): row is ArrayRow {
-	return Array.isArray(row);
-}
-
-function isObjectRow(row: EachRow): row is ObjectRow {
-	return typeof row === "object" && row !== null && !Array.isArray(row);
-}
-
-function interpolateArrayRow(
-	template: string,
-	row: ArrayRow,
-	index: number,
-): string {
-	// Hand-rolled walker so `%%` escapes to a literal `%` without consuming a
-	// row value, and format specifiers consume their argument in order.
-	let i = 0;
-	let out = "";
-	for (let j = 0; j < template.length; j += 1) {
-		const c = template[j];
-		if (c !== "%" || j === template.length - 1) {
-			out += c;
-			continue;
-		}
-		const next = template[j + 1];
-		if (next === "%") {
-			out += "%";
-			j += 1;
-			continue;
-		}
-		if (next === "#") {
-			out += String(index);
-			j += 1;
-			continue;
-		}
-		if (
-			next === "s" ||
-			next === "d" ||
-			next === "i" ||
-			next === "f" ||
-			next === "j" ||
-			next === "o"
-		) {
-			const v = row[i];
-			i += 1;
-			out += typeof v === "object" && v !== null ? safeStringify(v) : String(v);
-			j += 1;
-			continue;
-		}
-		out += c;
-	}
-	return out;
-}
-
-function interpolateObjectRow(
-	template: string,
-	row: ObjectRow,
-	index: number,
-): string {
-	return template
-		.replace(/\$#/g, String(index))
-		.replace(/\$([a-zA-Z_][\w.]*)/g, (_match, path: string) => {
-			const parts = path.split(".");
-			let cursor: unknown = row;
-			for (const p of parts) {
-				if (cursor && typeof cursor === "object" && p in cursor) {
-					cursor = Reflect.get(cursor, p);
-				} else {
-					return "undefined";
-				}
-			}
-			if (typeof cursor === "object" && cursor !== null)
-				return safeStringify(cursor);
-			return String(cursor);
-		});
-}
-
-function interpolateEach(
-	template: string,
-	row: EachRow,
-	index: number,
-): string {
-	if (isArrayRow(row)) return interpolateArrayRow(template, row, index);
-	if (isObjectRow(row)) return interpolateObjectRow(template, row, index);
-	// Primitive row (number, string, boolean, bigint, symbol, null, undefined).
-	// Append index so names don't collide.
-	return `${template} [${index}]`;
-}
-
-const describeFn = ((name: string, fn: SuiteFn) =>
-	registerSuite(name, "run", fn)) as SuiteApi;
-describeFn.skip = (name, fn) => registerSuite(name, "skip", fn);
-describeFn.only = (name, fn) => registerSuite(name, "only", fn);
-describeFn.todo = (name) => registerSuite(name, "todo", () => {});
-
-const testFn = ((name: string, fn: TestFn) =>
-	registerTest(name, "run", fn)) as TestApi;
-testFn.skip = (name, fn) => registerTest(name, "skip", fn);
-testFn.only = (name, fn) => registerTest(name, "only", fn);
-testFn.todo = (name) => registerTest(name, "todo", undefined);
-testFn.each = <Row extends EachRow>(rows: readonly Row[]) => {
-	return (name: string, fn: (row: Row) => void | Promise<void>) => {
-		rows.forEach((row, index) => {
-			const resolvedName = interpolateEach(name, row, index);
-			registerTest(resolvedName, "run", () => fn(row));
-		});
-	};
-};
-
-export const describe: SuiteApi = describeFn;
-export const test: TestApi = testFn;
-export const it: TestApi = testFn;
-
-export function addHook(type: HookType, fn: TestFn): void {
-	current().hooks.push({ type, fn });
-}
-
-export const beforeAll = (fn: TestFn): void => addHook("beforeAll", fn);
-export const afterAll = (fn: TestFn): void => addHook("afterAll", fn);
-export const beforeEach = (fn: TestFn): void => addHook("beforeEach", fn);
-export const afterEach = (fn: TestFn): void => addHook("afterEach", fn);

package/src/runtime/test-context.ts

@@ -1,59 +0,0 @@
-/**
- * Per-test execution frame.
- *
- * Whereas `withViContext` wraps each test FILE (so spies and fake
- * timers can span tests within a file), `withTestContext` wraps each
- * INDIVIDUAL test (cycle = beforeEach + body + afterEach). It exists
- * so test-scoped resources — most notably container overrides
- * registered through `helix.override()` — get torn down between tests
- * without needing the user to wire `afterEach(restore)` by hand.
- *
- * Cleanup semantics mirror `withViContext`'s finally:
- *   - reverse insertion order
- *   - one cleanup throwing must not block the others
- */
-
-import { AsyncLocalStorage } from "node:async_hooks";
-
-export type TestCleanup = () => void | Promise<void>;
-
-interface TestFrame {
-	cleanups: TestCleanup[];
-}
-
-const storage = new AsyncLocalStorage<TestFrame>();
-
-export async function withTestContext<T>(body: () => Promise<T>): Promise<T> {
-	const frame: TestFrame = { cleanups: [] };
-	try {
-		return await storage.run(frame, body);
-	} finally {
-		for (let i = frame.cleanups.length - 1; i >= 0; i -= 1) {
-			try {
-				await frame.cleanups[i]();
-			} catch (err) {
-				// One cleanup failing must not block the others — but log it
-				// so silent leaks become noisy. `console.error` matches what
-				// Vitest does for `afterEach` failures observed at runtime.
-				console.error("[helix] test cleanup failed:", err);
-			}
-		}
-	}
-}
-
-/**
- * Register a cleanup function that runs at the end of the current
- * test cycle. Returns `true` when registered, `false` when called
- * outside a test frame (caller decides — usually a no-op or fallback
- * to a wider frame).
- */
-export function registerTestCleanup(cleanup: TestCleanup): boolean {
-	const frame = storage.getStore();
-	if (!frame) return false;
-	frame.cleanups.push(cleanup);
-	return true;
-}
-
-export function inTestContext(): boolean {
-	return storage.getStore() !== undefined;
-}