Recover the LSP analysis context after a workspace build

Why:
    Projects opened before their first build lack generated metadata.
    Recover on compiler-log events without requiring an editor restart.

Context modified (compiler-log creation and change notifications):
Before (text):
    Refresh diagnostics using the existing analysis and package context.
After (text):
    Discover fresh analysis tables and package configuration.
    Replace the context if the workspace package is available.
    Otherwise retain the previous context without repeated error messages.
    Preserve open buffers, settings and diagnostics, then refresh diagnostics.

Diagnostic modified (initial package discovery failure):
Before (text):
    Try building the project then restart the server
After (text):
    Try building the project. The server will retry when a compiler log
    changes.

Add snapshot tests for Created and Changed events, early retries,
compiled-file lookup and preservation of unsaved buffers. Document the
automatic recovery behavior.

Validation:
    dune build and eight recovery/diagnostic tests pass. The full LSP
    suite still has snapshot differences in hover_jsx.ml and code_action.ml.
Signed-off-by: Pedro Castro <aspeddro@gmail.com>

Author: aspeddro

lsp/lsp.md

@@ -114,6 +114,11 @@ notifications. Some are out of scope because they don't make sense.
       generated with `build_root` field for each subpackage.
   - [x] Add the warning number to the diagnostic message.
 - [x] `workspace/didChangeWatchedFiles` - client notification
+  - When a `.compiler.log` is created or changed, the server rediscovers packages
+    and refreshes its analysis context and compiler configuration. A workspace
+    opened before its first build can recover without restarting the server.
+    Failed discovery leaves the previous context intact; open buffers, settings
+    and diagnostic ownership are preserved.
   - The server uses this notification to detect changes to generated
     `.compiler.log` files, which usually means a ReScript build has finished.
     When a watched log changes, the server re-reads every known compiler log and

lsp/src/rescript_language_server.ml

@@ -128,30 +128,22 @@ let publish_diagnostics ?(force_publish_uris = []) (state : State.t) diagnostics
    function unsafe in the usual functional sense: callers must provide a fresh
    per-server analysis state or accept that repeated calls append/overwrite
    package roots as a side effect. *)
-let discover_subpackages_and_populate ~workspace_root
+let discover_subpackages_and_populate ~notify_errors ~workspace_root
     ~(analysis_state : Analysis.Shared_types.state) ~server =
   let root_package =
     let root_path = workspace_root |> Uri.to_path in
     match Analysis.Packages.new_bs_package ~root_path with
     | Some p -> Some p
     | None ->
-      (* TODO: Decide how the server should recover when the workspace has not
-         been built yet, for example right after cloning a repository. Package
-         discovery depends on generated build metadata, so most analysis
-         features cannot work until that metadata exists.
-         Options to evaluate:
-         - Keep the server running and show a window message. In this case user should restart the server after build.
-         - Stop the server after explaining that a build is required.
-         - Re-initialize `analysis_state` after DidChangeWatchedFiles reports a
-           new `.compiler.log` change.
-         *)
       let message =
         Printf.sprintf
           "Failed to initialize the context for the project at %s. Try \
-           building the project then restart the server"
+           building the project. The server will retry when a compiler log \
+           changes."
           root_path
       in
-      Server.show_message_notification ~kind:MessageType.Error message server;
+      if notify_errors then
+        Server.show_message_notification ~kind:MessageType.Error message server;
       None
   in
 
@@ -171,7 +163,7 @@ let discover_subpackages_and_populate ~workspace_root
             | exception Failure err -> Either.Right err)
           dependencies
       in
-      if List.length deps_errors > 0 then
+      if notify_errors && List.length deps_errors > 0 then
         Server.show_message_notification ~kind:MessageType.Error
           (Printf.sprintf "Failed to resolve dependencies. %s"
              (String.concat ", " deps_errors))
@@ -205,27 +197,18 @@ let discover_subpackages_and_populate ~workspace_root
     | None -> ())
   |> ignore
 
-let on_initialize (params : InitializeParams.t) (server : State.t Server.t) =
-  let state = Server.state server in
-
-  let diagnostics =
-    Diagnostics.make ~diagnostics:(Diagnostics.empty ())
-      ~send:(fun publish_diagnostics_params ->
-        Server.notification
-          (Server_notification.PublishDiagnostics publish_diagnostics_params)
-          server)
-  in
-
+let discover_project_context ~notify_errors ~workspace_root
+    (server : State.t Server.t) =
   let analysis_state = Analysis.Shared_types.create_state () in
