Skip to main content

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}