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+", ®ex).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}