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

package/docs/user-guide/rules/service-key-matches-name.md

@@ -0,0 +1,29 @@
+---
+title: service-key-matches-name
+group: Services and Layers
+---
+
+**Intent**: a service's key is its class name, alone or after a path prefix.
+
+```ts
+// ❌ no
+export class GeocodingApis extends Context.Service<GeocodingApis, Shape>()("GeocodingAPIs") {}
+
+// ✅ yes
+export class GeocodingApis extends Context.Service<GeocodingApis, Shape>()("GeocodingApis") {}
+
+// ✅ yes
+export class GeocodingApis extends Context.Service<GeocodingApis, Shape>()(
+    "app/geo/GeocodingApis",
+) {}
+```
+
+**Trigger**: `class X extends Context.Service<…>()("key")`, or the v3 `Context.Tag("key")<…>()` and `Effect.Service<X>()("key", …)`, with a literal key that is neither `"X"` nor ends with `"/X"`.
+
+**Exemptions and blind spots**: keys that are not literals (variables, templates with expressions). A `Context.Service` assigned to a variable is not seen: see `service-not-as-class` (effecttsgo). `deterministic-keys` (effecttsgo) with the `default` or `package-identifier` formula produces keys this rule accepts; with `default-hashed` the two contradict each other: enable only one.
+
+**Why**: the key is the service's identity in errors, traces and `Context` lookups; a key that drifts from the name, as after a rename, makes it hard to find the class behind a message.
+
+**Options**: none
+
+**Fix**: suggestion that replaces the last segment of the key with the class name

package/docs/user-guide/rules/service-port-shape-only.md

@@ -0,0 +1,27 @@
+---
+title: service-port-shape-only
+group: Services and Layers
+---
+
+**Intent**: a port is a shape-only `Context.Service` (v3: `Context.Tag`), with no implementation attached.
+
+```ts
+// ❌ no
+class Agent extends Context.Service<Agent, Shape>()("app/Agent", { make: makeAgent }) {}
+
+// ✅ yes
+export class Agent extends Context.Service<
+    Agent,
+    { readonly search: (name: string) => Effect.Effect<RaceCard, AgentError> }
+>()("app/agent/Agent") {}
+```
+
+**Trigger**: the second argument of `Context.Service<…>()(id, opts)`; a `static layer`, `static Default` or `static Live` member on a `Context.Service` or v3 `Context.Tag(id)<…>()` class; any `Effect.Service`.
+
+**Exemptions and blind spots**: a `Context.Service` or v3 `Context.GenericTag` assigned to a variable is not seen: see `service-not-as-class` (effecttsgo). Statics with other names slip through.
+
+**Why**: `make` and a static layer tie the port to a default implementation, while the port must stay a contract any adapter can satisfy. It is a convention, not Effect's idiom: Effect's own docs put `static readonly layer` on the service.
+
+**Options**: none
+
+**Fix**: none

package/docs/user-guide/rules/single-style-per-function.md

@@ -0,0 +1,36 @@
+---
+title: single-style-per-function
+group: Effectful functions
+---
+
+**Intent**: a function is entirely Effect or not Effect at all.
+
+```ts
+// ❌ no
+export const POST = async (request: Request) => {
+    const form = await request.formData()
+    const created = await Effect.runPromise(Effect.result(createEvent(form)))
+    // …
+}
+
+// ✅ yes: promises lifted with Effect.tryPromise
+const createEvent = Effect.fn("events.create")(function* (request: Request) {
+    const form = yield* Effect.tryPromise({
+        try: () => request.formData(),
+        catch: () => new BadRequest({ message: "invalid form data" }),
+    })
+    // …
+})
+```
+
+**Trigger**: `async`, `await` and `.then(` in a function that builds Effects: an Effect generator, or a function using an `Effect.*` member. A `test`/`it` callback (`.only`, `.each(…)` and the like included) or a `beforeAll`/`afterAll`/`beforeEach`/`afterEach` hook, and in test files any other function except an Effect generator, is reported once, on the function, when more than one of its `await`s, or any `.then(`, involves Effect: has an `Effect.*` member in its expression, nested callbacks and `Effect.run*` included.
+
+**Exemptions and blind spots**: `Effect.run*` alone does not make a function effectful: it is how an async boundary hands over to Effect, and where it may appear is decided by [`run-only-in-runner`](run-only-in-runner.md). An `async` function that renders JSX itself, not only in nested callbacks, is a Server Component: how it turns failures into UI is left to the application. A test, hook or test helper may await promise-based fixtures (a container, an identity provider), then one Effect program, and assert on its result. A step that reaches Effect only through a helper (`await run(seed)`) is not counted.
+
+**Why**: errors travel on two channels, exceptions and Effect, and neither sees them all.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none

