opencode-effect-enforcer 0.2.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://www.schemastore.org/package.json",
+  "name": "opencode-effect-enforcer",
+  "version": "0.2.0",
+  "description": "OpenCode V2 plugin for Effect v4 skills, guidance, and pattern enforcement",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "effect",
+    "effect-ts"
+  ],
+  "homepage": "https://github.com/mpsuesser/opencode-effect-enforcer#readme",
+  "bugs": {
+    "url": "https://github.com/mpsuesser/opencode-effect-enforcer/issues"
+  },
+  "license": "MIT",
+  "author": "Marc Suesser",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mpsuesser/opencode-effect-enforcer.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": "./src/index.ts",
+  "files": [
+    "src",
+    "skills",
+    "guidance",
+    "patterns",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "fmt": "dprint fmt",
+    "fmt:check": "dprint check",
+    "lint": "oxlint -c oxlintrc.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "bun run fmt:check && bun run lint && bun run typecheck",
+    "prepublishOnly": "bun run check && bun run test"
+  },
+  "dependencies": {
+    "@ast-grep/napi": "^0.42.3",
+    "@opencode-ai/plugin": "0.0.0-next-17148",
+    "diff": "^9.0.0",
+    "effect": "4.0.0-rc.111",
+    "picomatch": "^4.0.3",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "@types/diff": "^8.0.0",
+    "@types/json-schema": "^7.0.15",
+    "@types/picomatch": "^4.0.2",
+    "dprint": "^0.50.2",
+    "oxlint": "^1.12.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "packageManager": "bun@1.3.14"
+}

package/patterns/avoid-any.md

@@ -0,0 +1,37 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-any
+description: Avoid using 'as any' or 'as unknown as' type assertions
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern:
+    - '$A as any'
+    - '$A as unknown'
+level: warning
+---
+
+# Avoid `as any` Type Assertions
+
+```haskell
+-- Transformation
+asAny      :: a → Any       -- erases type, defeats compiler
+asUnknown  :: a → Unknown   -- same problem with extra steps
+
+-- Instead
+decode     :: Schema a → Unknown → Either ParseError a
+guard      :: (a → Bool) → a → Maybe a
+generics   :: ∀ a. Constraint a ⇒ a → F a
+```
+
+```haskell
+-- Pattern
+bad  :: Unknown → T
+bad x = x `as` T                    -- trust me bro
+
+good :: Unknown → Either ParseError T
+good x = Schema.decode schemaT x    -- prove it
+```
+
+Using `as any` bypasses type checking entirely. The `as unknown as T` pattern is equivalent—casting through `unknown` still erases type information. Note: `as const` is acceptable—it narrows to literal types without erasing type safety.

package/patterns/avoid-data-tagged-error.md

@@ -0,0 +1,34 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-data-tagged-error
+description: Review Data.TaggedError usage; public or serialized errors should use Schema.TaggedError
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: Data.TaggedError($$$)
+level: info
+suggestSkills:
+    - effect-error-handling
+---
+
+# Prefer `Schema.TaggedError` for Public Errors
+
+```haskell
+-- Transformation
+Data.TaggedError   :: String -> { fields } -> Error   -- lightweight, not schema-backed
+Schema.TaggedError :: String -> { schemas } -> Error  -- serializable, RPC-ready
+```
+
+```haskell
+-- Pattern
+bad :: Error
+bad = class MyError extends Data.TaggedError("MyError")<{ message: string }>
+
+good :: Error
+good = class MyError extends Schema.TaggedError<MyError>()("MyError", {
+  message: Schema.String
+})
+```
+
+`Schema.TaggedError` provides serialization, RPC compatibility, and runtime validation. Prefer it for public, cross-module, persisted, or wire-visible failures. `Data.TaggedError` remains valid for lightweight module-internal errors that do not need schema encoding, so treat this finding as a design review rather than an automatic rewrite.

package/patterns/avoid-direct-json.md

