@doubleloop-io/oxlint-plugin-effect 0.1.0 → 0.1.2

package/docs/user-guide/rules/adapter-import-boundary.md

@@ -0,0 +1,27 @@
+---
+title: adapter-import-boundary
+group: Design and boundaries
+---
+
+**Intent**: domain code and other adapters do not import an adapter; only entry files choose it.
+
+```ts
+// ❌ no: in src/orders/place-order.ts
+import { GoogleCalendar } from "../calendar/google/GoogleCalendar.ts"
+
+// ✅ yes: depend on the port, main.ts provides GoogleCalendar.layer
+import { Calendar } from "../calendar/Calendar.ts"
+```
+
+**Trigger**: a relative import of a file in another directory that is an adapter: one of its `.ts` files (tests excluded) builds a `Layer` with `Layer.effect`, `succeed`, `sync`, `scoped`, `effectContext`, `unwrap`, `mock` and similar, or declares a v3 `Effect.Service`, which always carries its implementation. Composition alone (`mergeAll`, `provide`, `merge`) does not make an adapter.
+
+**Exemptions and blind spots**: entry files, where adapters are chosen, and test files, which compose the Layers they exercise. Non-relative imports (path aliases such as `@/calendar/google`) and directory imports through an `index.ts` (`"../google"`) slip through. On a layout other than one directory per adapter, check what it reports before trusting it. Infrastructure requirements in the port's `R` channel need types: see `leaking-requirements` (effecttsgo).
+
+**Why**: the adapter can be replaced without touching its consumers.
+
+**Options**:
+
+- `entryFiles`: shared setting, see [Shared settings](../shared-settings.md).
+- `testFiles`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none

package/docs/user-guide/rules/all-errors-handled-at-boundary.md

@@ -0,0 +1,30 @@
+---
+title: all-errors-handled-at-boundary
+group: Runtime and entry point
+---
+
+**Intent**: the entry point runs an Effect whose error channel is closed to `never`.
+
+```ts
+// ❌ no
+export const POST = (request: Request) => Effect.runPromise(createEvent(request))
+
+// ✅ yes: in an entry file
+export const POST = (request: Request) =>
+    Effect.runPromise(createEvent(request) satisfies Effect.Effect<Response, never>)
+
+// ✅ yes: a typed helper
+const runBoundary = (effect: Effect.Effect<Response, never, never>) => Effect.runPromise(effect)
+```
+
+**Trigger**: `Effect.runPromise`, `runSync`, `runFork` and `runCallback` whose argument is not `… satisfies Effect.Effect<A, never>`, a parameter declared with that type, or a program ending in `Effect.result`/`Effect.exit`, or the v3 `Effect.either` (`Effect.result(program)`, `program.pipe(…, Effect.result)`).
+
+**Exemptions and blind spots**: the `*Exit` variants, which return failures as values; `NodeRuntime.runMain`/`BunRuntime.runMain`, which log the Cause and exit with code 1, the right outcome for a process that cannot start; runners inside an `async` function that renders JSX itself, a Server Component, which hands failures to React rather than to an HTTP response; test files, where a rejected run fails the test with the error. The rule checks the shape; `tsc` gives the guarantee.
+
+**Why**: `Effect.runPromise` turns any error left over into a rejected promise, a generic 500. With `never`, a new untranslated error does not compile, and `R = never` forces all Layers to be provided.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none

package/docs/user-guide/rules/anti-slop-no-manual-effect-error-tag.md

