RFC: GraphQL LSP with multi-schema support#307
Merged
Conversation
Comprehensive design document covering: - Tagged template API design (3 pattern candidates with comparison) - LSP architecture analysis (graphql-language-service-server vs from-scratch vs hybrid approach) - Multi-schema resolution via import path association - Implementation plan (5 phases) - Alternatives considered and open questions Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Supplementary document covering: - LSP protocol requirements by tier (core/navigation/productivity/advanced) - graphql-language-service interface layer API analysis with function signatures - Components that must be built from scratch (template extractor, position mapping, schema management, cross-file fragments, handler wiring) - soda-gql-specific extension opportunities (inlay hints, code lens, custom validation rules, semantic tokens, multi-schema context indicator, compat migration actions, build integration commands) - Risk analysis and dependency overview Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Commit to Pattern C (gql.{schemaName} tagged template extension) and
Hybrid LSP architecture (graphql-language-service interface + custom
server). Move rejected alternatives (Patterns A/B, server wrap,
full scratch) to Alternatives Considered with rationale.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Rewrite API design to require callback wrapper:
- gql.{schemaName}(({ query, fragment }) => query`...`)
- query/mutation/subscription/fragment as tagged template tags
- Fragment Arguments RFC syntax for fragment variables
- Tagged template results callable for metadata chaining
- SWC for TS AST parsing in LSP
- Fragment Arguments preprocessor for graphql-js compatibility
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Test Coverage ReportOverall Coverage: 79.9% (10821/13537 lines)
|
Owner
Author
|
cursor review |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
4 tasks
whatasoda
added a commit
that referenced
this pull request
Feb 1, 2026
## Summary - Implement `@soda-gql/lsp` package providing a GraphQL Language Server Protocol server for soda-gql's tagged template API (RFC #307, Phase 0 + Phase 1) - SWC-based template extraction from `gql.{schemaName}(({ query }) => query`...`)` callback patterns with multi-schema resolution - LSP features: diagnostics (validation), completion (field/argument suggestions), hover (type information) - Fragment Arguments RFC syntax preprocessing (strips non-standard syntax before `graphql-language-service` validation) - Bidirectional TS ↔ GraphQL position mapping for accurate diagnostic/completion positions - CLI integration via `soda-gql lsp` command (stdio transport) ### Architecture | Component | File | Role | |-----------|------|------| | Schema resolver | `src/schema-resolver.ts` | Loads/caches GraphQL schemas from config | | Document manager | `src/document-manager.ts` | SWC-based tagged template extraction | | Fragment preprocessor | `src/fragment-args-preprocessor.ts` | Strips Fragment Arguments for validation | | Position mapping | `src/position-mapping.ts` | TS ↔ GraphQL position conversion | | Diagnostics | `src/handlers/diagnostics.ts` | Schema validation via graphql-language-service | | Completion | `src/handlers/completion.ts` | Field/argument autocompletion | | Hover | `src/handlers/hover.ts` | Type information on hover | | Server | `src/server.ts` | LSP protocol wiring (vscode-languageserver) | ### Not included (deferred) - `codegen lsp-config` subcommand (`.graphqlrc.generated.json` generation) — separate PR - Phase 2+ features (definition, cross-file fragments, inlay hints) ## Test plan - [ ] `bun --conditions=@soda-gql test packages/lsp/` — 60 tests pass - [ ] `bun typecheck` — no LSP-introduced errors (pre-existing `packages/core` errors only) - [ ] `bun --conditions=@soda-gql packages/cli/src/index.ts lsp --help` — prints help - [ ] Integration tests verify end-to-end flow: document parsing → diagnostics/completion/hover 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Key design decisions
gql.{schemaName}(({ query, fragment }) => query...)— callback required for intermediate module compatibility, tag names encode operation kindvscode-languageserver+graphql-language-serviceinterface layer (not server) + SWC parserDocuments
docs/rfcs/graphql-lsp-multi-schema.mddocs/rfcs/graphql-lsp-implementation-details.mdOpen questions (to be resolved during implementation)
Test plan
🤖 Generated with Claude Code