mir_analyzer/file_analyzer.rs
1//! Per-file analysis entry point for incremental analysis.
2//!
3//! [`FileAnalyzer`] runs a **single** body-analysis pass against an
4//! [`AnalysisSession`] snapshot. In the eager-static-input model the workspace
5//! symbol index is built up front by the background indexer
6//! ([`AnalysisSession::index_batch`]), so `find_class_like` resolves vendor
7//! classes directly — there is no lazy-load / retry loop. The only on-demand
8//! work is [`AnalysisSession::priority_index_for_ast`], which faults in the
9//! open file's *direct* references if the background walk hasn't reached them
10//! yet, keeping warm-up free of transient false positives.
11//!
12//! For batch multi-file analysis, use [`BatchFileAnalyzer::analyze_batch`]
13//! which parallelizes analysis across multiple pre-parsed files.
14
15use std::sync::Arc;
16
17use mir_issues::Issue;
18use php_ast::owned::Program;
19use php_rs_parser::source_map::SourceMap;
20use rayon::prelude::*;
21
22use crate::body_analysis::BodyAnalyzer;
23use crate::db::MirDatabase;
24use crate::session::AnalysisSession;
25use crate::symbol::ResolvedSymbol;
26
27/// Result of a single-file analysis.
28pub struct FileAnalysis {
29 pub issues: Vec<Issue>,
30 pub symbols: Vec<ResolvedSymbol>,
31}
32
33impl FileAnalysis {
34 /// Return the innermost resolved symbol whose span contains `byte_offset`,
35 /// or `None` if no symbol was recorded at that position.
36 ///
37 /// Entry point for hover / go-to-definition flows: callers map
38 /// (line, column) → byte offset → resolved symbol, then look up the
39 /// symbol's definition via [`crate::AnalysisSession::definition_of`] or
40 /// type info via [`ResolvedSymbol::resolved_type`].
41 pub fn symbol_at(&self, byte_offset: u32) -> Option<&ResolvedSymbol> {
42 // Primary: cursor is on an identifier token.
43 if let Some(sym) = self
44 .symbols
45 .iter()
46 .filter(|s| s.span.start <= byte_offset && byte_offset < s.span.end)
47 .min_by_key(|s| s.span.end - s.span.start)
48 {
49 return Some(sym);
50 }
51
52 // Fallback: cursor is in a call-expression gap (e.g. the whitespace,
53 // argument list, or trailing `->` between two chained method calls).
54 // Match against the full expression span recorded for call-like
55 // symbols and return the innermost (smallest) enclosing call —
56 // mirrors `crate::batch::BatchAnalysis::symbol_at`, which already
57 // does this; this single-file path fell out of sync with it.
58 self.symbols
59 .iter()
60 .filter(|s| {
61 s.expr_span
62 .is_some_and(|es| es.start <= byte_offset && byte_offset < es.end)
63 })
64 .min_by_key(|s| {
65 let es = s.expr_span.unwrap();
66 es.end - es.start
67 })
68 }
69}
70
71/// Per-file body analysis analyzer bound to an [`AnalysisSession`]. Cheap to
72/// construct — typically held transiently per analysis call.
73pub struct FileAnalyzer<'a> {
74 session: &'a AnalysisSession,
75}
76
77impl<'a> FileAnalyzer<'a> {
78 pub fn new(session: &'a AnalysisSession) -> Self {
79 Self { session }
80 }
81
82 /// Run a single body-analysis pass against a frozen db snapshot.
83 ///
84 /// `priority_index_for_ast` runs first to fault in any of this file's
85 /// direct class references not yet reached by the background indexer; then
86 /// one snapshot is analyzed and its reference locations committed. The lock
87 /// is not held during analysis, so concurrent edits and reads proceed.
88 pub fn analyze(
89 &self,
90 file: Arc<str>,
91 source: &str,
92 program: &Program,
93 source_map: &SourceMap,
94 ) -> FileAnalysis {
95 crate::metrics::record_file_analysis();
96
97 // Priority-index the buffer's direct class references so any not yet
98 // reached by the background indexer resolve in this single pass (no
99 // transient false UndefinedClass during warm-up). Once indexing
100 // completes this is a no-op.
101 // Capture (text, generation) BEFORE the warm-up: if a concurrent edit
102 // swaps the input text mid-flight, the stored Arc no longer matches
103 // and the mark is dead on arrival — the safe direction.
104 let prepare_generation = self.session.prepare_generation_snapshot();
105 let ingested_text = {
106 let db = self.session.snapshot_db();
107 db.lookup_source_file(file.as_ref())
108 .map(|sf| sf.text(&db as &dyn crate::db::MirDatabase))
109 };
110 self.session
111 .prepare_ast_for_analysis(program, file.as_ref());
112 // Record the warm-up so later Phase-1 sweeps (references, dependent
113 // re-analysis) skip this file's parse + AST walk while its salsa
114 // input text is unchanged.
115 if let Some(text) = ingested_text {
116 self.session
117 .mark_prepared_for_analysis(&file, text, prepare_generation);
118 }
119
120 let _scope = crate::metrics::BodyAnalysisScope::new();
121
122 // Single pass against a frozen snapshot. With the eager-static-input
123 // model the workspace index is complete (or priority-indexed for this
124 // file's direct refs), so there are no body-analysis "misses" to fault
125 // in — no retry loop, no whole-file re-analysis.
126 let db = self.session.snapshot_db();
127 let driver = BodyAnalyzer::new(&db, self.session.php_version());
128 let (issues, symbols) = driver.analyze_bodies(program, file.clone(), source, source_map);
129 self.session
130 .commit_ref_locs_batch(db.take_pending_ref_locs());
131 FileAnalysis { issues, symbols }
132 }
133}
134
135/// Batch file analyzer for parallel multi-file analysis.
136///
137/// `BatchFileAnalyzer` processes pre-parsed files in parallel using rayon,
138/// making it efficient for analyzing many files at once (e.g., cold-start analysis).
139pub struct BatchFileAnalyzer<'a> {
140 session: &'a AnalysisSession,
141}
142
143/// A pre-parsed file ready for batch analysis.
144pub struct ParsedFile {
145 pub(crate) file: Arc<str>,
146 pub(crate) source: Arc<str>,
147 pub(crate) program: Program,
148 pub(crate) source_map: SourceMap,
149}
150
151impl ParsedFile {
152 /// File path this `ParsedFile` represents.
153 pub fn file(&self) -> &Arc<str> {
154 &self.file
155 }
156
157 /// Source text for this file.
158 pub fn source(&self) -> &Arc<str> {
159 &self.source
160 }
161
162 /// Create a `ParsedFile` from an owned program and source map.
163 pub fn new(file: Arc<str>, source: Arc<str>, program: Program, source_map: SourceMap) -> Self {
164 Self {
165 file,
166 source,
167 program,
168 source_map,
169 }
170 }
171}
172
173impl<'a> BatchFileAnalyzer<'a> {
174 pub fn new(session: &'a AnalysisSession) -> Self {
175 Self { session }
176 }
177
178 /// Analyze multiple pre-parsed files in parallel.
179 ///
180 /// Each rayon worker gets its own cloned database snapshot, so concurrent
181 /// analysis proceeds without lock contention on the session.
182 pub fn analyze_batch(&self, files: Vec<ParsedFile>) -> Vec<(Arc<str>, FileAnalysis)> {
183 // First pass: collect all ASTs and auto-discover stubs.
184 // Also lazy-load vendor autoload.files globals once so they are in the
185 // workspace index before the parallel analysis snapshot is taken.
186 self.session.ensure_vendor_eager_functions();
187 files.iter().for_each(|file| {
188 self.session.ensure_stubs_for_ast(&file.program);
189 });
190
191 // Second pass: analyze files in parallel.
192 // Each rayon worker gets its own database clone (Salsa is Send but !Sync).
193 let db = self.session.snapshot_db();
194 let results: Vec<(Arc<str>, FileAnalysis, Vec<crate::db::RefLoc>)> = files
195 .into_par_iter()
196 .map_with(db, |db, file| {
197 let driver = BodyAnalyzer::new(db as &dyn MirDatabase, self.session.php_version());
198 let (issues, symbols) = driver.analyze_bodies(
199 &file.program,
200 file.file.clone(),
201 &file.source,
202 &file.source_map,
203 );
204 let pending = db.take_pending_ref_locs();
205 let analysis = FileAnalysis { issues, symbols };
206 (file.file, analysis, pending)
207 })
208 .collect();
209 let mut all_ref_locs = Vec::new();
210 let mut out = Vec::with_capacity(results.len());
211 for (file, analysis, ref_locs) in results {
212 all_ref_locs.extend(ref_locs);
213 out.push((file, analysis));
214 }
215 self.session.commit_ref_locs_batch(all_ref_locs);
216 out
217 }
218}