Types

struct JuliaWorkspace

The central handle representing a Julia workspace. It wraps a Salsa runtime that holds all mutable inputs (the set of files, the active project, and dynamic-feature results) and memoizes every derived query computed from them. A workspace is manipulated through the mutation functions (add_file!, update_file!, remove_file!, …) and inspected through the query functions (get_diagnostics, get_julia_syntax_tree, …).

Constructor

JuliaWorkspace(; dynamic=DynamicOff, store_path=nothing,
                 symbolcache_download=false,
                 symbolcache_upstream=DEFAULT_SYMBOLCACHE_UPSTREAM,
                 indirect_file_watch_callback=nothing,
                 progress_callback=nothing)

Create an empty workspace. To build one directly from folders on disc, use workspace_from_folders instead.

Keyword arguments

• dynamic::DynamicMode: Whether and how to run the out-of-process dynamic feature that indexes environments. See DynamicMode.
• store_path::Union{Nothing,String}: Directory used to cache package symbol data (.jstore files). Defaults to a managed scratch space.
• symbolcache_download::Bool: If true, allow downloading precomputed symbol caches from symbolcache_upstream rather than indexing locally.
• symbolcache_upstream::String: Upstream URL for symbol-cache downloads. Defaults to DEFAULT_SYMBOLCACHE_UPSTREAM.
• indirect_file_watch_callback::Union{Nothing,Function}: Invoked once with a URI the first time an indirect file (a file pulled in via include but not explicitly added) is requested. Intended for a host to register a file watcher.
• progress_callback::Union{Nothing,Function}: Invoked as (key::String, message::String, percentage::Int) with progress updates while the dynamic feature indexes environments. key identifies the operation (each concurrently running operation — downloading caches for a project, indexing a project, loading caches — is its own progress bar with the full 0–100 range); a report with percentage >= 100 ends that operation's bar.
• max_concurrent_djps::Int: Maximum number of concurrently working dynamic child processes (0 disables the limit). Defaults to 4.
• max_failure_attempts::Int: How many terminal failures a project may accumulate before the dynamic feature stops launching child processes for it (0 or less disables the bound). Defaults to DEFAULT_MAX_FAILURE_ATTEMPTS. See retry_failed_dynamic_projects! to clear the budget.
• djp_request_timeout_seconds::Int: How long a child process may take to answer one indexing request before the work item is failed (0 or less means no deadline). Defaults to DEFAULT_DJP_REQUEST_TIMEOUT_SECONDS.
• resolve_workspace_environments::Bool: When false, no standalone package projects or test environments are created; only real project environments are watched. Defaults to true.

struct TextFile

A text file, consisting of its URI and content.

• uri::URI: The URI of the file.
• content::SourceText: The content of the file as SourceText.

struct SourceText

A source text, consisting of its content, line indices, and language ID.

• content::String
• line_indices::Vector{Int}
• language_id::String

struct Diagnostic

A diagnostic struct, consisting of range, severity, message, and source.

• range::UnitRange{Int64}
• severity::Symbol
• message::String
• uri::Union{Nothing,URI}
• tags::Vector{Symbol}
• source::String
• code::Union{Nothing,Symbol}: stable rule id, see LINT_RULES in lint_rules.jl. This is the identifier users name in JuliaLint.toml, and what is reported as the rule id in the CLI's JSON and SARIF output.

@enum DynamicMode DynamicOff DynamicIndexingOnly DynamicPersistent

Controls how a JuliaWorkspace uses the out-of-process dynamic feature that indexes package environments and resolves symbol information.

• DynamicOff: No dynamic feature is started. The workspace only relies on statically available information (parsed sources, Project.toml/Manifest.toml contents, and any locally cached symbol data). Environment-dependent diagnostics are suppressed because no environment can be resolved.
• DynamicIndexingOnly: Child Julia processes are spawned to index project and test environments (populating the on-disc symbol cache), but they are torn down once indexing completes. Use this for one-shot tools such as CI runs.
• DynamicPersistent: Like DynamicIndexingOnly, but the child processes are kept alive so the workspace can react to ongoing changes. Use this for long-running hosts such as a language server.

See also is_ready, wait_until_ready.

DEFAULT_SYMBOLCACHE_UPSTREAM

Default upstream URL from which precomputed package symbol caches are downloaded when symbolcache_download is enabled on a JuliaWorkspace. Downloading a cached index avoids having to index a package locally.

