@c9up/helix 0.1.3

package/src/runtime/equals.ts

@@ -0,0 +1,400 @@
+/**
+ * Deep structural equality — Vitest-compatible semantics.
+ *
+ * Handles: primitives (Object.is for NaN; ±0 treated equal in non-strict toEqual),
+ * Date, RegExp, Map, Set, Array, Buffer, typed arrays, DataView, boxed primitives
+ * (Number/String/Boolean), Error instances, circular refs, Symbol-keyed props.
+ * Ignores prototypes for plain objects (matches Jest/Vitest `toEqual`).
+ *
+ * `toStrictEqual` semantics (checks prototype + undefined-vs-missing keys)
+ * are supported via the `strict` option.
+ */
+
+export interface EqualsOptions {
+	/** `toStrictEqual` semantics — prototypes matched, undefined keys distinguished from missing. */
+	strict?: boolean;
+}
+
+type Seen = WeakMap<object, WeakSet<object>>;
+
+export function equals(
+	a: unknown,
+	b: unknown,
+	options: EqualsOptions = {},
+): boolean {
+	return eq(a, b, options, new WeakMap());
+}
+
+/**
+ * Record a pair as "in progress" in BOTH directions so a later visit to the
+ * mirrored pair (b,a) is detected as a cycle too.
+ */
+function markSeen(seen: Seen, a: object, b: object): void {
+	let setA = seen.get(a);
+	if (!setA) {
+		setA = new WeakSet();
+		seen.set(a, setA);
+	}
+	setA.add(b);
+	let setB = seen.get(b);
+	if (!setB) {
+		setB = new WeakSet();
+		seen.set(b, setB);
+	}
+	setB.add(a);
+}
+
+function seenPair(seen: Seen, a: object, b: object): boolean {
+	return seen.get(a)?.has(b) ?? false;
+}
+
+/**
+ * A structural comparator for one object "kind". Returns `true`/`false` when it
+ * recognises the pair as its kind (and decides equality), or `undefined` to
+ * mean "not my kind — let the next comparator try". This keeps `eq` a flat
+ * dispatch loop instead of a 150-line `instanceof` ladder.
+ */
+type Comparator = (
+	a: object,
+	b: object,
+	opts: EqualsOptions,
+	seen: Seen,
+) => boolean | undefined;
+
+function isBoxedPrimitive(v: object): boolean {
+	return v instanceof Number || v instanceof String || v instanceof Boolean;
+}
+
+// Boxed primitives — unwrap so `new Number(1)` vs `new Number(2)` differ
+// properly; a box compared against anything not the same box type is unequal.
+function compareBoxed(a: object, b: object): boolean | undefined {
+	if (a instanceof Number && b instanceof Number)
+		return Object.is(a.valueOf(), b.valueOf());
+	if (a instanceof String && b instanceof String)
+		return Object.is(a.valueOf(), b.valueOf());
+	if (a instanceof Boolean && b instanceof Boolean)
+		return Object.is(a.valueOf(), b.valueOf());
+	if (isBoxedPrimitive(a) || isBoxedPrimitive(b)) return false;
+	return undefined;
+}
+
+function compareDate(a: object, b: object): boolean | undefined {
+	if (!(a instanceof Date) && !(b instanceof Date)) return undefined;
+	return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+}
+
+function compareRegExp(a: object, b: object): boolean | undefined {
+	if (!(a instanceof RegExp) && !(b instanceof RegExp)) return undefined;
+	return (
+		a instanceof RegExp &&
+		b instanceof RegExp &&
+		a.source === b.source &&
+		a.flags === b.flags
+	);
+}
+
+// Error instances — compare name + message + own enumerable keys. The built-in
+// fields are non-enumerable so plain-keys comparison alone would report any two
+// Errors as equal.
+function compareError(
+	a: object,
+	b: object,
+	opts: EqualsOptions,
+	seen: Seen,
+): boolean | undefined {
+	if (!(a instanceof Error) && !(b instanceof Error)) return undefined;
+	if (!(a instanceof Error && b instanceof Error)) return false;
+	if (a.name !== b.name) return false;
+	if (a.message !== b.message) return false;
+	return compareOwnKeys(a, b, opts, seen);
+}
+
+// DataView — compare by byteLength + getUint8 byte-for-byte.
+function compareDataView(a: object, b: object): boolean | undefined {
+	if (!(a instanceof DataView) && !(b instanceof DataView)) return undefined;
+	if (!(a instanceof DataView && b instanceof DataView)) return false;
+	if (a.byteLength !== b.byteLength) return false;
+	for (let i = 0; i < a.byteLength; i += 1) {
+		if (a.getUint8(i) !== b.getUint8(i)) return false;
+	}
+	return true;
+}
+
+// Buffer — shortcut via Buffer.equals when both are Buffers. When only one is a
+// Buffer, return `undefined` so the typed-array comparator handles it (a Buffer
+// is a Uint8Array): a constructor mismatch there yields the correct inequality.
+function compareBuffer(a: object, b: object): boolean | undefined {
+	if (typeof Buffer === "undefined") return undefined;
+	if (Buffer.isBuffer(a) && Buffer.isBuffer(b)) return a.equals(b);
+	return undefined;
+}
+
+// Typed arrays (Uint8Array, Int16Array, Float64Array, BigInt64Array, …).
+// Require matching constructor so Uint8Array !== Int8Array even when values coincide.
+function compareTypedArray(
+	a: object,
+	b: object,
+	opts: EqualsOptions,
+): boolean | undefined {
+	const viewA = asNumericTypedArray(a);
+	const viewB = asNumericTypedArray(b);
+	if (!viewA && !viewB) return undefined;
+	if (!viewA || !viewB) return false;
+	if (a.constructor !== b.constructor) return false;
+	if (viewA.length !== viewB.length) return false;
+	for (let i = 0; i < viewA.length; i += 1) {
+		const av = viewA[i];
+		const bv = viewB[i];
+		// Object.is so NaN === NaN inside Float32/64Array.
+		if (Object.is(av, bv)) continue;
+		if (opts.strict) return false;
+		if (av !== bv) return false; // non-strict: ±0 already caught by `===`.
+	}
+	return true;
+}
+
+function compareArray(
+	a: object,
+	b: object,
+	opts: EqualsOptions,
+	seen: Seen,
+): boolean | undefined {
+	if (!Array.isArray(a) && !Array.isArray(b)) return undefined;
+	if (!(Array.isArray(a) && Array.isArray(b))) return false;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i += 1) {
+		if (!eq(a[i], b[i], opts, seen)) return false;
+	}
+	return true;
+}
+
+// Maps — structural key comparison supporting object keys.
+function compareMap(
+	a: object,
+	b: object,
+	opts: EqualsOptions,
+	seen: Seen,
+): boolean | undefined {
+	if (!(a instanceof Map) && !(b instanceof Map)) return undefined;
+	if (!(a instanceof Map && b instanceof Map)) return false;
+	if (a.size !== b.size) return false;
+	for (const [kA, vA] of a) {
+		// Fast path: identity/primitive key hit.
+		if (b.has(kA) && eq(vA, b.get(kA), opts, seen)) continue;
+		// Structural search across remaining entries.
+		let matched = false;
+		for (const [kB, vB] of b) {
+			if (eq(kA, kB, opts, seen) && eq(vA, vB, opts, seen)) {
+				matched = true;
+				break;
+			}
+		}
+		if (!matched) return false;
+	}
+	return true;
+}
+
+// Sets — deep structural. Use a fresh WeakMap per inner comparison so an
+// earlier failed candidate does not poison the next one via cycle cache.
+function compareSet(
+	a: object,
+	b: object,
+	opts: EqualsOptions,
+): boolean | undefined {
+	if (!(a instanceof Set) && !(b instanceof Set)) return undefined;
+	if (!(a instanceof Set && b instanceof Set)) return false;
+	if (a.size !== b.size) return false;
+	for (const v of a) {
+		let found = false;
+		for (const w of b) {
+			if (eq(v, w, opts, new WeakMap())) {
+				found = true;
+				break;
+			}
+		}
+		if (!found) return false;
+	}
+	return true;
+}
+
+// Order matters — mirrors the original `instanceof` ladder. Buffer sits before
+// typed arrays so the both-Buffer fast path wins before the generic view check.
+const STRUCTURAL_COMPARATORS: readonly Comparator[] = [
+	compareDate,
+	compareRegExp,
+	compareError,
+	compareDataView,
+	compareBuffer,
+	compareTypedArray,
+	compareArray,
+	compareMap,
+	compareSet,
+];
+
+function eq(a: unknown, b: unknown, opts: EqualsOptions, seen: Seen): boolean {
+	// Identity / NaN (Object.is). In non-strict mode, ±0 are also equal.
+	if (Object.is(a, b)) return true;
+	if (!opts.strict && a === b) return true;
+	if (a === null || b === null) return false;
+	if (typeof a !== typeof b) return false;
+	if (typeof a !== "object") return false;
+
+	const objA = a as object;
+	const objB = b as object;
+
+	if (seenPair(seen, objA, objB)) return true;
+	markSeen(seen, objA, objB);
+
+	const boxed = compareBoxed(objA, objB);
+	if (boxed !== undefined) return boxed;
+
+	// Strict: differing prototypes → not equal (plain `{}` vs class instance).
+	if (
+		opts.strict &&
+		Object.getPrototypeOf(objA) !== Object.getPrototypeOf(objB)
+	) {
+		return false;
+	}
+
+	for (const compare of STRUCTURAL_COMPARATORS) {
+		const result = compare(objA, objB, opts, seen);
+		if (result !== undefined) return result;
+	}
+
+	return compareOwnKeys(objA, objB, opts, seen);
+}
+
+function getProp(obj: object, key: PropertyKey): unknown {
+	return Reflect.get(obj, key);
+}
+
+type NumericTypedArray =
+	| Int8Array
+	| Uint8Array
+	| Uint8ClampedArray
+	| Int16Array
+	| Uint16Array
+	| Int32Array
+	| Uint32Array
+	| Float32Array
+	| Float64Array
+	| BigInt64Array
+	| BigUint64Array;
+
+function asNumericTypedArray(v: object): NumericTypedArray | undefined {
+	if (
+		v instanceof Int8Array ||
+		v instanceof Uint8Array ||
+		v instanceof Uint8ClampedArray ||
+		v instanceof Int16Array ||
+		v instanceof Uint16Array ||
+		v instanceof Int32Array ||
+		v instanceof Uint32Array ||
+		v instanceof Float32Array ||
+		v instanceof Float64Array ||
+		v instanceof BigInt64Array ||
+		v instanceof BigUint64Array
+	) {
+		return v;
+	}
+	return undefined;
+}
+
+function compareOwnKeys(
+	objA: object,
+	objB: object,
+	opts: EqualsOptions,
+	seen: Seen,
+): boolean {
+	const keysA = ownEnumerableKeys(objA);
+	const keysB = ownEnumerableKeys(objB);
+
+	if (opts.strict) {
+		if (keysA.length !== keysB.length) return false;
+		for (const k of keysA) {
+			if (!Object.prototype.propertyIsEnumerable.call(objB, k)) return false;
+			if (!eq(getProp(objA, k), getProp(objB, k), opts, seen)) return false;
+		}
+		return true;
+	}
+
+	// Non-strict: undefined value ≡ missing key.
+	const union = new Set<string | symbol>([...keysA, ...keysB]);
+	for (const k of union) {
+		const va = getProp(objA, k);
+		const vb = getProp(objB, k);
+		if (va === undefined && vb === undefined) continue;
+		if (!eq(va, vb, opts, seen)) return false;
+	}
+	return true;
+}
+
+function ownEnumerableKeys(obj: object): Array<string | symbol> {
+	const strings = Object.keys(obj);
+	const symbols = Object.getOwnPropertySymbols(obj).filter((s) =>
+		Object.prototype.propertyIsEnumerable.call(obj, s),
+	);
+	return [...strings, ...symbols];
+}
+
+/**
+ * Partial match — every key/element in `expected` must match in `actual`.
+ * Extra keys in `actual` are allowed for plain objects.
+ * Arrays must have the same length (Vitest v1+ semantics, not Jest).
+ * Date / RegExp / Error / Map / Set / TypedArray / Buffer / DataView delegate
+ * to `equals` — "partial" is ill-defined for them.
+ */
+export function partialEquals(actual: unknown, expected: unknown): boolean {
+	return partial(actual, expected, new WeakMap());
+}
+
+function partial(actual: unknown, expected: unknown, seen: Seen): boolean {
+	if (Object.is(actual, expected)) return true;
+	if (expected === null || expected === undefined) {
+		return actual === expected;
+	}
+	if (typeof expected !== "object") {
+		return equals(actual, expected);
+	}
+	if (typeof actual !== "object" || actual === null) return false;
+
+	// Both narrowed to object by the guards above — no cast needed.
+	const objE: object = expected;
+	const objA: object = actual;
+
+	if (seenPair(seen, objA, objE)) return true;
+	markSeen(seen, objA, objE);
+
+	// Types with no "partial" semantics — fall through to full equality.
+	if (lacksPartialSemantics(objE)) {
+		return equals(actual, expected);
+	}
+
+	if (Array.isArray(expected)) {
+		if (!Array.isArray(actual)) return false;
+		if (actual.length !== expected.length) return false;
+		for (let i = 0; i < expected.length; i += 1) {
+			if (!partial(actual[i], expected[i], seen)) return false;
+		}
+		return true;
+	}
+
+	for (const key of ownEnumerableKeys(objE)) {
+		if (!partial(getProp(objA, key), getProp(objE, key), seen)) return false;
+	}
+	return true;
+}
+
+/** Object kinds for which "partial" is ill-defined → fall back to full equals. */
+function lacksPartialSemantics(value: object): boolean {
+	return (
+		value instanceof Date ||
+		value instanceof RegExp ||
+		value instanceof Error ||
+		value instanceof Map ||
+		value instanceof Set ||
+		value instanceof DataView ||
+		(typeof Buffer !== "undefined" && Buffer.isBuffer(value)) ||
+		(ArrayBuffer.isView(value) && !(value instanceof DataView))
+	);
+}

