Skip to main content

reflex/query/
mod.rs

1//! Query engine for searching indexed code
2//!
3//! The query engine loads the memory-mapped cache and executes
4//! deterministic searches based on lexical, structural, or symbol patterns.
5
6pub mod filter;
7pub mod open_index;
8pub mod result;
9pub mod zero_hint;
10
11pub use filter::{LiteralPattern, QueryFilter, prepare_literal_pattern, substring_hint_text};
12pub use zero_hint::{ExcludedReason, ZeroHint};
13
14use anyhow::{Context, Result};
15use regex::Regex;
16
17use crate::cache::CacheManager;
18use crate::models::{
19    IndexPath, IndexStatus, IndexStatusReport, IndexWarning, Language, QueryResponse, SearchResult,
20    Span, SymbolKind,
21};
22use crate::output;
23use crate::parsers::ParserFactory;
24use std::sync::Arc;
25use std::sync::atomic::{AtomicUsize, Ordering};
26
27use open_index::OpenIndex;
28
29/// Drop every process-wide memo for `workspace_root`: the shared open-index
30/// handle and the freshness snapshot. Called around index writes so no query in
31/// this process keeps serving from replaced files or a stale verdict.
32pub fn invalidate_caches(workspace_root: &std::path::Path) {
33    open_index::invalidate(&workspace_root.join(crate::cache::CACHE_DIR));
34    status_cache::invalidate(workspace_root);
35}
36
37/// What an automatic update must do, from the freshness check
38/// ([`crate::auto_update`]).
39#[derive(Debug, Clone, PartialEq, Eq)]
40pub enum UpdatePlan {
41    /// Every indexed file matches the tree.
42    Fresh,
43    /// Only these paths (relative to the root) changed: added, modified or deleted.
44    Paths(Vec<std::path::PathBuf>),
45    /// A full run: many changes, a rule-file edit, or a cache format change. The
46    /// paths the check listed (capped at 100 per kind; none for a format change).
47    Full(Vec<std::path::PathBuf>),
48    /// Written by another released version; the reason names it.
49    Foreign(String),
50    /// Nothing could be compared; the reason says why.
51    Unknown(String),
52}
53
54/// The update plan for the workspace `cache` belongs to (memoised with the
55/// freshness verdict for the same window).
56pub fn update_plan(cache: &CacheManager) -> Result<UpdatePlan> {
57    Ok(status_cache::update_plan(cache)?.0)
58}
59
60/// An update plan with the freshness check it came from ([`plan_update`]).
61pub struct PlannedUpdate {
62    pub plan: UpdatePlan,
63    snapshot: Arc<status_cache::Snapshot>,
64}
65
66/// [`update_plan`], keeping the check for [`settle_update`].
67pub fn plan_update(cache: &CacheManager) -> Result<PlannedUpdate> {
68    let (plan, snapshot) = status_cache::update_plan(cache)?;
69    Ok(PlannedUpdate { plan, snapshot })
70}
71
72/// After `planned`'s paths were updated: confirm only those paths against the
73/// index and, when all match, make "fresh" the memoised verdict for the rest of
74/// the original check's window. Saves the second tree comparison (a `git status`
75/// on a large repository) right after an update. False when it could not.
76pub fn settle_update(cache: &CacheManager, planned: &PlannedUpdate) -> bool {
77    match &planned.plan {
78        UpdatePlan::Paths(paths) => status_cache::settle(cache, &planned.snapshot, paths),
79        _ => false,
80    }
81}
82
83/// What `search_internal` hands back: the page plus the bookkeeping the public
84/// wrappers turn into pagination, hints and timings.
85struct Internal {
86    results: Vec<SearchResult>,
87    /// Matches before offset/limit. Exact when `total_is_exact`; otherwise the
88    /// number verified before the page filled, which the public wrappers must
89    /// NOT report as a total.
90    total_count: usize,
91    /// False when verification stopped early (list mode with a limit).
92    total_is_exact: bool,
93    /// Sample-based estimate of the total when it is not exact.
94    approx_total: Option<usize>,
95    /// Candidate lines that contained the pattern only as a substring
96    /// (whole-identifier searches only), for the zero-result hint.
97    substring_only: Option<usize>,
98    /// Candidate files left out because they are lock/generated files nobody
99    /// asked for, for the zero-result hint.
100    excluded_by_default: usize,
101    /// Count-only mode: `(matching lines, files with a match)`; `results` is empty
102    /// and `total_count` is the line count.
103    counted: Option<(usize, usize)>,
104    /// Time spent in trigram lookup and intersection.
105    candidates_us: u64,
106    /// Trigram index or full scan.
107    index_path: IndexPath,
108    /// Engine warnings from the candidate pass.
109    warnings: Vec<String>,
110}
111
112/// Bookkeeping from a candidate pass (trigram or regex).
113#[derive(Debug, Clone)]
114struct CandidateStats {
115    candidates_us: u64,
116    substring_only: Option<usize>,
117    /// See `Internal::excluded_by_default`.
118    excluded_by_default: usize,
119    /// Count-only mode: `(matching lines, files with a match)`.
120    counted: Option<(usize, usize)>,
121    /// Every candidate was verified.
122    exhausted: bool,
123    /// Sample-based estimate of the total, only when not `exhausted`.
124    approx_total: Option<usize>,
125    /// Trigram index or full scan.
126    index_path: IndexPath,
127    /// What the engine wants the caller to know about the candidate pass (a
128    /// regex that had to scan), for `QueryResponse.warnings`.
129    warnings: Vec<String>,
130}
131
132impl Default for CandidateStats {
133    fn default() -> Self {
134        Self {
135            candidates_us: 0,
136            substring_only: None,
137            excluded_by_default: 0,
138            counted: None,
139            exhausted: true,
140            approx_total: None,
141            index_path: IndexPath::Trigram,
142            warnings: Vec::new(),
143        }
144    }
145}
146
147/// Which lines of a candidate file to verify.
148enum LineSet {
149    /// Only these 1-based lines (from the trigram intersection), ascending.
150    Only(Vec<u32>),
151    /// Every line: the pattern gave the index nothing to narrow on.
152    All,
153}
154
155/// Per-file filters, applied INSIDE the verification loop so that early
156/// termination counts only files the caller will actually receive.
157struct FileFilter {
158    language: Option<Language>,
159    include: Option<globset::GlobSet>,
160    exclude: Option<globset::GlobSet>,
161    file_pattern: Option<String>,
162    exclude_text: bool,
163    include_locks: bool,
164    include_generated: bool,
165}
166
167impl FileFilter {
168    fn from_filter(filter: &QueryFilter) -> Self {
169        Self {
170            language: filter.language,
171            include: result::build_glob_set(&filter.glob_patterns, "glob"),
172            exclude: result::build_glob_set(&filter.exclude_patterns, "exclude"),
173            file_pattern: filter.file_pattern.clone(),
174            exclude_text: filter.exclude_text,
175            include_locks: filter.include_locks,
176            include_generated: filter.include_generated,
177        }
178    }
179
180    /// The file is a lock/generated file nobody asked for. Counted, not searched.
181    fn excluded_by_default(&self, lang: Language) -> bool {
182        filter::excluded_by_default(
183            lang,
184            self.language,
185            self.include_locks,
186            self.include_generated,
187        )
188    }
189
190    /// The path filters alone: `glob`, `exclude`, `file`.
191    fn path_admits(&self, path: &str) -> bool {
192        if let Some(set) = &self.include
193            && !set.is_match(path)
194        {
195            return false;
196        }
197        if let Some(set) = &self.exclude
198            && set.is_match(path)
199        {
200            return false;
201        }
202        if let Some(needle) = &self.file_pattern
203            && !path.contains(needle.as_str())
204        {
205            return false;
206        }
207        true
208    }
209
210    fn accept(&self, path: &str, lang: Language) -> bool {
211        filter::tier_admits(
212            lang,
213            self.language,
214            self.exclude_text,
215            self.include_locks,
216            self.include_generated,
217        ) && self.path_admits(path)
218    }
219}
220
221/// What a streaming verification pass produced.
222struct VerifyOutcome {
223    /// In `(path, line)` order.
224    results: Vec<SearchResult>,
225    /// Every candidate file was verified.
226    exhausted: bool,
227    /// Estimate of the full match count, only when not `exhausted`: the page's
228    /// verified matches plus the sampled hit rate over the remaining candidates.
229    /// `None` when a remaining file had `LineSet::All` (no line count to scale).
230    estimated_total: Option<usize>,
231    /// Whole-identifier searches only: candidate lines holding the pattern as a
232    /// substring but not as a whole identifier.
233    substring_only: usize,
234    /// Candidate files left out because they are lock/generated files and nothing
235    /// asked for them.
236    excluded_by_default: usize,
237    /// Count-only mode: `(matching lines, files with a match)`; `results` is empty.
238    counted: Option<(usize, usize)>,
239}
240
241/// The per-line predicate for one query, built once.
242///
243/// The whole-identifier check used to compile `\b…\b` for every candidate line;
244/// on a common word that compile cost more than the match itself.
245enum LineMatcher {
246    /// Whole-identifier match (`\b…\b`), the default. Keeps the literal so the
247    /// zero-result hint can count substring-only lines.
248    WordBoundary(Regex, String),
249    /// Substring match (`contains: true`), also the fallback when the
250    /// word-boundary regex cannot be built.
251    Contains(String),
252    /// User-supplied regex, with the `kind` label its matches carry: a regex the
253    /// engine built from an `ignore_case` literal still reports `text_match`.
254    Regex(Regex, &'static str),
255}
256
257impl LineMatcher {
258    fn new(pattern: &str, filter: &QueryFilter) -> Result<Self> {
259        if filter.use_regex {
260            let label = if filter.ignore_case && filter.rewritten_from.is_some() {
261                "text_match"
262            } else {
263                "regex_match"
264            };
265            return match Regex::new(pattern) {
266                Ok(re) => Ok(Self::Regex(re, label)),
267                Err(e) => {
268                    log::error!("Invalid regex pattern '{}': {}", pattern, e);
269                    anyhow::bail!("Invalid regex pattern '{}': {}", pattern, e);
270                }
271            };
272        }
273        if filter.use_contains {
274            return Ok(Self::Contains(pattern.to_string()));
275        }
276        match Regex::new(&format!(r"\b{}\b", regex::escape(pattern))) {
277            Ok(re) => Ok(Self::WordBoundary(re, pattern.to_string())),
278            Err(_) => {
279                log::debug!(
280                    "Word boundary regex failed for pattern '{}', falling back to substring",
281                    pattern
282                );
283                Ok(Self::Contains(pattern.to_string()))
284            }
285        }
286    }
287
288    fn is_word_boundary(&self) -> bool {
289        matches!(self, Self::WordBoundary(..))
290    }
291
292    #[inline]
293    fn is_match(&self, line: &str) -> bool {
294        match self {
295            Self::WordBoundary(re, _) | Self::Regex(re, _) => re.is_match(line),
296            Self::Contains(p) => line.contains(p.as_str()),
297        }
298    }
299
300    /// Byte offset of the first match, to window the preview on it.
301    #[inline]
302    fn find(&self, line: &str) -> Option<usize> {
303        match self {
304            Self::WordBoundary(re, _) | Self::Regex(re, _) => re.find(line).map(|m| m.start()),
305            Self::Contains(p) => line.find(p.as_str()),
306        }
307    }
308
309    /// The literal text of a whole-identifier or substring matcher (regex: none).
310    fn literal(&self) -> Option<&str> {
311        match self {
312            Self::WordBoundary(_, p) | Self::Contains(p) => Some(p.as_str()),
313            Self::Regex(..) => None,
314        }
315    }
316
317    /// The `kind` label a text match carries in results.
318    fn kind_label(&self) -> &'static str {
319        match self {
320            Self::Regex(_, label) => label,
321            _ => "text_match",
322        }
323    }
324}
325
326/// Verify candidate files in path order, in parallel, stopping once `budget`
327/// results exist.
328///
329/// Files are processed in rounds of growing chunks (16, 32, … 1024). Inside a
330/// round rayon's indexed `map().collect()` keeps file order, and lines within a
331/// file are ascending, so the concatenation is already in `(path, line)` order:
332/// the first page is complete and correctly ordered the moment the budget is met,
333/// without verifying the rest. With `budget: None` every file is verified.
334/// Files sampled to estimate the total after a page fills early. Spread evenly over
335/// the remaining candidates (path order), so one directory of dense hits does not
336/// set the rate for the whole repo.
337pub const ESTIMATE_SAMPLE_FILES: usize = 32;
338/// Remaining candidate lines at or below which the search just finishes instead of
339/// sampling: verifying 128 lines costs less than reasoning about them.
340pub const ESTIMATE_FINISH_LINES: usize = 128;
341/// Candidate lines verified per sampled file, so a single minified bundle with a
342/// thousand candidate lines cannot dominate the sample.
343pub const ESTIMATE_PER_FILE_LINES: usize = 16;
344
345fn verify_files_streaming(
346    open: &OpenIndex,
347    files: Vec<(u32, LineSet)>,
348    matcher: &LineMatcher,
349    file_filter: &FileFilter,
350    paths_only: bool,
351    budget: Option<usize>,
352    count_only: bool,
353) -> VerifyOutcome {
354    use rayon::prelude::*;
355
356    let content = &open.snapshot;
357
358    // Resolve path + language once per file, drop files the filters reject, and
359    // sort by the path string the results will carry.
360    let mut excluded_by_default = 0usize;
361    let mut accepted: Vec<(u32, String, Language, LineSet)> = files
362        .into_iter()
363        .filter_map(|(file_id, lines)| {
364            let path = content.get_file_path(file_id)?;
365            let lang = Language::from_path(path);
366            let path_str = path.to_string_lossy().into_owned();
367            if file_filter.accept(&path_str, lang) {
368                Some((file_id, path_str, lang, lines))
369            } else {
370                // Counted only when the tier gate is the SOLE reason: a lock file
371                // the `file` filter already rejected must not make the zero-result
372                // hint blame lock files (the 2.0.0 field test's wrong hint).
373                if file_filter.path_admits(&path_str) && file_filter.excluded_by_default(lang) {
374                    excluded_by_default += 1;
375                }
376                None
377            }
378        })
379        .collect();
380    accepted.sort_by(|a, b| a.1.cmp(&b.1));
381
382    let count_substring_only = matcher.is_word_boundary();
383    let substring_only = AtomicUsize::new(0);
384    let kind_label = matcher.kind_label();
385
386    let verify_one = |file_id: u32, path: &str, lang: Language, lines: &LineSet| {
387        let Ok(text) = content.get_file_content(file_id) else {
388            return Vec::new();
389        };
390        let all_lines: Vec<&str> = text.lines().collect();
391        let mut out = Vec::new();
392
393        let mut check = |line_no: usize, line: &str| -> bool {
394            let Some(offset) = matcher.find(line) else {
395                if count_substring_only
396                    && let Some(p) = matcher.literal()
397                    && line.contains(p)
398                {
399                    substring_only.fetch_add(1, Ordering::Relaxed);
400                }
401                return false;
402            };
403            out.push(SearchResult {
404                path: path.to_string(),
405                lang,
406                kind: SymbolKind::Unknown(kind_label.to_string()),
407                symbol: None,
408                span: Span {
409                    start_line: line_no,
410                    end_line: line_no,
411                },
412                // Bounded, and WINDOWED on the match: on a minified bundle this
413                // line is the whole 1.45 MB file, and the first 512 bytes of it
414                // would tell the caller nothing.
415                preview: crate::parsers::preview::line_preview(line, offset),
416                dependencies: None,
417            });
418            true
419        };
420
421        match lines {
422            LineSet::Only(nos) => {
423                let mut last = 0u32;
424                for &line_no in nos {
425                    if line_no == last {
426                        continue;
427                    }
428                    last = line_no;
429                    let idx = line_no as usize;
430                    if idx == 0 || idx > all_lines.len() {
431                        log::debug!(
432                            "Line {} out of bounds (file has {} lines)",
433                            line_no,
434                            all_lines.len()
435                        );
436                        continue;
437                    }
438                    if check(idx, all_lines[idx - 1]) && paths_only {
439                        break;
440                    }
441                }
442            }
443            LineSet::All => {
444                for (i, line) in all_lines.iter().enumerate() {
445                    if check(i + 1, line) && paths_only {
446                        break;
447                    }
448                }
449            }
450        }
451        out
452    };
453
454    // Count-only: no `SearchResult`, no preview, no path clone, no grouping —
455    // one parallel pass that returns two numbers. `(?i)kubernetes --count` on the
456    // Kubernetes checkout spent most of its ~220 ms materialising and grouping
457    // 114k rows it then threw away.
458    if count_only && budget.is_none() {
459        let count_one = |file_id: u32, lines: &LineSet| -> usize {
460            let Ok(text) = content.get_file_content(file_id) else {
461                return 0;
462            };
463            let mut hits = 0usize;
464            let mut check = |line: &str| {
465                if matcher.find(line).is_some() {
466                    hits += 1;
467                    true
468                } else {
469                    if count_substring_only
470                        && let Some(p) = matcher.literal()
471                        && line.contains(p)
472                    {
473                        substring_only.fetch_add(1, Ordering::Relaxed);
474                    }
475                    false
476                }
477            };
478            match lines {
479                LineSet::Only(nos) => {
480                    let all_lines: Vec<&str> = text.lines().collect();
481                    let mut last = 0u32;
482                    for &line_no in nos {
483                        if line_no == last {
484                            continue;
485                        }
486                        last = line_no;
487                        let idx = line_no as usize;
488                        if idx == 0 || idx > all_lines.len() {
489                            continue;
490                        }
491                        if check(all_lines[idx - 1]) && paths_only {
492                            break;
493                        }
494                    }
495                }
496                LineSet::All => {
497                    for line in text.lines() {
498                        if check(line) && paths_only {
499                            break;
500                        }
501                    }
502                }
503            }
504            hits
505        };
506        let (lines, files_hit) = open.pool().install(|| {
507            accepted
508                .par_iter()
509                .map(|(file_id, _, _, lines)| {
510                    let n = count_one(*file_id, lines);
511                    (n, usize::from(n > 0))
512                })
513                .reduce(|| (0, 0), |a, b| (a.0 + b.0, a.1 + b.1))
514        });
515        return VerifyOutcome {
516            results: Vec::new(),
517            exhausted: true,
518            estimated_total: None,
519            substring_only: substring_only.into_inner(),
520            excluded_by_default,
521            counted: Some((if paths_only { files_hit } else { lines }, files_hit)),
522        };
523    }
524
525    let mut results: Vec<SearchResult> = Vec::new();
526    let mut next = 0usize;
527    // The doubling rounds exist so a page can stop early. Without a budget every
528    // file is verified anyway, and each round boundary is a full pool drain that
529    // waits on its slowest file; one round keeps every thread busy to the end.
530    let mut chunk = if budget.is_some() {
531        16usize
532    } else {
533        accepted.len().max(1)
534    };
535    let mut exhausted = true;
536
537    while next < accepted.len() {
538        if let Some(b) = budget
539            && results.len() >= b
540        {
541            exhausted = false;
542            break;
543        }
544        let end = (next + chunk).min(accepted.len());
545        let slice = &accepted[next..end];
546        let round: Vec<Vec<SearchResult>> = open.pool().install(|| {
547            slice
548                .par_iter()
549                .map(|(file_id, path, lang, lines)| verify_one(*file_id, path, *lang, lines))
550                .collect()
551        });
552        for r in round {
553            results.extend(r);
554        }
555        next = end;
556        chunk = (chunk * 2).min(1024);
557    }
558
559    // The page is full but candidates remain. Either finish (cheap) or estimate the
560    // total from a spread sample, so the caller gets a number that is close rather
561    // than a posting-list upper bound that ran 2x high in the field.
562    let mut estimated_total = None;
563    if !exhausted {
564        let remaining = &accepted[next..];
565        // One "unit" is what a result counts: a line normally, a file in paths mode
566        // (`verify_one` stops at the first hit per file there).
567        let unit = |lines: &LineSet| -> Option<usize> {
568            match lines {
569                _ if paths_only => Some(1),
570                LineSet::Only(v) => Some(v.len()),
571                LineSet::All => None,
572            }
573        };
574        let remaining_units = remaining
575            .iter()
576            .try_fold(0usize, |acc, (_, _, _, l)| unit(l).map(|u| acc + u));
577
578        let finish = remaining.len() <= ESTIMATE_SAMPLE_FILES
579            || remaining_units.is_some_and(|u| u <= ESTIMATE_FINISH_LINES);
580        if finish {
581            let round: Vec<Vec<SearchResult>> = open.pool().install(|| {
582                remaining
583                    .par_iter()
584                    .map(|(file_id, path, lang, lines)| verify_one(*file_id, path, *lang, lines))
585                    .collect()
586            });
587            for r in round {
588                results.extend(r);
589            }
590            exhausted = true;
591        } else if let Some(units) = remaining_units {
592            let stride = remaining.len() / ESTIMATE_SAMPLE_FILES;
593            let picks: Vec<&(u32, String, Language, LineSet)> = (0..ESTIMATE_SAMPLE_FILES)
594                .map(|i| &remaining[i * stride])
595                .collect();
596            let (hits, sampled_units) = open.pool().install(|| {
597                picks
598                    .par_iter()
599                    .map(|(file_id, path, lang, lines)| {
600                        let trimmed = match lines {
601                            LineSet::Only(v) if !paths_only => {
602                                LineSet::Only(v[..v.len().min(ESTIMATE_PER_FILE_LINES)].to_vec())
603                            }
604                            LineSet::Only(v) => LineSet::Only(v.clone()),
605                            LineSet::All => LineSet::All,
606                        };
607                        let u = unit(&trimmed).unwrap_or(0);
608                        // Sample hits are counted, never appended: the page must stay
609                        // a contiguous prefix in path order.
610                        (verify_one(*file_id, path, *lang, &trimmed).len(), u)
611                    })
612                    .reduce(|| (0usize, 0usize), |a, b| (a.0 + b.0, a.1 + b.1))
613            });
614            let rate = hits as f64 / sampled_units.max(1) as f64;
615            estimated_total = Some(results.len() + (rate * units as f64).round() as usize);
616        }
617    }
618
619    VerifyOutcome {
620        results,
621        exhausted,
622        estimated_total,
623        substring_only: substring_only.into_inner(),
624        excluded_by_default,
625        counted: None,
626    }
627}
628
629/// Manages query execution against the index
630pub struct QueryEngine {
631    cache: CacheManager,
632    /// The open index, resolved on first use so every phase of one query reads the
633    /// same files. Dropped by [`QueryEngine::reset_open`] after this engine updates
634    /// the index, so the next phase reads the published snapshot.
635    open: std::sync::Mutex<Option<Arc<OpenIndex>>>,
636    /// Update a stale index before answering ([`QueryEngine::with_update`]).
637    /// `None`: answer from the index as it is (the library default).
638    update: Option<crate::auto_update::UpdateOptions>,
639}
640
641impl QueryEngine {
642    /// Create a new query engine with the given cache manager
643    pub fn new(cache: CacheManager) -> Self {
644        Self {
645            cache,
646            open: std::sync::Mutex::new(None),
647            update: None,
648        }
649    }
650
651    /// An engine that brings a stale index up to date before it answers, and
652    /// builds a missing one ([`crate::auto_update`]). Every `rfx` command uses one
653    /// unless `--no-update` is given; [`QueryEngine::new`] answers from the index
654    /// as it is.
655    pub fn with_update(mut self, opts: crate::auto_update::UpdateOptions) -> Self {
656        self.update = Some(opts);
657        self
658    }
659
660    /// Run the automatic update (when this engine has one) with this engine's
661    /// maps dropped first. `Ok(None)` when it has none.
662    fn run_update(&self) -> Result<Option<crate::auto_update::Updated>> {
663        let Some(opts) = self.update else {
664            return Ok(None);
665        };
666        self.reset_open();
667        let updated = crate::auto_update::update_if_stale(&self.cache, &opts)?;
668        if let crate::auto_update::Updated::Skipped(reason) = &updated {
669            log::warn!("Index not updated: {reason}");
670        }
671        Ok(Some(updated))
672    }
673
674    /// Before a search that has no freshness verdict of its own: update the index
675    /// (or, without an update, warn the old way).
676    fn update_first(&self, filter: &QueryFilter) -> Result<()> {
677        match self.run_update()? {
678            Some(crate::auto_update::Updated::Skipped(reason)) if !filter.suppress_output => {
679                output::warn(&format!("⚠️  Index not updated: {reason}"));
680                Ok(())
681            }
682            Some(_) => Ok(()),
683            None => {
684                if !self.cache.exists() {
685                    return Err(crate::errors::ReflexError::IndexNotFound.into());
686                }
687                self.check_index_freshness(filter)
688            }
689        }
690    }
691
692    /// The shared open-index handle (see [`open_index`]).
693    ///
694    /// Typed `CacheCorrupted` on a short or garbled store, so the MCP layer can
695    /// rebuild once and retry.
696    fn open_index(&self) -> Result<Arc<OpenIndex>> {
697        let mut slot = self.open.lock().unwrap_or_else(|e| e.into_inner());
698        if let Some(open) = slot.as_ref() {
699            return Ok(Arc::clone(open));
700        }
701        let open = open_index::get_or_open(&self.cache)?;
702        *slot = Some(Arc::clone(&open));
703        Ok(open)
704    }
705
706    /// Forget this engine's open index, so the next read opens the snapshot the
707    /// manifest names now. Called before this engine updates the index: the old
708    /// maps must not outlive the update (on Windows a mapped file cannot be
709    /// replaced), and the retry must not read them.
710    fn reset_open(&self) {
711        *self.open.lock().unwrap_or_else(|e| e.into_inner()) = None;
712    }
713
714    /// Load dependencies for search results if requested (legacy - per result)
715    /// Deprecated: Use group_and_load_dependencies for file-level grouping
716    fn load_dependencies(&self, results: &mut [SearchResult], include_deps: bool) -> Result<()> {
717        if !include_deps || results.is_empty() {
718            return Ok(());
719        }
720
721        log::debug!("Loading dependencies for {} results", results.len());
722
723        // Create dependency index
724        // Note: We need to pass the workspace root, not the cache directory
725        // The cache path is .reflex/, so its parent is the workspace root (.)
726        let workspace_root = self
727            .cache
728            .path()
729            .parent()
730            .ok_or_else(|| anyhow::anyhow!("Cache path has no parent"))?;
731        let cache_for_deps = CacheManager::new(workspace_root);
732        let dep_index = crate::dependency::DependencyIndex::new(cache_for_deps);
733
734        // Load dependencies for each result
735        for result in results {
736            // Normalize path: strip leading "./" if present
737            let normalized_path = result.path.strip_prefix("./").unwrap_or(&result.path);
738
739            // Get file_id from database by path
740            match self.cache.get_file_id(normalized_path) {
741                Ok(Some(file_id)) => {
742                    log::debug!("Found file_id={} for path={}", file_id, result.path);
743                    // Get dependencies for this file
744                    match dep_index.get_dependencies_info(file_id) {
745                        Ok(dep_infos) => {
746                            log::debug!(
747                                "Loaded {} dependencies for file_id={}",
748                                dep_infos.len(),
749                                file_id
750                            );
751                            if !dep_infos.is_empty() {
752                                result.dependencies = Some(dep_infos);
753                            }
754                        }
755                        Err(e) => {
756                            log::warn!("Failed to get dependencies for file_id={}: {}", file_id, e);
757                        }
758                    }
759                }
760                Ok(None) => {
761                    log::warn!("No file_id found for path: {}", result.path);
762                }
763                Err(e) => {
764                    log::warn!("Failed to get file_id for path {}: {}", result.path, e);
765                }
766            }
767        }
768
769        Ok(())
770    }
771
772    /// Group search results by file and load dependencies at file level
773    /// Returns file-grouped results with dependencies populated once per file
774    fn group_and_load_dependencies(
775        &self,
776        results: Vec<SearchResult>,
777        include_deps: bool,
778        context_lines: usize,
779    ) -> Result<Vec<crate::models::FileGroupedResult>> {
780        use crate::models::{FileGroupedResult, MatchResult};
781        use std::collections::HashMap;
782
783        if results.is_empty() {
784            return Ok(Vec::new());
785        }
786
787        // Group results by file path (preserving language from first match)
788        let mut grouped: HashMap<String, Vec<SearchResult>> = HashMap::new();
789        for result in results {
790            grouped.entry(result.path.clone()).or_default().push(result);
791        }
792
793        // Create dependency index if needed
794        let dep_index = if include_deps {
795            let workspace_root = self
796                .cache
797                .path()
798                .parent()
799                .ok_or_else(|| anyhow::anyhow!("Cache path has no parent"))?;
800            let cache_for_deps = CacheManager::new(workspace_root);
801            Some(crate::dependency::DependencyIndex::new(cache_for_deps))
802        } else {
803            None
804        };
805
806        // The shared index handle, for extracting context lines
807        let open_opt = self.open_index().ok();
808        let content_reader_opt = open_opt.as_deref().map(|o| &o.snapshot);
809
810        // Convert to FileGroupedResult and load dependencies
811        let mut file_results: Vec<FileGroupedResult> = grouped
812            .into_iter()
813            .map(|(path, file_matches)| {
814                // Capture language from first match (all matches in a file share the same language)
815                let language = file_matches.first().map(|r| r.lang).unwrap_or_default();
816
817                // Load dependencies for this file (once per file, not per result)
818                let dependencies = if let Some(dep_idx) = &dep_index {
819                    let normalized_path = path.strip_prefix("./").unwrap_or(&path);
820                    match self.cache.get_file_id(normalized_path) {
821                        Ok(Some(file_id)) => match dep_idx.get_dependencies_info(file_id) {
822                            Ok(dep_infos) if !dep_infos.is_empty() => {
823                                log::debug!(
824                                    "Loaded {} dependencies for file: {}",
825                                    dep_infos.len(),
826                                    path
827                                );
828                                Some(dep_infos)
829                            }
830                            Ok(_) => None,
831                            Err(e) => {
832                                log::warn!("Failed to get dependencies for {}: {}", path, e);
833                                None
834                            }
835                        },
836                        Ok(None) => {
837                            log::warn!("No file_id found for path: {}", path);
838                            None
839                        }
840                        Err(e) => {
841                            log::warn!("Failed to get file_id for path {}: {}", path, e);
842                            None
843                        }
844                    }
845                } else {
846                    None
847                };
848
849                // Array file id (not the database id) for context extraction
850                let file_id_for_context = open_opt.as_deref().and_then(|o| o.file_id_for(&path));
851                log::debug!(
852                    "Context extraction: file={}, file_id={:?}, content_reader={}",
853                    path,
854                    file_id_for_context,
855                    content_reader_opt.is_some()
856                );
857
858                // Convert SearchResults to MatchResults (strip path and dependencies) and extract context
859                let matches: Vec<MatchResult> = file_matches
860                    .into_iter()
861                    .map(|r| {
862                        // Extract context lines if requested (0 = disabled)
863                        let (context_before, context_after) = if context_lines > 0 {
864                            if let (Some(reader), Some(fid)) =
865                                (&content_reader_opt, file_id_for_context)
866                            {
867                                let result = reader
868                                    .get_context_by_line(fid, r.span.start_line, context_lines)
869                                    .unwrap_or_else(|e| {
870                                        log::warn!(
871                                            "Failed to extract context for {}:{}: {}",
872                                            path,
873                                            r.span.start_line,
874                                            e
875                                        );
876                                        (vec![], vec![])
877                                    });
878                                log::debug!(
879                                    "Extracted context for {}:{} - before: {}, after: {}",
880                                    path,
881                                    r.span.start_line,
882                                    result.0.len(),
883                                    result.1.len()
884                                );
885                                result
886                            } else {
887                                if content_reader_opt.is_none() {
888                                    log::debug!(
889                                        "No ContentReader available for context extraction"
890                                    );
891                                }
892                                if file_id_for_context.is_none() {
893                                    log::debug!("No file_id found for {}", path);
894                                }
895                                (vec![], vec![])
896                            }
897                        } else {
898                            (vec![], vec![])
899                        };
900
901                        MatchResult {
902                            kind: r.kind,
903                            symbol: r.symbol,
904                            span: r.span,
905                            preview: r.preview,
906                            context_before,
907                            context_after,
908                        }
909                    })
910                    .collect();
911
912                FileGroupedResult {
913                    path,
914                    language,
915                    dependencies,
916                    matches,
917                }
918            })
919            .collect();
920
921        // Sort by path for deterministic output
922        file_results.sort_by(|a, b| a.path.cmp(&b.path));
923
924        Ok(file_results)
925    }
926
927    /// Execute a query and return matching results with index metadata
928    ///
929    /// This is the preferred method for programmatic/JSON output as it includes
930    /// index freshness information that AI agents can use to decide whether to re-index.
931    pub fn search_with_metadata(
932        &self,
933        pattern: &str,
934        filter: QueryFilter,
935    ) -> Result<QueryResponse> {
936        if self.update.is_none() {
937            return self.search_with_metadata_once(pattern, filter);
938        }
939        let started = std::time::Instant::now();
940        let mut update_time = std::time::Duration::ZERO;
941        let mut notes = Vec::new();
942        let mut update = |notes: &mut Vec<String>| -> Result<bool> {
943            let t = std::time::Instant::now();
944            let updated = self.run_update()?;
945            update_time += t.elapsed();
946            Ok(match updated {
947                Some(crate::auto_update::Updated::Skipped(reason)) => {
948                    notes.push(format!("Index not updated: {reason}"));
949                    false
950                }
951                Some(u) => u.wrote(),
952                None => false,
953            })
954        };
955        if !self.cache.exists() {
956            update(&mut notes)?;
957        }
958        // The search and the check run together; a fresh index pays nothing more.
959        // A stale one is updated and searched again, twice at most (a file can
960        // change while an update runs).
961        let mut response = self.search_with_metadata_once(pattern, filter.clone())?;
962        for _ in 0..2 {
963            if response.status != IndexStatus::Stale || !update(&mut notes)? {
964                break;
965            }
966            response = self.search_with_metadata_once(pattern, filter.clone())?;
967        }
968        response.warnings.extend(notes);
969        if let Some(t) = response.timings.as_mut() {
970            t.update_us = update_time.as_micros() as u64;
971            t.total_us = started.elapsed().as_micros() as u64;
972        }
973        Ok(response)
974    }
975
976    fn search_with_metadata_once(
977        &self,
978        pattern: &str,
979        filter: QueryFilter,
980    ) -> Result<QueryResponse> {
981        log::info!(
982            "Executing query with metadata: pattern='{}', filter={:?}",
983            pattern,
984            filter
985        );
986
987        let started = std::time::Instant::now();
988
989        // Ensure cache exists
990        if !self.cache.exists() {
991            return Err(crate::errors::ReflexError::IndexNotFound.into());
992        }
993
994        // Open (or reuse) the index. A short or garbled store surfaces as a typed
995        // `CacheCorrupted`, so the MCP layer can auto-rebuild once and retry. This
996        // replaces the per-query `validate()`, whose `PRAGMA quick_check` walked the
997        // whole database on every call.
998        self.open_index()?;
999        let open_us = started.elapsed().as_micros() as u64;
1000
1001        // A whole-identifier pattern containing brackets can never match; run it as an
1002        // escaped regex and say so. This lives here, not in the surfaces, so the CLI,
1003        // MCP and HTTP paths cannot disagree about it (1.7.2 fixed only MCP).
1004        let prepared = prepare_literal_pattern(pattern, &filter);
1005        let mut filter = filter;
1006        if prepared.use_regex && !filter.use_regex {
1007            log::debug!(
1008                "Pattern {:?} rewritten to regex {:?}",
1009                pattern,
1010                prepared.effective
1011            );
1012            filter.rewritten_from = Some(pattern.to_string());
1013        }
1014        filter.use_regex = prepared.use_regex;
1015
1016        // The freshness snapshot runs on its own thread while the search runs. It
1017        // costs a few git spawns (or a tree walk outside git) and depends on nothing
1018        // the search produces; only the WORDING is scoped to the result paths, and
1019        // that is derived after both are done. On the CLI, where the memo is cold
1020        // every time, this takes the status phase off the zero-hit floor.
1021        let status_started = std::time::Instant::now();
1022        let (searched, search_done, snapshot) = std::thread::scope(|s| {
1023            let status = s.spawn(|| {
1024                let snapshot = status_cache::snapshot(&self.cache);
1025                (snapshot, status_started.elapsed())
1026            });
1027            let searched = self.search_internal(&prepared.effective, filter.clone());
1028            // Measured before the join, so the status wait is not charged to verify.
1029            let search_done = started.elapsed();
1030            let snapshot = status
1031                .join()
1032                .unwrap_or_else(|panic| std::panic::resume_unwind(panic));
1033            (searched, search_done, snapshot)
1034        });
1035        let Internal {
1036            results,
1037            total_count: total,
1038            total_is_exact,
1039            approx_total,
1040            substring_only,
1041            excluded_by_default,
1042            counted,
1043            candidates_us,
1044            index_path,
1045            warnings: engine_warnings,
1046        } = searched?;
1047        let (snapshot, status_compute) = snapshot;
1048        let snapshot = snapshot?;
1049
1050        // Scoped to the result paths: the index being behind is reported honestly as
1051        // `stale` either way, and a stale index is never trusted; the scope only
1052        // sharpens the reason ("including a file these results came from").
1053        let scope: Vec<String> = results.iter().map(|r| r.path.clone()).collect();
1054        let report = Self::report_from(&snapshot, Some(&scope));
1055        let (status, can_trust_results, warning) =
1056            (report.status, report.can_trust_results, report.warning);
1057        let status_done = started.elapsed();
1058
1059        // Build pagination metadata
1060        use crate::models::PaginationInfo;
1061        let pagination = PaginationInfo {
1062            // Never the verified-so-far number: that is not a total.
1063            total: total_is_exact.then_some(total),
1064            count: results.len(),
1065            offset: filter.offset.unwrap_or(0),
1066            limit: filter.limit,
1067            has_more: !total_is_exact || total > filter.offset.unwrap_or(0) + results.len(),
1068            total_is_exact,
1069            approx_total,
1070        };
1071
1072        // Always use grouped format (group results by file)
1073        // Dependencies are loaded only when include_dependencies is true
1074        let grouped_results = self.group_and_load_dependencies(
1075            results,
1076            filter.include_dependencies,
1077            filter.context_lines,
1078        )?;
1079
1080        let total_elapsed = started.elapsed();
1081        let timings = crate::models::QueryTimings {
1082            index_path,
1083            open_us,
1084            candidates_us,
1085            verify_us: (search_done.as_micros() as u64).saturating_sub(open_us + candidates_us),
1086            status_us: (status_done - search_done).as_micros() as u64,
1087            status_compute_us: status_compute.as_micros() as u64,
1088            group_us: (total_elapsed - status_done).as_micros() as u64,
1089            total_us: total_elapsed.as_micros() as u64,
1090            update_us: 0,
1091        };
1092        log::debug!("Query timings for '{}': {:?}", pattern, timings);
1093
1094        // Why nothing came back: one reason, chosen from the filter in a fixed
1095        // order (see `zero_hint`). Computed only on a zero, so its disk and
1096        // config reads cost nothing on the hot path.
1097        let substring_hint_count = if total == 0 { substring_only } else { None };
1098        let excluded_by_default =
1099            (total == 0 && excluded_by_default > 0).then_some(excluded_by_default);
1100        let zero = if total == 0 {
1101            let config = self.cache.load_index_config().unwrap_or_default();
1102            self.open_index().ok().and_then(|open| {
1103                zero_hint::explain_zero(
1104                    &self.cache.workspace_root(),
1105                    &config,
1106                    &open,
1107                    &filter,
1108                    pattern,
1109                    substring_only,
1110                    excluded_by_default.unwrap_or(0),
1111                    prepared.warning.is_some(),
1112                )
1113            })
1114        } else {
1115            None
1116        };
1117        let (hint, excluded_reason) = match zero {
1118            Some(z) => (Some(z.text), Some(z.reason)),
1119            None => (None, None),
1120        };
1121
1122        Ok(QueryResponse {
1123            ai_instruction: None, // AI instruction is generated by CLI/MCP layer, not here
1124            status,
1125            can_trust_results,
1126            warning,
1127            pagination,
1128            results: grouped_results,
1129            substring_hint_count,
1130            warnings: prepared
1131                .warning
1132                .into_iter()
1133                .chain(engine_warnings)
1134                .collect(),
1135            hint,
1136            excluded_reason,
1137            excluded_by_default,
1138            file_count: counted.map(|(_, files)| files),
1139            timings: filter.collect_timings.then_some(timings),
1140        })
1141    }
1142
1143    /// Execute a query and return matching results (legacy method)
1144    ///
1145    /// This method prints warnings to stderr and returns just the results.
1146    /// For programmatic use, prefer `search_with_metadata()`.
1147    pub fn search(&self, pattern: &str, filter: QueryFilter) -> Result<Vec<SearchResult>> {
1148        log::info!(
1149            "Executing query: pattern='{}', filter={:?}",
1150            pattern,
1151            filter
1152        );
1153
1154        // Update a stale index first (or, without an update, warn the old way).
1155        self.update_first(&filter)?;
1156
1157        // Open (or reuse) the index; corruption surfaces as a typed error.
1158        self.open_index()?;
1159
1160        // Same bracket rewrite as `search_with_metadata`; this surface has nowhere to
1161        // report it, but it must not return a different answer.
1162        let prepared = prepare_literal_pattern(pattern, &filter);
1163        let mut filter = filter;
1164        if prepared.use_regex && !filter.use_regex {
1165            filter.rewritten_from = Some(pattern.to_string());
1166        }
1167        filter.use_regex = prepared.use_regex;
1168
1169        // Execute the search (discard total count - legacy method doesn't use it)
1170        let mut results = self
1171            .search_internal(&prepared.effective, filter.clone())?
1172            .results;
1173
1174        // Load dependencies if requested
1175        self.load_dependencies(&mut results, filter.include_dependencies)?;
1176
1177        Ok(results)
1178    }
1179
1180    /// Internal search implementation (used by both search methods)
1181    /// Returns (results, total_count) where total_count is the count before offset/limit
1182    fn search_internal(&self, pattern: &str, filter: QueryFilter) -> Result<Internal> {
1183        use std::time::{Duration, Instant};
1184
1185        // Start timeout timer if configured
1186        let start_time = Instant::now();
1187        let timeout = if filter.timeout_secs > 0 {
1188            Some(Duration::from_secs(filter.timeout_secs))
1189        } else {
1190            None
1191        };
1192
1193        // KEYWORD DETECTION (early): Check if this is a keyword query that should scan ALL files
1194        // When a user searches for a language keyword (like "class", "function") with --symbols or --kind,
1195        // we interpret it as "list all symbols of that type" and should scan ALL files,
1196        // not just the first 100 candidates from trigram search.
1197        //
1198        // Requirements for keyword query mode:
1199        // 1. Symbol mode active (--symbols or --kind)
1200        // 2. Pattern matches a keyword in ANY supported language
1201        //
1202        // Note: --lang is optional. If specified, language filtering happens naturally in Phase 2/3.
1203        // Empty pattern in symbol mode means "list all symbols of the requested kind" —
1204        // treat it like a keyword query so we scan all files instead of failing the
1205        // broad-query guard or returning zero trigram matches.
1206        let is_keyword_query = if filter.symbols_mode || filter.kind.is_some() {
1207            pattern.is_empty() || ParserFactory::get_all_keywords().contains(&pattern)
1208        } else {
1209            false
1210        };
1211
1212        // KEYWORD-TO-KIND MAPPING: If user searches for a keyword without --kind, infer the kind
1213        // Example: "class" → SymbolKind::Class, "function" → SymbolKind::Function
1214        // This ensures keyword queries return only the relevant symbol type
1215        let mut filter = filter.clone(); // Clone so we can modify it
1216        if is_keyword_query
1217            && filter.kind.is_none()
1218            && let Some(inferred_kind) = Self::keyword_to_kind(pattern)
1219        {
1220            log::info!(
1221                "Keyword '{}' mapped to kind {:?} (auto-inferred)",
1222                pattern,
1223                inferred_kind
1224            );
1225            filter.kind = Some(inferred_kind);
1226        }
1227
1228        // EARLY BROAD QUERY DETECTION (Index Size Check)
1229        // This check happens BEFORE the expensive trigram search to prevent hangs on large indexes
1230        // For very large codebases (like Linux kernel with 62K files), even valid 3-char trigrams
1231        // like "get" can take 10-30+ seconds to search. This early check prevents that hang.
1232        //
1233        // Criteria for early blocking:
1234        // 1. Large index (> 20,000 files) AND
1235        // 2. Short pattern (< 4 chars) AND
1236        // 3. Not using regex (regex has its own trigram extraction) — a regex the
1237        //    engine built from a literal (`ignore_case`, brackets) is judged as
1238        //    that literal AND
1239        // 4. Not a keyword query (keywords are intentionally broad) AND
1240        // 5. Not forced by --force flag
1241        let guarded_literal = filter.rewritten_from.as_deref();
1242        if !filter.force && (!filter.use_regex || guarded_literal.is_some()) && !is_keyword_query {
1243            // Index-wide file count from the open handle. `cache.stats()` here used
1244            // to open SQLite and spawn git on every query.
1245            let total_files = self.open_index()?.file_count();
1246            let pattern = guarded_literal.unwrap_or(pattern);
1247            let pattern_len = pattern.chars().count();
1248
1249            // Thresholds for early blocking:
1250            // - Large index: 20,000+ files (approximately where performance degrades significantly)
1251            // - Short pattern: < 4 chars (3-char trigrams are borderline, < 4 catches edge cases)
1252            // Test overrides allow reducing thresholds for integration tests without creating 20K+ files
1253            let large_index_threshold = filter.test_large_index_threshold.unwrap_or(20_000);
1254            let short_pattern_threshold = filter.test_short_pattern_threshold.unwrap_or(4);
1255
1256            if total_files > large_index_threshold && pattern_len < short_pattern_threshold {
1257                anyhow::bail!(
1258                    "Query too broad - would be expensive to execute on this large index\n\
1259                     \n\
1260                     This index contains {} files, and pattern '{}' ({} characters) is too short for efficient searching.\n\
1261                     On large codebases, short patterns can take 10-30+ seconds to complete.\n\
1262                     \n\
1263                     This query could:\n\
1264                     • Hang for an extended period before returning results\n\
1265                     • Return thousands of results\n\
1266                     • Flood LLM context windows with excessive data\n\
1267                     • Fail entirely\n\
1268                     \n\
1269                     Suggestions to narrow the query:\n\
1270                     • Use a longer, more specific pattern (4+ characters recommended for large indexes)\n\
1271                     • Add a language filter: --lang <language>\n\
1272                     • Add a file filter: --glob <pattern> or --file <path>\n\
1273                     • Use --force to bypass this check if you really need all results\n\
1274                     \n\
1275                     To force execution anyway:\n\
1276                     rfx query \"{}\" --force",
1277                    total_files,
1278                    pattern,
1279                    pattern_len,
1280                    pattern
1281                );
1282            }
1283        }
1284
1285        // Early termination applies to plain list-mode text/regex searches: the
1286        // page is complete once `offset + limit` results exist, in order, and the
1287        // total is reported as inexact. Symbol and AST searches dedup and filter
1288        // after enrichment, so they verify everything; count and no-limit callers
1289        // (`mode:"count"`, `list_locations`, `--count`) pass no limit and also do.
1290        let budget = if filter.symbols_mode
1291            || filter.kind.is_some()
1292            || filter.use_ast
1293            || is_keyword_query
1294            || filter.require_exact_total
1295        {
1296            None
1297        } else {
1298            filter
1299                .limit
1300                .map(|limit| filter.offset.unwrap_or(0).saturating_add(limit))
1301        };
1302
1303        // PHASE 1: Get initial candidates (choose search strategy)
1304        let mut substring_only = None;
1305        let mut excluded_by_default = 0usize;
1306        let mut counted = None;
1307        let mut candidates_us = 0u64;
1308        let mut total_is_exact = true;
1309        let mut approx_total = None;
1310        let index_path;
1311        let engine_warnings;
1312        let mut results = if is_keyword_query {
1313            // A keyword query bypasses the index on purpose.
1314            index_path = IndexPath::Scan;
1315            engine_warnings = Vec::new();
1316            // KEYWORD QUERY MODE: Scan all files (or files of target language if --lang specified)
1317            // This ensures we find ALL classes/functions/etc, not just those in the first 100 trigram matches
1318            if let Some(lang) = filter.language {
1319                log::info!(
1320                    "Keyword query detected for '{}' - scanning all {:?} files (bypassing trigram search)",
1321                    pattern,
1322                    lang
1323                );
1324            } else {
1325                log::info!(
1326                    "Keyword query detected for '{}' - scanning all files (bypassing trigram search)",
1327                    pattern
1328                );
1329            }
1330            self.get_all_language_files(&filter)?
1331        } else {
1332            let (candidates, stats) = if filter.use_regex {
1333                // Regex pattern search with trigram optimization
1334                self.get_regex_candidates(pattern, &filter, timeout.as_ref(), &start_time, budget)?
1335            } else {
1336                // Standard trigram-based full-text search
1337                self.get_trigram_candidates(pattern, &filter, budget)?
1338            };
1339            substring_only = stats.substring_only;
1340            excluded_by_default = stats.excluded_by_default;
1341            counted = stats.counted;
1342            candidates_us = stats.candidates_us;
1343            total_is_exact = stats.exhausted;
1344            approx_total = (!stats.exhausted).then_some(stats.approx_total).flatten();
1345            index_path = stats.index_path;
1346            engine_warnings = stats.warnings;
1347            candidates
1348        };
1349
1350        // EARLY LANGUAGE FILTER: Apply language filtering BEFORE broad query check
1351        // This ensures we only parse files matching the language filter in Phase 2
1352        // Critical for non-keyword queries to work correctly with accurate candidate counts
1353        //
1354        // Skip for keyword queries - those candidates are already pre-filtered by language
1355        if !is_keyword_query && let Some(lang) = filter.language {
1356            let before_count = results.len();
1357            results.retain(|r| r.lang == lang);
1358            log::debug!(
1359                "Language filter ({:?}): reduced {} candidates to {} candidates",
1360                lang,
1361                before_count,
1362                results.len()
1363            );
1364        }
1365
1366        // EARLY GLOB PATTERN FILTER: Apply glob/exclude filtering BEFORE broad query check
1367        // This ensures candidate count reflects actual files that will be parsed
1368        // Critical for queries like: rfx query "index" --symbols --glob "src/**/*.rs"
1369        if !filter.glob_patterns.is_empty() || !filter.exclude_patterns.is_empty() {
1370            // Build include matcher (if patterns specified)
1371            let include_matcher = result::build_glob_set(&filter.glob_patterns, "glob");
1372
1373            // Build exclude matcher (if patterns specified)
1374            let exclude_matcher = result::build_glob_set(&filter.exclude_patterns, "exclude");
1375
1376            // Apply filters
1377            let before_count = results.len();
1378            results.retain(|r| {
1379                // If include patterns specified, path must match at least one
1380                let included = if let Some(ref matcher) = include_matcher {
1381                    matcher.is_match(&r.path)
1382                } else {
1383                    true // No include patterns = include all
1384                };
1385
1386                // If exclude patterns specified, path must NOT match any
1387                let excluded = if let Some(ref matcher) = exclude_matcher {
1388                    matcher.is_match(&r.path)
1389                } else {
1390                    false // No exclude patterns = exclude none
1391                };
1392
1393                included && !excluded
1394            });
1395            log::debug!(
1396                "Glob filter: reduced {} candidates to {} candidates",
1397                before_count,
1398                results.len()
1399            );
1400        }
1401
1402        // Check timeout after Phase 1
1403        if let Some(timeout_duration) = timeout
1404            && start_time.elapsed() > timeout_duration
1405        {
1406            anyhow::bail!(
1407                "Query timeout exceeded ({} seconds).\n\
1408                     \n\
1409                     The query took too long to complete. Try one of these approaches:\n\
1410                     • Use a more specific search pattern (longer patterns = faster search)\n\
1411                     • Add a language filter with --lang to narrow the search space\n\
1412                     • Add a file filter with --file to search specific directories\n\
1413                     • Increase the timeout with --timeout <seconds>\n\
1414                     \n\
1415                     Example: rfx query \"{}\" --lang rust --timeout 60",
1416                filter.timeout_secs,
1417                pattern
1418            );
1419        }
1420
1421        // BROAD QUERY DETECTION: Check if query is too expensive BEFORE parsing
1422        // This protects LLM users from accidentally running expensive queries that flood context windows
1423        if !filter.force {
1424            let candidate_count = results.len();
1425            let pattern_len = pattern.chars().count();
1426
1427            // Condition 1: Pattern too short (< 3 chars can't use trigram optimization efficiently)
1428            // Exception: Allow short keyword queries (e.g., "fn", "if") since they scan all language files
1429            let is_short_pattern = pattern_len < 3 && !filter.use_regex && !is_keyword_query;
1430
1431            // Condition 2: AST query without glob restriction on large codebases
1432            // Allow on small codebases (< 100 files) but require glob for larger ones
1433            let is_broad_ast =
1434                filter.use_ast && filter.glob_patterns.is_empty() && candidate_count >= 100;
1435
1436            // Condition 3: Query-type-aware threshold for symbol/AST parsing
1437            // Different thresholds based on actual performance characteristics:
1438            // - AST without glob: 100 files (allow small codebases, block large ones)
1439            // - AST with glob: 10,000 files (~5 seconds max)
1440            // - Keyword queries: 20,000 files (~3 seconds max) - scan all files of language
1441            // - Trigram-filtered symbols: 50,000 files (~5 seconds max) - very fast due to trigram filtering
1442            let threshold = if filter.use_ast && filter.glob_patterns.is_empty() {
1443                100 // AST without glob - allow small codebases
1444            } else if filter.use_ast {
1445                10_000 // AST with glob restriction
1446            } else if is_keyword_query {
1447                20_000 // Keyword queries (e.g., "class", "function")
1448            } else {
1449                50_000 // Trigram-filtered symbol queries
1450            };
1451
1452            let has_many_candidates = candidate_count > threshold
1453                && (filter.symbols_mode || filter.kind.is_some() || filter.use_ast);
1454
1455            if is_short_pattern || has_many_candidates || is_broad_ast {
1456                let reason = if is_short_pattern {
1457                    format!(
1458                        "Pattern '{}' is too short ({} characters). Short patterns bypass trigram optimization and require scanning many files.",
1459                        pattern, pattern_len
1460                    )
1461                } else if is_broad_ast {
1462                    format!(
1463                        "AST query without --glob restriction will scan the entire codebase ({} files). AST queries are SLOW (500ms-10s+).",
1464                        candidate_count
1465                    )
1466                } else if is_keyword_query {
1467                    format!(
1468                        "Keyword query '{}' matched {} files. This query scans all files of the target language, which will take significant time and produce excessive results.",
1469                        pattern, candidate_count
1470                    )
1471                } else {
1472                    format!(
1473                        "Query matched {} files. Parsing this many files with --symbols or --kind will take significant time and produce excessive results.",
1474                        candidate_count
1475                    )
1476                };
1477
1478                let suggestions = if is_short_pattern {
1479                    vec![
1480                        "• Use a longer, more specific pattern (3+ characters recommended)",
1481                        "• Add a language filter: --lang <language>",
1482                        "• Add a file path filter: --file <path> or --glob <pattern>",
1483                        "• Use --force to bypass this check if you really need all results",
1484                    ]
1485                } else if is_broad_ast {
1486                    vec![
1487                        "• Add --glob to restrict AST query to specific files: --glob 'src/**/*.rs'",
1488                        "• Use --symbols instead (10-100x faster in 95% of cases)",
1489                        "• Use --force to bypass this check if you need a full codebase scan",
1490                    ]
1491                } else if is_keyword_query {
1492                    vec![
1493                        "• Add a language filter to reduce files scanned: --lang <language>",
1494                        "• Add glob patterns to search specific directories: --glob 'src/**/*.rs'",
1495                        "• Add --kind to filter to specific symbol types: --kind function",
1496                        "• Use a more specific pattern instead of a keyword",
1497                        "• Use --force to bypass this check if you need all results",
1498                    ]
1499                } else {
1500                    vec![
1501                        "• Add a language filter to reduce candidate set: --lang <language>",
1502                        "• Add glob patterns to search specific directories: --glob 'src/**/*.rs'",
1503                        "• Use a more specific search pattern",
1504                        "• Use --force to bypass this check if you need all results",
1505                    ]
1506                };
1507
1508                // Build the command snippet showing current flags
1509                let mut cmd_flags = String::new();
1510                if filter.symbols_mode {
1511                    cmd_flags.push_str("--symbols ");
1512                }
1513                if let Some(ref lang) = filter.language {
1514                    cmd_flags.push_str(&format!("--lang {:?} ", lang));
1515                }
1516                if let Some(ref kind) = filter.kind {
1517                    cmd_flags.push_str(&format!("--kind {:?} ", kind));
1518                }
1519                if filter.use_ast {
1520                    cmd_flags.push_str("--ast ");
1521                }
1522
1523                anyhow::bail!(
1524                    "Query too broad - would be expensive to execute\n\
1525                     \n\
1526                     {}\n\
1527                     \n\
1528                     This query could:\n\
1529                     • Hang for an extended period before returning results\n\
1530                     • Return thousands of results\n\
1531                     • Flood LLM context windows with excessive data\n\
1532                     • Fail entirely\n\
1533                     \n\
1534                     Suggestions to narrow the query:\n\
1535                     {}\n\
1536                     \n\
1537                     To force execution anyway:\n\
1538                     rfx query \"{}\" --force {}",
1539                    reason,
1540                    suggestions.join("\n             "),
1541                    pattern,
1542                    cmd_flags
1543                );
1544            }
1545        }
1546
1547        // DETERMINISTIC SORTING: Sort candidates early for deterministic results
1548        // This ensures results are always returned in the same order
1549        if filter.symbols_mode || filter.kind.is_some() || filter.use_ast {
1550            results.sort_by(|a, b| {
1551                a.path
1552                    .cmp(&b.path)
1553                    .then_with(|| a.span.start_line.cmp(&b.span.start_line))
1554            });
1555
1556            // Warn if many candidates need parsing (helps users refine queries)
1557            let candidate_count = results.len();
1558            if candidate_count > 1000 && !filter.suppress_output {
1559                output::warn(&format!(
1560                    "Pattern '{}' matched {} files - parsing may take some time. Consider using --file, --glob, or a more specific pattern to narrow the search.",
1561                    pattern, candidate_count
1562                ));
1563            } else if candidate_count > 100 {
1564                log::info!(
1565                    "Parsing {} candidate files for symbol extraction",
1566                    candidate_count
1567                );
1568            }
1569        }
1570
1571        // PHASE 2: Enrich with symbol information or AST pattern matching (if needed)
1572        if filter.use_ast {
1573            // AST pattern matching: Execute Tree-sitter query on candidate files
1574            results = self.enrich_with_ast(results, pattern, filter.language)?;
1575        } else if filter.symbols_mode || filter.kind.is_some() {
1576            // Symbol enrichment: Parse candidate files and extract symbol definitions
1577            results = self.enrich_with_symbols(results, pattern, &filter, is_keyword_query)?;
1578        }
1579
1580        // PHASE 3: Apply post-enrichment filters
1581        // Note: Language and glob filters are applied in Phase 1 (before broad query check)
1582        // Only kind, file_pattern, and exact filters are applied here
1583
1584        // Deduplicate symbols: the same source location can be emitted as both
1585        // Function and Method by some parsers.  Keep the first hit for each
1586        // (path, start_line, symbol_name) triple so --kind function doesn't
1587        // return the same definition twice.
1588        if filter.symbols_mode || filter.kind.is_some() {
1589            let mut seen = std::collections::HashSet::<(String, usize, Option<String>)>::new();
1590            results.retain(|r| seen.insert((r.path.clone(), r.span.start_line, r.symbol.clone())));
1591        }
1592
1593        // Apply kind filter (only relevant for symbol searches)
1594        // Special case: --kind function also includes methods (methods are functions in classes)
1595        if let Some(ref kind) = filter.kind {
1596            results.retain(|r| {
1597                if matches!(kind, SymbolKind::Function) {
1598                    // When searching for functions, also include methods
1599                    matches!(r.kind, SymbolKind::Function | SymbolKind::Method)
1600                } else {
1601                    r.kind == *kind
1602                }
1603            });
1604        }
1605
1606        // Apply file path filter (substring match)
1607        if let Some(ref file_pattern) = filter.file_pattern {
1608            results.retain(|r| r.path.contains(file_pattern));
1609        }
1610
1611        // Apply exact name filter (only for symbol searches)
1612        if filter.exact && filter.symbols_mode {
1613            results.retain(|r| r.symbol.as_deref() == Some(pattern));
1614        }
1615
1616        // Expand symbol bodies if requested
1617        // Works for both symbol-mode and regex searches (if regex matched a symbol definition)
1618        if filter.expand {
1619            // Fetch full symbol bodies from the shared content store
1620            if let Ok(open) = self.open_index() {
1621                let content_reader = &open.snapshot;
1622                for result in &mut results {
1623                    // Only expand if the result has a meaningful span (not just a single line)
1624                    if result.span.start_line < result.span.end_line {
1625                        // Find the file_id for this result's path
1626                        if let Some(file_id) = open.file_id_for(&result.path) {
1627                            // Fetch the full span content
1628                            if let Ok(content) = content_reader.get_file_content(file_id) {
1629                                let lines: Vec<&str> = content.lines().collect();
1630                                let start_idx = result.span.start_line.saturating_sub(1);
1631                                let end_idx = result.span.end_line.min(lines.len());
1632
1633                                if start_idx < end_idx {
1634                                    let full_body = lines[start_idx..end_idx].join("\n");
1635                                    // Expand shows more than a preview, but not an
1636                                    // unbounded amount: on a minified file this is
1637                                    // the entire bundle.
1638                                    result.preview =
1639                                        crate::parsers::preview::expand_preview(&full_body);
1640                                }
1641                            }
1642                        }
1643                    }
1644                }
1645            }
1646        }
1647
1648        // Step 4: Deduplicate by path if paths-only mode
1649        if filter.paths_only {
1650            use std::collections::HashSet;
1651            let mut seen_paths = HashSet::new();
1652            results.retain(|r| seen_paths.insert(r.path.clone()));
1653        }
1654
1655        // Drop text-tier results when the caller asked for code only. Applied BEFORE
1656        // the total is captured, so pagination counts what the caller will actually
1657        // receive rather than what was found and then discarded.
1658        results.retain(|r| {
1659            filter::tier_admits(
1660                r.lang,
1661                filter.language,
1662                filter.exclude_text,
1663                filter.include_locks,
1664                filter.include_generated,
1665            )
1666        });
1667
1668        // Step 5: Sort results deterministically (by path, then line number)
1669        results.sort_by(|a, b| {
1670            a.path
1671                .cmp(&b.path)
1672                .then_with(|| a.span.start_line.cmp(&b.span.start_line))
1673        });
1674
1675        // Capture total count AFTER all filtering but BEFORE pagination (offset/limit)
1676        // This is the total number of results the user can paginate through. In
1677        // count-only mode nothing was materialised and the verifier's count is it.
1678        let total_count = counted.map(|(lines, _)| lines).unwrap_or(results.len());
1679
1680        // Step 5.5: Apply offset (pagination)
1681        if let Some(offset) = filter.offset {
1682            if offset < results.len() {
1683                results = results.into_iter().skip(offset).collect();
1684            } else {
1685                // Offset beyond results - return empty
1686                results.clear();
1687            }
1688        }
1689
1690        // Step 6: Apply limit
1691        if let Some(limit) = filter.limit {
1692            results.truncate(limit);
1693        }
1694
1695        log::info!(
1696            "Query returned {} results (total before pagination: {})",
1697            results.len(),
1698            total_count
1699        );
1700
1701        Ok(Internal {
1702            results,
1703            total_count,
1704            total_is_exact,
1705            approx_total,
1706            substring_only,
1707            excluded_by_default,
1708            counted,
1709            candidates_us,
1710            index_path,
1711            warnings: engine_warnings,
1712        })
1713    }
1714
1715    /// Search for symbols by exact name match
1716    pub fn find_symbol(&self, name: &str) -> Result<Vec<SearchResult>> {
1717        let filter = QueryFilter {
1718            symbols_mode: true,
1719            ..Default::default()
1720        };
1721        self.search(name, filter)
1722    }
1723
1724    /// Search using a Tree-sitter AST pattern
1725    pub fn search_ast(&self, pattern: &str, lang: Option<Language>) -> Result<Vec<SearchResult>> {
1726        let filter = QueryFilter {
1727            language: lang,
1728            use_ast: true,
1729            ..Default::default()
1730        };
1731
1732        self.search(pattern, filter)
1733    }
1734
1735    /// Execute AST query on all indexed files (no trigram filtering)
1736    ///
1737    /// WARNING: This method scans the entire codebase (500ms-2s+).
1738    /// In 95% of cases, use --symbols instead which is 10-100x faster.
1739    ///
1740    /// # Algorithm
1741    /// 1. Get all indexed files for the specified language
1742    /// 2. Apply glob/exclude filters to reduce file set
1743    /// 3. Load file contents for all matching files
1744    /// 4. Execute AST query pattern using Tree-sitter
1745    /// 5. Apply remaining filters and return results
1746    ///
1747    /// # Performance
1748    /// - Parses entire codebase (not just trigram candidates)
1749    /// - Expected: 500ms-2s for medium codebases, 2-10s for large codebases
1750    /// - Use --glob to limit scope for better performance
1751    ///
1752    /// # Requirements
1753    /// - Language must be specified (AST queries are language-specific)
1754    /// - AST pattern must be valid S-expression syntax
1755    pub fn search_ast_all_files(
1756        &self,
1757        ast_pattern: &str,
1758        filter: QueryFilter,
1759    ) -> Result<Vec<SearchResult>> {
1760        log::info!(
1761            "Executing AST query on all files: pattern='{}', filter={:?}",
1762            ast_pattern,
1763            filter
1764        );
1765
1766        // Require language for AST queries
1767        let lang = filter.language.ok_or_else(|| anyhow::anyhow!(
1768            "Language must be specified for AST pattern matching. Use --lang to specify the language.\n\
1769             \n\
1770             Example: rfx query \"(function_definition) @fn\" --ast --lang python"
1771        ))?;
1772
1773        // Update a stale index first (or, without an update, warn the old way).
1774        self.update_first(&filter)?;
1775
1776        // The shared content store
1777        let open = self.open_index()?;
1778        let content_reader = &open.snapshot;
1779
1780        // Build glob matchers ONCE before file iteration (performance optimization)
1781        let include_matcher = result::build_glob_set(&filter.glob_patterns, "glob");
1782
1783        let exclude_matcher = result::build_glob_set(&filter.exclude_patterns, "exclude");
1784
1785        // Get all files matching the language and glob filters
1786        let mut candidates: Vec<SearchResult> = Vec::new();
1787
1788        for file_id in content_reader.live_ids() {
1789            let file_path = match content_reader.get_file_path(file_id) {
1790                Some(p) => p,
1791                None => continue,
1792            };
1793
1794            // Detect language from file extension
1795            let detected_lang = Language::from_path(file_path);
1796
1797            // Filter by language
1798            if detected_lang != lang {
1799                continue;
1800            }
1801
1802            let file_path_str = file_path.to_string_lossy().to_string();
1803
1804            // Apply glob/exclude filters BEFORE loading content (performance optimization)
1805            let included = include_matcher
1806                .as_ref()
1807                .is_none_or(|m| m.is_match(&file_path_str));
1808            let excluded = exclude_matcher
1809                .as_ref()
1810                .is_some_and(|m| m.is_match(&file_path_str));
1811
1812            if !included || excluded {
1813                continue;
1814            }
1815
1816            // Create a dummy candidate for this file (AST query will replace it)
1817            candidates.push(SearchResult {
1818                path: file_path_str,
1819                lang: detected_lang,
1820                span: Span {
1821                    start_line: 1,
1822                    end_line: 1,
1823                },
1824                symbol: None,
1825                kind: SymbolKind::Unknown("ast_query".to_string()),
1826                preview: String::new(),
1827                dependencies: None,
1828            });
1829        }
1830
1831        log::info!(
1832            "AST query scanning {} files for language {:?}",
1833            candidates.len(),
1834            lang
1835        );
1836
1837        // BROAD QUERY DETECTION: Block large AST queries without glob restriction
1838        // Allow small codebases (<100 files) but require --glob for larger ones
1839        if !filter.force && filter.glob_patterns.is_empty() && candidates.len() >= 100 {
1840            anyhow::bail!(
1841                "Query too broad - would be expensive to execute\n\
1842                 \n\
1843                 AST query without --glob restriction will scan the ENTIRE codebase ({} files). AST queries are SLOW (500ms-10s+).\n\
1844                 \n\
1845                 This query could:\n\
1846                 • Hang for an extended period before returning results\n\
1847                 • Return thousands of results\n\
1848                 • Flood LLM context windows with excessive data\n\
1849                 • Fail entirely\n\
1850                 \n\
1851                 Suggestions to narrow the query:\n\
1852                 • Add --glob to restrict AST query to specific files: --glob 'src/**/*.rs'\n\
1853                 • Use --symbols instead (10-100x faster in 95% of cases)\n\
1854                 • Use --force to bypass this check if you need a full codebase scan\n\
1855                 \n\
1856                 To force execution anyway:\n\
1857                 rfx query \"{}\" --force --ast --lang {:?}",
1858                candidates.len(),
1859                ast_pattern,
1860                lang
1861            );
1862        }
1863
1864        if candidates.is_empty() {
1865            if !filter.suppress_output {
1866                output::warn(&format!(
1867                    "No files found for language {:?}. Check your language filter or glob patterns.",
1868                    lang
1869                ));
1870            }
1871            return Ok(Vec::new());
1872        }
1873
1874        // Execute the AST query on all candidate files
1875        // This will load file contents and parse them with tree-sitter
1876        let mut results = self.enrich_with_ast(candidates, ast_pattern, filter.language)?;
1877
1878        log::debug!("AST query found {} matches before filtering", results.len());
1879
1880        // Apply remaining filters (same as search_internal Phase 3)
1881
1882        // Apply kind filter
1883        if let Some(ref kind) = filter.kind {
1884            results.retain(|r| {
1885                if matches!(kind, SymbolKind::Function) {
1886                    matches!(r.kind, SymbolKind::Function | SymbolKind::Method)
1887                } else {
1888                    r.kind == *kind
1889                }
1890            });
1891        }
1892
1893        // Note: exact filter doesn't make sense for AST queries (pattern is S-expression, not symbol name)
1894
1895        // Expand symbol bodies if requested
1896        if filter.expand
1897            && let Ok(open) = self.open_index()
1898        {
1899            let content_reader = &open.snapshot;
1900            {
1901                for result in &mut results {
1902                    if result.span.start_line < result.span.end_line
1903                        && let Some(file_id) = open.file_id_for(&result.path)
1904                        && let Ok(content) = content_reader.get_file_content(file_id)
1905                    {
1906                        let lines: Vec<&str> = content.lines().collect();
1907                        let start_idx = result.span.start_line.saturating_sub(1);
1908                        let end_idx = result.span.end_line.min(lines.len());
1909
1910                        if start_idx < end_idx {
1911                            let full_body = lines[start_idx..end_idx].join("\n");
1912                            // Bounded: on a minified file this body is the whole bundle.
1913                            result.preview = crate::parsers::preview::expand_preview(&full_body);
1914                        }
1915                    }
1916                }
1917            }
1918        }
1919
1920        // Deduplicate by path if paths-only mode
1921        if filter.paths_only {
1922            use std::collections::HashSet;
1923            let mut seen_paths = HashSet::new();
1924            results.retain(|r| seen_paths.insert(r.path.clone()));
1925        }
1926
1927        // Drop text-tier results when the caller asked for code only. Applied BEFORE
1928        // the total is captured, so pagination counts what the caller will actually
1929        // receive rather than what was found and then discarded.
1930        results.retain(|r| {
1931            filter::tier_admits(
1932                r.lang,
1933                filter.language,
1934                filter.exclude_text,
1935                filter.include_locks,
1936                filter.include_generated,
1937            )
1938        });
1939
1940        // Sort results deterministically
1941        results.sort_by(|a, b| {
1942            a.path
1943                .cmp(&b.path)
1944                .then_with(|| a.span.start_line.cmp(&b.span.start_line))
1945        });
1946
1947        // Apply offset (pagination)
1948        if let Some(offset) = filter.offset {
1949            if offset < results.len() {
1950                results = results.into_iter().skip(offset).collect();
1951            } else {
1952                results.clear();
1953            }
1954        }
1955
1956        // Apply limit
1957        if let Some(limit) = filter.limit {
1958            results.truncate(limit);
1959        }
1960
1961        log::info!("AST query returned {} results", results.len());
1962
1963        // Load dependencies if requested
1964        self.load_dependencies(&mut results, filter.include_dependencies)?;
1965
1966        Ok(results)
1967    }
1968
1969    /// Search using AST pattern with separate text pattern for trigram filtering
1970    ///
1971    /// This allows efficient AST queries by:
1972    /// 1. Using text_pattern for Phase 1 trigram filtering (narrows to candidate files)
1973    /// 2. Using ast_pattern for Phase 2 AST matching (structure-aware filtering)
1974    ///
1975    /// # Example
1976    /// ```ignore
1977    /// // Find async functions: trigram search for "fn ", AST match for function_item
1978    /// engine.search_ast_with_text_filter("fn ", "(function_item (async))", filter)?;
1979    /// ```
1980    pub fn search_ast_with_text_filter(
1981        &self,
1982        text_pattern: &str,
1983        ast_pattern: &str,
1984        filter: QueryFilter,
1985    ) -> Result<Vec<SearchResult>> {
1986        log::info!(
1987            "Executing AST query with text filter: text='{}', ast='{}', filter={:?}",
1988            text_pattern,
1989            ast_pattern,
1990            filter
1991        );
1992
1993        // Update a stale index first (or, without an update, warn the old way).
1994        self.update_first(&filter)?;
1995
1996        // Start timeout timer if configured
1997        use std::time::{Duration, Instant};
1998        let start_time = Instant::now();
1999        let timeout = if filter.timeout_secs > 0 {
2000            Some(Duration::from_secs(filter.timeout_secs))
2001        } else {
2002            None
2003        };
2004
2005        // PHASE 1: Get initial candidates using text pattern (trigram search)
2006        let candidates = if filter.use_regex {
2007            self.get_regex_candidates(text_pattern, &filter, timeout.as_ref(), &start_time, None)?
2008                .0
2009        } else {
2010            self.get_trigram_candidates(text_pattern, &filter, None)?.0
2011        };
2012
2013        log::debug!("Phase 1 found {} candidate locations", candidates.len());
2014
2015        // PHASE 2: Execute AST query on candidates
2016        let mut results = self.enrich_with_ast(candidates, ast_pattern, filter.language)?;
2017
2018        log::debug!("Phase 2 AST matching found {} results", results.len());
2019
2020        // PHASE 3: Apply filters
2021        if let Some(lang) = filter.language {
2022            results.retain(|r| r.lang == lang);
2023        }
2024
2025        if let Some(ref kind) = filter.kind {
2026            results.retain(|r| {
2027                if matches!(kind, SymbolKind::Function) {
2028                    matches!(r.kind, SymbolKind::Function | SymbolKind::Method)
2029                } else {
2030                    r.kind == *kind
2031                }
2032            });
2033        }
2034
2035        if let Some(ref file_pattern) = filter.file_pattern {
2036            results.retain(|r| r.path.contains(file_pattern));
2037        }
2038
2039        // Apply glob pattern filters (same logic as in search_internal)
2040        if !filter.glob_patterns.is_empty() || !filter.exclude_patterns.is_empty() {
2041            let include_matcher = result::build_glob_set(&filter.glob_patterns, "glob");
2042
2043            let exclude_matcher = result::build_glob_set(&filter.exclude_patterns, "exclude");
2044
2045            results.retain(|r| {
2046                let included = include_matcher.as_ref().is_none_or(|m| m.is_match(&r.path));
2047                let excluded = exclude_matcher
2048                    .as_ref()
2049                    .is_some_and(|m| m.is_match(&r.path));
2050                included && !excluded
2051            });
2052        }
2053
2054        if filter.exact && filter.symbols_mode {
2055            results.retain(|r| r.symbol.as_deref() == Some(text_pattern));
2056        }
2057
2058        // Expand symbol bodies if requested
2059        if filter.expand
2060            && let Ok(open) = self.open_index()
2061        {
2062            let content_reader = &open.snapshot;
2063            {
2064                for result in &mut results {
2065                    if result.span.start_line < result.span.end_line
2066                        && let Some(file_id) = open.file_id_for(&result.path)
2067                        && let Ok(content) = content_reader.get_file_content(file_id)
2068                    {
2069                        let lines: Vec<&str> = content.lines().collect();
2070                        let start_idx = result.span.start_line.saturating_sub(1);
2071                        let end_idx = result.span.end_line.min(lines.len());
2072
2073                        if start_idx < end_idx {
2074                            let full_body = lines[start_idx..end_idx].join("\n");
2075                            // Bounded: on a minified file this body is the whole bundle.
2076                            result.preview = crate::parsers::preview::expand_preview(&full_body);
2077                        }
2078                    }
2079                }
2080            }
2081        }
2082
2083        // Drop text-tier results when the caller asked for code only. Applied BEFORE
2084        // the total is captured, so pagination counts what the caller will actually
2085        // receive rather than what was found and then discarded.
2086        results.retain(|r| {
2087            filter::tier_admits(
2088                r.lang,
2089                filter.language,
2090                filter.exclude_text,
2091                filter.include_locks,
2092                filter.include_generated,
2093            )
2094        });
2095
2096        // Sort results deterministically
2097        results.sort_by(|a, b| {
2098            a.path
2099                .cmp(&b.path)
2100                .then_with(|| a.span.start_line.cmp(&b.span.start_line))
2101        });
2102
2103        // Apply offset (pagination)
2104        if let Some(offset) = filter.offset {
2105            if offset < results.len() {
2106                results = results.into_iter().skip(offset).collect();
2107            } else {
2108                results.clear();
2109            }
2110        }
2111
2112        // Apply limit
2113        if let Some(limit) = filter.limit {
2114            results.truncate(limit);
2115        }
2116
2117        log::info!("AST query returned {} results", results.len());
2118
2119        Ok(results)
2120    }
2121
2122    /// List all symbols of a specific kind
2123    pub fn list_by_kind(&self, kind: SymbolKind) -> Result<Vec<SearchResult>> {
2124        let filter = QueryFilter {
2125            kind: Some(kind),
2126            symbols_mode: true,
2127            ..Default::default()
2128        };
2129
2130        self.search("*", filter)
2131    }
2132
2133    /// Enrich text match candidates with symbol information by parsing files
2134    ///
2135    /// Takes a list of text match candidates and extracts symbol information at those locations.
2136    ///
2137    /// # Algorithm
2138    /// 1. Group candidates by file_id for efficient processing
2139    /// 2. Parse each file with tree-sitter to extract ALL symbols
2140    /// 3. Filter symbols based on matching strategy:
2141    ///    - If use_regex=true: Extract symbols whose line spans overlap with candidate locations
2142    ///    - If use_contains=true: Filter symbols by substring match on symbol name
2143    ///    - Default: Filter symbols by exact name match
2144    /// 4. Return filtered symbol results
2145    ///
2146    /// # Performance
2147    /// Only parses files that have text matches, so typically 10-100 files
2148    /// instead of the entire codebase (62K+ files).
2149    ///
2150    /// # Optimizations
2151    /// 1. Language filtering: Skips files with unsupported languages (no parsers)
2152    /// 2. Parallel processing: Uses Rayon to parse files concurrently across CPU cores
2153    fn enrich_with_symbols(
2154        &self,
2155        candidates: Vec<SearchResult>,
2156        pattern: &str,
2157        filter: &QueryFilter,
2158        keyword_query: bool,
2159    ) -> Result<Vec<SearchResult>> {
2160        use rayon::prelude::*;
2161        use std::collections::{HashMap, HashSet};
2162
2163        // The shared index handle (content store + file-id map + meta.db connection)
2164        let open = self.open_index()?;
2165        let content_reader = &open.snapshot;
2166
2167        // Group candidates by file, filtering out unsupported languages
2168        let mut files_by_path: HashMap<String, Vec<SearchResult>> = HashMap::new();
2169        let mut skipped_unsupported = 0;
2170
2171        for candidate in candidates {
2172            // Skip files with unsupported languages (no parser available)
2173            if !candidate.lang.is_supported() {
2174                skipped_unsupported += 1;
2175                continue;
2176            }
2177
2178            files_by_path
2179                .entry(candidate.path.clone())
2180                .or_default()
2181                .push(candidate);
2182        }
2183
2184        let total_files = files_by_path.len();
2185        log::debug!(
2186            "Processing {} candidate files for symbol enrichment (skipped {} unsupported language files)",
2187            total_files,
2188            skipped_unsupported
2189        );
2190
2191        // Warn if pattern is very broad (may take time to parse all files)
2192        if total_files > 1000 && !filter.suppress_output {
2193            output::warn(&format!(
2194                "Pattern '{}' matched {} files. This may take some time to parse. Consider using a more specific pattern or adding --lang/--file filters to narrow the search.",
2195                pattern, total_files
2196            ));
2197        }
2198
2199        // Parse on the shared query pool, sized from `[performance] parallel_threads`
2200        let pool = open.pool();
2201
2202        // PHASE 2a: pre-filter — skip files where EVERY occurrence of the pattern is
2203        // inside a comment or a string literal, so tree-sitter never parses them.
2204        //
2205        // Only the candidate lines are examined: the trigram pass already verified
2206        // that those are the lines holding the pattern, so scanning the whole file
2207        // (as this did before 2.0.0, serially) found nothing more. A definition
2208        // line is always a candidate line, so a file that defines the symbol is
2209        // never skipped. Two cases keep the old outcome exactly:
2210        // * keyword queries carry dummy line-1 candidates from
2211        //   `get_all_language_files`, so there is nothing to examine;
2212        // * a regex pattern's source text never occurs literally, so the old
2213        //   `line.find(pattern)` skipped nothing.
2214        let files_to_skip: HashSet<String> = if keyword_query || filter.use_regex {
2215            HashSet::new()
2216        } else {
2217            pool.install(|| {
2218                files_by_path
2219                    .par_iter()
2220                    .filter_map(|(file_path, cands)| {
2221                        let lang = Language::from_path(std::path::Path::new(file_path));
2222                        let line_filter = crate::line_filter::get_filter(lang)?;
2223                        let file_id = open.file_id_for(file_path)?;
2224                        let content = content_reader.get_file_content(file_id).ok()?;
2225                        let all_lines: Vec<&str> = content.lines().collect();
2226
2227                        let mut wanted: Vec<usize> =
2228                            cands.iter().map(|c| c.span.start_line).collect();
2229                        wanted.sort_unstable();
2230                        wanted.dedup();
2231
2232                        let mut saw_occurrence = false;
2233                        for line_no in wanted {
2234                            let Some(line) = line_no.checked_sub(1).and_then(|i| all_lines.get(i))
2235                            else {
2236                                continue;
2237                            };
2238                            let mut search_start = 0;
2239                            while let Some(pos) = line[search_start..].find(pattern) {
2240                                saw_occurrence = true;
2241                                let at = search_start + pos;
2242                                if !line_filter.is_in_comment(line, at)
2243                                    && !line_filter.is_in_string(line, at)
2244                                {
2245                                    // In code: this file must be parsed.
2246                                    return None;
2247                                }
2248                                search_start = at + pattern.len();
2249                            }
2250                        }
2251                        // Only skip when there WAS an occurrence and none was in code.
2252                        saw_occurrence.then(|| {
2253                            log::debug!(
2254                                "Pre-filter: Skipping {} (all matches in comments/strings)",
2255                                file_path
2256                            );
2257                            file_path.clone()
2258                        })
2259                    })
2260                    .collect()
2261            })
2262        };
2263
2264        let files_to_process: Vec<String> = files_by_path
2265            .keys()
2266            .filter(|p| !files_to_skip.contains(p.as_str()))
2267            .cloned()
2268            .collect();
2269
2270        log::debug!(
2271            "Pre-filter: Skipped {} files where all matches are in comments/strings (parsing {} files)",
2272            files_to_skip.len(),
2273            files_to_process.len()
2274        );
2275
2276        // Symbol cache lookup, on the handle's shared connection. The keys are the
2277        // candidates' `files.hash` (the stored bytes), from a query restricted to
2278        // the candidate paths.
2279        let mut conn = open.meta_conn()?;
2280        let rows = crate::cache::CacheManager::file_rows_on(&conn, &files_to_process)
2281            .context("Failed to load file hashes")?;
2282        log::debug!("Loaded {} file rows for symbol cache lookups", rows.len());
2283
2284        let file_lookup_tuples: Vec<(i64, String, String)> = files_to_process
2285            .iter()
2286            .filter_map(|path| {
2287                let (id, hash) = rows.get(path)?;
2288                Some((*id, hash.clone(), path.clone()))
2289            })
2290            .collect();
2291
2292        let batch_results = crate::symbol_cache::SymbolCache::batch_get_with_kind_on(
2293            &conn,
2294            &file_lookup_tuples,
2295            filter.kind.clone(),
2296        )
2297        .context("Failed to batch read symbol cache")?;
2298
2299        let id_to_path: HashMap<i64, &str> = rows
2300            .iter()
2301            .map(|(path, (id, _))| (*id, path.as_str()))
2302            .collect();
2303
2304        let mut cached_symbols: HashMap<String, Vec<SearchResult>> = HashMap::new();
2305        for (file_id, symbols) in batch_results {
2306            if let Some(file_path) = id_to_path.get(&file_id) {
2307                cached_symbols.insert(file_path.to_string(), symbols);
2308            }
2309        }
2310
2311        // Everything else — no files row, or no (current-hash) cache entry.
2312        let files_needing_parse: Vec<String> = files_to_process
2313            .iter()
2314            .filter(|p| !cached_symbols.contains_key(p.as_str()))
2315            .cloned()
2316            .collect();
2317
2318        log::debug!(
2319            "Symbol cache: {} hits, {} need parsing",
2320            cached_symbols.len(),
2321            files_needing_parse.len()
2322        );
2323
2324        // Parse cache misses in parallel; cache writes are collected and committed in
2325        // ONE transaction afterwards, instead of one connection + INSERT per file
2326        // from inside the pool.
2327        /// Symbols parsed from one file, plus its `(file_id, hash)` cache key when known.
2328        type ParsedFile = (Vec<SearchResult>, Option<(i64, String)>);
2329        let parsed: Vec<ParsedFile> = pool.install(|| {
2330            files_needing_parse
2331                .par_iter()
2332                .map(|file_path| {
2333                    let Some(file_id) = open.file_id_for(file_path) else {
2334                        log::warn!("Could not find file_id for path: {}", file_path);
2335                        return (Vec::new(), None);
2336                    };
2337                    let content = match content_reader.get_file_content(file_id) {
2338                        Ok(c) => c,
2339                        Err(e) => {
2340                            log::warn!("Failed to read file {}: {}", file_path, e);
2341                            return (Vec::new(), None);
2342                        }
2343                    };
2344                    let lang = Language::from_path(std::path::Path::new(file_path));
2345                    let symbols = match ParserFactory::parse(file_path, content, lang) {
2346                        Ok(symbols) => {
2347                            log::debug!("Parsed {} symbols from {}", symbols.len(), file_path);
2348                            symbols
2349                        }
2350                        Err(e) => {
2351                            log::debug!("Failed to parse {}: {}", file_path, e);
2352                            Vec::new()
2353                        }
2354                    };
2355                    let key = rows.get(file_path).map(|(id, hash)| (*id, hash.clone()));
2356                    (symbols, key)
2357                })
2358                .collect()
2359        });
2360
2361        let mut parsed_symbols: Vec<SearchResult> = Vec::new();
2362        let mut to_cache: Vec<(i64, String, Vec<SearchResult>)> = Vec::new();
2363        for (symbols, key) in parsed {
2364            if let Some((id, hash)) = key {
2365                to_cache.push((id, hash, symbols.clone()));
2366            }
2367            parsed_symbols.extend(symbols);
2368        }
2369        // Best-effort: a failed cache write must never fail the query. Written only
2370        // while meta.db's rows go with the snapshot the content came from: between
2371        // the two publishes of an index run the key could name another version.
2372        if !open.meta_matches_snapshot(&conn) {
2373            log::debug!(
2374                "Index is mid-publish; not caching {} parses",
2375                to_cache.len()
2376            );
2377        } else if let Err(e) =
2378            crate::symbol_cache::SymbolCache::batch_set_by_id_on(&mut conn, &to_cache)
2379        {
2380            log::debug!(
2381                "Failed to cache symbols for {} files: {}",
2382                to_cache.len(),
2383                e
2384            );
2385        }
2386        drop(conn);
2387
2388        // Combine cached and parsed symbols
2389        let mut all_symbols: Vec<SearchResult> = Vec::new();
2390
2391        // Add all cached symbols
2392        for symbols in cached_symbols.values() {
2393            all_symbols.extend_from_slice(symbols);
2394        }
2395
2396        // Add all parsed symbols
2397        all_symbols.extend(parsed_symbols);
2398
2399        // KEYWORD DETECTION: Check if pattern is a language keyword (e.g., "class", "function")
2400        // If it matches a keyword AND symbols_mode is true, interpret as "list all symbols of that type"
2401        // rather than looking for a symbol literally named "class" or "function"
2402        //
2403        // IMPORTANT: Only check keywords for languages that will pass Phase 3 filtering.
2404        // If a language filter is specified, only check that language's keywords.
2405        // Otherwise, check all languages present in the symbol results.
2406        let is_keyword_query = {
2407            // Determine which language to check keywords for
2408            let lang_to_check = if let Some(lang) = filter.language {
2409                // Language filter specified - check that language only
2410                // This ensures keyword detection aligns with Phase 3 language filtering
2411                vec![lang]
2412            } else {
2413                // No language filter - check all languages that appear in the actual symbols
2414                // (not candidates, but the parsed symbols that made it through)
2415                // This handles mixed-language codebases correctly
2416                let mut langs: Vec<Language> =
2417                    all_symbols.iter().map(|s| s.lang).collect::<Vec<_>>();
2418                langs.sort_by(|a, b| format!("{:?}", a).cmp(&format!("{:?}", b))); // Deterministic ordering
2419                langs.dedup(); // Remove duplicates after sorting
2420                langs
2421            };
2422
2423            // Check if pattern matches a keyword in any of the relevant languages
2424            lang_to_check
2425                .iter()
2426                .any(|lang| ParserFactory::get_keywords(*lang).contains(&pattern))
2427        };
2428
2429        // If pattern is a keyword (like "class" or "function"), skip name-based filtering
2430        // and return all symbols (kind filtering happens in Phase 3)
2431        let filtered: Vec<SearchResult> = if is_keyword_query {
2432            log::info!(
2433                "Pattern '{}' is a language keyword - listing all symbols (kind filtering will be applied in Phase 3)",
2434                pattern
2435            );
2436            all_symbols
2437        } else if filter.use_regex {
2438            // For regex queries, candidates already matched content via regex in Phase 1.
2439            // Extract symbols whose line spans overlap with the candidate locations.
2440            // This ensures symbols are found at the locations where the regex matched.
2441
2442            // Build a map of (file_path, line_no) from candidates
2443            use std::collections::{HashMap, HashSet};
2444            let mut candidate_lines: HashMap<String, HashSet<usize>> = HashMap::new();
2445            for candidate in &files_by_path {
2446                for cand in candidate.1 {
2447                    candidate_lines
2448                        .entry(candidate.0.clone())
2449                        .or_default()
2450                        .insert(cand.span.start_line);
2451                }
2452            }
2453
2454            // Filter symbols whose spans overlap with candidate lines
2455            all_symbols
2456                .into_iter()
2457                .filter(|sym| {
2458                    if let Some(lines) = candidate_lines.get(&sym.path) {
2459                        // Check if symbol's line span overlaps with any candidate line
2460                        for line in sym.span.start_line..=sym.span.end_line {
2461                            if lines.contains(&line) {
2462                                return true;
2463                            }
2464                        }
2465                    }
2466                    false
2467                })
2468                .collect()
2469        } else if filter.use_contains {
2470            // Substring match (opt-in with --contains)
2471            all_symbols
2472                .into_iter()
2473                .filter(|sym| sym.symbol.as_deref().is_some_and(|s| s.contains(pattern)))
2474                .collect()
2475        } else {
2476            // Exact match (default)
2477            all_symbols
2478                .into_iter()
2479                .filter(|sym| sym.symbol.as_deref() == Some(pattern))
2480                .collect()
2481        };
2482
2483        log::info!(
2484            "Symbol enrichment found {} matches for pattern '{}'",
2485            filtered.len(),
2486            pattern
2487        );
2488
2489        Ok(filtered)
2490    }
2491
2492    /// Enrich text match candidates with AST pattern matching
2493    ///
2494    /// Takes a list of text match candidates and executes a Tree-sitter AST query
2495    /// on the candidate files, returning only matches that satisfy the AST pattern.
2496    ///
2497    /// # Algorithm
2498    /// 1. Extract unique file paths from candidates
2499    /// 2. Load file contents for each candidate file
2500    /// 3. Execute AST query pattern using Tree-sitter
2501    /// 4. Return AST matches
2502    ///
2503    /// # Performance
2504    /// Only parses files that have text matches, so typically 10-100 files
2505    /// instead of the entire codebase (62K+ files).
2506    ///
2507    /// # Requirements
2508    /// - Language must be specified (AST queries are language-specific)
2509    /// - AST pattern must be valid S-expression syntax
2510    fn enrich_with_ast(
2511        &self,
2512        candidates: Vec<SearchResult>,
2513        ast_pattern: &str,
2514        language: Option<Language>,
2515    ) -> Result<Vec<SearchResult>> {
2516        // Require language for AST queries
2517        let lang = language.ok_or_else(|| anyhow::anyhow!(
2518            "Language must be specified for AST pattern matching. Use --lang to specify the language."
2519        ))?;
2520
2521        // The shared index handle (content store + file-id map)
2522        let open = self.open_index()?;
2523        let content_reader = &open.snapshot;
2524
2525        // Collect unique file paths from candidates and load their contents
2526        use std::collections::HashMap;
2527        let mut file_contents: HashMap<String, String> = HashMap::new();
2528
2529        for candidate in &candidates {
2530            if file_contents.contains_key(&candidate.path) {
2531                continue;
2532            }
2533
2534            // Find file_id for this path
2535            let file_id = match open.file_id_for(&candidate.path) {
2536                Some(id) => id,
2537                None => {
2538                    log::warn!("Could not find file_id for path: {}", candidate.path);
2539                    continue;
2540                }
2541            };
2542
2543            // Load file content
2544            let content = match content_reader.get_file_content(file_id) {
2545                Ok(c) => c,
2546                Err(e) => {
2547                    log::warn!("Failed to read file {}: {}", candidate.path, e);
2548                    continue;
2549                }
2550            };
2551
2552            file_contents.insert(candidate.path.clone(), content.to_string());
2553        }
2554
2555        log::debug!(
2556            "Executing AST query on {} candidate files with language {:?}",
2557            file_contents.len(),
2558            lang
2559        );
2560
2561        // Execute AST query using the ast_query module
2562        let results =
2563            crate::ast_query::execute_ast_query(candidates, ast_pattern, lang, &file_contents)?;
2564
2565        log::info!(
2566            "AST query found {} matches for pattern '{}'",
2567            results.len(),
2568            ast_pattern
2569        );
2570
2571        Ok(results)
2572    }
2573
2574    /// Map keyword patterns to SymbolKind for auto-inference
2575    ///
2576    /// When users search for keywords like "class" or "function" with --symbols,
2577    /// automatically infer the kind filter to return only symbols of that type.
2578    ///
2579    /// This makes keyword queries more intuitive: searching for "class" returns
2580    /// only classes, not all symbols.
2581    fn keyword_to_kind(keyword: &str) -> Option<SymbolKind> {
2582        filter::keyword_to_kind(keyword)
2583    }
2584
2585    /// Get all files matching the language filter (for keyword queries)
2586    ///
2587    /// This method bypasses trigram search and returns ALL files of the specified language.
2588    /// Used for keyword queries like "list all classes" where we need complete coverage,
2589    /// not just the first 100 candidates from a trigram search.
2590    ///
2591    /// Similar to `search_ast_all_files()` but works for symbol queries instead of AST queries.
2592    fn get_all_language_files(&self, filter: &QueryFilter) -> Result<Vec<SearchResult>> {
2593        // Language filter is optional - if not specified, scan all files
2594        // If specified, only scan files of that language
2595
2596        // The shared content store
2597        let open = self.open_index()?;
2598        let content_reader = &open.snapshot;
2599
2600        // Build glob matchers if specified (for filtering)
2601        let include_matcher = result::build_glob_set(&filter.glob_patterns, "glob");
2602
2603        let exclude_matcher = result::build_glob_set(&filter.exclude_patterns, "exclude");
2604
2605        // Scan all files and filter by language + glob patterns
2606        let mut candidates: Vec<SearchResult> = Vec::new();
2607
2608        for file_id in content_reader.live_ids() {
2609            let file_path = match content_reader.get_file_path(file_id) {
2610                Some(p) => p,
2611                None => continue,
2612            };
2613
2614            // Detect language from file extension
2615            let detected_lang = Language::from_path(file_path);
2616
2617            // Filter by language (if specified)
2618            if let Some(lang) = filter.language
2619                && detected_lang != lang
2620            {
2621                continue;
2622            }
2623
2624            let file_path_str = file_path.to_string_lossy().to_string();
2625
2626            // Apply glob/exclude filters
2627            let included = include_matcher
2628                .as_ref()
2629                .is_none_or(|m| m.is_match(&file_path_str));
2630            let excluded = exclude_matcher
2631                .as_ref()
2632                .is_some_and(|m| m.is_match(&file_path_str));
2633
2634            if !included || excluded {
2635                continue;
2636            }
2637
2638            // Apply file path filter if specified
2639            if let Some(ref file_pattern) = filter.file_pattern
2640                && !file_path_str.contains(file_pattern)
2641            {
2642                continue;
2643            }
2644
2645            // Create a dummy candidate for this file
2646            // Phase 2 (symbol enrichment) will parse it and extract actual symbols
2647            candidates.push(SearchResult {
2648                path: file_path_str,
2649                lang: detected_lang,
2650                span: Span {
2651                    start_line: 1,
2652                    end_line: 1,
2653                },
2654                symbol: None,
2655                kind: SymbolKind::Unknown("keyword_query".to_string()),
2656                preview: String::new(),
2657                dependencies: None,
2658            });
2659        }
2660
2661        if let Some(lang) = filter.language {
2662            log::info!(
2663                "Keyword query will scan {} {:?} files for symbol extraction",
2664                candidates.len(),
2665                lang
2666            );
2667        } else {
2668            log::info!(
2669                "Keyword query will scan {} files (all languages) for symbol extraction",
2670                candidates.len()
2671            );
2672        }
2673
2674        Ok(candidates)
2675    }
2676
2677    /// Get candidate results using trigram-based full-text search
2678    ///
2679    /// The trigram intersection yields exact candidate `(file, line)` pairs; only
2680    /// those lines are verified, in path order, in parallel, and — in list mode —
2681    /// only until `budget` results exist (see [`verify_files_streaming`]).
2682    fn get_trigram_candidates(
2683        &self,
2684        pattern: &str,
2685        filter: &QueryFilter,
2686        budget: Option<usize>,
2687    ) -> Result<(Vec<SearchResult>, CandidateStats)> {
2688        let open = self.open_index()?;
2689        let trigram_index = &open.snapshot;
2690
2691        // Patterns shorter than 3 chars have no trigrams, so the trigram index always
2692        // returns empty.  Fall back to a linear scan of the content store so that
2693        // --force (which bypasses the broad-query guard) still produces real results.
2694        if pattern.chars().count() < 3 {
2695            log::info!(
2696                "Pattern '{}' is shorter than 3 chars — trigram index cannot be used, \
2697                 falling back to linear scan",
2698                pattern
2699            );
2700            let results = self.linear_scan_candidates(pattern, filter, &open)?;
2701            let stats = CandidateStats {
2702                index_path: IndexPath::Scan,
2703                ..CandidateStats::default()
2704            };
2705            return Ok((results, stats));
2706        }
2707
2708        // Search using trigrams
2709        let candidates_started = std::time::Instant::now();
2710        let candidates = trigram_index.search_candidates(pattern);
2711        let candidates_us = candidates_started.elapsed().as_micros() as u64;
2712        log::debug!(
2713            "Found {} candidate locations from trigram search in {} us",
2714            candidates.len(),
2715            candidates_us
2716        );
2717
2718        // Group candidate lines by file. The intersection is sorted by
2719        // (file_id, line_no), so each file's lines arrive ascending.
2720        let mut files: Vec<(u32, LineSet)> = Vec::new();
2721        for loc in candidates {
2722            match files.last_mut() {
2723                Some((id, LineSet::Only(lines))) if *id == loc.file_id => lines.push(loc.line_no),
2724                _ => files.push((loc.file_id, LineSet::Only(vec![loc.line_no]))),
2725            }
2726        }
2727        log::debug!("Scanning {} files with trigram matches", files.len());
2728
2729        // One matcher for the whole query (see `LineMatcher`).
2730        let matcher = LineMatcher::new(pattern, filter)?;
2731        let file_filter = FileFilter::from_filter(filter);
2732
2733        let outcome = verify_files_streaming(
2734            &open,
2735            files,
2736            &matcher,
2737            &file_filter,
2738            filter.paths_only,
2739            budget,
2740            filter.count_only_line_search(),
2741        );
2742
2743        let stats = CandidateStats {
2744            candidates_us,
2745            substring_only: matcher.is_word_boundary().then_some(outcome.substring_only),
2746            excluded_by_default: outcome.excluded_by_default,
2747            counted: outcome.counted,
2748            exhausted: outcome.exhausted,
2749            approx_total: outcome.estimated_total,
2750            index_path: IndexPath::Trigram,
2751            warnings: Vec::new(),
2752        };
2753        Ok((outcome.results, stats))
2754    }
2755
2756    /// Linear scan fallback for patterns shorter than 3 characters.
2757    ///
2758    /// The trigram index requires 3-char n-grams; patterns like "fn" or "i" yield
2759    /// zero trigrams and therefore zero results.  This method scans every file in
2760    /// the content store directly using the same matching logic (word-boundary,
2761    /// contains, or regex) so short-pattern queries always return real results.
2762    fn linear_scan_candidates(
2763        &self,
2764        pattern: &str,
2765        filter: &QueryFilter,
2766        open: &OpenIndex,
2767    ) -> Result<Vec<SearchResult>> {
2768        use rayon::prelude::*;
2769
2770        let content_reader = &open.snapshot;
2771        let pattern_owned = pattern.to_string();
2772        let matcher = LineMatcher::new(pattern, filter)?;
2773
2774        let results: Vec<SearchResult> = open.pool().install(|| {
2775            content_reader
2776                .live_ids()
2777                .collect::<Vec<_>>()
2778                .par_iter()
2779                .flat_map(|&file_id| {
2780                    let file_path = match content_reader.get_file_path(file_id) {
2781                        Some(p) => p.to_path_buf(),
2782                        None => return Vec::new(),
2783                    };
2784                    let content = match content_reader.get_file_content(file_id) {
2785                        Ok(c) => c,
2786                        Err(_) => return Vec::new(),
2787                    };
2788
2789                    let file_path_str = file_path.to_string_lossy().to_string();
2790                    let lang = Language::from_path(&file_path);
2791
2792                    let mut seen_lines = std::collections::HashSet::new();
2793                    let mut file_results = Vec::new();
2794
2795                    for (line_idx, line) in content.lines().enumerate() {
2796                        let line_no = line_idx + 1;
2797                        if seen_lines.contains(&line_no) {
2798                            continue;
2799                        }
2800
2801                        if !matcher.is_match(line) {
2802                            continue;
2803                        }
2804
2805                        seen_lines.insert(line_no);
2806                        file_results.push(SearchResult {
2807                            path: file_path_str.clone(),
2808                            lang,
2809                            kind: SymbolKind::Unknown("text_match".to_string()),
2810                            symbol: None,
2811                            span: Span {
2812                                start_line: line_no,
2813                                end_line: line_no,
2814                            },
2815                            // Bounded, and WINDOWED on the match: on a minified bundle
2816                            // this line is the whole 1.45 MB file, and the first 512
2817                            // bytes of it would tell the caller nothing.
2818                            preview: crate::parsers::preview::line_preview(
2819                                line,
2820                                line.find(pattern_owned.as_str()).unwrap_or(0),
2821                            ),
2822                            dependencies: None,
2823                        });
2824                    }
2825
2826                    file_results
2827                })
2828                .collect()
2829        });
2830
2831        log::info!(
2832            "Linear scan (short pattern '{}') found {} results across {} files",
2833            pattern,
2834            results.len(),
2835            content_reader.live_file_count()
2836        );
2837        Ok(results)
2838    }
2839
2840    /// Get candidate results using regex patterns with trigram optimization
2841    ///
2842    /// # Algorithm
2843    ///
2844    /// 1. Extract literal sequences (≥3 chars) from the regex pattern
2845    /// 2. For each literal, take the exact candidate `(file, line)` pairs from the
2846    ///    trigram index and UNION them
2847    /// 3. Verify the regex on those lines only, in path order, in parallel, with the
2848    ///    same early termination as literal search
2849    /// 4. With no usable literal (none ≥3 chars, or a case-insensitive flag), verify
2850    ///    every line of every file
2851    ///
2852    /// # Why candidate lines are sufficient
2853    ///
2854    /// Matching is per line, and every literal the extractor emits must appear
2855    /// verbatim in any match (the extractor drops the atom before a `?`, `*` or
2856    /// `{0,n}`). A matching line therefore contains at least one emitted literal
2857    /// in full, and the union over literals of their exact candidate lines is a
2858    /// superset of the matching lines. This is the same assumption the literal
2859    /// path makes; a capped posting list loses a file in both paths alike.
2860    fn get_regex_candidates(
2861        &self,
2862        pattern: &str,
2863        filter: &QueryFilter,
2864        timeout: Option<&std::time::Duration>,
2865        start_time: &std::time::Instant,
2866        budget: Option<usize>,
2867    ) -> Result<(Vec<SearchResult>, CandidateStats)> {
2868        // Step 1: Compile the regex (the filter carries the `kind` label)
2869        let matcher = LineMatcher::new(pattern, filter)
2870            .with_context(|| format!("Invalid regex pattern: {}", pattern))?;
2871
2872        // Check timeout before expensive operations
2873        if let Some(timeout_duration) = timeout
2874            && start_time.elapsed() > *timeout_duration
2875        {
2876            anyhow::bail!(
2877                "Query timeout exceeded ({} seconds) during regex compilation",
2878                timeout_duration.as_secs()
2879            );
2880        }
2881
2882        // Step 2: Extract literals from the regex. A literal under `(?i)` is looked
2883        // up under every ASCII case variant; a non-ASCII one cannot be folded.
2884        use crate::regex_trigrams::extract_literals;
2885        let literals = extract_literals(pattern);
2886        let unfoldable = literals
2887            .iter()
2888            .any(|l| l.case_insensitive && !l.text.is_ascii());
2889
2890        let open = self.open_index()?;
2891        let candidates_started = std::time::Instant::now();
2892
2893        let mut warnings = Vec::new();
2894        let index_path;
2895        let files: Vec<(u32, LineSet)> = if literals.is_empty() || unfoldable {
2896            // No usable literal - fall back to a full scan of every line.
2897            index_path = IndexPath::Scan;
2898            // A literal shorter than 3 chars scans silently on the case-sensitive
2899            // path too (`get_trigram_candidates`); `-i fn` must not warn either.
2900            let short_literal = filter
2901                .rewritten_from
2902                .as_deref()
2903                .is_some_and(|p| p.chars().count() < 3);
2904            if !short_literal {
2905                let text = if unfoldable {
2906                    format!(
2907                        "Regex pattern '{}' has a non-ASCII case-insensitive literal, which the trigram index cannot fold; falling back to full content scan. This may be slow on large codebases.",
2908                        pattern
2909                    )
2910                } else {
2911                    format!(
2912                        "Regex pattern '{}' has no literals (≥3 chars), falling back to full content scan. This may be slow on large codebases. Consider using patterns with literal text.",
2913                        pattern
2914                    )
2915                };
2916                if !filter.suppress_output {
2917                    output::warn(&text);
2918                }
2919                warnings.push(text);
2920            }
2921            open.snapshot
2922                .live_ids()
2923                .map(|id| (id, LineSet::All))
2924                .collect()
2925        } else {
2926            index_path = IndexPath::Trigram;
2927            log::debug!(
2928                "Using {} literals to narrow regex search candidates",
2929                literals.len()
2930            );
2931
2932            // Union of each literal's exact candidate lines (alternation-safe).
2933            // Each source is sorted by (file, line) and key-unique, so a single
2934            // source needs no sort; several are merged with one sort + dedup. A
2935            // per-file BTreeMap here cost ~8 ms per 100k locations.
2936            let mut locations: Vec<crate::trigram::FileLocation> = Vec::new();
2937            let mut sources = 0usize;
2938            // Under Unicode case folding `k` and `s` also match the Kelvin sign
2939            // and the long s, which live on lines the ASCII fold cannot reach.
2940            let mut need_exotic = false;
2941            for literal in &literals {
2942                let found = if literal.case_insensitive {
2943                    if literal
2944                        .text
2945                        .bytes()
2946                        .any(|b| matches!(b.to_ascii_lowercase(), b'k' | b's'))
2947                    {
2948                        need_exotic = true;
2949                    }
2950                    open.snapshot
2951                        .search_candidates_fold(literal.text.as_bytes())
2952                } else {
2953                    open.snapshot.search_candidates(&literal.text)
2954                };
2955                log::debug!(
2956                    "Literal '{}' (ci={}) found on {} candidate lines",
2957                    literal.text,
2958                    literal.case_insensitive,
2959                    found.len()
2960                );
2961                locations.extend(found);
2962                sources += 1;
2963            }
2964            if need_exotic {
2965                locations.extend(open.snapshot.exotic_fold_lines());
2966                sources += 1;
2967            }
2968            if sources > 1 {
2969                locations.sort_unstable();
2970                locations.dedup();
2971            }
2972            // Group by file; lines arrive ascending within each file.
2973            let mut files: Vec<(u32, LineSet)> = Vec::new();
2974            for loc in locations {
2975                match files.last_mut() {
2976                    Some((id, LineSet::Only(lines))) if *id == loc.file_id => {
2977                        lines.push(loc.line_no)
2978                    }
2979                    _ => files.push((loc.file_id, LineSet::Only(vec![loc.line_no]))),
2980                }
2981            }
2982            files
2983        };
2984        let candidates_us = candidates_started.elapsed().as_micros() as u64;
2985        log::debug!(
2986            "Regex candidates: {} files in {} us",
2987            files.len(),
2988            candidates_us
2989        );
2990
2991        let file_filter = FileFilter::from_filter(filter);
2992        let outcome = verify_files_streaming(
2993            &open,
2994            files,
2995            &matcher,
2996            &file_filter,
2997            filter.paths_only,
2998            budget,
2999            filter.count_only_line_search(),
3000        );
3001
3002        log::info!(
3003            "Regex search found {} matches for pattern '{}'",
3004            outcome.results.len(),
3005            pattern
3006        );
3007        let stats = CandidateStats {
3008            candidates_us,
3009            substring_only: None,
3010            excluded_by_default: outcome.excluded_by_default,
3011            counted: outcome.counted,
3012            exhausted: outcome.exhausted,
3013            approx_total: outcome.estimated_total,
3014            index_path,
3015            warnings,
3016        };
3017        Ok((outcome.results, stats))
3018    }
3019
3020    /// Get index status for programmatic use (doesn't print warnings)
3021    ///
3022    /// Returns (status, can_trust_results, warning) tuple for JSON output.
3023    /// This is optimized for AI agents to detect staleness and auto-reindex.
3024    pub fn get_index_status(&self) -> Result<(IndexStatus, bool, Option<IndexWarning>)> {
3025        self.index_status_for(None)
3026    }
3027
3028    /// Index status read from the filesystem, never from the freshness memo.
3029    ///
3030    /// For `check_index_status`: an agent asking whether the index is current is
3031    /// exactly the caller that must not be told what was true a second ago.
3032    pub fn fresh_index_status(&self) -> Result<(IndexStatus, bool, Option<IndexWarning>)> {
3033        let r = self.fresh_index_report()?;
3034        Ok((r.status, r.can_trust_results, r.warning))
3035    }
3036
3037    /// [`Self::fresh_index_status`] with the branch/commit details attached, which
3038    /// are present even when fresh.
3039    pub fn fresh_index_report(&self) -> Result<IndexStatusReport> {
3040        status_cache::invalidate(&self.cache.workspace_root());
3041        self.index_report_for(None)
3042    }
3043
3044    /// Index status, with `scope` naming the files a caller's answer came from.
3045    ///
3046    /// `scope` does NOT soften `can_trust_results`. A stale index always yields
3047    /// `can_trust_results: false`, because the changes that matter most are the ones
3048    /// scoping cannot see: a newly created file produces no results to intersect
3049    /// with, and an empty result set has no scope at all — which is exactly the case
3050    /// where an agent concludes "no callers" and acts on it.
3051    ///
3052    /// Scope is used only to describe the impact, via
3053    /// [`IndexWarning::reason`], so a caller can tell "your results may be missing a
3054    /// file you just edited" from "a file in these results has changed".
3055    pub fn index_status_for(
3056        &self,
3057        scope: Option<&[String]>,
3058    ) -> Result<(IndexStatus, bool, Option<IndexWarning>)> {
3059        let r = self.index_report_for(scope)?;
3060        Ok((r.status, r.can_trust_results, r.warning))
3061    }
3062
3063    /// [`Self::index_status_for`] with details.
3064    pub fn index_report_for(&self, scope: Option<&[String]>) -> Result<IndexStatusReport> {
3065        // Everything that costs a subprocess or a database open is computed once per
3066        // TTL in `status_cache`; only the scope-dependent wording is built here.
3067        let snapshot = status_cache::snapshot(&self.cache)?;
3068        Ok(Self::report_from(&snapshot, scope))
3069    }
3070
3071    /// The verdict for one caller, from a snapshot already computed.
3072    ///
3073    /// Pure, so a caller can compute the snapshot on another thread while the
3074    /// search runs and derive the wording once both are done.
3075    fn report_from(
3076        snapshot: &status_cache::Snapshot,
3077        scope: Option<&[String]>,
3078    ) -> IndexStatusReport {
3079        if let Some((status, can_trust_results, warning)) = snapshot.decided.clone() {
3080            return IndexStatusReport {
3081                status,
3082                can_trust_results,
3083                warning,
3084                details: snapshot.details.clone(),
3085            };
3086        }
3087        let changes = &snapshot.changes;
3088        let details = snapshot.details.clone();
3089
3090        if changes.is_empty() {
3091            return IndexStatusReport {
3092                status: IndexStatus::Fresh,
3093                can_trust_results: true,
3094                warning: None,
3095                details,
3096            };
3097        }
3098
3099        // Whether a changed file is among the ones this answer came from. Used only
3100        // to sharpen the message — never to upgrade trust.
3101        let hits_results = match scope {
3102            None | Some([]) => false,
3103            Some(paths) => changes.any(|changed| {
3104                paths
3105                    .iter()
3106                    .any(|p| p == changed || p.ends_with(changed) || changed.ends_with(p.as_str()))
3107            }),
3108        };
3109
3110        let reason = {
3111            let mut parts = Vec::new();
3112            if changes.modified_count > 0 {
3113                parts.push(format!("{} modified", changes.modified_count));
3114            }
3115            if changes.added_count > 0 {
3116                parts.push(format!("{} added", changes.added_count));
3117            }
3118            if changes.deleted_count > 0 {
3119                parts.push(format!("{} deleted", changes.deleted_count));
3120            }
3121            let impact = if hits_results {
3122                " — including a file these results came from"
3123            } else if changes.deleted_count > 0 {
3124                " — deleted files still produce hits at their old lines"
3125            } else {
3126                " — these results may not reflect them"
3127            };
3128            format!(
3129                "Files changed since the index was built ({}){}",
3130                parts.join(", "),
3131                impact
3132            )
3133        };
3134
3135        let some_if_any = |v: Vec<String>| if v.is_empty() { None } else { Some(v) };
3136        let warning = IndexWarning {
3137            reason,
3138            action_required: "index_project".to_string(),
3139            files_modified: some_if_any(changes.modified.clone()),
3140            files_added: some_if_any(changes.added.clone()),
3141            files_deleted: some_if_any(changes.deleted.clone()),
3142            changed_count: Some(
3143                changes.modified_count + changes.added_count + changes.deleted_count,
3144            ),
3145            truncated: changes.truncated,
3146            details: details.clone(),
3147        };
3148
3149        // Stale means untrusted, with no exception. A search served from an index
3150        // that does not know about the caller's own edits cannot promise completeness,
3151        // and a silently-confident wrong answer is the failure this release fixes.
3152        IndexStatusReport {
3153            status: IndexStatus::Stale,
3154            can_trust_results: false,
3155            warning: Some(warning),
3156            details,
3157        }
3158    }
3159
3160    /// Check index freshness and show non-blocking warnings
3161    ///
3162    /// This performs lightweight checks to warn users if their index might be stale:
3163    /// 1. Branch mismatch: indexed different branch
3164    /// 2. Commit changed: HEAD moved since indexing
3165    /// 3. File changes: quick mtime check on sample of files (if available)
3166    fn check_index_freshness(&self, filter: &QueryFilter) -> Result<()> {
3167        let root = self.cache.workspace_root();
3168
3169        // Check git state if in a git repo
3170        if crate::git::is_git_repo(&root) {
3171            if !crate::git::is_git_available() {
3172                static WARNED: std::sync::OnceLock<()> = std::sync::OnceLock::new();
3173                if !filter.suppress_output {
3174                    WARNED.get_or_init(|| {
3175                        output::warn("⚠️  git binary not found in PATH; index freshness checks disabled for this session.");
3176                    });
3177                }
3178                return Ok(());
3179            }
3180            if let Ok(current_branch) = crate::git::get_current_branch(&root) {
3181                // Check if we're on a different branch than what was indexed
3182                if !self.cache.branch_exists(&current_branch).unwrap_or(false) {
3183                    if !filter.suppress_output {
3184                        output::warn(&format!(
3185                            "⚠️  WARNING: Index not found for branch '{}'. Run 'rfx index' to index this branch.",
3186                            current_branch
3187                        ));
3188                    }
3189                    return Ok(());
3190                }
3191
3192                // Branch exists - check if commit changed
3193                if let (Ok(current_commit), Ok(branch_info)) = (
3194                    crate::git::get_current_commit(&root),
3195                    self.cache.get_branch_info(&current_branch),
3196                ) {
3197                    if branch_info.commit_sha != current_commit {
3198                        if !filter.suppress_output {
3199                            output::warn(&format!(
3200                                "⚠️  WARNING: Index may be stale (commit changed: {} → {}). Consider running 'rfx index'.",
3201                                &branch_info.commit_sha[..7],
3202                                &current_commit[..7]
3203                            ));
3204                        }
3205                        return Ok(());
3206                    }
3207
3208                    // If commits match, do a quick file freshness check
3209                    // Sample up to 10 files to check for modifications (cheap mtime check)
3210                    if let Ok(branch_files) = self.cache.get_branch_files(&current_branch) {
3211                        let mut checked = 0;
3212                        let mut changed = 0;
3213                        const SAMPLE_SIZE: usize = 10;
3214
3215                        for (path, _indexed_hash) in branch_files.iter().take(SAMPLE_SIZE) {
3216                            checked += 1;
3217                            let file_path = std::path::Path::new(path);
3218
3219                            // Check if file exists and has been modified (mtime/size heuristic)
3220                            if let Ok(metadata) = std::fs::metadata(file_path)
3221                                && let Ok(modified) = metadata.modified()
3222                            {
3223                                let indexed_time = branch_info.last_indexed;
3224                                let file_time = modified
3225                                    .duration_since(std::time::UNIX_EPOCH)
3226                                    .unwrap_or_default()
3227                                    .as_secs()
3228                                    as i64;
3229
3230                                // If file modified after indexing, it might be stale
3231                                if file_time > indexed_time {
3232                                    // File modified after indexing - likely stale
3233                                    // Note: We skip hash verification for performance (mtime check is sufficient)
3234                                    // This may cause false positives if files were touched without changes,
3235                                    // but the warning is non-blocking and vastly better than slow queries
3236                                    changed += 1;
3237                                }
3238                            }
3239                        }
3240
3241                        if changed > 0 && !filter.suppress_output {
3242                            output::warn(&format!(
3243                                "⚠️  WARNING: {} of {} sampled files changed since indexing. Consider running 'rfx index'.",
3244                                changed, checked
3245                            ));
3246                        }
3247                    }
3248                }
3249            }
3250        }
3251
3252        Ok(())
3253    }
3254}
3255
3256/// Generate AI instruction based on query results
3257///
3258/// Provides context-aware guidance to AI agents on how to handle search results.
3259/// Uses priority-based logic to determine the most relevant instruction.
3260#[allow(clippy::too_many_arguments)]
3261pub fn generate_ai_instruction(
3262    result_count: usize,
3263    total_count: usize,
3264    has_more: bool,
3265    symbols_mode: bool,
3266    paths_only: bool,
3267    use_ast: bool,
3268    use_regex: bool,
3269    language_filter: bool,
3270    glob_filter: bool,
3271    exact_mode: bool,
3272) -> Option<String> {
3273    // Priority 1: No results
3274    if result_count == 0 {
3275        return Some(
3276            "No results found. Consider these alternatives: 1) Check pattern spelling, 2) Remove --kind or --lang filters to broaden search, 3) Try partial match or related term, 4) Use search_regex tool for pattern matching with special characters or complex patterns."
3277            .to_string()
3278        );
3279    }
3280
3281    // Priority 2: Query too broad (500+ results)
3282    if total_count >= 500 {
3283        return Some(format!(
3284            "Query too broad: {} results found. STOP. Do not list results. Refine search automatically by adding filters: kind parameter (Function/Struct/Class), lang parameter (rust/python/etc), or glob parameter (['src/**/*.rs']). Call search_code again with appropriate filters.",
3285            total_count
3286        ));
3287    }
3288
3289    // Priority 3: Paginated results
3290    //
3291    // REF-191: for autonomous find-all tasks this instruction must NOT tell the
3292    // agent to stop and ask the user — there is no user in an agent loop, and a
3293    // partial answer to "find every occurrence" is wrong. Instruct decisive
3294    // continuation: fetch the remaining page(s) via offset, or probe the total
3295    // cheaply with mode="count" first.
3296    if has_more {
3297        return Some(format!(
3298            "Showing {} of {} results — {} more available. This is a partial answer. To finish a find-all task, call again with offset={} (raise limit up to 500 to get the rest in one call), or use mode=\"count\" first if you only need the total.",
3299            result_count,
3300            total_count,
3301            total_count.saturating_sub(result_count),
3302            result_count
3303        ));
3304    }
3305
3306    // Priority 4: Single precise result (symbols mode)
3307    if result_count == 1 && symbols_mode {
3308        return Some(
3309            "Found 1 precise result. Respond concisely: '[symbol] at [path]:[line]'.".to_string(),
3310        );
3311    }
3312
3313    // Priority 5: Few precise results (symbols mode)
3314    if (2..=10).contains(&result_count) && symbols_mode {
3315        return Some(format!(
3316            "Found {} precise results (definitions only, not usages). List locations concisely: '[symbol] at [path]:[line]' for each result.",
3317            result_count
3318        ));
3319    }
3320
3321    // Priority 6: Many results (101-500)
3322    if (101..500).contains(&total_count) {
3323        return Some(format!(
3324            "Found {} results - this is broad. Suggest refining search with: kind parameter (Function/Struct/Class/etc), lang parameter (rust/python/etc), or glob parameter to narrow file scope.",
3325            total_count
3326        ));
3327    }
3328
3329    // Priority 7: Full-text mode with many results (suggest symbols mode)
3330    if result_count >= 100 && !symbols_mode {
3331        return Some(format!(
3332            "Found {} results in full-text search mode (includes definitions AND all usages). Consider using symbols=true parameter to filter to definitions only. This typically reduces results by 80-90%.",
3333            result_count
3334        ));
3335    }
3336
3337    // Priority 8: Paths-only mode
3338    if paths_only {
3339        return Some(format!(
3340            "Found {} unique files (paths-only mode - no code content included). Next step: Use Read tool on specific files that look relevant based on their paths.",
3341            result_count
3342        ));
3343    }
3344
3345    // Priority 9: AST query results
3346    if use_ast {
3347        return Some(format!(
3348            "Found {} results using AST pattern matching. These are structure-based matches using Tree-sitter patterns, not text search.",
3349            result_count
3350        ));
3351    }
3352
3353    // Priority 10: Regex with many results
3354    if use_regex && result_count >= 100 {
3355        return Some(format!(
3356            "Found {} results using regex pattern matching. Regex matches are expansive. Consider using exact text search or symbols mode for more precise results.",
3357            result_count
3358        ));
3359    }
3360
3361    // Priority 11: Language filter with few results
3362    if language_filter && result_count <= 5 {
3363        return Some(format!(
3364            "Found {} results with language filter active. Results are limited to this language only. Remove lang parameter if you want to search all languages.",
3365            result_count
3366        ));
3367    }
3368
3369    // Priority 12: Glob filter with few results
3370    if glob_filter && result_count <= 10 {
3371        return Some(format!(
3372            "Found {} results with glob filter active. Results are limited to matching paths. Remove glob parameter to search entire codebase.",
3373            result_count
3374        ));
3375    }
3376
3377    // Priority 13: Exact mode with few results
3378    if exact_mode && result_count <= 5 {
3379        return Some(format!(
3380            "Found {} results in exact match mode. Only exact symbol name matches are included. Remove exact parameter to allow substring matching.",
3381            result_count
3382        ));
3383    }
3384
3385    // Normal case (11-100 results, no special conditions) - no instruction
3386    None
3387}
3388
3389#[cfg(test)]
3390mod tests {
3391    use super::*;
3392    use crate::indexer::Indexer;
3393    use crate::models::IndexConfig;
3394    use std::fs;
3395    use tempfile::TempDir;
3396
3397    // ==================== Basic Tests ====================
3398
3399    #[test]
3400    fn test_query_engine_creation() {
3401        let temp = TempDir::new().unwrap();
3402        let cache = CacheManager::new(temp.path());
3403        let engine = QueryEngine::new(cache);
3404
3405        assert!(engine.cache.path().ends_with(".reflex"));
3406    }
3407
3408    #[test]
3409    fn test_filter_modes() {
3410        // Test that symbols_mode works as expected
3411        let filter_fulltext = QueryFilter::default();
3412        assert!(!filter_fulltext.symbols_mode);
3413
3414        let filter_symbols = QueryFilter {
3415            symbols_mode: true,
3416            ..Default::default()
3417        };
3418        assert!(filter_symbols.symbols_mode);
3419
3420        // Test that kind implies symbols_mode (handled in CLI layer)
3421        let filter_with_kind = QueryFilter {
3422            kind: Some(SymbolKind::Function),
3423            symbols_mode: true,
3424            ..Default::default()
3425        };
3426        assert!(filter_with_kind.symbols_mode);
3427    }
3428
3429    // ==================== Search Mode Tests ====================
3430
3431    #[test]
3432    fn test_fulltext_search() {
3433        let temp = TempDir::new().unwrap();
3434        let project = temp.path().join("project");
3435        fs::create_dir(&project).unwrap();
3436
3437        // Create test files
3438        fs::write(
3439            project.join("main.rs"),
3440            "fn main() {\n    println!(\"hello\");\n}",
3441        )
3442        .unwrap();
3443        fs::write(project.join("lib.rs"), "pub fn hello() {}").unwrap();
3444
3445        // Index the project
3446        let cache = CacheManager::new(&project);
3447        let indexer = Indexer::new(cache, IndexConfig::default());
3448        indexer.index(&project, false).unwrap();
3449
3450        // Search for "hello"
3451        let cache = CacheManager::new(&project);
3452        let engine = QueryEngine::new(cache);
3453        let filter = QueryFilter::default(); // full-text mode
3454        let results = engine.search("hello", filter).unwrap();
3455
3456        // Should find both occurrences (println and function name)
3457        assert!(results.len() >= 2);
3458        assert!(results.iter().any(|r| r.path.contains("main.rs")));
3459        assert!(results.iter().any(|r| r.path.contains("lib.rs")));
3460    }
3461
3462    #[test]
3463    fn test_symbol_search() {
3464        let temp = TempDir::new().unwrap();
3465        let project = temp.path().join("project");
3466        fs::create_dir(&project).unwrap();
3467
3468        // Create test file with function definition and call
3469        fs::write(
3470            project.join("main.rs"),
3471            "fn greet() {}\nfn main() {\n    greet();\n}",
3472        )
3473        .unwrap();
3474
3475        // Index
3476        let cache = CacheManager::new(&project);
3477        let indexer = Indexer::new(cache, IndexConfig::default());
3478        indexer.index(&project, false).unwrap();
3479
3480        let cache = CacheManager::new(&project);
3481
3482        // Symbol search (definitions only)
3483        let engine = QueryEngine::new(cache);
3484        let filter = QueryFilter {
3485            symbols_mode: true,
3486            ..Default::default()
3487        };
3488        let results = engine.search("greet", filter).unwrap();
3489
3490        // Should find only the definition, not the call
3491        assert!(!results.is_empty());
3492        assert!(results.iter().any(|r| r.kind == SymbolKind::Function));
3493    }
3494
3495    #[test]
3496    fn test_regex_search() {
3497        let temp = TempDir::new().unwrap();
3498        let project = temp.path().join("project");
3499        fs::create_dir(&project).unwrap();
3500
3501        fs::write(
3502            project.join("main.rs"),
3503            "fn test1() {}\nfn test2() {}\nfn other() {}",
3504        )
3505        .unwrap();
3506
3507        let cache = CacheManager::new(&project);
3508        let indexer = Indexer::new(cache, IndexConfig::default());
3509        indexer.index(&project, false).unwrap();
3510
3511        let cache = CacheManager::new(&project);
3512
3513        let engine = QueryEngine::new(cache);
3514        let filter = QueryFilter {
3515            use_regex: true,
3516            ..Default::default()
3517        };
3518        let results = engine.search(r"fn test\d", filter).unwrap();
3519
3520        // Should match test1 and test2 but not other
3521        assert_eq!(results.len(), 2);
3522        assert!(results.iter().all(|r| r.preview.contains("test")));
3523    }
3524
3525    // ==================== Filter Tests ====================
3526
3527    #[test]
3528    fn test_language_filter() {
3529        let temp = TempDir::new().unwrap();
3530        let project = temp.path().join("project");
3531        fs::create_dir(&project).unwrap();
3532
3533        fs::write(project.join("main.rs"), "fn main() {}").unwrap();
3534        fs::write(project.join("main.js"), "function main() {}").unwrap();
3535
3536        let cache = CacheManager::new(&project);
3537        let indexer = Indexer::new(cache, IndexConfig::default());
3538        indexer.index(&project, false).unwrap();
3539
3540        let cache = CacheManager::new(&project);
3541
3542        let engine = QueryEngine::new(cache);
3543
3544        // Filter to Rust only
3545        let filter = QueryFilter {
3546            language: Some(Language::Rust),
3547            ..Default::default()
3548        };
3549        let results = engine.search("main", filter).unwrap();
3550
3551        assert!(results.iter().all(|r| r.lang == Language::Rust));
3552        assert!(results.iter().all(|r| r.path.ends_with(".rs")));
3553    }
3554
3555    #[test]
3556    fn test_kind_filter() {
3557        let temp = TempDir::new().unwrap();
3558        let project = temp.path().join("project");
3559        fs::create_dir(&project).unwrap();
3560
3561        fs::write(
3562            project.join("main.rs"),
3563            "struct Point {}\nfn main() {}\nimpl Point { fn new() {} }",
3564        )
3565        .unwrap();
3566
3567        let cache = CacheManager::new(&project);
3568        let indexer = Indexer::new(cache, IndexConfig::default());
3569        indexer.index(&project, false).unwrap();
3570
3571        let cache = CacheManager::new(&project);
3572
3573        let engine = QueryEngine::new(cache);
3574
3575        // Filter to functions only (includes methods)
3576        let filter = QueryFilter {
3577            symbols_mode: true,
3578            kind: Some(SymbolKind::Function),
3579            use_contains: true, // "mai" is substring of "main"
3580            ..Default::default()
3581        };
3582        // Search for "mai" which should match "main" (tri gram pattern will def be in index)
3583        let results = engine.search("mai", filter).unwrap();
3584
3585        // Should find main function
3586        assert!(!results.is_empty(), "Should find at least one result");
3587        assert!(
3588            results.iter().any(|r| r.symbol.as_deref() == Some("main")),
3589            "Should find 'main' function"
3590        );
3591    }
3592
3593    #[test]
3594    fn test_file_pattern_filter() {
3595        let temp = TempDir::new().unwrap();
3596        let project = temp.path().join("project");
3597        fs::create_dir_all(project.join("src")).unwrap();
3598        fs::create_dir_all(project.join("tests")).unwrap();
3599
3600        fs::write(project.join("src/lib.rs"), "fn foo() {}").unwrap();
3601        fs::write(project.join("tests/test.rs"), "fn foo() {}").unwrap();
3602
3603        let cache = CacheManager::new(&project);
3604        let indexer = Indexer::new(cache, IndexConfig::default());
3605        indexer.index(&project, false).unwrap();
3606
3607        let cache = CacheManager::new(&project);
3608
3609        let engine = QueryEngine::new(cache);
3610
3611        // Filter to src/ only
3612        let filter = QueryFilter {
3613            file_pattern: Some("src/".to_string()),
3614            ..Default::default()
3615        };
3616        let results = engine.search("foo", filter).unwrap();
3617
3618        assert!(results.iter().all(|r| r.path.contains("src/")));
3619        assert!(!results.iter().any(|r| r.path.contains("tests/")));
3620    }
3621
3622    #[test]
3623    fn test_limit_filter() {
3624        let temp = TempDir::new().unwrap();
3625        let project = temp.path().join("project");
3626        fs::create_dir(&project).unwrap();
3627
3628        // Create file with many matches
3629        let content = (0..20)
3630            .map(|i| format!("fn test{}() {{}}", i))
3631            .collect::<Vec<_>>()
3632            .join("\n");
3633        fs::write(project.join("main.rs"), content).unwrap();
3634
3635        let cache = CacheManager::new(&project);
3636        let indexer = Indexer::new(cache, IndexConfig::default());
3637        indexer.index(&project, false).unwrap();
3638
3639        let cache = CacheManager::new(&project);
3640
3641        let engine = QueryEngine::new(cache);
3642
3643        // Limit to 5 results
3644        let filter = QueryFilter {
3645            limit: Some(5),
3646            use_contains: true, // "test" is substring of "test0", "test1", etc.
3647            ..Default::default()
3648        };
3649        let results = engine.search("test", filter).unwrap();
3650
3651        assert_eq!(results.len(), 5);
3652    }
3653
3654    #[test]
3655    fn test_exact_match_filter() {
3656        let temp = TempDir::new().unwrap();
3657        let project = temp.path().join("project");
3658        fs::create_dir(&project).unwrap();
3659
3660        fs::write(
3661            project.join("main.rs"),
3662            "fn test() {}\nfn test_helper() {}\nfn other_test() {}",
3663        )
3664        .unwrap();
3665
3666        let cache = CacheManager::new(&project);
3667        let indexer = Indexer::new(cache, IndexConfig::default());
3668        indexer.index(&project, false).unwrap();
3669
3670        let cache = CacheManager::new(&project);
3671
3672        let engine = QueryEngine::new(cache);
3673
3674        // Exact match for "test"
3675        let filter = QueryFilter {
3676            symbols_mode: true,
3677            exact: true,
3678            ..Default::default()
3679        };
3680        let results = engine.search("test", filter).unwrap();
3681
3682        // Should only match exactly "test", not "test_helper" or "other_test"
3683        assert_eq!(results.len(), 1);
3684        assert_eq!(results[0].symbol.as_deref(), Some("test"));
3685    }
3686
3687    // ==================== Expand Mode Tests ====================
3688
3689    #[test]
3690    fn test_expand_mode() {
3691        let temp = TempDir::new().unwrap();
3692        let project = temp.path().join("project");
3693        fs::create_dir(&project).unwrap();
3694
3695        fs::write(
3696            project.join("main.rs"),
3697            "fn greet() {\n    println!(\"Hello\");\n    println!(\"World\");\n}",
3698        )
3699        .unwrap();
3700
3701        let cache = CacheManager::new(&project);
3702        let indexer = Indexer::new(cache, IndexConfig::default());
3703        indexer.index(&project, false).unwrap();
3704
3705        let cache = CacheManager::new(&project);
3706
3707        let engine = QueryEngine::new(cache);
3708
3709        // Search with expand mode
3710        let filter = QueryFilter {
3711            symbols_mode: true,
3712            expand: true,
3713            ..Default::default()
3714        };
3715        let results = engine.search("greet", filter).unwrap();
3716
3717        // Should have full function body in preview
3718        assert!(!results.is_empty());
3719        let result = &results[0];
3720        assert!(result.preview.contains("println"));
3721    }
3722
3723    // ==================== Edge Cases ====================
3724
3725    #[test]
3726    fn test_search_empty_index() {
3727        let temp = TempDir::new().unwrap();
3728        let project = temp.path().join("project");
3729        fs::create_dir(&project).unwrap();
3730
3731        let cache = CacheManager::new(&project);
3732        let indexer = Indexer::new(cache, IndexConfig::default());
3733        indexer.index(&project, false).unwrap();
3734
3735        let cache = CacheManager::new(&project);
3736
3737        let engine = QueryEngine::new(cache);
3738        let filter = QueryFilter::default();
3739        let results = engine.search("nonexistent", filter).unwrap();
3740
3741        assert_eq!(results.len(), 0);
3742    }
3743
3744    #[test]
3745    fn test_search_no_index() {
3746        let temp = TempDir::new().unwrap();
3747        let project = temp.path().join("project");
3748        fs::create_dir(&project).unwrap();
3749
3750        let cache = CacheManager::new(&project);
3751        let engine = QueryEngine::new(cache);
3752        let filter = QueryFilter::default();
3753
3754        // Should fail when index doesn't exist
3755        assert!(engine.search("test", filter).is_err());
3756    }
3757
3758    #[test]
3759    fn test_search_special_characters() {
3760        let temp = TempDir::new().unwrap();
3761        let project = temp.path().join("project");
3762        fs::create_dir(&project).unwrap();
3763
3764        fs::write(project.join("main.rs"), "let x = 42;\nlet y = x + 1;").unwrap();
3765
3766        let cache = CacheManager::new(&project);
3767        let indexer = Indexer::new(cache, IndexConfig::default());
3768        indexer.index(&project, false).unwrap();
3769
3770        let cache = CacheManager::new(&project);
3771
3772        let engine = QueryEngine::new(cache);
3773        let filter = QueryFilter::default();
3774
3775        // Search for special characters
3776        let results = engine.search("x + ", filter).unwrap();
3777        assert!(!results.is_empty());
3778    }
3779
3780    #[test]
3781    fn test_search_unicode() {
3782        let temp = TempDir::new().unwrap();
3783        let project = temp.path().join("project");
3784        fs::create_dir(&project).unwrap();
3785
3786        fs::write(project.join("main.rs"), "// 你好世界\nfn main() {}").unwrap();
3787
3788        let cache = CacheManager::new(&project);
3789        let indexer = Indexer::new(cache, IndexConfig::default());
3790        indexer.index(&project, false).unwrap();
3791
3792        let cache = CacheManager::new(&project);
3793
3794        let engine = QueryEngine::new(cache);
3795        let filter = QueryFilter {
3796            use_contains: true, // Unicode word boundaries may not work as expected
3797            force: true,        // Bypass broad query detection for 2-char Unicode pattern
3798            ..Default::default()
3799        };
3800
3801        // Search for unicode characters
3802        let results = engine.search("你好", filter).unwrap();
3803        assert!(!results.is_empty());
3804    }
3805
3806    #[test]
3807    fn test_case_sensitive_search() {
3808        let temp = TempDir::new().unwrap();
3809        let project = temp.path().join("project");
3810        fs::create_dir(&project).unwrap();
3811
3812        fs::write(project.join("main.rs"), "fn Test() {}\nfn test() {}").unwrap();
3813
3814        let cache = CacheManager::new(&project);
3815        let indexer = Indexer::new(cache, IndexConfig::default());
3816        indexer.index(&project, false).unwrap();
3817
3818        let cache = CacheManager::new(&project);
3819
3820        let engine = QueryEngine::new(cache);
3821        let filter = QueryFilter::default();
3822
3823        // Search is case-sensitive
3824        let results = engine.search("Test", filter).unwrap();
3825        assert!(results.iter().any(|r| r.preview.contains("Test()")));
3826    }
3827
3828    // ==================== Determinism Tests ====================
3829
3830    #[test]
3831    fn test_results_sorted_deterministically() {
3832        let temp = TempDir::new().unwrap();
3833        let project = temp.path().join("project");
3834        fs::create_dir(&project).unwrap();
3835
3836        fs::write(project.join("a.rs"), "fn test() {}").unwrap();
3837        fs::write(project.join("z.rs"), "fn test() {}").unwrap();
3838        fs::write(project.join("m.rs"), "fn test() {}\nfn test2() {}").unwrap();
3839
3840        let cache = CacheManager::new(&project);
3841        let indexer = Indexer::new(cache, IndexConfig::default());
3842        indexer.index(&project, false).unwrap();
3843
3844        let cache = CacheManager::new(&project);
3845
3846        let engine = QueryEngine::new(cache);
3847        let filter = QueryFilter::default();
3848
3849        // Run search multiple times
3850        let results1 = engine.search("test", filter.clone()).unwrap();
3851        let results2 = engine.search("test", filter.clone()).unwrap();
3852        let results3 = engine.search("test", filter).unwrap();
3853
3854        // Results should be identical and sorted by path then line
3855        assert_eq!(results1.len(), results2.len());
3856        assert_eq!(results1.len(), results3.len());
3857
3858        for i in 0..results1.len() {
3859            assert_eq!(results1[i].path, results2[i].path);
3860            assert_eq!(results1[i].path, results3[i].path);
3861            assert_eq!(results1[i].span.start_line, results2[i].span.start_line);
3862            assert_eq!(results1[i].span.start_line, results3[i].span.start_line);
3863        }
3864
3865        // Verify sorting (path ascending, then line ascending)
3866        for i in 0..results1.len().saturating_sub(1) {
3867            let curr = &results1[i];
3868            let next = &results1[i + 1];
3869            assert!(
3870                curr.path < next.path
3871                    || (curr.path == next.path && curr.span.start_line <= next.span.start_line)
3872            );
3873        }
3874    }
3875
3876    // ==================== Combined Filter Tests ====================
3877
3878    #[test]
3879    fn test_multiple_filters_combined() {
3880        let temp = TempDir::new().unwrap();
3881        let project = temp.path().join("project");
3882        fs::create_dir_all(project.join("src")).unwrap();
3883
3884        fs::write(project.join("src/main.rs"), "fn test() {}\nstruct Test {}").unwrap();
3885        fs::write(project.join("src/lib.rs"), "fn test() {}").unwrap();
3886        fs::write(project.join("test.js"), "function test() {}").unwrap();
3887
3888        let cache = CacheManager::new(&project);
3889        let indexer = Indexer::new(cache, IndexConfig::default());
3890        indexer.index(&project, false).unwrap();
3891
3892        let cache = CacheManager::new(&project);
3893
3894        let engine = QueryEngine::new(cache);
3895
3896        // Combine language, kind, and file pattern filters
3897        let filter = QueryFilter {
3898            language: Some(Language::Rust),
3899            kind: Some(SymbolKind::Function),
3900            file_pattern: Some("src/main".to_string()),
3901            symbols_mode: true,
3902            ..Default::default()
3903        };
3904        let results = engine.search("test", filter).unwrap();
3905
3906        // Should only find the function in src/main.rs
3907        assert_eq!(results.len(), 1);
3908        assert!(results[0].path.contains("src/main.rs"));
3909        assert_eq!(results[0].kind, SymbolKind::Function);
3910    }
3911
3912    // ==================== Helper Method Tests ====================
3913
3914    #[test]
3915    fn test_find_symbol_helper() {
3916        let temp = TempDir::new().unwrap();
3917        let project = temp.path().join("project");
3918        fs::create_dir(&project).unwrap();
3919
3920        fs::write(project.join("main.rs"), "fn greet() {}").unwrap();
3921
3922        let cache = CacheManager::new(&project);
3923        let indexer = Indexer::new(cache, IndexConfig::default());
3924        indexer.index(&project, false).unwrap();
3925
3926        let cache = CacheManager::new(&project);
3927
3928        let engine = QueryEngine::new(cache);
3929        let results = engine.find_symbol("greet").unwrap();
3930
3931        assert!(!results.is_empty());
3932        assert_eq!(results[0].kind, SymbolKind::Function);
3933    }
3934
3935    #[test]
3936    fn test_list_by_kind_helper() {
3937        let temp = TempDir::new().unwrap();
3938        let project = temp.path().join("project");
3939        fs::create_dir(&project).unwrap();
3940
3941        fs::write(
3942            project.join("main.rs"),
3943            "struct Point {}\nfn test() {}\nstruct Line {}",
3944        )
3945        .unwrap();
3946
3947        let cache = CacheManager::new(&project);
3948        let indexer = Indexer::new(cache, IndexConfig::default());
3949        indexer.index(&project, false).unwrap();
3950
3951        let cache = CacheManager::new(&project);
3952
3953        let engine = QueryEngine::new(cache);
3954
3955        // Search for structs that contain "oin" (Point contains it, Line doesn't)
3956        let filter = QueryFilter {
3957            kind: Some(SymbolKind::Struct),
3958            symbols_mode: true,
3959            use_contains: true, // "oin" is substring of "Point"
3960            ..Default::default()
3961        };
3962        let results = engine.search("oin", filter).unwrap();
3963
3964        // Should find Point struct
3965        assert!(!results.is_empty(), "Should find at least Point struct");
3966        assert!(results.iter().all(|r| r.kind == SymbolKind::Struct));
3967        assert!(results.iter().any(|r| r.symbol.as_deref() == Some("Point")));
3968    }
3969
3970    // ==================== Metadata Tests ====================
3971
3972    #[test]
3973    fn test_search_with_metadata() {
3974        let temp = TempDir::new().unwrap();
3975        let project = temp.path().join("project");
3976        fs::create_dir(&project).unwrap();
3977
3978        fs::write(project.join("main.rs"), "fn test() {}").unwrap();
3979
3980        let cache = CacheManager::new(&project);
3981        let indexer = Indexer::new(cache, IndexConfig::default());
3982        indexer.index(&project, false).unwrap();
3983
3984        let cache = CacheManager::new(&project);
3985
3986        let engine = QueryEngine::new(cache);
3987        let filter = QueryFilter::default();
3988        let response = engine.search_with_metadata("test", filter).unwrap();
3989
3990        // Check metadata is present (status might be stale if run inside git repo)
3991        assert!(!response.results.is_empty());
3992        // Note: can_trust_results may be false if running in a git repo without branch index
3993    }
3994
3995    // ==================== Multi-language Tests ====================
3996
3997    #[test]
3998    fn test_search_across_languages() {
3999        let temp = TempDir::new().unwrap();
4000        let project = temp.path().join("project");
4001        fs::create_dir(&project).unwrap();
4002
4003        fs::write(project.join("main.rs"), "fn greet() {}").unwrap();
4004        fs::write(project.join("main.ts"), "function greet() {}").unwrap();
4005        fs::write(project.join("main.py"), "def greet(): pass").unwrap();
4006
4007        let cache = CacheManager::new(&project);
4008        let indexer = Indexer::new(cache, IndexConfig::default());
4009        indexer.index(&project, false).unwrap();
4010
4011        let cache = CacheManager::new(&project);
4012
4013        let engine = QueryEngine::new(cache);
4014        let filter = QueryFilter::default();
4015        let results = engine.search("greet", filter).unwrap();
4016
4017        // Should find greet in all three languages
4018        assert!(results.len() >= 3);
4019        assert!(results.iter().any(|r| r.lang == Language::Rust));
4020        assert!(results.iter().any(|r| r.lang == Language::TypeScript));
4021        assert!(results.iter().any(|r| r.lang == Language::Python));
4022    }
4023}
4024
4025/// Process-local memo for the freshness verdict's expensive inputs.
4026///
4027/// `search_with_metadata` runs the freshness check on EVERY query, and
4028/// `find_references` calls it two or three times per MCP request. One snapshot
4029/// costs one `meta.db` connection, two `git` spawns and one `git status
4030/// --porcelain`; before this module the same query ran three connections and
4031/// three spawns, and the memo covered only the last of them. Results are memoised
4032/// briefly, keyed by workspace root.
4033///
4034/// What this trades away: an edit landing less than the TTL before a search can be
4035/// reported fresh. Agent tool round-trips are seconds apart, and `check_index_status`
4036/// — the explicit probe an agent uses when it cares — always bypasses the cache.
4037/// Every index write in this process invalidates the memo.
4038///
4039/// `REFLEX_FRESHNESS_TTL_MS` overrides the window; `0` disables caching entirely.
4040mod status_cache {
4041    use crate::cache::{CacheManager, FileFingerprint};
4042    use crate::git::WorktreeChanges;
4043    use crate::indexer::{Indexer, PathPolicy, looks_binary};
4044    use crate::models::{IndexConfig, IndexStatus, IndexWarning, IndexWarningDetails, Language};
4045    use anyhow::Result;
4046    use std::collections::{HashMap, HashSet};
4047    use std::path::{Path, PathBuf};
4048    use std::sync::{Arc, Mutex, OnceLock};
4049    use std::time::{Duration, Instant};
4050
4051    const DEFAULT_TTL_MS: u64 = 1_000;
4052
4053    pub type Verdict = (IndexStatus, bool, Option<IndexWarning>);
4054
4055    /// What one freshness computation found. The verdict is derived per caller
4056    /// (`QueryEngine::index_report_for`), because its wording depends on scope.
4057    pub struct Snapshot {
4058        /// A verdict that does not depend on the working tree at all (a cache
4059        /// written by another build). `None` means: judge by `changes`.
4060        pub decided: Option<Verdict>,
4061        /// Branch/commit context for humans; present in git repos even when fresh.
4062        pub details: Option<IndexWarningDetails>,
4063        /// Files whose content differs from what the index holds.
4064        pub changes: WorktreeChanges,
4065        /// meta.db could not be read, so nothing was compared. Readers are told
4066        /// `fresh` (as before), but an automatic update must not act on it.
4067        pub unreadable: bool,
4068        /// The cache was written by another released version (`decided` says so).
4069        pub foreign: bool,
4070        /// A rule file (`.reflex/config.toml`, an ignore file) differs from the one
4071        /// the last index run saw: WHICH files are indexed may have changed, so
4072        /// only a full run brings the index up to date. The paths are also listed
4073        /// in `changes` as modified.
4074        pub rules_changed: bool,
4075        /// When the tree was compared. A verdict settled after an update keeps
4076        /// the time of the check it came from, so it expires on that schedule.
4077        pub checked_at: Instant,
4078    }
4079
4080    impl Snapshot {
4081        fn unreadable() -> Self {
4082            Self {
4083                decided: Some((IndexStatus::Fresh, true, None)),
4084                details: None,
4085                changes: WorktreeChanges::default(),
4086                unreadable: true,
4087                foreign: false,
4088                rules_changed: false,
4089                checked_at: Instant::now(),
4090            }
4091        }
4092    }
4093
4094    struct Entry {
4095        computed_at: Instant,
4096        snapshot: Arc<Snapshot>,
4097    }
4098
4099    fn ttl() -> Duration {
4100        static TTL: OnceLock<Duration> = OnceLock::new();
4101        *TTL.get_or_init(|| {
4102            let ms = std::env::var("REFLEX_FRESHNESS_TTL_MS")
4103                .ok()
4104                .and_then(|v| v.trim().parse::<u64>().ok())
4105                .unwrap_or(DEFAULT_TTL_MS);
4106            Duration::from_millis(ms)
4107        })
4108    }
4109
4110    /// Bumped by every [`invalidate`]. A snapshot computed while it moved may
4111    /// describe the tree before an index write, so it is returned but not memoised.
4112    static EPOCH: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
4113
4114    fn store() -> &'static Mutex<HashMap<PathBuf, Entry>> {
4115        static STORE: OnceLock<Mutex<HashMap<PathBuf, Entry>>> = OnceLock::new();
4116        STORE.get_or_init(|| Mutex::new(HashMap::new()))
4117    }
4118
4119    fn key(root: &Path) -> PathBuf {
4120        root.canonicalize().unwrap_or_else(|_| root.to_path_buf())
4121    }
4122
4123    /// Only paths Reflex would index can make the index stale. Editing a README or
4124    /// anything under `target/` must not mark it permanently behind.
4125    fn indexable_with(path: &str, policy: &crate::indexer::PathPolicy) -> bool {
4126        crate::indexer::Indexer::is_indexable_path_with(Path::new(path), Some(policy))
4127    }
4128
4129    /// The memoised snapshot for the workspace `cache` belongs to.
4130    pub fn snapshot(cache: &CacheManager) -> Result<Arc<Snapshot>> {
4131        let root = cache.workspace_root();
4132        let key = key(&root);
4133        let ttl = ttl();
4134
4135        if !ttl.is_zero()
4136            && let Ok(map) = store().lock()
4137            && let Some(entry) = map.get(&key)
4138            && entry.computed_at.elapsed() < ttl
4139        {
4140            return Ok(Arc::clone(&entry.snapshot));
4141        }
4142
4143        let epoch = EPOCH.load(std::sync::atomic::Ordering::Acquire);
4144        let snapshot = Arc::new(compute(cache, &root)?);
4145
4146        if !ttl.is_zero()
4147            && let Ok(mut map) = store().lock()
4148            && EPOCH.load(std::sync::atomic::Ordering::Acquire) == epoch
4149        {
4150            map.insert(
4151                key,
4152                Entry {
4153                    computed_at: snapshot.checked_at,
4154                    snapshot: Arc::clone(&snapshot),
4155                },
4156            );
4157        }
4158
4159        Ok(snapshot)
4160    }
4161
4162    /// Where the candidate paths for a content check come from.
4163    enum Probe {
4164        /// `git status`, the dirty-at-index set and, when HEAD moved, the commit
4165        /// diff. Each path is then confirmed against its indexed fingerprint.
4166        Git(HashSet<String>),
4167        /// No git, or git could not answer: walk the tree and compare every file.
4168        Walk,
4169    }
4170
4171    /// Compare the working tree to what the index holds.
4172    ///
4173    /// Until 2.0.0 the baseline was the indexed COMMIT: any path `git status`
4174    /// listed made the index stale, so a dirty tree could never be fresh however
4175    /// often it was re-indexed, and an agent's session is dirty from its first edit
4176    /// to its last. The baseline is now the per-file fingerprint the indexer wrote
4177    /// (`size`, `mtime_ns`, blake3): a path git calls modified whose bytes the index
4178    /// already holds is not stale, and a commit of already-indexed content moves
4179    /// HEAD without changing a single file's verdict.
4180    fn compute(cache: &CacheManager, root: &Path) -> Result<Snapshot> {
4181        let is_git = crate::git::is_git_repo(root) && crate::git::is_git_available();
4182        let current_branch = if is_git {
4183            crate::git::read_head_branch(root).or_else(|| crate::git::get_current_branch(root).ok())
4184        } else {
4185            None
4186        };
4187
4188        // One connection for the schema hash, the branch row and the dirty set.
4189        let reads = match cache.status_reads(current_branch.as_deref()) {
4190            Ok(r) => r,
4191            Err(e) => {
4192                log::debug!("Could not read index status from meta.db: {}", e);
4193                return Ok(Snapshot::unreadable());
4194            }
4195        };
4196
4197        // A cache written by a different Reflex build. `validate()` no longer bails on
4198        // this (that turned a version skew into a rebuild stampede — see cache.rs), so
4199        // reads still work; they are simply not to be trusted, and the message names
4200        // who owns the cache so the user can pick a side.
4201        if !reads.schema_ok {
4202            let foreign = reads
4203                .owner
4204                .as_ref()
4205                .is_some_and(|(v, _)| v != env!("CARGO_PKG_VERSION"));
4206            let reason = match reads.owner {
4207                Some((v, sha)) if v != env!("CARGO_PKG_VERSION") => {
4208                    let sha = sha
4209                        .map(|s| format!(" (sha {})", &s[..s.len().min(7)]))
4210                        .unwrap_or_default();
4211                    format!(
4212                        "This .reflex/ was written by reflex {}{}; this binary is reflex {}. \
4213                         Results come from a cache format this version does not fully \
4214                         understand.",
4215                        v,
4216                        sha,
4217                        env!("CARGO_PKG_VERSION")
4218                    )
4219                }
4220                // Same version, or unstamped: the cache format changed under it. A
4221                // reindex brings it up to date; results until then may be partial.
4222                _ => "The index was built with a different cache format and needs \
4223                      rebuilding. Results may be incomplete until then."
4224                    .to_string(),
4225            };
4226
4227            let warning = IndexWarning::new(reason, "index_project");
4228            return Ok(Snapshot {
4229                decided: Some((IndexStatus::Stale, false, Some(warning))),
4230                details: None,
4231                changes: WorktreeChanges::default(),
4232                unreadable: false,
4233                foreign,
4234                rules_changed: false,
4235                checked_at: Instant::now(),
4236            });
4237        }
4238
4239        let config = cache.load_index_config().unwrap_or_else(|e| {
4240            log::debug!("Using default index config for freshness: {}", e);
4241            IndexConfig::default()
4242        });
4243        let policy = PathPolicy::from_config(root, &config);
4244
4245        let info = reads.branch_info.as_ref();
4246        let mut details = IndexWarningDetails {
4247            current_branch: current_branch.clone(),
4248            indexed_branch: info.map(|i| i.branch.clone()),
4249            current_commit: None,
4250            indexed_commit: info.map(|i| i.commit_sha.clone()),
4251            indexed_at: info.map(|i| i.last_indexed),
4252            checked_by: None,
4253        };
4254
4255        let probe = if current_branch.is_some() {
4256            let current_commit = crate::git::get_current_commit(root).ok();
4257            details.current_commit = current_commit.clone();
4258            let indexed_commit = info.map(|i| i.commit_sha.as_str());
4259            match git_candidates(
4260                root,
4261                &reads.dirty_at_index,
4262                indexed_commit,
4263                current_commit.as_deref(),
4264            ) {
4265                Ok(set) => Probe::Git(set),
4266                Err(e) => {
4267                    log::debug!("git could not name changed paths ({}); walking the tree", e);
4268                    Probe::Walk
4269                }
4270            }
4271        } else {
4272            Probe::Walk
4273        };
4274
4275        let rule_record: Option<std::collections::BTreeMap<String, String>> = reads
4276            .rule_files
4277            .as_deref()
4278            .and_then(|r| serde_json::from_str(r).ok());
4279        let mut rules_changed: Vec<String> = Vec::new();
4280
4281        let mut changes = match probe {
4282            Probe::Git(candidates) => {
4283                let keys: Vec<&str> = candidates.iter().map(String::as_str).collect();
4284                let fingerprints = cache.fingerprints_for(&keys)?;
4285                let mut out = WorktreeChanges::default();
4286                let mut added = Vec::new();
4287                for path in &candidates {
4288                    if let Some(record) = &rule_record
4289                        && crate::indexer::is_rule_file(path)
4290                        && !crate::indexer::FIXED_RULE_FILES.contains(&path.as_str())
4291                        && record.get(path).map(String::as_str)
4292                            != Some(crate::indexer::rule_file_hash(root, path).as_str())
4293                    {
4294                        rules_changed.push(path.clone());
4295                        continue;
4296                    }
4297                    classify_one(
4298                        root,
4299                        &config,
4300                        &policy,
4301                        path,
4302                        fingerprints.get(path),
4303                        &mut out,
4304                        &mut added,
4305                    );
4306                }
4307                // A new file counts only when the walk would reach it: git also
4308                // lists a tracked file that `.gitignore` now ignores, and no index
4309                // run will ever hold it.
4310                if !added.is_empty() {
4311                    let walked = Indexer::walked_among(root, &config, &policy, &added);
4312                    for path in added.iter().filter(|p| walked.contains(*p)) {
4313                        out.push_added(path);
4314                    }
4315                }
4316                details.checked_by = Some("git".to_string());
4317                out
4318            }
4319            Probe::Walk => {
4320                let fingerprints = fingerprints_all(cache)?;
4321                details.checked_by = Some("walk".to_string());
4322                walk_changes(root, &config, &policy, &fingerprints)
4323            }
4324        };
4325        if let Some(record) = &rule_record {
4326            for rel in crate::indexer::FIXED_RULE_FILES {
4327                let now = crate::indexer::rule_file_hash(root, rel);
4328                if record.get(rel).map(String::as_str).unwrap_or("") != now {
4329                    rules_changed.push(rel.to_string());
4330                }
4331            }
4332        }
4333        for rel in &rules_changed {
4334            changes.push_modified(rel);
4335        }
4336        changes.sort();
4337
4338        Ok(Snapshot {
4339            decided: None,
4340            details: Some(details),
4341            changes,
4342            unreadable: false,
4343            foreign: false,
4344            rules_changed: !rules_changed.is_empty(),
4345            checked_at: Instant::now(),
4346        })
4347    }
4348
4349    /// Paths whose content MAY differ from the index, in a git repository.
4350    ///
4351    /// Three sources, each necessary:
4352    /// * `git status` — edits, additions and deletions since HEAD;
4353    /// * the paths that were dirty when the index was written — an edit indexed
4354    ///   and then reverted with `git checkout -- f` is clean to git but differs
4355    ///   from the index;
4356    /// * `git diff --name-only indexed..HEAD` when HEAD moved — a commit, pull or
4357    ///   checkout changes tracked files without `git status` ever listing them.
4358    ///
4359    /// A path in none of the three has the bytes the index was built from.
4360    fn git_candidates(
4361        root: &Path,
4362        dirty_at_index: &[String],
4363        indexed_commit: Option<&str>,
4364        current_commit: Option<&str>,
4365    ) -> Result<HashSet<String>> {
4366        let mut set = crate::git::changed_paths(root)?;
4367        set.extend(dirty_at_index.iter().cloned());
4368        match (indexed_commit, current_commit) {
4369            (Some(indexed), Some(current)) if indexed != current => {
4370                if indexed == "unknown" {
4371                    anyhow::bail!("the index does not record a commit");
4372                }
4373                set.extend(crate::git::diff_names(root, indexed, current)?);
4374            }
4375            (None, _) | (_, None) => anyhow::bail!("no commit to diff against"),
4376            _ => {}
4377        }
4378        Ok(set)
4379    }
4380
4381    /// Every indexed fingerprint, memoised on the open index handle so a walk pays
4382    /// the table read once per index version.
4383    fn fingerprints_all(cache: &CacheManager) -> Result<Arc<HashMap<String, FileFingerprint>>> {
4384        match super::open_index::get_or_open(cache) {
4385            Ok(open) => open.fingerprints(cache),
4386            Err(_) => Ok(Arc::new(cache.load_fingerprints()?)),
4387        }
4388    }
4389
4390    /// Whether the file at `full` still has the bytes the index holds.
4391    ///
4392    /// A matching `(size, mtime_ns)` is proof enough; otherwise the file is hashed.
4393    /// That second step is what makes "reindexed but uncommitted" fresh: git lists
4394    /// the path, the mtime moved, and the hash says the index already has it.
4395    fn content_matches(full: &Path, md: &std::fs::Metadata, fp: &FileFingerprint) -> bool {
4396        if fp.stat_matches(md) {
4397            return true;
4398        }
4399        match std::fs::read(full) {
4400            Ok(bytes) => blake3::hash(&bytes).to_hex().as_str() == fp.hash,
4401            Err(_) => false,
4402        }
4403    }
4404
4405    /// Sort one candidate path into `out`, or leave it out when the indexer would.
4406    fn classify_one(
4407        root: &Path,
4408        config: &IndexConfig,
4409        policy: &PathPolicy,
4410        path: &str,
4411        fp: Option<&FileFingerprint>,
4412        out: &mut WorktreeChanges,
4413        added: &mut Vec<String>,
4414    ) {
4415        if !indexable_with(path, policy) {
4416            return;
4417        }
4418        let full = root.join(path);
4419        let md = if config.follow_symlinks {
4420            std::fs::metadata(&full)
4421        } else {
4422            std::fs::symlink_metadata(&full)
4423        };
4424        match (md, fp) {
4425            (Err(_), Some(_)) => out.push_deleted(path),
4426            (Err(_), None) => {}
4427            // A directory or an unfollowed symlink is nothing the indexer holds.
4428            (Ok(md), _) if !md.is_file() => {
4429                if fp.is_some() {
4430                    out.push_deleted(path);
4431                }
4432            }
4433            (Ok(md), _) if md.len() > config.max_file_size as u64 => {
4434                // Grown past the limit: the content differs and the next index
4435                // drops it. Not indexed before either → nothing to report.
4436                if fp.is_some() {
4437                    out.push_modified(path);
4438                }
4439            }
4440            // A new non-code file is sniffed the way the indexer sniffs it: a
4441            // binary is never indexed, so it can never be missing from the index.
4442            (Ok(_), None) => {
4443                if !Language::from_path(Path::new(path)).is_code() && looks_binary(&full) {
4444                    return;
4445                }
4446                added.push(path.to_string());
4447            }
4448            (Ok(md), Some(fp)) => {
4449                if !content_matches(&full, &md, fp) {
4450                    out.push_modified(path);
4451                }
4452            }
4453        }
4454    }
4455
4456    /// Compare every file the indexer would walk against the fingerprint table.
4457    ///
4458    /// Outside git this is the only way to know; the walk is parallel and the
4459    /// hash is computed only for files whose stat does not match, so on a warm
4460    /// cache it is a few milliseconds per thousand files.
4461    fn walk_changes(
4462        root: &Path,
4463        config: &IndexConfig,
4464        policy: &PathPolicy,
4465        fingerprints: &HashMap<String, FileFingerprint>,
4466    ) -> WorktreeChanges {
4467        let threads = std::thread::available_parallelism()
4468            .map(|n| n.get())
4469            .unwrap_or(1)
4470            .min(8);
4471        let mut builder = Indexer::walk_builder(root, config, policy);
4472        builder.threads(threads);
4473
4474        let seen: Mutex<Vec<(String, std::fs::Metadata)>> = Mutex::new(Vec::new());
4475        let max_size = config.max_file_size as u64;
4476        builder.build_parallel().run(|| {
4477            let seen = &seen;
4478            Box::new(move |entry| {
4479                let Ok(entry) = entry else {
4480                    return ignore::WalkState::Continue;
4481                };
4482                if !entry.file_type().map(|t| t.is_file()).unwrap_or(false) {
4483                    return ignore::WalkState::Continue;
4484                }
4485                let path = entry.path();
4486                if policy.classify(path).is_none() {
4487                    return ignore::WalkState::Continue;
4488                }
4489                let Ok(md) = entry.metadata() else {
4490                    return ignore::WalkState::Continue;
4491                };
4492                if md.len() > max_size {
4493                    return ignore::WalkState::Continue;
4494                }
4495                let rel = path
4496                    .strip_prefix(root)
4497                    .unwrap_or(path)
4498                    .to_string_lossy()
4499                    .replace('\\', "/");
4500                if let Ok(mut v) = seen.lock() {
4501                    v.push((rel, md));
4502                }
4503                ignore::WalkState::Continue
4504            })
4505        });
4506
4507        let seen = seen.into_inner().unwrap_or_default();
4508        let mut out = WorktreeChanges::default();
4509        let mut present: HashSet<&str> = HashSet::with_capacity(seen.len());
4510        for (rel, md) in &seen {
4511            present.insert(rel.as_str());
4512            match fingerprints.get(rel) {
4513                None => {
4514                    let full = root.join(rel);
4515                    if !Language::from_path(&full).is_code() && looks_binary(&full) {
4516                        continue;
4517                    }
4518                    out.push_added(rel);
4519                }
4520                Some(fp) => {
4521                    if !content_matches(&root.join(rel), md, fp) {
4522                        out.push_modified(rel);
4523                    }
4524                }
4525            }
4526        }
4527        for path in fingerprints.keys() {
4528            if !present.contains(path.as_str()) {
4529                out.push_deleted(path);
4530            }
4531        }
4532        out
4533    }
4534
4535    /// What an automatic update must do to make the index match the tree.
4536    pub fn update_plan(cache: &CacheManager) -> Result<(super::UpdatePlan, Arc<Snapshot>)> {
4537        let snap = snapshot(cache)?;
4538        Ok((plan_of(&snap), snap))
4539    }
4540
4541    fn plan_of(snap: &Snapshot) -> super::UpdatePlan {
4542        use super::UpdatePlan;
4543        if snap.unreadable {
4544            return UpdatePlan::Unknown(
4545                "the index metadata (meta.db) could not be read".to_string(),
4546            );
4547        }
4548        if let Some((status, _, warning)) = &snap.decided {
4549            if *status == IndexStatus::Fresh {
4550                return UpdatePlan::Fresh;
4551            }
4552            let reason = warning
4553                .as_ref()
4554                .map(|w| w.reason.clone())
4555                .unwrap_or_default();
4556            return if snap.foreign {
4557                UpdatePlan::Foreign(reason)
4558            } else {
4559                UpdatePlan::Full(Vec::new())
4560            };
4561        }
4562        let c = &snap.changes;
4563        if c.is_empty() {
4564            return UpdatePlan::Fresh;
4565        }
4566        let mut paths: Vec<PathBuf> = c
4567            .modified
4568            .iter()
4569            .chain(&c.added)
4570            .chain(&c.deleted)
4571            .map(PathBuf::from)
4572            .collect();
4573        paths.sort();
4574        paths.dedup();
4575        if snap.rules_changed || c.truncated {
4576            UpdatePlan::Full(paths)
4577        } else {
4578            UpdatePlan::Paths(paths)
4579        }
4580    }
4581
4582    /// After an update of `paths` (every change `prior` listed): when each now
4583    /// matches the index, remember "fresh" as the verdict, dated when `prior` was
4584    /// checked, and return true. The tree is not compared again, exactly as a
4585    /// memoised verdict is trusted for its window; a change made since `prior`
4586    /// shows once that window ends. False (nothing remembered) when a path still
4587    /// differs, the window has passed, or memoising is off.
4588    pub fn settle(cache: &CacheManager, prior: &Snapshot, paths: &[PathBuf]) -> bool {
4589        let ttl = ttl();
4590        if ttl.is_zero()
4591            || prior.checked_at.elapsed() >= ttl
4592            || prior.decided.is_some()
4593            || prior.rules_changed
4594            || prior.changes.truncated
4595        {
4596            return false;
4597        }
4598        let root = cache.workspace_root();
4599        let Ok(config) = cache.load_index_config() else {
4600            return false;
4601        };
4602        let policy = PathPolicy::from_config(&root, &config);
4603        let rels: Vec<String> = paths
4604            .iter()
4605            .map(|p| p.to_string_lossy().replace('\\', "/"))
4606            .collect();
4607        let keys: Vec<&str> = rels.iter().map(String::as_str).collect();
4608        let Ok(fingerprints) = cache.fingerprints_for(&keys) else {
4609            return false;
4610        };
4611        let mut still = WorktreeChanges::default();
4612        let mut added = Vec::new();
4613        for rel in &rels {
4614            classify_one(
4615                &root,
4616                &config,
4617                &policy,
4618                rel,
4619                fingerprints.get(rel),
4620                &mut still,
4621                &mut added,
4622            );
4623        }
4624        if !still.is_empty() || !added.is_empty() {
4625            return false;
4626        }
4627        let settled = Arc::new(Snapshot {
4628            decided: None,
4629            details: prior.details.clone(),
4630            changes: WorktreeChanges::default(),
4631            unreadable: false,
4632            foreign: false,
4633            rules_changed: false,
4634            checked_at: prior.checked_at,
4635        });
4636        match store().lock() {
4637            Ok(mut map) => {
4638                map.insert(
4639                    key(&root),
4640                    Entry {
4641                        computed_at: prior.checked_at,
4642                        snapshot: settled,
4643                    },
4644                );
4645                true
4646            }
4647            Err(_) => false,
4648        }
4649    }
4650
4651    /// Drop any memo for `root`, so the next read is fresh.
4652    ///
4653    /// Used by `check_index_status`, the explicit probe: an agent that asks whether
4654    /// the index is current must never be answered from a cache. Also called around
4655    /// every index write.
4656    pub fn invalidate(root: &Path) {
4657        let key = key(root);
4658        if let Ok(mut map) = store().lock() {
4659            EPOCH.fetch_add(1, std::sync::atomic::Ordering::AcqRel);
4660            map.remove(&key);
4661        }
4662    }
4663}