reflex-search 2.1.0

A local-first, structure-aware code search engine for AI agents
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
//! Query filter types and stateless filtering helpers

use regex::Regex;

use crate::models::SymbolKind;

/// Query filter options
#[derive(Debug, Clone)]
pub struct QueryFilter {
    /// Language filter (None = all languages)
    pub language: Option<crate::models::Language>,
    /// Symbol kind filter (None = all kinds)
    pub kind: Option<SymbolKind>,
    /// Use AST pattern matching (vs lexical search)
    pub use_ast: bool,
    /// Use regex pattern matching
    pub use_regex: bool,
    /// Maximum number of results
    pub limit: Option<usize>,
    /// Search symbol definitions only (vs full-text)
    pub symbols_mode: bool,
    /// Show full symbol body (from span.start_line to span.end_line)
    pub expand: bool,
    /// File path filter (substring match)
    pub file_pattern: Option<String>,
    /// Exact symbol name match (no substring matching)
    pub exact: bool,
    /// Use substring matching instead of word-boundary matching (opt-in, expansive)
    pub use_contains: bool,
    /// Match letters regardless of case (`rg -i`). Applies to whole-identifier,
    /// substring and regex line searches alike; the engine runs the query as a
    /// `(?i)` regex whose literals are looked up under every case variant.
    pub ignore_case: bool,
    /// Set by the engine when it rewrote a literal pattern into a regex (brackets,
    /// `ignore_case`): the original literal. Drives the broad-query guard (which
    /// must judge the literal's length, not the regex's) and the result `kind`.
    #[doc(hidden)]
    pub rewritten_from: Option<String>,
    /// Drop plain-text-tier results (docs, config, templates) from this query.
    ///
    /// The tier is included by default, because an agent searching for a config key
    /// wants the YAML as well as the struct. It is excluded for questions that are
    /// only meaningful about code — `find_references` in particular, whose reference
    /// search is a plain trigram scan and would otherwise return the name in a
    /// changelog entry as a "call site".
    pub exclude_text: bool,
    /// Search lock files too (`Cargo.lock`, `package-lock.json`, …). They are
    /// indexed but left out of every search by default; `lang: "lock"` selects
    /// them alone.
    pub include_locks: bool,
    /// Search generated files too (`*.pb.go`, `*.min.js`, `*.map`, …). Same
    /// default as lock files; `lang: "generated"` selects them alone.
    pub include_generated: bool,
    /// Count matches without materialising them: no previews, no grouping, no
    /// result rows. `total_count` / `pagination.total` carry the exact line count
    /// and `QueryResponse.file_count` the files with a match. Honoured only by the
    /// full-text line searches (trigram and regex) with no `limit`; symbol and AST
    /// searches ignore it. Set by `--count`, `mode: "count"` and `count_occurrences`.
    pub count_only: bool,
    /// Query timeout in seconds (0 = no timeout)
    pub timeout_secs: u64,
    /// Glob patterns to include (empty = all files)
    pub glob_patterns: Vec<String>,
    /// Glob patterns to exclude (applied after includes)
    pub exclude_patterns: Vec<String>,
    /// Return only unique file paths (deduplicated)
    pub paths_only: bool,
    /// Pagination offset (skip first N results after sorting)
    pub offset: Option<usize>,
    /// Force execution of potentially expensive queries (bypass broad query detection)
    pub force: bool,
    /// Suppress warning/info output (for --json mode to ensure pure JSON output)
    pub suppress_output: bool,
    /// Include dependency information in results
    pub include_dependencies: bool,
    /// Number of context lines to show before and after each match (default: 0 = disabled)
    pub context_lines: usize,
    /// Record per-phase timings into `QueryResponse.timings`.
    pub collect_timings: bool,
    /// Verify every candidate even with a `limit`, so `pagination.total` is exact.
    /// Set by callers whose contract promises an exact total for a page
    /// (`find_references`). Without it, a list-mode search stops once the page is
    /// full and reports `total_is_exact: false`.
    pub require_exact_total: bool,
    /// Test-only: Override large index threshold (None = use default of 20,000)
    #[doc(hidden)]
    pub test_large_index_threshold: Option<usize>,
    /// Test-only: Override short pattern threshold (None = use default of 4)
    #[doc(hidden)]
    pub test_short_pattern_threshold: Option<usize>,
}

