opencode-effect-enforcer 0.2.0

package/patterns/require-effect-concurrency.md

@@ -0,0 +1,83 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: require-effect-concurrency
+description: Specify concurrency explicitly for Effect collection combinators
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - all:
+              - pattern:
+                    context: Effect.forEach($EACH)
+                    strictness: signature
+              - regex: '^Effect\.forEach'
+        - all:
+              - pattern:
+                    context: Effect.forEach($A, $OPTIONS)
+                    strictness: signature
+              - regex: '^Effect\.forEach'
+        - all:
+              - pattern:
+                    context: Effect.forEach($A, $B, $OPTIONS)
+                    strictness: signature
+              - regex: '^Effect\.forEach'
+        - all:
+              - pattern:
+                    context: Effect.all($ALL)
+                    strictness: signature
+              - regex: '^Effect\.all'
+        - all:
+              - pattern:
+                    context: Effect.all($A, $OPTIONS)
+                    strictness: signature
+              - regex: '^Effect\.all'
+        - all:
+              - pattern:
+                    context: Effect.validate($VALIDATE)
+                    strictness: signature
+              - regex: '^Effect\.validate'
+        - all:
+              - pattern:
+                    context: Effect.validate($A, $OPTIONS)
+                    strictness: signature
+              - regex: '^Effect\.validate'
+        - all:
+              - pattern:
+                    context: Effect.validate($A, $B, $OPTIONS)
+                    strictness: signature
+              - regex: '^Effect\.validate'
+constraints:
+    OPTIONS:
+        not:
+            all:
+                - kind: object
+                - has:
+                      regex: '\bconcurrency\b'
+level: warning
+suggestSkills:
+    - effect-concurrency-testing
+---
+
+# Specify Effect Collection Concurrency
+
+```haskell
+-- Transformation
+Effect.forEach xs f           -- concurrency intent implicit
+Effect.forEach xs f opts      -- concurrency intent explicit
+```
+
+```typescript
+// Bad
+Effect.forEach(items, processItem);
+Effect.all(tasks);
+Effect.validate(inputs, validateInput, { discard: true });
+
+// Good
+Effect.forEach(items, processItem, { concurrency: 1 });
+Effect.all(tasks, { concurrency: 'unbounded' });
+Effect.validate(inputs, validateInput, { concurrency: 4, discard: true });
+```
+
+Even sequential execution is a concurrency decision. Specify `concurrency` on `Effect.forEach`, `Effect.all`, and `Effect.validate` so throughput and ordering intent are reviewable at the call site.

package/patterns/stream-large-files.md

@@ -0,0 +1,63 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: stream-large-files
+description: Review whole-file reads when the path appears large or unbounded
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - pattern: fs.readFile($PATH)
+        - pattern: fs.readFileString($PATH)
+constraints:
+    PATH:
+        any:
+            - regex: '(large|huge|dump|archive|dataset|backup|export|log|logs|jsonl|ndjson|csv)'
+            - pattern: $DIR + $FILE
+            - pattern: path.join($$$)
+            - pattern: path.resolve($$$)
+            - pattern: $FILES[$I]
+            - pattern: $ITEM.path
+level: info
+suggestSkills:
+    - effect-stream
+---
+
+# Consider Streaming Large Files
+
+```haskell
+-- Transformation
+readFile       :: FilePath → Effect String FileSystem   -- entire file in memory
+stream         :: FilePath → Stream Chunk FileSystem    -- incremental chunks
+
+-- For large files
+fs.stream path { chunkSize: 64 * 1024 }
+  |> decodeText "utf-8"
+  |> splitLines
+  |> map processLine
+  |> runDrain
+```
+
+```haskell
+-- Pattern
+bad :: FilePath → Effect String FileSystem
+bad path = readFileString path          -- OOM on gigabyte files
+
+good :: FilePath → Effect () FileSystem
+good path = pipe
+  (fs.stream path { chunkSize: 65536 })
+  $ Stream.decodeText "utf-8"
+  $ Stream.splitLines
+  $ Stream.map processLine
+  $ Stream.runDrain                     -- constant memory usage
+
+-- When to stream
+shouldStream :: FileSize → Bool
+shouldStream size
+  | size > megabytes 100 = True         -- definitely stream
+  | lineByLine needed    = True         -- stream for efficiency
+  | otherwise            = False        -- readFile is fine
+```
+
+`readFile` loads entire file into memory. Use `fs.stream` for large files or line-by-line processing to avoid OOM errors.

