opencode-effect-enforcer 0.2.0

package/patterns/effect-run-in-body.md

@@ -0,0 +1,58 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: effect-run-in-body
+description: Effect.runSync/runPromise/runFork should only be at entry points
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern:
+    - Effect.runSync
+    - Effect.runPromise
+    - Effect.runFork
+level: warning
+suggestSkills:
+    - effect-managed-runtime
+---
+
+# Effect.runSync / runPromise / runFork Only at Entry Points
+
+```haskell
+-- Transformation
+runSync    :: Effect a E R → a         -- escapes Effect, loses composition
+runPromise :: Effect a E R → Promise a -- same problem
+runFork    :: Effect a E R → Fiber a   -- same problem, async variant
+
+-- Instead: compose until boundary
+compose :: Effect a E R → Effect b E R → Effect (a, b) E R
+yield*  :: Effect a E R → a           -- inside Effect.gen only
+```
+
+```haskell
+-- Pattern
+bad :: Effect () R
+bad = do
+  result ← pure $ Effect.runSync someEffect   -- breaks composition!
+  doSomething result
+  -- can't retry, race, timeout the inner effect
+
+good :: Effect () R
+good = do
+  result ← someEffect                         -- still composable
+  doSomething result
+  -- can wrap entire program with retry, race, timeout
+
+-- Entry points only
+main :: IO ()
+main = Effect.runMain program              -- ✓ application boundary
+
+handler :: Request → IO Response
+handler req = Effect.runPromise (handle req)  -- ✓ API boundary
+
+test :: Spec
+test = Effect.runPromise (testProgram)        -- ✓ test boundary
+```
+
+Running effects mid-logic breaks composition. Keep effects as values until entry points (main, handlers, tests).
+
+`Effect.runFork` is just as much a runtime escape as `runSync` / `runPromise`: it materialises a `Fiber` at the call site instead of composing with `Effect.forkChild` / `Effect.forkDetach` (which stay inside the Effect world and respect structural concurrency). Reserve all three for the entrypoint / test harness boundary.

package/patterns/imperative-loops.md

@@ -0,0 +1,76 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: imperative-loops
+description: Use functional transformations instead of imperative loops (for / while / do-while)
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - kind: for_statement
+        - kind: for_in_statement
+        - kind: while_statement
+        - kind: do_statement
+level: warning
+suggestSkills:
+    - effect-parallelization
+    - effect-scheduling
+---
+
+# Use Functional Transformations
+
+```haskell
+-- Array operations
+map     :: [a] → (a → b) → [b]
+filter  :: [a] → (a → Bool) → [a]
+reduce  :: [a] → b → (b → a → b) → b
+filterMap :: [a] → (a → Option b) → [b]   -- single pass
+
+-- Record operations
+Record.map        :: {k: a} → (a → b) → {k: b}
+Record.filter     :: {k: a} → (a → Bool) → {k: a}
+Record.filterMap  :: {k: a} → (a → Option b) → {k: b}
+
+-- Effectful iteration
+Effect.forEach :: [a] → (a → Effect b) → Effect [b]
+```
+
+```haskell
+-- Bad: Imperative with mutations (any flavor of loop)
+bad₁ :: [Number] → [Number]
+bad₁ numbers = do
+  result ← []
+  for n in numbers do                       -- ✗ ForOf
+    if n % 2 == 0 then result.push(n * n)
+  return result
+
+bad₂ :: Effect ()
+bad₂ = do
+  while (not done) do                       -- ✗ While
+    yield* step
+
+bad₃ :: Effect ()
+bad₃ = do
+  repeat                                    -- ✗ DoWhile
+    yield* step
+  until done
+
+-- Good: Functional composition
+good :: [Number] → [Number]
+good numbers =
+  filterMap numbers λn →
+    if n % 2 == 0
+    then Option.some(n * n)
+    else Option.none()
+
+goodEffect :: [Item] → Effect ()
+goodEffect items = Effect.forEach items processItem { concurrency: 4 }
+
+goodRecurring :: Effect ()
+goodRecurring = step & Effect.repeat (Schedule.spaced (Duration.seconds 1))
+```
+
+Imperative loops — `for`, `for ... in`, `for ... of`, `while`, `do ... while` — encourage mutation and break composition. Use `Arr.map` / `Arr.filter` / `Arr.filterMap` / `Arr.reduce` for pure transformations, `Effect.forEach` for effectful iteration (with explicit `concurrency`), and `Effect.repeat` plus `Schedule` for recurring effects.
+
+Note: in tree-sitter TypeScript, `for ... of` and `for ... in` share the same AST kind (`for_in_statement`), so listing `for_in_statement` covers both.