@@ -0,0 +1,51 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-direct-json
+description: Consider using Schema.fromJsonString instead of direct JSON methods
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: JSON.$M($$$)
+level: info
+suggestSkills:
+    - effect-schema-composition
+---
+
+# Consider Schema JSON Codecs Instead of JSON Methods
+
+```haskell
+-- Transformation
+jsonParse     :: String → Any           -- returns Any, can throw
+jsonStringify :: a → String             -- no validation
+
+-- Instead
+fromJsonString :: Schema a → Schema String a
+unknownJson    :: Schema String unknown
+encodeJson     :: Schema a → a → String
+```
+
+```haskell
+-- Pattern
+bad :: String → IO User
+bad json = JSON.parse json        -- returns Any, throws on invalid
+
+good :: String → Either ParseError User
+good json = Schema.decodeUnknownSync(Schema.fromJsonString(User)) json
+
+unknownJson = Schema.fromJsonString(Schema.Unknown)
+
+-- Bidirectional
+data User = Schema.Class "User"
+  { id   :: Schema.Number
+  , name :: Schema.String
+  }
+
+decode :: String → Either ParseError User
+decode = Schema.decodeUnknownSync(Schema.fromJsonString(User))
+
+encode :: User → String
+encode = Schema.encodeSync(Schema.fromJsonString(User))
+```
+
+`JSON.parse` returns `any` and throws on invalid input. `Schema.fromJsonString(...)` provides typed, validated JSON parsing and encoding. Use `Schema.fromJsonString(Schema.Unknown)` when the JSON shape is intentionally unknown; `Schema.UnknownFromJsonString` is internal in current Effect v4. Direct JSON methods remain reasonable at narrow logging/debugging boundaries.

package/patterns/avoid-direct-tag-checks.md

@@ -0,0 +1,54 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-direct-tag-checks
+description: Avoid direct _tag property checks; use exported refinements/predicates
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - pattern: $A._tag === $B
+        - pattern: $A._tag !== $B
+        - pattern: switch ($A._tag) { $$$ }
+level: warning
+suggestSkills:
+    - effect-pattern-matching
+---
+
+# Avoid Direct `_tag` Property Checks
+
+```haskell
+-- Transformation
+directCheck :: Event → Bool
+directCheck e = e._tag == "FactRecorded"   -- fragile, poor narrowing
+
+-- Instead
+$is   :: Tag → Event → Bool                -- from TaggedEnum
+$match :: { Tag₁: h₁, Tag₂: h₂ } → Event → a  -- exhaustive matching
+```
+
+```haskell
+-- Pattern
+bad :: Event → Effect ()
+bad e
+  | e._tag == "FactRecorded" = handleFact e    -- manual check, fragile
+  | otherwise                = pure ()
+
+good :: Event → Effect ()
+good = $match
+  { FactRecorded:  handleFact
+  , QuestionAsked: handleQuestion
+  }                                            -- exhaustive, type-safe
+
+-- Or with predicates
+data Event = FactRecorded | QuestionAsked
+  deriving TaggedEnum
+
+isFactRecorded :: Event → Bool
+isFactRecorded = $is "FactRecorded"
+
+-- Refactoring-safe: rename tag in one place
+```
+
+Direct `_tag` checks don't narrow types correctly. Use `$is` for predicates or `$match` for exhaustive pattern matching via `Data.taggedEnum`.

package/patterns/avoid-expect-in-if.md

@@ -0,0 +1,52 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-expect-in-if
+description: Avoid nesting expect() calls inside if blocks in tests
+glob: '**/*.{test,spec}.{ts,tsx}'
+detector: ast
+rule:
+    pattern: expect($$$)
+    inside:
+        pattern: if ($$$) { $$$ }
+        stopBy: end
+level: warning
+suggestSkills:
+    - effect-testing
+---
+
+# Avoid `expect()` Inside `if` Blocks
+
+```haskell
+-- Anti-pattern
+testBad :: Effect ()
+testBad = do
+  result ← runTest
+  if isJust (value result)           -- condition false → silently passes!
+    then expect (name $ fromJust $ value result) `toBe` "test"
+    else pure ()                     -- hidden skip
+
+-- Pattern
+narrow :: Maybe a → Effect a
+narrow = assert "Expected value to be defined"
+
+testGood :: Effect ()
+testGood = do
+  result ← runTest
+  value  ← narrow (value result)     -- fails fast if Nothing
+  expect (name value) `toBe` "test"  -- type narrowed, safe
+```
+
+```haskell
+-- Transformation
+if value then expect(value.x) else skip    -- ✗ silent skip
+assert value; expect(value.x)               -- ✓ fail fast
+
+-- Alternative
+expect(value) `toBeDefined`
+assert value                                -- narrow for TS
+expect(value.name) `toBe` "test"
+```
+
+`if (x) { expect(x.y) }` silently passes when condition is false. Use `assert` to narrow types and fail fast.

package/patterns/avoid-mutable-state.md