package/patterns/throw-in-effect-gen.md

@@ -0,0 +1,62 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: throw-in-effect-gen
+description: Do not throw inside Effect.gen / Effect.fn / Effect.fnUntraced — use yield* Effect.fail() instead. The `try:` callback of Effect.try / Effect.tryPromise is exempt.
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    pattern: throw $ERR
+    inside:
+        any:
+            - pattern: Effect.gen($$$ARGS)
+            - pattern: Effect.fn($$$ARGS)
+            - pattern: Effect.fn($$$ARGS)($$$BODY)
+            - pattern: Effect.fnUntraced($$$ARGS)
+        stopBy: end
+    not:
+        inside:
+            any:
+                - pattern: 'Effect.try({ try: $$$ })'
+                - pattern: 'Effect.tryPromise({ try: $$$ })'
+            stopBy: end
+level: critical
+suggestSkills:
+    - effect-error-handling
+---
+
+# Do Not `throw` Inside `Effect.gen`
+
+```haskell
+-- Transformation
+throw :: Error -> ⊥                        -- untyped, uncatchable by Effect
+yield* Effect.fail :: TaggedError -> E ⊥ E  -- typed, catchable via catchTag
+```
+
+```haskell
+-- Pattern
+bad :: Effect.gen
+bad = Effect.gen \_ -> do
+  throw new Error("not found")            -- bypasses Effect error channel
+
+good :: Effect.gen
+good = Effect.gen \_ -> do
+  yield* Effect.fail(new UserNotFoundError({ message: "not found" }))
+  -- typed error, catchable with catchTag("UserNotFoundError", ...)
+```
+
+`throw` inside `Effect.gen` / `Effect.fn` / `Effect.fnUntraced` creates a defect (untyped), not a typed error. Use `yield* Effect.fail(new SchemaTaggedError(...))` to keep errors in the typed channel.
+
+## Exemption: the `try:` callback of `Effect.try` / `Effect.tryPromise`
+
+Throwing inside the `try:` callback of `Effect.try({ try, catch })` or `Effect.tryPromise({ try, catch })` is the *intended* shape — the paired `catch:` handler captures the throwable back into the typed error channel:
+
+```typescript
+Effect.tryPromise({
+	try: () => fetch(url), // ✓ throws here are caught by `catch` below
+	catch: (cause) => new FetchError({ url, message: String(cause) })
+});
+```
+
+The rule's `not.inside` clause carves out exactly that shape so legitimate `Effect.try` / `Effect.tryPromise` callbacks don't fire the diagnostic. Throws anywhere else inside an `Effect.gen` / `Effect.fn` / `Effect.fnUntraced` body remain flagged.

package/patterns/use-clock-service.md

@@ -0,0 +1,45 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: use-clock-service
+description: Use Effect DateTime instead of JS Date
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern:
+    - 'new Date($$$)'
+    - 'Date.$M($$$)'
+level: warning
+suggestSkills:
+    - effect-testing
+---
+
+# Use Effect DateTime Instead of JS Date
+
+```haskell
+-- Transformation
+newDate   :: IO Date              -- impure, non-deterministic
+dateNow   :: IO Milliseconds      -- side effect, untestable
+
+-- Instead
+now       :: Effect DateTime R    -- R includes Clock
+currentMs :: Effect Millis Clock  -- explicit dependency
+```
+
+```haskell
+-- Pattern
+bad :: IO Timestamp
+bad = Date.now                    -- where R = ∅, untestable
+
+good :: Effect Timestamp Clock
+good = Clock.currentTimeMillis    -- where R ⊃ Clock, testable
+
+-- In tests
+test :: Effect () TestClock
+test = do
+  TestClock.adjust (minutes 5)    -- deterministic time
+  result ← good
+  assert (result == expected)
+```
+
+Direct `Date` usage is non-deterministic. Use `DateTime.now` or `Clock.currentTimeMillis` for testable time operations via `TestClock`.

package/patterns/use-command-executor-service.md