package/patterns/prefer-arr-sort.md

@@ -0,0 +1,52 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: prefer-arr-sort
+description: Use Arr.sort with explicit Order instead of native Array.prototype.sort
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    pattern: $A.sort($$$)
+    not:
+        pattern: Arr.sort($$$)
+level: warning
+---
+
+# Use `Arr.sort` with Explicit `Order`
+
+```haskell
+-- Transformation
+native  :: [a] -> (a -> a -> Number) -> [a]   -- mutates in place, untyped comparator
+arrSort :: [a] -> Order a -> [a]               -- pure, typed, composable
+
+-- Pattern
+bad :: [User] -> [User]
+bad users = users.sort((a, b) => a.name.localeCompare(b.name))
+  -- mutates original, comparator is untyped
+
+good :: [User] -> [User]
+good users = Arr.sort(users, byName)
+  where byName = Order.mapInput(Order.String, (u: User) => u.name)
+  -- pure copy, typed ordering, composable
+```
+
+```haskell
+-- Composing orders
+byNameThenAge :: Order User
+byNameThenAge = Order.combine(
+  Order.mapInput(Order.String, _.name),
+  Order.mapInput(Order.Number, _.age)
+)
+
+sorted :: [User] -> [User]
+sorted = Arr.sort byNameThenAge
+
+-- Reverse
+descending :: [User] -> [User]
+descending = Arr.sort (Order.reverse byName)
+```
+
+Native `.sort()` mutates the array in place and uses an untyped comparator. `Arr.sort` from `effect/Array` returns a new sorted array using a composable, typed `Order`.
+
+References: EF-38 in effect-first-development.md

package/patterns/prefer-duration-values.md

@@ -0,0 +1,56 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: prefer-duration-values
+description: Use Duration helpers instead of numeric duration literals
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - pattern: 'Effect.sleep($DURATION)'
+        - pattern: 'Effect.delay($EFFECT, $DURATION)'
+        - pattern: 'Effect.delay($DURATION)'
+        - pattern: 'Effect.timeout($EFFECT, $DURATION)'
+        - pattern: 'Effect.timeout($DURATION)'
+        - pattern: 'Effect.timeoutOption($EFFECT, $DURATION)'
+        - pattern: 'Effect.timeoutOption($DURATION)'
+        - pattern: 'Effect.timeoutOrElse($EFFECT, { duration: $DURATION, $$$REST })'
+        - pattern: 'Effect.timeoutOrElse({ duration: $DURATION, $$$REST })'
+        - pattern: 'Schedule.duration($DURATION)'
+        - pattern: 'Schedule.during($DURATION)'
+        - pattern: 'Schedule.exponential($DURATION)'
+        - pattern: 'Schedule.fibonacci($DURATION)'
+        - pattern: 'Schedule.fixed($DURATION)'
+        - pattern: 'Schedule.spaced($DURATION)'
+        - pattern: 'Schedule.windowed($DURATION)'
+constraints:
+    DURATION:
+        kind: number
+level: warning
+suggestSkills:
+    - effect-scheduling
+    - effect-testing
+---
+
+# Prefer `Duration` Values
+
+```haskell
+-- Transformation
+number   :: milliseconds? seconds? unclear
+Duration :: explicit time unit
+```
+
+```typescript
+// Bad
+Effect.sleep(1000);
+program.pipe(Effect.timeout(5000));
+Schedule.spaced(250);
+
+// Good
+Effect.sleep(Duration.seconds(1));
+program.pipe(Effect.timeout(Duration.seconds(5)));
+Schedule.spaced(Duration.millis(250));
+```
+
+Numeric duration literals obscure units and make timeout/retry policies harder to review. Use `Duration.millis`, `Duration.seconds`, or another `effect/Duration` constructor so time windows are explicit.

