@systemfsoftware/vitest 0.0.0 → 0.1.0

package/dist/guard-BocOhXt2.mjs

@@ -0,0 +1,246 @@
+
+import { chai } from "vitest";
+//#region src/internal/refusals.ts
+/**
+* Every refusal the fork prints, as the one text it uses on both channels: the `this` type (or parameter union)
+* the compiler prints at the call site, and the message thrown at run time.
+*
+* Surface: `it(name, function* ({ expect }) { ... })`. Ported verbatim from the prototype's `checks.ts`; the
+* prototype's `test(` surfaces are rewritten to `it(`, and `refusedText` gained the `expect` statics
+* (`.resolves`, `.rejects`, `expect.anything`, `expect.poll`, `expect.soft`).
+*
+* @since 4.0.0
+*/
+/**
+* The brand every run-time refusal carries. A test is run a second time on a fresh build to catch leaked state,
+* so when that second run fails with a refusal the fork itself made, the runner re-throws the refusal rather than
+* relabelling it as a leak (see `throwSecondRun` in `runner.ts`). The brand is a `Symbol.for` value because a
+* worker holds two copies of these modules at once — the setup file's `dist/guard.mjs` beside the test graph's
+* `src/mod.ts` — and a refusal thrown by either copy has to be recognisable to the other, exactly as the guard's
+* window is shared.
+*/
+const refusalBrand = Symbol.for("@systemfsoftware/vitest/refusal");
+/** The error a refusal throws: the refusal text, branded so {@link isRefusal} recognises it. */
+/** @internal */
+const refusalOf = (text) => {
+	const error = new Error(text);
+	Reflect.set(error, refusalBrand, true);
+	return error;
+};
+/** Whether an error is one of the fork's own refusals, rather than a failure of the test under it. */
+/** @internal */
+const isRefusal = (error) => error instanceof Error && Reflect.get(error, refusalBrand) === true;
+/** @internal */
+const refusedText = {
+	toBeDefined: "✗ toBeDefined passes for almost any value the code returns. Assert the value: yield* expect(actual).toEqual(expected).",
+	toBeTruthy: "✗ toBeTruthy passes for almost any value the code returns. Assert the value: yield* expect(actual).toEqual(expected).",
+	toBeFalsy: "✗ toBeFalsy passes for almost any value the code returns. Assert the value: yield* expect(actual).toEqual(expected).",
+	toHaveLength: "✗ toHaveLength checks how many, not which. Assert the contents: toEqual([...]); only some of them: toEqual(expect.arrayContaining([...])).",
+	toHaveProperty: "✗ toHaveProperty checks one key at a time. Assert the shape once: toMatchObject({ key: value, ... }).",
+	toBeInstanceOf: "✗ toBeInstanceOf checks the kind of value, not the value. Assert the value: toEqual(expected); only its shape: toEqual(expect.schemaMatching(Schema)).",
+	toBeTypeOf: "✗ toBeTypeOf checks the kind of value, not the value. Assert the value: toEqual(expected); only its shape: toEqual(expect.schemaMatching(Schema)).",
+	toHaveBeenCalled: "✗ toHaveBeenCalled passes for any call with any arguments. Assert what the call carried: toHaveBeenCalledExactlyOnceWith(...args).",
+	toHaveBeenCalledTimes: "✗ toHaveBeenCalledTimes counts calls, not what they carried. Assert the calls: toHaveBeenNthCalledWith(n, ...args), or all of them: expect(spy.mock.calls).toEqual([[...], [...]]).",
+	toMatchSnapshot: "✗ a snapshot records what the code does now, not what it should do, and cannot fail on the run that writes it. State the expected value: toEqual(expected).",
+	toMatchInlineSnapshot: "✗ a snapshot records what the code does now, not what it should do, and cannot fail on the run that writes it. State the expected value: toEqual(expected).",
+	toMatchFileSnapshot: "✗ a snapshot records what the code does now, not what it should do, and cannot fail on the run that writes it. State the expected value: toEqual(expected).",
+	toThrowErrorMatchingSnapshot: "✗ a snapshot records what the code does now, not what it should do, and cannot fail on the run that writes it. Name the error: toThrow(MyError).",
+	toThrowErrorMatchingInlineSnapshot: "✗ a snapshot records what the code does now, not what it should do, and cannot fail on the run that writes it. Name the error: toThrow(MyError).",
+	resolves: "✗ .resolves/.rejects assert on a Promise outside the test runtime. Yield the Effect: const value = yield* program; its failure: const error = yield* Effect.flip(program); then yield* expect(error).toEqual(new MyError(...)).",
+	rejects: "✗ .resolves/.rejects assert on a Promise outside the test runtime. Yield the Effect: const value = yield* program; its failure: const error = yield* Effect.flip(program); then yield* expect(error).toEqual(new MyError(...)).",
+	anything: "✗ expect.anything() matches every value. Say what the value must be: expect.any(Money), expect.objectContaining({ ... }), expect.schemaMatching(Schema).",
+	poll: "✗ expect.poll waits on the real clock, outside the runner's virtual time. Let time pass inside the test: yield* TestClock.adjust(\"3 seconds\"); then yield* expect(value).toEqual(expected).",
+	soft: "✗ expect.soft reports several failures on one state; the fork reports the state once. Assert the state once: yield* expect(actual).toEqual(expected)."
+};
+/** @internal */
+const negatedText = {
+	...refusedText,
+	toBeNull: "✗ not.toBeNull passes for almost any value the code returns. Assert the value: yield* expect(actual).toEqual(expected).",
+	toBeUndefined: "✗ not.toBeUndefined passes for almost any value the code returns. Assert the value: yield* expect(actual).toEqual(expected)."
+};
+/** @internal */
+const neededText = {
+	toThrow: "✗ toThrow() passes for any error. Name the one expected: toThrow(MyError) or toThrow(\"message\"). An Effect failure is a value: const error = yield* Effect.flip(program); yield* expect(error).toEqual(new MyError(...)).",
+	toThrowError: "✗ toThrowError() passes for any error. Name the one expected: toThrow(MyError) or toThrow(\"message\"). An Effect failure is a value: const error = yield* Effect.flip(program); yield* expect(error).toEqual(new MyError(...)).",
+	toSatisfy: "✗ toSatisfy(predicate) fails with 'expected x to satisfy [Function]'. Say what must hold: toSatisfy(predicate, \"every line has a positive quantity\").",
+	toMatchObject: "✗ toMatchObject({}) matches every object. Name the fields that must hold: toMatchObject({ status: \"Pending\" })."
+};
+/** @internal */
+const booleanRefusal = "✗ expect(<boolean>) can only report 'expected false to be true'. Pass the two values instead: yield* expect(a).toEqual(b), which uses Effect Equal. A predicate: yield* expect(value).toSatisfy(predicate, \"what must hold\").";
+/** @internal */
+const refusePiecewise = "✗ a second check on the same state. Checking a state piece by piece reports one field at a time and misses the ones never checked. Assert the state once: yield* expect(order).toMatchObject({ id: 1, status: \"Pending\" }), or gather what you observed: yield* expect({ total, status }).toEqual({ total: Money.of(4.4), status: \"Pending\" }). A check inside a loop is the same: assert the whole array once. Several inputs: it.each(rows)(name, function* (row, { expect }) { ... }).";
+/** @internal */
+const refuseUnyielded = "✗ a check was written but never yielded, so it never ran. Yield it: yield* expect(actual).toEqual(expected).";
+/** @internal */
+const noCheckRefusal = "✗ this test yields no check, so it cannot fail. Yield one from the test's own expect: it(name, function* ({ expect }) { yield* expect(actual).toEqual(expected) }). An expect imported from vitest does not count.";
+/** @internal */
+const unprovidedText = "✗ the test needs a service that nothing provides. Write the test inside layer(Service.layer)((it) => { it(name, ...) }); every test gets its own fresh build.";
+/** @internal */
+const refuseAsyncBody = "✗ an async body runs outside the test runtime. Pass a generator: it(name, function* ({ expect }) { yield* expect(actual).toEqual(expected) }).";
+/** @internal */
+const refuseSyncBody = "✗ the body must be a generator that yields its checks: it(name, function* ({ expect }) { const x = yield* program; yield* expect(x).toEqual(expected) }).";
+/** @internal */
+const refuseEffectLane = "✗ it.effect is removed: the body is the generator itself, so the runner sees every step. it(name, function* ({ expect }) { const x = yield* program; yield* expect(x).toEqual(expected) }).";
+/** @internal */
+const refuseScopedLane = "✗ it.scoped is removed: the body is the generator itself, so the runner sees every step. it(name, function* ({ expect }) { const x = yield* program; yield* expect(x).toEqual(expected) }).";
+/** @internal */
+const refuseScopedLiveLane = "✗ it.scopedLive is removed: the body is the generator itself, so the runner sees every step. it(name, function* ({ expect }) { const x = yield* program; yield* expect(x).toEqual(expected) }).";
+/** @internal */
+const refuseHook = "✗ hooks share state between tests. Build what a test needs inside it; services come fresh per test from layer(Service.layer)((it) => { ... }).";
+/** @internal */
+const refuseRawExpect = "✗ an expect imported from vitest ran; take it from the test callback: it(name, function* ({ expect }) { ... })";
+/** @internal */
+const refuseRawIt = "✗ this test was registered with vitest's it; import it from @systemfsoftware/vitest";
+//#endregion
+//#region src/internal/guard.ts
+/**
+* The library brands both its checks and its tests, and this module closes the way around both brands.
+*
+* The `Asserted` brand only proves a test yielded a fork check. It cannot see a raw `vitest` `expect` beside
+* that check, and it cannot see a test the fork never registered. Both travel on the one shared
+* `chai.Assertion` prototype, measured on Vitest 5.0.1 and Chai 6.2.2:
+*
+* - raw `expect`, `expect.soft` and `expect.poll` all enter chai through `chai.expect`
+*   (`vitest/dist/chunks/index.m3L2HgmY.js:8005`, `:8035`, `:7514`);
+* - the task's own `ctx.expect` is `createExpect(context.task)` (`vitest/dist/chunks/index.m3L2HgmY.js:8513`)
+*   and enters through that same `chai.expect` (`:8005`);
+* - chai's `expect` is `new Assertion(val, message)` (`chai/index.js:3272`), and every `assert.*` method is
+*   `new Assertion(...)` on the same class (`chai/index.js:3367`, `:3394`).
+*
+* So this module wraps that prototype once, and every method, chainable method and property on it refuses
+* unless a check opened the window with {@link authorize} for the duration of its matcher call. Nothing
+* asynchronous may run inside that window, so a plain synchronous depth counter is enough; the counter is
+* nested-safe because chai's own matchers build further assertions inside the one call.
+*
+* The window, the install flag and the wrapper marks live on `globalThis` under `Symbol.for` keys rather than
+* in module scope. A worker can hold two copies of this file at once — the setup file resolves through Node's
+* conditions to `dist/guard.mjs` while the test graph resolves the fork's entry through the source condition
+* to `src/mod.ts` — and a window opened by one copy has to be the window the other copy reads. Module-scope
+* state made every legitimate check fail with the raw-expect refusal.
+*
+* The other half is {@link markTask}: the fork's `it` marks each task it registers, and the setup-file entry
+* (`@systemfsoftware/vitest/guard`) refuses a task that carries no mark. This setup-file hook is internal plumbing; the
+* user-facing hook refusal is the fork's own `beforeEach`.
+*
+* @since 4.0.0
+*/
+const isCallable = (value) => typeof value === "function";
+const isObject = (value) => typeof value === "object" && value !== null;
+const hasOwn = (value, key) => Object.hasOwn(value, key);
+const hasGuardFields = (value) => hasOwn(value, "depth") && hasOwn(value, "installed");
+const isGuardState = (value) => isObject(value) && hasGuardFields(value);
+const stateKey = Symbol.for("@systemfsoftware/vitest/guard");
+const wrappedKey = Symbol.for("@systemfsoftware/vitest/guard/wrapped");
+const createState = () => {
+	const created = {
+		depth: 0,
+		installed: false,
+		extendPatched: false
+	};
+	Reflect.set(globalThis, stateKey, created);
+	return created;
+};
+const stateOf = () => {
+	const existing = Reflect.get(globalThis, stateKey);
+	return isGuardState(existing) ? existing : createState();
+};
+const state = stateOf();
+const isWrapped = (value) => Reflect.get(value, wrappedKey) === true;
+const isUnwrapped = (value) => isCallable(value) && !isWrapped(value);
+const authorized = () => state.depth > 0;
+const refuse = () => {
+	throw refusalOf(refuseRawExpect);
+};
+/** @internal */
+const authorize = (run) => {
+	state.depth += 1;
+	try {
+		return run();
+	} finally {
+		state.depth -= 1;
+	}
+};
+/** @internal */
+const markTask = (task) => {
+	task.meta.effectVitestMarked = true;
+};
+/** @internal */
+const isMarked = (task) => task.meta.effectVitestMarked === true;
+const guardedCall = (run) => {
+	const guarded = function(...args) {
+		if (!authorized()) refuse();
+		return Reflect.apply(run, this, args);
+	};
+	Reflect.defineProperty(guarded, wrappedKey, { value: true });
+	return guarded;
+};
+const fieldOf = (descriptor, field) => Reflect.get(descriptor, field);
+const withValue = (descriptor) => {
+	const value = fieldOf(descriptor, "value");
+	return isUnwrapped(value) ? {
+		...descriptor,
+		value: guardedCall(value)
+	} : descriptor;
+};
+const withRead = (descriptor) => {
+	const read = fieldOf(descriptor, "get");
+	return isUnwrapped(read) ? {
+		...descriptor,
+		get: guardedCall(read)
+	} : descriptor;
+};
+const withWrite = (descriptor) => {
+	const write = fieldOf(descriptor, "set");
+	return isUnwrapped(write) ? {
+		...descriptor,
+		set: guardedCall(write)
+	} : descriptor;
+};
+const guardedDescriptor = (descriptor) => withWrite(withRead(withValue(descriptor)));
+const isWrappable = (descriptor) => descriptor?.configurable === true;
+const guardMember = (proto, name) => {
+	const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+	if (!isWrappable(descriptor)) return;
+	Object.defineProperty(proto, name, guardedDescriptor(descriptor));
+};
+const bookkeeping = [
+	"constructor",
+	"__methods",
+	"__flags",
+	"_obj"
+];
+/**
+* Every own member of the prototype, string- and symbol-keyed, except chai's bookkeeping fields. `Reflect.ownKeys`
+* rather than `Object.getOwnPropertyNames`, so a member chai hangs off a symbol is guarded too: measured on chai
+* 6.2.2, `Assertion.prototype` carries 104 string-keyed own members and no symbol-keyed ones, so the enumeration
+* is unchanged today and stays closed if chai adds one.
+*/
+const assertionMembers = (proto) => Reflect.ownKeys(proto).filter((name) => bookkeeping.includes(name) === false);
+const guardPrototype = () => {
+	const proto = chai.Assertion.prototype;
+	for (const name of assertionMembers(proto)) guardMember(proto, name);
+};
+const extendOf = () => Reflect.get(chai.expect, "extend");
+const wrapExtend = () => {
+	const extend = extendOf();
+	if (!isCallable(extend)) return;
+	state.extendPatched = true;
+	chai.util.addMethod(chai.expect, "extend", function(...args) {
+		const result = Reflect.apply(extend, this, args);
+		guardPrototype();
+		return result;
+	});
+};
+const patchExtend = () => {
+	if (state.extendPatched) return;
+	wrapExtend();
+};
+/** @internal */
+const installGuard = () => {
+	if (state.installed) return;
+	state.installed = true;
+	guardPrototype();
+	patchExtend();
+};
+//#endregion
+export { refuseScopedLiveLane as _, booleanRefusal as a, refusedText as b, negatedText as c, refuseAsyncBody as d, refuseEffectLane as f, refuseScopedLane as g, refuseRawIt as h, markTask as i, noCheckRefusal as l, refusePiecewise as m, installGuard as n, isRefusal as o, refuseHook as p, isMarked as r, neededText as s, authorize as t, refusalOf as u, refuseSyncBody as v, unprovidedText as x, refuseUnyielded as y };

package/dist/guard.d.ts

@@ -0,0 +1,2 @@
+
+export {}

package/dist/guard.mjs

@@ -0,0 +1,19 @@
+
+import { h as refuseRawIt, n as installGuard, r as isMarked, u as refusalOf } from "./guard-BocOhXt2.mjs";
+import { beforeEach } from "vitest";
+//#region src/guard.ts
+/**
+* The guard setup file, published as `@systemfsoftware/vitest/guard` and listed in the shared Vitest config's
+* `setupFiles`. It installs the prototype guard once per worker and refuses any task the fork's `it` did not
+* register, so neither a raw `vitest` `expect` nor a raw `vitest` `it` can sit beside a fork check (KTD8).
+*
+* Both halves are internal plumbing; the fork's own `beforeEach` refusal is the user-facing one.
+*
+* @since 4.0.0
+*/
+installGuard();
+beforeEach((context) => {
+	if (!isMarked(context.task)) throw refusalOf(refuseRawIt);
+});
+//#endregion
+export {};