package/src/runtime/expect.ts

@@ -0,0 +1,173 @@
+/**
+ * `expect(value)` engine — chainable assertion API compatible with Vitest.
+ *
+ * Supports:
+ *   - All matchers in `./matchers.ts`
+ *   - `.not.<matcher>()` — inverts pass/fail
+ *   - `.resolves.<matcher>()` / `.rejects.<matcher>()` — async awaits on received
+ *   - All four combinations: `.resolves.not`, `.rejects.not`, `.not.resolves`, `.not.rejects`
+ */
+
+import { AssertionError } from "./assertion-error.js";
+import { type MatcherName, matchers } from "./matchers.js";
+
+type MatcherArgs<Name extends MatcherName> = (typeof matchers)[Name] extends (
+	received: unknown,
+	...args: infer A
+) => unknown
+	? A
+	: never;
+
+type SyncChain = {
+	[K in MatcherName]: (...args: MatcherArgs<K>) => void;
+};
+
+type AsyncChain = {
+	[K in MatcherName]: (...args: MatcherArgs<K>) => Promise<void>;
+};
+
+export type Assertion = SyncChain & {
+	not: SyncChain & {
+		resolves: AsyncChain;
+		rejects: AsyncChain;
+	};
+	resolves: AsyncChain & { not: AsyncChain };
+	rejects: AsyncChain & { not: AsyncChain };
+};
+
+interface EvalContext {
+	received: unknown;
+	negate: boolean;
+}
+
+type MatcherInvoker = (
+	received: unknown,
+	...rest: unknown[]
+) => {
+	pass: boolean;
+	message(): string;
+};
+
+function evaluate(ctx: EvalContext, name: MatcherName, args: unknown[]): void {
+	const matcher = matchers[name] as MatcherInvoker;
+	let result: { pass: boolean; message(): string };
+	try {
+		result = matcher(ctx.received, ...args);
+	} catch (err) {
+		// A matcher threw unexpectedly (e.g. a user-supplied constructor with
+		// a throwing `Symbol.hasInstance`). Surface it as a normal assertion
+		// failure so reporters can render it uniformly.
+		const why = err instanceof Error ? err.message : String(err);
+		throw new AssertionError({
+			message: `matcher ${name} threw: ${why}`,
+			actual: ctx.received,
+			expected: args.length === 1 ? args[0] : args,
+			operator: ctx.negate ? `not.${name}` : name,
+		});
+	}
+	const pass = ctx.negate ? !result.pass : result.pass;
+	if (pass) return;
+	const prefix = ctx.negate ? "expected NOT: " : "";
+	throw new AssertionError({
+		message: `${prefix}${result.message()}`,
+		actual: ctx.received,
+		expected: args,
+		operator: ctx.negate ? `not.${name}` : name,
+	});
+}
+
+const matcherNames = Object.keys(matchers) as MatcherName[];
+
+function buildSync(received: unknown, negate: boolean): SyncChain {
+	const api = {} as SyncChain;
+	for (const name of matcherNames) {
+		const fn = (...args: unknown[]) =>
+			evaluate({ received, negate }, name, args);
+		Reflect.set(api, name, fn);
+	}
+	return api;
+}
+
+type PromiseMode = "resolves" | "rejects";
+
+function buildAsync(
+	received: unknown,
+	mode: PromiseMode,
+	negate: boolean,
+): AsyncChain {
+	const api = {} as AsyncChain;
+	for (const name of matcherNames) {
+		const fn = async (...args: unknown[]) => {
+			if (
+				!received ||
+				typeof (received as { then?: unknown }).then !== "function"
+			) {
+				throw new AssertionError({
+					message: `expected a Promise (for .${mode}), got ${typeof received}`,
+					operator: `${mode}.${name}`,
+				});
+			}
+			let resolved: unknown;
+			let rejected: unknown;
+			let didReject = false;
+			try {
+				resolved = await (received as PromiseLike<unknown>);
+			} catch (err) {
+				rejected = err;
+				didReject = true;
+			}
+			if (mode === "resolves") {
+				if (didReject) {
+					throw new AssertionError({
+						message: `expected promise to resolve, but it rejected with ${String(rejected)}`,
+						operator: `resolves.${name}`,
+					});
+				}
+				evaluate({ received: resolved, negate }, name, args);
+				return;
+			}
+			if (!didReject) {
+				throw new AssertionError({
+					message: `expected promise to reject, but it resolved with ${String(resolved)}`,
+					operator: `rejects.${name}`,
+				});
+			}
+			// `.rejects.toThrow(...)` feeds the rejection into toThrow's
+			// function-scoped contract by wrapping it in a rethrowing thunk.
+			const target =
+				name === "toThrow"
+					? () => {
+							throw rejected;
+						}
+					: rejected;
+			evaluate({ received: target, negate }, name, args);
+		};
+		Reflect.set(api, name, fn);
+	}
+	return api;
+}
+
+export function expect(received: unknown): Assertion {
+	const base = buildSync(received, false);
+
+	// `.not` returns a chain that negates every matcher. It also exposes
+	// `.resolves` / `.rejects` so `expect(p).not.resolves.toBe(x)` works, matching
+	// Vitest's full surface.
+	const notSync = Object.assign(buildSync(received, true), {
+		resolves: buildAsync(received, "resolves", true),
+		rejects: buildAsync(received, "rejects", true),
+	});
+
+	const resolves = Object.assign(buildAsync(received, "resolves", false), {
+		not: buildAsync(received, "resolves", true),
+	});
+	const rejects = Object.assign(buildAsync(received, "rejects", false), {
+		not: buildAsync(received, "rejects", true),
+	});
+
+	return Object.assign(base, {
+		not: notSync,
+		resolves,
+		rejects,
+	});
+}

