reflex/models.rs
1//! Core data models for Reflex
2//!
3//! These structures represent the normalized, deterministic output format
4//! that Reflex provides to AI agents and other programmatic consumers.
5
6use serde::{Deserialize, Serialize};
7use strum::{Display, EnumString};
8
9/// Represents a source code location span (line range only)
10#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
11pub struct Span {
12 /// Starting line number (1-indexed)
13 pub start_line: usize,
14 /// Ending line number (1-indexed)
15 pub end_line: usize,
16}
17
18impl Span {
19 pub fn new(start_line: usize, start_col: usize, end_line: usize, end_col: usize) -> Self {
20 // Ignore col parameters for backwards compatibility
21 let _ = (start_col, end_col);
22 Self {
23 start_line,
24 end_line,
25 }
26 }
27}
28
29/// Type of symbol found in code
30#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, EnumString, Display)]
31#[strum(serialize_all = "PascalCase")]
32pub enum SymbolKind {
33 Function,
34 Class,
35 Struct,
36 Enum,
37 Interface,
38 Trait,
39 Constant,
40 Variable,
41 Method,
42 Module,
43 Namespace,
44 Type,
45 Macro,
46 Property,
47 Event,
48 Import,
49 Export,
50 Attribute,
51 /// Catch-all for symbol kinds not yet explicitly supported.
52 /// This ensures no data loss when encountering new tree-sitter node types.
53 /// The string contains the original kind name from the parser.
54 #[strum(default)]
55 Unknown(String),
56}
57
58/// Programming language identifier
59#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
60#[serde(rename_all = "lowercase")]
61pub enum Language {
62 #[default]
63 Rust,
64 Python,
65 JavaScript,
66 TypeScript,
67 Vue,
68 Svelte,
69 Go,
70 Java,
71 PHP,
72 C,
73 Cpp,
74 CSharp,
75 Ruby,
76 Kotlin,
77 Swift,
78 Zig,
79 /// Plain-text tier: documentation, config and templates.
80 ///
81 /// Trigram-indexed only — no tree-sitter grammar, no symbol extraction, no
82 /// import extraction. Added because agents do not partition searches by file
83 /// type: a config key lives in the YAML, the Rust struct AND the spec paragraph,
84 /// and Reflex used to return the struct and a confident 0 for the rest.
85 ///
86 /// Serialises as `"text"` (the enum is `rename_all = "lowercase"`).
87 Text,
88 /// Lock files (`Cargo.lock`, `package-lock.json`, `*.lock`, …).
89 ///
90 /// Indexed since 2.0.0 in `[index] mode = "tracked"`, but excluded from every
91 /// search by default: 100k lines of pinned versions are noise for almost every
92 /// query and the one real question ("which lockfile pins serde 1.0.190?") is
93 /// asked with `include_locks: true` or `lang: "lock"`.
94 Lock,
95 /// Generated files judged by name: `*.pb.go`, `*_generated.*`, `*.generated.*`,
96 /// `*.min.js`, `*.min.css`, `*.map`. Indexed, excluded by default,
97 /// `include_generated: true` or `lang: "generated"` to widen.
98 Generated,
99 /// Never produced by [`Language::from_path`] since 2.0.0 (every path classifies
100 /// as code, `Text`, `Lock` or `Generated`); kept as the miss value of
101 /// [`Language::from_extension`] and as the forward-compatible sentinel for
102 /// readers of the `language` field.
103 Unknown,
104}
105
106/// Whether `file_name` is a dependency lock file.
107///
108/// Judged by full name: `package-lock.json` matches a text extension, and the
109/// name is the only thing that tells it apart from `settings.json`.
110pub fn is_lock_file(file_name: &str) -> bool {
111 if TEXT_FILENAME_EXCLUSIONS
112 .iter()
113 .any(|n| n.eq_ignore_ascii_case(file_name))
114 {
115 return true;
116 }
117 // `*-lock.json` and friends, beyond the names listed above.
118 file_name.ends_with("-lock.json") || file_name.ends_with(".lock")
119}
120
121/// Whether `file_name` looks like a generated file, judged by name only.
122///
123/// Content markers (`@generated` in the file head) are not read: the query engine
124/// derives a file's language from its path, so a content-based verdict at index
125/// time could not be honoured at query time.
126pub fn is_generated_name(file_name: &str) -> bool {
127 let lower = file_name.to_ascii_lowercase();
128 lower.ends_with(".pb.go")
129 || lower.ends_with(".min.js")
130 || lower.ends_with(".min.css")
131 || lower.ends_with(".map")
132 || lower.contains("_generated.")
133 || lower.contains(".generated.")
134}
135
136/// Extensions in the plain-text tier.
137///
138/// A fixed allowlist, not "everything unrecognised": an index that swallowed every
139/// binary blob and generated artefact in a repo would be slower and less useful.
140const TEXT_EXTENSIONS: &[&str] = &[
141 "md", "mdx", "txt", "yaml", "yml", "toml", "json", "proto", "html", "htm", "sh", "bash", "ini",
142 "cfg", "sql", "graphql", "bru",
143];
144
145/// Extensionless files in the plain-text tier, matched by exact name.
146///
147/// Agents grep these as readily as any `.md`; a `Makefile` target or a `Dockerfile`
148/// `COPY` line is a legitimate search hit. `Dockerfile.<variant>` is handled as a
149/// prefix in [`is_text_tier_file`].
150const TEXT_FILENAMES: &[&str] = &["Makefile", "makefile", "Dockerfile", "Justfile", "justfile"];
151
152/// Lock files, by exact name. See [`is_lock_file`] for the suffix rules.
153const TEXT_FILENAME_EXCLUSIONS: &[&str] = &[
154 "package-lock.json",
155 "npm-shrinkwrap.json",
156 "composer.lock",
157 "yarn.lock",
158 "pnpm-lock.yaml",
159 "Cargo.lock",
160 "poetry.lock",
161 "Gemfile.lock",
162 "go.sum",
163 "flake.lock",
164 "uv.lock",
165 "deno.lock",
166 "bun.lock",
167];
168
169/// Whether a file belongs in the ALLOWLIST text tier, judged by its full name.
170///
171/// This is the pre-2.0.0 rule, kept for `[index] mode = "allowlist"`. In the
172/// default `tracked` mode every non-binary, non-ignored file is text unless it is
173/// code, a lock file or a generated file.
174pub fn is_text_tier_file(file_name: &str) -> bool {
175 if is_lock_file(file_name) {
176 return false;
177 }
178 if TEXT_FILENAMES.contains(&file_name) || file_name.starts_with("Dockerfile.") {
179 return true;
180 }
181 match file_name.rsplit_once('.') {
182 Some((_, ext)) => TEXT_EXTENSIONS.contains(&ext.to_ascii_lowercase().as_str()),
183 None => false,
184 }
185}
186
187impl Language {
188 /// Classify a file by its path.
189 ///
190 /// This is the one classifier the indexer, watcher and query engine share, so a
191 /// file is either indexed, watched and searchable, or none of the three. Path
192 /// only: whether the file is binary is decided from its bytes by the indexer,
193 /// and a binary file is simply never in the index.
194 ///
195 /// * A lock file name wins (`Cargo.lock`, `package-lock.json`) → `Lock`.
196 /// * A generated name wins next (`x.pb.go`, `app.min.js`) → `Generated`.
197 /// * A recognised code extension → that language (`main.rs`, `app.mjs`).
198 /// * Everything else → `Text`: `README`, `OWNERS`, `foo.po`, `a.css`,
199 /// `Makefile`, `.githooks/pre-commit`. Whether such a file is INDEXED is the
200 /// `[index] mode` policy's decision (`PathPolicy::classify`).
201 pub fn from_path(path: &std::path::Path) -> Self {
202 let name = path.file_name().and_then(|n| n.to_str()).unwrap_or("");
203 if is_lock_file(name) {
204 return Language::Lock;
205 }
206 if is_generated_name(name) {
207 return Language::Generated;
208 }
209 let by_ext = path
210 .extension()
211 .and_then(|e| e.to_str())
212 .map(Self::from_extension)
213 .unwrap_or(Language::Unknown);
214 match by_ext {
215 Language::Text | Language::Unknown => Language::Text,
216 code => code,
217 }
218 }
219
220 pub fn from_extension(ext: &str) -> Self {
221 match ext {
222 "rs" => Language::Rust,
223 "py" => Language::Python,
224 "js" | "mjs" | "cjs" | "jsx" => Language::JavaScript,
225 "ts" | "mts" | "cts" | "tsx" => Language::TypeScript,
226 "vue" => Language::Vue,
227 "svelte" => Language::Svelte,
228 "go" => Language::Go,
229 "java" => Language::Java,
230 "php" => Language::PHP,
231 "c" | "h" => Language::C,
232 "cpp" | "cc" | "cxx" | "hpp" | "hxx" | "C" | "H" => Language::Cpp,
233 "cs" => Language::CSharp,
234 "rb" | "rake" | "gemspec" => Language::Ruby,
235 "kt" | "kts" => Language::Kotlin,
236 "swift" => Language::Swift,
237 "zig" => Language::Zig,
238 // The text tier. Note this maps by EXTENSION only; `is_text_tier_file`
239 // additionally excludes lock files by name, and the indexer uses that.
240 ext if TEXT_EXTENSIONS.contains(&ext.to_ascii_lowercase().as_str()) => Language::Text,
241 _ => Language::Unknown,
242 }
243 }
244
245 /// Parse a language from a human-friendly name (CLI/API input)
246 ///
247 /// Accepts lowercase names and common aliases.
248 /// Returns None for unrecognized names.
249 pub fn from_name(name: &str) -> Option<Self> {
250 match name.to_lowercase().as_str() {
251 "rust" | "rs" => Some(Language::Rust),
252 "python" | "py" => Some(Language::Python),
253 "javascript" | "js" => Some(Language::JavaScript),
254 "typescript" | "ts" => Some(Language::TypeScript),
255 "vue" => Some(Language::Vue),
256 "svelte" => Some(Language::Svelte),
257 "go" => Some(Language::Go),
258 "java" => Some(Language::Java),
259 "php" => Some(Language::PHP),
260 "c" => Some(Language::C),
261 "cpp" | "c++" => Some(Language::Cpp),
262 "csharp" | "cs" | "c#" => Some(Language::CSharp),
263 "ruby" | "rb" => Some(Language::Ruby),
264 "kotlin" | "kt" => Some(Language::Kotlin),
265 "swift" => Some(Language::Swift),
266 "zig" => Some(Language::Zig),
267 "text" | "txt" | "plaintext" | "plain" => Some(Language::Text),
268 "lock" | "lockfile" | "lockfiles" => Some(Language::Lock),
269 "generated" | "gen" => Some(Language::Generated),
270 _ => None,
271 }
272 }
273
274 /// Human-readable list of all supported language names (for error messages)
275 pub fn supported_names_help() -> &'static str {
276 "rust (rs), python (py), javascript (js), typescript (ts), vue, svelte, \
277 go, java, php, c, cpp (c++), csharp (cs, c#), ruby (rb), kotlin (kt), \
278 swift (full-text search only: no symbols), zig, \
279 text (every other non-binary file: docs, config, templates, extensionless), \
280 lock (lock files, excluded by default), generated (*.pb.go, *.min.js, *.map, \
281 *_generated.*, excluded by default)"
282 }
283
284 /// Check if this language has a parser implementation
285 ///
286 /// Returns true only for languages with working Tree-sitter parsers.
287 /// This determines which files will be indexed by Reflex.
288 pub fn is_supported(&self) -> bool {
289 match self {
290 Language::Rust => true,
291 Language::TypeScript => true,
292 Language::JavaScript => true,
293 Language::Vue => true,
294 Language::Svelte => true,
295 Language::Python => true,
296 Language::Go => true,
297 Language::Java => true,
298 Language::PHP => true,
299 Language::C => true,
300 Language::Cpp => true,
301 Language::CSharp => true,
302 Language::Ruby => true,
303 Language::Kotlin => true,
304 Language::Swift => false, // Temporarily disabled - parser queries out of date with tree-sitter-swift 0.7.x grammar
305 Language::Zig => true,
306 // No tree-sitter grammar, by design.
307 Language::Text => false,
308 Language::Lock => false,
309 Language::Generated => false,
310 Language::Unknown => false,
311 }
312 }
313
314 /// Whether this is the plain-text tier.
315 pub fn is_text(&self) -> bool {
316 matches!(self, Language::Text)
317 }
318
319 /// Whether files of this language are indexed but left out of every search
320 /// unless asked for (`include_locks` / `include_generated`, or `lang`).
321 pub fn is_excluded_by_default(&self) -> bool {
322 matches!(self, Language::Lock | Language::Generated)
323 }
324
325 /// Whether this is a code language, supported or not (Swift is code without a
326 /// working grammar). Code files are assumed to be text; every other file is
327 /// sniffed for a NUL byte before it is indexed.
328 pub fn is_code(&self) -> bool {
329 !matches!(
330 self,
331 Language::Text | Language::Lock | Language::Generated | Language::Unknown
332 )
333 }
334
335 /// Whether files of this language can be in the index at all.
336 ///
337 /// Distinct from [`Self::is_supported`], which means "has a tree-sitter parser".
338 /// The text tier is indexed but never parsed, so symbol search, AST queries and
339 /// dependency analysis skip it while full-text search covers it. Whether a given
340 /// path IS indexed also depends on `[index] mode` (`PathPolicy::classify`).
341 pub fn is_indexable(&self) -> bool {
342 !matches!(self, Language::Unknown)
343 }
344}
345
346/// Which files the indexer takes, beyond the code languages.
347#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
348#[serde(rename_all = "lowercase")]
349pub enum IndexMode {
350 /// Every file not ignored by `.gitignore` / `.ignore` / `[index] exclude`,
351 /// unless a NUL byte anywhere in it says it is binary. Lock and generated
352 /// files are indexed and excluded from searches by default. This is ripgrep's
353 /// rule, and what an agent that greps expects.
354 #[default]
355 Tracked,
356 /// The pre-2.0.0 rule: code by extension plus the fixed docs/config extension
357 /// list (`is_text_tier_file`). Lock and generated files are not indexed. For
358 /// trees where the long tail of data files is not worth the index size.
359 Allowlist,
360}
361
362impl IndexMode {
363 pub fn from_name(name: &str) -> Option<Self> {
364 match name.trim().to_ascii_lowercase().as_str() {
365 "tracked" => Some(Self::Tracked),
366 "allowlist" => Some(Self::Allowlist),
367 _ => None,
368 }
369 }
370}
371
372/// Type of import/dependency
373#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
374#[serde(rename_all = "lowercase")]
375pub enum ImportType {
376 /// Internal project file
377 Internal,
378 /// External library/package
379 External,
380 /// Standard library
381 Stdlib,
382 /// Rust `mod foo;` declaration (parent→child ownership, not a usage edge)
383 #[serde(rename = "mod_decl")]
384 ModDecl,
385}
386
387/// Dependency information for API output (simplified, path-based)
388#[derive(Debug, Clone, Serialize, Deserialize)]
389pub struct DependencyInfo {
390 /// Import path as written in source (or resolved path for internal deps)
391 pub path: String,
392 /// Line number where import appears (optional)
393 #[serde(skip_serializing_if = "Option::is_none")]
394 pub line: Option<usize>,
395 /// Imported symbols (for selective imports like `from x import a, b`)
396 #[serde(skip_serializing_if = "Option::is_none")]
397 pub symbols: Option<Vec<String>>,
398 /// Every file a package import resolved to (a Go package, a C# namespace, a
399 /// JVM wildcard), in walk order; `path` is then the import as written.
400 #[serde(skip_serializing_if = "Option::is_none")]
401 pub resolved_paths: Option<Vec<String>>,
402}
403
404/// Full dependency record (internal representation with file IDs)
405#[derive(Debug, Clone)]
406pub struct Dependency {
407 /// Source file ID
408 pub file_id: i64,
409 /// Import path as written in source code
410 pub imported_path: String,
411 /// Resolved file ID (None if external or stdlib)
412 pub resolved_file_id: Option<i64>,
413 /// Package key the import resolved to (`go:<dir>`, `jvm:<package>`,
414 /// `cs:<namespace>`), when it names a package rather than one file. The graph
415 /// expands it to the files that declare membership (`package_members`).
416 pub resolved_package: Option<String>,
417 /// The member of `resolved_package` the import names (a JVM class); `None`
418 /// means the whole package.
419 pub resolved_member: Option<String>,
420 /// Import type classification
421 pub import_type: ImportType,
422 /// Line number where import appears
423 pub line_number: usize,
424 /// Imported symbols (for selective imports)
425 pub imported_symbols: Option<Vec<String>>,
426}
427
428/// A lightweight, stable reference to a code symbol for API responses
429///
430/// Prefer this over `(String, SymbolKind, Span)` tuples — tuples serialize as
431/// positional JSON arrays, making any field addition a breaking change.
432/// Named fields here are additive-safe: new optional fields can be added without
433/// shifting positions or bumping the version.
434#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
435pub struct SymbolRef {
436 /// Symbol name (e.g., function name, class name)
437 pub name: String,
438 /// Symbol kind (function, class, struct, etc.)
439 pub kind: SymbolKind,
440 /// Location span in source file
441 pub span: Span,
442}
443
444/// Helper function to skip serializing "Unknown" symbol kinds
445fn is_unknown_kind(kind: &SymbolKind) -> bool {
446 matches!(kind, SymbolKind::Unknown(_))
447}
448
449/// A search result representing a symbol or code location
450#[derive(Debug, Clone, Serialize, Deserialize)]
451pub struct SearchResult {
452 /// Absolute or relative path to the file
453 pub path: String,
454 /// Detected programming language (internal use only, not serialized to save tokens)
455 #[serde(skip)]
456 pub lang: Language,
457 /// Type of symbol found (only included for symbol searches, not text matches)
458 #[serde(skip_serializing_if = "is_unknown_kind")]
459 pub kind: SymbolKind,
460 /// Symbol name (e.g., function name, class name)
461 /// None for text/regex matches where symbol name cannot be accurately determined
462 #[serde(skip_serializing_if = "Option::is_none")]
463 pub symbol: Option<String>,
464 /// Location span in the source file
465 pub span: Span,
466 /// Code preview (few lines around the match)
467 pub preview: String,
468 /// File dependencies (only populated when --dependencies flag is used)
469 /// DEPRECATED: Use FileGroupedResult.dependencies instead for file-level grouping
470 #[serde(skip_serializing_if = "Option::is_none")]
471 pub dependencies: Option<Vec<DependencyInfo>>,
472}
473
474/// An individual match within a file (no path or dependencies)
475#[derive(Debug, Clone, Serialize, Deserialize)]
476pub struct MatchResult {
477 /// Type of symbol found (only included for symbol searches, not text matches)
478 #[serde(skip_serializing_if = "is_unknown_kind")]
479 pub kind: SymbolKind,
480 /// Symbol name (e.g., function name, class name)
481 #[serde(skip_serializing_if = "Option::is_none")]
482 pub symbol: Option<String>,
483 /// Location span in the source file
484 pub span: Span,
485 /// Code preview (few lines around the match)
486 pub preview: String,
487 /// Lines of code before the match (for context)
488 #[serde(skip_serializing_if = "Vec::is_empty")]
489 pub context_before: Vec<String>,
490 /// Lines of code after the match (for context)
491 #[serde(skip_serializing_if = "Vec::is_empty")]
492 pub context_after: Vec<String>,
493}
494
495/// File-level grouped results with dependencies at file level
496#[derive(Debug, Clone, Serialize, Deserialize)]
497pub struct FileGroupedResult {
498 /// Absolute or relative path to the file
499 pub path: String,
500 /// Detected programming language of this file (e.g. "rust", "python", "unknown")
501 pub language: Language,
502 /// File dependencies (only populated when --dependencies flag is used)
503 #[serde(skip_serializing_if = "Option::is_none")]
504 pub dependencies: Option<Vec<DependencyInfo>>,
505 /// Individual matches within this file
506 pub matches: Vec<MatchResult>,
507}
508
509impl SearchResult {
510 pub fn new(
511 path: String,
512 lang: Language,
513 kind: SymbolKind,
514 symbol: Option<String>,
515 span: Span,
516 scope: Option<String>,
517 preview: String,
518 ) -> Self {
519 // Ignore scope parameter for backwards compatibility
520 let _ = scope;
521 Self {
522 path,
523 lang,
524 kind,
525 symbol,
526 span,
527 preview,
528 dependencies: None,
529 }
530 }
531}
532
533/// Configuration for indexing behavior
534/// [`IndexConfig::lock_wait_secs`]: wait for `index.lock` until it is free. The
535/// lock is advisory and released when its holder exits, so a crash cannot leave
536/// a waiter blocked.
537pub const LOCK_WAIT_FOREVER: u64 = u64::MAX;
538
539#[derive(Debug, Clone, Serialize, Deserialize)]
540pub struct IndexConfig {
541 /// Languages to include (empty = all supported)
542 pub languages: Vec<Language>,
543 /// Glob patterns to include
544 pub include_patterns: Vec<String>,
545 /// Glob patterns to exclude
546 pub exclude_patterns: Vec<String>,
547 /// Follow symbolic links
548 pub follow_symlinks: bool,
549 /// Maximum file size to index (bytes)
550 pub max_file_size: usize,
551 /// Number of threads for parallel indexing (0 = auto, 80% of available cores)
552 pub parallel_threads: usize,
553 /// Threads for the background symbol pass (`rfx index-symbols-internal`).
554 /// `0` = auto: half the cores, at most 32. See [`resolve_symbol_thread_count`].
555 #[serde(default)]
556 pub symbol_threads: usize,
557 /// Query timeout in seconds (0 = no timeout)
558 pub query_timeout_secs: u64,
559 /// Maximum entries per trigram posting list (0 = unlimited).
560 /// High-frequency trigrams are truncated at this threshold to bound query latency.
561 pub max_posting_list_entries: usize,
562 /// How long `Indexer::index` waits for `.reflex/index.lock` when another
563 /// indexer holds it (seconds). 0 = fail immediately with `IndexLocked`;
564 /// [`LOCK_WAIT_FOREVER`] = wait until it is free. The `rfx index` CLI waits
565 /// 30 s; automatic updates wait forever (a query never answers from a stale
566 /// index because another run was busy).
567 #[serde(default, skip_serializing_if = "is_zero_u64")]
568 pub lock_wait_secs: u64,
569 /// Index documentation, config and template files alongside code.
570 ///
571 /// On by default. Covers md, mdx, txt, yaml, yml, toml, json, proto, html, htm,
572 /// sh, bash, ini, cfg, sql and graphql, trigram-indexed only — no symbols, no
573 /// AST, no dependency analysis. Lock files are always excluded.
574 ///
575 /// Set `[index] text_tier = false` for a repo with large generated JSON or
576 /// vendored documentation where the index growth is not worth it.
577 ///
578 /// `#[serde(default = ...)]` so a config file written before 1.7.2 still parses
579 /// and gets the new default.
580 #[serde(default = "default_true")]
581 pub text_tier: bool,
582 /// Which non-code files the text tier takes: every non-binary, non-hidden, non-ignored file
583 /// (`tracked`, the default since 2.0.0) or the fixed extension list
584 /// (`allowlist`, the pre-2.0.0 rule).
585 #[serde(default)]
586 pub mode: IndexMode,
587 /// Walk dot-directories and dotfiles too (`.githooks/pre-commit`, `.env.example`).
588 /// Off by default, like ripgrep without `--hidden`. `.git/` and `.reflex/` are
589 /// never walked.
590 #[serde(default)]
591 pub hidden: bool,
592 /// `[index.vendored] patterns`: gitignore rules that mark directories vendored
593 /// (`!pattern` marks one project code), checked before the built-in rules.
594 /// Vendored files are searchable but not in the import graph (`crate::vendor`).
595 #[serde(default)]
596 pub vendored_patterns: Vec<String>,
597}
598
599/// Serde default for boolean options that are on unless explicitly disabled.
600fn default_true() -> bool {
601 true
602}
603
604impl Default for IndexConfig {
605 fn default() -> Self {
606 Self {
607 languages: vec![],
608 include_patterns: vec![],
609 exclude_patterns: vec![],
610 follow_symlinks: false,
611 max_file_size: 10 * 1024 * 1024, // 10 MB
612 parallel_threads: 0, // 0 = auto (80% of available cores)
613 symbol_threads: 0, // 0 = auto (50% of available cores)
614 query_timeout_secs: 30, // 30 seconds default timeout
615 max_posting_list_entries: 500_000, // cap at 500k to bound query latency
616 text_tier: true, // docs and config are searchable by default
617 mode: IndexMode::Tracked, // ripgrep defaults: not ignored, not hidden, not binary
618 hidden: false, // dot-directories skipped, like ripgrep
619 lock_wait_secs: 0, // fail fast when another indexer runs
620 vendored_patterns: vec![],
621 }
622 }
623}
624
625fn is_zero(v: &usize) -> bool {
626 *v == 0
627}
628fn is_zero_u64(v: &u64) -> bool {
629 *v == 0
630}
631
632/// A `HashMap` serialized with its keys in order, so the same index prints the same JSON.
633fn serialize_sorted<S: serde::Serializer>(
634 map: &std::collections::HashMap<String, usize>,
635 serializer: S,
636) -> Result<S::Ok, S::Error> {
637 map.iter()
638 .collect::<std::collections::BTreeMap<_, _>>()
639 .serialize(serializer)
640}
641
642/// Resolve `[performance] symbol_threads` (the background symbol pass) to a
643/// concrete thread count.
644///
645/// `REFLEX_SYMBOL_THREADS` overrides for benchmarking, then `configured` if
646/// non-zero, else half the cores (1..=32). The pass is detached from `rfx index`
647/// and runs while the user may be querying, so it takes half the machine rather
648/// than the indexer's 80%; before 2.0.0 it took 27.5%.
649pub fn resolve_symbol_thread_count(configured: usize) -> usize {
650 if let Some(n) = std::env::var("REFLEX_SYMBOL_THREADS")
651 .ok()
652 .and_then(|v| v.parse::<usize>().ok())
653 .filter(|&n| n > 0)
654 {
655 return n;
656 }
657 if configured != 0 {
658 return configured.max(1);
659 }
660 let available = std::thread::available_parallelism()
661 .map(|n| n.get())
662 .unwrap_or(4);
663 ((available as f64 * 0.5).ceil() as usize).clamp(1, 32)
664}
665
666/// Resolve `[performance] parallel_threads` to a concrete thread count.
667///
668/// `0` means automatic: 80% of the available cores, at least 1, at most
669/// `auto_cap`. A non-zero value is used as given. The indexer passes a cap of 8
670/// (write-side cache contention); query-time verification passes a higher cap.
671pub fn resolve_thread_count(configured: usize, auto_cap: usize) -> usize {
672 if configured != 0 {
673 return configured.max(1);
674 }
675 let available = std::thread::available_parallelism()
676 .map(|n| n.get())
677 .unwrap_or(4);
678 ((available as f64 * 0.8).ceil() as usize).clamp(1, auto_cap.max(1))
679}
680
681/// How a query found its candidate lines.
682///
683/// `trigram` is the normal case: the pattern's literals were looked up in the
684/// inverted index and only the lines they name were verified. `scan` means every
685/// line of every file was verified, which happens for a pattern shorter than
686/// 3 chars, a regex with no literal of 3+ chars (`\w+_id`), a non-ASCII literal
687/// under `(?i)`, or a keyword symbol query. Before 2.0.0 every `(?i)` regex
688/// scanned; since 2.0.0 its literals are looked up under all case variants.
689#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
690#[serde(rename_all = "lowercase")]
691pub enum IndexPath {
692 /// Candidates came from the trigram index.
693 #[default]
694 Trigram,
695 /// Every line was verified.
696 Scan,
697}
698
699/// Per-phase wall-clock timings for one query, in microseconds.
700///
701/// Present in a [`QueryResponse`] only when the caller asked for it
702/// (`rfx query --timing`, or `REFLEX_MCP_TIMING=1` for the MCP server).
703#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
704pub struct QueryTimings {
705 /// Whether the trigram index or a full scan produced the candidates.
706 #[serde(default)]
707 pub index_path: IndexPath,
708 /// Opening (or reusing) the index handle.
709 pub open_us: u64,
710 /// Trigram lookup and posting-list intersection.
711 pub candidates_us: u64,
712 /// Verifying candidate lines against the pattern (and any enrichment).
713 pub verify_us: u64,
714 /// Time the query waited for the freshness check after the search finished.
715 /// The check runs on its own thread alongside the search, so this is usually
716 /// near zero; `status_compute_us` is what the check itself cost.
717 pub status_us: u64,
718 /// The freshness check's own duration (git spawns, or a tree walk outside git).
719 #[serde(default)]
720 pub status_compute_us: u64,
721 /// Grouping by file, context lines, dependencies.
722 pub group_us: u64,
723 /// Whole query as seen by the engine.
724 pub total_us: u64,
725 /// Automatic updates of a stale index before the answer (0: none ran).
726 /// `total_us` includes them.
727 #[serde(default, skip_serializing_if = "is_zero_u64")]
728 pub update_us: u64,
729}
730
731/// Statistics about the index
732#[derive(Debug, Clone, Serialize, Deserialize, Default)]
733pub struct IndexStats {
734 /// Total files indexed
735 pub total_files: usize,
736 /// Index size on disk (bytes)
737 pub index_size_bytes: u64,
738 /// Last update timestamp
739 pub last_updated: String,
740 /// File count breakdown by language
741 #[serde(serialize_with = "serialize_sorted")]
742 pub files_by_language: std::collections::HashMap<String, usize>,
743 /// Line count breakdown by language
744 #[serde(serialize_with = "serialize_sorted")]
745 pub lines_by_language: std::collections::HashMap<String, usize>,
746 /// New files added since last index run (0 if not an incremental run)
747 #[serde(default, skip_serializing_if = "is_zero")]
748 pub new_files: usize,
749 /// Modified files re-indexed since last run (0 if not an incremental run)
750 #[serde(default, skip_serializing_if = "is_zero")]
751 pub modified_files: usize,
752 /// Unchanged files (same hash as last run, still re-indexed due to other changes)
753 #[serde(default, skip_serializing_if = "is_zero")]
754 pub unchanged_files: usize,
755 /// Files dropped from the index because they no longer exist on disk
756 #[serde(default, skip_serializing_if = "is_zero")]
757 pub deleted_files: usize,
758 /// Files skipped because they exceeded max_file_size
759 #[serde(default, skip_serializing_if = "is_zero")]
760 pub skipped_too_large: usize,
761 /// Total bytes of files skipped due to max_file_size
762 #[serde(default, skip_serializing_if = "is_zero_u64")]
763 pub skipped_bytes_too_large: u64,
764 /// Files skipped because a NUL byte says they are binary (ripgrep's rule)
765 #[serde(default, skip_serializing_if = "is_zero")]
766 pub skipped_binary: usize,
767 /// Raw bytes of indexed source held in content.bin (0 if unknown)
768 #[serde(default, skip_serializing_if = "is_zero_u64")]
769 pub corpus_bytes: u64,
770 /// Size of trigrams.bin on disk (0 if absent)
771 #[serde(default, skip_serializing_if = "is_zero_u64")]
772 pub trigram_index_bytes: u64,
773}
774
775/// Information about an indexed file
776#[derive(Debug, Clone, Serialize, Deserialize)]
777pub struct IndexedFile {
778 /// File path
779 pub path: String,
780 /// Detected language
781 pub language: String,
782 /// Last indexed timestamp
783 pub last_indexed: String,
784}
785
786/// Index status for query responses
787#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
788#[serde(rename_all = "snake_case")]
789pub enum IndexStatus {
790 /// Index is fresh and up-to-date
791 Fresh,
792 /// Index is stale (any issue: branch not indexed, commit changed, files modified)
793 Stale,
794}
795
796/// Warning details when index is stale
797#[derive(Debug, Clone, Serialize, Deserialize)]
798pub struct IndexWarning {
799 /// Human-readable reason why index is stale
800 pub reason: String,
801 /// Command to run to fix the issue
802 pub action_required: String,
803 /// Tracked files edited since the index was built.
804 ///
805 /// BREAKING in 1.7.2: this was a `u32` count. It is now the paths themselves,
806 /// because a count told an agent something was wrong without telling it what, so
807 /// the only safe reaction was to distrust the whole result. The list is capped;
808 /// `truncated` says when.
809 #[serde(skip_serializing_if = "Option::is_none")]
810 pub files_modified: Option<Vec<String>>,
811 /// Files present on disk but absent from the index (new or untracked).
812 #[serde(skip_serializing_if = "Option::is_none")]
813 pub files_added: Option<Vec<String>>,
814 /// Files in the index but no longer on disk. These produce ghost hits.
815 #[serde(skip_serializing_if = "Option::is_none")]
816 pub files_deleted: Option<Vec<String>>,
817 /// Total changed paths, which may exceed the lengths of the lists above.
818 #[serde(skip_serializing_if = "Option::is_none")]
819 pub changed_count: Option<usize>,
820 /// Whether the lists were cut short. Set on a fresh checkout or a huge rebase.
821 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
822 pub truncated: bool,
823 /// Additional context (git branch info, etc.)
824 #[serde(skip_serializing_if = "Option::is_none")]
825 pub details: Option<IndexWarningDetails>,
826}
827
828impl IndexWarning {
829 /// A warning with only a reason and an action, no file lists.
830 pub fn new(reason: impl Into<String>, action_required: impl Into<String>) -> Self {
831 Self {
832 reason: reason.into(),
833 action_required: action_required.into(),
834 files_modified: None,
835 files_added: None,
836 files_deleted: None,
837 changed_count: None,
838 truncated: false,
839 details: None,
840 }
841 }
842
843 /// Attach git branch/commit context.
844 pub fn with_details(mut self, details: IndexWarningDetails) -> Self {
845 self.details = Some(details);
846 self
847 }
848}
849
850/// Detailed information about index staleness
851#[derive(Debug, Clone, Serialize, Deserialize)]
852pub struct IndexWarningDetails {
853 /// Current branch (if in git repo)
854 #[serde(skip_serializing_if = "Option::is_none")]
855 pub current_branch: Option<String>,
856 /// Indexed branch (if in git repo)
857 #[serde(skip_serializing_if = "Option::is_none")]
858 pub indexed_branch: Option<String>,
859 /// Current commit SHA (if in git repo)
860 #[serde(skip_serializing_if = "Option::is_none")]
861 pub current_commit: Option<String>,
862 /// Indexed commit SHA (if in git repo)
863 #[serde(skip_serializing_if = "Option::is_none")]
864 pub indexed_commit: Option<String>,
865 /// When the index was last written (Unix seconds).
866 #[serde(default, skip_serializing_if = "Option::is_none")]
867 pub indexed_at: Option<i64>,
868 /// How the working tree was compared to the index: `"git"` (candidates from
869 /// `git status`, confirmed by fingerprint) or `"walk"` (every file stat'ed).
870 #[serde(default, skip_serializing_if = "Option::is_none")]
871 pub checked_by: Option<String>,
872}
873
874/// The full answer to `check_index_status`.
875///
876/// `details` is present even when the index is fresh, so a human can see that the
877/// indexed commit differs from HEAD without that difference being called staleness:
878/// since 2.0.0 freshness is judged by file content, not by commit.
879#[derive(Debug, Clone)]
880pub struct IndexStatusReport {
881 pub status: IndexStatus,
882 pub can_trust_results: bool,
883 pub warning: Option<IndexWarning>,
884 pub details: Option<IndexWarningDetails>,
885}
886
887/// Pagination information for query results
888#[derive(Debug, Clone, Serialize, Deserialize)]
889pub struct PaginationInfo {
890 /// Total number of results before offset/limit — **`null` whenever
891 /// `total_is_exact` is false**. A list-mode search with a `limit` stops
892 /// verifying once the page is full, and the number verified by then is not a
893 /// total; reporting it as one made agents stop paginating early (2.0.0 field
894 /// test: `total: 851` for a term with 18,752 matches). Use `approx_total` for an
895 /// estimate, or a count-mode / no-limit search for the exact number.
896 #[serde(default)]
897 pub total: Option<usize>,
898 /// Number of results in this response (after offset/limit)
899 pub count: usize,
900 /// Offset used (starting position)
901 pub offset: usize,
902 /// Limit used (max results per page)
903 #[serde(skip_serializing_if = "Option::is_none")]
904 pub limit: Option<usize>,
905 /// Whether there are more results after this page
906 pub has_more: bool,
907 /// `true` when `total` counts every match. `false` when a list-mode search
908 /// stopped verifying once the page was full: `total` is then `null` and
909 /// `approx_total` carries an estimate. Count mode, no-limit searches,
910 /// symbol/AST searches and `require_exact_total` callers are always exact.
911 #[serde(default = "default_true")]
912 pub total_is_exact: bool,
913 /// Estimated total when `total_is_exact` is false. After the page filled, a
914 /// spread sample of the remaining candidate lines was verified and the
915 /// measured hit rate scaled over the rest (see
916 /// `query::ESTIMATE_SAMPLE_FILES`). Typically within ±30% on the synthetic
917 /// corpus; wider when hits cluster in a few files. Absent when no estimate was
918 /// possible (a regex with no literal, where every line is a candidate).
919 #[serde(default, skip_serializing_if = "Option::is_none")]
920 pub approx_total: Option<usize>,
921}
922
923impl PaginationInfo {
924 /// The total, only when it is a real one.
925 pub fn exact_total(&self) -> Option<usize> {
926 if self.total_is_exact {
927 self.total
928 } else {
929 None
930 }
931 }
932
933 /// The best number available for a threshold or a log line: the exact total,
934 /// else the estimate, else the end of this page. Never show it as a total.
935 pub fn best_total(&self) -> usize {
936 self.exact_total()
937 .or(self.approx_total)
938 .unwrap_or(self.offset + self.count)
939 }
940}
941
942/// Query response with results and index status
943#[derive(Debug, Clone, Serialize, Deserialize)]
944pub struct QueryResponse {
945 /// AI-optimized instruction for how to handle these results
946 /// Only present when --ai flag is used or in MCP mode
947 /// Provides guidance to AI agents on response format and next actions
948 #[serde(skip_serializing_if = "Option::is_none")]
949 pub ai_instruction: Option<String>,
950 /// Status of the index (fresh or stale)
951 pub status: IndexStatus,
952 /// Whether the results can be trusted
953 pub can_trust_results: bool,
954 /// Warning information (only present if stale)
955 #[serde(skip_serializing_if = "Option::is_none")]
956 pub warning: Option<IndexWarning>,
957 /// Pagination information
958 pub pagination: PaginationInfo,
959 /// File-grouped search results
960 /// Results are always grouped by file path, with dependencies populated when --dependencies flag is used
961 pub results: Vec<FileGroupedResult>,
962 /// For a whole-identifier search that found nothing: how many candidate lines
963 /// contain the pattern as a substring. Lets the caller explain a zero without
964 /// running a second search. Absent whenever there were results, or when the
965 /// search was not a whole-identifier one.
966 #[serde(default, skip_serializing_if = "Option::is_none")]
967 pub substring_hint_count: Option<usize>,
968 /// Things the engine did to the query that the caller should know about.
969 ///
970 /// Today this is one message at most: a whole-identifier pattern containing
971 /// brackets was escaped and run as a regex (see
972 /// `query::prepare_literal_pattern`). Every surface — CLI, MCP, HTTP — carries it,
973 /// so a rewrite is never silent on any of them.
974 #[serde(default, skip_serializing_if = "Vec::is_empty")]
975 pub warnings: Vec<String>,
976 /// For a whole-identifier search that found nothing while substring matches
977 /// exist: a ready-to-show sentence naming the count and the switch that shows
978 /// them. Absent whenever there were results, or when the search was not a
979 /// whole-identifier one.
980 #[serde(default, skip_serializing_if = "Option::is_none")]
981 pub hint: Option<String>,
982 /// Machine-readable cause behind `hint`: `hidden` (the filter names a
983 /// dot-directory), `not_indexed` (the `file` filter names a path the index does
984 /// not hold), `lock_or_generated`, `whole_identifier`. Absent when no rule
985 /// applies, so a harness can branch without parsing prose.
986 #[serde(default, skip_serializing_if = "Option::is_none")]
987 pub excluded_reason: Option<crate::query::ExcludedReason>,
988 /// For a search that found nothing: how many candidate files were lock or
989 /// generated files, which every search leaves out unless `include_locks` /
990 /// `include_generated` (or `lang`) asks for them. The `hint` says so too.
991 #[serde(default, skip_serializing_if = "Option::is_none")]
992 pub excluded_by_default: Option<usize>,
993 /// Count-only searches: the number of files with at least one match. `results`
994 /// is empty in that mode, so this is the only place the file count lives.
995 #[serde(default, skip_serializing_if = "Option::is_none")]
996 pub file_count: Option<usize>,
997 /// Per-phase timings, only when requested.
998 #[serde(default, skip_serializing_if = "Option::is_none")]
999 pub timings: Option<QueryTimings>,
1000}
1001
1002/// Report from cache compaction operation
1003#[derive(Debug, Clone, Serialize, Deserialize)]
1004pub struct CompactionReport {
1005 /// Always 0 since auto-update: index runs remove deleted files (kept for JSON compatibility)
1006 pub files_removed: usize,
1007 /// Space saved in bytes
1008 pub space_saved_bytes: u64,
1009 /// Duration in milliseconds
1010 pub duration_ms: u64,
1011}
1012
1013#[cfg(test)]
1014mod tests {
1015 use super::*;
1016
1017 /// `rfx stats --json` printed the language maps in `HashMap` order through 2.2.0.
1018 #[test]
1019 fn index_stats_json_lists_languages_in_order() {
1020 let names = ["Zig", "Rust", "Text", "Go", "Python", "C", "Kotlin", "Ruby"];
1021 let stats = IndexStats {
1022 files_by_language: names.iter().map(|n| (n.to_string(), 1)).collect(),
1023 lines_by_language: names.iter().map(|n| (n.to_string(), 10)).collect(),
1024 ..Default::default()
1025 };
1026 // A string, not a `Value`: serde_json's `Map` would sort the keys itself.
1027 let json = serde_json::to_string(&stats).unwrap();
1028 for field in ["files_by_language", "lines_by_language"] {
1029 let section = &json[json.find(field).unwrap()..];
1030 let section = §ion[..section.find('}').unwrap()];
1031 let positions: Vec<usize> =
1032 ["C", "Go", "Kotlin", "Python", "Ruby", "Rust", "Text", "Zig"]
1033 .iter()
1034 .map(|n| section.find(&format!("\"{n}\"")).unwrap())
1035 .collect();
1036 assert!(positions.is_sorted(), "{field}: {section}");
1037 }
1038 }
1039
1040 #[test]
1041 fn test_symbol_ref_json_shape() {
1042 let sym = SymbolRef {
1043 name: "my_function".to_string(),
1044 kind: SymbolKind::Function,
1045 span: Span {
1046 start_line: 10,
1047 end_line: 20,
1048 },
1049 };
1050 let json = serde_json::to_value(&sym).unwrap();
1051 assert_eq!(json["name"], "my_function");
1052 assert_eq!(json["kind"], "Function");
1053 assert_eq!(json["span"]["start_line"], 10);
1054 assert_eq!(json["span"]["end_line"], 20);
1055 assert!(json.as_array().is_none());
1056 }
1057
1058 #[test]
1059 fn test_symbol_ref_roundtrip() {
1060 let original = SymbolRef {
1061 name: "MyStruct".to_string(),
1062 kind: SymbolKind::Struct,
1063 span: Span {
1064 start_line: 1,
1065 end_line: 5,
1066 },
1067 };
1068 let json = serde_json::to_string(&original).unwrap();
1069 let decoded: SymbolRef = serde_json::from_str(&json).unwrap();
1070 assert_eq!(original, decoded);
1071 }
1072
1073 #[test]
1074 fn test_symbol_ref_exact_json() {
1075 let sym = SymbolRef {
1076 name: "Foo".to_string(),
1077 kind: SymbolKind::Class,
1078 span: Span {
1079 start_line: 3,
1080 end_line: 7,
1081 },
1082 };
1083 let json = serde_json::to_string(&sym).unwrap();
1084 assert_eq!(
1085 json,
1086 r#"{"name":"Foo","kind":"Class","span":{"start_line":3,"end_line":7}}"#
1087 );
1088 }
1089}