Struct AnalysisSession 

pub struct AnalysisSession { /* private fields */ }

Long-lived analysis context. Owns the salsa database and tracks which stubs have been loaded.

Cheap to clone the inner db for parallel reads; writes funnel through Self::ingest_file, Self::invalidate_file, and the crate-internal [Self::with_db_mut].

Implementations

impl AnalysisSession

pub fn analyze_paths( &self, paths: &[PathBuf], opts: &BatchOptions, ) -> AnalysisResult

Run the full batch analysis pipeline on a set of file paths.

pub fn re_analyze_file( &self, file_path: &str, new_content: &str, opts: &BatchOptions, ) -> AnalysisResult

Re-analyze a single file (definition collection + body analysis) within the batch context.

Mirrors the old ProjectAnalyzer::re_analyze_file cache-aware path. Use Self::reanalyze_dependents for LSP-style per-file flows that don’t need batch options.

pub fn collect_definitions(&self, paths: &[PathBuf])

Collect type definitions only from paths into the codebase without analyzing method bodies or emitting issues. Used to load vendor types.

When a disk-backed cache is attached, per-file StubSlice results from previous runs are reused on a content-hash match, eliminating the parse + definition-collection step. Cache misses run the normal pipeline and write back so subsequent runs hit.

impl AnalysisSession

pub fn new(php_version: PhpVersion) -> Self

Create a session targeting the given PHP language version.

pub fn with_source_provider(self, provider: Arc<dyn SourceProvider>) -> Self

Swap in a custom crate::SourceProvider. LSPs install a VFS-backed provider here so the analyzer reads from unsaved editor buffers instead of disk.

pub fn with_cache(self, cache: Arc<AnalysisCache>) -> Self

Attach a pre-built [AnalysisCache] (the body-analysis issue cache) and open a sibling definition StubSlice cache under the same root, so callers using this builder get the same speedup as with_cache_dir.

Rebuilds the shared database to attach the definition cache — call before any file is ingested. A debug assertion catches misuse.

pub fn with_cache_dir(self, cache_dir: &Path) -> Self

Convenience: open a disk-backed cache at cache_dir and attach it.

Attaches both the body-analysis issue cache ([AnalysisCache]) and the definition StubSlice cache to the shared database. Builds a fresh [AnalyzerDb] internally — call before any file is ingested. A debug assertion catches misuse.

pub fn with_psr4(self, map: Arc<Psr4Map>) -> Self

Attach a Composer autoload map (PSR-4, PSR-0, classmap, files). Sets the same map as the active crate::ClassResolver so Self::load_class works out of the box.

pub fn with_class_resolver(self, resolver: Arc<dyn ClassResolver>) -> Self

Attach a generic class resolver for projects that don’t use Composer (WordPress, Drupal, custom autoloaders, workspace-walk indexes). Replaces any previously-set Composer-backed resolver. Automatically wrapped with stub awareness so PHP built-ins remain resolvable.

pub fn with_user_stubs(self, files: Vec<PathBuf>, dirs: Vec<PathBuf>) -> Self

pub fn php_version(&self) -> PhpVersion

pub fn cache(&self) -> Option<&AnalysisCache>

pub fn psr4(&self) -> Option<&Psr4Map>

pub fn ensure_essential_stubs(&self)

👎Deprecated:

use ensure_all_stubs() or ensure_stubs_for_ast() instead

Deprecated — stub loading is now fully lazy per-AST.

This is an alias for Self::ensure_all_stubs kept for API compatibility. Internal analysis paths use Self::prepare_ast_for_analysis which loads only the stubs referenced by the file under analysis.

pub fn ensure_all_stubs(&self)

Load every embedded PHP stub plus any configured user stubs. Use for batch tools (CLI, full project analysis) where comprehensive symbol coverage matters more than cold-start latency.

pub fn loaded_stub_count(&self) -> usize

Number of distinct embedded stubs currently ingested into the session. Useful for diagnostics and bench reporting.

pub fn ensure_stubs_for_source(&self, source: &str)

Auto-discover and ingest the embedded stubs needed to cover every built-in PHP function / class / constant referenced by source.