package/docs/user-guide/rules/split-success-path-from-error-handling.md

@@ -0,0 +1,37 @@
+---
+title: split-success-path-from-error-handling
+group: Error channel
+---
+
+**Intent**: the generator holds only the happy path; error handling lives in the second argument of `Effect.fn`.
+
+```ts
+// ❌ no
+function* () {
+    const x = yield* fetchThing.pipe(Effect.catchTag("NotFound", () => Effect.succeed(fallback)))
+}
+
+// ✅ yes: naming the error or giving an alternative is not handling
+function* () {
+    const x = yield* fetchThing.pipe(Effect.orElseSucceed(() => fallback))
+    const y = yield* decode(raw).pipe(Effect.mapError((error) => new BadRequest({ message: error.message })))
+}
+
+// ✅ yes: translation in the second argument, which also receives the original arguments
+const createEvent = Effect.fn("events.create")(
+    function* (request: Request) { /* success only */ },
+    (effect, request) => effect.pipe(Effect.catchTags({ BadRequest: (e) => refused(400, e.message) })),
+)
+```
+
+**Trigger**: inside a generator passed to `Effect.gen`/`Effect.fn`, callbacks passed to `Effect.*` combinators included, calls to `Effect.catch*` (`catch`, `catchAll`, `catchTag`, `catchTags`, `catchIf`, `catchCause`, `catchDefect`, `catchReason`, …), `either`, `result`, `exit`, `match*` and `sandbox`.
+
+**Exemptions and blind spots**: pipeables of a nested `Effect.fn`. Handlers inside the callback of an iteration (`forEach`, `filter`, `reduce`, `partition`, `validate`, `findFirst`, …): they handle each element on its own, and in the pipeables the first failure would stop the rest. Functions the generator only defines, such as an `HttpApiBuilder` handler or a service method: they are programs of their own. Test files, where the failure is the outcome under observation (`yield* Effect.result(op)` then `expect`). A `catch`, `catchTag`, `catchTags`, `catchIf` or `catchFilter` whose handlers only die (`Effect.die` passed directly or as the sole return): it is a selective `orDie`, declaring the case untracked rather than handling it; a die behind a wrapper or a condition is still reported. A `.pipe(Effect.catch…)` appended to an `Effect.gen` escapes; [`prefer-effect-fn`](prefer-effect-fn.md) closes that gap.
+
+**Why**: translation becomes a single exhaustive point instead of catches scattered along the flow.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](../shared-settings.md).
+
+**Fix**: none

package/docs/user-guide/rules/try-object-form.md

@@ -0,0 +1,27 @@
+---
+title: try-object-form
+group: Error channel
+---
+
+**Intent**: `Effect.try` and `Effect.tryPromise` take `{ try, catch }`, with `catch` producing a tagged error.
+
+```ts
+// ❌ no
+Effect.tryPromise(() => api.spreadsheets.get({ spreadsheetId }))
+
+// ✅ yes
+Effect.tryPromise({
+    try: () => api.spreadsheets.get({ spreadsheetId }),
+    catch: toSheetError(spreadsheetId),
+})
+```
+
+**Trigger**: `Effect.try` and `Effect.tryPromise` whose argument is not an object literal.
+
+**Exemptions and blind spots**: an options object held in a variable is reported too.
+
+**Why**: the thunk form types the error as `Cause.UnknownError` (`UnknownException` in v3), which no caller can handle by tag.
+
+**Options**: none
+
+**Fix**: none

package/docs/user-guide/rules/untraced-recursion.md

