@effect/language-service 0.78.0 → 0.80.0

package/README.md

@@ -10,6 +10,7 @@ This package implements a TypeScript language service plugin that allows additio
 2. Inside your tsconfig.json, you should add the plugin configuration as follows:
 ```jsonc
 {
+  "$schema": "https://raw.githubusercontent.com/Effect-TS/language-service/refs/heads/main/schema.json",
   "compilerOptions": {
     "plugins": [
       // ... other LSPs (if any) and as last
@@ -39,6 +40,68 @@ And you're done! You'll now be able to use a set of refactors and diagnostics th
 
 ## Provided functionalities
 
+### Diagnostics
+
+<!-- diagnostics-table:start -->
+| Diagnostic | Sev | Fix | Description | v3 | v4 |
+| --- | --- | --- | --- | --- | --- |
+| `anyUnknownInErrorContext` | ➖ |  | Detects 'any' or 'unknown' types in Effect error or requirements channels | ✓ | ✓ |
+| `catchAllToMapError` | 💡 | 🔧 | Suggests using Effect.mapError instead of Effect.catchAll when the callback only wraps the error with Effect.fail | ✓ | ✓ |
+| `catchUnfailableEffect` | 💡 |  | Warns when using error handling on Effects that never fail (error type is 'never') | ✓ | ✓ |
+| `classSelfMismatch` | ❌ | 🔧 | Ensures Self type parameter matches the class name in Service/Tag/Schema classes | ✓ | ✓ |
+| `deterministicKeys` | ➖ | 🔧 | Enforces deterministic naming for service/tag/error identifiers based on class names | ✓ | ✓ |
+| `duplicatePackage` | ⚠️ |  | Detects when multiple versions of the same Effect package are loaded | ✓ | ✓ |
+| `effectFnIife` | ⚠️ | 🔧 | Effect.fn or Effect.fnUntraced is called as an IIFE (Immediately Invoked Function Expression). Use Effect.gen instead. | ✓ | ✓ |
+| `effectFnOpportunity` | 💡 | 🔧 | Suggests using Effect.fn for functions that returns an Effect | ✓ | ✓ |
+| `effectGenUsesAdapter` | ⚠️ |  | Warns when using the deprecated adapter parameter in Effect.gen | ✓ | ✓ |
+| `effectInFailure` | ⚠️ |  | Warns when an Effect is used inside an Effect failure channel | ✓ | ✓ |
+| `effectInVoidSuccess` | ⚠️ |  | Detects nested Effects in void success channels that may cause unexecuted effects | ✓ | ✓ |
+| `effectMapVoid` | 💡 | 🔧 | Suggests using Effect.asVoid instead of Effect.map(() => void 0), Effect.map(() => undefined), or Effect.map(() => {}) | ✓ | ✓ |
+| `effectSucceedWithVoid` | 💡 | 🔧 | Suggests using Effect.void instead of Effect.succeed(undefined) or Effect.succeed(void 0) | ✓ | ✓ |
+| `extendsNativeError` | ➖ |  | Warns when a class directly extends the native Error class | ✓ | ✓ |
+| `floatingEffect` | ❌ |  | Ensures Effects are yielded or assigned to variables, not left floating | ✓ | ✓ |
+| `genericEffectServices` | ⚠️ |  | Prevents services with type parameters that cannot be discriminated at runtime | ✓ | ✓ |
+| `globalErrorInEffectCatch` | ⚠️ |  | Warns when catch callbacks return global Error type instead of typed errors | ✓ | ✓ |
+| `globalErrorInEffectFailure` | ⚠️ |  | Warns when the global Error type is used in an Effect failure channel | ✓ | ✓ |
+| `importFromBarrel` | ➖ | 🔧 | Suggests importing from specific module paths instead of barrel exports | ✓ | ✓ |
+| `instanceOfSchema` | ➖ | 🔧 | Suggests using Schema.is instead of instanceof for Effect Schema types | ✓ | ✓ |
+| `layerMergeAllWithDependencies` | ⚠️ | 🔧 | Detects interdependencies in Layer.mergeAll calls where one layer provides a service that another layer requires | ✓ | ✓ |
+| `leakingRequirements` | 💡 |  | Detects implementation services leaked in service methods | ✓ | ✓ |
+| `missedPipeableOpportunity` | ➖ | 🔧 | Enforces the use of pipeable style for nested function calls | ✓ | ✓ |
+| `missingEffectContext` | ❌ |  | Reports missing service requirements in Effect context channel | ✓ | ✓ |
+| `missingEffectError` | ❌ | 🔧 | Reports missing error types in Effect error channel | ✓ | ✓ |
+| `missingEffectServiceDependency` | ➖ |  | Checks that Effect.Service dependencies satisfy all required layer inputs | ✓ |  |
+| `missingLayerContext` | ❌ |  | Reports missing service requirements in Layer context channel | ✓ | ✓ |
+| `missingReturnYieldStar` | ❌ | 🔧 | Suggests using 'return yield*' for Effects with never success for better type narrowing | ✓ | ✓ |
+| `missingStarInYieldEffectGen` | ❌ | 🔧 | Enforces using 'yield*' instead of 'yield' when yielding Effects in generators | ✓ | ✓ |
+| `multipleEffectProvide` | ⚠️ | 🔧 | Warns against chaining Effect.provide calls which can cause service lifecycle issues | ✓ | ✓ |
+| `nodeBuiltinImport` | ➖ |  | Warns when importing Node.js built-in modules that have Effect-native counterparts | ✓ | ✓ |
+| `nonObjectEffectServiceType` | ❌ |  | Ensures Effect.Service types are objects, not primitives | ✓ |  |
+| `outdatedApi` | ⚠️ |  | Detects usage of APIs that have been removed or renamed in Effect v4 |  | ✓ |
+| `outdatedEffectCodegen` | ⚠️ | 🔧 | Detects when generated code is outdated and needs to be regenerated | ✓ | ✓ |
+| `overriddenSchemaConstructor` | ❌ | 🔧 | Prevents overriding constructors in Schema classes which breaks decoding behavior | ✓ | ✓ |
+| `preferSchemaOverJson` | 💡 |  | Suggests using Effect Schema for JSON operations instead of JSON.parse/JSON.stringify which may throw | ✓ | ✓ |
+| `redundantSchemaTagIdentifier` | 💡 | 🔧 | Suggests removing redundant identifier argument when it equals the tag value in Schema.TaggedClass/TaggedError/TaggedRequest | ✓ | ✓ |
+| `returnEffectInGen` | 💡 | 🔧 | Warns when returning an Effect in a generator causes nested Effect<Effect<...>> | ✓ | ✓ |
+| `runEffectInsideEffect` | 💡 | 🔧 | Suggests using Runtime methods instead of Effect.run* inside Effect contexts | ✓ |  |
+| `schemaStructWithTag` | 💡 | 🔧 | Suggests using Schema.TaggedStruct instead of Schema.Struct with _tag field | ✓ | ✓ |
+| `schemaSyncInEffect` | 💡 |  | Suggests using Effect-based Schema methods instead of sync methods inside Effect generators | ✓ | ✓ |
+| `schemaUnionOfLiterals` | ➖ | 🔧 | Simplifies Schema.Union of multiple Schema.Literal calls into single Schema.Literal | ✓ |  |
+| `scopeInLayerEffect` | ⚠️ | 🔧 | Suggests using Layer.scoped instead of Layer.effect when Scope is in requirements | ✓ |  |
+| `serviceNotAsClass` | ➖ | 🔧 | Warns when ServiceMap.Service is used as a variable instead of a class declaration |  | ✓ |
+| `strictBooleanExpressions` | ➖ |  | Enforces boolean types in conditional expressions for type safety | ✓ | ✓ |
+| `strictEffectProvide` | ➖ |  | Warns when using Effect.provide with layers outside of application entry points | ✓ | ✓ |
+| `tryCatchInEffectGen` | 💡 |  | Discourages try/catch in Effect generators in favor of Effect error handling | ✓ | ✓ |
+| `unknownInEffectCatch` | ⚠️ |  | Warns when catch callbacks return unknown instead of typed errors | ✓ | ✓ |
+| `unnecessaryEffectGen` | 💡 | 🔧 | Suggests removing Effect.gen when it contains only a single return statement | ✓ | ✓ |
+| `unnecessaryFailYieldableError` | 💡 | 🔧 | Suggests yielding yieldable errors directly instead of wrapping with Effect.fail | ✓ | ✓ |
+| `unnecessaryPipe` | 💡 | 🔧 | Removes pipe calls with no arguments | ✓ | ✓ |
+| `unnecessaryPipeChain` | 💡 | 🔧 | Simplifies chained pipe calls into a single pipe call | ✓ | ✓ |
+| `unsupportedServiceAccessors` | ⚠️ | 🔧 | Warns about service accessors that need codegen due to generic/complex signatures | ✓ | ✓ |
+
+`➖` off by default, `❌` error, `⚠️` warning, `💬` message, `💡` suggestion, `🔧` quick fix available
+<!-- diagnostics-table:end -->
+
 ### Quickinfo
 
 - Show the extended type of the current Effect
@@ -46,48 +109,6 @@ And you're done! You'll now be able to use a set of refactors and diagnostics th
 - Hovering a variable assignment of a type Layer, will show info on how each service got involved
 - Hovering a layer, will attempt to produce a graph
 
-### Diagnostics
-
-- Better error readability when you're missing errors or service types in your Effect definitions
-- Better error readability when you're missing service requirements in your Layer definitions
-- Floating Effects that are not yielded or run
-- Wrong usage of yield inside `Effect.gen`
-- Multiple versions of Effect in your project
-- Warn on leaking requirements in Effect services
-- Warn on Scope as requirement of a Layer
-- Warn on subsequent `Effect.provide` anti-pattern
-- Warn when using `Effect.provide` with Layer outside of application entry points
-- Detect wrong `Self` type parameter for APIs like `Effect.Service` or `Schema.TaggedError` and similar 
-- Unnecessary usages of `Effect.gen` or `pipe()`
-- Warn when using `Effect.gen` with the old generator adapter pattern
-- Warn when importing from a barrel file instead of from the module directly
-- Warn on usage of try/catch inside `Effect.gen` and family
-- Detect unnecessary pipe chains like `X.pipe(Y).pipe(Z)`
-- Warn when using `Effect.Service` with `accessors: true` but methods have generics or multiple signatures
-- Warn on missing service dependencies in `Effect.Service` declarations
-- Warn when `Effect.Service` is used with a primitive type instead of an object type
-- Warn when schema classes override the default constructor behavior
-- Warn when `@effect-diagnostics-next-line` comments have no effect (i.e., they don't suppress any diagnostic)
-- Detect nested function calls that can be converted to pipeable style for better readability
-- Warn when using catch functions (`catchAll`, `catch`, `catchIf`, `catchSome`, `catchTag`, `catchTags`) on effects that never fail
-- Warn when catch callbacks in `Effect.tryPromise`, `Effect.tryMap`, or `Effect.tryMapPromise` return `unknown` or `any` types
-- Warn when catch callbacks in `Effect.tryPromise`, `Effect.try`, `Effect.tryMap`, or `Effect.tryMapPromise` return the global `Error` type instead of typed errors
-- Warn when using `Effect.runSync`, `Effect.runPromise`, `Effect.runFork`, or `Effect.runCallback` inside an Effect
-- Warn when using `Schema.decodeSync`, `Schema.decodeUnknownSync`, `Schema.encodeSync`, or `Schema.encodeUnknownSync` inside Effect generators, suggesting Effect-based alternatives
-- Suggest using Effect Schema for JSON operations instead of `JSON.parse`/`JSON.stringify` inside Effect contexts
-- Warn when using `Schema.Union` with multiple `Schema.Literal` calls that can be simplified to a single `Schema.Literal` call
-- Suggest using `Schema.TaggedStruct` instead of `Schema.Struct` when a `_tag` field with `Schema.Literal` is present to make the tag optional in the constructor
-- Warn when using `yield* Effect.fail()` with yieldable error types that can be yielded directly
-- Warn when the global `Error` type is used in an Effect failure channel, recommending tagged errors
-- Warn when an `Effect` computation is placed in an Effect failure channel, since failure channels should contain only failure types
-- Warn when `Layer.mergeAll` contains layers with interdependencies (where one layer provides a service that another layer in the same call requires)
-- Suggest using `Effect.fn` for functions that return `Effect.gen` for better tracing and concise syntax
-- Warn when `Effect.fn` or `Effect.fnUntraced` is used as an IIFE (Immediately Invoked Function Expression), suggesting `Effect.gen` instead
-- Suggest removing redundant identifier argument when it equals the tag value in `Schema.TaggedClass`, `Schema.TaggedError`, or `Schema.TaggedRequest`
-- Suggest using `Schema.is` instead of `instanceof` for Effect Schema types
-- Suggest using `Effect.void` instead of `Effect.succeed(undefined)` or `Effect.succeed(void 0)`
-- Warn when using outdated Effect v3 APIs in an Effect v4 project, with guidance on the correct v4 replacement (renamed, changed, or removed APIs)
-
 ### Completions
 
 - Autocomplete 'Self' in `Effect.Service`, `Context.Tag`, `Schema.TaggedClass`, `Schema.TaggedRequest`, `ServiceMap.Service`, `Model.Class` and family
@@ -145,7 +166,9 @@ Few options can be provided alongside the initialization of the Language Service
         "missingDiagnosticNextLine": "warning", // controls the severity of warnings for unused @effect-diagnostics-next-line comments (default: "warning", allowed values: off,error,warning,message,suggestion)
         "includeSuggestionsInTsc": true, // when enabled with effect-language-service patch enabled, diagnostics with "suggestion" severity will be reported as "message" in TSC with "[suggestion]" prefix; useful to help steer LLM output (default: true)
         "ignoreEffectWarningsInTscExitCode": false, // if set to true, effect-related warnings won't change the exit code of tsc, meaning that tsc will compile fine even if effect warnings are emitted (default: false)
+        "ignoreEffectErrorsInTscExitCode": false, // if set to true, effect-related errors won't change the exit code of tsc (default: false)
         "ignoreEffectSuggestionsInTscExitCode": true, // if set to true, effect-related suggestions won't change the exit code of tsc (default: true)
+        "skipDisabledOptimization": false, // if set to true, disabled diagnostics are still processed so per-line or per-section overrides can be honored in patched tsc runs (default: false)
         "quickinfo": true, // controls Effect quickinfo (default: true)
         "quickinfoEffectParameters": "whenTruncated", // (default: "whenTruncated") controls when to display effect type parameters always,never,whenTruncated
         "quickinfoMaximumLength": -1, // controls how long can be the types in the quickinfo hover (helps with very long type to improve perfs, defaults to -1 for no truncation, can be any number eg. 1000 and TS will try to fit as much as possible in that budget, higher number means more info.)
@@ -209,13 +232,13 @@ so that across updates the patch will be re-applied again.
 The effect language service plugin comes with a builtin CLI tool that can be used to perform various utilities, checks and setups. Since it relies on typescript, we recommend to install it locally and run it locally to ensure it loads the same typescript version of your project rather than a global installation that may resolve to use a different TS version from the one of your project.
 
 ### `effect-language-service setup`
-Runs through a wizard to setup/update some basic functionalities of the LSP in an interactive way.
+Runs through a wizard to setup/update some basic functionalities of the LSP in an interactive way. This also keeps the `tsconfig.json` `$schema` aligned with the published Effect Language Service schema.
 
 ### `effect-language-service codegen`
 Automatically updates Effect codegens in your TypeScript files. This command scans files for `@effect-codegens` directives and applies the necessary code transformations. Use `--file` to update a specific file, or `--project` with a tsconfig file to update an entire project. The `--verbose` flag provides detailed output about which files are being processed and updated.
 
 ### `effect-language-service diagnostics`
-Provides a way to get through a CLI the list of Effect specific diagnostics; without patching your typescript installation. A --file option may be used to get diagnostics for a specific file, or --project with a tsconfig file to get an entire project.
+Provides a way to get through a CLI the list of Effect specific diagnostics; without patching your typescript installation. A `--file` option may be used to get diagnostics for a specific file, or `--project` with a tsconfig file to get an entire project. You can also pass `--lspconfig '{ "effectFn": ["untraced"] }'` to override the project plugin configuration inline for that diagnostics run.
 
 ### `effect-language-service quickfixes`
 Shows diagnostics that have available quick fixes along with their proposed code changes. This is useful for previewing what fixes the language service can apply to your code. Use `--file` to check a specific file, or `--project` with a tsconfig file to check an entire project. The output displays each diagnostic with its location and the diff of proposed changes.