package/patterns/prefer-effect-fn.md

@@ -0,0 +1,161 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: prefer-effect-fn
+description: Service methods should use Effect.fn for automatic tracing instead of plain Effect.gen wrappers
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - pattern: ($$$ARGS) => Effect.gen($$$BODY)
+        - pattern: '$NAME: ($$$ARGS) => Effect.gen($$$BODY)'
+        - all:
+              - kind: method_definition
+              - has:
+                    field: body
+                    regex: Effect\.gen
+        - all:
+              - kind: pair
+              - has:
+                    pattern: function($$$ARGS) { return Effect.gen($$$BODY) }
+    inside:
+        any:
+            - pattern: Layer.effect($$$)
+            - pattern: Layer.effectContext($$$)
+            - pattern: Layer.succeed($$$)
+        stopBy: end
+    not:
+        inside:
+            pattern: Effect.fn($$$)($$$)
+            stopBy: end
+level: warning
+suggestSkills:
+    - effect-service-implementation
+---
+
+# Prefer `Effect.fn` for Service Methods
+
+```haskell
+-- Transformation
+Effect.gen :: (() -> Generator) -> Effect      -- no tracing, anonymous
+Effect.fn  :: String -> (...args -> Effect)     -- named, auto-traced span
+```
+
+```haskell
+-- Pattern
+bad :: Service method
+bad = {
+  getUser: (id: UserId) =>
+    Effect.gen(function* () {                  -- anonymous, no span
+      ...
+    })
+}
+
+good :: Service method
+good = {
+  getUser: Effect.fn("UserService.getUser")(
+    (id: UserId) =>                            -- named span, auto-traced
+      Effect.gen(function* () {
+        ...
+      })
+  )
+}
+```
+
+`Effect.fn` wraps a function to automatically create a traced span with the given name. Use it for all service method implementations to get observability for free.
+
+## Format
+
+```typescript
+const methodName = Effect.fn('ServiceName.methodName')(function* (
+	arg1: Type1,
+	arg2: Type2
+) {
+	// implementation using yield*
+});
+```
+
+Key details:
+
+- **Naming convention**: `"ServiceName.methodName"` — matches the service class and method
+- **Generator shorthand**: Pass a generator function directly to `Effect.fn` — no need for an intermediate arrow wrapping `Effect.gen`
+- **Wraps the function**: `Effect.fn` takes the entire implementation function as a generator
+
+## Complete Before/After
+
+```typescript
+// BEFORE — plain arrow functions, no tracing
+export class UserRepository extends Context.Service<UserRepository>()(
+	'@services/UserRepository',
+	{
+		make: Effect.gen(function* () {
+			const db = yield* DatabaseClient;
+
+			return {
+				findById: (id: string): Effect.Effect<User, UserNotFound> =>
+					Effect.gen(function* () {
+						const row = yield* db.query(
+							'SELECT * FROM users WHERE id = ?',
+							id
+						);
+						if (!row)
+							return yield* new UserNotFound({
+								id,
+								message: `Not found: ${id}`
+							});
+						return row as User;
+					}),
+
+				create: (
+					data: CreateUserData
+				): Effect.Effect<User, DuplicateUser> =>
+					Effect.gen(function* () {
+						return yield* db.insert('users', data);
+					})
+			};
+		})
+	}
+) {}
+
+// AFTER — Effect.fn, every method gets a traced span
+export class UserRepository extends Context.Service<UserRepository>()(
+	'@services/UserRepository',
+	{
+		make: Effect.gen(function* () {
+			const db = yield* DatabaseClient;
+
+			const findById = Effect.fn('UserRepository.findById')(
+				(id: string): Effect.Effect<User, UserNotFound> =>
+					Effect.gen(function* () {
+						const row = yield* db.query(
+							'SELECT * FROM users WHERE id = ?',
+							id
+						);
+						if (!row)
+							return yield* new UserNotFound({
+								id,
+								message: `Not found: ${id}`
+							});
+						return row as User;
+					})
+			);
+
+			const create = Effect.fn('UserRepository.create')(
+				(data: CreateUserData): Effect.Effect<User, DuplicateUser> =>
+					Effect.gen(function* () {
+						return yield* db.insert('users', data);
+					})
+			);
+
+			return { findById, create };
+		})
+	}
+) {}
+```
+
+## When NOT to use Effect.fn
+
+- Top-level programs or scripts (not service methods)
+- One-off effects that aren't part of a service interface
+- Simple succeed/fail expressions that don't benefit from tracing

