@danieljvdm/dev-kit 0.11.3 → 0.12.0

package/skills/effect-ts/references/guide-testing.md

@@ -1,532 +0,0 @@
-# Testing Guide
-
-This guide covers `@effect/vitest`, deterministic execution, test Layers,
-property tests, protocol round trips, and test-service conventions.
-
-Key source files:
-
-- `packages/vitest/src/index.ts`
-- `packages/vitest/src/internal/internal.ts`
-- `packages/vitest/test/index.test.ts`
-- `packages/vitest/typetest/index.tst.ts`
-
-## Preferred Rule
-
-When testing Effect code with Vitest, prefer `@effect/vitest` over manually calling `Effect.runPromise`, `Effect.runSync`, or ad hoc runtime setup inside ordinary Vitest tests.
-
-Layer provisioning in tests should follow these rules:
-
-1. If multiple tests should share the same layered setup, use `layer(...)`.
-2. If a nested group needs extra dependencies, use `it.layer(...)`.
-3. If tests need isolated layer instances per test, use multiple separate `it.layer(...)` calls.
-4. Do not default to local `.pipe(Effect.provide(...))` inside test bodies.
-
-Use:
-
-- `it.effect` for Effect-based tests with test services
-- `it.live` for Effect-based tests that should use live services
-- `layer(...)` and `it.layer(...)` for shared layered test setup
-- `it.effect.prop` for Effect-based property tests
-
-Do not default to `.pipe(Effect.provide(SomeLayer))` inside test bodies when `layer(...)` or `it.layer(...)` expresses the setup more clearly.
-
-Keep one executable green suite. Do not land `.red.test.ts` suites, red-only
-scripts, or wall-clock sleeps. Use `TestClock` for time-driven behavior.
-
-Use `Effect.exit` when asserting expected failures, then assert the tagged error
-and its important payload fields. When a protocol boundary uses Schema, test
-its decode and encode round trip rather than bypassing the contract.
-
-Shared skill guidance should not copy exact package-version claims from one
-repository or require agents to reread external URLs unless the target
-repository explicitly owns that workflow.
-
-## Imports
-
-Preferred imports for Effect tests:
-
-```ts
-import { assert, describe, it, layer } from "@effect/vitest";
-import { Effect } from "effect";
-```
-
-`@effect/vitest` re-exports Vitest, so it is the normal entrypoint for test APIs in an Effect codebase.
-
-## Core Test Modes
-
-## `it.effect`
-
-Use `it.effect` for most Effect tests.
-
-It automatically:
-
-- runs the effect
-- scopes it correctly
-- provides the default test environment
-
-The default test environment includes:
-
-- `TestConsole`
-- `TestClock`
-
-This comes directly from the internal implementation.
-
-Example:
-
-```ts
-import { assert, it } from "@effect/vitest";
-import { Effect } from "effect";
-
-it.effect("loads a user", () =>
-  Effect.gen(function* () {
-    yield* Effect.void;
-    assert.isTrue(true);
-  }),
-);
-```
-
-Use `it.effect` when:
-
-- the test uses ordinary Effect code
-- the test benefits from `TestClock`
-- the test benefits from `TestConsole`
-- the test should run in a scoped Effect runtime
-
-## `it.live`
-
-Use `it.live` when the test should use live services instead of the default test environment.
-
-Example:
-
-```ts
-it.live("uses live services", () =>
-  Effect.gen(function* () {
-    yield* Effect.void;
-  }),
-);
-```
-
-Use `it.live` when:
-
-- you need the real `Clock`
-- the test should interact with live runtime services
-- you deliberately do not want the test environment overrides
-
-Rule of thumb:
-
-- default: `it.effect`
-- opt into `it.live` only when you actually need live behavior
-
-## Effect Test Structure
-
-Preferred pattern:
-
-```ts
-it.effect("does something", () =>
-  Effect.gen(function* () {
-    const value = yield* someEffect;
-    assert.strictEqual(value, 1);
-  }),
-);
-```
-
-Prefer `Effect.gen` inside `it.effect` and `it.live` for readability.
-
-Avoid:
-
-- `it("...", async () => ...)` for Effect programs
-- `Effect.runPromise(...)` inside plain Vitest tests
-- manual runtime setup for routine Effect tests
-
-## Assertions
-
-Use `assert` for Effect tests.
-
-The canonical source also uses `expect` in some tests, but for skill guidance prefer `assert` in Effect-based tests because it keeps tests more uniform and explicit inside Effect programs.
-
-Examples:
-
-```ts
-assert.isTrue(value === 1);
-assert.strictEqual(a + b, b + a);
-assert.include(text, substring);
-```
-
-## Test Context
-
-`it.effect` and `it.live` test functions can receive a Vitest `TestContext`.
-
-Example:
-
-```ts
-it.effect("uses context", (ctx) =>
-  Effect.gen(function* () {
-    ctx.onTestFailed(() => {
-      // cleanup or diagnostics
-    });
-  }),
-);
-```
-
-Use this when you need:
-
-- failure hooks
-- abort signals
-- ordinary Vitest test context integration
-
-## `each`, `skip`, `skipIf`, `runIf`, `only`, `fails`
-
-The Effect testers support the standard test variants:
-
-- `it.effect.each(...)`
-- `it.live.each(...)`
-- `it.effect.skip(...)`
-- `it.effect.skipIf(...)`
-- `it.effect.runIf(...)`
-- `it.effect.only(...)`
-- `it.live.fails(...)`
-
-Examples from the canonical tests show these are first-class parts of the API.
-
-Use them exactly as you would with Vitest, but return `Effect` from the test body.
-
-## Property Testing
-
-There are two different property-test entrypoints and they do not have identical behavior.
-
-## Top-level `it.prop`
-
-Use `it.prop` for non-Effect property tests.
-
-Example:
-
-```ts
-import { it } from "@effect/vitest";
-import { FastCheck } from "effect/testing";
-
-const realNumber = FastCheck.float({ noNaN: true, noDefaultInfinity: true });
-
-it.prop("symmetry", [realNumber, FastCheck.integer()], ([a, b]) => a + b === b + a);
-```
-
-Important limitation from the internal implementation:
-
-- top-level `it.prop` does not support `Schema` arbitraries yet
-- if you pass a `Schema`, it throws
-
-So use top-level `it.prop` only with explicit `FastCheck` arbitraries.
-
-## `it.effect.prop`
-
-Use `it.effect.prop` for property tests that return `Effect`.
-
-This is the more powerful property-testing mode for Effect code.
-
-Example:
-
-```ts
-import { assert, it } from "@effect/vitest";
-import { Effect } from "effect";
-import { FastCheck } from "effect/testing";
-
-const realNumber = FastCheck.float({ noNaN: true, noDefaultInfinity: true });
-
-it.effect.prop("symmetry", [realNumber, FastCheck.integer()], ([a, b]) =>
-  Effect.gen(function* () {
-    assert.strictEqual(a + b, b + a);
-  }),
-);
-```
-
-Unlike top-level `it.prop`, `it.effect.prop` does support `Schema` inputs by converting them with `Schema.toArbitrary`.
-
-So prefer `it.effect.prop` when:
-
-- the property test needs `Effect`
-- you want to use `Schema` values as arbitraries
-- the test needs Effect services or scope
-
-## `layer(...)`
-
-Use top-level `layer(...)` to share a `Layer` across a group of tests.
-
-Hard rule:
-
-- use `layer(...)` when tests should share one layered setup
-- do not use it when each test needs its own isolated layer instance
-
-This is one of the most important `@effect/vitest` features.
-
-Example:
-
-```ts
-import { describe, it, layer } from "@effect/vitest";
-import { Context, Effect, Layer } from "effect";
-
-class Foo extends Context.Service<Foo, string>()("Foo") {
-  static readonly layer = Layer.succeed(Foo)("foo");
-}
-
-describe("foo", () => {
-  layer(Foo.layer)((it) => {
-    it.effect("gets foo", () =>
-      Effect.gen(function* () {
-        const foo = yield* Foo;
-        return foo;
-      }),
-    );
-  });
-});
-```
-
-What it does internally:
-
-- builds the layer once for the test group
-- memoizes the built layer with a `MemoMap`
-- keeps the scope open for the group
-- closes the scope in `afterAll`
-
-This makes it the preferred way to share layer setup across related tests.
-
-This is also the preferred alternative to calling `Effect.provide(...)` inside each individual test body.
-
-## Honest Test Layers
-
-Make every test Layer's name match the behavior it provides:
-
-- Use `Layer.succeed` for a complete static implementation.
-- Add `layerTest` and a test-control service when reusable state, failure
-  injection, or observation belongs to a real authority seam.
-- Use `layerMemory` only when the in-memory implementation faithfully preserves
-  the service's observable contract.
-- Use a real local adapter when persistence, transactions, serialization, or
-  protocol behavior matters.
-- Keep narrow one-off fakes local to their tests.
-
-Exercise the same service interface as production callers. When a service and
-its reusable test-control service share state, back both with the same scoped
-object. Keep partial implementations local rather than advertising them as
-general test or in-memory Layers.
-
-## Anti-Pattern: Local `Effect.provide(...)` In Tests
-
-If multiple tests use the same layer, do not write tests like this:
-
-```ts
-it.effect("creates and lists todos", () =>
-  Effect.gen(function* () {
-    const service = yield* TodoService;
-    yield* service.create("write tests");
-    yield* service.create("ship feature");
-  }).pipe(Effect.provide(TodoService.inMemoryLayer)),
-);
-```
-
-Why this is the wrong pattern:
-
-- it repeats provisioning in every test
-- it hides the layered test setup inside each test body
-- it fights the `@effect/vitest` layer helpers
-- it makes shared setup and teardown less explicit
-- it bypasses the clearer grouped-layer style that the library is designed for
-
-Prefer:
-
-```ts
-describe("TodoService", () => {
-  layer(TodoService.inMemoryLayer)((it) => {
-    it.effect("creates and lists todos", () =>
-      Effect.gen(function* () {
-        const service = yield* TodoService;
-        yield* service.create("write tests");
-        yield* service.create("ship feature");
-      }),
-    );
-
-    it.effect("updates completion and deletes todos", () =>
-      Effect.gen(function* () {
-        const service = yield* TodoService;
-        const todo = yield* service.create("close issue");
-        yield* service.setCompleted(todo.id, true);
-        yield* service.remove(todo.id);
-      }),
-    );
-  });
-});
-```
-
-Rule:
-
-- if a test or group of tests depends on a layer, prefer `layer(...)`
-- if a nested group needs extra dependencies, prefer `it.layer(...)`
-- if tests need isolated layer instances per test, use multiple separate `it.layer(...)` calls
-- use local `Effect.provide(...)` in tests only for true one-off edge cases, not as the normal pattern
-
-This matches the general layer guidance: provisioning belongs at the boundary, and in `@effect/vitest` the test boundary should usually be expressed with `layer(...)` rather than ad hoc local provisioning.
-
-## `it.layer(...)`
-
-Use `it.layer(...)` inside an existing layered test group to add nested layer context.
-
-Hard rule:
-
-- use `it.layer(...)` when a specific test or nested test block should get its own isolated layered setup
-- if isolation matters, prefer multiple separate `it.layer(...)` calls over one shared `layer(...)` group
-
-Example:
-
-```ts
-layer(Foo.layer)((it) => {
-  it.layer(Bar.layer)("nested", (it) => {
-    it.effect("gets both", () =>
-      Effect.gen(function* () {
-        const foo = yield* Foo;
-        const bar = yield* Bar;
-        return [foo, bar];
-      }),
-    );
-  });
-});
-```
-
-Important behavior from the implementation:
-
-- nested `it.layer(...)` reuses the parent memo map
-- nested `it.layer(...)` does not accept `memoMap` or `excludeTestServices`
-- nested layering is meant to extend the current layered test environment, not redefine its runtime policy
-
-Use multiple `it.layer(...)` blocks when each test should get its own isolated layered setup instead of sharing one top-level `layer(...)` group.
-
-## `layer` Options
-
-The top-level `layer(...)` helper accepts:
-
-- `timeout`
-- `memoMap`
-- `excludeTestServices`
-
-### `excludeTestServices`
-
-By default, `layer(...)` merges your layer with the test environment (`TestClock` and `TestConsole`).
-
-Use `excludeTestServices: true` when you want your layer group to run without those test-service overrides.
-
-This is useful for tests that should keep live runtime behavior.
-
-### `memoMap`
-
-Use `memoMap` only when you have a specific reason to coordinate layer memoization manually across test setups.
-
-Most tests should let `@effect/vitest` manage it.
-
-## Scoped Resources In Tests
-
-`@effect/vitest` is designed to work correctly with scoped effects and layered resources.
-
-The canonical tests explicitly verify resource release through `afterAll`.
-
-Use this normally:
-
-- define scoped services in layers
-- use `layer(...)` to share them
-- let the helper own scope setup and teardown
-
-Avoid manually managing large scopes in test code unless the test specifically needs that control.
-
-## `flakyTest`
-
-Use `flakyTest` for tests that need bounded retrying.
-
-Repo behavior:
-
-- wraps the test in `Effect.scoped`
-- retries using a schedule
-- retries for up to a timeout window
-- converts final failure to defect with `Effect.orDie`
-
-Use this only for truly flaky integration-style conditions, not as a substitute for deterministic tests.
-
-## `makeMethods` And `describeWrapped`
-
-These exist for custom integration and wrapper scenarios.
-
-### `makeMethods`
-
-Use `makeMethods` when you need to extend or wrap a custom Vitest `it` instance while preserving Effect-aware helpers.
-
-### `describeWrapped`
-
-Use `describeWrapped` when you want a `describe` wrapper that hands you the augmented Effect-aware `it` methods directly.
-
-Most test code can just use imported `describe` and `it` from `@effect/vitest`.
-
-## Equality Testers
-
-`addEqualityTesters()` exists as part of the public API.
-
-Use it only when you have a concrete need to install equality testers for your Vitest environment.
-
-It is not needed for ordinary test structure.
-
-## Recommended Patterns
-
-### Pattern: normal Effect test
-
-```ts
-it.effect("does work", () =>
-  Effect.gen(function* () {
-    const value = yield* Effect.succeed(1);
-    assert.strictEqual(value, 1);
-  }),
-);
-```
-
-### Pattern: shared layer for a test group
-
-```ts
-layer(AppLayer)("app", (it) => {
-  it.effect("uses app services", () =>
-    Effect.gen(function* () {
-      yield* Effect.void;
-    }),
-  );
-});
-```
-
-### Pattern: property test with Effect
-
-```ts
-it.effect.prop("law", [FastCheck.integer()], ([n]) =>
-  Effect.gen(function* () {
-    assert.strictEqual(n + 0, n);
-  }),
-);
-```
-
-### Pattern: use `TestClock`
-
-```ts
-it.effect("uses TestClock", () =>
-  Effect.gen(function* () {
-    const fiber = yield* Effect.forkChild(Effect.sleep("1 second"));
-    yield* TestClock.adjust("1 second");
-    yield* Fiber.join(fiber);
-  }),
-);
-```
-
-## Anti-Patterns
-
-- using plain `it(...)` with `Effect.runPromise(...)` for normal Effect tests
-- using `it.live` by default when `it.effect` is sufficient
-- manually building and tearing down large layer graphs instead of using `layer(...)`
-- using top-level `it.prop` with `Schema` inputs
-- using `flakyTest` to hide deterministic failures
-- duplicating runtime setup instead of sharing a layer
-
-## Good Repo Examples To Study
-
-- `packages/vitest/test/index.test.ts`
-- `packages/vitest/src/index.ts`
-- `packages/vitest/src/internal/internal.ts`
-- `packages/vitest/typetest/index.tst.ts`