DEFAULT_MAX_FAILURE_ATTEMPTS

Terminal failures tolerated per work-item identity before the reactor stops launching children for it. Two, so the first genuine fix to a broken Project.toml still gets a fresh attempt, while a deterministically unresolvable project (an unsatisfiable test env, an unregistered dependency) stops costing a child process per edit.

DEFAULT_DJP_REQUEST_TIMEOUT_SECONDS

How long a child indexing process may take to answer one request. Generous — indexing a large environment from cold legitimately takes minutes — but finite, because an unbounded wait turns a wedged child into a wedged host: the work item stays pending forever and is_ready never becomes true.

struct CompletionResult

The full result of a completion request.

• is_incomplete::Bool: true if the list is truncated and should be recomputed as the user keeps typing.
• items::Vector{CompletionResultItem}: The completion candidates.

struct CompletionResultItem

A single completion candidate, expressed without any LSP types.

• label::String: Text shown in the completion list.
• kind::Int: A CompletionKinds value.
• detail, detail_label, detail_description: Optional detail strings.
• documentation::Union{Nothing,String}: Optional markdown documentation.
• sort_text, filter_text: Optional overrides for sorting/filtering.
• insert_text_format::Int: An InsertFormats value.
• text_edit::CompletionEdit: The primary edit applied on acceptance.
• additional_edits::Vector{CompletionEdit}: Extra edits (for example new imports).
• data::Union{Nothing,String}: Opaque payload carried through to resolution.

struct CompletionEdit

A text edit attached to a completion item, expressed with Position values rather than LSP types.

• start::Position: Start of the range to replace.
• stop::Position: End of the range to replace.
• new_text::String: Replacement text.
• uri::Union{Nothing,URI}: Target file, or nothing for the current file.

module CompletionKinds

Named constants for completion item kinds, mirroring the LSP CompletionItemKind enumeration. Used as the kind field of CompletionResultItem.

module InsertFormats

Named constants for completion insert-text formats: PlainText (literal text) and Snippet (LSP snippet syntax with placeholders). Used as the insert_text_format field of CompletionResultItem.

struct DefinitionResult

The location a go-to-definition request resolves to.

• uri::URI: File containing the definition.
• start::Position: Start of the definition's name range.
• stop::Position: End of the definition's name range.

struct ReferenceResult

A single location where a symbol is referenced (used by find-references).

• uri::URI: File containing the reference.
• start::Position: Start of the reference range.
• stop::Position: End of the reference range.

struct RenameEdit

A single text edit that renames an occurrence of a symbol.

• uri::URI: File the edit applies to.
• start::Position: Start of the range to replace.
• stop::Position: End of the range to replace.
• new_text::String: Replacement text.

struct HighlightResult

A document-highlight range for an occurrence of a symbol.

• start::Position: Start of the occurrence.
• stop::Position: End of the occurrence.
• kind::Symbol: :read or :write, indicating whether the occurrence reads or writes the symbol.

struct SignatureResult

The result of a signature-help request at a call site.

• signatures::Vector{SignatureInfo}: Candidate signatures for the call.
• active_signature::Int: Index of the signature to highlight.
• active_parameter::Int: Index of the parameter to highlight.

struct SignatureInfo

Describes a single callable signature in a signature-help result.

• label::String: The full signature rendered as text.
• documentation::String: Documentation for the signature.
• parameters::Vector{ParameterInfo}: The signature's parameters in order.

struct ParameterInfo

Describes a single parameter of a function signature in signature help.

• label::Union{String,Tuple{Int,Int}}: The parameter as it appears in the signature — either the exact substring, or a [start, end) UTF-16 offset range into the signature label (LSP ParameterInformation.label).
• documentation::Union{String,Nothing}: Optional documentation for the parameter.

struct DocumentSymbolResult

A node in the document-outline tree (document symbols).

• name::String: Display name of the symbol.
• kind::Int: LSP SymbolKind integer.
• start::Position: Start of the symbol's range.
• stop::Position: End of the symbol's range.
• children::Vector{DocumentSymbolResult}: Nested symbols.

struct WorkspaceSymbolResult

A single match returned by a workspace-wide symbol search.