@@ -0,0 +1,70 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-mutable-state
+description: Prefer Ref over let bindings for mutable state in Effect services
+glob: '**/*.ts'
+detector: ast
+rule:
+    pattern: let $$$DECLS
+    inside:
+        pattern: Layer.effect($$$)
+        stopBy: end
+level: info
+---
+
+# Prefer `Ref` Over `let` for Mutable State
+
+```haskell
+-- Transformation
+let x = v; x = v'       :: mutable binding   -- not fiber-safe
+Ref.make(v) >>= Ref.set :: Ref a -> Effect a -- fiber-safe, composable
+```
+
+```haskell
+-- Pattern
+bad :: Mutable let
+bad = let counter = 0
+bad = counter += 1
+
+good :: Ref
+good = const counterRef = yield* Ref.make(0)
+good = yield* Ref.update(counterRef, (n) => n + 1)
+```
+
+Shared mutable `let` bindings in Effect services are suspicious because they can hide fiber-visible state and lifecycle behavior. Prefer `Ref`, `SynchronizedRef`, or `Effect.cached` for state that is read or written through your service API.
+
+## When `let` Is Acceptable
+
+- Loop counters in non-effectful pure functions
+- Local temporaries in synchronous helpers
+- Destructuring reassignment in narrow scopes
+
+The `info` level reflects that `let` has legitimate uses — this pattern surfaces it for review, not as an error.
+
+## Scoped Mutable Collections Can Be Fine
+
+Small mutable collections inside `Layer.effect` or `InstanceState.make` are acceptable when all of the following are true:
+
+- the collection is private to the service implementation
+- its lifetime is tied to the layer or instance scope
+- callers only observe it through effectful service methods
+- cleanup/finalization is handled explicitly
+
+Examples include private `Map` values for registries, PubSub channel lookup tables, or runner maps inside a dedicated coordinator service.
+
+## When `Effect.cached` Replaces `let`
+
+Mutable fields used for deduplication or caching (`task?: Promise<T>`, `fiber?: Fiber<T>`, `result?: T`) should be replaced with `Effect.cached`:
+
+```ts
+// Before: mutable dedup tracking
+let task: Promise<Result> | undefined;
+const getResult = () => (task ??= computeExpensive());
+
+// After: Effect.cached inside service make block
+const cachedResult = yield* Effect.cached(computeExpensive());
+```
+
+For invalidatable caches, use `Effect.cachedInvalidateWithTTL(effect, Duration.infinity)` instead of rebinding a `let`.

package/patterns/avoid-native-fetch.md

@@ -0,0 +1,61 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-native-fetch
+description: Use Effect HTTP modules instead of native fetch
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: fetch($$$ARGS)
+level: warning
+suggestSkills:
+    - effect-http-client
+---
+
+# Use Effect HTTP Modules Instead of Native `fetch`
+
+```haskell
+-- Transformation
+fetch    :: String -> Promise Response       -- global side effect, untyped errors
+HttpClient :: Request -> Effect Response E R  -- typed, composable, testable
+
+-- Pattern
+bad :: String -> Promise Response
+bad url = fetch(url)                         -- untyped rejection, no retry/timeout
+bad url = fetch(url, { method: "POST" })     -- scattered options
+
+good :: String -> Effect User HttpError HttpClient
+good url = pipe(
+  HttpClient.get(url),
+  Effect.flatMap(HttpClientResponse.schemaBodyJson(User))
+)
+```
+
+```haskell
+-- Composable request building
+request :: Effect HttpClientRequest HttpBodyError
+request = pipe(
+  HttpClientRequest.post("/api/users"),
+  HttpClientRequest.bodyJson({ name: "Alice" })
+)
+
+-- With retry, timeout, tracing
+resilient :: Effect Response HttpError (HttpClient | Scope)
+resilient = pipe(
+  request,
+  Effect.flatMap(HttpClient.execute),
+  Effect.retry(Schedule.recurs(3)),
+  Effect.timeout(Duration.seconds(10))
+)
+
+-- Platform layer at entry point
+main = program.pipe(
+  Effect.provide(BunHttpClient.layer)    -- or NodeHttpClient.layer
+)
+```
+
+Native `fetch` produces untyped Promise rejections. Use `HttpClientRequest`, `HttpClientResponse`, and `HttpClient` from Effect for typed errors, composable request building, and testability via layer substitution.
+
+Exception: an explicit low-level platform implementation that cannot use Effect HTTP. Keep it isolated, lift it with `Effect.tryPromise`, propagate the supplied `AbortSignal`, classify status before decoding, and decode unknown bodies with `Schema`.
+
+References: EF-9b, Checklist #42 in effect-first-development.md

