full-analysis: auto-instantiate environments and cache detection results

Add automatic `Pkg.instantiate()` for environments that have not been
instantiated yet (e.g., freshly cloned repositories or new project
directories). This allows full analysis to work immediately upon opening
files in such environments, whether they are package source files,
test files, or scripts with their own Project.toml.

Also add caching for environment detection results to avoid redundant
`Pkg.instantiate()` calls and `Base.identify_package_env` lookups for
the same environment.

The behavior is controlled by `full_analysis.auto_instantiate` config
option (default: `true`).

Author: aviatesk

CHANGELOG.md

@@ -16,6 +16,15 @@ 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: [`eda08b5...HEAD`](https://github.com/aviatesk/JETLS.jl/compare/eda08b5...HEAD)
 
+### Added
+
+- JETLS now automatically runs `Pkg.instantiate()` for packages that have not
+  been instantiated yet (e.g., freshly cloned repositories). This allows
+  full analysis to work immediately upon opening such packages. Note that this
+  will automatically create a `Manifest.toml` file when the package has not been
+  instantiated yet. This behavior is controlled by the `full_analysis.auto_instantiate`
+  configuration option (default: `true`). Set it to `false` to disable.
+
 ### Fixed
 
 - Fixed error when receiving notifications after shutdown request. The server

docs/src/configuration.md

@@ -8,6 +8,7 @@ This documentation uses TOML format to describe the configuration schema.
 ```toml
 [full_analysis]
 debounce = 1.0             # number (seconds), default: 1.0
+auto_instantiate = true    # boolean, default: true
 
 formatter = "Runic"        # String preset: "Runic" (default) or "JuliaFormatter"
 
@@ -33,6 +34,7 @@ executable = "testrunner"  # string, default: "testrunner" (or "testrunner.bat"
 
 - [`[full_analysis]`](@ref config/full_analysis)
     - [`[full_analysis] debounce`](@ref config/full_analysis-debounce)
+    - [`[full_analysis] auto_instantiate`](@ref config/full_analysis-auto_instantiate)
 - [`formatter`](@ref config/formatter)
 - [`[diagnostic]`](@ref config/diagnostic)
     - [`[diagnostic] enabled`](@ref config/diagnostic-enabled)
@@ -58,6 +60,22 @@ may delay diagnostic updates.
 debounce = 2.0  # Wait 2 seconds after save before analyzing
 ```
 
+#### [`[full_analysis] auto_instantiate`](@id config/full_analysis-auto_instantiate)
+
+- **Type**: boolean
+- **Default**: `true`
+
+When enabled, JETLS automatically runs `Pkg.instantiate()` for packages that have
+not been instantiated yet (e.g., freshly cloned repositories). This allows full
+analysis to work immediately upon opening such packages. Note that this will
+automatically create a `Manifest.toml` file when the package has not been
+instantiated yet.
+
+```toml
+[full_analysis]
+auto_instantiate = false  # Disable automatic instantiation
+```
+
 ### [`formatter`](@id config/formatter)
 
 - **Type**: string or table

jetls-client/package.json

@@ -119,6 +119,11 @@
                   "default": 1,
                   "minimum": 0,
                   "markdownDescription": "Debounce time in seconds before triggering full analysis after a document change."
+                },
+                "auto_instantiate": {
+                  "type": "boolean",
+                  "default": true,
+                  "markdownDescription": "When enabled, JETLS automatically runs `Pkg.instantiate()` for packages that have not been instantiated yet (e.g., freshly cloned repositories). This allows full analysis to work immediately upon opening such packages. Note that this will automatically create a `Manifest.toml` file when the package has not been instantiated yet."
                 }
               }
             },

src/analysis/full-analysis.jl

@@ -59,20 +59,17 @@ function request_analysis!(
         notify::Bool = true, # used by tests
     )
     manager = server.state.analysis_manager
