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_code with regex:true / --regex) \
290                 or substring 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/// Explain a symbol search that can find nothing: `language` is code with no
326/// symbol parser (Swift), so a confident zero would read as "no definitions".
327pub fn no_symbol_parser_warning(filter: &QueryFilter) -> Option<String> {
328    let language = filter.language?;
329    let symbol_search = filter.symbols_mode || filter.kind.is_some();
330    (symbol_search
331        && language.is_code()
332        && !crate::parsers::ParserFactory::has_symbol_parser(language))
333    .then(|| {
334        format!(
335            "{0:?} has no symbol parser, so a symbol search finds no {0:?} definitions. \
336             Full-text search (without symbols / kind) still finds them.",
337            language
338        )
339    })
340}
341
342/// Warn when a literal line search looks like a regular expression: a class escape
343/// (`\w`, `\s`, `\d`, `\b`), an escaped regex character (`\.`, `\(`, `\|`, …) or
344/// `.*` / `.+`. It runs as literal text, so it finds the text itself, or nothing.
345/// Since 2026-10-30 a regex is `search_code` with `regex:true`, not a tool of its own,
346/// and `impl\s+\w+\s+for` without the flag counted 1 line instead of 58. A pattern
347/// with brackets already carries the rewrite warning, which names `regex:true`.
348/// The text names `search_code`: `list_locations` and `find_references` take no
349/// `regex` key, and "pass regex:true" there sent an agent to Grep (2026-10-31).
350pub fn regex_syntax_warning(pattern: &str, filter: &QueryFilter) -> Option<String> {
351    if filter.use_regex || filter.use_ast || pattern.contains(REGEX_ONLY_CHARS) {
352        return None;
353    }
354    let escape = pattern
355        .as_bytes()
356        .windows(2)
357        .any(|w| w[0] == b'\\' && b"wWsSdDbB.()[]{}|+*?^$".contains(&w[1]));
358    (escape || pattern.contains(".*") || pattern.contains(".+")).then(|| {
359        format!(
360            "Pattern {:?} looks like a regular expression, but it was searched as literal \
361             text. Use search_code with regex:true (--regex on the CLI) to search it as a \
362             regex.",
363            pattern
364        )
365    })
366}
367
368#[cfg(test)]
369mod literal_pattern_tests {
370    use super::*;
371
372    fn plain() -> QueryFilter {
373        QueryFilter::default()
374    }
375
376    #[test]
377    fn regex_syntax_in_a_literal_search_warns() {
378        for p in [r"impl\s+\w+\s+for", r"foo\.bar", r"get_.*_id", r"^\d+"] {
379            let w = regex_syntax_warning(p, &plain()).unwrap_or_else(|| panic!("{p}"));
380            assert!(w.contains("search_code with regex:true"), "{w}");
381        }
382        let contains = QueryFilter {
383            use_contains: true,
384            ..plain()
385        };
386        assert!(regex_syntax_warning(r"\w+_id", &contains).is_some());
387        // A regex search, a bracket pattern (it has its own warning) and plain code
388        // with string escapes do not warn.
389        let regex = QueryFilter {
390            use_regex: true,
391            ..plain()
392        };
393        assert!(regex_syntax_warning(r"impl\s+\w+", &regex).is_none());
394        for p in [
395            r"fn (get|set)_\w+",
396            "verify_csrf",
397            r#"\"name\""#,
398            r"C:\\temp",
399            "a.b",
400            r"\n",
401        ] {
402            assert!(regex_syntax_warning(p, &plain()).is_none(), "{p}");
403        }
404    }
405
406    #[test]
407    fn bracket_patterns_are_escaped_and_routed_to_regex() {
408        for p in [
409            "unwrap()",
410            "#[derive(",
411            "-> Result<",
412            "RealmId::nil()",
413            "vec![]",
414        ] {
415            let got = prepare_literal_pattern(p, &plain());
416            assert!(got.use_regex, "{p} must run as a regex");
417            assert_eq!(got.effective, regex::escape(p));
418            let w = got.warning.expect("rewrite must be reported");
419            assert!(w.contains("bracket"), "{w}");
420            assert!(w.contains(p), "warning names the original pattern: {w}");
421        }
422    }
423
424    #[test]
425    fn plain_identifiers_are_untouched() {
426        let got = prepare_literal_pattern("verify_csrf", &plain());
427        assert_eq!(
428            got,
429            LiteralPattern {
430                effective: "verify_csrf".into(),
431                use_regex: false,
432                warning: None
433            }
434        );
435    }
436
437    #[test]
438    fn ignore_case_becomes_a_case_insensitive_regex() {
439        let ic = QueryFilter {
440            ignore_case: true,
441            ..plain()
442        };
443        // Whole identifier: escaped and word-bounded, no warning.
444        let got = prepare_literal_pattern("realm.id", &ic);
445        assert_eq!(got.effective, r"(?i)\brealm\.id\b");
446        assert!(got.use_regex);
447        assert!(got.warning.is_none());
448
449        // Substring: escaped only.
450        let got = prepare_literal_pattern(
451            "realm.id",
452            &QueryFilter {
453                use_contains: true,
454                ..ic.clone()
455            },
456        );
457        assert_eq!(got.effective, r"(?i)realm\.id");
458        assert!(got.warning.is_none());
459
460        // The caller's own regex is kept verbatim.
461        let got = prepare_literal_pattern(
462            r"realm_?id\b",
463            &QueryFilter {
464                use_regex: true,
465                ..ic.clone()
466            },
467        );
468        assert_eq!(got.effective, r"(?i)realm_?id\b");
469
470        // Brackets: the bracket rewrite (substring + warning) happens first.
471        let got = prepare_literal_pattern("unwrap()", &ic);
472        assert_eq!(got.effective, r"(?i)unwrap\(\)");
473        assert!(got.warning.is_some());
474
475        // Not a line search: untouched.
476        for f in [
477            QueryFilter {
478                symbols_mode: true,
479                ..ic.clone()
480            },
481            QueryFilter {
482                kind: Some(SymbolKind::Function),
483                ..ic.clone()
484            },
485            QueryFilter {
486                use_ast: true,
487                ..ic.clone()
488            },
489        ] {
490            let got = prepare_literal_pattern("RealmId", &f);
491            assert_eq!(got.effective, "RealmId");
492            assert!(!got.use_regex);
493        }
494    }
495
496    #[test]
497    fn non_literal_modes_are_never_rewritten() {
498        let cases: Vec<(&str, QueryFilter)> = vec![
499            (
500                "contains",
501                QueryFilter {
502                    use_contains: true,
503                    ..plain()
504                },
505            ),
506            (
507                "regex",
508                QueryFilter {
509                    use_regex: true,
510                    ..plain()
511                },
512            ),
513            (
514                "symbols",
515                QueryFilter {
516                    symbols_mode: true,
517                    ..plain()
518                },
519            ),
520            (
521                "kind",
522                QueryFilter {
523                    kind: Some(SymbolKind::Function),
524                    ..plain()
525                },
526            ),
527            (
528                "ast",
529                QueryFilter {
530                    use_ast: true,
531                    ..plain()
532                },
533            ),
534        ];
535        for (name, f) in cases {
536            let got = prepare_literal_pattern("unwrap()", &f);
537            assert_eq!(
538                got.effective, "unwrap()",
539                "{name}: pattern must be verbatim"
540            );
541            assert_eq!(
542                got.use_regex, f.use_regex,
543                "{name}: regex flag passes through"
544            );
545            assert!(got.warning.is_none(), "{name}: no warning");
546        }
547    }
548
549    #[test]
550    fn hint_names_the_count_and_both_switches() {
551        let h = substring_hint_text(89, "verify_csrf");
552        assert!(h.contains("89 substring match"));
553        assert!(h.contains("contains:true"));
554        assert!(h.contains("--contains"));
555        assert!(h.contains("verify_csrf"));
556    }
557}