initialize: Add LSP initializationOptions support (#350)

Add support for static initialization options that are set once during
server startup and require a restart to take effect. This differs from
dynamic configuration managed by `ConfigManager`.

Currently supports `n_analysis_workers` option for configuring the number
of concurrent analysis worker tasks. Due to current architecture
constraints around package environment switching and world age
management, parallelization is limited to the signature analysis phase.

Also updates `jetls-client` and documentation accordingly.

Written by Claude

Author: aviatesk

CHANGELOG.md

@@ -16,6 +16,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Commit: [`HEAD`](https://github.com/aviatesk/JETLS.jl/commit/HEAD)
 - Diff: [`f9b2c2f...HEAD`](https://github.com/aviatesk/JETLS.jl/compare/f9b2c2f...HEAD)
 
+### Added
+
+- Added support for LSP `initializationOptions` with the `n_analysis_workers`
+  option for configuring concurrent analysis worker tasks.
+  See [Initialization options](https://aviatesk.github.io/JETLS.jl/dev/launching/#init-options)
+  for details.
+
 ### Fixed
 
 - Fixed handling of messages received before the initialize request per

docs/src/launching.md

@@ -127,3 +127,77 @@ client cannot execute the normal LSP shutdown sequence.
     When specified via command line, the process ID should match the
     `processId` field that the client sends in the LSP `initialize` request
     parameters.
+
+## [Initialization options](@id init-options)
+
+JETLS accepts static initialization options via the LSP `initializationOptions`
+field in the `initialize` request. Unlike [dynamic configuration](@ref config/schema)
+that can be changed at runtime, these options are set once at server startup and
+require a server restart to take effect.
+
+### [Schema](@id init-options/schema)
+
+```json
+{
+  "n_analysis_workers": 1
+}
+```
+
+### [Reference](@id init-options/reference)
+
+#### [`n_analysis_workers`](@id init-options/n_analysis_workers)
+
+- **Type**: integer
+- **Default**: `1`
+- **Minimum**: `1`
+
+Number of concurrent analysis worker tasks for running full analysis.
+
+```json
+{
+  "n_analysis_workers": 3
+}
+```
+
+!!! warning "Current limitations"
+    JETLS currently runs all analysis within a single server process. These
+    "workers" are concurrent tasks, not separate processes. Due to constraints
+    around package environment switching and world age management during code
+    loading, all workers are forced to execute sequentially during the code
+    loading phase of full analysis. Only the signature analysis phase of
+    package analysis actually runs in parallel.
+
+    As a result, increasing `n_analysis_workers` may not significantly speed up
+    overall analysis in many scenarios. The semantics of this option may also
+    change substantially in future versions as the full analysis architecture
+    evolves.
+
+### [Client configuration](@id init-options/client-config)
+
+#### [VSCode (`jetls-client` extension)](@id init-options/client-config/vscode)
+
+Configure initialization options in VSCode's `settings.json`:
+
+```json
+{
+  "jetls-client.initializationOptions": {
+    "n_analysis_workers": 3
+  }
+}
+```
+
+#### [Zed (`aviatesk/zed-julia` extension)](@id init-options/client-config/zed)
+
+Configure initialization options in Zed's `settings.json`:
+
+```json
+{
+  "lsp": {
+    "JETLS": {
+      "initialization_options": {
+        "n_analysis_workers": 3
+      }
+    }
+  }
+}
+```

jetls-client/CHANGELOG.md

@@ -10,6 +10,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Commit: [`HEAD`](https://github.com/aviatesk/JETLS.jl/commit/HEAD)
 - Diff: [`dd21f78...HEAD`](https://github.com/aviatesk/JETLS.jl/compare/dd21f78...HEAD)
 
+### Added
+
+- Added `jetls-client.initializationOptions` setting for static server options
+  that require a restart to take effect. Currently supports `n_analysis_workers`
+  for configuring concurrent analysis worker tasks.
+  See <https://aviatesk.github.io/JETLS.jl/dev/launching/#init-options> for details.
+
 ## v0.2.4
 
 - Commit: [`dd21f78`](https://github.com/aviatesk/JETLS.jl/commit/dd21f78)

jetls-client/README.md

@@ -103,6 +103,29 @@ You can override the automatic selection using `"jetls-client.communicationChann
 For detailed information about each communication channel and when to use them,
 see the [Communication channels documentation](https://aviatesk.github.io/JETLS.jl/dev/launching/#Communication-channels).
 
+### Initialization options
+
+Static options that are sent to JETLS during startup. These settings require a
+server restart to take effect.
+
+Configure via `"jetls-client.initializationOptions"`:
+
+- `"n_analysis_workers": number`: Number of concurrent analysis worker threads
+  (default: `1`, minimum: `1`)
+
+Example:
+
+```jsonc
+{
+  "jetls-client.initializationOptions": {
+    "n_analysis_workers": 3
+  }
+}
+```
+
+For more details, see the
+[Initialization options documentation](https://aviatesk.github.io/JETLS.jl/dev/launching/#Initialization-options).
+
 ## Configuring JETLS
 
 JETLS behavior (diagnostics, formatting, etc.) can be configured through VSCode's

jetls-client/jetls-client.ts

@@ -444,6 +444,8 @@ async function startLanguageServer() {
     };
   }
 
+  const initializationOptions = vscode.workspace.getConfiguration("jetls-client").get("initializationOptions", {});
+
   const clientOptions: LanguageClientOptions = {
     documentSelector: [
       {
@@ -455,6 +457,7 @@ async function startLanguageServer() {
         language: "julia",
       },
     ],
+    initializationOptions,
     outputChannel,
   };
 

jetls-client/package.json

@@ -104,6 +104,21 @@
           "markdownDescription": "Port number for socket communication (`0` = auto-assign). Only used when `'socket'` communication channel is used.",
           "order": 3
         },
+        "jetls-client.initializationOptions": {
+          "scope": "resource",
+          "type": "object",
+          "default": {},
+          "markdownDescription": "Static initialization options sent to JETLS during startup. These settings require a server restart to take effect.",
+          "properties": {
+            "n_analysis_workers": {
+              "type": "integer",
+              "default": 1,
+              "minimum": 1,
+              "markdownDescription": "Number of analysis worker tasks. Default is `1`. See [documentation](https://aviatesk.github.io/JETLS.jl/dev/launching/#init-options/n_analysis_workers) for details and current limitations."
+            }
+          },
+          "order": 4
+        },
         "jetls-client.settings": {
           "scope": "resource",
           "type": "object",

src/JETLS.jl

@@ -75,6 +75,7 @@ include("utils/binding.jl")
 include("utils/lsp.jl")
 include("utils/server.jl")
 
+include("init_options.jl")
 include("config.jl")
 include("workspace-configuration.jl")
 

src/analysis/full-analysis.jl

@@ -72,8 +72,10 @@ end
 # ===============
 
 function start_analysis_workers!(server::Server)
-    for i = 1:length(server.state.analysis_manager.worker_tasks)
-        server.state.analysis_manager.worker_tasks[i] = Threads.@spawn :default try
+    n_workers = get_init_option(server.state.init_options, :n_analysis_workers)
+    @info "Starting $n_workers analysis workers"
+    for _ = 1:n_workers
+        Threads.@spawn :default try
             analysis_worker(server)
         catch err
             @error "Critical error happened in analysis worker"
@@ -82,7 +84,7 @@ function start_analysis_workers!(server::Server)
     end
 end
 
- # Analysis queue processing implementation (analysis serialized per AnalysisEntry)
+# Analysis queue processing implementation (analysis serialized per AnalysisEntry)
 function analysis_worker(server::Server)
     # Note: Currently single worker, but designed for future multi-worker scaling.
     # When multiple workers exist, the per-entry serialization ensures correctness.

src/init_options.jl

@@ -0,0 +1,29 @@
+const DEFAULT_INIT_OPTIONS = InitOptions(; n_analysis_workers=1)
+
+function merge_init_options(base::InitOptions, overlay::InitOptions)
+    InitOptions(;
+        n_analysis_workers = something(overlay.n_analysis_workers, base.n_analysis_workers))
+end
+
+function validate_init_options(opts::InitOptions)
+    n = opts.n_analysis_workers
+    if n !== nothing && n < 1
+        @warn "n_analysis_workers must be at least 1, using default" n
+        return InitOptions(; n_analysis_workers=DEFAULT_INIT_OPTIONS.n_analysis_workers)
+    end
+    return opts
+end
+
+function parse_init_options(@nospecialize init_options)
+    init_options === nothing && return DEFAULT_INIT_OPTIONS
+    init_options isa AbstractDict || return DEFAULT_INIT_OPTIONS
+    parsed = try
+        validate_init_options(Configurations.from_dict(InitOptions, init_options))
+    catch err
+        @warn "Failed to parse initializationOptions, using defaults" err
+        return DEFAULT_INIT_OPTIONS
+    end
+    return merge_init_options(DEFAULT_INIT_OPTIONS, parsed)
+end
+
+get_init_option(opts::InitOptions, key::Symbol) = @something getfield(opts, key) error(lazy"Invalid init option: $key")

src/initialize.jl

@@ -1,8 +1,3 @@
-# NOTE: Static server settings that require a server restart to take effect should be
-# accessed during server initialization via `state.init_params.initializationOptions`.
-# These settings differ from dynamic configuration options managed by `ConfigManager`
-# that can be changed at throughout server lifecycle.
-
 """
 Receives `msg::InitializeRequest` and sets up the `server.state` based on `msg.params`.
 As a response to this `msg`, it returns an `InitializeResponse` and performs registration of
@@ -22,6 +17,12 @@ function handle_InitializeRequest(
     state = server.state
     init_params = state.init_params = msg.params
 
+    # NOTE: Static server settings that require a server restart to take effect should be
+    # accessed during server initialization via `state.init_params.initializationOptions`.
+    # These settings differ from dynamic configuration options managed by `ConfigManager`
+    # that can be changed at throughout server lifecycle.
+    state.init_options = parse_init_options(init_params.initializationOptions)
+
     workspaceFolders = init_params.workspaceFolders
     if workspaceFolders !== nothing
         state.workspaceFolders = URI[uri for (; uri) in workspaceFolders]
@@ -427,4 +428,5 @@ function handle_InitializedNotification(server::Server)
     register(server, registrations)
 
     JETLS_DEV_MODE && show_setup_info("Initialized JETLS with the following setup:")
+    JETLS_DEV_MODE && @info "JETLS intialization options" init_options=state.init_options
 end