impl Default for QueryFilter {
    fn default() -> Self {
        Self {
            language: None,
            kind: None,
            use_ast: false,
            use_regex: false,
            limit: Some(100), // Default: limit to 100 results for token efficiency
            symbols_mode: false,
            expand: false,
            file_pattern: None,
            exact: false,
            use_contains: false, // Default: word-boundary matching
            ignore_case: false,  // Default: case-sensitive
            rewritten_from: None,
            exclude_text: false,      // Default: docs and config are searched too
            include_locks: false,     // Default: lock files stay out
            include_generated: false, // Default: generated files stay out
            count_only: false,        // Default: materialise results
            timeout_secs: 30,         // 30 seconds default timeout
            glob_patterns: Vec::new(),
            exclude_patterns: Vec::new(),
            paths_only: false,
            offset: None,
            force: false,                       // Default: enable broad query detection
            suppress_output: false,             // Default: show warnings/info
            include_dependencies: false,        // Default: don't load dependencies for performance
            context_lines: 0,                   // Default: no context lines shown
            collect_timings: false,             // Default: no per-phase timings
            require_exact_total: false,         // Default: list mode may stop early
            test_large_index_threshold: None,   // Default: use production threshold (20,000)
            test_short_pattern_threshold: None, // Default: use production threshold (4)
        }
    }
}

impl QueryFilter {
    /// Whether this query is a count-only full-text LINE search: the one shape
    /// the verifier can answer with two numbers instead of result rows.
    pub fn count_only_line_search(&self) -> bool {
        self.count_only
            && self.limit.is_none()
            && !self.symbols_mode
            && !self.use_ast
            && self.kind.is_none()
    }
}

/// Whether a file of language `lang` belongs in this query's results.
///
/// An explicit `want` selects exactly that language (so `lang: "lock"` is how a
/// caller asks for lock files alone). Otherwise the text tier is in unless
/// `exclude_text`, and the lock / generated tiers are out unless asked for.
pub fn tier_admits(
    lang: crate::models::Language,
    want: Option<crate::models::Language>,
    exclude_text: bool,
    include_locks: bool,
    include_generated: bool,
) -> bool {
    use crate::models::Language;
    if let Some(want) = want {
        return lang == want;
    }
    match lang {
        Language::Text => !exclude_text,
        Language::Lock => include_locks,
        Language::Generated => include_generated,
        _ => true,
    }
}

/// Whether `lang` was left out only because nothing asked for it: the count of
/// such candidate files explains a zero result.
pub fn excluded_by_default(
    lang: crate::models::Language,
    want: Option<crate::models::Language>,
    include_locks: bool,
    include_generated: bool,
) -> bool {
    use crate::models::Language;
    want.is_none()
        && match lang {
            Language::Lock => !include_locks,
            Language::Generated => !include_generated,
            _ => false,
        }
}

/// Explain a zero result when the only candidate files were excluded by default.
pub fn excluded_by_default_hint_text(files: usize) -> String {
    format!(
        "{} candidate file(s) were lock or generated files, which every search leaves \
         out by default — pass include_locks:true / include_generated:true \
         (--include-locks / --include-generated on the CLI), or lang:\"lock\" / \
         lang:\"generated\", to search them.",
        files
    )
}

/// Map a language keyword to its corresponding SymbolKind.
///
/// When users search for keywords like "class" or "function" with --symbols,
/// automatically infer the kind filter to return only symbols of that type.
pub fn keyword_to_kind(keyword: &str) -> Option<SymbolKind> {
    match keyword {
        "class" => Some(SymbolKind::Class),
        "struct" => Some(SymbolKind::Struct),
        "enum" => Some(SymbolKind::Enum),
        "interface" => Some(SymbolKind::Interface),
        "trait" => Some(SymbolKind::Trait),
        "type" => Some(SymbolKind::Type),
        "record" => Some(SymbolKind::Struct), // C# record types
        "function" | "fn" | "def" | "func" => Some(SymbolKind::Function),
        "const" | "static" => Some(SymbolKind::Constant),
        "var" | "let" => Some(SymbolKind::Variable),
        "mod" | "module" | "namespace" => Some(SymbolKind::Module),
        "impl" | "async" => None,
        _ => None,
    }
}