@@ -0,0 +1,26 @@
+---
+title: anti-slop-no-manual-effect-error-tag
+group: Error channel
+---
+
+**Intent**: a catch handler does not discriminate errors by `_tag`; `catchTag` and `catchReason` do.
+
+```ts
+// ❌ no
+program.pipe(Effect.catch((error) => (error._tag === "NotFound" ? recover : Effect.fail(error))))
+
+// ✅ yes
+program.pipe(Effect.catchTag("NotFound", () => recover))
+```
+
+**Trigger**: an equality comparison between `_tag` (or `reason._tag`) and a string literal, or a `switch` on `_tag`, whose nearest enclosing function is a handler passed to `Effect.catch`, `catchAll` or `catchIf`. On `reason._tag` the message proposes `Effect.catchReason(s)`.
+
+**Exemptions and blind spots**: handlers of other combinators (`catchTag`, `catchCause`, `mapError`), and `_tag` checks in a function nested inside the handler. Outside these handlers the same checks belong to [`no-manual-discriminant-comparison`](no-manual-discriminant-comparison.md): the two never fire on the same node.
+
+**Why**: a hand-written dispatch keeps the caught errors in the type even when handled, and silently misses tags added later.
+
+**Options**: none
+
+**Fix**: none
+
+**Origin**: absorbed from [`dmmulroy/anti-slop`](https://github.com/dmmulroy/anti-slop), MIT-licensed: see [`LICENSE.anti-slop`](../../../LICENSE.anti-slop).

package/docs/user-guide/rules/anti-slop-no-service-constructor-imports.md

@@ -0,0 +1,32 @@
+---
+title: anti-slop-no-service-constructor-imports
+group: Services and Layers
+---
+
+**Intent**: runtime code obtains a service from its Layer, never by calling its `make…` constructor.
+
+```ts
+// ❌ no: in src/runtime.ts
+import { makeIssueService } from "./issue-service.ts"
+
+// ✅ yes
+import { IssueService } from "./issue-service.ts"
+
+Effect.gen(function* () {
+    const issues = yield* IssueService
+})
+```
+
+**Trigger**: a named import of `make` followed by an uppercase letter (`makeIssueService`, also when renamed) from a relative module.
+
+**Exemptions and blind spots**: test files, which build services from their constructors to inject fakes. Non-relative imports (packages, path aliases), namespace and default imports, and constructors with another prefix slip through. The same import can also fire [`adapter-import-boundary`](adapter-import-boundary.md).
+
+**Why**: calling the constructor wires its dependencies by hand, and its requirements stop propagating to the composition root.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none
+
+**Origin**: absorbed from [`dmmulroy/anti-slop`](https://github.com/dmmulroy/anti-slop), MIT-licensed: see [`LICENSE.anti-slop`](../../../LICENSE.anti-slop).

package/docs/user-guide/rules/anti-slop-prefer-effect-match.md

@@ -0,0 +1,30 @@
+---
+title: anti-slop-prefer-effect-match
+group: Code shape
+---
+
+**Intent**: a choice among several literal values of the same expression is a `Match`, not a chain of ternaries.
+
+```ts
+// ❌ no
+const label = kind === "a" ? "A" : kind === "b" ? "B" : "Other"
+
+// ✅ yes
+const label = Match.value(kind).pipe(
+    Match.when("a", () => "A"),
+    Match.when("b", () => "B"),
+    Match.orElse(() => "Other"),
+)
+```
+
+**Trigger**: a ternary chain of at least two levels where every condition compares the same expression, by source text, with a literal (`==`, `===`, `!=`, `!==`).
+
+**Exemptions and blind spots**: a single ternary, chains comparing different expressions, and the same expression written differently (`a.b` vs `a["b"]`). A chain returned by a match handler also fires [`no-nested-match`](no-nested-match.md): extract the handler first, since a `Match.value` left inside it fires `no-nested-match` again.
+
+**Why**: a ternary chain hides which value is the fallback and cannot be made exhaustive.
+
+**Options**: none
+
+**Fix**: none
+
+**Origin**: absorbed from [`dmmulroy/anti-slop`](https://github.com/dmmulroy/anti-slop), MIT-licensed: see [`LICENSE.anti-slop`](../../../LICENSE.anti-slop).

package/docs/user-guide/rules/exported-schema-identifier.md

@@ -0,0 +1,26 @@
+---
+title: exported-schema-identifier
+group: Schema
+---
+
+**Intent**: an exported schema carries an `identifier` equal to its name.
+
+```ts
+// ❌ no
+export const EventBusEvents = Schema.Union([Created, Deleted])
+
+// ✅ yes
+export const EventBusEvents = Schema.Union([Created, Deleted]).annotate({
+    identifier: "EventBusEvents",
+})
+```
+
+**Trigger**: `export const X = Schema.Struct(…)`, `Schema.Union(…)` or `Schema.Array(…)`, also followed by `.pipe(…)`, `.annotate(…)` or `.check(…)`, with no `identifier` in a `.annotate(…)` or `Schema.annotate(…)` of the chain (v3: `annotations`), or with a literal `identifier` other than `"X"`.
+
+**Exemptions and blind spots**: non-exported schemas (fragments reused through `.fields`), and `Schema.Class` and `Schema.TaggedError`, which carry the name already. A computed `identifier` is not compared. Other constructors (`Schema.TaggedStruct`, `Schema.Literals`, …), `export { X }` lists and chains through other methods slip through. An exported fragment reused only through `.fields` fires too, although the annotation does not reach the schemas that spread it: export the plain fields object instead (`export const BaseFields = { … }`).
+
+**Why**: without an `identifier`, decoding errors, JSON Schema and arbitraries describe the schema by its structure instead of its name.
+
+**Options**: none
+
+**Fix**: suggestion that corrects the `identifier`, or two that add it, `v3:` with `.annotations(…)` and `v4:` with `.annotate(…)`

package/docs/user-guide/rules/no-asymmetric-match-handlers.md

@@ -0,0 +1,30 @@
+---
+title: no-asymmetric-match-handlers
+group: Code shape
+---
+
+**Intent**: if one match handler delegates to a named function, the others do too.
+
+```ts
+// ❌ no
+Option.match(only, {
+    onNone: () => missingIn(sheet),
+    onSome: Effect.fn("onlyCandidate")(function* (name: string) { … }),
+})
+
+// ✅ yes
+Option.match(only, {
+    onNone: () => missingIn(sheet),
+    onSome: (name) => onlyCandidate(sheet, name),
+})
+```
+
+**Trigger**: on the same matches as [`no-nested-match`](no-nested-match.md), a handler with an inline body next to one that delegates. A handler delegates if it is a reference, a call, or a function returning only a call; it is inline if it has multiple statements, is a generator, or builds an `Effect.fn`/`Effect.gen`.
+
+**Exemptions and blind spots**: returned literals, templates, arrays and objects are values and count on neither side.
+
+**Why**: a branch saying _what_ next to one showing _how_ forces the reader to switch level halfway through the choice.
+
+**Options**: none
+
+**Fix**: none

package/docs/user-guide/rules/no-effect-promise.md

@@ -0,0 +1,26 @@
+---
+title: no-effect-promise
+group: Error channel
+---
+
+**Intent**: a promise that can reject is lifted with [`Effect.tryPromise`](try-object-form.md), not `Effect.promise`.
+
+```ts
+// ❌ no
+Effect.promise(() => client.connect())
+
+// ✅ yes
+Effect.tryPromise({ try: () => client.connect(), catch: toConnectionError })
+```
+
+**Trigger**: `Effect.promise` outside the release step of `acquireRelease`, `acquireUseRelease` and `addFinalizer`.
+
+**Exemptions and blind spots**: the release step, where a promise that cannot reject is the normal case. Test files, where a rejection during setup is a broken test and the defect fails it with the cause. Elsewhere, a promise that truly cannot reject must be suppressed by hand.
+
+**Why**: `Effect.promise` turns a rejection into a defect.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none

package/docs/user-guide/rules/no-effect-return-type.md

@@ -0,0 +1,29 @@
+---
+title: no-effect-return-type
+group: Code shape
+---
+
+**Intent**: `Effect`, `Stream` and `Layer` return types are inferred, not annotated, except on exported declarations.
+
+```ts
+// ❌ no
+(effect, name): Effect.Effect<RaceFillResult, never, Agent | SheetReader | SheetWriter> =>
+
+// ✅ yes
+(effect, name) =>
+
+// ✅ yes: an exported declaration keeps its annotation as a contract
+export const findPrice = (id: PriceId): Effect.Effect<Price, PriceNotFound> =>
+```
+
+**Trigger**: `Effect.Effect`, `Stream.Stream` or `Layer.Layer` in an annotated return type, even nested (`Option.Option<Effect.Effect<…>>`, a function returning an `Effect`).
+
+**Exemptions and blind spots**: module-level declarations with `export` (`export const`, `export function`, `export default`), unless `checkExported` is on; methods of an exported object, functions an exported function returns, and `export { f }` lists are still checked. Recursion, and returns of different shapes that need unifying (`Effect.succeed` and `Effect.fail`), recognized from the shape of the `return`s. An `import type { Effect }` used as `Effect<…>` slips through.
+
+**Why**: the error and requirement channels collect what comes from everything the function calls; an error or a service added deep down would change every caller's annotation. An exported signature is the module's contract, like a named type: there the annotation makes such a change visible where it is published. To check a returned object against a named type, annotate the callback that builds it (`Effect.map(CurrentSession, (session): OrganizationContext => ({ … }))`) or use `satisfies`.
+
+**Options**:
+
+- `checkExported`: default `false`. Also checks exported declarations.
+
+**Fix**: suggestion that removes the annotation

package/docs/user-guide/rules/no-inline-schema-codec.md

@@ -0,0 +1,26 @@
+---
+title: no-inline-schema-codec
+group: Schema
+---
+
+**Intent**: a decoder or encoder is a named module-level constant, not built and applied inline.
+
+```ts
+// ❌ no
+const toPayment = (raw: unknown) => Schema.decodeUnknownSync(PaymentResponse)(raw)
+
+// ✅ yes
+const decodePaymentResponse = Schema.decodeUnknownSync(PaymentResponse)
+
+const toPayment = (raw: unknown) => decodePaymentResponse(raw)
+```
+
+**Trigger**: an immediate application `Schema.decode*(X)(input)` or `Schema.encode*(X)(input)` (the `Effect`, `Exit`, `Option`, `Promise`, `Result` and `Sync` variants, `Unknown` included) inside a function, test callbacks included.
+
+**Exemptions and blind spots**: module scope, and the generator of `Layer.effect(T, Effect.gen(…))` or `Layer.effect(T)(Effect.gen(…))` (also `Layer.scoped`), which run once; functions nested in that generator, such as the service methods, are checked. Codecs built inside a function and applied later (`const decode = Schema.decodeUnknownEffect(X)`), codecs passed as callbacks (`Effect.flatMap(Schema.decodeUnknownEffect(X))`) and a Layer built through `.pipe(Layer.effect(T))` slip through. Whether the codec should be synchronous is not this rule's concern: see `schema-sync` (effecttsgo).
+
+**Why**: a named codec says what it decodes at the call site and is built once, instead of at every call.
+
+**Options**: none
+
+**Fix**: none

package/docs/user-guide/rules/no-inline-yield-star.md

@@ -0,0 +1,29 @@
+---
+title: no-inline-yield-star
+group: Code shape
+---
+
+**Intent**: a `yield*` result is bound to a `const` before being used.
+
+```ts
+// ❌ no
+function* () {
+    return yield* missingIn(yield* readSheet())
+}
+
+// ✅ yes
+function* () {
+    const sheet = yield* readSheet()
+    return yield* missingIn(sheet)
+}
+```
+
+**Trigger**: a `yield*` whose result is used inside a larger expression: argument, operand, member, property, template.
+
+**Exemptions and blind spots**: a `yield*` that is the whole value of a statement (`yield* x`, `return yield* x`, `if (yield* x)`, `for (… of yield* x)`), a declaration or an assignment. Also the whole branch of a ternary, or the right operand of `&&`/`||`/`??`, in one of those positions (`const a = cached ?? (yield* x)`): binding first would run the effect unconditionally. The autofix extracts every nested `yield*` into `const`s, innermost first, named after the argument's last identifier without a verb prefix (`readSheet()` → `sheet`); when that name is taken, prefixed by the object it is read from (`reader.rows` → `readerRows`), else numbered (`sheet2`). There is no autofix when moving the effect could change when or how often it runs: branches of a ternary or `&&`/`||`/`??` inside a larger expression, optional chaining, `while`/`for` conditions, statements without braces, another call evaluated before the `yield*`.
+
+**Why**: with several `yield*`s in one expression the order of effects can only be inferred from precedence. One `const` per effect makes the order the reading order and names the intermediate value.
+
+**Options**: none
+
+**Fix**: autofix

package/docs/user-guide/rules/no-manual-discriminant-comparison.md

@@ -0,0 +1,36 @@
+---
+title: no-manual-discriminant-comparison
+group: Tagged values
+---
+
+**Intent**: branching on a union's discriminant goes through an exhaustive match, never through comparisons or `switch`.
+
+```ts
+// ❌ no
+switch (event._tag) {
+    case "Created":
+        return onCreated(event)
+    case "Deleted":
+        return onDeleted(event)
+}
+
+// ✅ yes
+Match.value(event).pipe(Match.tagsExhaustive({ Created: onCreated, Deleted: onDeleted }))
+
+// ✅ yes, with `discriminants: ["_tag", "type"]`
+Match.value(payment).pipe(
+    Match.discriminatorsExhaustive("type")({ card: fromCard, transfer: fromTransfer }),
+)
+```
+
+**Trigger**: an equality comparison between a discriminant (also `["type"]`) and a string literal, or a `switch` on a discriminant. The discriminants are the names in `discriminants`.
+
+**Exemptions and blind spots**: comparisons against a variable rather than a literal. On `_tag`, the handlers covered by [`anti-slop-no-manual-effect-error-tag`](anti-slop-no-manual-effect-error-tag.md): the two never fire on the same node. Guard clauses such as `if (x.type === "a") return …` fire too; on `_tag` use `Predicate.isTagged`. A `_tag` compared with a variant of Effect's own types (`Success`/`Failure` of `Result` and `Exit`, `Left`/`Right`, `Some`/`None`) is reported with their refinement as the remedy, such as `Result.isFailure`: those types cannot gain a variant; a `switch` is reported as usual. An exhaustive ts-pattern match is an equally valid remedy. A name added to `discriminants` also fires on objects outside closed unions (DOM events, external payloads): the list is a choice of the codebase.
+
+**Why**: `Match.tagsExhaustive`, `Match.discriminatorsExhaustive` and `$match` fail to compile when a variant is added; a comparison or a `switch` does not.
+
+**Options**:
+
+- `discriminants`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none

package/docs/user-guide/rules/no-manual-discriminant-construction.md

@@ -0,0 +1,32 @@
+---
+title: no-manual-discriminant-construction
+group: Tagged values
+---
+
+**Intent**: a union's variant is built by its constructor, never as an object literal with the discriminant.
+
+```ts
+// ❌ no
+const error = { _tag: "NotFound", id }
+
+// ✅ yes
+const error = new NotFound({ id })
+
+// ❌ no, with `discriminants: ["_tag", "eventType"]`
+const event = { eventType: "PaymentStarted", id, payment }
+
+// ✅ yes
+const event = PaymentStartedEvent.make({ id, payment })
+```
+
+**Trigger**: an object literal with a discriminant property (also `"type"` or `["type"]`) whose value is a string literal. The discriminants are the names in `discriminants`.
+
+**Exemptions and blind spots**: values that are not literals (`"Ready" as const` included). Literals that are patterns or raw input, also nested: the arguments of `Match.when`, `Match.not`, of `.with(…)` on a ts-pattern `match(…)` chain, the expected value of an `expect(…)` matcher or `expect.*` helper, the input of `Schema.decode*(X)(…)`/`Schema.encode*(X)(…)`, the argument of `JSON.stringify`, and an argument whose parameter is annotated `unknown` in a function declared in the same file (a fake API's raw body). Transport payloads written as literals fire, as does raw data passed to an imported function or through a variable, and a name added to `discriminants` fires on objects outside closed unions: the list is a choice of the codebase. See `schema-struct-with-tag` (effecttsgo) for `Schema.Struct` with a `_tag` field.
+
+**Why**: a literal skips the constructor, so it carries none of the class's prototype, equality or validation, and drifts silently when the type changes.
+
+**Options**:
+
+- `discriminants`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none

package/docs/user-guide/rules/no-nested-match.md

@@ -0,0 +1,44 @@
+---
+title: no-nested-match
+group: Code shape
+---
+
+**Intent**: a match handler contains neither another match nor a ternary.
+
+```ts
+// ❌ no
+const run = (argv: ReadonlyArray<string>) =>
+    Result.match(parseArgs(argv), {
+        onFailure: usageError,
+        onSuccess: (command) =>
+            Option.match(command.only, { onNone: () => fillAll, onSome: fillOnly }),
+    })
+
+// ✅ yes, outside a generator: a named handler
+const fill = (command: CliCommand) =>
+    Option.match(command.only, { onNone: () => fillAll, onSome: fillOnly })
+
+const run = (argv: ReadonlyArray<string>) =>
+    Result.match(parseArgs(argv), { onFailure: usageError, onSuccess: fill })
+
+// ✅ yes, inside a generator: guard clauses
+const run = Effect.fn("run")(function* (argv: ReadonlyArray<string>) {
+    const parsed = parseArgs(argv)
+    if (Result.isFailure(parsed)) return yield* usageError(parsed.failure)
+
+    const { only } = parsed.success
+    if (Option.isNone(only)) return yield* fillAll
+
+    return yield* fillOnly(only.value)
+})
+```
+
+**Trigger**: a handler of `Option.match`, `Result.match`, `Exit.match`, `Either.match`, `$match` or `Match.valueTags` that is itself a data-last match (also `Match.type().pipe(…)` and `pipe(Match.type(), …)`), or that returns a match, a `Match.value(…).pipe(…)` or `pipe(Match.value(…), …)` chain or a ternary.
+
+**Exemptions and blind spots**: `if` inside handlers, and whatever they return from inside an `if` or another nested block; the handlers of an outer `Match.value`/`Match.type` chain; matches nested deeper than the returned value, or assigned to a variable before being returned.
+
+**Why**: two nested levels of choice hide which branch is the normal one.
+
+**Options**: none
+
+**Fix**: none

package/docs/user-guide/rules/no-parameterless-catch-all.md

@@ -0,0 +1,28 @@
+---
+title: no-parameterless-catch-all
+group: Error channel
+---
+
+**Intent**: errors are caught by tag; a fallback that ignores the error is spelled `orElseSucceed`/`orElse`, never a catch-all with an ignored parameter.
+
+```ts
+// ❌ no
+Effect.catch(() => Effect.succeed(fallback))
+
+// ✅ yes
+Effect.catchTag("AgentTimeout", () => Effect.succeed(skip))
+Effect.catchTag(["ParseError", "ReservedPortError"], () => Effect.succeed(3000))
+
+// ✅ yes: every failure truly means the same fallback
+Effect.orElseSucceed(() => fallback)
+```
+
+**Trigger**: `Effect.catch`, `catchAll`, `catchCause` and `catchEager` with a parameterless handler.
+
+**Exemptions and blind spots**: a catch-all that discriminates on `_tag` by hand: see [`anti-slop-no-manual-effect-error-tag`](anti-slop-no-manual-effect-error-tag.md), and `catch-all-to-map-error`, `catch-all-tag-dispatch-to-catch-tag` and `catch-to-ignore` (effecttsgo).
+
+**Why**: a catch-all that ignores its parameter also swallows the errors added later, which `catchTag` would leave visible in the type.
+
+**Options**: none
+
+**Fix**: none

package/docs/user-guide/rules/no-provide-on-definition.md

@@ -0,0 +1,27 @@
+---
+title: no-provide-on-definition
+group: Services and Layers
+---
+
+**Intent**: a program does not provide its own Layers; its caller does.
+
+```ts
+// ❌ no
+const printMissing = Effect.gen(function* () { … }).pipe(Effect.provide(missingLayer))
+
+// ✅ yes: the program stays unprovided, its caller provides
+const printMissing = Effect.gen(function* () { … })
+Missing: () => printMissing.pipe(Effect.provide(missingLayer)),
+```
+
+**Trigger**: `Effect.provide` applied to `Effect.gen(…)` or to `Effect.fn(…)(…)`, in all three forms: with `.pipe`, as an `Effect.fn` pipeable, data-first.
+
+**Exemptions and blind spots**: test files. A program passed directly to `Effect.run*`, also through `.pipe(…)` or data-first `Effect.*` combinators (`Effect.runPromise(Effect.gen(…).pipe(Effect.provide(layer), Effect.result))`): it is already being dispatched; through any other function it is still reported. A context captured in an enclosing generator with `const ctx = yield* Effect.context<R>()` (also followed by `.pipe(…)`) and handed back to a method of the Layer being built: the caller chose the adapters when it built the Layer. A context obtained through a helper (`yield* contextWithoutSpan()`) is still reported. `provide` on a named program is allowed; `strict-effect-provide` (effecttsgo) reports it too.
+
+**Why**: a program that provides its own Layers can no longer be wired to different adapters by its caller.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none

package/docs/user-guide/rules/no-throw-or-primitive-failure.md

@@ -0,0 +1,34 @@
+---
+title: no-throw-or-primitive-failure
+group: Error channel
+---
+
+**Intent**: an expected failure is a tagged error, never a thrown or primitive value.
+
+```ts
+// ❌ no
+Effect.gen(function* () {
+    if (tab === undefined) throw new Error("tab not found")
+})
+Effect.fail("tab not found")
+
+// ✅ yes
+export class SheetTabNotFoundError extends Schema.TaggedError<SheetTabNotFoundError>()(
+    "SheetTabNotFoundError",
+    { spreadsheetId: Schema.String, message: Schema.String },
+) {}
+
+Effect.fail(new SheetTabNotFoundError({ spreadsheetId, message: "tab not found" }))
+```
+
+**Trigger**: a `throw` directly inside a generator passed to `Effect.gen`/`Effect.fn`; `Effect.fail` with a literal or a template.
+
+**Exemptions and blind spots**: `Effect.fail` with a literal in test files, where a synthetic failure feeds code generic over the error; a `throw` in a test generator is still reported. A `throw` inside a nested callback. `Effect.fail(new Error(…))` and `class X extends Error`: see `global-error-in-effect-failure` and `extends-native-error` (effecttsgo).
+
+**Why**: the typed error channel discriminates only on tags. A `throw` in the generator becomes a defect, outside the error channel.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none

package/docs/user-guide/rules/no-transport-types-in-generator.md

@@ -0,0 +1,41 @@
+---
+title: no-transport-types-in-generator
+group: Design and boundaries
+---
+
+**Intent**: the generator returns a domain value; conversion to a transport type happens in the second argument of `Effect.fn`.
+
+```ts
+// ❌ no: an error branch inside the happy path
+function* (request: Request) {
+    const credential = yield* sessionCredential
+    if (credential === undefined) return Response.redirect(new URL("/login", origin), 303)
+    // …
+}
+
+// ✅ yes
+const createEvent = Effect.fn("events.create")(
+    function* (request: Request) {
+        const credential = yield* sessionCredential // fails with Unauthenticated
+        const submission = yield* form(request)
+        return yield* apiCreateEvent(credential, submission)
+    },
+    (effect, request) =>
+        effect.pipe(
+            Effect.map((created) => Response.redirect(eventUrl(request, created), 303)),
+            Effect.catchTags({ Unauthenticated: () => Effect.succeed(toLogin(request)) }),
+        ),
+)
+```
+
+**Trigger**: `new T(…)`, `T.method(…)` and `T(…)` inside an Effect generator, callbacks passed to `Effect.*` combinators included, when `T` is a transport type.
+
+**Exemptions and blind spots**: pipeables of `Effect.fn`, where the conversion must live. Functions the generator only defines, such as an HTTP handler it registers. `return yield* new Unauthenticated(…)` is a declared failure. An early `return` of a domain value that actually signals an error is indistinguishable from a success.
+
+**Why**: an early `return new Response(…)` on the happy path is an error branch disguised as success, and escapes exhaustive translation.
+
+**Options**:
+
+- `transportTypes`: default `["Response", "NextResponse"]`, replaced by the configured list. Add your own transport DTOs.
+
+**Fix**: none

package/docs/user-guide/rules/no-yielded-match.md

@@ -0,0 +1,35 @@
+---
+title: no-yielded-match
+group: Code shape
+---
+
+**Intent**: inside an Effect generator, return early on the empty or failed case instead of yielding a match.
+
+```ts
+// ❌ no
+const save = Effect.fn("save")(function* (id: PolicyId) {
+    const found = yield* findPolicy(id)
+    return yield* Option.match(found, {
+        onNone: () => register(id),
+        onSome: (policy) => update(policy),
+    })
+})
+
+// ✅ yes
+const save = Effect.fn("save")(function* (id: PolicyId) {
+    const found = yield* findPolicy(id)
+    if (Option.isNone(found)) return yield* register(id)
+
+    return yield* update(found.value)
+})
+```
+
+**Trigger**: `yield*` of `Option.match(x, {…})` or `Result.match(x, {…})` (v3: `Either.match`), or of a `x.pipe(…)`/`pipe(x, …)` ending in one of them, in the generator of `Effect.gen` or `Effect.fn`.
+
+**Exemptions and blind spots**: an `Option.match` with `onNone` → `Effect.fail(…)` and `onSome` → `Effect.succeed`: see `option-match-to-from-option` (effecttsgo). A handler that `no-nested-match` reports. Matches not yielded directly (assigned first, or inside `Effect.flatMap`) slip through.
+
+**Why**: the match splits the generator into two equal-weight branches; a guard clause leaves one main path of `yield*`.
+
+**Options**: none
+
+**Fix**: none

package/docs/user-guide/rules/prefer-effect-fn.md

@@ -0,0 +1,31 @@
+---
+title: prefer-effect-fn
+group: Effectful functions
+---
+
+**Intent**: an effectful function is `Effect.fn("name")`, and a named effect value has a span.
+
+```ts
+// ❌ no
+const outcomeFor = (name: string) => Effect.gen(function* () { … }).pipe(Effect.catch(toFailed))
+const refresh = Effect.gen(function* () { … })
+
+// ✅ yes: extra combinators as arguments, not .pipe
+const outcomeFor = Effect.fn("outcomeFor")(function* (name: string) { … }, Effect.catch(toFailed))
+const refresh = Effect.gen(function* () { … }).pipe(Effect.withSpan("refresh"))
+```
+
+**Trigger**:
+
+- a declared function, a variable or an object member that only returns `Effect.gen(…)`, even with `.pipe`;
+- a variable or an object member whose value is `Effect.gen(…)` without `Effect.withSpan` in its `.pipe`;
+- `Effect.fn(body)` without a name;
+- `.pipe` on `Effect.fn(…)(…)`.
+
+**Exemptions and blind spots**: `Effect.gen` inline as an argument (`Layer.effect(Tag, Effect.gen(…))`, `Stream.unwrap`, callbacks, `it.effect`). Recursive functions: see [`untraced-recursion`](untraced-recursion.md).
+
+**Why**: named stack traces and spans without wrapper functions. Combinators passed as arguments run inside the function's span and receive its arguments: `(effect, name) => effect.pipe(…)`.
+
+**Options**: none
+
+**Fix**: none