• name::String: Display name of the symbol.
• kind::Int: LSP SymbolKind integer.
• uri::URI: File containing the symbol.
• start::Position: Start of the symbol's range.
• stop::Position: End of the symbol's range.

struct SelectionRangeResult

A nested selection range used to grow/shrink an editor selection. Each result points to its enclosing range via parent, forming a chain from the innermost to the outermost syntactic construct.

• start::Position: Start of this selection range.
• stop::Position: End of this selection range.
• parent::Union{Nothing,SelectionRangeResult}: The enclosing range, or nothing for the outermost range.

struct BlockRangeResult

Describes the syntactic block surrounding a position, distinguishing the full block extent from the sub-range to highlight.

• block_start::Position: Start of the enclosing block.
• highlight_start::Position: Start of the range to highlight.
• highlight_stop::Position: End of the range to highlight.
• block_stop::Position: End of the enclosing block.

struct DocumentLinkResult

A clickable link discovered in a source file (for example a path in a string literal passed to include).

• start::Position: Start of the link's text range.
• stop::Position: End of the link's text range.
• target_uri::URI: The link target.

struct InlayHintResult

A single inlay hint rendered inline in the editor.

• position::Position: Where the hint is anchored.
• label::String: Hint text.
• kind::Symbol: :parameter (a parameter name) or :type (an inferred type).
• padding_left::Bool: Whether to render padding before the hint.
• padding_right::Bool: Whether to render padding after the hint.

struct InlayHintConfig

Configuration controlling which inlay hints are produced.

• enabled::Bool: Master switch for inlay hints.
• variable_types::Bool: Whether to show inferred variable type hints.
• parameter_names::Symbol: Which parameter-name hints to show: :all, :literals, or :nothing.

struct CodeActionInfo

Describes a code action that is available at a given location, without yet computing its edits. Pass its id to execute_code_action to obtain the concrete edits.

• id::String: Stable identifier of the action.
• title::String: Human-readable title shown to the user.
• kind::Symbol: One of :quickfix, :refactor, :refactor_rewrite, :source_organize_imports, or :empty.
• is_preferred::Bool: Whether this action should be offered as the preferred fix.

struct TextEditResult

A single text replacement produced by a code action.

• start::Position: Start of the range to replace.
• stop::Position: End of the range to replace.
• new_text::String: Replacement text.

struct WorkspaceFileEdit

A group of TextEditResult edits that apply to a single file, as part of a workspace-wide edit produced by a code action.

• uri::URI: File the edits apply to.
• edits::Vector{TextEditResult}: Edits for that file.

struct LintRule

A user-facing lint rule. Fully declarative: everything the pipeline needs to know about a rule — where its findings come from, how each preset classifies it, its tags and documentation link, whether it depends on the environment being ready — is a field here rather than a side table.

• id::Symbol: The rule id, as written in JuliaLint.toml and reported on Diagnostic.code.
• tier::LintTier: The inputs the rule needs, see LintTier.
• severity_minimal/severity_default/severity_strict::Symbol: The rule's severity in each preset (:off, :hint, :information, :warning, :error). Every rule classifies all three presets, so the "every preset classifies every rule" invariant holds by construction. Prefer :off in minimal and default for a new rule: a rule that switches itself on for every project on upgrade breaks their CI.
• tags::Vector{Symbol}: LSP diagnostic tags, e.g. [:unnecessary]. A property of the rule, not of the configured severity: an unused binding stays "unnecessary" (greyed out by the editor) whether the user reports it as a hint or an error.
• doc_link::Union{Nothing,URI}: Documentation link surfaced as the diagnostic's code description.
• env_dependent::Bool: Whether findings depend on package symbols being indexed; such rules are suppressed until a file's environment is ready (see _is_env_dependent_finding).
• option_keys::Vector{Symbol}: Extra keys accepted alongside severity when the rule is configured as a table.
• codes::Vector{StaticLint.LintCodes}: The StaticLint codes this rule covers; empty for rules backed by another analysis.
• category::Union{Nothing,Symbol}: The StaticLint.LintOptions field that gates the check emitting these codes, or nothing when the check always runs (those rules are filtered when diagnostics are emitted instead).

@enum LintTier

The inputs a lint rule needs, from least to most:

• TierSyntax: the syntax tree of a single file, nothing else.
• TierSemantic: a single file plus semantic information (bindings, scopes, package symbols — today the StaticLint semantic pass).
• TierProject: project or environment information (Project.toml, Manifest, configuration files, environment resolution).
• TierWorkspace: cross-file workspace information (include graph, the full set of configuration files).

