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