package/patterns/avoid-node-imports.md

@@ -0,0 +1,86 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-node-imports
+description: Use Effect platform abstractions instead of node: imports — catch-all for modules without a dedicated rule
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - all:
+              - kind: import_statement
+              - regex: '["'']node:[^"'']+["'']'
+              - not:
+                    regex: '["'']node:(?:fs(?:/promises)?|path|os|child_process|https?)["'']'
+        - all:
+              - pattern: require($SPEC)
+              - not:
+                    regex: 'node:(?:fs(?:/promises)?|path|os|child_process|https?)'
+        - all:
+              - pattern: import($SPEC)
+              - not:
+                    regex: 'node:(?:fs(?:/promises)?|path|os|child_process|https?)'
+constraints:
+    SPEC:
+        regex: '^["'']node:[^"'']+["'']$'
+level: warning
+suggestSkills:
+    - effect-platform-abstraction
+---
+
+# Use Effect Platform Services Instead of `node:` Imports
+
+This is the **catch-all** rule for `node:*` imports that don't have a more specific pattern. Modules with a dedicated rule are excluded here to avoid duplicate diagnostics:
+
+| `node:` module          | Dedicated rule                  |
+| ----------------------- | ------------------------------- |
+| `fs`, `fs/promises`     | `use-filesystem-service`        |
+| `path`                  | `use-path-service`              |
+| `os`                    | `use-temp-file-scoped`          |
+| `child_process`         | `use-command-executor-service`  |
+| `http`, `https`         | `use-http-client-service`       |
+
+Everything else (`node:stream`, `node:url`, `node:readline`, `node:crypto`, `node:net`, …) falls under this rule.
+
+```haskell
+-- Transformation
+import "node:*"     :: Node -> IO a        -- platform-coupled, untestable
+
+-- Instead
+effect services    :: Effect a R          -- platform-agnostic, testable
+```
+
+```haskell
+-- Pattern (catch-all examples — covered modules are routed to their dedicated rule)
+bad :: Node -> IO
+bad = do
+  stream <- "node:stream"                  -- → use Stream from effect
+  url    <- "node:url"                     -- → URL is a Schema codec
+  rl     <- "node:readline"                -- → use Terminal service
+
+good :: Effect a (Stream | Terminal | …)
+good = do
+  stream <- Stream.fromReadableStream      -- platform-agnostic
+  term   <- Terminal.Terminal              -- from effect
+```
+
+**Platform module mappings (full):**
+
+| `node:` import       | Effect Platform                                                       |
+| -------------------- | --------------------------------------------------------------------- |
+| `node:fs`            | `FileSystem.FileSystem`                                               |
+| `node:fs/promises`   | `FileSystem.FileSystem`                                               |
+| `node:path`          | `Path.Path`                                                           |
+| `node:os`            | `FileSystem.makeTempFileScoped` / `Path.Path` / platform layer        |
+| `node:child_process` | `ChildProcessSpawner` + `ChildProcess` from `effect/unstable/process` |
+| `node:http`          | `HttpClient.HttpClient`                                               |
+| `node:https`         | `HttpClient.HttpClient`                                               |
+| `node:stream`        | `Stream` from effect                                                  |
+| `node:readline`      | `Terminal.Terminal`                                                   |
+| `node:crypto`        | `Crypto` from `effect/unstable/crypto` or a wrapped Effect service    |
+
+**Exceptions:**
+
+- Build scripts and tooling config (`vite.config.ts`, `build.ts`, etc.)
+- Platform-specific layers that implement Effect platform services

package/patterns/avoid-non-null-assertion.md

@@ -0,0 +1,44 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-non-null-assertion
+description: Avoid using ! non-null assertion operator
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: $A!
+level: warning
+---
+
+# Avoid Non-Null Assertion Operator `!`
+
+```haskell
+-- Transformation
+bang :: a | Null → a        -- "trust me" → runtime crash on null
+safe :: a | Null → Maybe a  -- explicit handling required
+
+-- Instead
+optional  :: a?.b           -- optional chaining
+coalesce  :: a ?? default   -- nullish coalescing
+option    :: Option a       -- Effect's optional type
+guard     :: a → Maybe a    -- type guard proves existence
+```
+
+```haskell
+-- Pattern
+bad :: Map → Value
+bad map = map.get("key")!         -- crash if key missing
+
+good :: Map → Maybe Value
+good map = Option.fromNullishOr (map.get "key")
+
+-- Or with chaining
+safe :: User → Maybe Email
+safe user = user?.contact?.email ?? Nothing
+
+-- With Schema for external data
+validated :: Unknown → Either ParseError User
+validated = Schema.decode userSchema
+```
+
+The `!` operator is "trust me, this isn't null"—if wrong, runtime crash. Use `?.`, `??`, `Option`, or type guards for safe null handling.