@@ -0,0 +1,54 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: use-command-executor-service
+description: Use Effect's ChildProcessSpawner instead of node:child_process
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - all:
+              - kind: import_statement
+              - regex: '["''](?:node:)?child_process["'']'
+        - pattern: require($SPEC)
+        - pattern: import($SPEC)
+constraints:
+    SPEC:
+        regex: '^["''](?:node:)?child_process["'']$'
+level: warning
+suggestSkills:
+    - effect-command-executor
+    - effect-platform-abstraction
+---
+
+# Use Effect Process Services Instead of `child_process`
+
+```haskell
+-- Transformation
+import "node:child_process" :: Node → IO Process    -- callback-spaghetti, untyped
+spawn / exec / execFile     :: Args → Promise / Stream  -- ad-hoc lifecycle
+
+-- Instead
+ChildProcess        :: Args → ChildProcess           -- pure value, declarative
+ChildProcessSpawner :: Effect a ChildProcessSpawner  -- typed I/O, scoped lifetime
+```
+
+```haskell
+-- Pattern (Effect v4 — effect/unstable/process)
+bad :: () → IO String
+bad = exec "git" ["status"] (cb)              -- callback, untyped, no cancellation
+
+good :: Effect String ChildProcessSpawner
+good = do
+  spawner ← ChildProcessSpawner.ChildProcessSpawner
+  spawner.string (ChildProcess.make "git" ["status"])
+  -- typed output, error channel, scoped lifetime
+```
+
+Direct `child_process` imports give you callback APIs, manual lifecycle, and no error channel. Use `ChildProcessSpawner` and `ChildProcess` from `effect/unstable/process` for typed errors, scoped resource lifetime, and platform-agnostic process spawning.
+
+**Exceptions:**
+
+- Build scripts and tooling config that legitimately couple to Node
+- Platform-specific layers that implement `ChildProcessSpawner`

package/patterns/use-console-service.md

@@ -0,0 +1,54 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: use-console-service
+description: Use Effect Console or Effect.log instead of console
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: console.$M($$$)
+level: warning
+suggestSkills:
+    - effect-observability
+---
+
+# Use Effect Console Instead of console.\*
+
+```haskell
+-- Transformation
+console.log   :: String → IO ()      -- side effect, not composable
+console.error :: String → IO ()      -- same problem
+
+-- Instead
+Console.log   :: String → Effect () Console
+Effect.log    :: String → Effect () ∅        -- with structured logging
+Effect.logError :: String → Effect () ∅
+```
+
+```haskell
+-- Pattern
+bad :: Effect ()
+bad = do
+  Effect.sync \_ → console.error "Error:" error   -- ceremony with no benefit
+
+good :: Effect ()
+good = Console.error ("Error:" <> show error)     -- proper Effect console
+
+better :: Effect ()
+better = Effect.logError error                    -- structured, with context
+
+-- Why Effect logging
+structured :: Effect () ∅
+structured = do
+  Effect.logInfo "Processing" `withLogSpan` "request"
+  -- adds: timestamp, span, log level, structured context
+
+-- Testable
+test :: Effect () TestConsole
+test = do
+  program
+  logs ← TestConsole.output
+  assert (logs `contains` "expected message")
+```
+
+`console.*` in Effect code breaks the paradigm. Use `Console` service or `Effect.log*` for structured, testable logging.

package/patterns/use-filesystem-service.md

