Struct DocumentStore 

pub struct DocumentStore { /* private fields */ }

Implementations

impl DocumentStore

pub fn new() -> Self

pub fn set_session_cache_dir(&self, dir: PathBuf)

Set the directory used to persist stub-parse and analysis results across server restarts. Must be called before the first analysis_session use; subsequent calls are silently ignored (OnceLock semantics).

pub fn set_autoload_uris(&self, uris: Vec<Url>)

Register URIs discovered from composer.json autoload.files entries. These PHP files define global helper functions (e.g. tap() in Laravel) that are not class-resolvable via PSR-4. Clears analysis_cache so the next per-file analysis pre-ingests them into the AnalysisSession before running mir’s FileAnalyzer.

pub fn analysis_session(&self, php_version: PhpVersion) -> Arc<AnalysisSession>

Get or build the AnalysisSession for the given PHP version. Rebuilds when the version changes (e.g. user flipped config). The session owns its own salsa db and AnalysisCache; lazy-loads vendor files via the shared PSR-4 map.

pub fn workspace_php_version(&self) -> PhpVersion

Current PHP version tracked by the workspace input.

pub fn psr4_arc(&self) -> Arc<ArcSwap<Psr4Map>>

Return the Arc<ArcSwap<Psr4Map>> so callers can share it. Backend clones this arc at construction time so writes (e.g. loading composer.json on initialized) are immediately visible to lazy_load_psr4_imports without extra plumbing.

pub fn mirror_text(&self, uri: &Url, text: &str)

Mirror a file’s current text into the salsa layer. Creates the FileText input on first sight, otherwise updates text on the existing input (bumping the salsa revision so downstream queries invalidate).

pub fn mirror_text_arc(&self, uri: &Url, text_arc: Arc<str>)

Like [mirror_text] but takes an already-allocated Arc<str>.

Callers that already hold an Arc<str> (e.g. ingest_from_doc reusing ParsedDoc::source_arc()) use this to avoid a second allocation and to ensure text_cache and parsed_cache hold the same Arc pointer — enabling Arc::ptr_eq validation in get_parsed_cached.

pub fn seed_cached_index(&self, uri: &Url, index: Arc<FileIndex>) -> bool

Phase K2: pre-seed a FileIndex loaded from the on-disk cache onto the FileText input for uri. The next file_index call for that file returns the cached index directly, skipping parse + extract.

Must be called before any file_index(db, sf) call for this file — otherwise salsa has already memoized the fresh-parse result and setting cached_index now would only bump the revision without using the cache. In practice the workspace-scan path seeds immediately after mirror_text and before any query runs.

Returns false when uri was not mirrored (caller should mirror first); returns true on success.

pub fn with_host<R>(&self, f: impl FnOnce(&AnalysisHost) -> R) -> R

Run f with a borrow of the AnalysisHost. Used by tests and by the upcoming *_salsa accessors to query the salsa layer.

pub fn evict_token_cache(&self, uri: &Url)

Evict the semantic-tokens cache for uri. Called by Backend when a file is closed; diff-based tokens computed against the old revision are no longer meaningful.

pub fn ingest(&self, uri: Url, text: &str)

Register a file in the salsa layer without marking it open.

Salsa’s parsed_doc query parses lazily on first read; diagnostics are populated by did_open when the editor actually opens the file.

pub fn ingest_from_doc(&self, uri: Url, doc: &ParsedDoc)

Index a file using an already-parsed ParsedDoc, avoiding a second parse.

Prefer this over [ingest] when the caller already has a ParsedDoc (e.g. after running DefinitionCollector during workspace scan). Reuses the Arc<str> already owned by doc so that text_cache and SourceFile::text share the same pointer — enabling the Arc::ptr_eq fast path in get_parsed_cached on the first subsequent salsa query, without an extra Arc::from(source) allocation.

pub fn remove(&self, uri: &Url)

pub fn get_doc_salsa(&self, uri: &Url) -> Option<Arc<ParsedDoc>>

Salsa-backed parsed document.

Salsa-backed parsed document for any mirrored file (open or background-indexed). Returns None only when the file is not known to the store. Callers that want “only if open” should gate on Backend::open_files at the call site (see Backend::get_doc).

