@systemfsoftware/vitest 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @systemfsoftware/vitest
 
+## 0.2.0
+
+### Minor Changes
+
+- Tests take `expect` from the test callback and yield each check: `it(name, function* ({ expect }) { yield* expect(actual).toEqual(expected) })`. The package stops exporting `expect`, `assert` and the `utils` helpers. With its `guard` entry listed in `setupFiles`, an `expect` imported from Vitest, or a test registered through Vitest's own `it`, is refused. Also refused, each with its rewrite as the message: a second check on one observed state, an unyielded check, a body with no check, a non-generator body, `it.effect`/`it.scoped`/`it.scopedLive`, `beforeEach`/`afterEach`, and weak matchers such as `toHaveLength`, `toBeDefined`, snapshots, `expect.anything`, `expect.soft`/`expect.poll` and argument-less `toThrow`. Libraries that judge inside a test import `step`, `captureRunBinding` and the `Check`/`Expect`/`Asserted` types from the `integration` entry.
+
+- `@systemfsoftware/differential-spec` depends on and imports `@systemfsoftware/vitest` by its own name instead of through an `@effect/vitest` alias. `@systemfsoftware/oxlint-config-recommended` enables the test-discipline rule under its new id `vitest-from-systemfsoftware-vitest`. `@systemfsoftware/vitest` documentation examples import from `@systemfsoftware/vitest`.
+
+  The lawful runner is published under its own name, `@systemfsoftware/vitest`, starting at `0.1.0`, so peers declared as `^0.1.0` accept its patch releases.
+
+- A failing test now reports one failure record instead of a raw cause: the error with its message, the first source line outside the spec libraries, the steps that ran and the cell decisions each caused, and a rerun command for that one scenario. Every cause in the chain keeps all lines of its message. A replay value is printed only for a run a seed or a property chose. Each failure prints once; other errors in the same cause are logged. A failed `expect` points at the line that called it and a property failure at the line that declared it. A new `@systemfsoftware/vitest/failure` entry exports the renderer, the recorder, the cause summary (`summaryOf`) and the author call-site capture (`callSite`, `callFrameOutside`, `withRaisingFrame`) for libraries that raise their own failures.
+
+- Kernel runs are serialized. A run started while another is live now waits behind it, in arrival order, instead of failing: two runs never interleave, so a scenario never sees another run's decisions, and a suite whose cases drive the kernel can run its tests concurrently.
+
+  `@systemfsoftware/vitest` adds `captureRunBinding`, the running test's run binding. `bind(effect)` re-provides it to an effect a library runs on a runtime of its own — its own scheduler, a worker, a simulation kernel — so the checks inside it count as that test's assertions, report softly, and see the same `owned` regions.
+
+  `@systemfsoftware/effect-spec-runtime` runs a case that declares no live reason through that runner, and a case's annotations now reach the test's report.
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/{checks-DiuzHhQM.d.ts → checks-Cq9of-Lx.d.ts}

@@ -1,7 +1,111 @@
 
 import * as V from "vitest";
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
+import * as Tracer from "effect/Tracer";
 import * as Context from "effect/Context";
