Compile plugin-tutorial using markdown-unlit

Makes sure the plugin-tutorial can never be out-of-date again.

Author: fendor

docs/contributing/plugin-tutorial.lhs

@@ -0,0 +1 @@
+plugin-tutorial.md

docs/contributing/plugin-tutorial.md

@@ -1,4 +1,5 @@
 # Let’s write a Haskell Language Server plugin
+
 Originally written by Pepe Iborra, maintained by the Haskell community.
 
 Haskell Language Server (HLS) is a Language Server Protocol (LSP) server for the Haskell programming language. It builds on several previous efforts to create a Haskell IDE.
@@ -22,6 +23,49 @@ While writing them, I didn't have to worry about performance, UI, or distributio
 
 The plugins also make these tools much more accessible to all users of HLS.
 
+## Preamble
+
+```haskell
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE DerivingStrategies #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE RecordWildCards #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE ViewPatterns #-}
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DeriveAnyClass #-}
+
+import Ide.Types
+import Ide.Logger
+import Ide.Plugin.Error
+
+import Development.IDE.Core.RuleTypes
+import Development.IDE.Core.Service hiding (Log)
+import Development.IDE.Core.Shake hiding (Log)
+import Development.IDE.GHC.Compat
+import Development.IDE.GHC.Compat.Core
+import Development.IDE.GHC.Error
+import Development.IDE.Types.HscEnvEq
+import Development.IDE.Core.PluginUtils
+
+import qualified Language.LSP.Server as LSP
+import Language.LSP.Protocol.Types as JL
+import Language.LSP.Protocol.Message
+
+import Data.Aeson as Aeson
+import Data.Map (Map)
+import Data.IORef
+import Data.Maybe (fromMaybe, catMaybes)
+import qualified Data.Map as Map
+import qualified Data.HashMap.Strict as HashMap
+import qualified Data.Text as T
+import Control.Monad (forM)
+import Control.Monad.IO.Class (liftIO)
+import Control.Monad.Trans.Class
+import GHC.Generics (Generic)
+```
+
 ## Plugins in the HLS codebase
 
 The HLS codebase includes several plugins (found in `./plugins`). For example:
@@ -37,7 +81,9 @@ I recommend looking at the existing plugins for inspiration and reference. A few
 - Folders containing the plugin follow the `hls-pluginname-plugin` naming convention
 - Plugins are "linked" in `src/HlsPlugins.hs#idePlugins`. New plugin descriptors
   must be added there.
-  ```haskell -- src/HlsPlugins.hs
+
+  ```haskell ignore
+  -- Defined in src/HlsPlugins.**hs**
 
   idePlugins = pluginDescToIdePlugins allPlugins
     where
@@ -53,6 +99,7 @@ I recommend looking at the existing plugins for inspiration and reference. A few
         , NewPlugin.descriptor "new-plugin" -- Add new plugins here.
         ]
   ```
+
 To add a new plugin, extend the list of `allPlugins` and rebuild.
 
 ## The goal of the plugin we will write
@@ -80,7 +127,7 @@ Once the build is done, you can find the location of the HLS binary with `cabal
 This way you can simply test your changes by reloading your editor after rebuilding the binary.
 
 > **Note:** In VSCode, edit the "Haskell Server Executable Path" setting.
-
+>
 > **Note:** In Emacs, edit the `lsp-haskell-server-path` variable.
 
 ![Settings](settings-vscode.png)
@@ -90,6 +137,7 @@ This way you can simply test your changes by reloading your editor after rebuild
 ## Digression about the Language Server Protocol
 
 There are two main types of communication in the Language Server Protocol:
+
 - A **request-response interaction** type where one party sends a message that requires a response from the other party.
 - A **notification** is a one-way interaction where one party sends a message without expecting any response.
 
@@ -98,24 +146,27 @@ There are two main types of communication in the Language Server Protocol:
 ## Anatomy of a plugin
 
 HLS plugins are values of the `PluginDescriptor` datatype, which is defined in `hls-plugin-api/src/Ide/Types.hs` as:
-```haskell
+
+```haskell ignore
 data PluginDescriptor (ideState :: Type) =
   PluginDescriptor { pluginId                   :: !PluginId
                    , pluginCommands             :: ![PluginCommand ideState]
                    , pluginHandlers             :: PluginHandlers ideState
                    , pluginNotificationHandlers :: PluginNotificationHandlers ideState
-                   , [...] -- Other fields omitted for brevity.
+--                 , [...] -- Other fields omitted for brevity.
                    }
 ```
 
 ### Request-response interaction
 
 The `pluginHandlers` handle LSP client requests and provide responses to the client. They must fulfill these requests as quickly as possible.
+
 - Example: When you want to format a file, the client sends the [`textDocument/formatting`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_formatting) request to the server. The server formats the file and responds with the formatted content.
 
 ### Notification
 
 The `pluginNotificationHandlers` handle notifications sent by the client to the server that are not explicitly triggered by a user.
+
 - Example: Whenever you modify a Haskell file, the client sends a notification informing HLS about the changes to the file.
 
 The `pluginCommands` are special types of user-initiated notifications sent to
@@ -124,6 +175,7 @@ the server. These actions can be long-running and involve multiple modules.
 ## The explicit imports plugin
 
 To achieve our plugin goals, we need to define:
+
 - a command handler (`importLensCommand`),
 - a code lens request handler (`lensProvider`).
 
@@ -134,13 +186,15 @@ Using the convenience `defaultPluginDescriptor` function, we can bootstrap the p
 ```haskell
 -- plugins/hls-explicit-imports-plugin/src/Ide/Plugin/ExplicitImports.hs
 
+data Log
+
 -- | The "main" function of a plugin.
 descriptor :: Recorder (WithPriority Log) -> PluginId -> PluginDescriptor IdeState
 descriptor recorder plId =
