Merge pull request #289 from aviatesk/avi/prioritize-workspace-config

config: hierarchical configuration experiment (not enabled for now)

Author: aviatesk

AGENTS.md

@@ -6,6 +6,10 @@
   - Additionally, prioritize simple text style and limit unnecessary decorations
     (e.g. `**`) to only truly necessary locations. This is a style that should
     generally be aimed for, but pay particular attention when writing Markdown.
+  - Headers should use sentence case (only the first word capitalized), not
+    title case. For example:
+    - Good: `## Conclusion and alternative approaches`
+    - Bad: `## Conclusion And Alternative Approaches`
 - When writing commit messages, follow the format `component: Brief summary` for
   the title. In the body of the commit message, provide a brief prose summary of
   the purpose of the changes made.

docs/src/configuration.md

@@ -67,7 +67,7 @@ See [TestRunner integration](@ref) for setup instructions.
 
 ## How to configure JETLS
 
-### Method 1: Project-specific configuration file
+### Method 1: File-based configuration
 
 Create a `.JETLSConfig.toml` file in your project root.
 This configuration method works client-agnostically, thus allows projects to
@@ -154,10 +154,13 @@ section:
 When multiple configuration sources are present, they are merged in priority
 order (highest first):
 
-1. Project-specific `.JETLSConfig.toml`
-2. Editor configuration via LSP
+1. File-based configuration (`.JETLSConfig.toml`)
+2. Editor configuration via LSP (`workspace/configuration`)
 3. Built-in defaults
 
-The `.JETLSConfig.toml` file takes precedence, since it provides a
-**client-agnostic** way to configure JETLS that works consistently across
-all editors.
+File-based configuration (`.JETLSConfig.toml`) takes precedence as it provides
+a **client-agnostic** way to configure JETLS that works consistently across all
+editors. While the LSP specification defines `scopeUri` for hierarchical
+configuration, current LSP clients (including Zed and VS Code as of 2025-10-27)
+do not properly support scoped configuration requests, making `.JETLSConfig.toml`
+the more useful configuration method for project-specific settings.

src/did-change-watched-files.jl

