bux-lang/docs/LSP.md

Bux Language Server (bux-lsp)

Status: v0.17.0 — stdio JSON-RPC 2.0 language server
Binary: tools/bux-lsp (make lsp)
Editors: VS Code extension in vscode/; any LSP client via stdio

Bux already ships a real Language Server Protocol implementation. It is not syntax-only: hover and outline use bootstrap semantic analysis when available, and error underlines (red squiggles) come from in-process lex / parse / type-check of the live editor buffer on every open, edit, and save.

---

Quick start

# From the repository root
make lsp                 # build → tools/bux-lsp
make vscode              # optional: compile VS Code client
make test-lsp            # unit + smoke tests

Point your editor at the binary:

Client	How
VS Code	Open the repo (or install vscode/). Extension auto-finds tools/bux-lsp. Setting: bux.lsp.path
Neovim	vim.lsp.start({ cmd = { "path/to/tools/bux-lsp" }, … })
Helix / Zed / Emacs	Configure language server command = bux-lsp (stdio)
Any LSP client	Spawn bux-lsp with no args; speak LSP over stdin/stdout

Protocol framing: standard Content-Length headers + JSON-RPC 2.0 body.

---

Capabilities (v0.16)

Method	Support	Notes
initialize / shutdown / exit	✅	serverInfo: bux-lsp 0.17.0
textDocument/didOpen / didChange / didSave	✅	Full text sync (textDocumentSync: 1)
textDocument/publishDiagnostics	✅	Live underlines on open/change/save (in-process); optional buxc merge on open/save
textDocument/completion	✅	Trigger: . :
textDocument/hover	✅	Sema types for globals/stdlib; scoped locals + inferred let
textDocument/definition	✅	Go to definition
textDocument/references	✅	Find all references
textDocument/rename + prepareRename	✅	Locals, globals, fields, variants, methods, import path segments
textDocument/documentSymbol	✅	Outline
workspace/symbol	✅	Fuzzy-ish workspace search
textDocument/implementation	✅	Interface → implementing types/methods
Call hierarchy	✅	prepare / incoming / outgoing (funcs + methods + interface dispatch)
Type hierarchy	✅	prepare / supertypes / subtypes (extend T for I)

Version history (high level)

Ver	Highlights
0.2–0.3	Diagnostics, hover, go-to-def, outline, real sema enrich
0.4	Position-sensitive locals, inferred let types
0.5	References + rename
0.6	workspace/symbol
0.7–0.10	Deep rename (fields/variants/methods/paths)
0.8–0.11	Call hierarchy (methods, interface dispatch)
0.12–0.14	Module-path rename, implementation, workspace import index
0.15–0.16	Type hierarchy + workspace type-impl index
0.17	Live buffer diagnostics (lex/parse/sema) on every edit — red squiggles without buxc on PATH

---

VS Code

See vscode/README.md for install, commands, and settings.

make vscode
# Status bar: "Bux" — click to restart server
# Commands: Bux: Restart / Stop / Show Output

Settings:

• bux.lsp.enabled (default true)
• bux.lsp.path (default "bux-lsp"; also searches tools/bux-lsp)
• bux-lsp.trace.server — off | messages | verbose

---

Manual smoke (no editor)

# After make lsp
printf 'Content-Length: 85\r\n\r\n{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' \
  | ./tools/bux-lsp
# Expect a JSON result with "capabilities" and serverInfo version 0.17.0

Error underlines (what students usually want)

Open a .bux file with the LSP running. A type error such as:

func Main() -> int {
    let x: int = "boom";  // red underline under "boom"
    return 0;
}

is reported via textDocument/publishDiagnostics as soon as the file is opened or you type (didChange). No save required. Source field: "bux" (in-process) or "buxc" (optional CLI merge on open/save).

Automated coverage:

make test-lsp
# tools/smoke_lsp_diagnostics.sh   ← error underlines
# tools/test_lsp_locals.nim
# tools/smoke_lsp_hover.sh
# tools/smoke_lsp_rename*.sh
# tools/smoke_lsp_*hierarchy*.sh
# …

---

Limitations / not yet

Honest gaps (so Reddit / issue trackers stay accurate):

• No format-on-save via LSP yet (bux fmt exists as CLI; not textDocument/formatting)
• No semantic tokens provider (TextMate grammar handles highlighting in VS Code)
• No code actions / lightbulbs (quick-fixes)
• No inlay hints
• didChange uses a fast symbol path; full sema + diagnostics refresh mainly on open/save
• Completion is useful but not a full IDE IntelliSense engine
• Single-process stdio only (no TCP/socket mode)

PRs welcome: tools/lsp_server.nim, tests under tools/smoke_lsp_*.sh and make test-lsp.

---

Related

Doc / path	Role
tools/lsp_server.nim	Server implementation
vscode/	Official VS Code client
BuildAndTest.md	Build / test matrix
Makefile targets lsp, test-lsp, vscode