Used by crate::FileAnalyzer::analyze to keep essentials-only mode correct without forcing callers to enumerate which stubs they need. Idempotent — already-loaded stubs are skipped via [Self::loaded_stubs].

The discovery scan is a coarse identifier sweep (see [crate::stubs::collect_referenced_builtin_paths]) — it may pull in a slightly larger set than the file strictly needs, but never misses a referenced built-in. Cost is sub-millisecond per file.

Fast path: if every embedded stub is already loaded (e.g. after a batch tool called Self::ensure_all_stubs), the source scan is skipped entirely.

pub fn ensure_stubs_for_ast(&self, program: &Program)

Discover and ingest stubs by walking the parsed AST of a PHP file.

Similar to Self::ensure_stubs_for_source, but takes an already-parsed AST instead of raw source text. Produces zero false positives since it only extracts identifiers from actual AST nodes (not from strings or comments). Preferred over ensure_stubs_for_source when the AST is already available (e.g., in crate::FileAnalyzer).

Idempotent and skips the scan if all stubs are already loaded.

pub fn has_resolver(&self) -> bool

Returns true if this session has a configured class resolver (typically a PSR-4 / classmap autoloader chained with the stub resolver). Used by FileAnalyzer to skip the AST-scan preload when no resolver is wired up.

pub fn prepare_ast_for_analysis(&self, program: &Program, file: &str)

Run both pre-passes (builtin-stub loading and PSR-4 class preloading) in one call. Replaces the two separate ensure_stubs_for_ast / preload_psr4_classes_for_ast calls at every FileAnalyzer::analyze site.

pub fn priority_index_for_ast(&self, program: &Program, file: &str)

Priority-index the classes directly referenced by file’s AST.

In the eager-static-input model the background indexer (Self::index_batch) walks the whole vendor tree, but it may not have reached every file the open buffer references yet. To avoid a transient false UndefinedClass during the warm-up window, this reorders that static work: it resolves the buffer’s direct class references and loads any not-yet-indexed ones immediately, jumping them to the front of the queue.

This is bounded by the number of distinct direct references in one file — no transitive BFS, no depth/total budget, no pinning. Inheritance ancestors and signature types of those classes are picked up by the background walk (or, for navigation, by Self::hover / Self::definition_of). Because bump_workspace_revision no longer nulls the workspace index singleton, each Self::load_class here costs only a resolver lookup + parse (or cache hit) + one tier-aware merge, invalidating just the actively-analyzed file’s memo once — not the whole cache. Once background indexing completes this is a no-op (every reference already resolves).

pub fn ingest_file(&self, file: Arc<str>, source: Arc<str>)

definition-collection ingestion. Updates the file’s source text in the salsa db, runs definition collection, and ingests the resulting stub slice. Triggers stub loading on first call. Also updates the cache’s reverse- dependency graph for file so cross-file invalidation stays correct across incremental edits — without rebuilding the graph from scratch.

If file was previously ingested, its old definitions and reference locations are removed first so renames / deletions don’t leave stale state in the codebase. (Without this, long-running sessions would accumulate dead reference-location entries indefinitely.)

pub fn set_file_text(&self, file: Arc<str>, source: Arc<str>)

Register source as the text of file in the salsa input layer without parsing or running definition collection.

This is the LSP-friendly bulk-population entry point: after a workspace scan, callers can feed every discovered file’s text to the session cheaply (an Arc clone plus a HashMap insert per file). Name resolution then happens on demand via Self::load_class, which reads the file from disk through the configured crate::ClassResolver and runs definition collection lazily when a class FQCN actually needs to resolve.

Contrast with Self::ingest_file, which eagerly parses, runs definition collection, and populates the symbol index. Use ingest_file for files the user is actively editing (where in-memory text diverges from disk); use set_file_text for files known only through the workspace scan.

Clears the negative cache: a previously-unresolvable FQCN may now resolve if its defining file is among the newly-registered set.

pub fn set_vendor_files<I>(&self, files: I)

where I: IntoIterator<Item = (Arc<str>, Arc<str>)>,

Bulk-register vendor / library files with HIGH salsa durability.

