Racket

racket-langserver🔗ℹ

The racket-langserver is a Language Server Protocol implementation for Racket. This project seeks to use DrRacket’s public APIs to provide functionality that mimics DrRacket’s code tools as closely as possible.

1 Installation and usage🔗ℹ

A Racket runtime is a prerequisite, so before using racket-langserver, ensure that a Racket runtime is installed. You can install from the official download page or install one from your package manager.

First, install an LSP runtime for your editor.

Next, install the package via raco:

raco pkg install racket-langserver

To update the racket-langserver use
raco pkg update racket-langserver

Once it is installed, you can configure your editor to use a custom LSP client for Racket (and all installed module languages, e.g. Rhombus) files (usually .rkt), and set the command for the custom client to

racket -l racket-langserver

You may need to restart your LSP runtime or your editor for racket-langserver to start.

1.1 VSCode🔗ℹ

Use the Magic Racket extension.

2 Interfaces🔗ℹ

(require racket-langserver/common/interfaces)
	package: racket-langserver

This module provides the data types used by the LSP protocol layer and the doc library API. Most structs are generated by define-json-struct, which is basically struct with JSON encode/decode support. Shared runtime structs such as SemanticToken and LexerEntry are defined directly when JSON encode/decode support is not needed.

Each define-json-struct type exports:

A keyword constructor / match expander (e.g. Pos) that also accepts positional arguments.
A predicate (e.g. Pos?).
Accessors for each field (e.g. Pos-line, Pos-char).
A JSON-hash match expander Name-js (e.g. Pos-js) that matches immutable hasheq tables using the JSON field names.
A JSON-hash predicate Name-js? (e.g. Pos-js?).

To convert a struct value to a JSON-compatible hasheq, use jsexpr-encode from racket-langserver/json-util. Nested struct values are encoded recursively.

2.1 Position and Range🔗ℹ