@@ -0,0 +1,59 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: use-filesystem-service
+description: Use FileSystem service instead of direct Node.js fs / fs/promises imports
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - all:
+              - kind: import_statement
+              - regex: '["''](?:node:)?fs(?:/promises)?["'']'
+        - pattern: require($SPEC)
+        - pattern: import($SPEC)
+constraints:
+    SPEC:
+        regex: '^["''](?:node:)?fs(?:/promises)?["'']$'
+level: high
+suggestSkills:
+    - effect-filesystem
+---
+
+# Use FileSystem Service Instead of `fs` / `fs/promises`
+
+```haskell
+-- Transformation
+import "node:fs"           :: Node → IO a            -- platform-coupled, untestable
+import "fs"                :: Node → IO a            -- same problem
+import "node:fs/promises"  :: Node → Promise a       -- Promise-based, not Effect
+import "fs/promises"       :: Node → Promise a       -- same problem
+
+-- Instead
+FileSystem                 :: Effect a FileSystem    -- platform-agnostic, Effect-native
+```
+
+```haskell
+-- Pattern
+bad :: FilePath → IO String
+bad path = fs.readFileSync path "utf-8"   -- R = Node, untestable, blocks event loop
+
+bad₂ :: FilePath → Promise String
+bad₂ path = fsPromises.readFile path "utf-8"   -- Promise, not Effect
+
+good :: FilePath → Effect String FileSystem
+good path = do
+  fs ← FileSystem.FileSystem
+  fs.readFileString path                  -- R ⊃ FileSystem, portable, typed errors
+
+-- Platform provision at entry point
+main :: Effect () (FileSystem | Console | ...)
+main = program
+  & provide BunServices.layer    -- or NodeServices.layer
+  & runMain
+```
+
+Direct `fs` / `fs/promises` imports couple code to Node.js and bypass the Effect error channel. Use `FileSystem` from `effect` for portability across Node and Bun, with typed errors and composable I/O; provide the concrete platform layer only at the runtime boundary.
+
+This pattern subsumes the legacy `avoid-fs-promises` pattern — both `fs` and `fs/promises` are covered here.

package/patterns/use-http-client-service.md

@@ -0,0 +1,77 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: use-http-client-service
+description: Use Effect HttpClient instead of node:http / node:https
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - all:
+              - kind: import_statement
+              - regex: '["''](?:node:)?https?["'']'
+        - pattern: require($SPEC)
+        - pattern: import($SPEC)
+constraints:
+    SPEC:
+        regex: '^["''](?:node:)?https?["'']$'
+level: warning
+suggestSkills:
+    - effect-http-client
+    - effect-platform-abstraction
+---
+
+# Use Effect HttpClient Instead of `node:http` / `node:https`
+
+```haskell
+-- Transformation
+import "node:http"  :: Node → IO Request          -- low-level, callback-based
+import "node:https" :: Node → IO Request          -- same problem with TLS
+
+-- Instead
+HttpClient          :: Request → Effect Response  -- typed, composable, testable
+HttpClientRequest   :: Request builder            -- pure value, no side effects
+HttpClientResponse  :: Response codec helpers     -- schema-validated JSON, streams, etc.
+```
+
+```haskell
+-- Pattern
+bad :: URL → IO Response
+bad url = http.get url (cb)                       -- callback, untyped errors
+
+good :: URL → Effect User HttpClient
+good url = pipe
+  (HttpClient.get url)
+  (Effect.flatMap (HttpClientResponse.schemaBodyJson User))
+  -- schema-decoded body, typed error channel, layer-based testing
+```
+
+```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 (HttpClient | HttpBodyError)
+resilient = pipe
+  request
+  (Effect.flatMap HttpClient.execute)
+  (Effect.retry (Schedule.recurs 3))
+  (Effect.timeout (Duration.seconds 10))
+
+-- Provide platform layer at entry point
+main = program
+  & provide BunHttpClient.layer    -- or NodeHttpClient.layer
+```
+
+Direct `http` / `https` imports give you callback APIs, manual TLS plumbing, and no error channel. Use Effect's `HttpClient`, `HttpClientRequest`, and `HttpClientResponse` for typed errors, composable request building, declarative retry/timeout, and testability via layer substitution.
+
+**Exceptions:**
+
+- Platform-specific layers that implement `HttpClient.HttpClient`
+- Build scripts and tooling that legitimately need raw Node HTTP
+
+References: EF-9b in effect-first-development.md

package/patterns/use-path-service.md