package/patterns/avoid-object-type.md

@@ -0,0 +1,46 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-object-type
+description: Avoid using Object or {} as types
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - all:
+              - kind: type_identifier
+              - regex: '^Object$'
+        - all:
+              - kind: object_type
+              - regex: '^\{\}$'
+level: warning
+---
+
+# Avoid `Object` and `{}` as Types
+
+```haskell
+-- Transformation
+object :: Object                  -- accepts nearly anything
+empty  :: {}                      -- same problem, no structure
+
+-- Instead
+data User = User { id :: Int, name :: String }  -- explicit shape
+record :: Record String a                       -- dictionary with known value type
+unknown :: Unknown                              -- truly unknown, requires validation
+```
+
+```haskell
+-- Pattern
+bad :: Object → Effect ()
+bad obj = doSomething obj         -- what fields? what types?
+
+good :: User → Effect ()
+good user = doSomething user      -- clear structure, IDE support
+
+-- For unknown shapes
+decode :: Unknown → Either ParseError User
+decode = Schema.decode userSchema
+```
+
+`Object` and `{}` provide no type safety—they accept any non-null value. Use explicit types, `Record<K,V>`, `unknown`, or Schema for validation.

package/patterns/avoid-option-getorthrow.md

@@ -0,0 +1,39 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-option-getorthrow
+description: Avoid Option.getOrThrow - use Option.match or Option.getOrElse for safe unwrapping
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: $A.getOrThrow
+level: warning
+---
+
+# Avoid `Option.getOrThrow`
+
+```haskell
+-- Transformation
+getOrThrow :: Option a -> a            -- partial function, may throw
+
+-- Instead
+match      :: Option a -> { onNone, onSome } -> b   -- total, exhaustive
+getOrElse  :: (() -> a) -> Option a -> a             -- total, with default
+```
+
+```haskell
+-- Pattern
+bad :: Option User -> User
+bad opt = Option.getOrThrow opt           -- throws if None
+
+good :: Option User -> String
+good opt = Option.match opt
+  { onNone: \_ -> "unknown"
+  , onSome: \u -> u.name
+  }
+
+also_good :: Option User -> User
+also_good opt = Option.getOrElse opt \_ -> defaultUser
+```
+
+`Option.getOrThrow` defeats the purpose of using Option. Always handle both cases explicitly.

package/patterns/avoid-platform-coupling.md

@@ -0,0 +1,43 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-platform-coupling
+description: Binding packages should not import platform-specific packages like @effect/platform-bun
+glob: 'packages/*/binding/**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - all:
+              - kind: import_statement
+              - regex: '["'']@effect/platform-(?:bun|node)(?:/[^"'']*)?["'']'
+        - pattern: require($SPEC)
+        - pattern: import($SPEC)
+constraints:
+    SPEC:
+        regex: '^["'']@effect/platform-(?:bun|node)(?:/[^"'']*)?["'']$'
+level: warning
+suggestSkills:
+    - effect-platform-layers
+---
+
+# Avoid Platform Coupling in Bindings
+
+```haskell
+-- Transformation
+concrete :: @effect/platform-bun    -- tied to Bun runtime
+abstract :: effect services         -- portable across runtimes
+
+-- Pattern
+bad  :: packages/*/binding/
+bad  = import { BunServices } from "@effect/platform-bun"
+bad  = Layer.provide(BunServices.layer)        -- hardwired platform
+
+good :: packages/*/binding/
+good = Layer.provide(platformLayer)          -- no platform coupling
+good = -- runtime provides ChildProcessSpawner, FileSystem, etc.
+```
+
+Binding packages wrap external systems (CLIs, APIs, databases) and must be platform-agnostic. They should depend on abstract services from `effect` and its unstable namespaces, such as `FileSystem`, `Path`, `HttpClient`, and `ChildProcessSpawner`, but never on `@effect/platform-bun` or `@effect/platform-node` concrete implementations.
+
+Platform-specific layers (`BunServices.layer`, `NodeServices.layer`) belong in the runtime or CLI entry point, not in bindings. The runtime provides concrete implementations of abstract Effect services there.