workspace_from_folders(workspace_folders::Vector{String}; dynamic=DynamicOff, symbolcache_download=false, symbolcache_upstream=DEFAULT_SYMBOLCACHE_UPSTREAM)

Create a new JuliaWorkspace and populate it by recursively reading every folder in workspace_folders from disc. This is the most convenient entry point for analysing a project that lives on the local file system.

Keyword arguments

• dynamic::DynamicMode: Whether and how to run the out-of-process dynamic feature. See DynamicMode. Defaults to DynamicOff.
• symbolcache_download::Bool: If true, allow downloading precomputed package symbol caches from symbolcache_upstream instead of indexing locally.
• symbolcache_upstream::String: Upstream URL for symbol-cache downloads. Defaults to DEFAULT_SYMBOLCACHE_UPSTREAM.

Returns

• A JuliaWorkspace containing all files found under the given folders.

add_folder_from_disc!(jw::JuliaWorkspace, path; ignore_io_errors=false)

Recursively read all relevant files under the local folder path from disc and add them to the workspace jw. Julia sources, Project.toml/Manifest.toml, and configuration files are picked up. The whole batch is added before a single reconciliation step runs, so this is more efficient than calling add_file! per file.

If ignore_io_errors is true, files that cannot be read are skipped instead of raising an error.

add_file_from_disc!(jw::JuliaWorkspace, path)

Read the file at the local path from disc and add it to the workspace jw as a new file (see add_file!). The file content is read eagerly and the file's language is inferred from its extension.

Throws if a file with the same URI is already part of the workspace.

update_file_from_disc!(jw::JuliaWorkspace, path)

Re-read the file at the local path from disc and update its content in the workspace jw (see update_file!). Use this to refresh a file whose on-disc content changed outside of the workspace.

Throws if no file with the corresponding URI is part of the workspace.

add_file!(jw::JuliaWorkspace, file::TextFile)

Add a file to the workspace. If the file already exists as a regular file, it will throw an error. If the URI is currently tracked as an indirect file (reached via include from another file), it is promoted to a regular file and any existing lazy indirect content is cleared.

remove_file!(jw::JuliaWorkspace, uri::URI)

Remove a file from the workspace. If the file does not exist, it will throw an error.

remove_all_children!(jw::JuliaWorkspace, uri::URI)

Remove all children of a folder from the workspace.

set_active_project!(jw::JuliaWorkspace, uri_or_nothing::Union{URI,Nothing})

Set the active project for the workspace. The active project serves as the fallback environment for files that are not inside any project folder and also as the fallback test project when determining test environments.

Pass nothing to clear the active project.

When the active project is outside the workspace folders, its Project.toml and Manifest.toml will be loaded lazily via the indirect file mechanism, which triggers the indirect_file_watch_callback so the host (e.g. the LS) can register file watchers for them.

set_indirect_file_content!(jw::JuliaWorkspace, uri::URI, file::Union{TextFile,Nothing})

Update the content of an indirect file (a file referenced via include from a regular file but not itself added as a regular file). Pass nothing if the file no longer exists on disc. This is intended to be called by the LS in response to file-watcher notifications.

clear_indirect_file!(jw::JuliaWorkspace, uri::URI)

Drop tracking for an indirect file. Any cached lazy content is removed; if the include graph still references the URI, the next query will re-trigger the lazy disc read and the watcher callback.

get_text_files(jw::JuliaWorkspace)

Get all text files from the workspace.

Returns

• A set of URIs.

get_julia_files(jw::JuliaWorkspace)

Get all Julia files from the workspace.

Returns

• A set of URIs.

has_file(jw, uri)

Check if a file exists in the workspace.

get_text_file(jw::JuliaWorkspace, uri::URI)

Get a text file from the workspace. If the file does not exist, it will throw an error.

Returns

• A TextFile struct.

get_indirect_files(jw::JuliaWorkspace)

Return the set of URIs currently tracked as indirect files — i.e. files reached only via include(...) traversal that are not regular workspace files.

is_indirect_file(jw::JuliaWorkspace, uri::URI)

Return true if uri is currently part of the include graph as an indirect file (i.e. reached only via include and not added as a regular file).

position_at(source_text::SourceText, x::Int) -> Position

Convert the 1-based byte offset x within source_text into a Position (a 1-based line number and a 1-based UTF-8 byte column).

get_julia_syntax_tree(jw::JuliaWorkspace, uri::URI)

Get the syntax tree of a Julia file from the workspace.

Returns

• The tuple (tree, diagnostics), where tree is the syntax tree and diagnostics is a vector of Diagnostic structs.

get_toml_syntax_tree(jw::JuliaWorkspace, uri::URI)

Get the syntax tree of a TOML file from the workspace.

get_diagnostic(jw::JuliaWorkspace, uri::URI)

Get the diagnostics of a file from the workspace.

Returns

• A vector of Diagnostic structs.

get_diagnostics(jw::JuliaWorkspace)

Get all diagnostics from the workspace.

Returns

• A vector of Diagnostic structs.

