Skip to main content

reflex/query/
filter.rs

1//! Query filter types and stateless filtering helpers
2
3use regex::Regex;
4
5use crate::models::SymbolKind;
6
7/// Query filter options
8#[derive(Debug, Clone)]
9pub struct QueryFilter {
10    /// Language filter (None = all languages)
11    pub language: Option<crate::models::Language>,
12    /// Symbol kind filter (None = all kinds)
13    pub kind: Option<SymbolKind>,
14    /// Use AST pattern matching (vs lexical search)
15    pub use_ast: bool,
16    /// Use regex pattern matching
17    pub use_regex: bool,
18    /// Maximum number of results
19    pub limit: Option<usize>,
20    /// Search symbol definitions only (vs full-text)
21    pub symbols_mode: bool,
22    /// Show full symbol body (from span.start_line to span.end_line)
23    pub expand: bool,
24    /// File path filter (substring match)
25    pub file_pattern: Option<String>,
26    /// Exact symbol name match (no substring matching)
27    pub exact: bool,
28    /// Use substring matching instead of word-boundary matching (opt-in, expansive)
29    pub use_contains: bool,
30    /// Match letters regardless of case (`rg -i`). Applies to whole-identifier,
31    /// substring and regex line searches alike; the engine runs the query as a
32    /// `(?i)` regex whose literals are looked up under every case variant.
33    pub ignore_case: bool,
34    /// Set by the engine when it rewrote a literal pattern into a regex (brackets,
35    /// `ignore_case`): the original literal. Drives the broad-query guard (which
36    /// must judge the literal's length, not the regex's) and the result `kind`.
37    #[doc(hidden)]
38    pub rewritten_from: Option<String>,
39    /// Drop plain-text-tier results (docs, config, templates) from this query.
40    ///
41    /// The tier is included by default, because an agent searching for a config key
42    /// wants the YAML as well as the struct. It is excluded for questions that are
43    /// only meaningful about code — `find_references` in particular, whose reference
44    /// search is a plain trigram scan and would otherwise return the name in a
45    /// changelog entry as a "call site".
46    pub exclude_text: bool,
47    /// Search lock files too (`Cargo.lock`, `package-lock.json`, …). They are
48    /// indexed but left out of every search by default; `lang: "lock"` selects
49    /// them alone.
50    pub include_locks: bool,
51    /// Search generated files too (`*.pb.go`, `*.min.js`, `*.map`, …). Same
52    /// default as lock files; `lang: "generated"` selects them alone.
53    pub include_generated: bool,
54    /// Count matches without materialising them: no previews, no grouping, no
55    /// result rows. `total_count` / `pagination.total` carry the exact line count
56    /// and `QueryResponse.file_count` the files with a match. Honoured only by the
57    /// full-text line searches (trigram and regex) with no `limit`; symbol and AST
58    /// searches ignore it. Set by `--count`, `mode: "count"` and `count_occurrences`.
59    pub count_only: bool,
60    /// Query timeout in seconds (0 = no timeout)
61    pub timeout_secs: u64,
62    /// Glob patterns to include (empty = all files)
63    pub glob_patterns: Vec<String>,
64    /// Glob patterns to exclude (applied after includes)
65    pub exclude_patterns: Vec<String>,
66    /// Return only unique file paths (deduplicated)
67    pub paths_only: bool,
68    /// Pagination offset (skip first N results after sorting)
69    pub offset: Option<usize>,
70    /// Force execution of potentially expensive queries (bypass broad query detection)
71    pub force: bool,
72    /// Suppress warning/info output (for --json mode to ensure pure JSON output)
73    pub suppress_output: bool,
74    /// Include dependency information in results
75    pub include_dependencies: bool,
76    /// Number of context lines to show before and after each match (default: 0 = disabled)
77    pub context_lines: usize,
78    /// Record per-phase timings into `QueryResponse.timings`.
79    pub collect_timings: bool,
80    /// Verify every candidate even with a `limit`, so `pagination.total` is exact.
81    /// Set by callers whose contract promises an exact total for a page
82    /// (`find_references`). Without it, a list-mode search stops once the page is
83    /// full and reports `total_is_exact: false`.
84    pub require_exact_total: bool,
85    /// Test-only: Override large index threshold (None = use default of 20,000)
86    #[doc(hidden)]
87    pub test_large_index_threshold: Option<usize>,
88    /// Test-only: Override short pattern threshold (None = use default of 4)
89    #[doc(hidden)]
90    pub test_short_pattern_threshold: Option<usize>,
91}
92
93impl Default for QueryFilter {
94    fn default() -> Self {
95        Self {
96            language: None,
97            kind: None,
98            use_ast: false,
99            use_regex: false,
100            limit: Some(100), // Default: limit to 100 results for token efficiency
101            symbols_mode: false,
102            expand: false,
103            file_pattern: None,
104            exact: false,
105            use_contains: false, // Default: word-boundary matching
106            ignore_case: false,  // Default: case-sensitive
107            rewritten_from: None,
108            exclude_text: false,      // Default: docs and config are searched too
109            include_locks: false,     // Default: lock files stay out
110            include_generated: false, // Default: generated files stay out
111            count_only: false,        // Default: materialise results
112            timeout_secs: 30,         // 30 seconds default timeout
113            glob_patterns: Vec::new(),
114            exclude_patterns: Vec::new(),
115            paths_only: false,
116            offset: None,
117            force: false,                       // Default: enable broad query detection
118            suppress_output: false,             // Default: show warnings/info
119            include_dependencies: false,        // Default: don't load dependencies for performance
120            context_lines: 0,                   // Default: no context lines shown
121            collect_timings: false,             // Default: no per-phase timings
122            require_exact_total: false,         // Default: list mode may stop early
123            test_large_index_threshold: None,   // Default: use production threshold (20,000)
124            test_short_pattern_threshold: None, // Default: use production threshold (4)
125        }
126    }
127}
128
129impl QueryFilter {
130    /// Whether this query is a count-only full-text LINE search: the one shape
131    /// the verifier can answer with two numbers instead of result rows.
132    pub fn count_only_line_search(&self) -> bool {
133        self.count_only
134            && self.limit.is_none()
135            && !self.symbols_mode
136            && !self.use_ast
137            && self.kind.is_none()
138    }
139}
140
141/// Whether a file of language `lang` belongs in this query's results.
142///
143/// An explicit `want` selects exactly that language (so `lang: "lock"` is how a
144/// caller asks for lock files alone). Otherwise the text tier is in unless
145/// `exclude_text`, and the lock / generated tiers are out unless asked for.
146pub fn tier_admits(
147    lang: crate::models::Language,
148    want: Option<crate::models::Language>,
149    exclude_text: bool,
150    include_locks: bool,
151    include_generated: bool,
152) -> bool {
153    use crate::models::Language;
154    if let Some(want) = want {
155        return lang == want;
156    }
157    match lang {
158        Language::Text => !exclude_text,
159        Language::Lock => include_locks,
160        Language::Generated => include_generated,
161        _ => true,
162    }
163}
164
165/// Whether `lang` was left out only because nothing asked for it: the count of
166/// such candidate files explains a zero result.
167pub fn excluded_by_default(
168    lang: crate::models::Language,
169    want: Option<crate::models::Language>,
170    include_locks: bool,
171    include_generated: bool,
172) -> bool {
173    use crate::models::Language;
174    want.is_none()
175        && match lang {
176            Language::Lock => !include_locks,
177            Language::Generated => !include_generated,
178            _ => false,
179        }
180}
181
182/// Explain a zero result when the only candidate files were excluded by default.
183pub fn excluded_by_default_hint_text(files: usize) -> String {
184    format!(
185        "{} candidate file(s) were lock or generated files, which every search leaves \
186         out by default — pass include_locks:true / include_generated:true \
187         (--include-locks / --include-generated on the CLI), or lang:\"lock\" / \
188         lang:\"generated\", to search them.",
189        files
190    )
191}
192
193/// Map a language keyword to its corresponding SymbolKind.
194///
195/// When users search for keywords like "class" or "function" with --symbols,
196/// automatically infer the kind filter to return only symbols of that type.
197pub fn keyword_to_kind(keyword: &str) -> Option<SymbolKind> {
198    match keyword {
199        "class" => Some(SymbolKind::Class),
200        "struct" => Some(SymbolKind::Struct),
201        "enum" => Some(SymbolKind::Enum),
202        "interface" => Some(SymbolKind::Interface),
203        "trait" => Some(SymbolKind::Trait),
204        "type" => Some(SymbolKind::Type),
205        "record" => Some(SymbolKind::Struct), // C# record types
206        "function" | "fn" | "def" | "func" => Some(SymbolKind::Function),
207        "const" | "static" => Some(SymbolKind::Constant),
208        "var" | "let" => Some(SymbolKind::Variable),
209        "mod" | "module" | "namespace" => Some(SymbolKind::Module),
210        "impl" | "async" => None,
211        _ => None,
212    }
213}
214
215/// Check if pattern appears at word boundaries in a line.
216///
217/// Used for default (restrictive) matching to find complete identifiers
218/// rather than substrings.
219pub fn has_word_boundary_match(line: &str, pattern: &str) -> bool {
220    let escaped_pattern = regex::escape(pattern);
221    let pattern_with_boundaries = format!(r"\b{}\b", escaped_pattern);
222
223    if let Ok(re) = Regex::new(&pattern_with_boundaries) {
224        re.is_match(line)
225    } else {
226        log::debug!(
227            "Word boundary regex failed for pattern '{}', falling back to substring",
228            pattern
229        );
230        line.contains(pattern)
231    }
232}
233
234/// Bracket characters that make a whole-token literal search structurally unmatchable.
235///
236/// Whole-token matching wraps the pattern as `\b<pattern>\b`. A pattern ending in `)`
237/// or `>` can never satisfy the trailing `\b`, because the next character is almost
238/// never a word character. So `unwrap()`, `#[derive(` and `-> Result<` all returned a
239/// silent `0` in the 1.7.0 field test, against ripgrep counts of 1221, 1141 and 2139.
240/// The 1.7.2 fix lived only in the MCP layer; the CLI and HTTP surfaces kept
241/// returning the confident zero until 2.0.0, when the rewrite moved here.
242pub const REGEX_ONLY_CHARS: &[char] = &['(', ')', '[', ']', '{', '}', '<', '>'];
243
244/// A literal pattern rewritten so it cannot silently return zero.
245#[derive(Debug, Clone, PartialEq, Eq)]
246pub struct LiteralPattern {
247    /// What to actually search for (regex-escaped when `use_regex` is set).
248    pub effective: String,
249    /// Whether the query must run down the regex path.
250    pub use_regex: bool,
251    /// Explanation for the caller when the pattern was rewritten.
252    pub warning: Option<String>,
253}
254
255/// Make a literal pattern searchable, rather than letting it return a confident zero.
256///
257/// A pattern containing brackets cannot match under whole-token rules, so it is
258/// escaped and routed to the regex path, which is substring-based. The caller is told
259/// in `QueryResponse::warnings` — the rewrite is never silent.
260///
261/// `ignore_case` is also a rewrite: the query becomes a `(?i)` regex (the caller's
262/// own regex verbatim; a substring search escaped; a whole-identifier search
263/// escaped and wrapped in `\b…\b`, the same wrap the literal matcher applies).
264/// The regex path then looks the literals up under every case variant, so
265/// `ignore_case` costs about what the case-sensitive query costs. This rewrite
266/// carries no warning. The zero-result substring hint is not produced under
267/// `ignore_case`, because the regex path does not count substring-only lines.
268///
269/// No rewrite happens when the query is not a line search at all: symbol names
270/// never contain brackets, and an AST pattern is an S-expression whose parens are
271/// the syntax. A regex or substring query is never bracket-rewritten.
272pub fn prepare_literal_pattern(pattern: &str, filter: &QueryFilter) -> LiteralPattern {
273    let not_a_line_search = filter.use_ast || filter.symbols_mode || filter.kind.is_some();
274    let not_a_literal_line_search = filter.use_regex || filter.use_contains || not_a_line_search;
275
276    let mut out = if not_a_literal_line_search || !pattern.contains(REGEX_ONLY_CHARS) {
277        LiteralPattern {
278            effective: pattern.to_string(),
279            use_regex: filter.use_regex,
280            warning: None,
281        }
282    } else {
283        LiteralPattern {
284            effective: regex::escape(pattern),
285            use_regex: true,
286            warning: Some(format!(
287                "Pattern {:?} contains brackets, which a whole-identifier search can never \
288                 match. Searched it as an escaped regex instead (substring semantics). For \
289                 explicit control use a regex search (search_regex / --regex) or substring \
290                 mode (contains:true / --contains).",
291                pattern
292            )),
293        }
294    };
295
296    if filter.ignore_case && !not_a_line_search {
297        let body = if filter.use_regex {
298            pattern.to_string()
299        } else if filter.use_contains || out.use_regex {
300            regex::escape(pattern)
301        } else {
302            format!(r"\b{}\b", regex::escape(pattern))
303        };
304        out.effective = format!("(?i){}", body);
305        out.use_regex = true;
306    }
307
308    out
309}
310
311/// Explain a zero-result whole-identifier search by naming the substring count.
312///
313/// This is the single line that would have prevented every wrong conclusion in the
314/// 1.7.0 field test: an agent that sees `0` for `verify_csrf` concludes "no callers"
315/// and acts on it, when 89 lines contain `verify_csrf_form_field`.
316pub fn substring_hint_text(count: usize, pattern: &str) -> String {
317    format!(
318        "0 whole-identifier matches; {} substring matches — pass contains:true \
319         (--contains on the CLI) to see them. Reflex matches whole identifiers by \
320         default, so {:?} does not match longer names that merely contain it.",
321        count, pattern
322    )
323}
324
325#[cfg(test)]
326mod literal_pattern_tests {
327    use super::*;
328
329    fn plain() -> QueryFilter {
330        QueryFilter::default()
331    }
332
333    #[test]
334    fn bracket_patterns_are_escaped_and_routed_to_regex() {
335        for p in [
336            "unwrap()",
337            "#[derive(",
338            "-> Result<",
339            "RealmId::nil()",
340            "vec![]",
341        ] {
342            let got = prepare_literal_pattern(p, &plain());
343            assert!(got.use_regex, "{p} must run as a regex");
344            assert_eq!(got.effective, regex::escape(p));
345            let w = got.warning.expect("rewrite must be reported");
346            assert!(w.contains("bracket"), "{w}");
347            assert!(w.contains(p), "warning names the original pattern: {w}");
348        }
349    }
350
351    #[test]
352    fn plain_identifiers_are_untouched() {
353        let got = prepare_literal_pattern("verify_csrf", &plain());
354        assert_eq!(
355            got,
356            LiteralPattern {
357                effective: "verify_csrf".into(),
358                use_regex: false,
359                warning: None
360            }
361        );
362    }
363
364    #[test]
365    fn ignore_case_becomes_a_case_insensitive_regex() {
366        let ic = QueryFilter {
367            ignore_case: true,
368            ..plain()
369        };
370        // Whole identifier: escaped and word-bounded, no warning.
371        let got = prepare_literal_pattern("realm.id", &ic);
372        assert_eq!(got.effective, r"(?i)\brealm\.id\b");
373        assert!(got.use_regex);
374        assert!(got.warning.is_none());
375
376        // Substring: escaped only.
377        let got = prepare_literal_pattern(
378            "realm.id",
379            &QueryFilter {
380                use_contains: true,
381                ..ic.clone()
382            },
383        );
384        assert_eq!(got.effective, r"(?i)realm\.id");
385        assert!(got.warning.is_none());
386
387        // The caller's own regex is kept verbatim.
388        let got = prepare_literal_pattern(
389            r"realm_?id\b",
390            &QueryFilter {
391                use_regex: true,
392                ..ic.clone()
393            },
394        );
395        assert_eq!(got.effective, r"(?i)realm_?id\b");
396
397        // Brackets: the bracket rewrite (substring + warning) happens first.
398        let got = prepare_literal_pattern("unwrap()", &ic);
399        assert_eq!(got.effective, r"(?i)unwrap\(\)");
400        assert!(got.warning.is_some());
401
402        // Not a line search: untouched.
403        for f in [
404            QueryFilter {
405                symbols_mode: true,
406                ..ic.clone()
407            },
408            QueryFilter {
409                kind: Some(SymbolKind::Function),
410                ..ic.clone()
411            },
412            QueryFilter {
413                use_ast: true,
414                ..ic.clone()
415            },
416        ] {
417            let got = prepare_literal_pattern("RealmId", &f);
418            assert_eq!(got.effective, "RealmId");
419            assert!(!got.use_regex);
420        }
421    }
422
423    #[test]
424    fn non_literal_modes_are_never_rewritten() {
425        let cases: Vec<(&str, QueryFilter)> = vec![
426            (
427                "contains",
428                QueryFilter {
429                    use_contains: true,
430                    ..plain()
431                },
432            ),
433            (
434                "regex",
435                QueryFilter {
436                    use_regex: true,
437                    ..plain()
438                },
439            ),
440            (
441                "symbols",
442                QueryFilter {
443                    symbols_mode: true,
444                    ..plain()
445                },
446            ),
447            (
448                "kind",
449                QueryFilter {
450                    kind: Some(SymbolKind::Function),
451                    ..plain()
452                },
453            ),
454            (
455                "ast",
456                QueryFilter {
457                    use_ast: true,
458                    ..plain()
459                },
460            ),
461        ];
462        for (name, f) in cases {
463            let got = prepare_literal_pattern("unwrap()", &f);
464            assert_eq!(
465                got.effective, "unwrap()",
466                "{name}: pattern must be verbatim"
467            );
468            assert_eq!(
469                got.use_regex, f.use_regex,
470                "{name}: regex flag passes through"
471            );
472            assert!(got.warning.is_none(), "{name}: no warning");
473        }
474    }
475
476    #[test]
477    fn hint_names_the_count_and_both_switches() {
478        let h = substring_hint_text(89, "verify_csrf");
479        assert!(h.contains("89 substring match"));
480        assert!(h.contains("contains:true"));
481        assert!(h.contains("--contains"));
482        assert!(h.contains("verify_csrf"));
483    }
484}