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

[JoviDeCroock]

Root cause

Two independent problems prevented breakpoints in packages/graphqlsp/src/*.ts from binding when attaching to tsserver (TSS_DEBUG_BRK=9559):

1. Sourcemap sources are relative and resolve to the wrong place. The build emits sources like ../src/index.ts, relative to dist/. But tsserver loads the plugin from the example project's node_modules, where pnpm has either symlinked or hard-link-copied the package (e.g. node_modules/.pnpm/file+packages+graphqlsp.../node_modules/@0no-co/graphqlsp/dist/graphqlsp.js, as in the issue). Resolved from there, ../src/index.ts points at a nonexistent path or at the pnpm copy of the sources — never at the real packages/graphqlsp/src/index.ts the contributor set breakpoints in. Breakpoint binding is by path, so they stay unbound. (sourcesContent was already complete — that was not the problem.)
2. The attach config ignored sourcemaps under node_modules. The repo's .vscode/launch.json attach configuration only set port: 9559, so vscode-js-debug's default resolveSourceMapLocations (["${workspaceFolder}/**", "!**/node_modules/**"]) applied — which excludes exactly the location the plugin is loaded from. This is the "sourcemaps are ignored" part of the issue and it's a js-debug default, not something the build can fix; it has to be configured away in launch.json.

Fix

• scripts/rollup.config.mjs: when NODE_ENV=development (i.e. pnpm --filter @0no-co/graphqlsp dev):
  • sourcemapPathTransform rewrites every sourcemap source to an absolute path, so maps resolve to the real files in packages/graphqlsp/src no matter where pnpm materializes the built package;
  • terser is skipped, keeping mappings 1:1 with the rollup/babel output (and speeding up watch rebuilds).
• .vscode/launch.json: the attach config now sets sourceMaps: true, resolveSourceMapLocations: ["${workspaceFolder}/**"] (no node_modules exclusion), and outFiles covering packages/graphqlsp/dist and the plugin's dist inside any node_modules.

Production/publish output is unchanged — verified byte-identical (see below). No new .map files are shipped: dist/*.map was already published before this change, with identical content. Hence no changeset: published artifacts are unaffected; only dev-build behavior and docs changed. Absolute (machine-specific) source paths only ever appear in local dev builds.

What was verified

• NODE_ENV=development pnpm --filter @0no-co/graphqlsp build, then a Node script over dist/graphqlsp.js.map and dist/chunks/api-chunk.js.map:
  • all sources (14 + 20) are absolute paths to existing files; sourcesContent present for every source;
  • spot-checked mappings with the source-map package (originalPositionFor):
    • create(info) in dist/graphqlsp.js 4135:9 → packages/graphqlsp/src/index.ts 42:9 (function create(info: ts.server.PluginCreateInfo) {)
    • getGraphQLDiagnostics decl in dist/chunks/api-chunk.js 4569:9 → packages/graphqlsp/src/diagnostics.ts 215:16
    • findAllCallExpressions decl → packages/graphqlsp/src/ast/index.ts 137:16
• Production regression: snapshotted dist/ from a pre-change pnpm --filter @0no-co/graphqlsp run build, rebuilt after the change, diff -r reports byte-identical output (including .map files).
• Full pnpm run test:e2e: 11 files, 52/52 tests passed.

What was not verified: the interactive VS Code attach flow itself (two editor windows + TSS_DEBUG_BRK) — that can't be reproduced headlessly here. The verification above proves the two identified root causes are gone (maps resolve to real, existing src files from the loaded location; the launch config no longer excludes them), which is precisely what js-debug needs to bind the breakpoints from the issue.

Docs changes

README "Local development" gains a "Debugging with breakpoints" walkthrough: run the dev build (pnpm --filter @0no-co/graphqlsp dev), open the example with TSS_DEBUG_BRK=9559, attach via the provided launch configuration from the root window, plus a note that production builds' relative-path sourcemaps won't bind breakpoints.

Closes #304

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1bac82e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR