Effect Solutions Compliance Audit

Audit a repository against Effect TypeScript best practices from effect.solutions. Follow this skill to produce a consistent, evidence-based compliance report.

Prerequisites

Load current effect.solutions recommendations:

effect-solutions list

Load guidance used by this checklist:

effect-solutions show tsconfig
effect-solutions show services-and-layers
effect-solutions show data-modeling
effect-solutions show error-handling
effect-solutions show config
effect-solutions show testing

Load the effect-ts skill for Effect-specific implementation patterns:

skill({ name: "effect-ts" })

Audit Checklist

1. TypeScript Configuration

Inspect tsconfig.base.json (or tsconfig.json) and verify:

exactOptionalPropertyTypes: true
strict: true
noUnusedLocals: true
declarationMap: true
sourceMap: true
Confirm Effect Language Service plugin is configured.
Confirm module setting matches project type (preserve/bundler for apps, NodeNext for libraries).

Reference: effect-solutions show tsconfig

2. Services & Layers Pattern

Search for Effect services and verify:

Confirm services are defined with Context.Tag.
Confirm tag identifiers follow @path/ServiceName pattern.
Confirm layers use Layer.effect or Layer.sync.
Confirm a single Effect.provide is applied at the entry point.

Reference: effect-solutions show services-and-layers

3. Data Modeling

Inspect data modeling and verify:

Confirm Schema.Class is used for records.
Confirm Schema.TaggedClass is used for variants.
Confirm branded types are used for primitives (IDs, emails, and similar values).
Confirm pattern matching uses Match.valueTags.

Reference: effect-solutions show data-modeling

4. Error Handling

Inspect error handling and verify:

Confirm Schema.TaggedError is used for domain errors.
Confirm error recovery uses catchTag/catchTags where appropriate.
Confirm defects and typed errors are separated intentionally.

Reference: effect-solutions show error-handling

5. Configuration

Inspect configuration patterns and verify:

Confirm Schema.Config is used for validation.
Confirm a config service layer pattern is present.
Confirm secrets use Config.redacted.

Reference: effect-solutions show config

6. Testing

Inspect tests and verify:

Confirm tests use @effect/vitest.
Confirm Effect tests use it.effect().
Confirm test layer composition follows Effect layer patterns.

Reference: effect-solutions show testing

7. Runtime Execution Anti-Pattern (`Effect.runPromise` / `Effect.runSync` in Application Code)

Search application code for direct Effect.runPromise and Effect.runSync usage. Exclude test-only files and test helpers (__tests__/, *.test.ts, *.spec.ts, fixture directories).

Treat bare Effect.runPromise / Effect.runSync as findings when they bypass the project runtime composition. Bare execution typically uses the default runtime without project-provided layers (for tracing, config, logging, or domain services).

Apply project-aware evaluation:

Prefer the project's runtime entrypoint (for example runtime.runPromise) in application code.
Accept explicit layer provisioning when runtime usage is not feasible (for example during bootstrap or dependency-cycle constraints).
Exempt tests that intentionally provide dedicated test layers.

Template-ts convention example (use only when applicable in the audited repo):

ManagedRuntime in effect-runtime.ts
AppLayer composition
SentryTracingLive in runtime-provided observability

Search patterns:

Effect.runPromise( under application source directories (for example src/, apps/*/src/, packages/*/src/)
Effect.runSync( under application source directories (same scope)

Report each occurrence with:

File path and line
Whether it's using runtime.runPromise (✅) or bare Effect.runPromise (❌)
Whether required observability/config layers are provided by runtime or explicit Effect.provide fallback

Reference: effect-solutions show services-and-layers

8. Option/Either Internal Tag Anti-Patterns

Inspect direct _tag branching on Option/Either in application code and tests.

Production code: report all direct _tag usage as findings with replacement recommendation
Tests: allow _tag assertions for domain error identity, but flag control-flow branching patterns that should use helpers
Prefer:
- Either.match, Either.isLeft, Either.isRight
- Option.match, Option.isSome, Option.isNone, Option.getOrElse

Search patterns to include:

if (.*\._tag === "Left")
if (.*\._tag === "Right")
if (.*\._tag === "Some")
if (.*\._tag === "None")
expect\(.*\._tag\)