package/patterns/prefer-match-over-switch.md

@@ -0,0 +1,48 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: prefer-match-over-switch
+description: Use Match from Effect instead of native switch statements
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: 'switch ($X) { $$$ }'
+level: warning
+suggestSkills:
+    - effect-pattern-matching
+---
+
+# Use `Match` Instead of `switch`
+
+```haskell
+-- Transformation
+switch :: a -> { case₁: b, ..., default: b }  -- non-exhaustive, fall-through risk
+Match  :: a -> Matcher a b                     -- exhaustive, composable, type-safe
+
+-- Pattern
+bad :: Phase -> String
+bad phase = switch phase of
+  "idle"    -> "waiting"
+  "running" -> "active"
+  _         -> "unknown"              -- default hides new variants
+
+good :: Phase -> String
+good phase = Match.value(phase).pipe(
+  Match.when("idle", \_ -> "waiting"),
+  Match.when("running", \_ -> "active"),
+  Match.exhaustive                    -- compiler error if variant added
+)
+```
+
+```haskell
+-- For tagged unions
+matchTagged :: Event -> String
+matchTagged = Match.value >>> pipe
+  Match.tag("Created", \e -> "new: " <> e.id)
+  Match.tag("Completed", \e -> "done: " <> e.id)
+  Match.exhaustive
+```
+
+`switch` has fall-through semantics and non-exhaustive `default` cases that hide new variants at compile time. `Match` from Effect is exhaustive, composable, and type-safe — the compiler will error when new variants are added.
+
+References: EF-7 in effect-first-development.md

package/patterns/prefer-option-over-null.md

@@ -0,0 +1,56 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: prefer-option-over-null
+description: Consider using Option instead of union with null or undefined
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - all:
+              - kind: literal_type
+              - regex: '^null$'
+              - inside:
+                    kind: union_type
+                    stopBy: neighbor
+        - all:
+              - kind: literal_type
+              - regex: '^undefined$'
+              - inside:
+                    kind: union_type
+                    stopBy: neighbor
+level: info
+---
+
+# Consider `Option` Instead of `| null` / `| undefined`
+
+```haskell
+-- Transformation
+nullable :: T | Null              -- scattered null checks
+undef    :: T | Undefined         -- same problem, different keyword
+option   :: Option T              -- composable, chainable
+
+-- Option operations
+map      :: (a → b) → Option a → Option b
+flatMap  :: (a → Option b) → Option a → Option b
+filter   :: (a → Bool) → Option a → Option a
+getOrElse :: a → Option a → a
+```
+
+```haskell
+-- Pattern
+bad :: Id → User | Null
+bad id = users.get id             -- caller must check null
+
+good :: Id → Option User
+good id = Option.fromNullishOr (users.get id)
+
+-- Composition
+findEmail :: Id → Option Email
+findEmail = good >=> (_.email >>> Option.fromNullishOr)
+```
+
+`Option<T>` provides chainable operations. Use `| null` or `| undefined` only at external boundaries (JSON, DOM, third-party libs).
+
+Both `| null` and `| undefined` carry the same modelling cost — every consumer needs a defensive check, and `Option`'s combinators (`map`, `flatMap`, `filter`, `getOrElse`, `match`) replace those checks with a single composable shape. `| null | undefined` is the worst of both; convert it at the boundary with `Option.fromNullishOr`.

package/patterns/prefer-redacted-config.md

