symforge/protocol/search_tools.rs
1//! Search-oriented MCP tool input types and pure request parsing helpers.
2
3use schemars::JsonSchema;
4use serde::{Deserialize, Serialize};
5
6use crate::domain::index::LanguageId;
7use crate::live_index::search;
8
9use super::read_tools::{lenient_bool, lenient_option_vec, lenient_u32, lenient_u64};
10
11/// Input for `search_symbols`.
12#[derive(Deserialize, Serialize, JsonSchema)]
13pub struct SearchSymbolsInput {
14 /// Search query (case-insensitive substring match). Optional when `kind` or `path_prefix` is
15 /// provided — omitting `query` enables browse mode.
16 #[serde(default)]
17 pub query: Option<String>,
18 /// Optional kind filter using display names such as `fn`, `class`, or `interface`.
19 pub kind: Option<String>,
20 /// Optional relative path prefix scope, for example `src/` or `src/protocol`.
21 pub path_prefix: Option<String>,
22 /// Optional canonical language name such as `Rust`, `TypeScript`, `C#`, or `C++`.
23 pub language: Option<String>,
24 /// Optional maximum number of matches to return (default 50, capped at 100).
25 #[serde(default, deserialize_with = "lenient_u32")]
26 pub limit: Option<u32>,
27 /// When true, include generated files in the result set.
28 #[serde(default, deserialize_with = "lenient_bool")]
29 pub include_generated: Option<bool>,
30 /// When true, include test files in the result set.
31 #[serde(default, deserialize_with = "lenient_bool")]
32 pub include_tests: Option<bool>,
33 /// When true, include vendored/third-party paths (vendor/, node_modules/, third_party/).
34 /// Default false -- vendor noise dominates symbol lookup in repos with embedded grammars.
35 #[serde(default, deserialize_with = "lenient_bool")]
36 pub include_vendor: Option<bool>,
37 /// When true, include personal tooling paths (.claude/gsd-*).
38 /// Default false -- personal sidecars rarely answer codebase symbol questions.
39 #[serde(default, deserialize_with = "lenient_bool")]
40 pub include_personal_tooling: Option<bool>,
41 /// When true, return an approximate token cost estimate instead of actual content.
42 #[serde(default, deserialize_with = "lenient_bool")]
43 pub estimate: Option<bool>,
44 /// Optional maximum token budget for the response.
45 #[serde(default, deserialize_with = "lenient_u64")]
46 pub max_tokens: Option<u64>,
47 /// Feature 012 (Phase 3): target a SINGLE open project by id/alias instead of
48 /// the session's active project. Mutually exclusive with `projects`. Must be a
49 /// project id/alias, NEVER a filesystem path (a path is rejected with a
50 /// corrective error pointing at `index_folder(add:true)`). Omitting both
51 /// `project` and `projects` targets the active project (today's behavior).
52 #[serde(default)]
53 pub project: Option<String>,
54 /// Feature 012 (Phase 3): target an EXPLICIT subset of open projects by
55 /// id/alias, or `["*"]` for every open project. Mutually exclusive with
56 /// `project`. An empty list is rejected (no silent "all"). Daemon-only.
57 // `#[schemars(with = "Vec<String>")]` keeps this a plain `type: "array"`
58 // schema, NOT the `type: ["array", "null"]` union that strict MCP clients
59 // reject (mirrors `SearchTextInput::terms`; enforced by
60 // `tests/strict_client_schema_compat.rs`); serde keeps the field optional.
61 #[serde(default)]
62 #[schemars(with = "Vec<String>")]
63 pub projects: Option<Vec<String>>,
64}
65
66/// Input for `search_text`.
67#[derive(Deserialize, Serialize, JsonSchema, Default)]
68pub struct SearchTextInput {
69 /// Search query (case-insensitive substring match unless `regex` is true).
70 pub query: Option<String>,
71 /// Optional list of terms to match with OR semantics.
72 #[serde(default, deserialize_with = "lenient_option_vec")]
73 #[schemars(with = "Vec<String>")]
74 pub terms: Option<Vec<String>>,
75 /// Interpret `query` as a regex pattern instead of a literal substring.
76 #[serde(default, deserialize_with = "lenient_bool")]
77 pub regex: Option<bool>,
78 /// Optional relative path prefix scope, for example `src/` or `src/protocol`.
79 pub path_prefix: Option<String>,
80 /// Optional canonical language name such as `Rust`, `TypeScript`, `C#`, or `C++`.
81 pub language: Option<String>,
82 /// Optional maximum number of matches to return across all files (default 50).
83 #[serde(default, deserialize_with = "lenient_u32")]
84 pub limit: Option<u32>,
85 /// Optional maximum number of matches to return per file (default 5).
86 #[serde(default, deserialize_with = "lenient_u32")]
87 pub max_per_file: Option<u32>,
88 /// When true, include generated files in the result set.
89 #[serde(default, deserialize_with = "lenient_bool")]
90 pub include_generated: Option<bool>,
91 /// When true, include test files in the result set.
92 #[serde(default, deserialize_with = "lenient_bool")]
93 pub include_tests: Option<bool>,
94 /// When true, include vendored/third-party paths (vendor/, node_modules/, third_party/).
95 /// Default false -- vendor noise dominates results in repos with embedded grammars.
96 #[serde(default, deserialize_with = "lenient_bool")]
97 pub include_vendor: Option<bool>,
98 /// When true, include personal tooling paths (.claude/gsd-*).
99 /// Default false -- personal sidecars rarely answer code questions.
100 #[serde(default, deserialize_with = "lenient_bool")]
101 pub include_personal_tooling: Option<bool>,
102 /// Optional repo-relative include glob, for example `src/**/*.ts`.
103 pub glob: Option<String>,
104 /// Optional repo-relative exclude glob, for example `**/*.spec.ts`.
105 pub exclude_glob: Option<String>,
106 /// Optional symmetric number of surrounding lines to render around each match.
107 #[serde(default, deserialize_with = "lenient_u32")]
108 pub context: Option<u32>,
109 /// Optional case-sensitivity override. Literal mode defaults to false; regex mode defaults to true.
110 #[serde(default, deserialize_with = "lenient_bool")]
111 pub case_sensitive: Option<bool>,
112 /// When true, require whole-word matches for literal searches. Not supported with `regex=true`.
113 #[serde(default, deserialize_with = "lenient_bool")]
114 pub whole_word: Option<bool>,
115 /// Group matches: "file" (default), "symbol" (one entry per enclosing symbol),
116 /// "usage" (exclude imports and comments), or "names" (flat deduplicated list of
117 /// symbol names containing matches — useful as input to batch operations).
118 pub group_by: Option<String>,
119 /// When true, for each match include a compact list of callers of the enclosing symbol.
120 #[serde(default, deserialize_with = "lenient_bool")]
121 pub follow_refs: Option<bool>,
122 /// Max number of file matches to enrich with callers when follow_refs=true (default 3).
123 #[serde(default, deserialize_with = "lenient_u32")]
124 pub follow_refs_limit: Option<u32>,
125 /// When true, re-rank results by semantic importance (caller count, churn, symbol kind)
126 /// rather than simple match count. Default: false.
127 #[serde(default, deserialize_with = "lenient_bool")]
128 pub ranked: Option<bool>,
129 /// When true, return an approximate token cost estimate instead of actual content.
130 #[serde(default, deserialize_with = "lenient_bool")]
131 pub estimate: Option<bool>,
132 /// Optional maximum token budget for the response. Output is truncated at a line boundary if exceeded.
133 #[serde(default, deserialize_with = "lenient_u64")]
134 pub max_tokens: Option<u64>,
135 /// When true, interpret `query` as an ast-grep structural pattern instead of a text search.
136 /// Matches AST patterns using tree-sitter. Use `$VAR` for single-node metavariables
137 /// and `$$$` for multi-node wildcards. Example: `fn $NAME($$$) { $$$ }`.
138 #[serde(default, deserialize_with = "lenient_bool")]
139 pub structural: Option<bool>,
140 /// Feature 012 (Phase 3): target a SINGLE open project by id/alias instead of
141 /// the session's active project. Mutually exclusive with `projects`; must be a
142 /// project id/alias, never a path. Omitting both targets the active project.
143 #[serde(default)]
144 pub project: Option<String>,
145 /// Feature 012 (Phase 3): target an EXPLICIT subset of open projects by
146 /// id/alias, or `["*"]` for every open project. Mutually exclusive with
147 /// `project`; an empty list is rejected. Daemon-only.
148 // `#[schemars(with = "Vec<String>")]` keeps this a plain `type: "array"`
149 // schema, NOT the `type: ["array", "null"]` union that strict MCP clients
150 // reject (mirrors `SearchTextInput::terms`; enforced by
151 // `tests/strict_client_schema_compat.rs`); serde keeps the field optional.
152 #[serde(default)]
153 #[schemars(with = "Vec<String>")]
154 pub projects: Option<Vec<String>>,
155}
156
157/// Input for `search_files`.
158#[derive(Deserialize, Serialize, JsonSchema)]
159pub struct SearchFilesInput {
160 /// Filename, folder name, or partial path. Required for search and resolve modes. Optional when `changed_with` is provided.
161 #[serde(default)]
162 pub query: String,
163 /// Optional maximum number of matches to return (default 20, capped at 50).
164 #[serde(default, deserialize_with = "lenient_u32")]
165 pub limit: Option<u32>,
166 /// Optional current file path to boost local results.
167 pub current_file: Option<String>,
168 /// Deprecated since v7.x: prefer `rank_by="path+cochange"` with
169 /// `anchor_path=<path>`. This compatibility path still finds files that
170 /// frequently co-change with this file via git temporal coupling, but is
171 /// scheduled for removal in v8.x.
172 pub changed_with: Option<String>,
173 /// Set to true for exact path resolution mode: resolves an ambiguous filename or partial path to one exact project path.
174 #[serde(default, deserialize_with = "lenient_bool")]
175 pub resolve: Option<bool>,
176 /// When true, return an approximate token cost estimate instead of actual content.
177 #[serde(default, deserialize_with = "lenient_bool")]
178 pub estimate: Option<bool>,
179 /// Optional maximum token budget for the response.
180 #[serde(default, deserialize_with = "lenient_u64")]
181 pub max_tokens: Option<u64>,
182 /// When true, append a compact ranking explanation unless ranking diagnostics are disabled by policy.
183 /// Missing values default off; `SYMFORGE_DEBUG_RANKING=1` may still default diagnostics on operationally.
184 #[serde(default, deserialize_with = "lenient_bool")]
185 pub debug_ranking: Option<bool>,
186 /// Optional ranking mode. `"frecency"` requests call-time frecency
187 /// resolution: available session or persistent history is fused with
188 /// path ranking, otherwise the response includes explicit fallback,
189 /// unavailable, or disabled-by-policy evidence.
190 /// `"path+cochange"` fuses path match with the coupling store when
191 /// `anchor_path` is set and ready coupling data exists; otherwise the
192 /// response reports call-time preparation, fallback, unavailable, stale,
193 /// or disabled-by-policy evidence.
194 /// Any other value (including `None`) preserves the default
195 /// tier-based ordering exactly.
196 ///
197 /// The separate `changed_with=` branch is preserved for compatibility.
198 #[serde(default)]
199 pub rank_by: Option<String>,
200 /// Anchor file used as the co-change pivot when `rank_by="path+cochange"`.
201 #[serde(default)]
202 pub anchor_path: Option<String>,
203 /// When true, include vendored/third-party paths (vendor/, node_modules/, third_party/).
204 /// Default false -- vendor noise dominates path lookup in repos with embedded grammars.
205 #[serde(default, deserialize_with = "lenient_bool")]
206 pub include_vendor: Option<bool>,
207 /// When true, include personal tooling paths (.claude/gsd-*).
208 /// Default false -- personal sidecars rarely answer codebase path questions.
209 #[serde(default, deserialize_with = "lenient_bool")]
210 pub include_personal_tooling: Option<bool>,
211}
212
213/// Input for `find_references`.
214#[derive(Deserialize, Serialize, JsonSchema)]
215pub struct FindReferencesInput {
216 /// Symbol name to find references for (or trait/type name when mode='implementations').
217 pub name: String,
218 /// Filter by reference kind: "call", "import", "type_usage", or "all" (default: "all"). Ignored when mode='implementations'.
219 pub kind: Option<String>,
220 /// Optional exact-selector path from `search_symbols`, for example `src/db.rs`. Ignored when mode='implementations'.
221 pub path: Option<String>,
222 /// Optional selected symbol kind such as `fn`, `class`, or `struct`. Ignored when mode='implementations'.
223 pub symbol_kind: Option<String>,
224 /// Optional selected symbol line from `search_symbols`. Ignored when mode='implementations'.
225 #[serde(default, deserialize_with = "lenient_u32")]
226 pub symbol_line: Option<u32>,
227 /// Maximum number of files/entries to show (default 20 for references, 200 for implementations; capped at 100/500).
228 #[serde(default, deserialize_with = "lenient_u32")]
229 pub limit: Option<u32>,
230 /// Maximum number of reference hits per file (default 10, capped at 50). Ignored when mode='implementations'.
231 #[serde(default, deserialize_with = "lenient_u32")]
232 pub max_per_file: Option<u32>,
233 /// When true, show compact output: file:line [kind] in symbol — no source text (60-75% smaller). Ignored when mode='implementations'.
234 #[serde(default, deserialize_with = "lenient_bool")]
235 pub compact: Option<bool>,
236 /// Mode: "references" (default — call sites, imports, type usages) or "implementations" (trait/interface implementors and implemented traits). When mode='implementations', only name, direction, and limit are used.
237 #[serde(default)]
238 pub mode: Option<String>,
239 /// Search direction for implementations mode: "trait" (find implementors), "type" (find traits a type implements), or "auto" (default: search both).
240 #[serde(default)]
241 pub direction: Option<String>,
242 /// When true, return an approximate token cost estimate instead of actual content.
243 #[serde(default, deserialize_with = "lenient_bool")]
244 pub estimate: Option<bool>,
245 /// Optional maximum token budget for the response.
246 #[serde(default, deserialize_with = "lenient_u64")]
247 pub max_tokens: Option<u64>,
248 /// Feature 012 (Phase 3): target a SINGLE open project by id/alias instead of
249 /// the session's active project. Mutually exclusive with `projects`; must be a
250 /// project id/alias, never a path. Omitting both targets the active project.
251 #[serde(default)]
252 pub project: Option<String>,
253 /// Feature 012 (Phase 3): target an EXPLICIT subset of open projects by
254 /// id/alias, or `["*"]` for every open project. Mutually exclusive with
255 /// `project`; an empty list is rejected. Daemon-only.
256 // `#[schemars(with = "Vec<String>")]` keeps this a plain `type: "array"`
257 // schema, NOT the `type: ["array", "null"]` union that strict MCP clients
258 // reject (mirrors `SearchTextInput::terms`; enforced by
259 // `tests/strict_client_schema_compat.rs`); serde keeps the field optional.
260 #[serde(default)]
261 #[schemars(with = "Vec<String>")]
262 pub projects: Option<Vec<String>>,
263}
264
265pub(crate) fn parse_language_filter(input: Option<&str>) -> Result<Option<LanguageId>, String> {
266 let Some(language) = input.map(str::trim).filter(|language| !language.is_empty()) else {
267 return Ok(None);
268 };
269
270 let normalized = language.to_ascii_lowercase();
271 let parsed = match normalized.as_str() {
272 "rust" => Some(LanguageId::Rust),
273 "python" => Some(LanguageId::Python),
274 "javascript" => Some(LanguageId::JavaScript),
275 "typescript" => Some(LanguageId::TypeScript),
276 "go" => Some(LanguageId::Go),
277 "java" => Some(LanguageId::Java),
278 "c" => Some(LanguageId::C),
279 "c++" => Some(LanguageId::Cpp),
280 "c#" => Some(LanguageId::CSharp),
281 "ruby" => Some(LanguageId::Ruby),
282 "php" => Some(LanguageId::Php),
283 "swift" => Some(LanguageId::Swift),
284 "kotlin" => Some(LanguageId::Kotlin),
285 "dart" => Some(LanguageId::Dart),
286 "perl" => Some(LanguageId::Perl),
287 "elixir" => Some(LanguageId::Elixir),
288 "json" => Some(LanguageId::Json),
289 "toml" => Some(LanguageId::Toml),
290 "yaml" => Some(LanguageId::Yaml),
291 "markdown" | "md" => Some(LanguageId::Markdown),
292 "env" => Some(LanguageId::Env),
293 "html" => Some(LanguageId::Html),
294 "css" => Some(LanguageId::Css),
295 "scss" => Some(LanguageId::Scss),
296 _ => None,
297 };
298
299 parsed.map(Some).ok_or_else(|| {
300 "Unsupported language filter. Use one of: Rust, Python, JavaScript, TypeScript, Go, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, Dart, Perl, Elixir, JSON, TOML, YAML, Markdown, Env, HTML, CSS, SCSS.".to_string()
301 })
302}
303
304fn normalize_path_prefix(input: Option<&str>) -> search::PathScope {
305 let Some(prefix) = input.map(str::trim).filter(|prefix| !prefix.is_empty()) else {
306 return search::PathScope::any();
307 };
308
309 let normalized = prefix
310 .replace('\\', "/")
311 .trim_start_matches("./")
312 .trim_start_matches('/')
313 .trim_end_matches('/')
314 .to_string();
315
316 if normalized.is_empty() {
317 search::PathScope::any()
318 } else {
319 search::PathScope::prefix(normalized)
320 }
321}
322
323pub(crate) fn normalize_search_text_glob(input: Option<&str>) -> Option<String> {
324 input
325 .map(str::trim)
326 .filter(|pattern| !pattern.is_empty())
327 .map(|pattern| {
328 let normalized = pattern
329 .replace('\\', "/")
330 .trim_start_matches("./")
331 .trim_start_matches('/')
332 .to_string();
333 // Auto-prefix bare filenames (no glob chars, no path separators)
334 // so "foo.rs" matches "**/foo.rs" instead of failing silently.
335 if !normalized.contains('*')
336 && !normalized.contains('/')
337 && !normalized.contains('?')
338 && !normalized.contains('[')
339 {
340 format!("**/{normalized}")
341 } else {
342 normalized
343 }
344 })
345 .filter(|pattern| !pattern.is_empty())
346}
347
348pub(crate) fn search_symbols_options_from_input(
349 input: &SearchSymbolsInput,
350) -> Result<search::SymbolSearchOptions, String> {
351 let is_browse = input
352 .query
353 .as_ref()
354 .map(|q| q.trim().is_empty())
355 .unwrap_or(true);
356 let default_limit = if is_browse { 20u32 } else { 50u32 };
357 Ok(search::SymbolSearchOptions {
358 path_scope: normalize_path_prefix(input.path_prefix.as_deref()),
359 search_scope: search::SearchScope::Code,
360 result_limit: search::ResultLimit::new(
361 input.limit.unwrap_or(default_limit).min(100) as usize
362 ),
363 noise_policy: search::NoisePolicy {
364 include_generated: input.include_generated.unwrap_or(false),
365 include_tests: input.include_tests.unwrap_or(false),
366 include_vendor: input.include_vendor.unwrap_or(false),
367 include_ignored: false,
368 },
369 include_personal_tooling: input.include_personal_tooling.unwrap_or(false),
370 language_filter: parse_language_filter(input.language.as_deref())?,
371 })
372}
373
374pub(crate) fn search_text_options_from_input(
375 input: &SearchTextInput,
376) -> Result<search::TextSearchOptions, String> {
377 let is_regex = input.regex.unwrap_or(false);
378 let is_ranked = input.ranked.unwrap_or(false);
379
380 // When regex mode is active the user is doing a targeted, precise search
381 // and expects completeness over test noise by default. Vendor remains
382 // opt-in because embedded grammars and dependencies can dominate result
383 // caps before project code is seen.
384 let include_tests = input.include_tests.unwrap_or(is_regex);
385 let include_generated = input.include_generated.unwrap_or(false);
386
387 // When ranked=true the user wants results ordered by importance, which
388 // requires scanning broadly first. A low total_limit starves the
389 // ranker — boost it so common terms still surface enough files.
390 let total_limit = input.limit.unwrap_or(if is_ranked { 200 } else { 50 }) as usize;
391
392 Ok(search::TextSearchOptions {
393 path_scope: normalize_path_prefix(input.path_prefix.as_deref()),
394 search_scope: search::SearchScope::Code,
395 noise_policy: search::NoisePolicy {
396 include_generated,
397 include_tests,
398 include_vendor: input.include_vendor.unwrap_or(false),
399 include_ignored: false,
400 },
401 include_personal_tooling: input.include_personal_tooling.unwrap_or(false),
402 language_filter: parse_language_filter(input.language.as_deref())?,
403 total_limit,
404 max_per_file: input.max_per_file.unwrap_or(5) as usize,
405 glob: normalize_search_text_glob(input.glob.as_deref()),
406 exclude_glob: normalize_search_text_glob(input.exclude_glob.as_deref()),
407 context: input.context.map(|context| context as usize),
408 case_sensitive: input.case_sensitive,
409 whole_word: input.whole_word.unwrap_or(false),
410 ranked: is_ranked,
411 churn_scores: None,
412 })
413}
414
415/// Attempt to fix double-escaped regex character classes (e.g., `\\s` -> `\s`).
416/// Returns `Some(fixed)` if the pattern contains likely double-escaped sequences,
417/// `None` otherwise.
418pub(crate) fn fix_common_double_escapes(pattern: &str) -> Option<String> {
419 static RE: std::sync::LazyLock<regex::Regex> = std::sync::LazyLock::new(|| {
420 regex::Regex::new(r"\\\\([sdwbntSDWB])").expect("static regex")
421 });
422 if !RE.is_match(pattern) {
423 return None;
424 }
425 Some(RE.replace_all(pattern, r"\$1").to_string())
426}