use serde_json::json;
use std::collections::HashSet;
use std::path::Path;
use std::sync::{Arc, Mutex};
use crate::db::{
graph::{DEFAULT_MAX_TARGETS, GraphDb, QueryExt},
vector::{ExactNameProbe, UuidProbe, VectorDb, VectorSearchExt},
};
use crate::models::RepoScope;
use crate::pipeline::embed::Embedder;
pub mod rank;
pub const DEFAULT_MAX_RESULTS: usize = 5;
pub const MAX_RESULTS_CEILING: usize = 100;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ResolvedLimit {
pub value: usize,
pub requested: usize,
}
impl ResolvedLimit {
pub fn was_clamped(&self) -> bool {
self.requested != self.value
}
pub fn notice(&self) -> Option<String> {
if !self.was_clamped() {
return None;
}
if self.requested == 0 {
return Some("> Note: `max_results` was floored from 0 to the minimum of 1.\n".into());
}
Some(format!(
"> Note: `max_results` was clamped from {requested} to the advertised maximum of {MAX_RESULTS_CEILING}. \
This tool has no pagination — narrow the search with `kinds` / `path` / `repo_name`, or refine the query.\n",
requested = self.requested
))
}
}
pub fn resolve_max_results(requested: usize) -> ResolvedLimit {
ResolvedLimit {
value: requested.clamp(1, MAX_RESULTS_CEILING),
requested,
}
}
#[derive(Clone)]
pub struct SearchContext<'a> {
pub vector_db: &'a Arc<VectorDb>,
pub graph_db: &'a Arc<GraphDb>,
pub embedder: &'a Arc<Mutex<Embedder>>,
}
pub struct SearchFilters<'a> {
pub kinds: Option<&'a str>,
pub path: Option<&'a str>,
}
pub async fn run_search_hybrid_context(
query: &str,
max_results: usize,
repo: &RepoScope,
filters: SearchFilters<'_>,
ctx: &SearchContext<'_>,
) -> anyhow::Result<serde_json::Value> {
let max_results = resolve_max_results(max_results).value;
let vector = ctx
.embedder
.lock()
.unwrap()
.embed_query(query)
.map_err(|e| anyhow::anyhow!("Embedding failed: {}", e))?;
let repo_names = repo.filter_names();
let expanded_kinds = rank::parse_kinds(filters.kinds);
let normalized_path = normalized_path(filters.path);
const PATH_POOL_CEILING: usize = 600;
let pool_window = if normalized_path.is_some() {
rank::candidate_limit(max_results)
.saturating_mul(3)
.min(PATH_POOL_CEILING)
} else {
rank::candidate_limit(max_results)
};
let search_results = ctx
.vector_db
.search(&vector, pool_window, &repo_names, &expanded_kinds)
.await?;
let prefix_results = ctx
.graph_db
.find_entities_by_name_prefix(query, &repo_names, max_results)
.await
.unwrap_or_else(|_| json!([]));
let mut seen_uuids: HashSet<String> = HashSet::new();
let mut combined: Vec<serde_json::Value> = Vec::new();
merge_prefix_hits(
&prefix_results,
&expanded_kinds,
normalized_path.as_deref(),
&mut seen_uuids,
&mut combined,
);
let pool = CandidatePool {
vector: &vector,
query,
search_results: &search_results,
seen_uuids: &mut seen_uuids,
repo_names: &repo_names,
expanded_kinds: &expanded_kinds,
candidate_limit: pool_window,
ctx,
};
let mut vector_hits = pool.collect().await;
if let Some(pattern) = &normalized_path {
vector_hits.retain(|hit| {
rank::path_allows(
Some(pattern),
hit.get("file_path").and_then(|v| v.as_str()).unwrap_or(""),
)
});
}
combined.extend(rank::rerank(vector_hits, query));
if combined.is_empty() {
return Ok(serde_json::Value::Null);
}
combined.truncate(max_results);
let uuids: Vec<String> = combined
.iter()
.map(|entity| {
entity
.get("uuid")
.and_then(|v| v.as_str())
.unwrap_or("")
.to_string()
})
.collect();
let fetched = ctx
.graph_db
.get_entities_with_dependencies(&uuids, &repo_names)
.await?;
let context = serde_json::Value::Array(rank::dedup_by_identity(
fetched.as_array().cloned().unwrap_or_default(),
));
let entity_names: Vec<String> = context
.as_array()
.map(|entities| {
entities
.iter()
.filter_map(|entity| {
entity
.get("name")
.and_then(|v| v.as_str())
.map(String::from)
})
.collect()
})
.unwrap_or_default();
let enriched_context = enrich_with_relationships(&context, &entity_names, ctx.graph_db, repo)
.await
.unwrap_or(context);
Ok(enriched_context)
}
async fn enrich_with_relationships(
context: &serde_json::Value,
_entity_names: &[String],
graph_db: &Arc<GraphDb>,
repo: &RepoScope,
) -> anyhow::Result<serde_json::Value> {
let mut enriched = context.clone();
let repo_names = repo.filter_names();
if let Some(entities) = enriched.as_array_mut() {
for entity in entities.iter_mut() {
if let Some(name) = entity.get("name").and_then(|v| v.as_str())
&& let Ok(references) = graph_db
.find_references(name, &repo_names, DEFAULT_MAX_TARGETS, Some("all"))
.await
{
enrich_single_entity(entity, &references);
}
}
}
Ok(enriched)
}
pub(crate) struct CandidatePool<'a> {
pub vector: &'a [f32],
pub query: &'a str,
pub search_results: &'a [serde_json::Value],
pub seen_uuids: &'a mut HashSet<String>,
pub repo_names: &'a [String],
pub expanded_kinds: &'a [String],
pub candidate_limit: usize,
pub ctx: &'a SearchContext<'a>,
}
impl CandidatePool<'_> {
pub async fn collect(self) -> Vec<serde_json::Value> {
let mut vector_hits: Vec<serde_json::Value> = Vec::new();
merge_hits(self.search_results, self.seen_uuids, &mut vector_hits);
let probe_hits = name_probe_hits(
self.vector,
self.query,
self.repo_names,
self.expanded_kinds,
self.ctx,
)
.await;
merge_hits(&probe_hits, self.seen_uuids, &mut vector_hits);
let (bridge, top_roots) = CallerBridge {
vector: self.vector,
search_results: self.search_results,
seen_uuids: self.seen_uuids,
repo_names: self.repo_names,
expanded_kinds: self.expanded_kinds,
ctx: self.ctx,
}
.run(self.candidate_limit)
.await;
merge_hits(&bridge, self.seen_uuids, &mut vector_hits);
annotate_root_coverage(&mut vector_hits, &top_roots, self.repo_names, self.ctx).await;
vector_hits
}
}
fn merge_hits(
hits: &[serde_json::Value],
seen_uuids: &mut HashSet<String>,
pool: &mut Vec<serde_json::Value>,
) {
for hit in hits {
if let Some(uuid) = hit.get("uuid").and_then(|v| v.as_str())
&& seen_uuids.insert(uuid.to_string())
{
pool.push(hit.clone());
}
}
}
fn normalized_path(path: Option<&str>) -> Option<String> {
path.filter(|p| !p.trim().is_empty()).map(|p| {
crate::cli_tools::list_files::normalize_list_path(
p,
std::env::current_dir().ok().as_deref(),
std::env::var("KNOT_REPO_PATH")
.ok()
.as_deref()
.map(Path::new),
)
})
}
fn merge_prefix_hits(
prefix_results: &serde_json::Value,
expanded_kinds: &[String],
normalized_path: Option<&str>,
seen_uuids: &mut HashSet<String>,
combined: &mut Vec<serde_json::Value>,
) {
if let Some(arr) = prefix_results.as_array() {
for entity in arr {
let kind = entity.get("kind").and_then(|v| v.as_str()).unwrap_or("");
let file_path = entity
.get("file_path")
.and_then(|v| v.as_str())
.unwrap_or("");
if rank::kinds_allow(expanded_kinds, kind)
&& rank::path_allows(normalized_path, file_path)
{
push_if_unique(entity, seen_uuids, combined);
}
}
}
}
async fn name_probe_hits(
vector: &[f32],
query: &str,
repo_names: &[String],
expanded_kinds: &[String],
ctx: &SearchContext<'_>,
) -> Vec<serde_json::Value> {
let probe_tokens = rank::significant_query_tokens(query);
if probe_tokens.is_empty() {
return Vec::new();
}
let probe_names = rank::probe_name_variants(&probe_tokens);
ctx.vector_db
.search_exact_names(ExactNameProbe {
vector,
names: &probe_names,
tokens: &probe_tokens,
limit: 24,
repo_names,
kinds: expanded_kinds,
})
.await
.unwrap_or_default()
}
pub(crate) struct CallerBridge<'a> {
pub vector: &'a [f32],
pub search_results: &'a [serde_json::Value],
pub seen_uuids: &'a HashSet<String>,
pub repo_names: &'a [String],
pub expanded_kinds: &'a [String],
pub ctx: &'a SearchContext<'a>,
}
impl CallerBridge<'_> {
pub async fn run(&self, pool_cap: usize) -> (Vec<serde_json::Value>, Vec<String>) {
let top_roots: Vec<String> = self
.search_results
.iter()
.filter(|hit| {
let kind = hit.get("kind").and_then(|v| v.as_str()).unwrap_or("");
let file_path = hit.get("file_path").and_then(|v| v.as_str()).unwrap_or("");
rank::kind_boost(kind) >= 0.0 && !rank::is_test_path(file_path)
})
.filter_map(|hit| hit.get("uuid").and_then(|v| v.as_str()))
.take(TOP_ROOTS)
.map(String::from)
.collect();
if top_roots.is_empty() {
return (Vec::new(), top_roots);
}
let links = self
.ctx
.graph_db
.find_caller_links(&top_roots, self.repo_names, CALLER_LINK_LIMIT)
.await
.unwrap_or_default();
if links.is_empty() {
return (Vec::new(), top_roots);
}
let caller_uuids: HashSet<String> =
links.iter().map(|(caller, _)| caller.clone()).collect();
let fetch_list: Vec<String> = caller_uuids
.iter()
.filter(|u| !self.seen_uuids.contains(*u))
.cloned()
.collect();
if fetch_list.is_empty() {
return (Vec::new(), top_roots);
}
let mut hits = self
.ctx
.vector_db
.search_by_uuids(UuidProbe {
vector: self.vector,
uuids: &fetch_list,
repo_names: self.repo_names,
kinds: self.expanded_kinds,
limit: pool_cap,
})
.await
.unwrap_or_default();
hits.retain(|hit| {
hit.get("uuid")
.and_then(|v| v.as_str())
.is_some_and(|u| caller_uuids.contains(u))
});
(hits, top_roots)
}
}
async fn annotate_root_coverage(
pool: &mut [serde_json::Value],
top_roots: &[String],
repo_names: &[String],
ctx: &SearchContext<'_>,
) {
if pool.is_empty() || top_roots.is_empty() {
return;
}
let pool_uuids: Vec<String> = pool
.iter()
.filter_map(|hit| hit.get("uuid").and_then(|v| v.as_str()))
.map(String::from)
.collect();
if pool_uuids.is_empty() {
return;
}
let coverage = ctx
.graph_db
.fetch_root_coverage(&pool_uuids, top_roots, repo_names, pool_uuids.len())
.await
.unwrap_or_default();
if coverage.is_empty() {
return;
}
let by_uuid: std::collections::HashMap<&str, &crate::db::graph::RootCoverage> = coverage
.iter()
.map(|row| (row.uuid.as_str(), row))
.collect();
let pool_meta: std::collections::HashMap<&str, (&str, &str)> = pool
.iter()
.filter_map(|hit| {
Some((
hit.get("uuid")?.as_str()?,
(hit.get("kind")?.as_str()?, hit.get("file_path")?.as_str()?),
))
})
.collect();
let in_pool: HashSet<&str> = pool_uuids.iter().map(String::as_str).collect();
let mut superseded: HashSet<String> = HashSet::new();
if let Ok(links) = ctx
.graph_db
.find_caller_links(&pool_uuids, repo_names, pool_uuids.len() * 16)
.await
{
for (caller, callee) in links.iter().filter(|(caller, callee)| {
in_pool.contains(caller.as_str())
&& in_pool.contains(callee.as_str())
&& caller != callee
}) {
let (Some(caller_cov), Some(callee_cov)) =
(by_uuid.get(caller.as_str()), by_uuid.get(callee.as_str()))
else {
continue;
};
let caller_production =
pool_meta
.get(caller.as_str())
.is_some_and(|(kind, file_path)| {
rank::kind_boost(kind) >= 0.0 && !rank::is_test_path(file_path)
});
if caller_production && caller_cov.direct_roots >= callee_cov.direct_roots {
superseded.insert(callee.clone());
}
}
}
for hit in pool.iter_mut() {
let uuid = hit.get("uuid").and_then(|v| v.as_str()).unwrap_or("");
let Some(row) = by_uuid.get(uuid) else {
continue;
};
let superseded_here = superseded.contains(uuid);
let Some(obj) = hit.as_object_mut() else {
continue;
};
obj.entry("fqn")
.or_insert_with(|| serde_json::json!(row.fqn));
obj.insert(
"caller_roots".to_string(),
serde_json::json!(row.direct_roots),
);
obj.insert(
"caller_roots_transitive".to_string(),
serde_json::json!(row.transitive_roots),
);
obj.insert(
"caller_root_total".to_string(),
serde_json::json!(top_roots.len()),
);
obj.insert(
"caller_superseded".to_string(),
serde_json::json!(superseded_here),
);
}
}
const TOP_ROOTS: usize = 8;
const CALLER_LINK_LIMIT: usize = TOP_ROOTS * 32;
fn push_if_unique(
entity: &serde_json::Value,
seen_uuids: &mut HashSet<String>,
combined: &mut Vec<serde_json::Value>,
) {
merge_hits(std::slice::from_ref(entity), seen_uuids, combined);
}
pub(crate) fn extract_subclass_names(extends_arr: &[serde_json::Value]) -> Vec<String> {
extends_arr
.iter()
.filter_map(|e| e.get("name").and_then(|v| v.as_str()).map(String::from))
.collect()
}
pub(crate) fn extract_implementer_names(implements_arr: &[serde_json::Value]) -> Vec<String> {
implements_arr
.iter()
.filter_map(|e| e.get("name").and_then(|v| v.as_str()).map(String::from))
.collect()
}
pub(crate) fn format_reference_samples(references_arr: &[serde_json::Value]) -> Vec<String> {
references_arr
.iter()
.take(3)
.map(|e| {
let name = e.get("name").and_then(|v| v.as_str()).unwrap_or("?");
let file = e.get("file_path").and_then(|v| v.as_str()).unwrap_or("?");
format!("{} in {}", name, file)
})
.collect()
}
pub(crate) fn enrich_single_entity(entity: &mut serde_json::Value, references: &serde_json::Value) {
if let Some(extends_arr) = references.get("extends").and_then(|v| v.as_array())
&& !extends_arr.is_empty()
{
let subclasses = extract_subclass_names(extends_arr);
if let Some(obj) = entity.as_object_mut() {
obj.insert("subclasses".to_string(), json!(subclasses));
}
}
if let Some(implements_arr) = references.get("implements").and_then(|v| v.as_array())
&& !implements_arr.is_empty()
{
let implementers = extract_implementer_names(implements_arr);
if let Some(obj) = entity.as_object_mut() {
obj.insert("implementers".to_string(), json!(implementers));
}
}
if let Some(references_arr) = references.get("references").and_then(|v| v.as_array())
&& !references_arr.is_empty()
{
let usage_count = references_arr.len();
let samples = format_reference_samples(references_arr);
if let Some(obj) = entity.as_object_mut() {
obj.insert("type_usage_count".to_string(), json!(usage_count));
obj.insert("type_usage_samples".to_string(), json!(samples));
}
}
if let Some(calls_arr) = references.get("calls").and_then(|v| v.as_array())
&& !calls_arr.is_empty()
{
let caller_count = calls_arr.len();
let samples = format_reference_samples(calls_arr);
if let Some(obj) = entity.as_object_mut() {
obj.insert("caller_count".to_string(), json!(caller_count));
obj.insert("caller_samples".to_string(), json!(samples));
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn resolve_max_results_clamps_above_ceiling() {
let resolved = resolve_max_results(10_000);
assert_eq!(resolved.value, MAX_RESULTS_CEILING);
assert_eq!(resolved.requested, 10_000);
assert!(resolved.was_clamped());
}
#[test]
fn resolve_max_results_preserves_values_within_bound() {
for n in [1, DEFAULT_MAX_RESULTS, 20, MAX_RESULTS_CEILING] {
let resolved = resolve_max_results(n);
assert_eq!(resolved.value, n);
assert!(!resolved.was_clamped());
assert!(resolved.notice().is_none());
}
}
#[test]
fn resolve_max_results_floors_at_one() {
let resolved = resolve_max_results(0);
assert_eq!(resolved.value, 1);
assert!(resolved.was_clamped());
}
#[test]
fn clamp_notice_states_bound_and_refine_rule() {
let notice = resolve_max_results(500).notice().expect("clamped");
assert!(notice.contains("500"));
assert!(notice.contains(MAX_RESULTS_CEILING.to_string().as_str()));
assert!(notice.contains("kinds"));
assert!(notice.contains("path"));
assert!(notice.contains("no pagination"));
}
#[test]
fn extract_subclass_names_empty() {
let refs = vec![];
let names = extract_subclass_names(&refs);
assert_eq!(names.len(), 0);
}
#[test]
fn test_extract_subclass_names_with_data() {
let refs = vec![
json!({"name": "ChildClass1", "kind": "class"}),
json!({"name": "ChildClass2", "kind": "class"}),
];
let names = extract_subclass_names(&refs);
assert_eq!(names.len(), 2);
assert!(names.contains(&"ChildClass1".to_string()));
assert!(names.contains(&"ChildClass2".to_string()));
}
#[test]
fn test_extract_implementer_names() {
let refs = vec![
json!({"name": "ImplClass1", "kind": "class"}),
json!({"name": "ImplClass2", "kind": "class"}),
];
let names = extract_implementer_names(&refs);
assert_eq!(names.len(), 2);
assert!(names.contains(&"ImplClass1".to_string()));
}
#[test]
fn test_format_reference_samples_limits_to_three() {
let refs = vec![
json!({"name": "usage1", "file_path": "file1.java"}),
json!({"name": "usage2", "file_path": "file2.java"}),
json!({"name": "usage3", "file_path": "file3.java"}),
json!({"name": "usage4", "file_path": "file4.java"}),
json!({"name": "usage5", "file_path": "file5.java"}),
];
let samples = format_reference_samples(&refs);
assert_eq!(samples.len(), 3);
assert!(samples[0].contains("usage1"));
assert!(samples[1].contains("usage2"));
assert!(samples[2].contains("usage3"));
}
#[test]
fn test_format_reference_samples() {
let refs = vec![json!({"name": "caller1", "file_path": "caller.java"})];
let samples = format_reference_samples(&refs);
assert_eq!(samples.len(), 1);
assert!(samples[0].contains("caller1"));
assert!(samples[0].contains("caller.java"));
}
#[test]
fn test_enrich_single_entity_with_subclasses() {
let mut entity = json!({"name": "MyClass", "kind": "class"});
let references = json!({
"extends": [
{"name": "Child1", "kind": "class"},
{"name": "Child2", "kind": "class"}
],
"implements": [],
"references": [],
"calls": []
});
enrich_single_entity(&mut entity, &references);
assert_eq!(
entity.get("subclasses"),
Some(&json!(vec!["Child1", "Child2"]))
);
}
#[test]
fn test_enrich_single_entity_with_all_relationships() {
let mut entity = json!({"name": "MyInterface"});
let references = json!({
"extends": [{"name": "Child1"}],
"implements": [{"name": "Impl1"}, {"name": "Impl2"}],
"references": [
{"name": "ref1", "file_path": "ref1.java"},
{"name": "ref2", "file_path": "ref2.java"}
],
"calls": [{"name": "caller1", "file_path": "caller.java"}]
});
enrich_single_entity(&mut entity, &references);
assert!(entity.get("subclasses").is_some());
assert!(entity.get("implementers").is_some());
assert!(entity.get("type_usage_count").is_some());
assert!(entity.get("caller_count").is_some());
}
#[test]
fn test_enrich_single_entity_ignores_empty_arrays() {
let mut entity = json!({"name": "MyClass"});
let references = json!({
"extends": [],
"implements": [],
"references": [],
"calls": []
});
enrich_single_entity(&mut entity, &references);
assert!(entity.get("subclasses").is_none());
assert!(entity.get("implementers").is_none());
assert!(entity.get("type_usage_count").is_none());
assert!(entity.get("caller_count").is_none());
}
}