struct
(struct Pos (line char)
    #:transparent)
  line : exact-nonnegative-integer?
  char : exact-nonnegative-integer?

LSP position (zero-based line and character offset). The JSON field for char is character.

struct
(struct Range (start end)
    #:transparent)
  start : Pos?
  end : Pos?

LSP half-open range, the character at end is excluded.

2.2 Edit Payloads🔗ℹ

struct
(struct TextEdit (range newText)
    #:transparent)
  range : Range?
  newText : string?

A single text replacement operation. Apply by replacing the text covered by the range field with newText. Apply edits with doc-apply-edits! (including single-edit lists). This avoids range-shift pitfalls when multiple edits target nearby offsets.

struct
(struct WorkspaceEdit (changes)
#:transparent)
changes : (hash/c symbol? (listof TextEdit?))

Collection of document edits keyed by document URI.

2.3 Query Responses🔗ℹ

struct
(struct Location (uri range)
    #:transparent)
  uri : string?
  range : Range?

Identifies a source location in a document. The uri field names the target document, and range gives the span within that document.

struct
(struct Hover (contents range)
    #:transparent)
  contents : string?
  range : Range?

Hover information at a document position.

The contents field is Markdown from a Hover-Card. Sections appear in this fixed order:

Optional Typed Racket type in a racket fence. Labeled Type, or Type (stale) when the type comes from a retained trace.
Optional fenced definition. For a current same-file trace with local declaration detail, this shows code around the bound declaration. Local uses share that stored detail; each use does not rebuild it. Own-line leading comments above the form may also appear. Usually this slot shows the outermost same-line form (a compact binding clause, a one-line header collapsed with ..., or a complete one-line form). When no form on the identifier line fits, the full nearest enclosing form is shown. Without same-file detail, a Scribble bluebox signature may fill this slot instead. Racket-family forms use a racket fence. Rhombus forms use a rhombus fence. A lone definition fence is unlabeled. When a type precedes it, the fence is labeled Source or Signature.
Optional documentation after a — separator when earlier slots are also present: an online link and/or a locally installed docs excerpt. Link comes before body.
Optional check-syntax mouse-over text as a plain unlabeled note, only when it is the sole content (no type, definition, or docs link). The text is unchanged.

When a trace is old, same-file source detail still comes from the current buffer and retained types remain visible as stale. These results can be useful, but the binding link or type may be wrong until expansion finishes. Imports and cross-file bindings do not get same-file source snippets. Their cards use documentation when available, otherwise check-syntax text alone.

The range field comes from the inferred-type interval when present, including literal and expression-delimiter intervals. Otherwise it comes from check-syntax mouse-over status or a kept same-file source-detail range.

struct
(struct DocumentHighlight (range)
#:transparent)
range : Range?

Highlight entry for one symbol occurrence. The range field is the span to highlight in the current document.

struct
(struct CompletionItem (label)
#:transparent)
label : string?

One completion candidate shown by the client. The label field is the display text for the candidate.

struct
(struct CompletionList (isIncomplete items)
    #:transparent)
  isIncomplete : boolean?
  items : (listof CompletionItem?)

Completion response payload. The items field contains candidate entries. The isIncomplete field is always #t, indicating clients should continue filtering, sorting and may request updated results as the prefix changes.

struct
(struct SignatureInformation (label documentation)
    #:transparent)
  label : string?
  documentation : string?

One call-signature entry in a signature help response. The label field is the signature text shown to the user. The documentation field provides additional description for that signature.

struct
(struct SignatureHelp (signatures)
#:transparent)
signatures : (listof SignatureInformation?)

Signature help response payload. The signatures field contains the candidate call signatures for the call site, usually one entry per overload.

value
SymbolKind? : flat-contract?

Predicate for the SymbolKind JSON enum. Each variant maps a symbolic name to an LSP integer code:

Name		Code
File		1
Module		2
Namespace		3
Package		4
Class		5
Method		6
Property		7
Field		8
Constructor		9
Enum		10
Interface		11
Function		12
Variable		13
Constant		14
String		15
Number		16
Boolean		17
Array		18
Object		19
Key		20
Null		21
EnumMember		22
Struct		23
Event		24
Operator		25
TypeParameter		26

Access named constants via SymbolKind-Constant, SymbolKind-String, SymbolKind-Variable, etc.

struct
(struct SymbolInformation (name kind location)
    #:transparent)
  name : string?
  kind : SymbolKind?
  location : Location?

One symbol entry in document/workspace symbol results. The name field is the symbol display name. The kind field is a SymbolKind enum value (an LSP symbol kind integer code). The location field gives the symbol’s source location.

struct
(struct CodeAction (title kind diagnostics isPreferred edit)
    #:transparent)
  title : string?
  kind : string?
  diagnostics : (listof Diagnostic?)
  isPreferred : boolean?
  edit : WorkspaceEdit?

One code action returned by a code-action request. The title field is the user-visible action label. The kind field is the LSP action kind string (for example quick-fix or refactor). The diagnostics field lists diagnostics this action addresses. The isPreferred field marks the preferred action among alternatives. The edit field is the workspace edit to apply when the action is chosen.

value
DiagnosticSeverity? : flat-contract?

Predicate for the DiagnosticSeverity JSON enum.

Name		Code
Error		1
Warning		2
Information		3
Hint		4

Access named constants via DiagnosticSeverity-Error, DiagnosticSeverity-Warning, etc.

struct
(struct Diagnostic (range severity source message)
    #:transparent)
  range : Range?
  severity : DiagnosticSeverity?
  source : string?
  message : string?

One diagnostic reported to the editor. The range field identifies the affected source span. The severity field is a DiagnosticSeverity enum value: 1 = error, 2 = warning, 3 = information, 4 = hint. The source field names the producer (for example racket-langserver). The message field is the user-facing diagnostic text.

2.4 Resyntax Results🔗ℹ

struct
(struct Resyntax-Result (start end message rule-name new-text)
    #:transparent)
  start : exact-nonnegative-integer?
  end : exact-nonnegative-integer?
  message : string?
  rule-name : symbol?
  new-text : string?

One refactoring recommendation produced by the optional resyntax integration. The start and end fields are absolute character offsets into the document text. The message field is the user-facing explanation for the recommendation. The rule-name field identifies the resyntax rule that fired. The new-text field is the replacement text suggested for the covered range.

2.5 Formatting Options🔗ℹ

struct
(struct FormattingOptions ( tab-size
insert-spaces
trim-trailing-whitespace
insert-final-newline
trim-final-newlines
key)
    #:transparent)
  tab-size : exact-nonnegative-integer?
  insert-spaces : boolean?
  trim-trailing-whitespace : boolean?
  insert-final-newline : boolean?
  trim-final-newlines : boolean?
  key : (or/c false/c hash?)

Formatting options accepted by doc-format-edits.

The tab-size and insert-spaces fields are required in protocol payloads. The remaining fields (trim-trailing-whitespace, insert-final-newline, trim-final-newlines, key) are optional in the JSON payload; absent fields are represented as (Nothing) rather than #f. Test for an absent optional field with Nothing? from racket-langserver/common/json-util.

The corresponding JSON field names use camelCase: tabSize, insertSpaces, trimTrailingWhitespace, insertFinalNewline, trimFinalNewlines.

Not all generated accessors are exported. Public callers should rely on FormattingOptions-tab-size and FormattingOptions-trim-trailing-whitespace.

2.6 Lexer Entries🔗ℹ

struct
(struct LexerEntry (start end text type)
    #:transparent)
  start : exact-nonnegative-integer?
  end : exact-nonnegative-integer?
  text : string?
  type : symbol?

One cached lexer token entry returned by doc-token-at. The start and end fields are zero-based absolute character offsets. The text field is the exact token text. The type field names the lexer token class (for example symbol, string, or constant).

2.7 Semantic Tokens🔗ℹ

struct
(struct SemanticToken (start end type modifiers)
    #:transparent)
  start : exact-nonnegative-integer?
  end : exact-nonnegative-integer?
  type : SemanticTokenType?
  modifiers : SemanticTokenModifier?

One semantic token with absolute character offsets. The start and end fields are zero-based character positions. The type field is a SemanticTokenType enum value. The modifiers field is a SemanticTokenModifier enum value. Returned by doc-range-tokens; the caller encodes these into the LSP 3.17 relative-delta wire format.

value
SemanticTokenType? : flat-contract?

Predicate for the SemanticTokenType JSON enum.

Name		Value
variable		"variable"
function		"function"
string		"string"
number		"number"
regexp		"regexp"

value
SemanticTokenModifier? : flat-contract?

Predicate for the SemanticTokenModifier JSON enum.

Name		Value
definition		"definition"

3 Doc Library🔗ℹ

(require racket-langserver/doclib/doc)
	package: racket-langserver

The doc library provides single-threaded document helpers for representing and querying Racket source documents. All functions operate on document values that satisfy Doc? without touching the network or a thread scheduler, making them suitable for direct testing and reuse.

3.1 Document State🔗ℹ

syntax
Doc

Documentation placeholder for the opaque document struct type name. Use Doc? to test values and make-doc to construct them.

procedure
(Doc? v) → boolean?
  v : any/c
procedure
(Doc-uri doc) → string?
  doc : Doc?
procedure
(Doc-version doc) → exact-nonnegative-integer?
  doc : Doc?

Predicates and accessors for the opaque Doc document value. Doc? tests whether a value is a document. Doc-uri returns the document URI string. Doc-version returns the current nonnegative edit version.

procedure
(make-doc uri text [version]) → Doc?
  uri : string?
  text : string?
  version : exact-nonnegative-integer? = 0

Creates a new document state for the given uri and initial text. version defaults to 0 and tracks the edit sequence number. An initial (empty) build-trace% is allocated; call doc-expand! to populate it.

procedure
(doc-get-text doc) → string?
doc : Doc?

Returns the full current text content of the document.

procedure
(doc-apply-edits! doc edits) → void?
doc : Doc?
edits : (listof TextEdit?)

Applies a list of TextEdit values to doc. Edits are sorted and applied in descending start-position order so earlier edits do not shift the offsets of later ones. Raises an error if any two edits overlap. The output of doc-format-edits can be passed directly to this function if not #f.

procedure
(doc-apply-edit! doc range text) → void?
  doc : Doc?
  range : Range?
  text : string?

Applies a single text replacement to doc: replaces the content covered by range with text and adjusts the internal trace offsets accordingly. Prefer doc-apply-edits! when applying multiple edits so that offset ordering is handled automatically.

procedure
(doc-reset! doc new-text) → void?
doc : Doc?
new-text : string?

Replaces the full text with new-text and resets internal trace state. Use this for whole-file replacements.

procedure
(doc-update-version! doc new-ver) → void?
doc : Doc?
new-ver : exact-nonnegative-integer?

Updates the document’s tracked version number.

procedure
(doc-update-uri! doc new-uri) → void?
doc : Doc?
new-uri : string?

Updates the URI associated with the document.

procedure
(doc-copy-text-buffer doc) → (is-a?/c lsp-editor%)
doc : Doc?

Returns a mutable copy of the internal editor buffer.

3.2 Positions and Ranges🔗ℹ

All position helpers below work in terms of absolute character offsets (zero-based integer indices into the document text) as well as LSP Pos structs (line/character pairs).

procedure
(doc-pos->abs-pos doc pos) → exact-nonnegative-integer?
doc : Doc?
pos : Pos?

Converts an LSP Pos to an absolute character offset.

procedure
(doc-abs-pos->pos doc abs-pos) → Pos?
doc : Doc?
abs-pos : exact-nonnegative-integer?

Converts an absolute character offset to an LSP Pos.

procedure
(doc-line-start-abs-pos doc line) → exact-nonnegative-integer?
doc : Doc?
line : exact-nonnegative-integer?

Returns the absolute character offset at the start of line (zero-based).

procedure
(doc-line-end-abs-pos doc line) → exact-nonnegative-integer?
doc : Doc?
line : exact-nonnegative-integer?

Returns the absolute character offset at the end of line, not including the newline character.

procedure
(doc-end-abs-pos doc) → exact-nonnegative-integer?
doc : Doc?

Returns the absolute character offset one past the last character.

procedure
(doc-find-containing-paren doc pos)
→ (or/c exact-nonnegative-integer? #f)
doc : Doc?
pos : exact-nonnegative-integer?

Returns the absolute offset of the opening delimiter of the innermost parsed form (parenthesized or bracketed s-expression) that contains pos, or #f if pos is outside any parsed form.

3.3 Trace and Expansion🔗ℹ

These functions manage check-syntax expansion and the resulting trace.

procedure
(doc-expand! doc) → boolean?
doc : Doc?

Expands the document in-place, updates its trace to the current version, and walks the expanded text. Returns #t on success, #f if check-syntax expansion failed (e.g., the file has syntax errors). Trace-dependent query functions return fully accurate results only after a successful expansion. Lexer-only queries (such as doc-symbols and doc-token-at and doc-token-prefix-at) still work without expansion, but hover, definition, and reference queries will be stale or empty. This call does not compute or refresh stored resyntax results; use doc-resyntax!, or update them explicitly with doc-update-resyntax-result!, when you want resyntax-backed diagnostics and code actions to match the current text.

procedure
(doc-update-trace! doc
new-trace
new-version) → void?
  doc : Doc?
  new-trace : (is-a?/c build-trace%)
  new-version : exact-nonnegative-integer?

Replaces the document’s trace with a freshly computed one. Called internally by doc-expand! but also useful when a scheduler provides a new trace externally.

procedure
(doc-trace-latest? doc) → boolean?
doc : Doc?

Returns #t if the trace version matches the current document version, meaning the trace is up to date and query results are reliable.

procedure
(doc-walk-text trace text) → void?
trace : (is-a?/c build-trace%)
text : string?

Feeds text into trace for incremental token and hover collection. Called automatically by doc-expand!.

3.4 Resyntax🔗ℹ

These functions manage the optional resyntax recommendations attached to a document. They are separate from the check-syntax trace so callers can run resyntax synchronously in-process or compute results elsewhere and write them back later.

procedure
(doc-resyntax-available?) → boolean?

Returns #t when the optional resyntax package is available in the current process.

procedure
(doc-resyntax doc) → (listof Resyntax-Result?)
doc : Doc?

Analyzes the current text of doc with resyntax and returns the resulting recommendations without mutating the document. Returns an empty list when no recommendations are found or when resyntax is unavailable.

procedure
(doc-resyntax! doc) → void?
doc : Doc?

Runs doc-resyntax and stores the resulting recommendations on doc. This is the synchronous single-threaded convenience API for keeping doc-diagnostics and doc-code-action aligned with the document’s current text.

procedure
(doc-get-resyntax-results doc) → (listof Resyntax-Result?)
doc : Doc?

Returns the currently stored resyntax recommendations for doc. Editing or resetting the document clears previously stored results until resyntax is run again or new results are written with doc-update-resyntax-result!.

procedure
(doc-update-resyntax-result! doc results) → void?
doc : Doc?
results : (listof Resyntax-Result?)

Replaces the stored resyntax recommendations on doc with results. This is useful when resyntax analysis runs outside the main document thread, such as the language-server path that computes resyntax asynchronously and writes the finished results back later. The written results become the current resyntax state used by doc-diagnostics and doc-code-action until the document text changes.

procedure
(resyntax-result->diag doc res) → Diagnostic?
doc : Doc?
res : Resyntax-Result?

Converts res into an informational Diagnostic. The diagnostic range is derived from the result’s absolute offsets, and the diagnostic message is formatted as [rule-name] message.

procedure
(resyntax-result->code-action doc res) → CodeAction?
doc : Doc?
res : Resyntax-Result?

Converts res into a quick-fix CodeAction titled Apply rule [rule-name]. The action replaces the result range in doc with the result’s new-text.

3.5 Token and Symbol Utilities🔗ℹ

Lexer-derived token and symbol helpers. These do not require an up-to-date trace except where noted.

These lexer-derived helper APIs are not yet stable and may change between releases. The API is query-oriented: prefer point lookups and derived responses over bulk snapshot enumeration.

procedure
(doc-range-tokens doc range) → (listof SemanticToken?)
doc : Doc?
range : Range?

Returns semantic tokens that intersect range. Each SemanticToken struct has fields start, end, type, and modifiers (all absolute character offsets or enum values). The caller is responsible for encoding these into the LSP 3.17 delta format before sending them on the wire. Requires an up-to-date trace.

procedure
(doc-token-at doc pos) → (or/c LexerEntry? #f)
doc : Doc?
pos : exact-nonnegative-integer?

Returns the full lexer token covering absolute offset pos as a LexerEntry, or #f when pos does not fall within a token tracked by the cached lexer snapshot.

procedure
(doc-token-prefix-at doc pos) → string?
doc : Doc?
pos : exact-nonnegative-integer?

Returns the prefix of the lexer token covering absolute offset pos. When no token is found, returns the empty string.

3.6 Query Functions🔗ℹ

These return structured LSP responses. Most require an up-to-date trace; call doc-expand! first or check doc-trace-latest?. Exceptions are noted in individual entries.

procedure
(doc-hover doc pos) → (or/c Hover? #f)
doc : Doc?
pos : Pos?

Returns hover info at pos, or #f when check-syntax mouse-over status, Typed Racket type text, and same-file source detail are all missing. A docs link alone does not open a hover card.

When present, contents follows the fixed Hover-Card stack:

Optional Typed Racket type fence, labeled Type or Type (stale)
Optional fenced definition (same-file source, else docs signature). Labeled Source/Signature only when a type precedes it
Optional documentation link and/or excerpt after at most one —
Optional check-syntax mouse-over text only when it is the sole content. The text is unchanged and unlabeled

Source forms are read from the current buffer through kept trace ranges while an old trace refreshes. Retained Typed Racket types remain visible as Type (stale). The shown form or type can be useful, but the binding link or type may be wrong until expansion finishes. Code context is limited to 10 lines and 1000 source characters. Leading comments are limited to 10 lines and 200 source characters per line. Mouse-over status and documentation can also appear while an old trace refreshes.

procedure
(doc-completion doc pos) → CompletionList?
doc : Doc?
pos : Pos?

Returns completion candidates at pos. The list is always marked incomplete (isIncomplete is #t) since filtering is delegated to the client.

procedure
(doc-definition doc uri pos) → (or/c Location? #f)
  doc : Doc?
  uri : string?
  pos : Pos?

Resolves the definition location for the identifier at pos. Returns a Location in the same file for local bindings, a Location in the external file for required identifiers (triggering a cross-file check-syntax expansion), or #f if not found.

procedure
(doc-references doc uri pos include-decl?)
→ (or/c (listof Location?) #f)
  doc : Doc?
  uri : string?
  pos : Pos?
  include-decl? : boolean?

Returns all reference locations for the identifier at pos, or #f if no binding is found.

The include-decl? parameter is accepted for API compatibility with the LSP protocol but is not currently used in the implementation; the declaration site is always included when the binding is in the same file.

procedure
(doc-highlights doc pos) → (or/c (listof DocumentHighlight?) #f)
doc : Doc?
pos : Pos?

Returns document highlight entries for all occurrences of the symbol at pos, or #f if no binding is found.

procedure
(doc-rename doc uri pos new-name) → (or/c WorkspaceEdit? #f)
  doc : Doc?
  uri : string?
  pos : Pos?
  new-name : string?

Builds a workspace edit that renames all occurrences of the identifier at pos to new-name. Returns #f if the identifier cannot be renamed (e.g., it is imported from another module).

procedure
(doc-prepare-rename doc pos) → (or/c Range? #f)
doc : Doc?
pos : Pos?

Returns the range of the renameable identifier at pos, or #f if the identifier cannot be renamed (e.g., it is an external binding).

procedure
(doc-signature-help doc pos) → (or/c SignatureHelp? #f)
doc : Doc?
pos : Pos?

Returns signature help for the function call enclosing pos by scanning backward for the nearest opening parenthesis, or #f if not inside a call.

procedure
(doc-code-action doc range) → (listof CodeAction?)
doc : Doc?
range : Range?

Returns quick-fix code actions whose edits intersect range. This includes any quick fix stored in the current trace plus stored resyntax quick fixes produced by doc-resyntax! or doc-update-resyntax-result!. Returns an empty list when no actions are available.

procedure
(doc-diagnostics doc) → (listof Diagnostic?)
doc : Doc?

Returns the list of diagnostics for the document, including both trace diagnostics from the most recent doc-expand! run and any stored current resyntax diagnostics derived from doc-get-resyntax-results.

procedure
(doc-symbols doc uri) → (listof SymbolInformation?)
doc : Doc?
uri : string?

Returns all lexer-visible symbol, string, and constant occurrences in the document as SymbolInformation values with their source locations. Does not require an up-to-date trace; runs the lexer directly over the current text.

3.7 Formatting🔗ℹ

procedure
(doc-format-edits doc
fmt-range
#:formatting-options opts
[ #:on-type? on-type?])
→ (or/c (listof TextEdit?) #f)
  doc : Doc?
  fmt-range : Range?
  opts : FormattingOptions?
  on-type? : boolean? = #f

Computes formatting edits for the lines covered by fmt-range. Returns a list of TextEdit values to apply. For documents without a recognized s-expression language, returns an empty list.

When on-type? is #t, blank lines are indented too. For LSP on-type formatting requests, prefer doc-on-type-format-edits.

Formatting is performed on an internal copy of the document; the doc is not mutated by this call. Pass the result to doc-apply-edits! to apply the edits.

procedure
(doc-on-type-format-edits doc
pos
ch
#:formatting-options opts)
→ (or/c (listof TextEdit?) #f)
  doc : Doc?
  pos : Pos?
  ch : string?
  opts : FormattingOptions?

Computes formatting edits for an on-type formatting trigger. The pos argument is the cursor position after ch has been inserted.

For recognized s-expression languages, close delimiters format the containing form, and other triggers format the current line. For non-s-expression or unrecognized languages, returns an empty list.

Formatting is performed on an internal copy of the document; the doc is not mutated by this call. Pass the result to doc-apply-edits! to apply the edits.