haskell-lsp

The lsp library is a framework designed for building Language Server Protocol (LSP) servers. It abstracts the complexities of the protocol by providing built-in support for:

• JSON-RPC Transport: Handling the underlying communication layer.
• Virtual File System (VFS): Managing and tracking document state in memory.
• Request/Notification Handling: Responding to LSP requests and notifications via registered handlers.
• Capability Management: Automatically setting server capabilities in the initialize request based on registered handlers, as well as supporting dynamic registration of capabilities.
• Lifecycle & Progress: Managing cancellable requests and progress notifications.
• Diagnostics: Handling the publishing and flushing of diagnostic information.

It is part of a larger ecosystem including lsp-types (for protocol types) and lsp-test (for testing servers).

The lsp-test package provides a framework for functional testing of LSP servers. You can run sessions, perform actions like opening documents, and assert on server responses.

Setting up a session

Use runSession to initialize a session with a server name, capabilities, and a project directory.

Unit tests with HSpec

You can integrate lsp-test with HSpec to write assertions about diagnostics, symbols, or other LSP features.

Replaying captured sessions

If you have a captured session, you can replay it using replaySession.

Parsing with combinators

lsp-test provides combinators to skip or count specific notifications, requests, or responses during a session.

Debugging tests

To see server logs and standard error during testing, set the following environment variables:

• LSP_TEST_LOG_MESSAGES=1
• LSP_TEST_LOG_STDERR=1

-- Setting up a session
import Language.LSP.Test
main = runSession "hie" fullCaps "proj/dir" $ do
  doc <- openDoc "Foo.hs" "haskell"
  skipMany anyNotification
  symbols <- getDocumentSymbols doc

-- Unit tests with HSpec
describe "diagnostics" $
  it "report errors" $ runSession "hie" fullCaps "test/data" $ do
    openDoc "Error.hs" "haskell"
    [diag] <- waitForDiagnosticsSource "ghcmod"
    liftIO $ do
      diag ^. severity `shouldBe` Just DsError
      diag ^. source `shouldBe` Just "ghcmod"

-- Replaying captured session
replaySession "hie" "test/data/renamePass"

-- Parsing with combinators
skipManyTill loggingNotification publishDiagnosticsNotification
count 4 (message :: Session ApplyWorkspaceEditRequest)
anyRequest <|> anyResponse

To build a language server, you define a set of Handlers for notifications and requests, then use runServer with a ServerDefinition.

Key components of ServerDefinition include:

• staticHandlers: A function that returns your handlers based on server capabilities.
• doInitialize: A function to handle the initialization request and return the environment.
• interpretHandler: Defines how to run your handler monad (e.g., using runLspT).
• parseConfig: Logic to parse server configuration.

Example of a minimal server implementing SMethod_Initialized and SMethod_TextDocumentHover:

{-# LANGUAGE DuplicateRecordFields #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE OverloadedStrings #-}

import Control.Monad.IO.Class
import Data.Text qualified as T
import Language.LSP.Protocol.Message
import Language.LSP.Protocol.Types
import Language.LSP.Server

handlers :: Handlers (LspM ())
handlers =
  mconcat
    [ notificationHandler SMethod_Initialized $ \_not -> do
        let params =
              ShowMessageRequestParams
                MessageType_Info
                "Turn on code lenses?"
                (Just [MessageActionItem "Turn on", MessageActionItem "Don't"])
        _ <- sendRequest SMethod_WindowShowMessageRequest params $ \case
          Right (InL (MessageActionItem "Turn on")) -> do
            let regOpts = CodeLensRegistrationOptions (InR Null) Nothing (Just False)

            _ <- registerCapability mempty SMethod_TextDocumentCodeLens regOpts $ \_req responder -> do
              let cmd = Command "Say hello" "lsp-hello-command" Nothing
                  rsp = [CodeLens (mkRange 0 0 0 100) (Just cmd) Nothing]
              responder $ Right $ InL rsp
            pure ()
          Right _ ->
            sendNotification SMethod_WindowShowMessage (ShowMessageParams MessageType_Info "Not turning on code lenses")
          Left err ->
            sendNotification SMethod_WindowShowMessage (ShowMessageParams MessageType_Error $ "Something went wrong!\n" <> T.pack (show err))
        pure ()
    , requestHandler SMethod_TextDocumentHover $ \req responder -> do
        let TRequestMessage _ _ _ (HoverParams _doc pos _workDone) = req
            Position _l _c' = pos
            rsp = Hover (InL ms) (Just range)
            ms = mkMarkdown "Hello world"
            range = Range pos pos
        responder (Right $ InL rsp)
    ]

main :: IO Int
main =
  runServer $
    ServerDefinition
      { parseConfig = const $ const $ Right ()
      , onConfigChange = const $ pure ()
      , defaultConfig = ()
      , configSection = "demo"
      , doInitialize = \env _req -> pure $ Right env
      , staticHandlers = \_caps -> handlers
      , interpretHandler = \env -> Iso (runLspT env) liftIO
      , options = defaultOptions
      }