package/src/runtime/index.ts

@@ -0,0 +1,50 @@
+/**
+ * `@c9up/helix/runtime` — public surface of the Vitest-compatible test runtime.
+ *
+ * Test files can `import { describe, test, expect } from "@c9up/helix"` and
+ * get the full DSL. The runtime is orchestrator-agnostic: a Node child
+ * process, a Bun worker, or a Rust-spawned worker all load the same module.
+ */
+
+export type { AssertionErrorInit } from "./assertion-error.js";
+export { AssertionError, isAssertionError } from "./assertion-error.js";
+export type { EqualsOptions } from "./equals.js";
+export { equals, partialEquals } from "./equals.js";
+export type { Assertion } from "./expect.js";
+export { expect } from "./expect.js";
+export type { Hook, HookType } from "./lifecycle.js";
+export {
+	addHook,
+	afterAll,
+	afterEach,
+	beforeAll,
+	beforeEach,
+} from "./lifecycle.js";
+export type { MatcherName, MatcherResult, SpyLike } from "./matchers.js";
+export { matchers } from "./matchers.js";
+export type {
+	FileResult,
+	SerializedError,
+	SuiteResult,
+	TestResult,
+} from "./run.js";
+export { executeRoot } from "./run.js";
+export type { RunMode, SuiteNode, TestFn, TestNode } from "./suite.js";
+export {
+	describe,
+	getRoot,
+	it,
+	resetRoot,
+	test,
+} from "./suite.js";
+export type { Vi } from "./vi/index.js";
+export { vi, withViContext } from "./vi/index.js";
+export type {
+	CreateSpyOptions,
+	MockCallResult,
+	MockInternals,
+	Spy,
+} from "./vi/spy.js";
+export type { SpyOnOptions } from "./vi/spyOn.js";
+export type { RunFileOptions } from "./worker.js";
+export { runTestFile } from "./worker.js";

package/src/runtime/lifecycle.ts

@@ -0,0 +1,17 @@
+/**
+ * Public re-exports for lifecycle hooks.
+ *
+ * The actual registration lives in `./suite.ts` (hooks are attached to the
+ * currently-active suite on the collection stack). This module exists as a
+ * stable import path for reporters/plugins that want hooks without the full
+ * DSL surface.
+ */
+
+export type { Hook, HookType } from "./suite.js";
+export {
+	addHook,
+	afterAll,
+	afterEach,
+	beforeAll,
+	beforeEach,
+} from "./suite.js";