pub fn get_index_salsa(&self, uri: &Url) -> Option<Arc<FileIndex>>

Salsa-backed compact symbol index.

pub fn get_symbol_map_salsa(&self, uri: &Url) -> Option<Arc<SymbolMap>>

Salsa-backed pre-computed symbol map (name → Vec). Memoized per revision: stable files serve from cache in O(1).

pub fn other_symbol_maps( &self, uri: &Url, open_urls: &[Url], ) -> Vec<(Url, Arc<SymbolMap>)>

Pre-computed symbol maps for every entry in open_urls except uri.

pub fn sync_workspace_files(&self)

Refresh workspace.files to mirror the current active file set.

Skips all work when workspace_files_dirty is false (the common case after the workspace scan completes — file-set changes are rare).

pub fn mark_workspace_files_dirty(&self)

Mark the workspace file set as dirty so the next sync_workspace_files call re-runs the collect/sort/compare path. Exposed for benchmarks that need to measure the dirty-path cost in isolation.

pub fn set_php_version(&self, version: PhpVersion)

Update the PHP version tracked by the workspace. Salsa will invalidate all semantic_issues queries so diagnostics are re-evaluated. Skips the setter when the version hasn’t changed to avoid spurious query invalidation.

pub fn session_references_to( &self, symbol: &Name, ) -> Vec<(Arc<str>, u32, u32, u32)>

Session-backed workspace reference lookup. Returns (file, line, col) locations for every occurrence of symbol in the files that the AnalysisSession has ingested so far. The session’s reference index is built incrementally during ingest_file, so refs for files the session hasn’t seen yet (background-indexed but never opened) won’t appear here — those are covered by the AST-walker fallback in the references handler.

Returns LSP-style 0-based line/column.

pub fn get_workspace_index_salsa(&self) -> Arc<WorkspaceIndexData>

Phase J: salsa-memoized aggregate workspace index.

Returns the shared Arc<WorkspaceIndexData> with flat (Url, Arc<FileIndex>) list plus pre-built classes_by_name and subtypes_of reverse maps. Used by workspace_symbols, prepare_type_hierarchy, supertypes_of, subtypes_of, and find_implementations so they don’t each rebuild the aggregate per request. Invalidates automatically when any file’s file_index changes.

pub fn warm_reference_index(&self)

No-op after mir 0.22 migration. The session manages its own warm-up via ingest_file / analyze_dependents_of; there’s nothing for us to pre-warm here.

pub fn source_text(&self, uri: &Url) -> Option<Arc<str>>

Return the raw source text for uri if it has been mirrored into the salsa workspace. Used by the references handler to pre-filter session results by checking whether a file mentions the owning class name.

pub fn ensure_all_files_ingested(&self)

Run Pass 1 + Pass 2 analysis on every mirrored workspace file so that type-aware queries (e.g. session.references_to) see the full workspace.

Reference locations are only recorded during Pass 2 (FileAnalyzer::analyze). ingest_file alone (Pass 1) is not sufficient. Only needed for cross-file queries like textDocument/references that rely on the reference index. The session’s internal cache makes re-analysis of unchanged files cheap.

pub fn store_token_cache( &self, uri: &Url, result_id: String, tokens: Arc<Vec<SemanticToken>>, )

Cache the semantic tokens computed for a delta response. result_id is an opaque string (a hash of the token data) returned to the client.

pub fn get_token_cache( &self, uri: &Url, result_id: &str, ) -> Option<Arc<Vec<SemanticToken>>>

Return the cached tokens if result_id matches the stored one.

pub fn get_semantic_issues_salsa(&self, uri: &Url) -> Option<Arc<[Issue]>>

Raw semantic issues for a file, computed via mir’s session-based FileAnalyzer. The session lazy-loads dependencies via PSR-4 so the LSP no longer needs to mirror vendor up-front. Callers apply their own DiagnosticsConfig filter via crate::semantic_diagnostics::issues_to_diagnostics.

pub fn cached_type_map( &self, uri: &Url, doc: &ParsedDoc, meta: Option<&PhpStormMeta>, ) -> Arc<TypeMap>

Run (or reuse) mir’s per-file body analysis, retaining the full mir_analyzer::FileAnalysis — issues and resolved symbols — across requests. Diagnostics read .issues; position features call .symbol_at(offset) for the resolved type at a cursor.

