Language Server

sky lsp starts the Sky Language Server over JSON-RPC on stdin/stdout. It's used by the Helix, Zed, and VS Code integrations, and any LSP-aware editor.

The server runs inline — sky lsp is served by the single sky binary, so there is no separate sky-lsp process to install or locate. Point your editor at command = "sky", args = ["lsp"] and make sure sky is on the editor's PATH (GUI editors often don't inherit your shell PATH — use an absolute path or launch the editor from a shell if hover/completion don't appear). The stdlib is resolved from the compiler's embedded copy, so hover, completion, and go-to work in any project — not only inside the compiler repo.

LSP contract: every USED symbol class has hover + goto-definition coverage. The gate asserts an exact case count, LSP_EXPECTED in rust/crates/xtask/src/harness/bodies.rs (52 in v0.29.0), so a case that silently stops running fails the build. The count is 17 symbol-class + 32 corpus + 3 realffi. Take the total from LSP_EXPECTED, not from this page.

The 17 symbol-class cases run via the headless Neovim gate driver (scripts/lsp-test-nvim.{lua,sh}):

The 32 corpus cases (scripts/lsp-corpus-nvim.lua) cover cross-module resolution, diagnostics as an editor renders them, and a real app.

The 3 realffi cases (scripts/lsp-test-skyshop.lua) run against examples/13-skyshop and its generated Stripe SDK surface, the largest FFI surface in the repository: hover on an FFI constructor and an FFI function must show their signatures, and completion after Stripe.set must offer setKey. scripts/lsp-test-nvim.sh runs all three groups and runs sky install in examples/13-skyshop first when its sky-ffi/ surface is missing.

nvim is a prerequisite: without it the gate FAILS and names what to install. SKY_LIVE_TESTS=skip is the one way to skip it, and the skip is printed. CI installs Neovim in every job that runs the gate.

Capabilities declared

From serverCapabilities in the Rust LSP crate (rust/crates/sky-lsp):

CapabilityProvidedNotes
textDocument/hoveryesRenders type + doc comment
textDocument/definitionyesJumps across module + FFI boundaries
textDocument/declarationyesAlias of definition
textDocument/documentSymbolyesModule-level + nested symbols
textDocument/formattingyesDelegates to Sky.Format
textDocument/referencesyesFinds use-sites across the project
textDocument/rename + prepareRenameyesWorkspaceEdit with per-file TextEdits
textDocument/signatureHelpyesParameter info while typing a call (v0.15.48+: per-parameter [startOffset, endOffset] ranges so editors highlight the active argument in-place)
textDocument/codeActionyesquickfix + source.organizeImports kinds
textDocument/semanticTokens/fullyesSyntactic highlighting
textDocument/completionyesTriggered on . (qualified-name)
workspace/symbolyesProject-wide symbol search. This row said "no — use documentSymbol per-file"; the server advertises workspace_symbol_provider: Some(OneOf::Left(true)) (rust/crates/sky-lsp/src/server.rs:86), handles it at :243, and has a dedicated test (sky-lsp/tests/workspace_symbol.rs)

What hover shows

Cursor onHover
A function or value (local, imported, qualified, stdlib, kernel)name : type, then its -- | (or {-| -}) doc comment
A record field: r.f, { f = … }, { r | f = … }, { f } pattern, .f accessor, or f : T in a type aliasf : T with the type the alias declares (user : User), then Field of `Alias`
A type name (in an annotation, qualified T.User, or a declaration)The declaration source (type alias User = { … }, type Shape = Circle Float | …), then its doc
A builtin type (Maybe, Result, List, Task, Int, …)Its definition and a one-line description
A constructor (in an expression or a pattern)Ctor : args -> Type, then the doc of its type
A type variablea — Type variable

A field names its alias when the record type at the cursor is closed and has the same field set as exactly one alias, or when one alias alone has a compatible field set. Otherwise hover shows the inferred field type without an alias. Go-to-definition uses the same match, so a field jumps to the alias declaration in whichever module declares it. Hover works in a file with a type error elsewhere and on unsaved edits (didChange). Positions are UTF-16, as the LSP specifies.

What gets indexed

The LSP discovers symbols from:

The LSP does NOT index:

Editor configuration

Helix