+//#region src/internal/failure-record.d.ts
+/** A value the renderer narrows rather than assumes. */
+type Opaque$1<A = unknown> = A;
+/**
+ * A value a recorded span attribute or a replay path carries. Structured values stay structured on the span
+ * (KTD2); the renderer decides the text.
+ *
+ * @internal
+ */
+type AttributeValue = string | number | boolean | null | ReadonlyArray<AttributeValue> | {
+  readonly [key: string]: AttributeValue;
+};
+/**
+ * The test a failure happened in, as Vitest knows it. `file` is the path the rerun command names, so a caller
+ * that holds an absolute path derives the repo-relative one before handing it over.
+ *
+ * @internal
+ */
+interface TestIdentity {
+  /**
+   * The npm package the test file belongs to, e.g. `@systemfsoftware/effect-readiness`. Empty when the run
+   * provided no name: the rerun command then drops its `pnpm --filter` prefix and runs from the package
+   * directory, which is not a breach (R6).
+   */
+  readonly package: string;
+  /** The test file, as the rerun command writes it. */
+  readonly file: string;
+  /** The scenario name the rerun command filters on with `-t`. */
+  readonly name: string;
+}
+/**
+ * The value a generator chose a run by: the kernel's seed and decision path, or a property counterexample's
+ * seed and path. A path without a seed is a replay value offered for a baseline run, which R6 refuses (KTD5).
+ *
+ * @internal
+ */
+interface ReplayValue {
+  /** The generator's seed, or `undefined` when only a path was recorded. */
+  readonly seed: number | undefined;
+  /** The decisions or inputs the generator chose, in order. */
+  readonly path: ReadonlyArray<AttributeValue>;
+}
+/**
+ * A contract rule a rendered record breaks; the runner refuses such a record (R10, KTD7).
+ *
+ * @internal
+ */
+type Breach = 'R1' | 'R2' | 'R6';
+/**
+ * What a rendered failure gives Vitest: the tag the error carries, the record text, and the rules it breaks.
+ *
+ * @internal
+ */
+interface FailureRecord {
+  /** The headline's failure tag, e.g. `StepError`; the runner sets it as the thrown error's `name`. */
+  readonly name: string;
+  /** The text Vitest prints as the failure's message. */
+  readonly record: string;
+  /** The contract rules the record breaks: `R1` empty headline, `R2` no location, `R6` replay or rerun. */
+  readonly breaches: ReadonlyArray<Breach>;
+}
+/**
+ * Everything one failure is rendered from: the failure, its run's spans, the test and the replay value.
+ *
+ * @internal
+ */
+interface FailureRecordInput<E = never> {
+  /** The failure itself: a `Cause`, or the value a program threw or failed with. */
+  readonly failure: Cause.Cause<E> | E;
+  /** Every span the failing run recorded, in creation order. */
+  readonly spans: ReadonlyArray<Tracer.NativeSpan>;
+  /** The test the run belonged to. */
+  readonly identity: TestIdentity;
+  /** The generator that chose this run, or `undefined` on a run no generator chose. */
+  readonly replay: ReplayValue | undefined;
+  /**
+   * The seed the kernel's scheduler chose. The kernel knows its own scheduler, so it hands the note over rather
+   * than the renderer guessing it; a run no scheduler chose renders no note (KTD5).
+   */
+  readonly schedule?: {
+    readonly seed: number;
+  } | undefined;
+  /**
+   * The workspace root the rendered paths are relativized against, provided by the shared config the same way the
+   * package name is. Omitted, paths print absolute.
+   */
+  readonly root?: string | undefined;
+}
+/** @internal */
+declare const summaryOf: (value: Opaque$1) => string;
+/**
+ * Renders the record Vitest prints for one spec failure, and the contract rules it breaks.
+ *
+ * Never throws: a `Cause` renders layer by layer, a thrown `Error` renders as one layer, and any other value
+ * renders as itself. The first location the record names is the raising frame — the first stack frame outside
+ * `node_modules` and outside the spec libraries' own `src/` and `dist/` — and when no layer has one, the
+ * innermost failed span's site stands in, or the innermost unfinished cell's decide site for a deadlock (KTD6).
+ *
+ * @internal
+ */
+declare const renderFailureRecord: <E>(input: FailureRecordInput<E>) => FailureRecord;
+//#endregion
 //#region src/internal/refusals.d.ts
 /** @internal */
 declare const refusedText: {
@@ -229,4 +333,4 @@ interface Checks {
   readonly expect: Expect;
 }
 //#endregion
-export { Expect as a, NoCheckRefusal as c, RefuseSyncBody as d, ScopedLaneRefusal as f, Checks as i, RefuseAsyncBody as l, UnprovidedRefusal as m, AssertedShape as n, EffectLaneRefusal as o, ScopedLiveLaneRefusal as p, Check as r, HookRefusal as s, Asserted as t, RefuseEffectBody as u };
+export { summaryOf as S, FailureRecord as _, Expect as a, TestIdentity as b, NoCheckRefusal as c, RefuseSyncBody as d, ScopedLaneRefusal as f, Breach as g, AttributeValue as h, Checks as i, RefuseAsyncBody as l, UnprovidedRefusal as m, AssertedShape as n, EffectLaneRefusal as o, ScopedLiveLaneRefusal as p, Check as r, HookRefusal as s, Asserted as t, RefuseEffectBody as u, FailureRecordInput as v, renderFailureRecord as x, ReplayValue as y };

package/dist/engine-YsoQ_9we.d.ts

@@ -0,0 +1,158 @@
+
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Schema$1 from "effect/Schema";
+import { Schema } from "effect";
+import * as Arbitrary from "effect/unstable/arbitrary/Arbitrary";
+//#endregion
+//#region src/internal/errors.schema.d.ts
+declare const NonBooleanVerdict_base: Schema.Class<NonBooleanVerdict, Schema.TaggedStruct<"NonBooleanVerdict", {
+  readonly detail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** @internal */
+declare class NonBooleanVerdict extends NonBooleanVerdict_base {
+  get message(): string;
+}
+//#endregion
+//#region src/internal/property/impostor.d.ts
+/**
+ * @internal The constant impostor of R12: a fake of the subject under test that
+ * returns the first output it ever produced, for every later call, whatever the
+ * input it was given.
+ *
+ * A property that still holds for the impostor does not constrain the subject.
+ * Whether that is fatal is a per-file question — a subject's impostor must be
+ * refuted by some property in its file — so this module builds the fake and
+ * collects the verdicts; the engine decides them once, when the file finishes
+ * (KTD10).
+ */
+/**
+ * A value the fork hands over without inspecting: an argument to the subject, or one of its outputs.
+ *
+ * @internal
+ */
+type Opaque<A = unknown> = A;
+/**
+ * A function under test: any argument, any output.
+ *
+ * @internal
+ */
+type SubjectFunction = (...values: ReadonlyArray<never>) => Opaque;
+/**
+ * A record of functions under test; every member is replaced by a constant.
+ *
+ * @internal
+ */
+type MemberRecord = {
+  readonly [key: string]: SubjectFunction;
+};
+/**
+ * The function under test, or a record of them.
+ *
+ * @internal
+ */
+type Subject = SubjectFunction | MemberRecord;
+declare namespace kinds_d_exports {
+  export { LawApi, LawKind, LawSubject, MetamorphicRelation, deterministicHolds, idempotentHolds, invariantHolds, metamorphicHolds, modelHolds, roundTripHolds, spreadValues };
+}
+/** @internal */
+type LawKind = 'model' | 'metamorphic' | 'roundTrip' | 'invariant' | 'idempotent' | 'deterministic';
+/**
+ * A subject of a law kind: a function of the generated values.
+ *
+ * @internal
+ */
+type LawSubject<G extends Gens, A> = (...values: ReadonlyArray<ElementValues<G>>) => A;
+/**
+ * A metamorphic relation: the input transform, and how the two outputs relate (structural equality by default).
+ *
+ * @internal
+ */
+interface MetamorphicRelation<G extends Gens, A> {
+  readonly transform: (...values: ReadonlyArray<ElementValues<G>>) => Values<G>;
+  readonly relate?: (original: A, transformed: A) => boolean;
+}
+/**
+ * The R13 law surface: four gated kinds and two declared exemptions.
+ *
+ * @internal
+ */
+interface LawApi {
+  readonly model: <const G extends Gens, A, N extends number, S extends LawSubject<G, A>>(name: string, spec: PropertySpec<G, S, N>, oracle: LawSubject<G, A>) => void;
+  readonly metamorphic: <const G extends Gens, A, N extends number, S extends LawSubject<G, A>>(name: string, spec: PropertySpec<G, S, N>, relation: MetamorphicRelation<G, A>) => void;
+  readonly roundTrip: <const G extends Gens, E, N extends number, S extends LawSubject<G, E>>(name: string, spec: PropertySpec<G, S, N>, decode: (encoded: E) => Values<G>) => void;
+  readonly invariant: <const G extends Gens, A, N extends number, S extends LawSubject<G, A>>(name: string, spec: PropertySpec<G, S, N>, holds: (output: A, ...values: ReadonlyArray<ElementValues<G>>) => boolean) => void;
+  readonly idempotent: <const G extends Gens, N extends number, S extends (value: ElementValues<G>) => ElementValues<G>>(name: string, spec: PropertySpec<G, S, N>) => void;
+  readonly deterministic: <const G extends Gens, A, N extends number, S extends LawSubject<G, A>>(name: string, spec: PropertySpec<G, S, N>) => void;
+}
+/**
+ * The generated values as the argument list a law subject is called with.
+ *
+ * @internal
+ */
+declare const spreadValues: <G extends Gens>(values: Values<G>) => ReadonlyArray<ElementValues<G>>;
+/** @internal */
+declare const modelHolds: <G extends Gens, A>(oracle: LawSubject<G, A>) => (subject: LawSubject<G, A>, values: Values<G>) => boolean;
+/** @internal */
+declare const metamorphicHolds: <G extends Gens, A>(relation: MetamorphicRelation<G, A>) => (subject: LawSubject<G, A>, values: Values<G>) => boolean;
+/** @internal */
+declare const roundTripHolds: <G extends Gens, E>(decode: (encoded: E) => Values<G>) => (subject: LawSubject<G, E>, values: Values<G>) => boolean;
+/** @internal */
+declare const invariantHolds: <G extends Gens, A>(holds: (output: A, ...values: ReadonlyArray<ElementValues<G>>) => boolean) => (subject: LawSubject<G, A>, values: Values<G>) => boolean;
+/** @internal */
+declare const idempotentHolds: <G extends Gens>() => (subject: (value: ElementValues<G>) => ElementValues<G>, values: Values<G>) => boolean;
+/** @internal */
+declare const deterministicHolds: <G extends Gens, A>() => (subject: LawSubject<G, A>, values: Values<G>) => boolean;
+declare namespace engine_d_exports {
+  export { ArbitraryInput, CoveragePredicate, ElementValues, Gens, PropApi, PropertyRuntime, PropertySpec, PropertySubject, Values, makeProperty };
+}
+/** @internal */
+type ArbitraryInput = Schema$1.Top | Arbitrary.Arbitrary<Schema$1.Top['Type']>;
+/** @internal */
+type Gens = ReadonlyArray<ArbitraryInput> | {
+  readonly [key: string]: ArbitraryInput;
+};
+type Generated<I> = I extends Schema$1.Schema<infer T> ? T : I extends Arbitrary.Arbitrary<infer A> ? A : never;
+/** @internal */
+type Values<G extends Gens> = { readonly [K in keyof G]: Generated<G[K]>; };
+/** @internal */
+type ElementValues<G extends Gens> = G extends ReadonlyArray<ArbitraryInput> ? Generated<G[number]> : never;
+/** @internal */
+type PropertySubject = Subject;
+/** @internal */
+type CoveragePredicate<G extends Gens> = (...values: ReadonlyArray<ElementValues<G>>) => boolean;
+type PropertyRuns<N extends number> = number extends N ? number : `${N}` extends `-${bigint}` ? never : `${N}` extends `${bigint}` ? (N extends 0 ? never : N) : never;
+/** @internal */
+interface PropertySpec<G extends Gens, S extends PropertySubject, N extends number> {
+  readonly of: G;
+  readonly subject: S;
+  /**
+   * The property's own run count. Omitted, the configured default applies; when the run provides none,
+   * the built-in default of 100 does.
+   */
+  readonly runs?: N & PropertyRuns<N>;
+  /** Labelled input predicates, each with the minimum share of runs it must see (R14). */
+  readonly cover?: Readonly<Record<string, readonly [CoveragePredicate<G>, number]>>;
+  /** The property's own check options, merged field by field over the provided and built-in defaults. */
+  readonly arbitrary?: Arbitrary.CheckOptions;
+}
+/** @internal */
+interface PropertyRuntime<R> {
+  /** Registers the property's program; the runtime runs it inside the test it registers, under that test's binding. */
+  readonly register: (name: string, program: () => Effect.Effect<void, Cause.Cause<NonBooleanVerdict>, never>) => void;
+  readonly provide: <A, E>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, never>;
+}
+/** @internal */
+interface PropApi<R> {
+  readonly prop: <const G extends Gens, S extends PropertySubject, N extends number>(name: string, spec: PropertySpec<G, S, N>, holds: (subject: S, values: Values<G>) => boolean) => void;
+  readonly effectProp: <const G extends Gens, S extends PropertySubject, N extends number, E>(name: string, spec: PropertySpec<G, S, N>, holds: (subject: S, values: Values<G>) => Effect.Effect<boolean, E, R>) => void;
+  readonly law: LawApi;
+}
+/**
+ * The property surface over one runtime: `prop`, `effectProp`, and the R13 law kinds routed through the gate.
+ *
+ * @internal
+ */
+declare const makeProperty: <R>(runtime: PropertyRuntime<R>) => PropApi<R>;
+//#endregion
+export { Values as a, kinds_d_exports as c, PropertySubject as i, __exportAll as l, Gens as n, engine_d_exports as o, PropertySpec as r, LawApi as s, ArbitraryInput as t };