@@ -0,0 +1,31 @@
+---
+title: untraced-recursion
+group: Effectful functions
+---
+
+**Intent**: a recursive effectful function uses `Effect.fnUntraced`; the entry point that starts the recursion is traced.
+
+```ts
+// ❌ no
+const walk = Effect.fn("walk")(function* (node: Node) {
+    for (const child of node.children) yield* walk(child)
+})
+
+// ✅ yes
+const walk = Effect.fnUntraced(function* (node: Node) {
+    for (const child of node.children) yield* walk(child)
+})
+export const scan = Effect.fn("scan")(function* (root: Node) {
+    return yield* walk(root)
+})
+```
+
+**Trigger**: an `Effect.fn` assigned to a variable that its own body calls again, even by passing it as a callback.
+
+**Exemptions and blind spots**: mutual recursion, recursion in pipeables.
+
+**Why**: with `Effect.fn` every level opens a span nested in the previous one.
+
+**Options**: none
+
+**Fix**: none

package/docs/user-guide/rules.md

@@ -0,0 +1,26 @@
+---
+title: Rules overview
+---
+
+What each rule reports and why is on its page. Report false positives and missed cases in the [GitHub issues](https://github.com/doubleloop-io/oxlint-plugin-effect/issues).
+
+| Topic                   | Rules                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Error channel           | [`no-throw-or-primitive-failure`](rules/no-throw-or-primitive-failure.md), [`try-object-form`](rules/try-object-form.md), [`no-effect-promise`](rules/no-effect-promise.md), [`no-parameterless-catch-all`](rules/no-parameterless-catch-all.md), [`split-success-path-from-error-handling`](rules/split-success-path-from-error-handling.md), [`anti-slop-no-manual-effect-error-tag`](rules/anti-slop-no-manual-effect-error-tag.md) |
+| Tagged values           | [`no-manual-discriminant-comparison`](rules/no-manual-discriminant-comparison.md), [`no-manual-discriminant-construction`](rules/no-manual-discriminant-construction.md)                                                                                                                                                                                                                                                               |
+| Services and Layers     | [`service-port-shape-only`](rules/service-port-shape-only.md), [`service-key-matches-name`](rules/service-key-matches-name.md), [`service-built-with-of`](rules/service-built-with-of.md), [`provide-named-layer`](rules/provide-named-layer.md), [`no-provide-on-definition`](rules/no-provide-on-definition.md), [`anti-slop-no-service-constructor-imports`](rules/anti-slop-no-service-constructor-imports.md)                     |
+| Runtime and entry point | [`run-only-in-runner`](rules/run-only-in-runner.md), [`prefer-effect-vitest`](rules/prefer-effect-vitest.md), [`all-errors-handled-at-boundary`](rules/all-errors-handled-at-boundary.md)                                                                                                                                                                                                                                              |
+| Design and boundaries   | [`adapter-import-boundary`](rules/adapter-import-boundary.md), [`no-transport-types-in-generator`](rules/no-transport-types-in-generator.md)                                                                                                                                                                                                                                                                                           |
+| Effectful functions     | [`prefer-effect-fn`](rules/prefer-effect-fn.md), [`untraced-recursion`](rules/untraced-recursion.md), [`single-style-per-function`](rules/single-style-per-function.md)                                                                                                                                                                                                                                                                |
+| Code shape              | [`no-nested-match`](rules/no-nested-match.md), [`no-yielded-match`](rules/no-yielded-match.md), [`no-inline-yield-star`](rules/no-inline-yield-star.md), [`no-effect-return-type`](rules/no-effect-return-type.md), [`no-asymmetric-match-handlers`](rules/no-asymmetric-match-handlers.md), [`anti-slop-prefer-effect-match`](rules/anti-slop-prefer-effect-match.md)                                                                 |
+| Schema                  | [`exported-schema-identifier`](rules/exported-schema-identifier.md), [`no-inline-schema-codec`](rules/no-inline-schema-codec.md)                                                                                                                                                                                                                                                                                                       |
+| Config and secrets      | [`redacted-secret-names`](rules/redacted-secret-names.md)                                                                                                                                                                                                                                                                                                                                                                              |
+
+## 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).
+
+| Status     | Rules                                                                                                                                                                                                                                                               |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Imported   | [`anti-slop-no-manual-effect-error-tag`](rules/anti-slop-no-manual-effect-error-tag.md), [`anti-slop-no-service-constructor-imports`](rules/anti-slop-no-service-constructor-imports.md), [`anti-slop-prefer-effect-match`](rules/anti-slop-prefer-effect-match.md) |
+| Superseded | `no-manual-tag-comparison` → [`no-manual-discriminant-comparison`](rules/no-manual-discriminant-comparison.md), `no-manual-tagged-construction` → [`no-manual-discriminant-construction`](rules/no-manual-discriminant-construction.md)                             |

package/docs/user-guide/shared-settings.md

@@ -0,0 +1,65 @@
+---
+title: Shared settings
+order: 3
+---
+
+Three settings describe your project, not a rule, so they are declared once under `settings["dl-effect"]` in the oxlint config 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.
+
+## The settings
+
+| Setting                                                                          | Default                                                                      | Used by                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entryFiles`: the files allowed to run Effects and import adapters               | `**/main.ts`, `**/cli.ts`, `**/bin/**`                                       | [`run-only-in-runner`](rules/run-only-in-runner.md), [`adapter-import-boundary`](rules/adapter-import-boundary.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `testFiles`: the test files, exempt from the rules that tests legitimately break | `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `**/test/**`, `**/tests/**` | [`run-only-in-runner`](rules/run-only-in-runner.md), [`adapter-import-boundary`](rules/adapter-import-boundary.md), [`no-effect-promise`](rules/no-effect-promise.md), [`provide-named-layer`](rules/provide-named-layer.md), [`no-provide-on-definition`](rules/no-provide-on-definition.md), [`split-success-path-from-error-handling`](rules/split-success-path-from-error-handling.md), [`all-errors-handled-at-boundary`](rules/all-errors-handled-at-boundary.md), [`anti-slop-no-service-constructor-imports`](rules/anti-slop-no-service-constructor-imports.md), [`no-throw-or-primitive-failure`](rules/no-throw-or-primitive-failure.md), [`single-style-per-function`](rules/single-style-per-function.md), [`prefer-effect-vitest`](rules/prefer-effect-vitest.md) |
+| `discriminants`: the fields that discriminate a closed union                     | `_tag`                                                                       | [`no-manual-discriminant-comparison`](rules/no-manual-discriminant-comparison.md), [`no-manual-discriminant-construction`](rules/no-manual-discriminant-construction.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+
+The default `entryFiles` leave out `index.ts` on purpose: it is usually a barrel, and exempting it would let adapters reach the rest of the application through re-exports.
+
+Most rules skip `testFiles` entirely. Three use them differently: [`no-throw-or-primitive-failure`](rules/no-throw-or-primitive-failure.md) skips only primitive failures there, [`single-style-per-function`](rules/single-style-per-function.md) treats their helpers like tests, and [`prefer-effect-vitest`](rules/prefer-effect-vitest.md) checks only them. A helper directory such as `src/testing/` does not count as tests: it is support code.
+
+Add to `discriminants` the fields your unions discriminate on, such as `type` or `kind`.
+
+File globs are matched against the path relative to oxlint's working directory, with `/` on every platform.
+
+## Setting a value
+
+Set one only where its default does not fit: it **replaces** the default instead of extending it. To extend a default in a TypeScript config, spread the one the package exports: `defaultEntryFiles`, `defaultTestFiles` or `defaultDiscriminants`. A JSON config cannot import them: copy the default from the table above. 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 { defaultTestFiles } from "@doubleloop-io/oxlint-plugin-effect"
+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"],
+            testFiles: [...defaultTestFiles, "e2e/**"],
+        },
+    },
+})
+```
+
+```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"],
+            "testFiles": [
+                "**/*.test.*",
+                "**/*.spec.*",
+                "**/__tests__/**",
+                "**/test/**",
+                "**/tests/**",
+                "e2e/**"
+            ]
+        }
+    }
+}
+```
+
+## Where settings go
+
+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.

package/docs/user-guide/troubleshooting.md

@@ -0,0 +1,30 @@
+---
+title: Troubleshooting
+order: 8
+---
+
+The problems most often hit when adopting the plugin: each states the symptom, the cause and the fix.
+
+## The lint stops with a settings error
+
+- **Symptom**: oxlint exits with an error naming a `dl-effect` setting before reporting anything.
+- **Cause**: a key under `settings["dl-effect"]` is not one of the shared settings, or its value is not an array of strings.
+- **Fix**: correct the key or the value as described in [Shared settings](shared-settings.md#setting-a-value).
+
+## Settings are ignored or rejected
+
+- **Symptom**: settings put in a preset in `extends` have no effect, or oxlint rejects settings put in `overrides`.
+- **Cause**: oxlint reads settings only from the config that lints.
+- **Fix**: move them to that config, as described in [Where settings go](shared-settings.md#where-settings-go).
+
+## Many warnings on correct code
+
+- **Symptom**: on a layout that is not a Node CLI, such as Next.js or a monorepo, many warnings look like false positives, for example Effects run or adapters imported outside the entry files.
+- **Cause**: the defaults of `entryFiles` and `testFiles` fit a Node CLI.
+- **Fix**: set both for your layout, as described in [Shared settings](shared-settings.md#the-settings).
+
+## No warnings on code that uses aliases
+
+- **Symptom**: a file that breaks the rules gets no warnings.
+- **Cause**: the rules recognize literal names only: see [Common limits](common-limits.md).
+- **Fix**: import Effect modules under their own names where you want the rules to check the code.

package/docs/user-guide/versioning.md

@@ -0,0 +1,8 @@
+---
+title: Versioning
+order: 7
+---
+
+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.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@doubleloop-io/oxlint-plugin-effect",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.1",
   "description": "Oxlint rules for Effect 4 code",
+  "homepage": "https://doubleloop-io.github.io/oxlint-plugin-effect/",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -9,8 +10,9 @@
   },
   "files": [
     "dist/",
-    "RULES.md",
+    "docs/user-guide/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "LICENSE.anti-slop"
   ],
@@ -33,6 +35,8 @@
     "@oxlint/plugins": "^1.82.0"
   },
   "devDependencies": {
+    "@changesets/changelog-github": "^1.0.1",
+    "@changesets/cli": "^3.0.3",
     "@types/node": "^24.13.6",
     "oxfmt": "0.67.0",
     "oxlint": "1.82.0",
@@ -50,14 +54,16 @@
     "format:check": "oxfmt --check",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint --deny-warnings",
-    "test": "node --test rules-md.test.ts rules/*.test.ts shared/*.test.ts scripts/*.test.ts",
+    "test": "node --test src/rule-files.test.ts src/rules/*.test.ts src/shared/*.test.ts",
     "check": "pnpm format:check && pnpm typecheck && pnpm lint && pnpm test",
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && node presets/all-json.ts",
-    "build:w": "node --watch-path=index.ts --watch-path=rules --watch-path=presets --watch-path=shared --watch-path=tsconfig.build.json scripts/build.ts",
-    "pack:check": "node --test presets/all-dist.test.ts && node scripts/pack-check.ts",
-    "build-and-pack": "pnpm check && pnpm build && pnpm pack:check && pnpm smoke-test",
-    "smoke-test": "node scripts/smoke-test.ts",
-    "release": "node scripts/release.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/preset-all-json.ts",
+    "build:w": "node --watch-path=src --watch-path=tsconfig.build.json scripts/build.ts",
+    "pack:check": "node --test scripts/preset-all-dist-check.ts && node scripts/pack-check.ts",
+    "build-and-pack": "pnpm check && pnpm build && pnpm pack:check && pnpm consumer-test",
+    "consumer-test": "node scripts/consumer-test.ts",
+    "changeset-version": "changeset version && pnpm format",
+    "changeset-publish": "pnpm build-and-pack && changeset publish",
+    "changeset-status": "changeset status --verbose",
     "consumer:link": "./scripts/link-consumer.sh link",
     "consumer:unlink": "./scripts/link-consumer.sh unlink"
   }