Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Language Server

The FOL language server is started with:

fol tool lsp

It runs over stdio and is meant to be launched by editors.

Current Feature Set

The current working surface includes:

  • initialize / shutdown / exit
  • document open / change / close
  • diagnostics
  • hover
  • go-to-definition
  • whole-document formatting
  • code actions for compiler-suggested unresolved-name replacements
  • signature help for plain and qualified routine calls
  • references
  • rename for same-file local and current-package top-level symbols
  • semantic tokens
  • document symbols
  • workspace symbols for current open workspace members
  • completion
  • the same compiler-backed behavior for ordinary source files and build.fol

This is a V1 surface only. The editor does not claim V2-aware language support, broad rename outside the documented safe classes, or range formatting.

That means build files should not need a separate editor mode. build.fol goes through the same language server entrypoint as the rest of the package.

textDocument/didChange accepts both whole-document replacements and ranged change events. The server applies ranged changes in order against the current in-memory document version.

The server advertises incremental text sync by default. Full-document sync remains an explicit opt-in for clients/configs that need it.

Formatting is intentionally limited to textDocument/formatting. textDocument/rangeFormatting remains unsupported until the formatter can preserve surrounding structure safely instead of guessing at partial blocks.

Current whole-document formatting also normalizes blank-line runs: leading blank lines are removed and repeated blank lines collapse to one.

Analysis Model

The server works like this:

  1. receive editor request/notification
  2. map the open document to a package/workspace context
  3. materialize an analysis overlay for the in-memory document state
  4. run parse/package/resolve/typecheck as needed
  5. convert compiler results into LSP responses

Package/workspace root discovery is cached for the current session once a document directory has been mapped.

That means diagnostics and navigation are compiler-backed, not guessed from Tree-sitter alone.

For open documents, diagnostics and semantic snapshots are cached separately.

didOpen and didChange refresh diagnostics for the current in-memory text.

Hover, definition, signature help, references, rename, semantic tokens, document symbols, workspace symbols, and completion use a semantic snapshot keyed by document version and reuse it until didChange or didClose invalidates it.

Diagnostics

Compiler diagnostics remain canonical.

The server adapts them into LSP diagnostics for the currently open document.

LSP diagnostics include the diagnostic code in the message (e.g. [R1003] could not resolve name 'answer') so editors display the code inline.

The server deduplicates diagnostics by (line, code) before publishing. This means a parse cascade that produces many identical errors on the same line will show at most one diagnostic per line per code in the editor.

Expected Behavior

If the LSP client is attached correctly, you should expect:

  • source-file diagnostics in the open file
  • hover on resolved symbols
  • go-to-definition across current-package and imported symbols where supported
  • whole-document formatting edits from textDocument/formatting
  • code actions only when the compiler attached an exact replacement suggestion The current shipped code-action inventory is intentionally narrow: unresolved-name replacements only.
  • signature help for supported routine call sites
  • references for the supported symbol classes
  • rename for same-file local and current-package top-level symbols only
  • semantic tokens for semantic identifier categories
  • document symbols for the current file
  • workspace symbols across the current open workspace members
  • completion in ordinary source files and build.fol

If the client is attached but you see no diagnostics at all, the likely issue is not Tree-sitter. It is the LSP request/attach path.

For the compiler-owned contracts behind diagnostics and semantic editor behavior, see Compiler Integration.