512 lines
22 KiB
Text
512 lines
22 KiB
Text
/-
|
|
Copyright (c) 2025 Lean FRO. All rights reserved.
|
|
Released under Apache 2.0 license as described in the file LICENSE.
|
|
|
|
Author: Marc Huisinga
|
|
-/
|
|
module
|
|
|
|
prelude
|
|
import Lean.Server.FileWorker.WidgetRequests
|
|
import Lean.Widget.UserWidget
|
|
|
|
/-!
|
|
This file includes a complete overview over the Lean LSP API for documentation purposes.
|
|
-/
|
|
|
|
namespace Lean.Server.Overview
|
|
|
|
open Lean.JsonRpc Lean.Lsp Lean.Widget
|
|
|
|
inductive ProtocolExtensionKind
|
|
| standard
|
|
| leanSpecificMethod
|
|
| extendedParameterType (fieldNames : Array Name)
|
|
| extendedResponseType (fieldNames : Array Name)
|
|
| extendedParameterAndResponseType (parameterFieldNames responseFieldNames : Array Name)
|
|
| standardViolation (description : String)
|
|
|
|
structure RequestOverview where
|
|
method : String
|
|
direction : MessageDirection
|
|
kinds : Array ProtocolExtensionKind
|
|
parameterType : Type
|
|
responseType : Type
|
|
description : String
|
|
|
|
structure RpcRequestOverview where
|
|
method : Name
|
|
parameterType : Type
|
|
responseType : Type
|
|
description : String
|
|
|
|
structure NotificationOverview where
|
|
method : String
|
|
direction : MessageDirection
|
|
kinds : Array ProtocolExtensionKind
|
|
parameterType : Type
|
|
description : String
|
|
|
|
inductive MessageOverview where
|
|
| request (o : RequestOverview)
|
|
| rpcRequest (o : RpcRequestOverview)
|
|
| notification (o : NotificationOverview)
|
|
|
|
opaque NestedType (outerToInner : Array Type) : Type
|
|
|
|
/--
|
|
Complete overview over the full Lean LSP API.
|
|
|
|
The Lean language server requires all files for which it receives requests and notifications
|
|
to be opened by a `textDocument/didOpen` notification first, i.e. for the language client
|
|
to fully manage the contents of all files.
|
|
It will discard notifications and error requests for closed files.
|
|
This is in violation with LSP, which leaves the possibility open for language servers to receive
|
|
requests for open files, but this violation does not create problems with either VS Code or NeoVim.
|
|
-/
|
|
def protocolOverview : Array MessageOverview := #[
|
|
.notification {
|
|
method := "$/cancelRequest"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := CancelParams
|
|
description := "Emitted in VS Code when a running request is cancelled, e.g. when the document state has changed."
|
|
},
|
|
.request {
|
|
method := "initialize"
|
|
direction := .clientToServer
|
|
kinds := #[
|
|
.standardViolation "The Lean language server currently ignores almost all standard client capabilities and expects clients to be sufficiently fully-featured.",
|
|
.standardViolation "The `InitializeParams.rootUri?` field is not used by the language server - it instead uses the cwd of the language server process.",
|
|
.extendedParameterType #[``InitializeParams.initializationOptions?, ``InitializeParams.capabilities, ``ClientCapabilities.lean?]
|
|
]
|
|
parameterType := InitializeParams
|
|
responseType := InitializeResult
|
|
description := "Emitted when the language server is being initialized. The server is only started once an `initialized` notification is emitted after the `initialize` request."
|
|
},
|
|
.notification {
|
|
method := "initialized"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := InitializedParams
|
|
description := "Emitted after a response to the `initialize` request to start the server."
|
|
},
|
|
.request {
|
|
method := "shutdown"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := Option Empty
|
|
responseType := Option Empty
|
|
description := "Emitted when the language server is being asked to shut down and deliver responses for all pending requests."
|
|
},
|
|
.notification {
|
|
method := "exit"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := Option Empty
|
|
description := "Emitted once the language server should shut down after a `shutdown` request."
|
|
},
|
|
.request {
|
|
method := "client/registerCapability"
|
|
direction := .serverToClient
|
|
kinds := #[.standard]
|
|
parameterType := NestedType #[Option RegistrationParams, DidChangeWatchedFilesRegistrationOptions]
|
|
responseType := Option Empty
|
|
description := "Emitted by the language server after receiving the `initialized` notification to register file watchers for `.lean` and `.ilean` files using the `workspace/didChangeWatchedFiles` registration."
|
|
},
|
|
.notification {
|
|
method := "textDocument/didOpen"
|
|
direction := .clientToServer
|
|
kinds := #[.extendedParameterType #[``LeanDidOpenTextDocumentParams.dependencyBuildMode?]]
|
|
parameterType := LeanDidOpenTextDocumentParams
|
|
description := "Emitted in VS Code when a text document is opened. VS Code may sometimes emit this notification for files that were not opened in an editor."
|
|
},
|
|
.notification {
|
|
method := "textDocument/didClose"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := DidCloseTextDocumentParams
|
|
description := "Emitted in VS Code when a text document is closed. VS Code may sometimes emit this notification for files that were not opened in an editor."
|
|
},
|
|
.notification {
|
|
method := "textDocument/didChange"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := DidChangeTextDocumentParams
|
|
description := "Emitted in VS Code when a text document is edited."
|
|
},
|
|
.notification {
|
|
method := "textDocument/didSave"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := DidSaveTextDocumentParams
|
|
description := "Emitted in VS Code when a text document is saved."
|
|
},
|
|
.notification {
|
|
method := "workspace/didChangeWatchedFiles"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := DidChangeWatchedFilesParams
|
|
description := "Emitted in VS Code when one of the files that the language server registered a file watcher for changes."
|
|
},
|
|
.notification {
|
|
method := "textDocument/publishDiagnostics"
|
|
direction := .serverToClient
|
|
kinds := #[.extendedParameterType #[``PublishDiagnosticsParams.diagnostics, ``DiagnosticWith.fullRange?, ``DiagnosticWith.isSilent?, ``DiagnosticWith.leanTags?]]
|
|
parameterType := PublishDiagnosticsParams
|
|
description := "Emitted by the language server whenever a new set of diagnostics becomes available for a file. Unlike most language servers, the Lean language server emits this notification incrementally while processing the file, not only when the full file has been processed."
|
|
},
|
|
.notification {
|
|
method := "$/lean/fileProgress"
|
|
direction := .serverToClient
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := LeanFileProgressParams
|
|
description := "Emitted by the language server whenever the elaboration progress of a file changes."
|
|
},
|
|
.request {
|
|
method := "textDocument/completion"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := CompletionParams
|
|
responseType := CompletionList
|
|
description := "Emitted in VS Code when auto-completion is triggered, e.g. automatically while typing or after hitting Ctrl+Space."
|
|
},
|
|
.request {
|
|
method := "completionItem/resolve"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := CompletionItem
|
|
responseType := CompletionItem
|
|
description := "Emitted in VS Code when an auto-completion entry is selected."
|
|
},
|
|
.request {
|
|
method := "textDocument/codeAction"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := CodeActionParams
|
|
responseType := Array CodeAction
|
|
description := "Emitted in VS Code when code actions are triggered, e.g. automatically while typing, moving the text cursor or when hovering over a diagnostic."
|
|
},
|
|
.request {
|
|
method := "codeAction/resolve"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := CodeAction
|
|
responseType := CodeAction
|
|
description := "Emitted in VS Code when a code action in the light bulb menu is selected."
|
|
},
|
|
.request {
|
|
method := "textDocument/signatureHelp"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := SignatureHelpParams
|
|
responseType := Option SignatureHelp
|
|
description := "Emitted in VS Code when the signature help is triggered, e.g. automatically while typing or after hitting Ctrl+Shift+Space."
|
|
},
|
|
.request {
|
|
method := "textDocument/hover"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := HoverParams
|
|
responseType := Option Hover
|
|
description := "Emitted in VS Code when hovering over an identifier in the editor."
|
|
},
|
|
.request {
|
|
method := "textDocument/documentHighlight"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := DocumentHighlightParams
|
|
responseType := DocumentHighlightResult
|
|
description := "Emitted in VS Code when the text cursor is on an identifier."
|
|
},
|
|
.request {
|
|
method := "textDocument/documentSymbol"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := DocumentSymbolParams
|
|
responseType := DocumentSymbolResult
|
|
description := "Emitted in VS Code when a file is first opened or when it is changed."
|
|
},
|
|
.request {
|
|
method := "textDocument/foldingRange"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := FoldingRangeParams
|
|
responseType := Array FoldingRange
|
|
description := "Emitted in VS Code when a file is first opened or when it is changed."
|
|
},
|
|
.request {
|
|
method := "textDocument/documentColor"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := DocumentColorParams
|
|
responseType := Array ColorInformation
|
|
description := "Emitted in VS Code when a file is first opened or when it is changed. The language server defines this handler to override the default document color handler of VS Code with an empty one."
|
|
},
|
|
.request {
|
|
method := "textDocument/semanticTokens/range"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := SemanticTokensRangeParams
|
|
responseType := SemanticTokens
|
|
description := "Emitted in VS Code when a file is changed."
|
|
},
|
|
.request {
|
|
method := "textDocument/semanticTokens/full"
|
|
direction := .clientToServer
|
|
kinds := #[.standardViolation "Instead of reporting the full semantic tokens for the full file as specified by LSP, the Lean language server will only report the semantic tokens for the part of the file that has been processed so far. If the response is incomplete, the language server periodically emits `workspace/semanticTokens/refresh` to request another `textDocument/semanticTokens/full` request from the client. This process is repeated until the file has been fully processed and all semantic tokens have been reported. We use this trick to stream semantic tokens to VS Code, despite the fact that VS Code does not support result streaming."]
|
|
parameterType := SemanticTokensParams
|
|
responseType := SemanticTokens
|
|
description := "Emitted in VS Code when a file is first opened, when it is changed or when VS Code receives a `workspace/semanticTokens/refresh` request from the server."
|
|
},
|
|
.request {
|
|
method := "workspace/semanticTokens/refresh"
|
|
direction := .serverToClient
|
|
kinds := #[.standard]
|
|
parameterType := Option Empty
|
|
responseType := Option Empty
|
|
description := "Emitted by the language server to request another `textDocument/semanticTokens/full` request from the client."
|
|
},
|
|
.request {
|
|
method := "textDocument/inlayHint"
|
|
direction := .clientToServer
|
|
kinds := #[.standardViolation "Instead of reporting the full inlay hints for the full file as specified by LSP, the Lean language server will only report the inlay hints for the part of the file that has been processed so far. If the response is incomplete, the language server periodically emits `workspace/inlayHint/refresh` to request another `textDocument/inlayHint` request from the client. This process is repeated until the file has been fully processed and all inlay hints have been reported. We use this trick to stream inlay hints to VS Code, despite the fact that VS Code does not support result streaming."]
|
|
parameterType := InlayHintParams
|
|
responseType := Array InlayHint
|
|
description := "Emitted in VS Code when a file is first opened, when it is changed or when VS Code receives a `workspace/inlayHint/refresh` request from the server."
|
|
},
|
|
.request {
|
|
method := "workspace/inlayHint/refresh"
|
|
direction := .serverToClient
|
|
kinds := #[.standard]
|
|
parameterType := Option Empty
|
|
responseType := Option Empty
|
|
description := "Emitted by the language server to request another `textDocument/inlayHint` request from the client."
|
|
},
|
|
.request {
|
|
method := "textDocument/definition"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := DefinitionParams
|
|
responseType := Array LocationLink
|
|
description := "Emitted in VS Code when clicking 'Go to Definition' in the context menu or using Ctrl+Click."
|
|
},
|
|
.request {
|
|
method := "textDocument/declaration"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := DefinitionParams
|
|
responseType := Array LocationLink
|
|
description := "Emitted in VS Code when clicking 'Go to Declaration' in the context menu."
|
|
},
|
|
.request {
|
|
method := "textDocument/typeDefinition"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := DefinitionParams
|
|
responseType := Array LocationLink
|
|
description := "Emitted in VS Code when clicking 'Go to Type Definition' in the context menu."
|
|
},
|
|
.request {
|
|
method := "textDocument/references"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := ReferenceParams
|
|
responseType := Array Location
|
|
description := "Emitted in VS Code when clicking 'Find All References' or 'Go to References' in the context menu."
|
|
},
|
|
.request {
|
|
method := "textDocument/prepareCallHierarchy"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := CallHierarchyPrepareParams
|
|
responseType := Array CallHierarchyItem
|
|
description := "Emitted in VS Code when clicking 'Show Call Hierarchy' in the context menu."
|
|
},
|
|
.request {
|
|
method := "callHierarchy/incomingCalls"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := CallHierarchyIncomingCallsParams
|
|
responseType := Array CallHierarchyIncomingCall
|
|
description := "Emitted in VS Code when expanding a node in the call hierarchy in 'incoming calls' mode."
|
|
},
|
|
.request {
|
|
method := "callHierarchy/outgoingCalls"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := CallHierarchyOutgoingCallsParams
|
|
responseType := Array CallHierarchyOutgoingCall
|
|
description := "Emitted in VS Code when expanding a node in the call hierarchy in 'outgoing calls' mode."
|
|
},
|
|
.request {
|
|
method := "$/lean/prepareModuleHierarchy"
|
|
direction := .clientToServer
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := LeanPrepareModuleHierarchyParams
|
|
responseType := Option LeanModule
|
|
description := "Emitted in VS Code when clicking 'Show Module Hierarchy' or 'Show Inverse Module Hierarchy' in the context menu."
|
|
},
|
|
.request {
|
|
method := "$/lean/moduleHierarchy/imports"
|
|
direction := .clientToServer
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := LeanModuleHierarchyImportsParams
|
|
responseType := Array LeanImport
|
|
description := "Emitted in VS Code when expanding a node in the module hierarchy."
|
|
},
|
|
.request {
|
|
method := "$/lean/moduleHierarchy/importedBy"
|
|
direction := .clientToServer
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := LeanModuleHierarchyImportedByParams
|
|
responseType := Array LeanImport
|
|
description := "Emitted in VS Code when expanding a node in the inverse module hierarchy."
|
|
},
|
|
.request {
|
|
method := "textDocument/prepareRename"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := PrepareRenameParams
|
|
responseType := Option Range
|
|
description := "Emitted in VS Code when clicking 'Rename Symbol' in the context menu."
|
|
},
|
|
.request {
|
|
method := "textDocument/rename"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := RenameParams
|
|
responseType := WorkspaceEdit
|
|
description := "Emitted in VS Code when entering an identifier after clicking 'Rename Symbol' in the context menu."
|
|
},
|
|
.request {
|
|
method := "workspace/symbol"
|
|
direction := .clientToServer
|
|
kinds := #[.standard]
|
|
parameterType := WorkspaceSymbolParams
|
|
responseType := Array SymbolInformation
|
|
description := "Emitted in VS Code when opening the command prompt and entering a `#` prefix with a query after it."
|
|
},
|
|
.request {
|
|
method := "$/lean/plainGoal"
|
|
direction := .clientToServer
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := PlainGoalParams
|
|
responseType := Option PlainGoal
|
|
description := "Not used in VS Code. Emitted in editors that do not support an interactive InfoView (e.g. Emacs) and interactive tests."
|
|
},
|
|
.request {
|
|
method := "$/lean/plainTermGoal"
|
|
direction := .clientToServer
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := PlainTermGoalParams
|
|
responseType := Option PlainTermGoal
|
|
description := "Not used in VS Code. Emitted in editors that do not support an interactive InfoView (e.g. Emacs) and interactive tests."
|
|
},
|
|
.request {
|
|
method := "textDocument/waitForDiagnostics"
|
|
direction := .clientToServer
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := WaitForDiagnosticsParams
|
|
responseType := WaitForDiagnostics
|
|
description := "Not used in the editor. Emitted in interactive tests to wait for all diagnostics up to a given point."
|
|
},
|
|
.request {
|
|
method := "$/lean/waitForILeans"
|
|
direction := .clientToServer
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := WaitForILeansParams
|
|
responseType := WaitForILeans
|
|
description := "Not used in the editor. Emitted in interactive tests to wait for all .ileans in the project and the .ilean of the given file to be loaded."
|
|
},
|
|
.request {
|
|
method := "$/lean/rpc/connect"
|
|
direction := .clientToServer
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := RpcConnectParams
|
|
responseType := RpcConnected
|
|
description := "Emitted in VS Code when an RPC session for InfoView interactivity is initially set up."
|
|
},
|
|
.notification {
|
|
method := "$/lean/rpc/release"
|
|
direction := .clientToServer
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := RpcReleaseParams
|
|
description := "Emitted in VS Code when an RPC object in the server (the lifecycle of which is managed by the client) is freed by the client."
|
|
},
|
|
.notification {
|
|
method := "$/lean/rpc/keepAlive"
|
|
direction := .clientToServer
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := RpcKeepAliveParams
|
|
description := "Emitted periodically in VS Code to signal that the RPC client has not disconnected yet to keep the RPC session alive."
|
|
},
|
|
.request {
|
|
method := "$/lean/rpc/call"
|
|
direction := .clientToServer
|
|
kinds := #[.leanSpecificMethod]
|
|
parameterType := RpcCallParams
|
|
responseType := Json
|
|
description := "Emitted in VS Code when an RPC method is called. `RpcCallParams.method` and `RpcCallParams.params` can be any of the builtin `.rpcRequest`s described in this overview or any custom RPC methods tagged with `@[server_rpc_method]` that can be set up for use in the widget system."
|
|
},
|
|
.rpcRequest {
|
|
method := `Lean.Widget.getInteractiveDiagnostics
|
|
parameterType := GetInteractiveDiagnosticsParams
|
|
responseType := Array InteractiveDiagnostic
|
|
description := "Emitted in VS Code when the text cursor is moved, the set of diagnostics at the cursor position changes or the file starts or finishes processing."
|
|
},
|
|
.rpcRequest {
|
|
method := `Lean.Widget.getInteractiveGoals
|
|
parameterType := Lsp.PlainGoalParams
|
|
responseType := Option InteractiveGoals
|
|
description := "Emitted in VS Code when the text cursor is moved, the set of diagnostics at the cursor position changes or the file starts or finishes processing."
|
|
},
|
|
.rpcRequest {
|
|
method := `Lean.Widget.getInteractiveTermGoal
|
|
parameterType := Lsp.PlainTermGoalParams
|
|
responseType := Option InteractiveTermGoal
|
|
description := "Emitted in VS Code when the text cursor is moved, the set of diagnostics at the cursor position changes or the file starts or finishes processing."
|
|
},
|
|
.rpcRequest {
|
|
method := `Lean.Widget.getWidgets
|
|
parameterType := Position
|
|
responseType := GetWidgetsResponse
|
|
description := "Emitted in VS Code when the text cursor is moved, the set of diagnostics at the cursor position changes or the file starts or finishes processing."
|
|
},
|
|
.rpcRequest {
|
|
method := `Lean.Widget.InteractiveDiagnostics.infoToInteractive
|
|
parameterType := WithRpcRef Elab.InfoWithCtx
|
|
responseType := InfoPopup
|
|
description := "Emitted in VS Code when hovering over terms in the InfoView."
|
|
},
|
|
.rpcRequest {
|
|
method := `Lean.Widget.getGoToLocation
|
|
parameterType := GetGoToLocationParams
|
|
responseType := Array Lsp.LocationLink
|
|
description := "Emitted in VS Code when clicking 'Go to Definition' in the context menu of the InfoView or using Ctrl+Click in the InfoView."
|
|
},
|
|
.rpcRequest {
|
|
method := `Lean.Widget.lazyTraceChildrenToInteractive
|
|
parameterType := WithRpcRef LazyTraceChildren
|
|
responseType := Array InteractiveMessage
|
|
description := "Emitted in VS Code when unfolding a lazy trace message in the InfoView."
|
|
},
|
|
.rpcRequest {
|
|
method := `Lean.Widget.highlightMatches
|
|
parameterType := HighlightMatchesParams
|
|
responseType := HighlightedInteractiveMessage
|
|
description := "Emitted in VS Code when using the trace search in the InfoView."
|
|
},
|
|
.rpcRequest {
|
|
method := `Lean.Widget.getWidgetSource
|
|
parameterType := GetWidgetSourceParams
|
|
responseType := WidgetSource
|
|
description := "Emitted in VS Code when a widget is imported from another widget."
|
|
},
|
|
.rpcRequest {
|
|
method := `Lean.Widget.InteractiveDiagnostics.msgToInteractive
|
|
parameterType := MsgToInteractive
|
|
responseType := InteractiveMessage
|
|
description := "Emitted in VS Code in some widgets to convert non-interactive messages to interactive ones."
|
|
},
|
|
]
|