HIGH-durability files are not expected to change during the session. When a LOW-durability project file is edited, salsa can skip O(N) dependency verification for every HIGH-durability file, reducing workspace_symbol_index re-verification cost to O(project files only).

Definition collection runs lazily on first symbol access; no parsing at call time.

pub fn rebuild_workspace_symbol_index(&self)

Build or refresh the WorkspaceSymbolIndexSingleton from all currently registered files.

After this call, find_class_like, find_function, and find_global_constant read singleton.index(db) — a single Durability::HIGH tracked dep — instead of recomputing the full O(N_files) dep list via workspace_symbol_index. On subsequent LOW-durability (project-file) body edits the dep short-circuits in O(1).

Call this once after all vendor + stub + project files have been ingested (end of workspace warm-up). Also called automatically by Self::ingest_file when a file’s declared names change.

pub fn set_workspace_files<I>(&self, files: I)

where I: IntoIterator<Item = (Arc<str>, Arc<str>)>,

Bulk variant of Self::set_file_text. Acquires the salsa write lock once for the entire batch instead of once per file.

The intended LSP scan loop is:

let files: Vec<_> = walk_workspace()
    .map(|path| (path, fs::read(&path).unwrap()))
    .collect();
session.set_workspace_files(files);

After this call, every file’s source text is known to salsa. No parsing has happened yet — Definition collection runs per file on the first load_class that needs to consult it.

pub fn index_generation(&self) -> u64

The workspace generation epoch — the rust-analyzer-style “are we up to date” counter. Bumped whenever a file is added or removed. A consumer records this alongside the diagnostics it publishes for a file; when the value later advances (background indexing registered more files), those files become candidates for re-analysis + re-publish.

pub fn index_batch( &self, files: &[(Arc<str>, Arc<str>)], parallelism: IndexParallelism, cancel: &IndexCancel, ) -> IndexBatchOutcome

Index one bounded chunk of (path, text) files — the chunked background indexing primitive.

For each chunk this: (1) registers the files as Durability::HIGH salsa inputs in one short write window, (2) parses them to prime the in-process and on-disk declaration caches (in parallel when parallelism == [IndexParallelism::Rayon]; sequentially for wasm / single-thread consumers), and (3) merges their declarations into the workspace symbol index singleton incrementally (no full rebuild) so partially-indexed symbols resolve immediately.

The library spawns no thread: the consumer pumps chunks from its own driver (LSP worker thread, or one chunk per wasm event-loop tick), re-checking higher-priority work between calls. cancel is honoured at chunk boundaries so an edit can abandon queued indexing cheaply.

Contract: index the workspace incrementally through this method; don’t bulk-register the entire file set up front and then index — the first call lazily seeds the singleton from the currently-registered set (built-in stubs + this chunk), so keeping that initial set small keeps the first call cheap. Call Self::finalize_index once after the last chunk to reconcile authoritatively.

Responsiveness: parsing / declaration collection happens off the salsa write lock (on a snapshot); only the cheap symbol-map merge runs under the lock, so the write window per chunk is short and an interactive read on another thread blocks at most that long. Note that, per salsa’s snapshot model, a cancellable query in flight on another thread (e.g. hover, definition_of, FileAnalyzer::analyze) when this batch takes the write lock may unwind with salsa::Cancelled; a multi-threaded consumer should catch that and retry the request (the rust-analyzer pattern). A single-threaded consumer that interleaves requests between index_batch calls never observes cancellation.

pub fn finalize_index(&self)

Authoritative full rebuild of the workspace symbol index. Call once after the consumer has pumped every Self::index_batch chunk (end of warm-up) to reconcile the incrementally-merged index against the full registered set. Cheap after indexing — every file’s declarations are already cached.

pub fn invalidate_file(&self, file: &str)

Drop a file’s contribution to the session: codebase definitions, reference locations, salsa input handle, cache entry, and outgoing reverse-dependency edges. Cache entries of dependent files are also evicted (cross-file invalidation).

Use this when a file is closed by the consumer, or before a re-ingest of substantially changed content. (Plain re-ingest via Self::ingest_file also drops old definitions, but does not remove the salsa input handle — call this for full cleanup.)