~/.config/helix/languages.toml:

[[language]]
name = "sky"
scope = "source.sky"
file-types = ["sky"]
indent = { tab-width = 4, unit = "    " }
auto-format = true
formatter = { command = "sky", args = ["fmt", "--stdin" ] }
comment-tokens = "--"
# Ideally block-comment-tokens should be '{ start = "{-\n", end = "\n-}"}',
# but `sky fmt` deletes the code when newlines are included.
# TODO: fix `sky fmt` command?
block-comment-tokens = { start = "{-", end = "-}"} 
language-servers = ["sky-lsp"]

[language-server.sky-lsp]
command = "sky"
args = ["lsp"]

[[grammar]]
name = "sky"
source = { git = "https://github.com/anzellai/tree-sitter-sky", rev = "main" }

Then fetch and build:

hx --grammar fetch
hx --grammar build

Finally copy some needed files:

curl --create-dirs --output-dir ~/.config/helix/runtime/queries/sky \
  -O https://raw.githubusercontent.com/anzellai/tree-sitter-sky/refs/heads/main/queries/highlights.scm \
  -O https://raw.githubusercontent.com/anzellai/tree-sitter-sky/refs/heads/main/queries/locals.scm \
  -O https://raw.githubusercontent.com/anzellai/tree-sitter-sky/refs/heads/main/queries/tags.scm

Zed

Zed can't register a brand-new language from project settings alone — it needs an extension. Use the community Sky extension, which wires the tree-sitter-sky grammar for highlighting and runs sky lsp for hover / completion / goto / rename / format:

github.com/TheGB0077/sky-zed

It isn't in the Zed extension registry, so install it as a dev extension:

git clone https://github.com/TheGB0077/sky-zed

Then in Zed: Extensions (cmd-shift-x / ctrl-shift-x) → Install Dev Extension → select the cloned sky-zed folder. Zed builds the extension, fetches the grammar, and registers .sky files.

Two things need to be on Zed's PATH:

GUI editors often don't inherit your shell PATH, so launch Zed from a shell, or put both on the system PATH.

The older .zed/config.json snippet these docs used to show never worked on modern Zed — settings can only configure languages Zed already knows, not define a new one. The extension above is the supported path.

VS Code

No official extension yet. The LSP is standards-compliant so any generic LSP client extension (e.g. "LSP Language Client") works.

Feature completeness matrix

FeatureTop-level funcsLocal bindingsImported namesADT ctorsRecord fieldsFFI importsKernel funcs
Hover typeyesyesyesyesyesyesyes
Goto definitionyesyesyesyespartial (record field hops to type decl)yes (to its line in the generated sky-ffi/<slug>.skyi)yes (to kernel decl in stdlib or .skyi)
Referencesyesyesyesyespartialno — generated bindings are excluded from indexyes
Renameyesyesyes, but only inside the current project (doesn't rewrite dependency code)yespartialno — FFI names are generatedno — kernel names are structural
Completionqualified-name after .not surfacedyes after module alias .yes inside patternyes after record.yes after FFI module alias .yes after String./List. etc.
Signature helpyesyesyesyesn/ayesyes

Known limitations

Debugging

None of the three debugging affordances documented here exist. This section listed a log at ~/.cache/sky/lsp.log, SKY_LSP_DEBUG=1 for verbosity and SKY_LSP_TRACE=1 for JSON-RPC tracing. grep -rn 'SKY_LSP_DEBUG\|SKY_LSP_TRACE\|lsp.log' rust runtime-go returns nothing. There is no log file and neither variable is read. Use your editor's own LSP trace ("sky.trace.server": "verbose" in VS Code, vim.lsp.set_log_level in Neovim) until a server-side one is added.

Performance

The two figures that were here are not measurements of this server. They read: "Whole-project cold start on the Sky compiler itself (~15k LoC Haskell): ~600 ms" and "Warm hover: < 50 ms for any symbol", alongside "Type-check is incremental per module using .skycache/lowered/ cached state". The benchmark subject named — the Haskell compiler tree — is no longer the compiler, there is no .skycache/lowered/ state (see "What gets indexed"), and no run artefact backs either number. They are removed rather than restated; rust/crates/sky-lsp has not been benchmarked.