@shivaedev/test-story 0.0.0 → 0.1.0

package/package.json

@@ -1,11 +1,75 @@
 {
   "name": "@shivaedev/test-story",
-  "version": "0.0.0",
-  "description": "Placeholder. Story DSL for tests: domain traits, a staged seed, a story log and a settle loop.",
-  "license": "MIT",
+  "version": "0.1.0",
+  "description": "Tests that read like stories over the real engine: a story kit per engine with its own it, traits per feature, and a failure that prints the story, where it stopped and the engine's state",
+  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/test-story#readme",
+  "bugs": {
+    "url": "https://github.com/ShivaeDev/platform/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShivaeDev/platform.git",
     "directory": "packages/test-story"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#test/*": "./src/test-support/*",
+    "#*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    "./*.ts": {
+      "types": "./dist/*.d.ts",
+      "source": "./src/*.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./internal/*": null,
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/test-support",
+    "docs",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "@shivaedev/effect-test": "0.3.1"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-rc.112",
+    "@shivaedev/quality": "0.17.0",
+    "@types/node": "24.10.1",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "effect": "4.0.0-rc.112",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "vitest": "4.1.11"
+  },
+  "peerDependencies": {
+    "@effect/vitest": "4.0.0-rc.112",
+    "effect": "4.0.0-rc.112",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc6 --project tsconfig.build.json",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/genreTags.ts

@@ -0,0 +1,10 @@
+import { genreOf } from "#internal/genre.ts";
+
+export interface GenreTag {
+	readonly description: string;
+	readonly name: string;
+}
+
+export function genreTags(...kitNames: readonly string[]): GenreTag[] {
+	return kitNames.map((kitName) => genreOf(kitName).tag);
+}

package/src/internal/callSite.ts

@@ -0,0 +1,18 @@
+import { relative } from "node:path";
+
+const FRAMES = 50;
+
+// V8 formats a stack only when it is read, so a site costs little until a test fails.
+export function callSite(): Error {
+	const limit = Error.stackTraceLimit;
+	Error.stackTraceLimit = FRAMES;
+	const site = new Error("call site");
+	Error.stackTraceLimit = limit;
+	return site;
+}
+
+export function locate(stack: string | undefined, testFile: string): string | undefined {
+	const frame = stack?.split("\n").find((line) => line.includes(testFile));
+	const position = frame?.slice(frame.indexOf(testFile) + testFile.length).match(/^:(?<line>\d+):(?<column>\d+)/u)?.groups;
+	return position === undefined ? undefined : `${relative(process.cwd(), testFile)}:${position.line}:${position.column}`;
+}

package/src/internal/engineSnapshot.ts

@@ -0,0 +1,47 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import type { FailedTest } from "#internal/failureReport.ts";
+import type { Subject } from "#internal/narration.ts";
+import { describeValue, toJson } from "#internal/render.ts";
+import { WIDTH, wrap, wrapJson } from "#internal/wrap.ts";
+
+const INLINE_CHARACTERS = 2000;
+
+type Snapshot = { readonly value: unknown } | { readonly threw: unknown };
+
+function snapshot<TEngine>(subject: Subject<TEngine>): Snapshot {
+	try {
+		return { value: subject.inspect === undefined ? subject.engine : subject.inspect(subject.engine) };
+	} catch (threw) {
+		return { threw };
+	}
+}
+
+function slug(text: string): string {
+	return text
+		.toLowerCase()
+		.replaceAll(/[^a-z0-9.]+/gu, "-")
+		.slice(0, 80);
+}
+
+export function engineSnapshot<TEngine>(subject: Subject<TEngine>, test: FailedTest): string[] {
+	const heading = `The ${subject.name} when the test failed`;
+	const taken = snapshot(subject);
+	if ("threw" in taken) {
+		return wrap(`${heading} is unknown: its inspect hook threw ${describeValue(taken.threw)}`);
+	}
+	const json = toJson(taken.value);
+	if (json.length <= INLINE_CHARACTERS) {
+		return heading.length + 2 + json.length > WIDTH ? [`${heading}:`, ...wrapJson(json)] : [`${heading}: ${json}`];
+	}
+	const file = join(
+		process.cwd(),
+		"node_modules",
+		".cache",
+		"test-story",
+		`${slug(basename(test.file))}--${slug(test.name)}--${slug(subject.name)}.json`,
+	);
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, toJson(taken.value, 2));
+	return wrap(`${heading} is ${json.length} characters of JSON, too long to print here. Read it in ${relative(process.cwd(), file)}`);
+}

package/src/internal/errors.ts

@@ -0,0 +1,39 @@
+import { describeValue } from "#internal/render.ts";
+import { explained } from "#internal/wrap.ts";
+
+export function refusal(name: string, line: string, cause: unknown): Error {
+	return new Error(
+		explained(
+			`the trait "${line}" refused to set up the ${name}: ${describeValue(cause)}`,
+			`a trait throws when the ${name} it asks for cannot exist. Give the test traits that fit together, or fix the trait in the ${name} story kit if this ${name} should be possible.`,
+		),
+		{ cause },
+	);
+}
+
+export function broken(name: string, steps: number, reason: string): Error {
+	return new Error(
+		explained(
+			`the ${name} broke after ${steps} steps: ${reason}`,
+			`run.failed in the ${name} story kit reports a state the ${name} cannot recover from. The story printed with this failure shows the setup and steps that led here.`,
+		),
+	);
+}
+
+export function unfinished(name: string, steps: number, diagnosis: string | undefined): Error {
+	return new Error(
+		explained(
+			`the ${name} ran ${steps} steps and never reached what runUntil waits for${diagnosis === undefined ? "" : `: ${diagnosis}`}`,
+			`either the ${name} never gets there, so check the setup and the engine, or it needs more steps, so pass a larger maxSteps to runUntil.`,
+		),
+	);
+}
+
+export function cannotRun(name: string): Error {
+	return new Error(
+		explained(
+			`the ${name} story kit has no run hooks, so runUntil cannot step the ${name}`,
+			`give the ${name} story kit run: { maxSteps, step }, where step advances the ${name} by one step.`,
+		),
+	);
+}

package/src/internal/failureReport.ts

@@ -0,0 +1,54 @@
+import { relative } from "node:path";
+import { locate } from "#internal/callSite.ts";
+import { engineSnapshot } from "#internal/engineSnapshot.ts";
+import type { Narration, Subject } from "#internal/narration.ts";
+import { describeValue } from "#internal/render.ts";
+import { WIDTH, wrap } from "#internal/wrap.ts";
+
+export interface FailedTest {
+	readonly file: string;
+	readonly name: string;
+	readonly stack: string | undefined;
+}
+
+export function failureReport<TEngine>(narration: Narration, subject: Subject<TEngine>, test: FailedTest): string {
+	try {
+		return [...guide(subject.name), "", ...storyRows(narration, test), "", ...engineSnapshot(subject, test), "", rerun(test)].join("\n");
+	} catch (error) {
+		return `test-story could not print the story of this ${subject.name}: ${describeValue(error)}`;
+	}
+}
+
+function guide(name: string): string[] {
+	return [
+		"╭─ test-story: how to read the story below",
+		...wrap(
+			`"given" lines are the test's traits, the other lines were told by verbs and engine steps as they ran, and ✗ marks where the test stopped. The traits, verbs and steps live in the ${name} story kit that this test imports.`,
+			{ first: "│ ", rest: "│ " },
+		),
+		"╰─",
+	];
+}
+
+function storyRows(narration: Narration, test: FailedTest): string[] {
+	const rows = narration.lines.map(
+		(line, index) => `${narration.refused?.index === index ? "✗" : " "} ${index < narration.given ? "given" : "     "}  ${line}`,
+	);
+	if (narration.refused !== undefined) {
+		const where = locate(narration.sites[narration.refused.index]?.stack, test.file);
+		rows.splice(narration.refused.index + 1, 0, ...(where === undefined ? [] : [`         refused at ${where}`]));
+		return rows;
+	}
+	const where = locate(test.stack, test.file) ?? locate(narration.at?.stack, test.file);
+	return [
+		...rows,
+		`✗        the test failed ${rows.length === 0 ? "before the story told a line" : "after the line above"}`,
+		...(where === undefined ? [] : [`         at ${where}`]),
+	];
+}
+
+function rerun(test: FailedTest): string {
+	const run = `Rerun: vitest run ${relative(process.cwd(), test.file)}`;
+	const filter = `-t "${test.name.replaceAll(/[$()*+.?[\\\]^{|}]/gu, "\\$&")}"`;
+	return run.length + 1 + filter.length > WIDTH ? `${run} \\\n  ${filter}` : `${run} ${filter}`;
+}

package/src/internal/genre.ts

@@ -0,0 +1,14 @@
+import type { GenreTag } from "#genreTags.ts";
+
+export interface Genre {
+	readonly tag: GenreTag;
+	readonly title: string;
+}
+
+export function genreOf(kitName: string): Genre {
+	const words = kitName.trim().split(/\s+/u);
+	return {
+		tag: { description: `stories over a real ${words.join(" ")}`, name: [...words.map((word) => word.toLowerCase()), "story"].join("-") },
+		title: [...words, "story"].map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`).join(" "),
+	};
+}

package/src/internal/hooked.ts

@@ -0,0 +1,22 @@
+import { Effect } from "effect";
+
+export type AnyEffect = Effect.Effect<unknown, unknown, unknown>;
+
+export type Hook<TArguments extends readonly unknown[], TEffect extends AnyEffect, A> = (...input: TArguments) => Generator<TEffect, A, never> | A;
+
+export type ErrorOf<TEffect> = [TEffect] extends [never] ? never : [TEffect] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E : never;
+
+export type ServicesOf<TEffect> = [TEffect] extends [never] ? never : [TEffect] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R : never;
+
+function isGenerator<TEffect, A>(value: Generator<TEffect, A, never> | A): value is Generator<TEffect, A, never> {
+	return typeof value === "object" && value !== null && Symbol.iterator in value && "next" in value && typeof value.next === "function";
+}
+
+export function hooked<TEffect extends AnyEffect, A>(
+	call: () => Generator<TEffect, A, never> | A,
+): Effect.Effect<A, ErrorOf<TEffect>, ServicesOf<TEffect>> {
+	return Effect.suspend(() => {
+		const result = call();
+		return isGenerator(result) ? Effect.gen(() => result) : Effect.succeed(result);
+	});
+}

package/src/internal/narration.ts

@@ -0,0 +1,57 @@
+import type { TestContext } from "vitest";
+import { callSite } from "#internal/callSite.ts";
+import { failureReport } from "#internal/failureReport.ts";
+import { describeFailure } from "#internal/render.ts";
+
+export interface Refusal {
+	readonly cause: unknown;
+	readonly index: number;
+}
+
+export interface Narration {
+	at: Error | undefined;
+	given: number;
+	readonly lines: string[];
+	refused: Refusal | undefined;
+	readonly sites: Error[];
+	readonly tell: (line: string) => void;
+	readonly tellAt: (line: string, site: Error) => void;
+}
+
+export interface Subject<TEngine> {
+	readonly engine: TEngine;
+	readonly inspect: ((engine: TEngine) => unknown) | undefined;
+	readonly name: string;
+}
+
+export function narrate<TEngine>(subject: Subject<TEngine>, { onTestFailed }: Pick<TestContext, "onTestFailed">): Narration {
+	const narration: Narration = {
+		at: undefined,
+		given: 0,
+		lines: [],
+		refused: undefined,
+		sites: [],
+		tell: (line) => {
+			narration.tellAt(line, callSite());
+		},
+		tellAt: (line, site) => {
+			narration.lines.push(line);
+			narration.sites.push(site);
+			narration.at = site;
+		},
+	};
+	onTestFailed(({ task }) => {
+		const failure = task.result?.errors?.[0];
+		if (failure !== undefined) {
+			failure.message = `${failure.message === "" ? describeFailure(failure) : failure.message}\n\n${failureReport(narration, subject, { file: task.file.filepath, name: task.name, stack: failure.stack })}`;
+		}
+	});
+	return narration;
+}
+
+export function tellGiven(narration: Narration, given: readonly { readonly line: string; readonly site: Error }[]): void {
+	for (const part of given) {
+		narration.tellAt(part.line, part.site);
+	}
+	narration.given = given.length;
+}

package/src/internal/render.ts

@@ -0,0 +1,69 @@
+const OWN_ERROR_KEYS = new Set(["_tag", "cause", "message", "name", "stack"]);
+
+// Vitest serializes a failure's class into these keys.
+const SERIALIZED_KEYS = new Set(["constructor", "toString"]);
+
+export function describeValue(value: unknown): string {
+	if (typeof value === "string") {
+		return value;
+	}
+	if (value instanceof Error) {
+		return describeError(value);
+	}
+	return typeof value === "object" && value !== null ? toJson(value) : String(value);
+}
+
+function describeError(error: Error): string {
+	const tag = "_tag" in error && typeof error._tag === "string" ? error._tag : error.name;
+	return describeTagged(tag, error.message, Object.entries(error));
+}
+
+export function describeFailure(failure: { readonly _tag?: unknown; readonly message: string; readonly name?: string }): string {
+	const tag = typeof failure._tag === "string" ? failure._tag : (failure.name ?? "Error");
+	return describeTagged(
+		tag,
+		failure.message,
+		Object.entries(failure).filter(([key]) => !SERIALIZED_KEYS.has(key)),
+	);
+}
+
+function describeTagged(tag: string, message: string, entries: readonly (readonly [string, unknown])[]): string {
+	const fields = Object.fromEntries(entries.filter(([key]) => !OWN_ERROR_KEYS.has(key)));
+	const label = tag === "Error" ? "" : tag;
+	const detail = Object.keys(fields).length === 0 ? "" : toJson(fields);
+	if (message === "") {
+		return [label, detail].filter((part) => part !== "").join(" ") || "Error";
+	}
+	return [label === "" ? message : `${label}: ${message}`, detail].filter((part) => part !== "").join(" ");
+}
+
+export function toJson(value: unknown, indent?: number): string {
+	const seen = new WeakSet<object>();
+	const json = JSON.stringify(
+		value,
+		(_key, item: unknown) => {
+			if (typeof item === "bigint") {
+				return `${item}n`;
+			}
+			if (typeof item === "symbol") {
+				return item.toString();
+			}
+			if (item instanceof Error) {
+				return describeError(item);
+			}
+			if (typeof item !== "object" || item === null) {
+				return item;
+			}
+			if (seen.has(item)) {
+				return "[shown above]";
+			}
+			seen.add(item);
+			if (item instanceof Map) {
+				return Object.fromEntries([...item].map(([key, entry]: readonly [unknown, unknown]) => [describeValue(key), entry]));
+			}
+			return item instanceof Set ? [...item] : item;
+		},
+		indent,
+	);
+	return json ?? String(value);
+}

package/src/internal/runUntil.ts

@@ -0,0 +1,43 @@
+import { Effect } from "effect";
+import { broken, cannotRun, unfinished } from "#internal/errors.ts";
+import { type AnyEffect, type Hook, hooked } from "#internal/hooked.ts";
+import type { RunUntilOptions } from "#storyKit.ts";
+
+export interface LooseRunHooks<TEngine> {
+	readonly diagnose?: Hook<[engine: TEngine], AnyEffect, string>;
+	readonly failed?: Hook<[engine: TEngine], AnyEffect, string | undefined>;
+	readonly maxSteps: number;
+	readonly step: Hook<[engine: TEngine, tell: (line: string) => void], AnyEffect, void>;
+}
+
+export interface Running<TEngine> {
+	readonly engine: TEngine;
+	readonly name: string;
+	readonly run: LooseRunHooks<TEngine> | undefined;
+	readonly tell: (line: string) => void;
+}
+
+export const runUntil = Effect.fnUntraced(function* <TEngine>(
+	{ engine, name, run, tell }: Running<TEngine>,
+	until: Hook<[engine: TEngine], AnyEffect, boolean>,
+	options: RunUntilOptions | undefined,
+) {
+	if (run === undefined) {
+		return yield* Effect.die(cannotRun(name));
+	}
+	const { diagnose, failed, step } = run;
+	const maxSteps = options?.maxSteps ?? run.maxSteps;
+	for (let steps = 0; ; steps += 1) {
+		const reason = failed === undefined ? undefined : yield* hooked(() => failed(engine));
+		if (reason !== undefined) {
+			return yield* Effect.die(broken(name, steps, reason));
+		}
+		if (yield* hooked(() => until(engine))) {
+			return;
+		}
+		if (steps >= maxSteps) {
+			return yield* Effect.die(unfinished(name, steps, diagnose === undefined ? undefined : yield* hooked(() => diagnose(engine))));
+		}
+		yield* hooked(() => step(engine, tell));
+	}
+});

package/src/internal/seed.ts

@@ -0,0 +1,53 @@
+import { Cause, Effect } from "effect";
+import type { AnyTestLayer } from "@shivaedev/effect-test/any-test-layer.ts";
+import { refusal } from "#internal/errors.ts";
+import { type AnyEffect, type Hook, hooked } from "#internal/hooked.ts";
+import { type Narration, tellGiven } from "#internal/narration.ts";
+import type { LooseRunHooks } from "#internal/runUntil.ts";
+import type { Parts } from "#internal/traits.ts";
+import type { RunUntilOptions } from "#storyKit.ts";
+
+export type LooseTrait = Parts<string, (engine: unknown) => Effect.Effect<void, unknown, unknown>>;
+
+export interface LooseStory {
+	readonly engine: unknown;
+	readonly lines: readonly string[];
+	readonly runUntil: (until: Hook<[engine: unknown], AnyEffect, boolean>, options?: RunUntilOptions) => Effect.Effect<void, unknown, unknown>;
+	readonly tell: (line: string) => void;
+}
+
+export interface LooseDefinition {
+	readonly after?: Readonly<Partial<Record<string, Hook<[engine: unknown], AnyEffect, void>>>>;
+	readonly create: Hook<[], AnyEffect, unknown>;
+	readonly inspect?: (engine: unknown) => unknown;
+	readonly layer?: AnyTestLayer;
+	readonly name: string;
+	readonly run?: LooseRunHooks<unknown>;
+	readonly stages: readonly string[];
+	readonly verbs: (engine: unknown, story: LooseStory) => object;
+}
+
+export const seed = Effect.fnUntraced(function* (definition: LooseDefinition, engine: unknown, narration: Narration, given: readonly LooseTrait[]) {
+	const parts = given.flatMap((each) => each.parts);
+	tellGiven(narration, parts);
+	for (const stage of definition.stages) {
+		for (const [index, part] of parts.entries()) {
+			if (part.stage === stage) {
+				yield* Effect.suspend(() => part.apply(engine)).pipe(
+					Effect.catchCause((cause) => {
+						if (Cause.hasInterruptsOnly(cause)) {
+							return Effect.interrupt;
+						}
+						const thrown = Cause.squash(cause);
+						narration.refused = { cause: thrown, index };
+						return Effect.die(refusal(definition.name, part.line, thrown));
+					}),
+				);
+			}
+		}
+		const after = definition.after?.[stage];
+		if (after !== undefined) {
+			yield* hooked(() => after(engine));
+		}
+	}
+});

package/src/internal/start.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import type { TestContext } from "vitest";
+import { callSite } from "#internal/callSite.ts";
+import { hooked } from "#internal/hooked.ts";
+import { narrate } from "#internal/narration.ts";
+import { runUntil } from "#internal/runUntil.ts";
+import { type LooseDefinition, type LooseStory, type LooseTrait, seed } from "#internal/seed.ts";
+
+export const start = Effect.fnUntraced(function* (definition: LooseDefinition, given: readonly LooseTrait[], context: TestContext) {
+	const engine = yield* hooked(definition.create);
+	const narration = narrate({ engine, inspect: definition.inspect, name: definition.name }, context);
+	yield* seed(definition, engine, narration, given);
+	const story: LooseStory = {
+		engine,
+		lines: narration.lines,
+		runUntil: (until, options) => {
+			const site = callSite();
+			narration.at = site;
+			return runUntil({ engine, name: definition.name, run: definition.run, tell: (line) => narration.tellAt(line, site) }, until, options);
+		},
+		tell: narration.tell,
+	};
+	return { ...definition.verbs(engine, story), story };
+});

package/src/internal/storyIt.ts

@@ -0,0 +1,63 @@
+import type { TestContext } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+import type { EffectTest, EffectTestOptions } from "@shivaedev/effect-test/types.ts";
+import { makeEffectIt } from "@shivaedev/effect-test/vitest.ts";
+import { type Genre, genreOf } from "#internal/genre.ts";
+import { type AnyEffect, hooked } from "#internal/hooked.ts";
+import type { LooseDefinition, LooseTrait } from "#internal/seed.ts";
+import { start } from "#internal/start.ts";
+
+type LooseBody = (told: object, context: TestContext) => Generator<AnyEffect, unknown, never> | undefined;
+
+type LooseTest = (name: string, given: readonly LooseTrait[], body?: LooseBody, options?: number | EffectTestOptions) => void;
+
+export interface LooseIt extends LooseTest {
+	readonly fails: LooseTest;
+	readonly only: LooseTest;
+	readonly runIf: (condition: unknown) => LooseTest;
+	readonly skip: LooseTest;
+	readonly skipIf: (condition: unknown) => LooseTest;
+}
+
+function withTags(options: number | EffectTestOptions | undefined, tags: readonly string[]): EffectTestOptions {
+	if (typeof options === "number") {
+		return { tags: [...tags], timeout: options };
+	}
+	const own = options?.tags ?? [];
+	return { ...options, tags: [...tags, ...(typeof own === "string" ? [own] : own)] };
+}
+
+function storyOf(definition: LooseDefinition, given: readonly LooseTrait[], body: LooseBody | undefined) {
+	return function* story(_harness: unknown, context: TestContext) {
+		const told = yield* start(definition, given, context);
+		return yield* hooked(() => body?.(told, context));
+	};
+}
+
+// Vitest refuses a tag its config does not declare, so a genre the config leaves out names the test without tagging it.
+function declaring(definition: LooseDefinition, genre: Genre, declare: EffectTest<unknown, unknown>): LooseTest {
+	return (name, given, body, options) => {
+		const title = `${genre.title}: ${name}`;
+		const story = storyOf(definition, given, body);
+		try {
+			declare(title, story, withTags(options, [genre.tag.name]));
+		} catch (error) {
+			if (!(error instanceof Error && error.message.includes(`"${genre.tag.name}"`))) {
+				throw error;
+			}
+			declare(title, story, withTags(options, []));
+		}
+	};
+}
+
+export function storyIt(definition: LooseDefinition): LooseIt {
+	const genre = genreOf(definition.name);
+	const { effectApp } = makeEffectIt({ layer: definition.layer ?? Layer.empty, makeHarness: () => Effect.void });
+	return Object.assign(declaring(definition, genre, effectApp), {
+		fails: declaring(definition, genre, effectApp.fails),
+		only: declaring(definition, genre, effectApp.only),
+		runIf: (condition: unknown) => declaring(definition, genre, effectApp.runIf(condition)),
+		skip: declaring(definition, genre, effectApp.skip),
+		skipIf: (condition: unknown) => declaring(definition, genre, effectApp.skipIf(condition)),
+	});
+}

package/src/internal/traits.ts

@@ -0,0 +1,20 @@
+import { callSite } from "#internal/callSite.ts";
+
+export interface TraitPart<TStage extends string, TApply> {
+	readonly apply: TApply;
+	readonly line: string;
+	readonly site: Error;
+	readonly stage: TStage;
+}
+
+export interface Parts<TStage extends string, TApply> {
+	readonly parts: readonly TraitPart<TStage, TApply>[];
+}
+
+export function trait<TStage extends string, TApply>(stage: TStage, line: string, apply: TApply): Parts<TStage, TApply> {
+	return { parts: [{ apply, line, site: callSite(), stage }] };
+}
+
+export function traits<TStage extends string, TApply>(...given: readonly Parts<TStage, TApply>[]): Parts<TStage, TApply> {
+	return { parts: given.flatMap((each) => each.parts) };
+}