package/skills/effect-ts/references/guide-type-safety-and-boundaries.md

@@ -1,131 +0,0 @@
-# Effect Type Safety And Boundaries
-
-Use this when reviewing `unknown`, `any`, assertions, runtime shape checks,
-JSON or provider parsing, Promise rejection causes, thrown exceptions, and
-small helper functions around typed Effect code.
-
-## Contents
-
-- [Assign Boundary Ownership](#assign-boundary-ownership)
-- [Match Typed Values Directly](#match-typed-values-directly)
-- [Let Schema Own Runtime Shape](#let-schema-own-runtime-shape)
-- [Search Effect Before Adding Local Code](#search-effect-before-adding-local-code)
-- [Audit Assertions And Manual Narrowing](#audit-assertions-and-manual-narrowing)
-- [Keep Helpers Meaningful](#keep-helpers-meaningful)
-- [Preserve Typed Error Channels](#preserve-typed-error-channels)
-- [Completion Check](#completion-check)
-
-## Assign Boundary Ownership
-
-Identify who owns each value's type before inspecting it at runtime.
-
-- Reserve `unknown` for external input, foreign library output, and opaque
-  causes retained for diagnostics.
-- Decode external values with the owning Schema at their earliest application
-  boundary.
-- Pass decoded values and concrete error unions through internal services.
-- Expose public service methods as `Effect.Effect<A, DomainErrorUnion, R>`.
-- Keep an irreducible foreign cause in a `cause: Schema.Unknown` field inside a
-  concrete schema-backed error.
-
-Complete this step when every `unknown` has a named boundary owner.
-
-## Match Typed Values Directly
-
-Read the inferred value and error types before adding a runtime guard.
-
-- Match discriminated errors with their `_tag`, nested reason tags,
-  `Effect.catchTag`, or `Effect.catchTags`.
-- Access fields directly after the Effect error channel or Schema has already
-  established their type.
-- Use `instanceof` when runtime class identity is part of the owning API's
-  contract.
-- Inline a single-use boolean condition when it states the branch clearly.
-
-Extract a predicate when it provides reusable narrowing or owns a meaningful
-domain policy.
-
-## Let Schema Own Runtime Shape
-
-Choose the Schema adapter that matches the caller's control flow:
-
-| Intent                    | Adapter                             |
-| ------------------------- | ----------------------------------- |
-| Boolean type guard        | `Schema.is(Model)`                  |
-| Optional tolerant decode  | `Schema.decodeUnknownOption(Model)` |
-| Typed Effect failure      | `Schema.decodeUnknownEffect(Model)` |
-| JSON string decode        | `Schema.fromJsonString(Model)`      |
-| Any JSON-compatible value | `Schema.Json`                       |
-
-Define small schemas for provider responses, SDK payloads, persisted data, and
-other structured external values. Decode once in the adapter and return the
-schema-derived type.
-
-## Search Effect Before Adding Local Code
-
-Search the project's pinned Effect version and platform packages before
-creating a schema, codec, type guard, JSON type, or runtime helper. Check:
-
-- `Schema` for existing data models, codecs, guards, and transformations.
-- `Encoding` for base64, hex, and text encoding.
-- `FileSystem`, `Path`, `HttpClient`, `Clock`, `Random`, and other platform
-  services for runtime capabilities.
-
-Adopt the built-in value and type together when they model the same concept.
-For example, `Schema.Json` supplies both the recursive JSON schema and its
-`Schema.Json` type.
-
-## Audit Assertions And Manual Narrowing
-
-Inventory:
-
-- `as any`, `as unknown as`, branded casts, and non-null assertions.
-- Custom type predicates and generic helpers such as `isRecord`.
-- `typeof value === "object"`, property probes, `in`, `Array.isArray`, and
-  `JSON.parse` used to discover structured external data.
-
-Give each occurrence one disposition:
-
-1. Decode the boundary value with its Schema.
-2. Isolate a compiler or framework adapter assertion at the narrowest boundary
-   and document the contract it bridges.
-3. Remove narrowing already guaranteed by the inferred type.
-
-## Keep Helpers Meaningful
-
-Extract a helper when it owns domain policy, provides reusable type refinement,
-removes repeated non-trivial mechanics, or creates a named observability
-boundary with `Effect.fn`.
-
-Inline one-use property checks and tag comparisons. Apply the deletion test:
-if removing the helper leaves equally clear typed code, keep the code inline.
-
-## Preserve Typed Error Channels
-
-- Represent recoverable failures with schema-backed tagged errors.
-- Map `Effect.tryPromise` rejection causes to the concrete service error at the
-  Promise boundary.
-- Distinguish failures by caller action when recovery differs, such as
-  permission, download, save, and share errors.
-- Preserve the original foreign value as diagnostic context inside the tagged
-  error.
-- Use synchronous throws for framework-required hooks, impossible invariants,
-  defects, and thunks immediately captured by `Effect.try` or
-  `Effect.tryPromise`.
-- Scope `ThrowStatement` lint restrictions to Effect workflow and service
-  modules whose expected failures belong in the error channel. Give boundary
-  adapters, invariant utilities, tests, and captured thunks explicit scopes.
-
-## Completion Check
-
-Before completing a change, account for every modified `unknown`, `any`,
-assertion, type predicate, structural probe, JSON parser, Promise catch mapper,
-throw, and public Effect error type. Each occurrence should resolve to a typed
-internal value, a Schema-owned boundary, or a narrow documented adapter.
-
-Use these probes during an audit:
-
-- A typed error tag hidden behind a one-line predicate.
-- A provider payload inspected through `isRecord` and property probes.
-- A raw Promise rejection broadening a service error channel to `unknown`.
-- A custom recursive JSON schema or `JsonValue` type.