-
-  let workspace_root = Helpers.workspace_root_uri_of_initialize_params params in
-
-  discover_subpackages_and_populate ~workspace_root ~analysis_state ~server;
+  discover_subpackages_and_populate ~notify_errors ~workspace_root
+    ~analysis_state ~server;
 
   let compiler_config =
     analysis_state.packages_by_root |> Hashtbl.to_seq
     |> Seq.filter_map (fun (root_path, _) ->
-        match Compiler_config.parse ~root:root_path ~fs:state.fs with
+        match
+          Compiler_config.parse ~root:root_path ~fs:(Server.state server).fs
+        with
         | Ok config -> Some (Uri.of_path root_path, config)
         | Error _ ->
           (* NOTE: Surface malformed package configs to the client. We ignore
@@ -234,6 +217,21 @@ let on_initialize (params : InitializeParams.t) (server : State.t Server.t) =
           None)
     |> Compiler_config.Uri_map.of_seq
   in
+  (analysis_state, compiler_config)
+
+let on_initialize (params : InitializeParams.t) (server : State.t Server.t) =
+  let state = Server.state server in
+  let diagnostics =
+    Diagnostics.make ~diagnostics:(Diagnostics.empty ())
+      ~send:(fun publish_diagnostics_params ->
+        Server.notification
+          (Server_notification.PublishDiagnostics publish_diagnostics_params)
+          server)
+  in
+  let workspace_root = Helpers.workspace_root_uri_of_initialize_params params in
+  let analysis_state, compiler_config =
+    discover_project_context ~notify_errors:true ~workspace_root server
+  in
 
   let state =
     State.initialize state ~params ~diagnostics ~analysis_state ~compiler_config
@@ -626,7 +624,34 @@ let on_notification notification (server : State.t Server.t) =
     Server.request (Server_request.ClientRegisterCapability params) server;
 
     state
-  | DidChangeWatchedFiles _ -> (
+  | DidChangeWatchedFiles {changes} -> (
+    let state =
+      if
+        List.exists
+          (fun (event : FileEvent.t) ->
+            Filename.basename (Uri.to_path event.uri) = Constants.compiler_log
+            && (event.type_ = FileChangeType.Created
+               || event.type_ = FileChangeType.Changed))
+          changes
+      then
+        let workspace_root = State.workspace_root state in
+        let analysis_state, compiler_config =
+          discover_project_context ~notify_errors:false ~workspace_root server
+        in
+        (* A workspace opened before its first build has no package metadata.
+           Rediscover into fresh tables so failed lookups and old CMT caches
+           cannot survive the build. Keep the previous context if metadata is
+           still unavailable, and preserve buffers, settings and diagnostics. *)
+        if
+          Hashtbl.mem analysis_state.packages_by_root
+            (Uri.to_path workspace_root)
+        then
+          State.initialize state ~params:(State.params state)
+            ~diagnostics:(State.diagnostics state) ~analysis_state
+            ~compiler_config
+        else state
+      else state
+    in
     (* Do not limit diagnostics to the path reported by
        DidChangeWatchedFilesParams. In monorepos, a build in one subpackage
        can change diagnostics that should be shown for files in another

tests/lsp_tests/project_recovery.ml

@@ -0,0 +1,106 @@
+open Lsp
+open Types
+
+let notify_log ~root ~type_ client =
+  Test.Client.send_notification client
+    (Client_notification.DidChangeWatchedFiles
+       (DidChangeWatchedFilesParams.create
+          ~changes:
+            [
+              FileEvent.create ~type_
+                ~uri:(Uri.of_path (Filename.concat root "lib/bs/.compiler.log"));
+            ]))
+
+let test_recovery type_ =
+  Test.with_project ~name:"first-build" ~run_build:false
+    ~text:{|let value = 1
+|} (fun ~root ~doc client ->
+      let hover =
+        Client_request.TextDocumentHover
+          (HoverParams.create ~textDocument:(Test.text_document doc)
+             ~position:(Test.position (0, 5))
+             ())
+      in
+      Test.snapshot ~root client hover;
+      ignore (Test.Client.take_notifications client);
+      (* An early log event can arrive before build metadata exists. It must
+         leave the session usable and must not repeat initialization errors. *)
+      notify_log ~root ~type_ client;
+      Test.synchronize client;
+      let messages =
+        Test.Client.take_notifications client
+        |> List.filter (fun (n : Jsonrpc.Notification.t) ->
+            n.method_ = "window/showMessage")
+      in
+      Printf.printf "repeated initialization messages: %d\n"
+        (List.length messages);
+      Test.run_rescript_build ~root;
+      notify_log ~root ~type_ client;
+      Test.snapshot ~root client hover;
+      (* This request uses compiler_config, not only the analysis package cache. *)
+      Test.snapshot ~root client
+        (Client_request.UnknownRequest
+           {
+             meth = "textDocument/openCompiled";
+             params =
+               Some
+                 (Jsonrpc.Structured.t_of_yojson
+                    (TextDocumentIdentifier.yojson_of_t (Test.text_document doc)));
+           });
+      Test.change_document client doc ~version:1 ~text:{|let unsaved = 2
+|};
+      notify_log ~root ~type_:FileChangeType.Changed client;
+      let symbols =
+        Client_request.DocumentSymbol
+          (DocumentSymbolParams.create ~textDocument:(Test.text_document doc) ())
+      in
+      (* The unsaved buffer survives rediscovery; disk still has a valid value. *)
+      Test.snapshot ~root client symbols)
+
+let%expect_test "recovers after the first compiler log is created" =
+  test_recovery FileChangeType.Created;
+  [%expect
+    {|
+    null
+    repeated initialization messages: 0
+    { "contents": { "kind": "markdown", "value": "```rescript\nint\n```" } }
+    { "uri": "file:///workspace/lib/es6/./Test.res.js" }
+    [
+      {
+        "kind": 16,
+        "name": "unsaved",
+        "range": {
+          "end": { "character": 15, "line": 0 },
+          "start": { "character": 0, "line": 0 }
+        },
+        "selectionRange": {
+          "end": { "character": 15, "line": 0 },
+          "start": { "character": 0, "line": 0 }
+        }
+      }
+    ]
+    |}]
+
+let%expect_test "recovers when the client reports the first build as a change" =
+  test_recovery FileChangeType.Changed;
+  [%expect
+    {|
+    null
+    repeated initialization messages: 0
+    { "contents": { "kind": "markdown", "value": "```rescript\nint\n```" } }
+    { "uri": "file:///workspace/lib/es6/./Test.res.js" }
+    [
+      {
+        "kind": 16,
+        "name": "unsaved",
+        "range": {
+          "end": { "character": 15, "line": 0 },
+          "start": { "character": 0, "line": 0 }
+        },
+        "selectionRange": {
+          "end": { "character": 15, "line": 0 },
+          "start": { "character": 0, "line": 0 }
+        }
+      }
+    ]
+    |}]