Cache hit when the entry’s captured source Arc is pointer-equal to the file’s current doc.source_arc(). A miss recomputes and overwrites, so the entry self-evicts on any content edit. Build (or reuse) the whole-doc completion crate::types::type_map::TypeMap for uri. Cache hit when the entry’s captured source Arc is pointer-equal to doc.source_arc() and the PHPStorm-meta pointer is unchanged (meta lives behind ArcSwap, so its address is stable until .phpstorm.meta.php is reloaded). A miss rebuilds and overwrites, so the entry self-evicts on any content edit.

pub fn cached_analysis_if_fresh(&self, uri: &Url) -> Option<Arc<FileAnalysis>>

Cache-hit-only variant of Self::cached_analysis: returns the cached analysis when the entry is current for the file’s text, never computes. Lets async handlers take the warm path synchronously and reserve spawn_blocking for the cold path (mir Pass 1 + Pass 2 can take hundreds of ms on large files).

pub fn cached_analysis(&self, uri: &Url) -> Option<Arc<FileAnalysis>>

pub fn docs_for(&self, open_urls: &[Url]) -> Vec<(Url, Arc<ParsedDoc>)>

Returns (uri, doc) for files currently open in the editor.

Resolve open_urls (from Backend::open_urls()) to parsed docs. Files not mirrored in the salsa layer are filtered out silently.

pub fn doc_with_others( &self, uri: &Url, doc: Arc<ParsedDoc>, open_urls: &[Url], ) -> Vec<(Url, Arc<ParsedDoc>)>

(primary, doc) first, then every other open file’s parsed doc. The open_urls slice should include uri — this helper filters it out.

pub fn other_docs( &self, uri: &Url, open_urls: &[Url], ) -> Vec<(Url, Arc<ParsedDoc>)>

Parsed docs for every entry in open_urls except uri.

pub fn all_indexes(&self) -> Vec<(Url, Arc<FileIndex>)>

Compact symbol index for every mirrored file.

pub fn cache_vendor_index(&self, uri: Url, index: Arc<FileIndex>)

Store a lazily-loaded vendor FileIndex in the session cache. Only call this for files that are not part of the normal workspace scan (i.e. vendor files loaded on-demand by PSR-4 navigation).

pub fn get_vendor_index(&self, uri: &Url) -> Option<Arc<FileIndex>>

Retrieve a previously cached vendor FileIndex.

pub fn other_indexes(&self, uri: &Url) -> Vec<(Url, Arc<FileIndex>)>

Same as all_indexes but excludes uri.

pub fn all_docs_for_scan(&self) -> Vec<(Url, Arc<ParsedDoc>)>

Parsed documents for every mirrored file (open or background-indexed). Suitable for full-scan operations: find-references, rename, call_hierarchy, code_lens.

pub fn candidate_docs_for(&self, word: &str) -> Vec<(Url, Arc<ParsedDoc>)>

Parsed documents limited to files whose raw source text contains word.

Prefilters via Self::text_cache (a cheap substring scan on the raw Arc<str> already in memory) before calling Self::get_doc_salsa, which triggers a salsa parse for files not yet in the AST cache. This means only candidate files are ever parsed — the key win over [all_docs_for_scan] for find-references, which otherwise parses the entire workspace before the memchr gate in find_references_inner fires.

Files whose text is not yet in text_cache are included conservatively (safe superset — never produces false negatives).

pub fn candidate_urls_mentioning(&self, word: &str) -> Vec<Url>

URLs of files whose raw source text contains word. No parsing.

Used to scope [ensure_files_ingested] for method references: only files that mention the method name by text need mir Pass 2 analysis.

pub fn ensure_files_ingested(&self, urls: &[Url])

Run Pass 1 + Pass 2 analysis on the given files only.

Scoped alternative to [ensure_all_files_ingested] used by textDocument/references for method symbols: only files that textually mention the method name need to be analyzed, cutting the Pass-2 cost from O(workspace) to O(candidates).

Uses BatchFileAnalyzer so Pass 2 runs in parallel across rayon threads, cutting wall time from O(N × per-file) to O(N/cores × per-file).

Trait Implementations

impl Default for DocumentStore

fn default() -> Self

Returns the “default value” for a type.