-    analysis_info = get_analysis_info(server.state.analysis_manager, uri)
-    prev_analysis_result = nothing
-    if isnothing(analysis_info)
-        entry = lookup_analysis_entry(server.state, uri)
-    elseif analysis_info isa OutOfScope
-        entry = analysis_info
-    else
-        analysis_result = analysis_info::AnalysisResult # cached analysis result
-        entry = analysis_result.entry
-        prev_analysis_result = analysis_result
-    end
-
-    if entry isa OutOfScope
-        local outofscope = entry
+    prev_analysis_result = get_analysis_info(server.state.analysis_manager, uri)
+    local outofscope::OutOfScope
+    if isnothing(prev_analysis_result)
+        entry = lookup_analysis_entry(server, uri)
+        if entry isa OutOfScope
+            outofscope = entry
+            @goto out_of_scope
+        end
+    elseif prev_analysis_result isa OutOfScope
+        outofscope = prev_analysis_result
+        @label out_of_scope
         store!(manager.cache) do cache
             if get(cache, uri, nothing) === outofscope
                 cache, nothing
@@ -83,6 +80,9 @@ function request_analysis!(
             end
         end
         return nothing
+    else
+        prev_analysis_result::AnalysisResult
+        entry = prev_analysis_result.entry
     end
     entry = entry::AnalysisEntry
 
@@ -324,40 +324,114 @@ function new_analysis_result(request::AnalysisRequest, result)
     return AnalysisResult(entry, uri2diagnostics, analyzer, analyzed_file_infos, actual2virtual)
 end
 
-function lookup_analysis_entry(state::ServerState, uri::URI)
+function ensure_instantiated(server::Server, env_path::String, context::String)
+    if get_config(server.state.config_manager, :full_analysis, :auto_instantiate)
+        try
+            JETLS_DEV_MODE && @info "Instantiating package environment" env_path context
+            Pkg.instantiate()
+        catch e
+            @error """Failed to instantiate package environment;
+            Unable to instantiate the environment of the target package for analysis,
+            so this package will be analyzed as a script instead.
+            This may cause various features such as diagnostics to not function properly.
+            It is recommended to fix the problem by referring to the following error""" env_path
+            Base.showerror(stderr, e, catch_backtrace())
+            show_warning_message(server, """
+                Failed to instantiate package environment at $env_path.
+                The package will be analyzed as a script, which may result in incomplete diagnostics.
+                See the language server log for details.
+                It is recommended to fix your environment setup and restart the language server.""")
+        end
+    end
+end
+
+function ensure_instantiated_if_needed(server::Server, env_path::String, context::String)
+    instantiated_envs = server.state.analysis_manager.instantiated_envs
+    activate_do(env_path) do
+        # Check if already processed (success or failure)
+        if haskey(load(instantiated_envs), env_path)
+            return
+        end
+        ensure_instantiated(server, env_path, context)
+        # Mark as processed
+        store!(instantiated_envs) do cache
+            if haskey(cache, env_path)
+                cache, nothing
+            else
+                new_cache = copy(cache)
+                new_cache[env_path] = nothing
+                new_cache, nothing
+            end
+        end
+    end
+end
+
+function lookup_analysis_entry(server::Server, uri::URI)
+    state = server.state
     maybe_env_path = find_analysis_env_path(state, uri)
     if maybe_env_path isa OutOfScope
-        return maybe_env_path
+        outofscope = maybe_env_path
+        return outofscope
     end
 
     env_path = maybe_env_path
     if isnothing(env_path)
         return ScriptAnalysisEntry(uri)
     elseif uri.scheme == "untitled"
+        ensure_instantiated_if_needed(server, env_path, "untitled")
         return ScriptInEnvAnalysisEntry(env_path, uri)
     end
 
     pkgname = find_pkg_name(env_path)
+    filepath = uri2filepath(uri)::String # uri.scheme === "file"
     if isnothing(pkgname)
+        ensure_instantiated_if_needed(server, env_path, "script: $filepath")
         return ScriptInEnvAnalysisEntry(env_path, uri)
     end
-    filepath = uri2filepath(uri)::String # uri.scheme === "file"
     filekind, filedir = find_package_directory(filepath, env_path)
     if filekind === :src
+        instantiated_envs = server.state.analysis_manager.instantiated_envs
         return @something activate_do(env_path) do
+            # Check cache inside lock to avoid race conditions
+            cached = get(load(instantiated_envs), env_path, missing)
+            if cached === nothing
+                # Previously failed to detect package environment
+                return ScriptInEnvAnalysisEntry(env_path, uri)
+            elseif cached !== missing
+                pkgid, pkgfileuri = cached
+                return PackageSourceAnalysisEntry(env_path, pkgfileuri, pkgid)
+            end
+            # Cache miss - perform environment detection
+            ensure_instantiated(server, env_path, "src: $filepath")
             pkgenv = @lock Base.require_lock @something Base.identify_package_env(pkgname) begin
-                @warn "Failed to identify package environment" pkgname
+                @warn "Failed to identify package environment" env_path pkgname filepath
+                store!(instantiated_envs) do cache
+                    new_cache = copy(cache)
+                    new_cache[env_path] = nothing
+                    new_cache, nothing
+                end
                 return nothing
             end
             pkgid, env = pkgenv
             pkgfile = @something Base.locate_package(pkgid, env) begin
                 @warn "Expected a package to have a source file" pkgname
+                store!(instantiated_envs) do cache
+                    new_cache = copy(cache)
+                    new_cache[env_path] = nothing
+                    new_cache, nothing
+                end
                 return nothing
             end
             pkgfileuri = filepath2uri(pkgfile)
+            store!(instantiated_envs) do cache
+                new_cache = copy(cache)
+                new_cache[env_path] = (pkgid, pkgfileuri)
+                new_cache, nothing
+            end
             PackageSourceAnalysisEntry(env_path, pkgfileuri, pkgid)
         end ScriptInEnvAnalysisEntry(env_path, uri)
     elseif filekind === :test
+        ensure_instantiated_if_needed(server, env_path, "test: $filepath")
         runtestsfile = joinpath(filedir, "runtests.jl")
         runtestsuri = filepath2uri(runtestsfile)
         return PackageTestAnalysisEntry(env_path, runtestsuri)
@@ -366,6 +440,7 @@ function lookup_analysis_entry(state::ServerState, uri::URI)
     else
         @assert filekind === :script
     end
+    ensure_instantiated_if_needed(server, env_path, "script: $filepath")
     return ScriptInEnvAnalysisEntry(env_path, uri)
 end
 

src/types.jl

@@ -186,6 +186,7 @@ const PendingAnalyses = CASContainer{Dict{AnalysisEntry,Union{Nothing,AnalysisRe
 const CurrentGenerations = CASContainer{Dict{AnalysisEntry,Int}}
 const AnalyzedGenerations = CASContainer{Dict{AnalysisEntry,Int}}
 const DebouncedRequests = LWContainer{Dict{AnalysisEntry,Timer}, LWStats}
+const InstantiatedEnvs = LWContainer{Dict{String,Union{Nothing,Tuple{Base.PkgId,URI}}}}
 
 struct AnalysisManager
     cache::AnalysisCache
@@ -195,6 +196,7 @@ struct AnalysisManager
     current_generations::CurrentGenerations
     analyzed_generations::AnalyzedGenerations
     debounced::DebouncedRequests
+    instantiated_envs::InstantiatedEnvs
     function AnalysisManager(n_workers::Int)
         return new(
             AnalysisCache(Dict{URI,AnalysisInfo}()),
@@ -203,7 +205,8 @@ struct AnalysisManager
             Vector{Task}(undef, n_workers),
             CurrentGenerations(Dict{AnalysisEntry,Int}()),
             AnalyzedGenerations(Dict{AnalysisEntry,Int}()),
-            DebouncedRequests(Dict{AnalysisEntry,Timer}())
+            DebouncedRequests(Dict{AnalysisEntry,Timer}()),
+            InstantiatedEnvs(Dict{String,Union{Nothing,Tuple{Base.PkgId,URI}}}())
         )
     end
 end
@@ -316,8 +319,9 @@ _unwrap_maybe(::Type{T}) where {T} = T
 
 @option struct FullAnalysisConfig <: ConfigSection
     debounce::Maybe{Float64}
+    auto_instantiate::Maybe{Bool}
 end
-default_config(::Type{FullAnalysisConfig}) = FullAnalysisConfig(1.0)
+default_config(::Type{FullAnalysisConfig}) = FullAnalysisConfig(1.0, true)
 
 @option struct TestRunnerConfig <: ConfigSection
     executable::Maybe{String}