Allow suppressing leaked service diagnostics (#687)

mattiamanzati · web-flow · commit 72827c0dcacf · 2026-03-20T13:56:12.000+01:00
diff --git a/.changeset/green-buses-joke.md b/.changeset/green-buses-joke.md
@@ -0,0 +1,5 @@
+---
+"@effect/language-service": patch
+---
+
+Allow the leaking requirements diagnostic to suppress specific leaked services with `@effect-expect-leaking` comments on the enclosing declaration.
diff --git a/packages/harness-effect-v3/__snapshots__/diagnostics/leakingRequirements.ts.output b/packages/harness-effect-v3/__snapshots__/diagnostics/leakingRequirements.ts.output
@@ -5,7 +5,7 @@ This leaks implementation details into the service's public type — callers sho
 
 Resolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.
 
-To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), not to this service.
+To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), or to this service by adding a `@effect-expect-leaking FileSystem` JSDoc.
 
 More info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)
 
@@ -16,6 +16,6 @@ This leaks implementation details into the service's public type — callers sho
 
 Resolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.
 
-To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), not to this service.
+To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), or to this service by adding a `@effect-expect-leaking FileSystem` JSDoc.
 
 More info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)
diff --git a/packages/harness-effect-v3/__snapshots__/diagnostics/leakingRequirements_genericTag.ts.output b/packages/harness-effect-v3/__snapshots__/diagnostics/leakingRequirements_genericTag.ts.output
@@ -5,6 +5,6 @@ This leaks implementation details into the service's public type — callers sho
 
 Resolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.
 
-To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), not to this service.
+To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), or to this service by adding a `@effect-expect-leaking FileSystem` JSDoc.
 
 More info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)
diff --git a/packages/harness-effect-v4/__snapshots__/diagnostics/leakingRequirements.ts.output b/packages/harness-effect-v4/__snapshots__/diagnostics/leakingRequirements.ts.output
@@ -5,7 +5,7 @@ This leaks implementation details into the service's public type — callers sho
 
 Resolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.
 
-To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), not to this service.
+To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), or to this service by adding a `@effect-expect-leaking FileSystem` JSDoc.
 
 More info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)
 
@@ -16,6 +16,6 @@ This leaks implementation details into the service's public type — callers sho
 
 Resolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.
 
-To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), not to this service.
+To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), or to this service by adding a `@effect-expect-leaking FileSystem` JSDoc.
 
 More info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)
diff --git a/packages/harness-effect-v4/__snapshots__/diagnostics/leakingRequirements_allowJsdoc.ts.codefixes b/packages/harness-effect-v4/__snapshots__/diagnostics/leakingRequirements_allowJsdoc.ts.codefixes
@@ -0,0 +1,2 @@
+leakingRequirements_skipNextLine from 495 to 506
+leakingRequirements_skipFile from 495 to 506
diff --git a/packages/harness-effect-v4/__snapshots__/diagnostics/leakingRequirements_allowJsdoc.ts.output b/packages/harness-effect-v4/__snapshots__/diagnostics/leakingRequirements_allowJsdoc.ts.output
@@ -0,0 +1,10 @@
+LeakingDeps
+15:13 - 15:24 | 2 | Methods of this Service require `Cache` from every caller.
+
+This leaks implementation details into the service's public type — callers shouldn't need to know *how* the service works internally, only *what* it provides.
+
+Resolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.
+
+To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `Cache` interface), or to this service by adding a `@effect-expect-leaking Cache` JSDoc.
+
+More info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)
diff --git a/packages/harness-effect-v4/__snapshots__/diagnostics/leakingRequirements_genericTag.ts.output b/packages/harness-effect-v4/__snapshots__/diagnostics/leakingRequirements_genericTag.ts.output
@@ -5,6 +5,6 @@ This leaks implementation details into the service's public type — callers sho
 
 Resolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.
 
-To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), not to this service.
+To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), or to this service by adding a `@effect-expect-leaking FileSystem` JSDoc.
 
 More info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)
diff --git a/packages/harness-effect-v4/__snapshots__/diagnostics/leakingRequirements_preview.ts.output b/packages/harness-effect-v4/__snapshots__/diagnostics/leakingRequirements_preview.ts.output
@@ -5,6 +5,6 @@ This leaks implementation details into the service's public type — callers sho
 
 Resolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.
 
