@doubleloop-io/oxlint-plugin-effect 0.1.0-rc.2 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# @doubleloop-io/oxlint-plugin-effect
+
+## 0.1.1
+
+### Patch Changes
+
+- [`2c67281`](https://github.com/doubleloop-io/oxlint-plugin-effect/commit/2c672814db1d169752d04295374001b935b785f5) Thanks [@iacoware](https://github.com/iacoware)! - The documentation has a website, now the package homepage: https://doubleloop-io.github.io/oxlint-plugin-effect/
+
+    - The rule catalog moves from `RULES.md`, no longer in the package, to one file per rule in `docs/user-guide/rules/`; the guide ships in the package.
+    - The README becomes the essential guide and links to the website.
+    - New Troubleshooting page.
+    - Improve rules documentation.
+
+## 0.1.0
+
+First stable release.
+
+- 30 rules for Effect code, grouped by topic in [`docs/user-guide/rules.md`](docs/user-guide/rules.md): error channel, tagged values, services and Layers, runtime and entry point, design and boundaries, effectful functions, code shape, Schema, config and secrets. Three are absorbed from [`dmmulroy/anti-slop`](https://github.com/dmmulroy/anti-slop).
+- An `all` preset that enables every rule at `warn`, for `oxlint.config.ts` and `.oxlintrc.json`.
+- Shared settings under `settings["dl-effect"]`: `entryFiles`, `testFiles`, `discriminants`.
+- Written for Effect 4; rules also recognize the Effect 3 name of the same API.
+- Requires Node `^22.20.0 || >=24.8.0` and oxlint `^1.82.0`.

package/README.md

@@ -2,9 +2,9 @@
 
 An oxlint plugin that enforces a catalog of patterns for Effect 4 code.
 
-The rules are written and tested against Effect 4. Where an Effect 3 API has the same intent, the rules recognize its v3 name too: each rule's Trigger in [`RULES.md`](RULES.md) names them.
+The rules are written and tested against Effect 4. Where an Effect 3 API has the same intent, the rules recognize its v3 name too: each rule's Trigger names them. The [Rules overview](https://doubleloop-io.github.io/oxlint-plugin-effect/rules-overview/) lists every rule.
 
-It complements the type-aware rules of [`@effect/tsgo`](#alongside-effecttsgo): it does not need them, and it checks what they do not.
+It complements the type-aware rules of [`@effect/tsgo`](https://doubleloop-io.github.io/oxlint-plugin-effect/alongside-effect-tsgo/): it does not need them, and it checks what they do not.
 
 ## Installation
 
@@ -12,9 +12,9 @@ It complements the type-aware rules of [`@effect/tsgo`](#alongside-effecttsgo):
 pnpm add -D @doubleloop-io/oxlint-plugin-effect oxlint
 ```
 
-Requires Node `^22.20.0 || >=24.8.0` and oxlint `^1.82.0`.
+Requires Node `^22.20.0 || >=24.8.0` and oxlint `^1.82.0`. What a release may change and which oxlint versions are supported: [Versioning](https://doubleloop-io.github.io/oxlint-plugin-effect/versioning/).
 
-## Configuration
+## Usage
 
 Extend the `all` preset. Prefer `oxlint.config.ts`, where `extends` takes config objects and the preset is imported by package name:
 
@@ -33,203 +33,20 @@ With `.oxlintrc.json`, `extends` takes file paths only, so the preset is reached
 }
 ```
 
-`all` enables every rule at `warn`, so adopting it never breaks a build: look at the warnings first, then raise to `error` the rules you want to enforce. A `recommended` preset with reasoned severities will come from measurements on real codebases.
+`all` enables every rule at `warn`, so adopting it never breaks a build: look at the warnings first, then raise to `error` the rules you want to enforce.
 
-To pick rules without the preset, load the plugin by package name and list the rules:
+**Set `entryFiles` before reading the warnings** on a layout that is not a Node CLI, such as Next.js or a monorepo. Its default, `**/main.ts`, `**/cli.ts`, `**/bin/**`, decides which files may run Effects and import adapters, so on another layout it turns correct code into warnings. How to set it: [Shared settings](https://doubleloop-io.github.io/oxlint-plugin-effect/shared-settings/#setting-a-value).
 
-```json
-{
-    "jsPlugins": ["@doubleloop-io/oxlint-plugin-effect"],
-    "rules": {
-        "dl-effect/no-effect-promise": "error",
-        "dl-effect/try-object-form": "error"
-    }
-}
-```
-
-### Configuration options
-
-Three settings describe your project, not a rule, so they are declared once under `settings["dl-effect"]` and every rule that uses them reads them from there. Their defaults fit a Node CLI; on another layout (Next.js, a monorepo) set them before reading the warnings.
-
-- `entryFiles`: the files allowed to run Effects and import adapters. Default `**/main.ts`, `**/cli.ts`, `**/bin/**`.
-- `testFiles`: the test files, exempt from the rules that tests legitimately break and the only files `prefer-effect-vitest` checks. Default `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `**/test/**`, `**/tests/**`.
-- `discriminants`: the fields that discriminate a closed union. Default `_tag`; add the ones your unions use, such as `type` or `kind`.
-
-The rules that use each one are listed in [Shared settings](RULES.md#shared-settings). Set one only where its default does not fit: it **replaces** the default instead of extending it. An unknown key or a value that is not an array of strings stops the lint with an error, so a typo is never silently ignored.
-
-```ts
-import dlEffectAll from "@doubleloop-io/oxlint-plugin-effect/presets/all"
-import { defineConfig } from "oxlint"
-
-export default defineConfig({
-    extends: [dlEffectAll],
-    settings: {
-        "dl-effect": { entryFiles: ["apps/web/src/app/**/route.ts", "apps/web/src/runtime.ts"] },
-    },
-})
-```
-
-```json
-{
-    "extends": ["./node_modules/@doubleloop-io/oxlint-plugin-effect/dist/presets/all.json"],
-    "settings": {
-        "dl-effect": { "entryFiles": ["apps/web/src/app/**/route.ts", "apps/web/src/runtime.ts"] }
-    }
-}
-```
-
-The package exports the defaults as `defaultEntryFiles`, `defaultTestFiles` and `defaultDiscriminants`: spread them to extend a default (`testFiles: [...defaultTestFiles, "e2e/**"]`).
-
-Settings belong to the config that lints: oxlint does not inherit them from a preset in `extends`, and rejects them in `overrides`. For a value that differs by group of files, use `overrides` on the rules instead.
-
-The other options and every default are in [Default configuration](#default-configuration).
-
-### Alongside `@effect/tsgo`
-
-[`@effect/tsgo`](https://github.com/Effect-TS/tsgo) is the official Effect language service on top of the TypeScript Go compiler; its `effecttsgo` oxlint presets add more than 100 type-aware rules. This plugin does not need it, and its rules target what those presets do not check, so the two complement each other. To use both, follow its [Oxlint Setup guide](https://github.com/Effect-TS/tsgo/blob/main/docs/README.md) and put its preset in `extends` **before** `all`:
-
-```ts
-import dlEffectAll from "@doubleloop-io/oxlint-plugin-effect/presets/all"
-import { recommended as effectTsgoRecommended } from "@effect/tsgo/oxlint-presets"
-import { defineConfig } from "oxlint"
-
-export default defineConfig({ extends: [effectTsgoRecommended, dlEffectAll] })
-```
-
-```json
-{
-    "extends": [
-        "./node_modules/@effect/tsgo/oxlint-presets/recommended.json",
-        "./node_modules/@doubleloop-io/oxlint-plugin-effect/dist/presets/all.json"
-    ]
-}
-```
-
-## Rules
-
-What each rule reports and why is in [`RULES.md`](RULES.md).
-
-| Topic                | Rules                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Error channel        | [`no-throw-or-primitive-failure`](RULES.md#no-throw-or-primitive-failure), [`try-object-form`](RULES.md#try-object-form), [`no-effect-promise`](RULES.md#no-effect-promise), [`no-parameterless-catch-all`](RULES.md#no-parameterless-catch-all), [`split-success-path-from-error-handling`](RULES.md#split-success-path-from-error-handling), [`anti-slop-no-manual-effect-error-tag`](RULES.md#anti-slop-no-manual-effect-error-tag) |
-| Tagged values        | [`no-manual-discriminant-comparison`](RULES.md#no-manual-discriminant-comparison), [`no-manual-discriminant-construction`](RULES.md#no-manual-discriminant-construction)                                                                                                                                                                                                                                                               |
-| Services & Layers    | [`service-port-shape-only`](RULES.md#service-port-shape-only), [`service-key-matches-name`](RULES.md#service-key-matches-name), [`service-built-with-of`](RULES.md#service-built-with-of), [`provide-named-layer`](RULES.md#provide-named-layer), [`no-provide-on-definition`](RULES.md#no-provide-on-definition), [`anti-slop-no-service-constructor-imports`](RULES.md#anti-slop-no-service-constructor-imports)                     |
-| Runtime & entrypoint | [`run-only-in-runner`](RULES.md#run-only-in-runner), [`prefer-effect-vitest`](RULES.md#prefer-effect-vitest), [`all-errors-handled-at-boundary`](RULES.md#all-errors-handled-at-boundary)                                                                                                                                                                                                                                              |
-| Design & boundaries  | [`adapter-import-boundary`](RULES.md#adapter-import-boundary), [`no-transport-types-in-generator`](RULES.md#no-transport-types-in-generator)                                                                                                                                                                                                                                                                                           |
-| Effectful functions  | [`prefer-effect-fn`](RULES.md#prefer-effect-fn), [`untraced-recursion`](RULES.md#untraced-recursion), [`single-style-per-function`](RULES.md#single-style-per-function)                                                                                                                                                                                                                                                                |
-| Code shape           | [`no-nested-match`](RULES.md#no-nested-match), [`no-yielded-match`](RULES.md#no-yielded-match), [`no-inline-yield-star`](RULES.md#no-inline-yield-star), [`no-effect-return-type`](RULES.md#no-effect-return-type), [`no-asymmetric-match-handlers`](RULES.md#no-asymmetric-match-handlers), [`anti-slop-prefer-effect-match`](RULES.md#anti-slop-prefer-effect-match)                                                                 |
-| Schema               | [`exported-schema-identifier`](RULES.md#exported-schema-identifier), [`no-inline-schema-codec`](RULES.md#no-inline-schema-codec)                                                                                                                                                                                                                                                                                                       |
-| Config & secrets     | [`redacted-secret-names`](RULES.md#redacted-secret-names)                                                                                                                                                                                                                                                                                                                                                                              |
-
-### Absorbed from anti-slop
-
-Some rules come from the Effect rules of [`dmmulroy/anti-slop`](https://github.com/dmmulroy/anti-slop), MIT-licensed: see [`LICENSE.anti-slop`](LICENSE.anti-slop).
-
-- Imported: [`anti-slop-no-manual-effect-error-tag`](RULES.md#anti-slop-no-manual-effect-error-tag), [`anti-slop-no-service-constructor-imports`](RULES.md#anti-slop-no-service-constructor-imports), [`anti-slop-prefer-effect-match`](RULES.md#anti-slop-prefer-effect-match).
-- Superseded: `no-manual-tag-comparison` by [`no-manual-discriminant-comparison`](RULES.md#no-manual-discriminant-comparison), `no-manual-tagged-construction` by [`no-manual-discriminant-construction`](RULES.md#no-manual-discriminant-construction).
-
-## Default configuration
-
-`all` is equivalent to the config below, with every setting and option spelled out at its default. Both **replace** the defaults instead of extending them: see [Shared settings](RULES.md#shared-settings).
-
-```ts
-import { defineConfig } from "oxlint"
-
-// Constructors that must not appear inside an Effect generator: the conversion to the
-// transport belongs in the second argument of Effect.fn. Add your own transport DTOs.
-const transportTypes = ["Response", "NextResponse"]
-
-// Schema fields holding a secret: a field matches an entry or ends with it capitalized
-// (`password` matches `dbPassword`). No generic `token`: `nextPageToken` is not a secret.
-const secretFields = ["password", "secret", "apiKey", "accessToken", "refreshToken", "idToken"]
-
-export default defineConfig({
-    jsPlugins: ["@doubleloop-io/oxlint-plugin-effect"],
-    settings: {
-        "dl-effect": {
-            // Files allowed to run Effects (Effect.run*, runMain, ManagedRuntime.make) and to
-            // import adapters. `index.ts` is left out on purpose: as a barrel it would let
-            // adapters leak through re-exports.
-            entryFiles: ["**/main.ts", "**/cli.ts", "**/bin/**"],
-            // Files exempt from the rules that tests legitimately break. Helper directories such
-            // as `src/testing/` are support code, not tests, so they are not matched.
-            testFiles: [
-                "**/*.test.*",
-                "**/*.spec.*",
-                "**/__tests__/**",
-                "**/test/**",
-                "**/tests/**",
-            ],
-            // Fields that discriminate a closed union, compared or switched on only through an
-            // exhaustive match and set only by a constructor. Add the ones your unions use, such
-            // as `type` or `kind`.
-            discriminants: ["_tag"],
-        },
-    },
-    // Every rule at `warn`, to measure noise without blocking.
-    rules: {
-        // Error channel
-        "dl-effect/no-throw-or-primitive-failure": "warn",
-        "dl-effect/try-object-form": "warn",
-        "dl-effect/no-effect-promise": "warn",
-        "dl-effect/no-parameterless-catch-all": "warn",
-        "dl-effect/split-success-path-from-error-handling": "warn",
-        "dl-effect/anti-slop-no-manual-effect-error-tag": "warn",
-        // Tagged values
-        "dl-effect/no-manual-discriminant-comparison": "warn",
-        "dl-effect/no-manual-discriminant-construction": "warn",
-        // Services & Layers
-        "dl-effect/service-port-shape-only": "warn",
-        "dl-effect/service-key-matches-name": "warn",
-        "dl-effect/service-built-with-of": "warn",
-        "dl-effect/provide-named-layer": "warn",
-        "dl-effect/no-provide-on-definition": "warn",
-        "dl-effect/anti-slop-no-service-constructor-imports": "warn",
-        // Runtime & entrypoint
-        "dl-effect/run-only-in-runner": "warn",
-        "dl-effect/prefer-effect-vitest": "warn",
-        "dl-effect/all-errors-handled-at-boundary": "warn",
-        // Design & boundaries
-        "dl-effect/adapter-import-boundary": "warn",
-        "dl-effect/no-transport-types-in-generator": ["warn", { transportTypes }],
-        // Effectful functions
-        "dl-effect/prefer-effect-fn": "warn",
-        "dl-effect/untraced-recursion": "warn",
-        "dl-effect/single-style-per-function": "warn",
-        // Code shape
-        "dl-effect/no-nested-match": "warn",
-        "dl-effect/no-yielded-match": "warn",
-        "dl-effect/no-inline-yield-star": "warn",
-        "dl-effect/no-effect-return-type": ["warn", { checkExported: false }],
-        "dl-effect/no-asymmetric-match-handlers": "warn",
-        "dl-effect/anti-slop-prefer-effect-match": "warn",
-        // Schema
-        "dl-effect/exported-schema-identifier": "warn",
-        "dl-effect/no-inline-schema-codec": "warn",
-        // Config & secrets
-        "dl-effect/redacted-secret-names": ["warn", { secretFields }],
-    },
-})
-```
-
-To change a setting, declare it in `settings`; to change a rule option, extend `all` and override only that rule.
-
-## Versioning
-
-Versions are `0.x`: any minor release may add, remove or change rules, options, settings and messages.
-
-Supported oxlint is the `peerDependencies` range, `^1.82.0`; CI tests the tarball against `1.82.0`. oxlint's JS plugin API is still experimental, so a newer oxlint minor may break the plugin before the range is narrowed.
+## Documentation
 
-## Development
+The guide is on the [website](https://doubleloop-io.github.io/oxlint-plugin-effect/):
 
-- `pnpm format`: formats with oxfmt; the only script that rewrites sources.
-- `pnpm check`: format check, typecheck, lint and tests, writing nothing. The tests are the `RuleTester`s from `oxlint/plugins-dev` with `node --test`, plus an alignment check of `RULES.md` with one section per rule.
-- `pnpm build`: compiles to `dist/` and generates `dist/presets/all.json` from `presets/all.ts` (the rule list comes from the plugin).
-- `pnpm pack:check`: checks the built preset, then the tarball `npm pack` would publish: only the files in `files`, no local absolute paths, `publint --strict`.
-- `pnpm smoke-test`: installs the tarball in `smoke-fixture/` with pnpm and checks the diagnostics of oxlint with each config form: `oxlint.config.ts` and `.oxlintrc.json` with the preset, `.oxlintrc.json` with the plugin by package name.
-- `pnpm build-and-pack`: `check`, `build`, `pack:check` and `smoke-test`; run it after every change.
-- `pnpm release <bump>`: from a clean `main` equal to `origin/main`, runs `build-and-pack`, bumps with `npm version <bump> --preid rc` (`prerelease` for the next rc, `x.y.z` for a stable), publishes, then pushes the commit and the tag. A prerelease is `next`, and also `latest` until the first stable version; a stable version is `latest`. A failed publish undoes the bump. Without `<bump>`, prints the version in `package.json` and the npm dist-tags.
-- `pnpm build:w`: reruns `pnpm build`, preset included, on every change to `index.ts`, `rules/`, `presets/`, `shared/` or `tsconfig.build.json`; a failed build waits for the next change.
-- `pnpm consumer:link <consumer>`: after `pnpm build`, replaces the pnpm symlinks of the plugin in every workspace package of `<consumer>` with links to the checkout, so the consumer's own lint runs the checkout's rules; no tracked file of the consumer changes. `pnpm consumer:unlink <consumer>` restores them with `pnpm install --frozen-lockfile`, as does any `pnpm install` in the consumer.
+- [Configuration](https://doubleloop-io.github.io/oxlint-plugin-effect/configuration/): the `all` preset and picking rules.
+- [Shared settings](https://doubleloop-io.github.io/oxlint-plugin-effect/shared-settings/): the settings that describe your project, their defaults and the rules that use them.
+- [Default configuration](https://doubleloop-io.github.io/oxlint-plugin-effect/default-configuration/): `all` with every setting and option spelled out.
+- [Alongside `@effect/tsgo`](https://doubleloop-io.github.io/oxlint-plugin-effect/alongside-effect-tsgo/): combining its presets with this one.
+- [Rules overview](https://doubleloop-io.github.io/oxlint-plugin-effect/rules-overview/): every rule, grouped by topic.
+- [Versioning](https://doubleloop-io.github.io/oxlint-plugin-effect/versioning/): what a release may change.
+- [Troubleshooting](https://doubleloop-io.github.io/oxlint-plugin-effect/troubleshooting/): the problems most often hit when adopting the plugin.
 
-A new rule must be registered in `index.ts` and documented in `RULES.md` under a `` ### `rule-name` `` heading; `pnpm build` adds it to the preset.
+Coding agents: the same pages ship in the package under `docs/user-guide/`, starting from `docs/user-guide/README.md`.

package/docs/user-guide/README.md

@@ -0,0 +1,24 @@
+---
+title: "@doubleloop-io/oxlint-plugin-effect"
+---
+
+An oxlint plugin that enforces a catalog of patterns for Effect 4 code.
+
+The rules are written and tested against Effect 4. Where an Effect 3 API has the same intent, the rules recognize its v3 name too: each rule's Trigger names them.
+
+It complements the type-aware rules of [`@effect/tsgo`](alongside-effect-tsgo.md): it does not need them, and it checks what they do not.
+
+## Guide
+
+- [Installation](installation.md): the package and the Node and oxlint versions it requires.
+- [Configuration](configuration.md): the `all` preset and picking rules.
+- [Shared settings](shared-settings.md): the settings that describe your project, their defaults and the rules that use them.
+- [Alongside `@effect/tsgo`](alongside-effect-tsgo.md): combining its presets with this one.
+- [Default configuration](default-configuration.md): `all` with every setting and option spelled out.
+- [Versioning](versioning.md): what a release may change and which oxlint versions are supported.
+- [Troubleshooting](troubleshooting.md): the problems most often hit when adopting the plugin.
+
+## Rules
+
+- [Rules overview](rules.md): every rule, grouped by topic.
+- [Common limits](common-limits.md): the limits every rule shares.

package/docs/user-guide/alongside-effect-tsgo.md

@@ -0,0 +1,23 @@
+---
+title: Alongside `@effect/tsgo`
+order: 4
+---
+
+[`@effect/tsgo`](https://github.com/Effect-TS/tsgo) is the official Effect language service on top of the TypeScript Go compiler; its `effecttsgo` oxlint presets add more than 100 type-aware rules. This plugin does not need it, and its rules target what those presets do not check, so the two complement each other. To use both, follow its [Oxlint Setup guide](https://github.com/Effect-TS/tsgo/blob/main/docs/README.md) and put its preset in `extends` **before** `all`:
+
+```ts
+import dlEffectAll from "@doubleloop-io/oxlint-plugin-effect/presets/all"
+import { recommended as effectTsgoRecommended } from "@effect/tsgo/oxlint-presets"
+import { defineConfig } from "oxlint"
+
+export default defineConfig({ extends: [effectTsgoRecommended, dlEffectAll] })
+```
+
+```json
+{
+    "extends": [
+        "./node_modules/@effect/tsgo/oxlint-presets/recommended.json",
+        "./node_modules/@doubleloop-io/oxlint-plugin-effect/dist/presets/all.json"
+    ]
+}
+```

package/docs/user-guide/common-limits.md

@@ -0,0 +1,10 @@
+---
+title: Common limits
+order: 6
+---
+
+The limits every rule shares.
+
+- **Syntax only**: no rule uses type information. Only two rules look past the file: [`adapter-import-boundary`](rules/adapter-import-boundary.md), to find which directories are adapters, and [`prefer-effect-vitest`](rules/prefer-effect-vitest.md), to find whether `@effect/vitest` is installed.
+- **Literal names**: `Effect.gen` is recognized, `import { Effect as E }` or `import * as L from "effect/Layer"` slip through. On code that uses aliases, silence is not compliance.
+- **Effect 4**: the rules are written against v4. Where a v3 API has the same intent, they recognize its v3 name too (`catchAll`, `Either`, `Context.Tag`, `Config.redacted`, …), and the Trigger names it.

package/docs/user-guide/configuration.md

@@ -0,0 +1,43 @@
+---
+title: Configuration
+order: 2
+---
+
+Extend the `all` preset. Prefer `oxlint.config.ts`, where `extends` takes config objects and the preset is imported by package name:
+
+```ts
+import dlEffectAll from "@doubleloop-io/oxlint-plugin-effect/presets/all"
+import { defineConfig } from "oxlint"
+
+export default defineConfig({ extends: [dlEffectAll] })
+```
+
+With `.oxlintrc.json`, `extends` takes file paths only, so the preset is reached through `node_modules`:
+
+```json
+{
+    "extends": ["./node_modules/@doubleloop-io/oxlint-plugin-effect/dist/presets/all.json"]
+}
+```
+
+`all` enables every rule at `warn`, so adopting it never breaks a build: look at the warnings first, then raise to `error` the rules you want to enforce. A `recommended` preset with reasoned severities will come from measurements on real codebases.
+
+To pick rules without the preset, load the plugin by package name and list the rules:
+
+```json
+{
+    "jsPlugins": ["@doubleloop-io/oxlint-plugin-effect"],
+    "rules": {
+        "dl-effect/no-effect-promise": "error",
+        "dl-effect/try-object-form": "error"
+    }
+}
+```
+
+## Settings
+
+The settings that describe your project, such as its entry files and test files, are on [Shared settings](shared-settings.md). Their defaults fit a Node CLI: on another layout (Next.js, a monorepo), set them before reading the warnings.
+
+The other options and every default are in [Default configuration](default-configuration.md).
+
+To use it with the `@effect/tsgo` presets, see [Alongside `@effect/tsgo`](alongside-effect-tsgo.md).

package/docs/user-guide/default-configuration.md

@@ -0,0 +1,88 @@
+---
+title: Default configuration
+order: 5
+---
+
+`all` is equivalent to the config below, with every setting and option spelled out at its default. Both **replace** the defaults instead of extending them: see [Shared settings](shared-settings.md).
+
+```ts
+import { defineConfig } from "oxlint"
+
+// Constructors that must not appear inside an Effect generator: the conversion to the
+// transport belongs in the second argument of Effect.fn. Add your own transport DTOs.
+const transportTypes = ["Response", "NextResponse"]
+
+// Schema fields holding a secret: a field matches an entry or ends with it capitalized
+// (`password` matches `dbPassword`). No generic `token`: `nextPageToken` is not a secret.
+const secretFields = ["password", "secret", "apiKey", "accessToken", "refreshToken", "idToken"]
+
+export default defineConfig({
+    jsPlugins: ["@doubleloop-io/oxlint-plugin-effect"],
+    settings: {
+        "dl-effect": {
+            // Files allowed to run Effects (Effect.run*, runMain, ManagedRuntime.make) and to
+            // import adapters. `index.ts` is left out on purpose: as a barrel it would let
+            // adapters leak through re-exports.
+            entryFiles: ["**/main.ts", "**/cli.ts", "**/bin/**"],
+            // Files exempt from the rules that tests legitimately break. Helper directories such
+            // as `src/testing/` are support code, not tests, so they are not matched.
+            testFiles: [
+                "**/*.test.*",
+                "**/*.spec.*",
+                "**/__tests__/**",
+                "**/test/**",
+                "**/tests/**",
+            ],
+            // Fields that discriminate a closed union, compared or switched on only through an
+            // exhaustive match and set only by a constructor. Add the ones your unions use, such
+            // as `type` or `kind`.
+            discriminants: ["_tag"],
+        },
+    },
+    // Every rule at `warn`, to measure noise without blocking.
+    rules: {
+        // Error channel
+        "dl-effect/no-throw-or-primitive-failure": "warn",
+        "dl-effect/try-object-form": "warn",
+        "dl-effect/no-effect-promise": "warn",
+        "dl-effect/no-parameterless-catch-all": "warn",
+        "dl-effect/split-success-path-from-error-handling": "warn",
+        "dl-effect/anti-slop-no-manual-effect-error-tag": "warn",
+        // Tagged values
+        "dl-effect/no-manual-discriminant-comparison": "warn",
+        "dl-effect/no-manual-discriminant-construction": "warn",
+        // Services & Layers
+        "dl-effect/service-port-shape-only": "warn",
+        "dl-effect/service-key-matches-name": "warn",
+        "dl-effect/service-built-with-of": "warn",
+        "dl-effect/provide-named-layer": "warn",
+        "dl-effect/no-provide-on-definition": "warn",
+        "dl-effect/anti-slop-no-service-constructor-imports": "warn",
+        // Runtime & entrypoint
+        "dl-effect/run-only-in-runner": "warn",
+        "dl-effect/prefer-effect-vitest": "warn",
+        "dl-effect/all-errors-handled-at-boundary": "warn",
+        // Design & boundaries
+        "dl-effect/adapter-import-boundary": "warn",
+        "dl-effect/no-transport-types-in-generator": ["warn", { transportTypes }],
+        // Effectful functions
+        "dl-effect/prefer-effect-fn": "warn",
+        "dl-effect/untraced-recursion": "warn",
+        "dl-effect/single-style-per-function": "warn",
+        // Code shape
+        "dl-effect/no-nested-match": "warn",
+        "dl-effect/no-yielded-match": "warn",
+        "dl-effect/no-inline-yield-star": "warn",
+        "dl-effect/no-effect-return-type": ["warn", { checkExported: false }],
+        "dl-effect/no-asymmetric-match-handlers": "warn",
+        "dl-effect/anti-slop-prefer-effect-match": "warn",
+        // Schema
+        "dl-effect/exported-schema-identifier": "warn",
+        "dl-effect/no-inline-schema-codec": "warn",
+        // Config & secrets
+        "dl-effect/redacted-secret-names": ["warn", { secretFields }],
+    },
+})
+```
+
+To change a setting, declare it in `settings`; to change a rule option, extend `all` and override only that rule.

package/docs/user-guide/installation.md

@@ -0,0 +1,12 @@
+---
+title: Installation
+order: 1
+---
+
+```bash
+pnpm add -D @doubleloop-io/oxlint-plugin-effect oxlint
+```
+
+Requires Node `^22.20.0 || >=24.8.0` and oxlint `^1.82.0`. What a release may change and which oxlint versions are supported: [Versioning](versioning.md).
+
+Then extend the `all` preset: see [Configuration](configuration.md).

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