Adds a mechanism to preload the effect's debugger instrumentation bef… (#75)

Author: mattiamanzati

.changeset/whole-parents-help.md

@@ -0,0 +1,5 @@
+---
+"effect-vscode": patch
+---
+
+Adds a mechanism to preload the effect's debugger instrumentation before node begins executing userlands scripts.

package.json

@@ -50,6 +50,24 @@
           },
           "default": [],
           "description": "A list of span patterns to ignore when showing the span stack"
+        },
+        "effect.instrumentation.injectNodeOptions": {
+          "type": "boolean",
+          "default": false,
+          "description": "If enabled, the effect instrumentation code will be injected into node debug configurations by appending a NODE_OPTIONS environment variable"
+        },
+        "effect.instrumentation.injectDebugConfigurations": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "default": ""
+          },
+          "default": [
+            "node",
+            "node-terminal",
+            "pwa-node"
+          ],
+          "description": "A list of debug configuration types to inject the instrumentation into when injectNodeOptions is enabled"
         }
       }
     },
@@ -256,6 +274,7 @@
     "test": "node ./out/test/runTest.js"
   },
   "devDependencies": {
+    "@vscode/js-debug": "*",
     "@changesets/changelog-github": "^0.5.1",
     "@changesets/cli": "^2.29.5",
     "@effect/eslint-plugin": "^0.3.2",

src/InjectNodeOptionsInstrumentationProvider.ts

@@ -0,0 +1,52 @@
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Runtime from "effect/Runtime"
+import * as vscode from "vscode"
+import { configWithDefault, VsCodeContext } from "./VsCode"
+
+export const InjectNodeOptionsInstrumentationLive = Effect.gen(function*() {
+  const extension = yield* VsCodeContext
+
+  // gets the config if it shuold be injected or not
+  const injectNodeOptions = yield* configWithDefault("effect.instrumentation", "injectNodeOptions", false)
+  const injectDebugConfigurations = yield* configWithDefault("effect.instrumentation", "injectDebugConfigurations", [
+    "node",
+    "node-terminal",
+    "pwa-node"
+  ])
+  const runtime = yield* Effect.runtime<never>()
+
+  yield* Effect.acquireRelease(
+    Effect.sync(() =>
+      vscode.debug.registerDebugConfigurationProvider("*", {
+        resolveDebugConfiguration(_folder, config, _token) {
+          // if disabled (default) then do nothing
+          const shouldInjectBool = Runtime.runSync(runtime, injectNodeOptions.get)
+          if (!shouldInjectBool) return config
+
+          // abort immediately if the token is cancelled
+          if (_token?.isCancellationRequested) return config
+
+          // if not supported, then do nothing
+          const debugConfigurations = Runtime.runSync(runtime, injectDebugConfigurations.get)
+          if (
+            debugConfigurations.map((_) => String(_).toLowerCase()).indexOf(config.type.toLowerCase()) === -1
+          ) return config
+
+          // if enabled, then inject the instrumentation in NODE_OPTIONS
+          const configEnv = config.env || {}
+          const previousNodeOptions = configEnv.NODE_OPTIONS || "${env:NODE_OPTIONS}"
+          const instrumentationPath = JSON.stringify(extension.extensionPath + "/out/instrumentation.global.js")
+          return {
+            ...config,
+            env: {
+              ...configEnv,
+              "NODE_OPTIONS": `--require ${instrumentationPath} ${previousNodeOptions}`
+            }
+          }
+        }
+      })
+    ),
+    (disposer) => Effect.sync(() => disposer.dispose())
+  )
+}).pipe(Layer.scopedDiscard)

src/extension.ts

@@ -8,6 +8,7 @@ import { DebugBreakpointsProviderLive } from "./DebugBreakpointsProvider"
 import { DebugEnv } from "./DebugEnv"
 import { DebugFibersProviderLive } from "./DebugFibersProvider"
 import { DebugSpanStackProviderLive } from "./DebugSpanStackProvider"
+import { InjectNodeOptionsInstrumentationLive } from "./InjectNodeOptionsInstrumentationProvider"
 import { LayerHoverProviderLive } from "./LayerHoverProvider"
 import { MetricsProviderLive } from "./MetricsProvider"
 import { SpanProviderLive } from "./SpanProvider"
@@ -25,7 +26,8 @@ const MainLive = ClientsProviderLive.pipe(
     DebugFibersProviderLive,
     TracerExtendedLive,
     LayerHoverProviderLive,
-    DebugBreakpointsProviderLive
+    DebugBreakpointsProviderLive,
+    InjectNodeOptionsInstrumentationLive
   )),
   Layer.provide(Clients.Default),
   Layer.provide(DebugEnv.Live),