@aurelienbbn/oxlint-plugin-effect

42 oxlint rules for Effect code: runtime boundaries, failure channels, concurrency, services, Schema. Only what @effect/tsgo doesn't own.

pnpm add -D @aurelienbbn/oxlint-plugin-effect oxlint   # oxlint >=1.82.0 <2.0.0

{
  "jsPlugins": ["@aurelienbbn/oxlint-plugin-effect"],
  "rules": {
    "effect/require-all-concurrency": "error",
    "effect/require-tagged-effect-fail": "error",
    "effect/no-run-promise-in-runtime": ["error", { "allow": ["**/src/main.ts"] }]
  }
}

No preset: enable each rule by name.

Upstream first, this plugin second

@effect/tsgo recommended oxlint preset   ← enable FIRST, wins every overlap (type-aware)
  floating Effects · missing yield* / return yield* · Effect-native globals & JSON
  Effect.fn opportunities · try/catch and timers in generators · class Self mismatch
        +
withEffectTsgoLayer extras               ← @aurelienbbn/oxlint-config; off in recommended
  any/unknown in error & requirements channels · unsafe Effect type assertions
  deterministic service/error keys · Effect.provide outside entry points
        │
        ▼
@aurelienbbn/oxlint-plugin-effect        ← policies and syntactic failure modes tsgo doesn't own

Wire tsgo with withEffectTsgoLayer from @aurelienbbn/oxlint-config: it adds the four extras and settles every overlap with this plugin in one table. Mind its version lock: @effect/tsgo 0.45.0 accepts only oxlint 1.81.0 / 1.82.0 and oxlint-tsgolint 7.0.2001.

Type-dependent conclusions stay with @effect/tsgo. Ownership: docs/rule-ownership.md; the catalog gate enforces the inventory.

What fires

const values = Effect.all(programs); // ❌ require-all-concurrency
const values = Effect.all(programs, { concurrency: 1 }); // ✅ explicit choice

const program = Effect.fail("boom"); // ❌ require-tagged-effect-fail
const program = Effect.fail(new DomainError({ reason })); // ✅ tagged error

const load = (id: string) => Effect.fn(`users.load.${id}`)(body); // ❌ no-dynamic-span-name
const load = Effect.fn("users.load")(body); // ✅ ids go in span attributes

class NotFound extends Schema.TaggedError<NotFound>()("Missing", {}) {} // ❌ tagged-error-name, twice
class NotFoundError extends Schema.TaggedError<NotFoundError>()("NotFoundError", {}) {} // ✅ catchTag greps to the class

const Status = Schema.Literals(["Pending", "partially-refunded"]); // ❌ schema-literal-case, twice
const Status = Schema.Literals(["pending", "partially_refunded"]); // ✅ one case on the wire

// orders/domain/order.ts
export interface Order {
  readonly id: OrderId;
} // ❌ schema-domain-types
export const Order = Schema.Struct({ id: OrderId }); // ✅ the schema owns the shape
export type Order = typeof Order.Type;
const Concurrency = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(1))); // ❌ schema-check-branded
const Concurrency = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(1)), Schema.brand("Concurrency")); // ✅ only make or a decode builds one

const sync = Effect.fn("OrderSync.run")(body); // ❌ telemetry-name-format
const sync = Effect.fn("orders.sync")(body); // ✅ <area>.<operation>, lowercase snake_case

Effect.tryPromise(() => fetch(url)); // ❌ no-untyped-try-promise-catch, require-abort-signal
Effect.tryPromise({
  try: (signal) => fetch(url, { signal }),
  catch: (cause) => new HttpError({ cause }), // ✅ typed, cause kept, signal forwarded
});