/// Check if pattern appears at word boundaries in a line.
///
/// Used for default (restrictive) matching to find complete identifiers
/// rather than substrings.
pub fn has_word_boundary_match(line: &str, pattern: &str) -> bool {
    let escaped_pattern = regex::escape(pattern);
    let pattern_with_boundaries = format!(r"\b{}\b", escaped_pattern);

    if let Ok(re) = Regex::new(&pattern_with_boundaries) {
        re.is_match(line)
    } else {
        log::debug!(
            "Word boundary regex failed for pattern '{}', falling back to substring",
            pattern
        );
        line.contains(pattern)
    }
}

/// Bracket characters that make a whole-token literal search structurally unmatchable.
///
/// Whole-token matching wraps the pattern as `\b<pattern>\b`. A pattern ending in `)`
/// or `>` can never satisfy the trailing `\b`, because the next character is almost
/// never a word character. So `unwrap()`, `#[derive(` and `-> Result<` all returned a
/// silent `0` in the 1.7.0 field test, against ripgrep counts of 1221, 1141 and 2139.
/// The 1.7.2 fix lived only in the MCP layer; the CLI and HTTP surfaces kept
/// returning the confident zero until 2.0.0, when the rewrite moved here.
pub const REGEX_ONLY_CHARS: &[char] = &['(', ')', '[', ']', '{', '}', '<', '>'];

/// A literal pattern rewritten so it cannot silently return zero.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LiteralPattern {
    /// What to actually search for (regex-escaped when `use_regex` is set).
    pub effective: String,
    /// Whether the query must run down the regex path.
    pub use_regex: bool,
    /// Explanation for the caller when the pattern was rewritten.
    pub warning: Option<String>,
}

/// Make a literal pattern searchable, rather than letting it return a confident zero.
///
/// A pattern containing brackets cannot match under whole-token rules, so it is
/// escaped and routed to the regex path, which is substring-based. The caller is told
/// in `QueryResponse::warnings` — the rewrite is never silent.
///
/// `ignore_case` is also a rewrite: the query becomes a `(?i)` regex (the caller's
/// own regex verbatim; a substring search escaped; a whole-identifier search
/// escaped and wrapped in `\b…\b`, the same wrap the literal matcher applies).
/// The regex path then looks the literals up under every case variant, so
/// `ignore_case` costs about what the case-sensitive query costs. This rewrite
/// carries no warning. The zero-result substring hint is not produced under
/// `ignore_case`, because the regex path does not count substring-only lines.
///
/// No rewrite happens when the query is not a line search at all: symbol names
/// never contain brackets, and an AST pattern is an S-expression whose parens are
/// the syntax. A regex or substring query is never bracket-rewritten.
pub fn prepare_literal_pattern(pattern: &str, filter: &QueryFilter) -> LiteralPattern {
    let not_a_line_search = filter.use_ast || filter.symbols_mode || filter.kind.is_some();
    let not_a_literal_line_search = filter.use_regex || filter.use_contains || not_a_line_search;

    let mut out = if not_a_literal_line_search || !pattern.contains(REGEX_ONLY_CHARS) {
        LiteralPattern {
            effective: pattern.to_string(),
            use_regex: filter.use_regex,
            warning: None,
        }
    } else {
        LiteralPattern {
            effective: regex::escape(pattern),
            use_regex: true,
            warning: Some(format!(
                "Pattern {:?} contains brackets, which a whole-identifier search can never \
                 match. Searched it as an escaped regex instead (substring semantics). For \
                 explicit control use a regex search (search_regex / --regex) or substring \
                 mode (contains:true / --contains).",
                pattern
            )),
        }
    };

    if filter.ignore_case && !not_a_line_search {
        let body = if filter.use_regex {
            pattern.to_string()
        } else if filter.use_contains || out.use_regex {
            regex::escape(pattern)
        } else {
            format!(r"\b{}\b", regex::escape(pattern))
        };
        out.effective = format!("(?i){}", body);
        out.use_regex = true;
    }

    out
}

/// Explain a zero-result whole-identifier search by naming the substring count.
///
/// This is the single line that would have prevented every wrong conclusion in the
/// 1.7.0 field test: an agent that sees `0` for `verify_csrf` concludes "no callers"
/// and acts on it, when 89 lines contain `verify_csrf_form_field`.
pub fn substring_hint_text(count: usize, pattern: &str) -> String {
    format!(
        "0 whole-identifier matches; {} substring matches — pass contains:true \
         (--contains on the CLI) to see them. Reflex matches whole identifiers by \
         default, so {:?} does not match longer names that merely contain it.",
        count, pattern
    )
}