pub fn tracked_file_count(&self) -> usize

Number of files currently tracked in this session’s salsa input set. Stable across reads; useful for diagnostics and memory bounds checks.

pub fn definition_of( &self, symbol: &Name, ) -> Result<Location, SymbolLookupError>

Resolve a top-level symbol (class or function) to its declaration location. Powers go-to-definition.

Side effects: if the symbol isn’t yet known, this may invoke the configured crate::SourceProvider to fault in additional files and mutate the salsa input set. Use Self::definition_of_cached for a pure variant that only consults already-loaded state.

Returns:

• Ok(Location) — symbol found with a source location
• Err(NotFound) — no such symbol in the codebase
• Err(NoSourceLocation) — symbol exists but has no recorded span (e.g. some stub-only declarations)

pub fn definition_of_cached( &self, symbol: &Name, ) -> Result<Location, SymbolLookupError>

Pure variant of Self::definition_of. Never invokes the crate::SourceProvider and never mutates salsa inputs; resolves only against state already loaded by set_file_text / ingest_file. Returns Err(NotFound) when the symbol isn’t in the loaded set, even if a resolver could in principle map it.

pub fn hover(&self, symbol: &Name) -> Result<HoverInfo, SymbolLookupError>

Hover information for a symbol: type, docstring, and definition location.

Use crate::FileAnalysis::symbol_at to find the symbol at a cursor position, then build a crate::Name from its kind. This method assembles the displayable hover data.

Side effects: when symbol’s owning class isn’t yet loaded, this may invoke the configured crate::SourceProvider to fault in dependencies. Use Self::hover_cached for a pure variant.

Returns Err(NotFound) if the symbol doesn’t exist. May still return Ok with docstring: None or definition: None if those specific pieces aren’t available.

pub fn hover_cached( &self, symbol: &Name, ) -> Result<HoverInfo, SymbolLookupError>

Pure variant of Self::hover. Never invokes the crate::SourceProvider; consults only the already-loaded db.

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

Every recorded reference to symbol with its source location as a Range. Use crate::FileAnalysis::symbol_at to find the symbol at a cursor, build a crate::Name from it, and pass it here.

pub fn class_issues(&self, files: &[Arc<str>]) -> Vec<Issue>

Class-level issues (inheritance violations, abstract-method gaps, override incompatibilities) for the given set of files.

These checks are cross-file by nature and are not emitted by crate::FileAnalyzer::analyze. Call this after ingesting or re-analyzing a file and its dependents to get the full diagnostic picture.

Circular-inheritance checks always run against the full workspace graph regardless of the files filter — a cycle is a workspace-wide problem.

pub fn document_symbols(&self, file: &str) -> Vec<DocumentSymbol>

All declarations defined in file as a hierarchical tree.

Classes/interfaces/traits/enums are returned with their methods, properties, and constants nested in children. Top-level functions and constants are returned with empty children.

pub fn contains_function(&self, fqn: &str) -> bool

Returns true if a function with fqn is registered and active in the codebase. Case-insensitive lookup with optional leading backslash.

pub fn contains_class(&self, fqcn: &str) -> bool

Returns true if a class / interface / trait / enum with fqcn is registered and active in the codebase.

pub fn contains_method(&self, class: &str, name: &str) -> bool

Returns true if class has a method named name registered. Method names are matched case-insensitively (PHP method dispatch semantics).

pub fn load_class(&self, fqcn: &str) -> LoadOutcome

Resolve fqcn via the configured crate::ClassResolver and ingest the mapped file. The session keeps a negative cache so repeated calls for an unresolvable name don’t re-hit the resolver; the cache is invalidated on any Self::ingest_file / Self::invalidate_file.

This is the LSP-friendly entry point: the analyzer never touches vendor/ on its own, but consumers can ask it to resolve individual symbols on demand. Designed to be called when a diagnostic would otherwise report UndefinedClass.

Returns a crate::LoadOutcome distinguishing already-loaded / freshly-loaded / not-resolvable. Use crate::LoadOutcome::is_loaded when only success matters.