get_diagnostics_blocking(jw::JuliaWorkspace; cancel_token::Union{CancellationTokens.CancellationToken,Nothing}=nothing)

Wait for the dynamic environment to finish loading, then return all diagnostics. This is useful for CLI tools that want the full, accurate set of diagnostics. If cancel_token is provided, throws CancellationTokens.OperationCanceledException when the token is cancelled.

get_packages(jw::JuliaWorkspace)

Get all packages from the workspace.

Returns

• A set of URIs.

get_projects(jw::JuliaWorkspace)

Get all projects from the workspace.

Returns

• A set of URIs.

get_test_items(jw::JuliaWorkspace, uri::URI)

Get the test items that belong to a given URI of a workspace.

Returns

• an instance of the struct TestDetails

get_test_items(jw::JuliaWorkspace)

Get all test items of the workspace jw.

Returns

• an instance of the struct TestDetails

get_test_env(jw::JuliaWorkspace, uri::URI)

Get the test environment that belongs to the given uri of the workspace jw.

Returns

• an instance of the struct JuliaTestEnv

is_ready(jw::JuliaWorkspace)

Check whether the workspace's dynamic environment loading has completed. Returns true if no dynamic feature is configured, or if the environment has finished loading and no tasks are pending.

wait_until_ready(jw::JuliaWorkspace; cancel_token::Union{CancellationTokens.CancellationToken,Nothing}=nothing)

Block until the workspace's dynamic environment loading has completed. If cancel_token is provided, throws CancellationTokens.OperationCanceledException when the token is cancelled.

get_update_channel(jw::JuliaWorkspace)

Return the Channel{Symbol} that receives notifications when dynamic data becomes available. Returns nothing if no dynamic feature is configured. Consumers can take! or wait on this channel to be notified of updates.

get_hover_text(jw::JuliaWorkspace, uri::URI, index::Integer)

Return a Markdown documentation string for the expression at index (1-based Julia string index) in the file identified by uri, or nothing if there is no hover information for that position.

get_doc_from_word(jw::JuliaWorkspace, word::AbstractString)

Search all loaded symbol stores for symbols matching word (fuzzy match) and return their documentation as a single markdown string. Returns "No results found." when no matches are found.

get_completions(jw::JuliaWorkspace, uri::URI, index::Integer, completion_mode::Symbol=:import)

Return a CompletionResult with completion items at the given index (1-based Julia string index) in the file identified by uri.

completion_mode may be :import (default) or :qualify to control whether additional using statements are inserted for out-of-scope symbols.

is_completion_match(s, prefix, cutoff=3)

Returns true if s starts with prefix or has a sufficiently high fuzzy score.

get_expr1(x, offset, pos=0)

Walk a CSTParser EXPR tree and return the leaf EXPR whose span covers offset (0-based byte offset). Returns nothing if no match is found.

completion_type(b) -> Union{Symbol,Missing}

Infer the type of a binding b as a Symbol suitable for display in hover and completion results, stripping a leading Core. qualifier. Returns missing when the type cannot be determined or b is not a StaticLint.Binding.

get_typed_definition(b) -> Union{String,Symbol,Missing}

Return a human-readable definition string for the binding b with its inferred type annotation inserted where possible (for example x::Int). Falls back to completion_type when b is not a StaticLint.Binding.

get_definitions(jw::JuliaWorkspace, uri::URI, index::Integer)

Return a vector of DefinitionResult for the symbol at index (1-based Julia string index) in the file identified by uri.

get_references(jw::JuliaWorkspace, uri::URI, index::Integer)

Return a vector of ReferenceResult for all references to the symbol at index (1-based Julia string index) in the file identified by uri.

get_rename_edits(jw::JuliaWorkspace, uri::URI, index::Integer, new_name::String)

Return a vector of RenameEdit for renaming the symbol at index (1-based Julia string index) in uri to new_name.

get_highlights(jw::JuliaWorkspace, uri::URI, index::Integer)

Return a vector of HighlightResult for highlighted occurrences of the symbol at index (1-based Julia string index) in the same file.

can_rename(jw::JuliaWorkspace, uri::URI, index::Integer)

Check whether the symbol at index (1-based Julia string index) can be renamed. Returns a named tuple (; start::Position, stop::Position) describing the range of the renamable symbol (both positions use 1-based line and column), or nothing if the symbol cannot be renamed.

get_signature_help(jw::JuliaWorkspace, uri::URI, index::Integer)

Return a SignatureResult with signature information for the function call at index (1-based Julia string index) in the file identified by uri.

get_document_symbols(jw::JuliaWorkspace, uri::URI)

Return a vector of DocumentSymbolResult representing the document outline for the file identified by uri. Each result has start_offset and end_offset as 0-based byte offsets, plus name, kind (LSP SymbolKind integer), and children.

get_workspace_symbols(jw::JuliaWorkspace, query::String)

Search all files for top-level bindings whose name starts with query. Returns a vector of WorkspaceSymbolResult.

get_selection_ranges(jw::JuliaWorkspace, uri::URI, indices::Vector{Int})