#[cfg(test)]
mod literal_pattern_tests {
    use super::*;

    fn plain() -> QueryFilter {
        QueryFilter::default()
    }

    #[test]
    fn bracket_patterns_are_escaped_and_routed_to_regex() {
        for p in [
            "unwrap()",
            "#[derive(",
            "-> Result<",
            "RealmId::nil()",
            "vec![]",
        ] {
            let got = prepare_literal_pattern(p, &plain());
            assert!(got.use_regex, "{p} must run as a regex");
            assert_eq!(got.effective, regex::escape(p));
            let w = got.warning.expect("rewrite must be reported");
            assert!(w.contains("bracket"), "{w}");
            assert!(w.contains(p), "warning names the original pattern: {w}");
        }
    }

    #[test]
    fn plain_identifiers_are_untouched() {
        let got = prepare_literal_pattern("verify_csrf", &plain());
        assert_eq!(
            got,
            LiteralPattern {
                effective: "verify_csrf".into(),
                use_regex: false,
                warning: None
            }
        );
    }

    #[test]
    fn ignore_case_becomes_a_case_insensitive_regex() {
        let ic = QueryFilter {
            ignore_case: true,
            ..plain()
        };
        // Whole identifier: escaped and word-bounded, no warning.
        let got = prepare_literal_pattern("realm.id", &ic);
        assert_eq!(got.effective, r"(?i)\brealm\.id\b");
        assert!(got.use_regex);
        assert!(got.warning.is_none());

        // Substring: escaped only.
        let got = prepare_literal_pattern(
            "realm.id",
            &QueryFilter {
                use_contains: true,
                ..ic.clone()
            },
        );
        assert_eq!(got.effective, r"(?i)realm\.id");
        assert!(got.warning.is_none());

        // The caller's own regex is kept verbatim.
        let got = prepare_literal_pattern(
            r"realm_?id\b",
            &QueryFilter {
                use_regex: true,
                ..ic.clone()
            },
        );
        assert_eq!(got.effective, r"(?i)realm_?id\b");

        // Brackets: the bracket rewrite (substring + warning) happens first.
        let got = prepare_literal_pattern("unwrap()", &ic);
        assert_eq!(got.effective, r"(?i)unwrap\(\)");
        assert!(got.warning.is_some());

        // Not a line search: untouched.
        for f in [
            QueryFilter {
                symbols_mode: true,
                ..ic.clone()
            },
            QueryFilter {
                kind: Some(SymbolKind::Function),
                ..ic.clone()
            },
            QueryFilter {
                use_ast: true,
                ..ic.clone()
            },
        ] {
            let got = prepare_literal_pattern("RealmId", &f);
            assert_eq!(got.effective, "RealmId");
            assert!(!got.use_regex);
        }
    }

    #[test]
    fn non_literal_modes_are_never_rewritten() {
        let cases: Vec<(&str, QueryFilter)> = vec![
            (
                "contains",
                QueryFilter {
                    use_contains: true,
                    ..plain()
                },
            ),
            (
                "regex",
                QueryFilter {
                    use_regex: true,
                    ..plain()
                },
            ),
            (
                "symbols",
                QueryFilter {
                    symbols_mode: true,
                    ..plain()
                },
            ),
            (
                "kind",
                QueryFilter {
                    kind: Some(SymbolKind::Function),
                    ..plain()
                },
            ),
            (
                "ast",
                QueryFilter {
                    use_ast: true,
                    ..plain()
                },
            ),
        ];
        for (name, f) in cases {
            let got = prepare_literal_pattern("unwrap()", &f);
            assert_eq!(
                got.effective, "unwrap()",
                "{name}: pattern must be verbatim"
            );
            assert_eq!(
                got.use_regex, f.use_regex,
                "{name}: regex flag passes through"
            );
            assert!(got.warning.is_none(), "{name}: no warning");
        }
    }

    #[test]
    fn hint_names_the_count_and_both_switches() {
        let h = substring_hint_text(89, "verify_csrf");
        assert!(h.contains("89 substring match"));
        assert!(h.contains("contains:true"));
        assert!(h.contains("--contains"));
        assert!(h.contains("verify_csrf"));
    }
}