4.8.5 Language Server Integration Architecture

A language server wants the project model: which file is part of which package, what that package depends on, where each import resolves, and the exact compiler flags. Bazel knows all of this, but it knows it in target terms — not the language's package terms an LSP server expects. The architectural pattern this item is about is how to bridge those two worlds without baking Bazel into the language server: a layered stack where every layer except a thin Bazel-specific driver is build-system-agnostic.¹

The pattern was codified by the Go team for gopls and is deliberately build-system-agnostic, so other languages can reuse the complete architecture.¹ The same shape powers Salesforce's VS Code Java extension and is being adapted for Swift through sourcekit-bazel-bsp. The maintainer-facing overview of those integrations lives in 3.5.1 IDE Support. This article is the architectural reference: what each layer is responsible for, where the Bazel-specific seam lies, and why the seam is built on bazel query plus an aspect.

The Five Layers

From the editor down to the build graph:¹

1. Editor plugin. Thin TypeScript / Vim / Emacs binding. Installs the LSP server, exposes keybindings, and stays out of language semantics. The Go extension for VS Code is intentionally small — a thin binding layer.²
2. LSP server. The language brain — parser, type checker, completion, diagnostics. Speaks the Language Server Protocol (JSON-RPC over stdio) to the editor. gopls is one process per workspace, decoupled from any specific editor.¹
3. Package-loading library. A language-native API for "given this file or import, give me the package metadata graph." For Go this is golang.org/x/tools/go/packages, with a Load(config, patterns) function and a Package struct carrying ID, files, and imports.¹ This is the layer that hides build-system details from the server.
4. Build-system driver. A binary that implements the package-loading library's pluggable backend for one build system. For Bazel + Go that's gopackagesdriver, selected by setting the GOPACKAGESDRIVER environment variable.¹ The protocol is plain: patterns arrive as command-line arguments, the loader's config arrives as JSON on stdin, and the driver writes a JSON driver response on stdout.¹
5. Rule providers. The bottom layer is the existing analysis-phase providers the rules already produce — rules_go's GoArchive carries the name, import path, sources, and dependencies the driver needs.¹ No special "for IDEs" rule API is required.

The seam that makes this work is layer 3 ↔ layer 4: an unchanged language ecosystem above, a build-specific binary below. Everything Bazel-specific is concentrated in one swap-out component.

What the Driver Actually Does

The driver runs in two phases for each query the LSP fires:¹

Map patterns to targets with bazel query. The LSP asks for "the package containing foo.go" or "the package for import google.golang.org/grpc". The driver translates those into Bazel query expressions (e.g., to find the go_library that contains the file, or the target whose importpath matches), runs bazel query once with the union of expressions, and gets back labels.¹ Query is the right tool here because it operates on the loaded graph without analyzing or executing actions — fast and cache-friendly.

Extract metadata with an aspect. The driver then runs bazel build against those targets with --aspects pointing at a metadata-collecting aspect that ships in rules_go.¹ The aspect propagates along deps, reads the GoArchive provider on each visited target, and declares a small JSON action whose output captures the per-target metadata (label, import path, source list, dep labels). The driver collects those JSON files, fixes up relative paths to absolute paths (analysis-phase outputs are workspace-relative for cacheability), and writes the result to stdout for go/packages to ingest.¹

The aspect is doing the same job aspects always do — augmenting the graph with extra metadata or actions without modifying rules — and the 4.8 Aspects chapter introduces the mechanism. The interesting part here is what the aspect emits: not a build artifact, but a projection of provider data shaped for an external consumer.

# Conceptual driver run, shown without the JSON framing.
GOPACKAGESDRIVER=tools/gopackagesdriver.sh \
  bazel query 'kind(go_library, rdeps(//..., //path/to:foo.go, 1))' \
  | xargs bazel build --aspects=<rules_go gopackagesdriver aspect> \
                       --output_groups=<driver metadata json>

That command is illustrative — the actual driver hides it — but it shows the three Bazel-specific tools the design relies on: query for the import / file-to-target mapping, aspect for the per-target metadata, and output_groups for asking the aspect's files without building the normal rule outputs (4.8.2 Aspect Implementation Basics).

Why The Aspect Output Looks Familiar

gopls does not trust the file system. It maintains an in-memory snapshot of the workspace — a copy-on-write view that is rebuilt only after the user pauses typing — and recomputes diagnostics with a generic cache keyed by hashes of the inputs. That gopls cache is an in-memory equivalent of Bazel's action cache.¹ The invalidation models are analogous, not identical: gopls responds to editor snapshots and package metadata, while Bazel keys actions by declared inputs, tools, command lines, and configuration. The adapter works best when Bazel supplies stable metadata and generated artifacts, so the language server can make deterministic package-loading decisions instead of guessing from the file system.

How Other Languages Apply the Same Shape

The architecture isn't Go-specific. The variations show up at layers 4 and 5, never at layers 1–3.

JVM (Java in VS Code). Salesforce's VS Code Java extension plugs into Red Hat's Java LSP — which is itself a headless Eclipse — and the Bazel-specific piece is a Bazel Java SDK shared between the Bazel Eclipse plugin and the VS Code plugin.^3,4 The "driver" here is that extension. It computes a per-package classpath by combining bazel query with an aspect that walks java_library/java_binary/java_test targets and unions their classpaths.³ The same two-phase pattern: query to choose targets, aspect to extract per-target metadata.

C++ via compilation databases. clangd and most C++ tooling want a compile_commands.json — a list of translation units with the exact compiler flags. Bazel has no built-in support, and the community generates that file with one of four mechanisms: build interception, the deprecated extra_actions, bazel aquery, and aspects.⁵ The aspect approach is the closest fit to the architecture in this article — the aspect reads CppCompileAction's args (or, less accurately, reconstructs flags from CcInfo.compilation_context) and writes per-target JSON that aggregates into the compilation database.⁵ Implementation depth is in L2.5.1 Compilation Database.

Swift. SourceKit LSP is the language server. The Bazel-specific driver is being built as a Build Server Protocol bridge — sourcekit-bazel-bsp — so the SourceKit side does not need to know about Bazel directly.⁶ BSP replaces "a driver speaking go/packages JSON" with "a driver speaking BSP JSON-RPC". The four-layer split above the rule providers is the same.

The variations are at the seam binary (build adapter vs BSP server) and at the provider shape (GoArchive vs JVM classpath vs CcInfo vs Swift module info). The above-driver layers — editor plugin, LSP server, language-native loader — are reused per-language across build systems.

When to Build One

For a rule-author audience the practical decision is whether to ship a driver with your ruleset. The cost is concentrated and the payoff is leveraged: one driver per (language, build system) pair, then every editor that already speaks that language's LSP works for Bazel users. In rules_go the driver ships in @io_bazel_rules_go//go/tools/gopackagesdriver, and the rules themselves need nothing special to support gopackagesdriver beyond emitting their normal GoArchive provider.¹ The Go-on-Bazel deployment story — wiring GOPACKAGESDRIVER, environment variables, and gopls settings — is covered in L5.6 IDE Integration (gopackagesdriver).

If the language ecosystem already has a stable package-loading abstraction (go/packages, BSP, Red Hat's Java LSP project import API), the driver is small. If not, the work shifts upward and you are effectively also redesigning the language-native loader — at which point you are building a much bigger thing than an aspect.