-To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), not to this service.
+To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), or to this service by adding a `@effect-expect-leaking FileSystem` JSDoc.
 
 More info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)
diff --git a/packages/harness-effect-v4/examples/diagnostics/leakingRequirements_allowJsdoc.ts b/packages/harness-effect-v4/examples/diagnostics/leakingRequirements_allowJsdoc.ts
@@ -0,0 +1,46 @@
+import type { Effect } from "effect"
+import { ServiceMap } from "effect"
+
+export class FileSystem extends ServiceMap.Service<FileSystem, {
+  writeFile: (content: string) => Effect.Effect<void>
+}>()("FileSystem") {}
+
+export class Cache extends ServiceMap.Service<Cache, {
+    writeFile: (content: string) => Effect.Effect<void>
+  }>()("Cache") {}
+
+// LeakingDeps is leaking FileSystem and Cache, but only Cache should be considered to be leaked
+
+// @effect-expect-leaking FileSystem
+export class LeakingDeps extends ServiceMap.Service<LeakingDeps, {
+  writeCache: () => Effect.Effect<void, never, FileSystem | Cache>
+  readCache: Effect.Effect<void, never, FileSystem | Cache>
+}>()("LeakingDeps") {}
+
+// LeakingDeps2 is leaking FileSystem and Cache, but both are expected to be leaked
+
+// @effect-expect-leaking FileSystem Cache
+export class LeakingDeps2 extends ServiceMap.Service<LeakingDeps2, {
+    writeCache: () => Effect.Effect<void, never, FileSystem | Cache>
+    readCache: Effect.Effect<void, never, FileSystem | Cache>
+}>()("LeakingDeps2") {}
+
+// LeakingDeps3 is leaking FileSystem and Cache, but both are expected to be leaked
+
+/**
+ * Example inside of a class with multiple JSDoc
+ * @effect-leakable-service
+ * @effect-expect-leaking FileSystem Cache
+ */
+export class LeakingDeps3 extends ServiceMap.Service<LeakingDeps3, {
+    writeCache: () => Effect.Effect<void, never, FileSystem | Cache>
+    readCache: Effect.Effect<void, never, FileSystem | Cache>
+}>()("LeakingDeps3") {}
+
+// LeakingDeps4 is leaking FileSystem and Cache, but both are expected to be leaked
+
+// @effect-expect-leaking FileSystem Cache
+export const LeakingDeps4 = ServiceMap.Service<{
+    writeCache: () => Effect.Effect<void, never, FileSystem | Cache>
+    readCache: Effect.Effect<void, never, FileSystem | Cache>
+}>("LeakingDeps4")
diff --git a/packages/language-service/src/core/TypeScriptApi.ts b/packages/language-service/src/core/TypeScriptApi.ts
@@ -187,6 +187,8 @@ declare module "typescript" {
   export interface Node {
     /** @deprecated Use ts.getTokenPosOfNode(node, sourceFile) instead */
     getStart(sourceFile?: ts.SourceFile, includeJsDocComment?: boolean): number
+    /** @deprecated Use node.pos instead */
+    getFullStart(): number
     /** @deprecated Use sourceFile.text.substring(node.pos, node.end) instead */
     getText(sourceFile?: ts.SourceFile): string
   }
diff --git a/packages/language-service/src/diagnostics/leakingRequirements.ts b/packages/language-service/src/diagnostics/leakingRequirements.ts
@@ -24,6 +24,39 @@ export const leakingRequirements = LSP.createDiagnostic({
     const typeParser = yield* Nano.service(TypeParser.TypeParser)
     const tsUtils = yield* Nano.service(TypeScriptUtils.TypeScriptUtils)
 
+    const isExpectedLeakingServiceSuppressed = (leakedServiceName: string, startNode: ts.Node): boolean => {
+      const sourceFile = tsUtils.getSourceFileOfNode(startNode)
+      if (!sourceFile) return false
+
+      return !!ts.findAncestor(startNode, (current) => {
+        const ranges = ts.getLeadingCommentRanges(sourceFile.text, current.pos) ?? []
+        const isSuppressed = ranges.some((range) => {
+          const commentText = sourceFile.text.slice(range.pos, range.end)
+          return commentText
+            .split("\n")
+            .filter((line) => line.includes("@effect-expect-leaking"))
+            .some((line) => {
+              const markerIndex = line.indexOf("@effect-expect-leaking")
+              return markerIndex !== -1 &&
+                line.slice(markerIndex + "@effect-expect-leaking".length).includes(leakedServiceName)
+            })
+        })
+
+        if (isSuppressed) {
+          return true
+        }
+
+        return (
+            ts.isClassDeclaration(current) ||
+            ts.isVariableStatement(current) ||
+            ts.isExpressionStatement(current) ||
+            ts.isStatement(current)
+          )
+          ? "quit"
+          : false
+      })
+    }
+
     const parseLeakedRequirements = Nano.cachedBy(
       Nano.fn("leakingServices.checkServiceLeaking")(
         function*(service: ts.Type, atLocation: ts.Node) {
@@ -113,16 +146,19 @@ export const leakingRequirements = LSP.createDiagnostic({
     )
 
     function reportLeakingRequirements(node: ts.Node, requirements: Array<ts.Type>) {
-      if (requirements.length === 0) return
-      const requirementsStr = requirements.map((_) => typeChecker.typeToString(_)).join(" | ")
+      const filteredRequirements = requirements.filter((requirement) =>
+        !isExpectedLeakingServiceSuppressed(typeChecker.typeToString(requirement), node)
+      )
+      if (filteredRequirements.length === 0) return
+
+      const requirementsStr = filteredRequirements.map((_) => typeChecker.typeToString(_)).join(" | ")
+      const firstStr = typeChecker.typeToString(filteredRequirements[0])
       report({
         location: node,
         messageText: `Methods of this Service require \`${requirementsStr}\` from every caller.\n\n` +
           `This leaks implementation details into the service's public type — callers shouldn't need to know *how* the service works internally, only *what* it provides.\n\n` +
           `Resolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.\n\n` +
-          `To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add \`@effect-leakable-service\` JSDoc to their interface declarations (e.g., the \`${
-            typeChecker.typeToString(requirements[0])
-          }\` interface), not to this service.\n\n` +
+          `To suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add \`@effect-leakable-service\` JSDoc to their interface declarations (e.g., the \`${firstStr}\` interface), or to this service by adding a \`@effect-expect-leaking ${firstStr}\` JSDoc.\n\n` +
           `More info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage`,
         fixes: []
       })
diff --git a/packages/language-service/src/metadata.json b/packages/language-service/src/metadata.json
@@ -538,7 +538,7 @@
           {
             "start": 212,
             "end": 217,
-            "text": "Methods of this Service require `FileSystem` from every caller.\n\nThis leaks implementation details into the service's public type — callers shouldn't need to know *how* the service works internally, only *what* it provides.\n\nResolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.\n\nTo suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), not to this service.\n\nMore info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)"
+            "text": "Methods of this Service require `FileSystem` from every caller.\n\nThis leaks implementation details into the service's public type — callers shouldn't need to know *how* the service works internally, only *what* it provides.\n\nResolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.\n\nTo suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), or to this service by adding a `@effect-expect-leaking FileSystem` JSDoc.\n\nMore info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)"
           }
         ]
       }

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@effect/language-service": patch
 +---
++
 +Allow the leaking requirements diagnostic to suppress specific leaked services with `@effect-expect-leaking` comments on the enclosing declaration.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+leakingRequirements_skipNextLine from 495 to 506`
	`2`	`+leakingRequirements_skipFile from 495 to 506`
Original file line number	Diff line number	Diff line change
`@@ -187,6 +187,8 @@ declare module "typescript" {`
`187`	`187`	`export interface Node {`
`188`	`188`	`/** @deprecated Use ts.getTokenPosOfNode(node, sourceFile) instead */`
`189`	`189`	`getStart(sourceFile?: ts.SourceFile, includeJsDocComment?: boolean): number`
	`190`	`+ /** @deprecated Use node.pos instead */`
	`191`	`+ getFullStart(): number`
`190`	`192`	`/** @deprecated Use sourceFile.text.substring(node.pos, node.end) instead */`
`191`	`193`	`getText(sourceFile?: ts.SourceFile): string`
`192`	`194`	`}`