For each 1-based string index in indices, compute a nested selection range. Returns a vector of Union{Nothing, SelectionRangeResult}.

get_current_block_range(jw::JuliaWorkspace, uri::URI, index::Integer)

Find the current top-level block at index (1-based Julia string index). Returns a BlockRangeResult with 0-based byte offsets, or nothing.

get_module_at(jw::JuliaWorkspace, uri::URI, index::Integer)

Return the fully qualified module name at index (1-based Julia string index), or "Main" if no module scope is found.

get_document_links(jw::JuliaWorkspace, uri::URI) → Vector{DocumentLinkResult}

Return clickable document links (string literals that resolve to files). Offsets in results are 0-based byte offsets for direct use with CST spans.

get_inlay_hints(jw::JuliaWorkspace, uri::URI, start_index::Integer, end_index::Integer, config::InlayHintConfig) → Vector{InlayHintResult}

Return inlay hints (parameter names, variable types) for the given range. start_index and end_index are 1-based Julia string indices.

get_code_actions(jw::JuliaWorkspace, uri::URI, index::Integer, diagnostic_messages::Vector{String}, workspace_folders::Vector{String}=String[]) → Vector{CodeActionInfo}

Return the list of applicable code actions at index (1-based Julia string index). diagnostic_messages should contain the text of any diagnostics overlapping the cursor. workspace_folders is an optional list of workspace folder paths (used by license actions).

execute_code_action(jw::JuliaWorkspace, action_id::String, uri::URI, index::Integer, workspace_folders::Vector{String}=String[]) → Vector{WorkspaceFileEdit}

Execute the code action identified by action_id at index (1-based Julia string index). Returns a vector of workspace file edits. Each edit contains a URI and a vector of TextEditResults with 0-based byte offsets.

get_format_edits(jw::JuliaWorkspace, uri::URI) → WorkspaceFileEdit

Format the entire document uri and return a WorkspaceFileEdit describing the edits required to apply the formatting. The formatting style and options are taken from the nearest juliaformat.toml configuration file (see derived_format_configuration); when no configuration is found the minimal JuliaFormatter style is used. A style of "runic" routes formatting through Runic.jl.

If the document is already correctly formatted the returned edit list is empty. Throws an error if formatting fails (for example because of a syntax error).

get_format_edits(jw::JuliaWorkspace, uri::URI, start_line::Integer, stop_line::Integer) → WorkspaceFileEdit

Format the whole-line range [start_line, stop_line] (1-based, inclusive) of the document uri and return a WorkspaceFileEdit. Configuration is resolved the same way as for full-document formatting.

If the targeted range is already correctly formatted the returned edit list is empty. Throws an error if formatting fails.

get_legacy_cst(jw::JuliaWorkspace, uri::URI)

Get the CSTParser legacy syntax tree for a Julia file.

Returns

• An EXPR (CSTParser expression tree).

get_roots_for_uri(jw::JuliaWorkspace, uri::URI)

Get all root files whose include tree contains the given URI.

Returns

• A Set{URI} of root file URIs.

get_best_root_for_uri(jw::JuliaWorkspace, uri::URI)

Get the single best root file for a given URI. Prefers package src/ roots over test roots when a file is reachable from multiple roots. Returns nothing if the URI is not part of any root's include tree.

Returns

• A URI or nothing.

get_static_lint_data(jw::JuliaWorkspace, uri::URI)

Get the static lint analysis data for the best root containing uri. This includes the metadata dictionary, environment, and workspace packages needed by LS request handlers.

Returns

• A named tuple (meta_dict, env, workspace_packages, root) or nothing if no root contains the URI.
  • meta_dict::Dict{UInt64, StaticLint.Meta} — maps EXPR object_id → metadata
  • env::StaticLint.ExternalEnv — resolved environment (symbols, methods, deps)
  • workspace_packages::Dict{String,Any} — deved packages available for import
  • root::URI — the root file that was used

get_environment(jw::JuliaWorkspace, uri::URI)

Get the resolved environment for the best root containing uri.

Returns

• A StaticLint.ExternalEnv or nothing.

get_expr_location(jw::JuliaWorkspace, x::CSTParser.EXPR)

Given an EXPR node from a CST obtained via get_legacy_cst, return the URI and byte offset of x within its owning file.

Walks x.parent pointers up to the file-root EXPR, computes the byte offset by descending through the tree, then looks up the root's objectid in a Salsa-memoized expr→URI mapping.

Returns

• (uri::URI, offset::Int) if the owning file is found
• nothing if the EXPR cannot be mapped to a file

get_files(jw::JuliaWorkspace)

Get all files from the workspace.

Returns

• A set of URIs.

update_file!(jw::JuliaWorkspace, file::TextFile)

Update a file in the workspace. If the file does not exist, it will throw an error.

unescapeuri(str)

Percent-decode a string according to the URI escaping rules.

escapeuri(x)

Apply URI percent-encoding to escape special characters in x.

_bytes(s::String)

Get a Vector{UInt8}, a vector of bytes of a string.

escapepath(path)

Escape the path portion of a URI, given the string path containing embedded / characters which separate the path segments.