@@ -0,0 +1,53 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: use-path-service
+description: Use Path service instead of direct Node.js path imports
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - all:
+              - kind: import_statement
+              - regex: '["''](?:node:)?path["'']'
+        - pattern: require($SPEC)
+        - pattern: import($SPEC)
+constraints:
+    SPEC:
+        regex: '^["''](?:node:)?path["'']$'
+level: warning
+suggestSkills:
+    - effect-path
+---
+
+# Use Path Service Instead of `path`
+
+```haskell
+-- Transformation
+import "node:path"  :: Node → Path a    -- platform-coupled
+import "path"       :: Node → Path a    -- same problem
+
+-- Instead
+Path               :: Effect Path Path  -- platform-agnostic
+```
+
+```haskell
+-- Pattern
+bad :: String → String → String
+bad dir file = path.join dir file      -- R = Node
+
+good :: String → String → Effect String Path
+good dir file = do
+  p ← Path.Path
+  p.join dir file                      -- R ⊃ Path, portable
+
+-- Path operations
+join      :: [String] → Effect String Path
+dirname   :: String → Effect String Path
+basename  :: String → Effect String Path
+extname   :: String → Effect String Path
+resolve   :: String → Effect String Path
+```
+
+Direct `path` imports couple code to Node.js. Use `Path` from `effect` for cross-platform path operations and provide the concrete platform layer at the runtime boundary.

package/patterns/use-random-service.md

@@ -0,0 +1,45 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: use-random-service
+description: Use Random service instead of Math.random()
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: Math.random()
+level: warning
+suggestSkills:
+    - effect-testing
+---
+
+# Use Random Service Instead of `Math.random()`
+
+```haskell
+-- Transformation
+mathRandom :: IO Float              -- impure, non-deterministic
+random     :: Effect Float Random   -- explicit dependency, testable
+
+-- Random operations
+next       :: Effect Float Random
+nextInt    :: Effect Int Random
+nextRange  :: (Int, Int) → Effect Int Random
+shuffle    :: [a] → Effect [a] Random
+```
+
+```haskell
+-- Pattern
+bad :: IO Int
+bad = floor (Math.random * 100)     -- R = ∅, untestable
+
+good :: Effect Int Random
+good = Random.nextIntBetween 0 100  -- R ⊃ Random, deterministic in tests
+
+-- In tests
+test :: Effect () TestRandom
+test = do
+  TestRandom.feedInts [42, 7, 13]   -- deterministic sequence
+  result ← good
+  assert (result == 42)
+```
+
+`Math.random()` is non-deterministic. Use `Random` service for reproducible randomness via `TestRandom.feed*` in tests.

package/patterns/use-temp-file-scoped.md

@@ -0,0 +1,66 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: use-temp-file-scoped
+description: Use makeTempFileScoped/makeTempDirectoryScoped instead of os.tmpdir() or non-scoped variants
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - all:
+              - kind: import_statement
+              - regex: '["''](?:node:)?os["'']'
+        - pattern: require($SPEC)
+        - pattern: import($SPEC)
+        - pattern: os.tmpdir()
+        - pattern: $FS.makeTempFile($$$)
+        - pattern: $FS.makeTempDirectory($$$)
+constraints:
+    SPEC:
+        regex: '^["''](?:node:)?os["'']$'
+level: warning
+suggestSkills:
+    - effect-filesystem
+---
+
+# Use Scoped Temp Files for Automatic Cleanup
+
+```haskell
+-- Transformation
+os.tmpdir        :: IO FilePath              -- Node-coupled, manual cleanup
+makeTempFile     :: Effect FilePath FS       -- manual cleanup required
+makeTempFileScoped :: Effect FilePath (FS | Scope)  -- auto cleanup
+
+-- Scoped resources
+withTempFile :: (FilePath → Effect a) → Effect a
+withTempFile use = scoped $ do
+  path ← makeTempFileScoped { prefix: "myapp-" }
+  use path
+  -- auto cleanup on scope exit, even on error
+```
+
+```haskell
+-- Pattern
+bad :: Effect () FS
+bad = do
+  tmpFile ← makeTempFile
+  writeFileString tmpFile "data"
+  remove tmpFile                    -- might not run on error!
+
+good :: Effect () (FS | Scope)
+good = scoped $ do
+  tmpFile ← makeTempFileScoped { prefix: "myapp-" }
+  writeFileString tmpFile "data"
+  -- auto removed when scope ends
+
+-- Directories too
+withTempDir :: Effect () (FS | Scope)
+withTempDir = scoped $ do
+  dir ← makeTempDirectoryScoped { prefix: "myapp-" }
+  path ← join dir "file.txt"
+  writeFileString path "data"
+  -- entire dir removed when scope ends
+```
+
+`makeTempFileScoped` provides automatic cleanup via Effect's scope. Never use `os.tmpdir()` (Node-coupled) or unscoped variants (leak resources).