The tier determines which derived query produces a rule's findings and which prerequisites gate it; it is not user-visible.

struct EffectiveLintConfig

The lint configuration in force for one file, after resolving the preset baseline, the config file's [rules] deltas and any applicable [[override]] blocks.

• severities::Dict{Symbol,Symbol}: rule id → severity, :off when disabled.
• options::Dict{Symbol,Dict{Symbol,Any}}: rule id → that rule's extra options.
• selected::Bool: whether the file is linted at all (include/exclude).

struct EffectiveFormatConfig

The formatting configuration in force for one file, after resolving the style preset, the [options] deltas and any applicable [[override]] blocks.

• style::String: The style preset.
• options::Dict{Symbol,Any}: JuliaFormatter.Options overrides.
• selected::Bool: Whether the file is formatted at all (include/exclude).

struct GlobPattern

A compiled gitignore-style glob. * matches within a path segment, ** spans segments, ? matches a single non-separator character, and [...] is a character class. A leading / anchors the pattern to the config file's directory; a pattern containing no / matches at any depth. A trailing / makes the pattern match everything below that directory.

The source pattern is what participates in equality, so that configs compare and hash by their written form (the compiled regex is derived from it).

struct PathFilter

The include/exclude glob pair of a config file. An empty include list selects everything; exclude always wins over include.

struct Position

A position in a source file expressed as a 1-based line number and a 1-based UTF-8 byte column within that line.

• line::Int: 1-based line number.
• column::Int: 1-based UTF-8 byte offset from the start of the line.

struct JuliaPackage

Details of a Julia package.

• project_file_uri::URI
• name::String
• uuid::UUID
• content_hash::UInt64

struct JuliaTestEnv

Details of a Julia test environment.

• package_name::String
• package_uri::Union{URI,Nothing}
• project_uri::Union{URI,Nothing}
• env_content_hash::Union{UInt,Nothing}

struct JuliaProject

Details of a Julia project.

• project_file_uri::URI
• manifest_file_uri::URI
• julia_version::Union{Nothing,VersionNumber}
• content_hash::UInt64
• deved_packages::Dict{String,JuliaProjectEntryDevedPackage}
• regular_packages::Dict{String,JuliaProjectEntryRegularPackage}
• stdlib_packages::Dict{String,JuliaProjectEntryStdlibPackage}

struct JuliaProjectEntryDevedPackage

Details of a Julia project entry for a developed package.

• name::String
• uuid::UUID
• uri::URI
• version::String

struct JuliaProjectEntryRegularPackage

Details of a Julia project entry for a regular package.

• name::String
• uuid::UUID
• version::String
• git_tree_sha1::String

struct JuliaProjectEntryStdlibPackage

Details of a Julia project entry for a standard library package.

• name::String
• uuid::UUID
• version::Union{Nothing,String}

struct NotebookFile

A notebook file, consisting of its URI and cells.

• uri::URI: The URI of the file.
• cells::Vector{SourceText}: The cells of the notebook as a vector of SourceText.

struct TestSetupDetail

Details of a test setup.

• uri::URI
• name::Symbol
• kind::Symbol
• code::String
• range::UnitRange{Int}
• code_range::UnitRange{Int}

struct TestDetails

Details of a test.

• testitems::Vector{TestItemDetail}
• testsetups::Vector{TestSetupDetail}
• testerrors::Vector{TestErrorDetail}

struct TestItemDetail

Details of a test item.

• uri::URI
• id::String
• name::String
• code::String
• range::UnitRange{Int}
• code_range::UnitRange{Int}
• option_default_imports::Bool
• option_tags::Vector{Symbol}
• option_setup::Vector{Symbol}
• option_skip::Union{Bool,String} — a literal true/false, or the source text of an expression that the test process evaluates just before the test item would run.

struct TestErrorDetail

Details of a test error.

• uri::URI
• id::String
• name::Union{Nothing,String}
• message::String
• range::UnitRange{Int}

struct URI

Details of a Unified Resource Identifier.

• scheme::Union{Nothing, String}
• authority::Union{Nothing, String}
• path::String
• query::Union{Nothing, String}
• fragment::Union{Nothing, String}