• Concurrency rules demand an explicit choice; they don't claim omitted concurrency is unbounded.
• Same allow paths on no-run-promise-in-runtime and no-unscoped-runtime-launch: shared boundary matching.
• tagged-error-name clashes with tsgo deterministic-keys only when tsgo's keyPatterns gain an error target: that target wants a package-qualified tag (pkg/file/NotFoundError). Keep errors out of keyPatterns, or turn this rule off.
• schema-literal-case keeps Schema.Literals([...]) values in one case, snake_case by default: they travel as data (URLs, SQL, logs, wire contracts), and snake_case is what Postgres, Shopify REST (partially_refunded) and Stripe (requires_payment_method) use. Schema.Literal("..."), _tags and non-string literals are out of scope. No fix: renaming a wire value needs a coordinated change.
• schema-domain-types makes a domain folder Schema-only: in **/domain/** (option files), an interface, an object type (bare, in Readonly<>, in a union or an intersection), a union of literals or an enum is reported; declare a Schema.Struct, Schema.TaggedStruct, Schema.Union or Schema.Literals and derive the type with typeof X.Type. Silent: generic declarations, declarations holding behavior (methods, function-typed members) or runtime handles (Schema.*, Effect.*, Layer.*, Stream.* members), unions of named types, and an empty interface that extends a schema type. No fix: the schema is the decision.
• schema-check-branded puts a domain check in the type: a check runs only when a value is decoded, encoded or built with make, so without a brand code can still write { concurrency: 0 }. In **/domain/** (option files), a Schema.check(...) or .check(...) whose chain has no Schema.brand is reported. A wire DTO needs no brand (decoding and encoding both check it), so the rule stays out of other folders by default; built-in schemas used as they are (Schema.Int, Schema.NonEmptyString) are not checks it sees. A counter that only grows (attempts + 1) is the usual exception: suppress it there.
• telemetry-name-format wants indexed names as <area>.<operation> in lowercase dotted snake_case (mcp.auth.verify_api_key): span names, Rpc.make tags, and the keys of annotateLogs, annotateSpans, annotateCurrentSpan and withSpan's attributes (one segment allowed: event). String literals only; no-dynamic-span-name owns runtime names.
• telemetry-name-format with logMessages: true treats a log message as an event name: the first argument of Effect.log, logTrace, logDebug, logInfo, logWarning, logError and logFatal (through Effect, an alias, or a named import from effect/Effect) must be a literal in the name format, like Effect.logInfo("webhook.rejected", { attempt }), so log backends can search and count by it. A variable, a template with values or a concatenation is reported too: values go in later arguments or Effect.annotateLogs.
• Enable telemetry-name-format or effect-fn-name-matches-binding, not both: the binding rule ties the last span segment to the binding (const syncAll = Effect.fn("orders.syncAll")), which snake_case rejects.
• 🎨 dependencies-first, padding-after-dependencies, no-switch, prefer-match, prefer-effect-array-helpers, schema-type-adjacent, schema-literal-case, schema-domain-types, schema-check-branded, tagged-error-name, telemetry-name-format are opinionated. Suppress at the exceptional call site, not in the shared config.

1 autofix, 5 suggestions

Only padding-after-dependencies has one behavior-preserving rewrite: it inserts the blank line below the leading service dependencies. Every other fix needs project knowledge: error type, runtime boundary, concurrency policy, layer owner, tracing name, platform adapter.

Effect.gen(function* () {
  const repo = yield* UserRepo;
  const user = yield* repo.findUser(id); // ❌ padding-after-dependencies
});

Effect.gen(function* () {
  const repo = yield* UserRepo;

  const user = yield* repo.findUser(id); // ✅ dependencies stand apart
});

Migration

Contract

Registered contract inventory

Generated from package exports by pnpm catalog. Rule-specific options and limitations are described above and in the source tests.

Credited concepts

• Effect bundled AGENTS.md "The name string should match the function name" (concept)
• Effect bundled ai-docs "capped exponential backoff with jitter and max attempts" pattern (concept)
• Effect bundled ai-docs 04_integration/10_managed-runtime.ts module-level runtime (concept)
• Effect bundled ai-docs 09_testing/10_effect-tests.ts "controls time with TestClock" (concept)
• Effect bundled ai-docs catch: (cause) => new X({ cause }) convention (concept)
• OpenTelemetry Tracing API specification, span name guidance "most general string ... low cardinality" (Apache-2.0, concept)
• ai-automation by Sandro Maglione (inspiration, independently re-implemented)
• anti-slop by Dillon Mulroy (MIT, concept re-implemented)
• eslint-plugin-unicorn no-array-callback-reference (MIT; rule concept, independently re-implemented)
• eslint-plugin-unicorn no-array-for-each (MIT; rule concept, independently re-implemented)
• eslint-plugin-unicorn no-array-method-this-argument (MIT; rule concept, independently re-implemented)
• eslint-plugin-unicorn no-array-sort (MIT; rule concept, independently re-implemented)
• executor by Rhys Sullivan, dotted snake_case span and attribute names such as mcp.auth.verify_api_key (MIT, naming-style inspiration)