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

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`). 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

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

@@ -0,0 +1,30 @@
+---
+title: prefer-effect-vitest
+group: Runtime and entry point
+---
+
+**Intent**: tests hand their Effects to `@effect/vitest` instead of running them.
+
+```ts
+// ❌ no
+test("…", async () => {
+    await Effect.runPromise(authorize({ role: "Manager" }))
+})
+
+// ✅ yes: fakes as Layers
+import { effect } from "@effect/vitest"
+
+effect("…", () => authorize({ role: "Manager" }).pipe(Effect.provide(sheetWith(row))))
+```
+
+**Trigger**: the same references as [`run-only-in-runner`](run-only-in-runner.md), inside test files only.
+
+**Exemptions and blind spots**: projects where `@effect/vitest` cannot be found in a `node_modules` from the test file up, since the remedy is out of reach there; scattered runs in their tests go unreported. Every file outside `testFiles`, test helpers such as `src/testing/` included.
+
+**Why**: the test runtime brings `TestClock` and a scope per test, and fixtures provided as Layers replace services where the code reads them.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none

package/docs/user-guide/rules/provide-named-layer.md

@@ -0,0 +1,27 @@
+---
+title: provide-named-layer
+group: Services and Layers
+---
+
+**Intent**: `Effect.provide` receives a named Layer, never an inline composition.
+
+```ts
+// ❌ no
+printMissing.pipe(Effect.provide(Layer.mergeAll(FileRaceList.layer, GoogleSheet.readerLayer)))
+
+// ✅ yes: the Layer is named in the entry point, provided in the dispatch
+const missingLayer = Layer.mergeAll(FileRaceList.layer, GoogleSheet.readerLayer)
+Missing: () => printMissing.pipe(Effect.provide(missingLayer)),
+```
+
+**Trigger**: an `Effect.provide` argument composed inline: `Layer.*(…)`, a ternary, an `&&`/`||`, a `match`/`$match`.
+
+**Exemptions and blind spots**: test files, where different fakes per test are idiomatic. Where `provide` sits (outside the entry point) needs types: see `strict-effect-provide` (effecttsgo).
+
+**Why**: an inline Layer cannot be reused and hides which adapters a branch chooses. When branches need different Layers, there is one `provide` per branch, all in the dispatch: a single Layer with every service would build adapters the command does not use.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none

package/docs/user-guide/rules/redacted-secret-names.md

@@ -0,0 +1,31 @@
+---
+title: redacted-secret-names
+group: Config and secrets
+---
+
+**Intent**: a secret read from config or declared in a schema is `Redacted`.
+
+```ts
+// ❌ no
+serviceAccount: Config.schema(NonBlank, "GOOGLE_SERVICE_ACCOUNT_JSON")
+const Session = Schema.Struct({ userId: UserId, accessToken: Schema.String })
+
+// ✅ yes
+serviceAccount: Config.schema(Schema.Redacted(NonBlank), "GOOGLE_SERVICE_ACCOUNT_JSON")
+const Session = Schema.Struct({ userId: UserId, accessToken: Schema.Redacted(Schema.String) })
+```
+
+**Trigger**:
+
+- a literal name read with `Config.*` that ends with `KEY`, `SECRET`, `TOKEN`, `PASSWORD`, `CREDENTIAL`, `CREDENTIALS` or `_JSON` (service account keys often travel as inline JSON), when it does not go through `Config.Redacted`, the v3 `Config.redacted` (also wrapping a config, `Config.redacted(Config.string(name))`), or `Config.schema(Schema.Redacted…(…), name)`;
+- a field of `Schema.Struct({…})` or `Schema.Class<X>("X")({…})` whose name is a `secretFields` entry or ends with it capitalized (`password` matches `dbPassword`), declared with a `Schema.*` constant such as `Schema.String`, also through `.pipe(…)`, `.check(…)`, `.annotate(…)`/`.annotations(…)` or `Schema.optional`/`optionalKey`/`optionalWith`/`NullOr`/`UndefinedOr`/`NullishOr`, with no `Schema.Redacted…` along the way.
+
+**Exemptions and blind spots**: a naming heuristic: secrets with other names slip through, non-secrets with these names must be suppressed. Fields declared with a named schema (`accessToken: AccessToken`) are not inspected; other constructors (`Schema.TaggedClass`, `Schema.TaggedStruct`, …) are not seen. `process.env` read outside `Config`: see `process-env` and `process-env-in-effect` (effecttsgo).
+
+**Why**: a `Redacted` value does not end up in logs or `toString`.
+
+**Options**:
+
+- `secretFields`: default `["password", "secret", "apiKey", "accessToken", "refreshToken", "idToken"]` (no generic `token`), replaced by the configured list. `Config` names are fixed.
+
+**Fix**: none

package/docs/user-guide/rules/run-only-in-runner.md

@@ -0,0 +1,32 @@
+---
+title: run-only-in-runner
+group: Runtime and entry point
+---
+
+**Intent**: Effects run only in the program's runner, the entry point.
+
+```ts
+// ❌ no
+export const check = () => Effect.runPromise(pingDb(url))
+
+// ✅ yes: in main.ts
+NodeRuntime.runMain(
+    run(process.argv.slice(2)).pipe(Effect.provide(NodeServices.layer)) satisfies Effect.Effect<
+        void,
+        never
+    >,
+)
+```
+
+**Trigger**: every reference, not just calls, to `Effect.run*`, `NodeRuntime.runMain`, `BunRuntime.runMain` and `ManagedRuntime.make` outside entry files.
+
+**Exemptions and blind spots**: test files, checked by [`prefer-effect-vitest`](prefer-effect-vitest.md) instead.
+
+**Why**: logger, Layers and defect handling are configured in one place.
+
+**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/service-built-with-of.md

@@ -0,0 +1,36 @@
+---
+title: service-built-with-of
+group: Services and Layers
+---
+
+**Intent**: the service a Layer provides is built with `Tag.of({…})`, not a bare object literal.
+
+```ts
+// ❌ no
+export const RepoLive = Layer.effect(
+    Repo,
+    Effect.gen(function* () {
+        const db = yield* Database
+        return { find: (id: RepoId) => db.get(id) }
+    }),
+)
+
+// ✅ yes
+export const RepoLive = Layer.effect(
+    Repo,
+    Effect.gen(function* () {
+        const db = yield* Database
+        return Repo.of({ find: (id: RepoId) => db.get(id) })
+    }),
+)
+```
+
+**Trigger**: an object literal passed as the value of `Layer.succeed(T, {…})`, returned by the function of `Layer.sync(T, () => ({…}))`, or returned by a top-level `return {…}` of the generator of `Layer.effect(T, Effect.gen(…))` or `Layer.scoped`; the curried `Layer.succeed(T)(…)` forms too.
+
+**Exemptions and blind spots**: a named factory (`Layer.sync(Repo, makeRepo)`) and a variable (`Layer.succeed(Repo, repo)`) are not inspected; `return` inside an `if` or a nested block, `Effect.gen(…).pipe(Layer.effect(T))` and generators other than `Effect.gen` slip through.
+
+**Why**: `T.of` names the service the object implements and keeps it checked against the shape if the literal moves out of the Layer; one form for every Layer.
+
+**Options**: none
+
+**Fix**: suggestion that wraps the literal in `T.of(…)`