pub fn source_of(&self, file: &str) -> Option<Arc<str>>

Retrieve the source text the session has registered for file, if any. Returns None when the file has never been ingested. Used by the parallel re-analysis path to re-feed dependents to body analysis without the caller having to track sources independently.

pub fn reanalyze_dependents(&self, file: &str) -> Vec<(Arc<str>, FileAnalysis)>

Re-analyze every transitive dependent of file in parallel.

When the user saves a file that other files depend on (e.g. editing a base class, an interface, or a trait), those dependents may have new diagnostics. This method computes them in parallel using rayon and returns the per-file analysis results so the LSP server can publish updated diagnostics in one batch.

Source text for dependents is retrieved from the session’s salsa inputs (set by previous ingest_file calls) — the caller doesn’t need to track or re-read files. Files for which the session has no source are silently skipped (returns the analyzable subset).

Cross-file inferred return types are resolved on demand via salsa.

pub fn reanalyze_dependents_cancellable( &self, file: &str, cancel: &IndexCancel, ) -> Vec<(Arc<str>, FileAnalysis)>

Cancellable variant of Self::reanalyze_dependents.

The consumer flips cancel (typically because a newer edit arrived) to abandon the re-analysis; the flag is checked at each file boundary. Salsa cannot unwind the plain-Rust body-analysis walk mid-flight, so a file already in progress finishes, but no further files are started. Files skipped due to cancellation are simply absent from the returned vec — the consumer should drop a stale flag and start fresh work on each edit.

pub fn pending_lazy_loads(&self, file: &str) -> Vec<Arc<str>>

FQCNs that file imports via use statements but that aren’t yet loaded in the session.

Designed as the input to background prefetching: after the LSP server ingests an open buffer, it can call this and lazy-load the returned FQCNs on a worker thread so the user’s first Cmd+Click into vendor code doesn’t pay the file-read+parse cost.

Returns an empty Vec if the file hasn’t been ingested or has no unresolved imports.

pub fn prefetch_imports(&self, file: &str) -> usize

Convenience: synchronously lazy-load every import of file that isn’t already in the codebase. Returns the number successfully loaded.

For non-blocking prefetch, call this from a worker thread:

let s = session.clone();  // AnalysisSession is wrapped in Arc by callers
std::thread::spawn(move || {
    s.prefetch_imports(&file_path);
});

Uses a single shared-visited two-tier BFS across all pending imports (see [Self::load_classes_transitive_bounded]) with a shallow depth so member access on imported types type-checks without pulling in the entire vendor tree.

pub fn all_classes(&self) -> Vec<(Arc<str>, Option<Location>)>

All class / interface / trait / enum FQCNs currently known to the session, each paired with the file that defines them when available.

Use this to build workspace-wide views (outline, fuzzy search, etc.). Consumers implement their own search/match logic on top — the analyzer only exposes the iterator.

pub fn all_functions(&self) -> Vec<(Arc<str>, Option<Location>)>

All global function FQNs currently known to the session, each paired with their declaration location when available.

pub fn structural_dependents(&self, file: &str) -> Vec<String>

BFS transitive dependents of file using the in-memory reverse dep map.

O(D) where D is the number of transitive dependents — faster than [Self::dependency_graph().transitive_dependents()] which rebuilds the full graph on every call. Only covers structural dependencies from definition collection (imports, class hierarchy, type hints); does not include bare FQN body references recorded during body analysis. For full fidelity, use dependency_graph().transitive_dependents() after body analysis is complete.

pub fn dependency_graph(&self) -> DependencyGraph

File dependency graph: which files depend on which other files. Used for incremental invalidation in LSP servers and build systems.

File dependency graph: which files depend on which other files. Used for incremental invalidation in LSP servers and build systems.

O(edges) — iterates the file_references forward index (file → symbol keys it references) which is always current, then resolves each symbol to its defining file via O(1) lookup. Total cost is O(E) where E is the number of (file, symbol) reference edges, vs. the old O(F × S × R) scan.

Trait Implementations

impl Clone for AnalysisSession

fn clone(&self) -> AnalysisSession

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.