-  (defaultPluginDescriptor plId)
+  (defaultPluginDescriptor plId "A plugin for generating the minimal imports")
     { pluginCommands = [importLensCommand], -- The plugin provides a command handler
       pluginHandlers = mconcat -- The plugin provides request handlers
-        [ lensProvider
+        [  mkPluginHandler SMethod_TextDocumentCodeLens provider
         ]
     }
 ```
@@ -150,14 +204,15 @@ We'll start with the command, since it's the simplest of the two.
 ### The command handler
 
 In short, LSP commands work like this:
+
 - The LSP server (HLS) initially sends a command descriptor to the client, in this case as part of a code lens.
 - When the user clicks on the code lens, the client asks HLS to execute the command with the given descriptor. The server then handles and executes the command; this latter part is implemented by the `commandFunc` field of our `PluginCommand` value.
 
 > **Note**: Check the [LSP spec](https://microsoft.github.io/language-server-protocol/specification) for a deeper understanding of how commands work.
 
 The command handler will be called `importLensCommand` and have the `PluginCommand` type, a type defined in `Ide.Types` as:
 
-```haskell
+```haskell ignore
 -- hls-plugin-api/src/Ide/Types.hs
 
 data PluginCommand ideState = forall a. (FromJSON a) =>
@@ -174,18 +229,23 @@ Let's start by creating an unfinished command handler. We'll give it an ID and a
 importLensCommand :: PluginCommand IdeState
 importLensCommand =
   PluginCommand
-    { commandId = "ImportLensCommand"
+    { commandId = importCommandId
     , commandDesc = "Explicit import command"
     , commandFunc = runImportCommand
     }
 
+importCommandId :: CommandId
+importCommandId = "ImportLensCommand"
+```
+
+```haskell ignore
 -- | Not implemented yet.
 runImportCommand = undefined
 ```
 
 The most important (and still `undefined`) field is `commandFunc :: CommandFunction`, a type synonym from `LSP.Types`:
 
-```haskell
+```haskell ignore
 -- hls-plugin-api/src/Ide/Types.hs
 
 type CommandFunction ideState a
@@ -194,8 +254,7 @@ type CommandFunction ideState a
   -> LspM Config (Either ResponseError Value)
 ```
 
-
-`CommandFunction` takes an `ideState` and a JSON-encodable argument. `LspM` is a monad transformer with access to IO, and having access to a language context environment `Config`. The action evaluates to an `Either` value. `Left` indicates failure with a `ResponseError`, `Right` indicates success with a `Value`.
+`CommandFunction` takes an `ideState` and a JSON-encodable argument. `LspM` is a monad transformer with access to IO, and having access to a language context environment `Config`. The action evaluates to an `Either` value. `Left` indicates failure with a `ResponseError`, `Right` indicates sucess with a `Value`.
 
 Our handler will ignore the state argument and only use the `WorkspaceEdit` argument.
 
@@ -207,10 +266,10 @@ newtype ImportCommandParams = ImportCommandParams WorkspaceEdit
 
 -- | The actual command handler
 runImportCommand :: CommandFunction IdeState ImportCommandParams
-runImportCommand _ (ImportCommandParams edit) = do
+runImportCommand _ _ (ImportCommandParams edit) = do
   -- This command simply triggers a workspace edit!
-  _ <- sendRequest SWorkspaceApplyEdit (ApplyWorkspaceEditParams Nothing edit) (\_ -> pure ())
-  return (Right Null)
+  _ <- lift $ pluginSendRequest SMethod_WorkspaceApplyEdit (ApplyWorkspaceEditParams Nothing edit) (\_ -> pure ())
+  return $ InR JL.Null
 ```
 
 `runImportCommand` [sends a request](https://hackage.haskell.org/package/lsp/docs/Language-LSP-Server.html#v:sendRequest) to the client using the method `SWorkspaceApplyEdit` and the parameters `ApplyWorkspaceEditParams Nothing edit`, providing a response handler that does nothing. It then returns `Right Null`, which is an empty `Aeson.Value` wrapped in `Right`.
@@ -219,42 +278,41 @@ runImportCommand _ (ImportCommandParams edit) = do
 
 The code lens provider implements all the steps of the algorithm described earlier:
 
->  1. Request the type checking artifacts.
->  2. Extract the actual import lists from the type-checked AST.
->  3. Ask GHC to produce the minimal import lists for this AST.
->  4. For each import statement lacking an explicit list, determine its minimal import list and generate a code lens displaying this list along with a command to insert it.
+> 1. Request the type checking artifacts.
+> 2. Extract the actual import lists from the type-checked AST.
+> 3. Ask GHC to produce the minimal import lists for this AST.
+> 4. For each import statement lacking an explicit list, determine its minimal import list and generate a code lens displaying this list along with a command to insert it.
 
 The provider takes the usual `LspFuncs` and `IdeState` arguments, as well as a `CodeLensParams` value containing a file URI. It returns an IO action that produces either an error or a list of code lenses for that file.
 
 ```haskell
-provider :: CodeLensProvider
-provider _lspFuncs          -- LSP functions, not used
-         state              -- ghcide state, used to retrieve typechecking artifacts
+provider :: PluginMethodHandler IdeState Method_TextDocumentCodeLens
+provider state              -- ghcide state, used to retrieve typechecking artifacts
          pId                -- Plugin ID
-         CodeLensParams{_textDocument = TextDocumentIdentifier{_uri}}
+         CodeLensParams{_textDocument = TextDocumentIdentifier{_uri}} = do
   -- VSCode uses URIs instead of file paths
   -- haskell-lsp provides conversion functions
-  | Just nfp <- uriToNormalizedFilePath $ toNormalizedUri _uri
-  = do
-    -- Get the typechecking artifacts from the module
-    tmr <- runAction "importLens" state $ use TypeCheck nfp
-    -- We also need a GHC session with all the dependencies
-    hsc <- runAction "importLens" state $ use GhcSessionDeps nfp
-    -- Use the GHC API to extract the "minimal" imports
-    (imports, mbMinImports) <- extractMinimalImports hsc tmr
-
-    case mbMinImports of
-        Just minImports -> do
-            let minImportsMap =
-                    Map.fromList [ (srcSpanStart l, i) | L l i <- minImports ]
-            lenses <- forM imports $
-              -- for every import, maybe generate a code lens
-              generateLens pId _uri minImportsMap
-            return $ Right (List $ catMaybes lenses)
-        _ ->
-            return $ Right (List [])
-  | otherwise
-  = return $ Right (List [])
+  nfp <- getNormalizedFilePathE _uri
+  -- Get the typechecking artifacts from the module
+  tmr <- runActionE "importLens" state $ useE TypeCheck nfp
+  -- We also need a GHC session with all the dependencies
+  hsc <- runActionE "importLens" state $ useE GhcSessionDeps nfp
+  -- Use the GHC API to extract the "minimal" imports
+  (imports, mbMinImports) <- liftIO $ extractMinimalImports hsc tmr
+
+  case mbMinImports of
+      Just minImports -> do
+          let minImportsMap =
+                Map.fromList [ (realSrcLocToPosition loc, i)
+                             | L l i <- minImports
+                             , let RealSrcLoc loc _ = srcSpanStart (locA l)
+                             ]
+          lenses <- forM imports $ \imp ->
+            -- for every import, maybe generate a code lens
+            liftIO (generateLens pId _uri minImportsMap imp)
+          return $ InL (catMaybes lenses)
+      _ ->
+          return $ InL []
 ```
 
 Note the simplicity of retrieving the type checking artifacts for the module, as well as a fully set up GHC session, via the `ghcide` rules.
@@ -265,14 +323,14 @@ The details of the GHC API are not relevant to this tutorial, but the code is te
 
 ```haskell
 extractMinimalImports
-  :: Maybe HscEnvEq
-  -> Maybe TcModuleResult
+  :: HscEnvEq
+  -> TcModuleResult
   -> IO ([LImportDecl GhcRn], Maybe [LImportDecl GhcRn])
-extractMinimalImports (Just hsc)) (Just (tmrModule -> TypecheckedModule{..})) = do
+extractMinimalImports hsc TcModuleResult{..} = do
     -- Extract the original imports and the typechecking environment
-    let (tcEnv,_) = tm_internals_
-        Just (_, imports, _, _) = tm_renamed_source
-        ParsedModule{ pm_parsed_source = L loc _} = tm_parsed_module
+    let tcEnv = tmrTypechecked
+        (_, imports, _, _) = tmrRenamed
+        ParsedModule{ pm_parsed_source = L loc _} = tmrParsed
         span = fromMaybe (error "expected real") $ realSpan loc
 
     -- GHC is secretly full of mutable state
@@ -283,7 +341,6 @@ extractMinimalImports (Just hsc)) (Just (tmrModule -> TypecheckedModule{..})) =
     -- getMinimalImports computes the minimal explicit import lists
       initTcWithGbl (hscEnv hsc) tcEnv span $ getMinimalImports usage
     return (imports, minimalImports)
-extractMinimalImports _ _ = return ([], Nothing)
 ```
 
 The function `generateLens` implements step 4 of the algorithm, producing a code lens for an import statement that lacks an import list. The code lens includes an `ImportCommandParams` value containing a workspace edit that rewrites the import statement, as our command provider expects.
@@ -292,34 +349,36 @@ The function `generateLens` implements step 4 of the algorithm, producing a code
 -- | Given an import declaration, generate a code lens unless it has an explicit import list
 generateLens :: PluginId
              -> Uri
-             -> Map SrcLoc (ImportDecl GhcRn)
+             -> Map Position (ImportDecl GhcRn)
              -> LImportDecl GhcRn
              -> IO (Maybe CodeLens)
 generateLens pId uri minImports (L src imp)
   -- Explicit import list case
-  | ImportDecl{ideclHiding = Just (False,_)} <- imp
+  | ImportDecl{ideclImportList = Just _} <- imp
   = return Nothing
   -- No explicit import list
-  | RealSrcSpan l <- src
-  , Just explicit <- Map.lookup (srcSpanStart src) minImports
+  | RealSrcSpan l _ <- locA src
+  , let position = realSrcLocToPosition $ realSrcSpanStart l
+  , Just explicit <- Map.lookup position minImports
   , L _ mn <- ideclName imp
   -- (Almost) no one wants to see an explicit import list for Prelude
   , mn /= moduleName pRELUDE
   = do
         -- The title of the command is just the minimal explicit import decl
-    let title = T.pack $ prettyPrint explicit
+    let title = T.pack $ printWithoutUniques explicit
         -- The range of the code lens is the span of the original import decl
         _range :: Range = realSrcSpanToRange l
         -- The code lens has no extra data
         _xdata = Nothing
         -- An edit that replaces the whole declaration with the explicit one
-        edit = WorkspaceEdit (Just editsMap) Nothing
-        editsMap = HashMap.fromList [(uri, List [importEdit])]
+        edit = WorkspaceEdit (Just editsMap) Nothing Nothing
+        editsMap = Map.fromList [(uri, [importEdit])]
         importEdit = TextEdit _range title
         -- The command argument is simply the edit
         _arguments = Just [toJSON $ ImportCommandParams edit]
-    -- Create the command
-    _command <- Just <$> mkLspCommand pId importCommandId title _arguments
+        _data_ = Nothing
+        -- Create the command
+        _command = Just $ mkLspCommand pId importCommandId title _arguments
     -- Create and return the code lens
     return $ Just CodeLens{..}
   | otherwise
@@ -333,6 +392,7 @@ There's only one Haskell code change left to do at this point: "link" the plugin
 Integrating the plugin into HLS itself requires changes to several configuration files.
 
 A good approach is to search for the ID of an existing plugin (e.g., `hls-class-plugin`):
+
 - `./cabal*.project` and `./stack*.yaml`: Add the plugin package to the `packages` field.
 - `./haskell-language-server.cabal`: Add a conditional block with the plugin package dependency.
 - `./.github/workflows/test.yml`: Add a block to run the plugin's test suite.
@@ -342,3 +402,8 @@ A good approach is to search for the ID of an existing plugin (e.g., `hls-class-
 The full code used in this tutorial, including imports, is available in [this Gist](https://gist.github.com/pepeiborra/49b872b2e9ad112f61a3220cdb7db967) and in this [branch](https://github.com/pepeiborra/ide/blob/imports-lens/src/Ide/Plugin/ImportLens.hs).
 
 I hope this has given you a taste of how easy and joyful it is to write plugins for HLS. If you are looking for contribution ideas, here are some good ones listed in the HLS [issue tracker](https://github.com/haskell/haskell-language-server/issues).
+
+```haskell
+main :: IO ()
+main = putStrLn "Just here to silence the error!"
+```

ghcide/src/Development/IDE/GHC/Compat/Core.hs

@@ -225,6 +225,7 @@ module Development.IDE.GHC.Compat.Core (
     SrcLoc.noSrcSpan,
     SrcLoc.noSrcLoc,
     SrcLoc.noLoc,
+    SrcLoc.srcSpanToRealSrcSpan,
     mapLoc,
     -- * Finder
     FindResult(..),