@@ -28,14 +28,14 @@ function handle_config_file_change!(
     tracker = ConfigChangeTracker()
 
     if change_type == FileChangeType.Created
-        load_config!(tracker, server, changed_path)
+        load_file_config!(tracker, server, changed_path)
         kind = "created"
         show_info_message(server, config_file_created_msg(changed_path))
     elseif change_type == FileChangeType.Changed
-        load_config!(tracker, server, changed_path; reload=true)
+        load_file_config!(tracker, server, changed_path; reload=true)
         kind = "updated"
     elseif change_type == FileChangeType.Deleted
-        delete_config!(tracker, server.state.config_manager, changed_path)
+        delete_file_config!(tracker, server.state.config_manager, changed_path)
         kind = "deleted"
         show_info_message(server, config_file_deleted_msg(changed_path))
     else error("Unknown FileChangeType") end
@@ -45,24 +45,24 @@ function handle_config_file_change!(
 end
 
 """
-Loads the project configuration from the specified path into the server's config manager.
+Loads the file-based configuration from the specified path into the server's config manager.
 
 If the file does not exist or cannot be parsed, just return leaving the current
 configuration unchanged. When there are unknown keys in the config file,
 send error message while leaving current configuration unchanged.
 """
-function load_config!(callback, server::Server, filepath::AbstractString;
-                      reload::Bool = false)
+function load_file_config!(callback, server::Server, filepath::AbstractString;
+                           reload::Bool = false)
     store!(server.state.config_manager) do old_data::ConfigManagerData
-        if reload && old_data.project_config_path != filepath
+        if reload && old_data.file_config_path != filepath
             show_warning_message(server, "Loading unregistered configuration file: $filepath")
         end
 
         isfile(filepath) || return old_data, nothing
         parsed = TOML.tryparsefile(filepath)
         parsed isa TOML.ParserError && return old_data, nothing
 
-        new_project_config = try
+        new_file_config = try
             Configurations.from_dict(JETLSConfig, parsed)
         catch e
             # TODO: remove this when Configurations.jl support to report
@@ -83,8 +83,8 @@ function load_config!(callback, server::Server, filepath::AbstractString;
         end
 
         new_data = ConfigManagerData(old_data;
-            project_config=new_project_config,
-            project_config_path=filepath
+            file_config=new_file_config,
+            file_config_path=filepath
         )
         on_difference(callback, get_settings(old_data), get_settings(new_data))
         return new_data, nothing
@@ -94,12 +94,12 @@ end
 unmatched_keys_in_config_file_msg(filepath::AbstractString, unmatched_keys) =
     unmatched_keys_msg("Configuration file at $filepath contains unknown keys:", unmatched_keys)
 
-function delete_config!(callback, manager::ConfigManager, filepath::AbstractString)
+function delete_file_config!(callback, manager::ConfigManager, filepath::AbstractString)
     store!(manager) do old_data::ConfigManagerData
-        old_data.project_config_path == filepath || return old_data, nothing
+        old_data.file_config_path == filepath || return old_data, nothing
         new_data = ConfigManagerData(old_data;
-            project_config=EMPTY_CONFIG,
-            project_config_path=nothing
+            file_config=EMPTY_CONFIG,
+            file_config_path=nothing
         )
         on_difference(callback, get_settings(old_data), get_settings(new_data))
         return new_data, nothing

src/lifecycle.jl

@@ -54,7 +54,7 @@ function handle_InitializeRequest(server::Server, msg::InitializeRequest)
     else
         config_path = joinpath(state.root_path, ".JETLSConfig.toml")
         if isfile(config_path)
-            load_config!(Returns(nothing), server, config_path)
+            load_file_config!(Returns(nothing), server, config_path)
         end
     end
 

src/types.jl

@@ -392,24 +392,28 @@ const EMPTY_CONFIG = JETLSConfig()
 
 struct ConfigManagerData
     static_settings::JETLSConfig
-    project_config::JETLSConfig
+    file_config::JETLSConfig
     lsp_config::JETLSConfig
-    project_config_path::Union{Nothing,String}
+    file_config_path::Union{Nothing,String}
     __settings__::JETLSConfig
     function ConfigManagerData(
             static_settings::JETLSConfig,
-            project_config::JETLSConfig,
+            file_config::JETLSConfig,
             lsp_config::JETLSConfig,
-            project_config_path::Union{Nothing,String}
+            file_config_path::Union{Nothing,String}
         )
         # Configuration priority:
         # 1. DEFAULT_CONFIG (base layer)
-        # 2. LSP config (middle layer)
-        # 3. Project config (highest priority)
+        # 2. LSP config via `workspace/configuration` (middle layer)
+        # 3. File config from `.JETLSConfig.toml` (highest priority)
+        #    - Allows client-agnostic configuration
+        #    - Limited to project root scope only
+        #    - Takes precedence since clients don't properly support
+        #      hierarchical configuration via scopeUri
         settings = DEFAULT_CONFIG
         settings = merge_setting(settings, lsp_config)
-        settings = merge_setting(settings, project_config)
-        return new(static_settings, project_config, lsp_config, project_config_path, settings)
+        settings = merge_setting(settings, file_config)
+        return new(static_settings, file_config, lsp_config, file_config_path, settings)
     end
 end
 
@@ -418,11 +422,11 @@ ConfigManagerData() = ConfigManagerData(DEFAULT_CONFIG, EMPTY_CONFIG, EMPTY_CONF
 function ConfigManagerData(
         data::ConfigManagerData;
         static_settings::JETLSConfig = data.static_settings,
-        project_config::JETLSConfig = data.project_config,
+        file_config::JETLSConfig = data.file_config,
         lsp_config::JETLSConfig = data.lsp_config,
-        project_config_path::Union{Nothing,String} = data.project_config_path
+        file_config_path::Union{Nothing,String} = data.file_config_path
     )
-    return ConfigManagerData(static_settings, project_config, lsp_config, project_config_path)
+    return ConfigManagerData(static_settings, file_config, lsp_config, file_config_path)
 end
 
 get_settings(data::ConfigManagerData) = data.__settings__

test/test_config.jl

@@ -113,11 +113,11 @@ end
     end
 end
 
-function store_project_config!(manager::JETLS.ConfigManager, filepath::AbstractString, new_config::JETLS.JETLSConfig)
+function store_file_config!(manager::JETLS.ConfigManager, filepath::AbstractString, new_config::JETLS.JETLSConfig)
     JETLS.store!(manager) do old_data
         new_data = JETLS.ConfigManagerData(old_data;
-            project_config=new_config,
-            project_config_path=filepath
+            file_config=new_config,
+            file_config_path=filepath
         )
         return new_data, nothing
     end
@@ -139,7 +139,7 @@ end
         internal=JETLS.InternalConfig(5, nothing)
     )
 
-    store_project_config!(manager, "/foo/bar/.JETLSConfig.toml", test_config)
+    store_file_config!(manager, "/foo/bar/.JETLSConfig.toml", test_config)
     JETLS.fix_static_settings!(manager)
 
     @test JETLS.get_config(manager, :full_analysis, :debounce) === 2.0
@@ -154,33 +154,34 @@ end
            JETLS.get_config(manager, :internal, :static_setting)
     end == Union{Nothing, Int}
 
-    # Test priority: LSP config has lower priority than project config
+    # Test priority: file config has higher priority than LSP config
     lsp_config = JETLS.JETLSConfig(;
         full_analysis=JETLS.FullAnalysisConfig(999.0),
         testrunner=JETLS.TestRunnerConfig("lsp_runner")
     )
     store_lsp_config!(manager, lsp_config)
-    # High priority project config should still win
+    # High priority file config should win
     @test JETLS.get_config(manager, :full_analysis, :debounce) === 2.0
     @test JETLS.get_config(manager, :testrunner, :executable) === "test_runner"
 
     # Test updating config
+    store_lsp_config!(manager, JETLS.EMPTY_CONFIG)
     changed_static_keys = Set{String}()
     updated_config = JETLS.JETLSConfig(;
         full_analysis=JETLS.FullAnalysisConfig(3.0),
         testrunner=JETLS.TestRunnerConfig("new_runner"),
         internal=JETLS.InternalConfig(10, nothing)
     )
     let data = JETLS.load(manager)
-        current_config = data.project_config
+        current_config = data.file_config
         JETLS.on_difference(current_config, updated_config) do _, new_val, path
             if JETLS.is_static_setting(JETLS.JETLSConfig, path...)
                 push!(changed_static_keys, join(path, "."))
             end
             return new_val
         end
     end
-    store_project_config!(manager, "/foo/bar/.JETLSConfig.toml", updated_config)
+    store_file_config!(manager, "/foo/bar/.JETLSConfig.toml", updated_config)
 
     # `on_static_setting` should be called for static keys
     @test changed_static_keys == Set(["internal.static_setting"])
@@ -193,19 +194,19 @@ end
 
 @testset "`fix_static_settings!`" begin
     manager = JETLS.ConfigManager(JETLS.ConfigManagerData())
-    high_priority_config = JETLS.JETLSConfig(;
+    file_config = JETLS.JETLSConfig(;
         internal=JETLS.InternalConfig(2, nothing)
     )
-    low_priority_config = JETLS.JETLSConfig(;
+    lsp_config = JETLS.JETLSConfig(;
         internal=JETLS.InternalConfig(999, nothing),
         testrunner=JETLS.TestRunnerConfig("custom")
     )
 
-    store_lsp_config!(manager, low_priority_config)
-    store_project_config!(manager, "/path/.JETLSConfig.toml", high_priority_config)
+    store_file_config!(manager, "/path/.JETLSConfig.toml", file_config)
+    store_lsp_config!(manager, lsp_config)
     JETLS.fix_static_settings!(manager)
 
-    # high priority should win for the static keys
+    # File config (higher priority) should win for the static keys
     data = JETLS.load(manager)
     @test JETLS.getobjpath(data.static_settings, :internal, :static_setting) == 2
 end
@@ -217,19 +218,21 @@ end
         full_analysis=JETLS.FullAnalysisConfig(2.0),
         testrunner=nothing
     )
-    project_config = JETLS.JETLSConfig(;
-        testrunner=JETLS.TestRunnerConfig("project_runner"),
+    file_config = JETLS.JETLSConfig(;
+        testrunner=JETLS.TestRunnerConfig("file_runner"),
         full_analysis=nothing
     )
 
     store_lsp_config!(manager, lsp_config)
-    store_project_config!(manager, "/project/.JETLSConfig.toml", project_config)
+    store_file_config!(manager, "/project/.JETLSConfig.toml", file_config)
 
-    @test JETLS.get_config(manager, :testrunner, :executable) == "project_runner"
+    # File config has higher priority, so it wins when both are set
+    @test JETLS.get_config(manager, :testrunner, :executable) == "file_runner"
+    # When file config doesn't set a value, LSP config is used
     @test JETLS.get_config(manager, :full_analysis, :debounce) == 2.0
 end
 
-@testset "LSP configuration merging without project config" begin
+@testset "LSP configuration merging without file config" begin
     manager = JETLS.ConfigManager(JETLS.ConfigManagerData())
 
     lsp_config = JETLS.JETLSConfig(;
@@ -247,22 +250,22 @@ end
     @testset "preset formatter: Runic" begin
         manager = JETLS.ConfigManager(JETLS.ConfigManagerData())
         config = JETLS.JETLSConfig(; formatter="Runic")
-        store_project_config!(manager, "/path/.JETLSConfig.toml", config)
+        store_file_config!(manager, "/path/.JETLSConfig.toml", config)
         @test JETLS.get_config(manager, :formatter) == "Runic"
     end
 
     @testset "preset formatter: JuliaFormatter" begin
         manager = JETLS.ConfigManager(JETLS.ConfigManagerData())
         config = JETLS.JETLSConfig(; formatter="JuliaFormatter")
-        store_project_config!(manager, "/path/.JETLSConfig.toml", config)
+        store_file_config!(manager, "/path/.JETLSConfig.toml", config)
         @test JETLS.get_config(manager, :formatter) == "JuliaFormatter"
     end
 
     @testset "custom formatter" begin
         manager = JETLS.ConfigManager(JETLS.ConfigManagerData())
         custom = JETLS.CustomFormatterConfig("my-formatter", "my-range-formatter")
         config = JETLS.JETLSConfig(; formatter=custom)
-        store_project_config!(manager, "/path/.JETLSConfig.toml", config)
+        store_file_config!(manager, "/path/.JETLSConfig.toml", config)
         formatter = JETLS.get_config(manager, :formatter)
         @test formatter isa JETLS.CustomFormatterConfig
         @test formatter.executable == "my-formatter"
@@ -273,7 +276,7 @@ end
         manager = JETLS.ConfigManager(JETLS.ConfigManagerData())
         custom = JETLS.CustomFormatterConfig("my-formatter", nothing)
         config = JETLS.JETLSConfig(; formatter=custom)
-        store_project_config!(manager, "/path/.JETLSConfig.toml", config)
+        store_file_config!(manager, "/path/.JETLSConfig.toml", config)
         formatter = JETLS.get_config(manager, :formatter)
         @test formatter isa JETLS.CustomFormatterConfig
         @test formatter.executable == "my-formatter"