fix: make dev-build sourcemaps debuggable (closes #304)

.vscode/launch.json

@@ -9,7 +9,18 @@
       "type": "node",
       "request": "attach",
       "name": "Attach to VS Code TS Server via Port",
-      "port": 9559
+      "port": 9559,
+      "sourceMaps": true,
+      // The plugin is loaded by tsserver from the example project's
+      // node_modules. The default value of "resolveSourceMapLocations"
+      // excludes anything inside node_modules, which prevents breakpoints in
+      // packages/graphqlsp/src from ever binding, so it's widened here.
+      // See: https://github.com/0no-co/GraphQLSP/issues/304
+      "resolveSourceMapLocations": ["${workspaceFolder}/**"],
+      "outFiles": [
+        "${workspaceFolder}/packages/graphqlsp/dist/**/*.js",
+        "${workspaceFolder}/**/node_modules/@0no-co/graphqlsp/dist/**/*.js"
+      ]
     }
   ]
 }

README.md

@@ -135,3 +135,28 @@ breakpoints do it with the `TSS_DEBUG_BRK=9559` prefix. When you make changes in
 to do is run `pnpm i` in your other editor and restart the `TypeScript server` for the changes to apply.
 
 > Ensure that both instances of your editor are using the Workspace Version of TypeScript
+
+### Debugging with breakpoints
+
+To set breakpoints in the TypeScript sources of `packages/graphqlsp` you need a
+development build of the plugin, which emits sourcemaps that point back at the
+files in `packages/graphqlsp/src`:
+
+1. Build the plugin with `pnpm --filter @0no-co/graphqlsp dev` (this watches for
+   changes; a one-off `NODE_ENV=development pnpm --filter @0no-co/graphqlsp build`
+   works too)
+2. Open the example project with `TSS_DEBUG_BRK=9559 code packages/example` and
+   run `pnpm i` in it, so it picks up the freshly built plugin
+3. In the VS Code window that has the repository root open, set your breakpoints
+   in `packages/graphqlsp/src` and start the "Attach to VS Code TS Server via
+   Port" launch configuration from the "Run and Debug" panel
+4. Trigger the plugin from the example window (e.g. by typing inside a `graphql()`
+   document) and your breakpoints will be hit
+
+After making changes in `packages/graphqlsp`, restart the example window's
+TypeScript server ("TypeScript: Restart TS Server" in the command palette) and
+reattach the debugger for the changes to apply.
+
+> Production builds (`pnpm build` without `NODE_ENV=development`) also emit
+> sourcemaps, but their `sources` are relative paths that don't resolve from the
+> location pnpm installs the package to, so breakpoints won't bind with them.

scripts/rollup.config.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path/posix';
+import nodePath from 'node:path';
 import { readFileSync } from 'node:fs';
 
 import * as prettier from 'prettier';
@@ -28,6 +29,8 @@ const extension = name => {
   }
 };
 
+const isDevelopment = process.env.NODE_ENV === 'development';
+
 const meta = JSON.parse(readFileSync('package.json'));
 const name = normalize(meta.name);
 
@@ -87,6 +90,19 @@ const commonOutput = {
   exports: 'auto',
   sourcemap: true,
   sourcemapExcludeSources: false,
+  // In development builds, sourcemap sources are rewritten to absolute paths.
+  // pnpm links or copies the built package into the example project's
+  // node_modules, from where relative sources never resolve back to the
+  // actual files in packages/graphqlsp/src, leaving debugger breakpoints
+  // unbound. See: https://github.com/0no-co/GraphQLSP/issues/304
+  ...(isDevelopment && {
+    sourcemapPathTransform(relativeSourcePath, sourcemapPath) {
+      return nodePath.resolve(
+        nodePath.dirname(sourcemapPath),
+        relativeSourcePath
+      );
+    },
+  }),
   hoistTransitiveImports: false,
   indent: false,
   freeze: false,
@@ -134,35 +150,38 @@ const outputPlugins = [
 
   cjsCheck(),
 
-  terser({
-    warnings: true,
-    ecma: 2015,
-    keep_fnames: true,
-    ie8: false,
-    compress: {
-      pure_getters: true,
-      toplevel: true,
-      booleans_as_integers: false,
+  // Minification is skipped in development builds to keep the emitted
+  // sourcemap mappings as close to the original sources as possible.
+  !isDevelopment &&
+    terser({
+      warnings: true,
+      ecma: 2015,
       keep_fnames: true,
-      keep_fargs: true,
-      if_return: false,
       ie8: false,
-      sequences: false,
-      loops: false,
-      conditionals: false,
-      join_vars: false,
-    },
-    mangle: {
-      module: true,
-      keep_fnames: true,
-    },
-    output: {
-      beautify: true,
-      braces: true,
-      indent_level: 2,
-    },
-  }),
-];
+      compress: {
+        pure_getters: true,
+        toplevel: true,
+        booleans_as_integers: false,
+        keep_fnames: true,
+        keep_fargs: true,
+        if_return: false,
+        ie8: false,
+        sequences: false,
+        loops: false,
+        conditionals: false,
+        join_vars: false,
+      },
+      mangle: {
+        module: true,
+        keep_fnames: true,
+      },
+      output: {
+        beautify: true,
+        braces: true,
+        indent_level: 2,
+      },
+    }),
+].filter(Boolean);
 
 export default [
   {