@@ -0,0 +1,70 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: prefer-redacted-config
+description: Use Config.redacted or Schema.Redacted for secret-like configuration values
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - pattern: Config.string($KEY)
+        - pattern: Config.nonEmptyString($KEY)
+        - all:
+              - kind: pair
+              - has:
+                    field: key
+                    regex: '(?i)(api[_-]?key|auth[_-]?token|token|secret|password|passwd|private[_-]?key|client[_-]?secret|database[_-]?url|db[_-]?url|connection[_-]?string|dsn)'
+              - has:
+                    field: value
+                    regex: '^Schema\.(String|NonEmptyString)(\.|$)'
+              - inside:
+                    pattern: Config.schema($$$)
+                    stopBy: end
+constraints:
+    KEY:
+        regex: '(?i)^["''][^"'']*(api[_-]?key|auth[_-]?token|token|secret|password|passwd|private[_-]?key|client[_-]?secret|database[_-]?url|db[_-]?url|connection[_-]?string|dsn)[^"'']*["'']$'
+level: warning
+suggestSkills:
+    - effect-config
+---
+
+# Prefer Redacted Config for Secrets
+
+```haskell
+-- Transformation
+Config.string secretKey    :: String            -- easy to log accidentally
+Config.redacted secretKey  :: Redacted String   -- hidden from logs/toString
+```
+
+```typescript
+// Bad
+const apiKey = Config.string('API_KEY');
+const token = Config.nonEmptyString('GITHUB_TOKEN');
+
+// Good
+const apiKey = Config.redacted('API_KEY');
+const token = Config.redacted('GITHUB_TOKEN');
+```
+
+For structured config schemas, wrap secret-like string fields in `Schema.Redacted`:
+
+```typescript
+// Bad
+const AppConfig = Config.schema(
+	Schema.Struct({
+		apiKey: Schema.String,
+		password: Schema.NonEmptyString
+	})
+);
+
+// Good
+const AppConfig = Config.schema(
+	Schema.Struct({
+		apiKey: Schema.Redacted(Schema.String),
+		password: Schema.Redacted(Schema.String)
+	})
+);
+```
+
+Secrets should remain redacted from the moment they enter the program. Use `Config.redacted` for primitive config values and `Schema.Redacted(Schema.String)` for schema-based config fields.

package/patterns/prefer-schema-class.md

@@ -0,0 +1,54 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: prefer-schema-class
+description: Review Schema.Struct used for decoded or domain objects; prefer Schema.Class when identity matters
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: Schema.Struct($$$)
+level: info
+suggestSkills:
+    - effect-domain-modeling
+---
+
+# Use `Schema.Class` Instead of `Schema.Struct`
+
+```haskell
+-- Transformation
+Schema.Struct :: { fields } -> Schema { fields }     -- anonymous, no constructor
+Schema.Class  :: String -> { fields } -> Class        -- named, constructable, extensible
+
+-- Pattern
+bad :: Schema
+bad = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String
+})
+-- anonymous type, no constructor, no instanceof
+
+good :: Schema
+good = class User extends Schema.Class<User>("User")({
+  id: Schema.String,
+  name: Schema.String
+}) {}
+-- named type, constructor, instanceof, optional annotations when useful
+```
+
+```haskell
+-- Benefits of Schema.Class
+construct :: User
+construct = new User({ id: "1", name: "Alice" })
+
+check :: unknown -> Bool
+check = (x) => x instanceof User
+
+extend :: Schema
+extend = class Admin extends User.extend<Admin>("Admin")({
+  role: Schema.Literal("admin")
+}) {}
+```
+
+`Schema.Struct` produces an anonymous schema without a constructor or `instanceof` support. `Schema.Class` provides a named type, constructor, extensibility, and optional annotation support when docs or introspection benefit from it. Prefer `Schema.Class` for decoded domain/API shapes, union members, and values that need identity. `Schema.Struct` remains appropriate for local structural composition, configuration internals, and schemas where class identity adds no value, so review this informational finding in context.
+
+References: EF-3, EF-33 in effect-first-development.md