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, KindScopeSearch, 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();
let rejected_prefix_uuids = 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,
scored_prefix_uuids: &rejected_prefix_uuids,
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));
strip_internal_fields(&mut combined);
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 scored_prefix_uuids: &'a [String],
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,
"cosine",
);
let non_code = crate::cli_tools::kinds::non_code_kinds();
if should_run_definition_channel(self.expanded_kinds) {
let definition_hits = self
.ctx
.vector_db
.search_excluding_kinds(KindScopeSearch {
vector: self.vector,
limit: self.candidate_limit,
repo_names: self.repo_names,
kinds: self.expanded_kinds,
exclude_kinds: &non_code,
})
.await
.unwrap_or_default();
merge_hits(
&definition_hits,
self.seen_uuids,
&mut vector_hits,
"definition",
);
}
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, "probe");
if !self.scored_prefix_uuids.is_empty() {
let scored_prefix = self
.ctx
.vector_db
.search_by_uuids(UuidProbe {
vector: self.vector,
uuids: self.scored_prefix_uuids,
repo_names: self.repo_names,
kinds: self.expanded_kinds,
limit: self.scored_prefix_uuids.len(),
})
.await
.unwrap_or_default();
merge_hits(&scored_prefix, self.seen_uuids, &mut vector_hits, "prefix");
}
let top_roots = seed_roots(&vector_hits, TOP_ROOTS, PROBE_ROOTS_MAX);
let bridge = CallerBridge {
vector: self.vector,
roots: &top_roots,
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, "bridge");
annotate_root_coverage(&mut vector_hits, &top_roots, self.repo_names, self.ctx).await;
vector_hits
}
}
pub(crate) const CHANNEL_FIELD: &str = "_channel";
fn strip_internal_fields(rows: &mut [serde_json::Value]) {
for row in rows.iter_mut() {
if let Some(obj) = row.as_object_mut() {
obj.remove(CHANNEL_FIELD);
}
}
}
fn merge_hits(
hits: &[serde_json::Value],
seen_uuids: &mut HashSet<String>,
pool: &mut Vec<serde_json::Value>,
channel: &'static str,
) {
for hit in hits {
if let Some(uuid) = hit.get("uuid").and_then(|v| v.as_str())
&& seen_uuids.insert(uuid.to_string())
{
let mut row = hit.clone();
if let Some(obj) = row.as_object_mut() {
obj.insert(CHANNEL_FIELD.to_string(), json!(channel));
}
pool.push(row);
}
}
}
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 should_run_definition_channel(user_kinds: &[String]) -> bool {
if user_kinds.is_empty() {
return true;
}
let any_user_kind = |non_code: bool| {
user_kinds
.iter()
.all(|k| crate::cli_tools::kinds::is_non_code_kind(k) == non_code)
};
!(any_user_kind(true) || any_user_kind(false))
}
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>,
) -> Vec<String> {
let mut rejected_uuids: Vec<String> = Vec::new();
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)
{
continue;
}
if crate::cli_tools::kinds::is_non_code_kind(kind) {
if let Some(uuid) = entity.get("uuid").and_then(|v| v.as_str())
&& !seen_uuids.contains(uuid)
{
rejected_uuids.push(uuid.to_string());
}
continue;
}
push_if_unique(entity, seen_uuids, combined);
}
}
rejected_uuids
}
const PROBE_RESULT_LIMIT: usize = 48;
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: PROBE_RESULT_LIMIT,
repo_names,
kinds: expanded_kinds,
})
.await
.unwrap_or_default()
}
pub(crate) struct CallerBridge<'a> {
pub vector: &'a [f32],
pub roots: &'a [String],
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> {
let direct_links = self
.ctx
.graph_db
.find_caller_links(self.roots, self.repo_names, CALLER_LINK_LIMIT)
.await
.unwrap_or_default();
if direct_links.is_empty() {
return Vec::new();
}
let mut caller_uuids: HashSet<String> = direct_links
.iter()
.map(|(caller, _)| caller.clone())
.collect();
let mut hits = self.fetch_callers(&caller_uuids, pool_cap).await;
if hits.len() < pool_cap {
let depth2_links = self
.ctx
.graph_db
.find_caller_links_depth2(self.roots, self.repo_names, CALLER_LINK_LIMIT_DEPTH2)
.await
.unwrap_or_default();
let before = caller_uuids.len();
for (caller, _) in depth2_links {
caller_uuids.insert(caller);
}
if caller_uuids.len() > before {
let mut depth2_hits = self
.fetch_callers(&caller_uuids, pool_cap - hits.len())
.await;
hits.append(&mut depth2_hits);
}
}
hits
}
async fn fetch_callers(
&self,
caller_uuids: &HashSet<String>,
limit: usize,
) -> Vec<serde_json::Value> {
if limit == 0 {
return Vec::new();
}
let visible: Vec<String> = caller_uuids
.iter()
.filter(|u| !self.seen_uuids.contains(*u))
.cloned()
.collect();
if visible.is_empty() {
return Vec::new();
}
let mut hits = self
.ctx
.vector_db
.search_by_uuids(UuidProbe {
vector: self.vector,
uuids: &visible,
repo_names: self.repo_names,
kinds: self.expanded_kinds,
limit,
})
.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
}
}
pub(crate) fn seed_roots(
rows: &[serde_json::Value],
top_roots: usize,
probe_max: usize,
) -> Vec<String> {
let mut seedable: Vec<(&str, f32, &str, i64, bool)> = rows
.iter()
.filter_map(|row| {
let uuid = row.get("uuid").and_then(|v| v.as_str())?;
let kind = row.get("kind").and_then(|v| v.as_str()).unwrap_or("");
let path = row.get("file_path").and_then(|v| v.as_str()).unwrap_or("");
if rank::kind_boost(kind) < 0.0 || rank::is_test_path(path) {
return None;
}
let cosine = row.get("score").and_then(|v| v.as_f64()).unwrap_or(0.0) as f32;
let line = row.get("start_line").and_then(|v| v.as_i64()).unwrap_or(0);
let probe = row.get(CHANNEL_FIELD).and_then(|v| v.as_str()) == Some("probe");
Some((uuid, cosine, path, line, probe))
})
.collect();
seedable.sort_by(|a, b| {
b.1.partial_cmp(&a.1)
.unwrap_or(std::cmp::Ordering::Equal)
.then_with(|| a.2.cmp(b.2))
.then_with(|| a.3.cmp(&b.3))
.then_with(|| a.0.cmp(b.0))
});
let mut roots: Vec<String> = Vec::new();
let mut probes = 0usize;
for (uuid, _, _, _, probe) in &seedable {
if roots.len() == top_roots {
break;
}
if *probe {
if probes >= probe_max {
continue;
}
probes += 1;
}
roots.push((*uuid).to_string());
}
roots
}
pub(crate) fn supersedes_caller(
caller_production: bool,
caller_direct: usize,
callee_direct: usize,
) -> bool {
caller_production && caller_direct >= 2 && caller_direct > callee_direct
}
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 supersedes_caller(
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(|| json!(row.fqn));
obj.insert("caller_roots".to_string(), json!(row.direct_roots));
obj.insert(
"caller_roots_transitive".to_string(),
json!(row.transitive_roots),
);
obj.insert("caller_root_total".to_string(), json!(top_roots.len()));
obj.insert("caller_out_degree".to_string(), json!(row.out_degree));
obj.insert("caller_superseded".to_string(), json!(superseded_here));
}
}
const TOP_ROOTS: usize = 8;
const PROBE_ROOTS_MAX: usize = 3;
const CALLER_LINK_LIMIT: usize = TOP_ROOTS * 32;
const CALLER_LINK_LIMIT_DEPTH2: usize = TOP_ROOTS * 16;
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, "prefix");
}
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 definition_channel_runs_without_kind_filter() {
assert!(should_run_definition_channel(&[]));
}
#[test]
fn definition_channel_runs_for_mixed_kind_filters() {
let mixed = vec!["rust_function".to_string(), "markdown_section".to_string()];
assert!(should_run_definition_channel(&mixed));
}
#[test]
fn definition_channel_skipped_for_docs_only_filters() {
let docs = vec![
"markdown_section".to_string(),
"markdown_document".to_string(),
];
assert!(!should_run_definition_channel(&docs));
let config = vec!["config_property".to_string()];
assert!(!should_run_definition_channel(&config));
}
#[test]
fn definition_channel_skipped_for_code_only_filters() {
let code = vec!["rust_function".to_string(), "method".to_string()];
assert!(!should_run_definition_channel(&code));
}
fn seed_fixture() -> Vec<serde_json::Value> {
let prose: Vec<serde_json::Value> = (0..6)
.map(|i| {
json!({"uuid": format!("prose{i}"), "name": "Purpose", "kind": "markdown_section",
"file_path": format!("docs/c{i}.md"), "start_line": 1, "score": 0.53 - f64::from(i) * 0.01,
"_channel": "cosine"})
})
.collect();
let code: Vec<serde_json::Value> = (0..4)
.map(|i| {
json!({"uuid": format!("code{i}"), "name": format!("helper{i}"), "kind": "rust_function",
"file_path": format!("src/g{i}.rs"), "start_line": 10 + i, "score": 0.38 - f64::from(i) * 0.02,
"_channel": "definition"})
})
.collect();
let probes: Vec<serde_json::Value> = (0..2)
.map(|i| {
json!({"uuid": format!("probe{i}"), "name": "find", "kind": "rust_method",
"fqn": format!("app::Things::find{i}"), "file_path": format!("src/f{i}.rs"),
"start_line": 5, "score": 0.40 - f64::from(i) * 0.05, "_channel": "probe"})
})
.collect();
vec![]
.into_iter()
.chain(prose)
.chain(code)
.chain(probes)
.chain(vec![
json!({"uuid": "testrow", "name": "test_login", "kind": "rust_function",
"file_path": "tests/login_test.rs", "start_line": 3, "score": 0.60,
"_channel": "cosine"}),
])
.collect()
}
#[test]
fn seed_roots_prefers_code_rows_over_prose() {
let rows = seed_fixture();
let roots = seed_roots(&rows, 8, 3);
assert!(!roots.iter().any(|u| u.starts_with("prose")), "{roots:?}");
assert!(!roots.contains(&"testrow".to_string()));
let code_count = roots.iter().filter(|u| u.starts_with("code")).count();
assert_eq!(
code_count, 4,
"all non-probe candidates seed first: {roots:?}"
);
let probe_count = roots.iter().filter(|u| u.starts_with("probe")).count();
assert_eq!(probe_count, 2);
}
#[test]
fn seed_roots_caps_probe_channel_rows() {
let mut rows = seed_fixture();
for i in 2..5 {
rows.push(
json!({"uuid": format!("probe{i}"), "name": "find", "kind": "rust_method",
"file_path": format!("src/f{i}.rs"), "start_line": 5,
"score": 0.42 - f64::from(i) * 0.01, "_channel": "probe"}),
);
}
let roots = seed_roots(&rows, 8, 3);
let probe_count = roots.iter().filter(|u| u.starts_with("probe")).count();
assert_eq!(
probe_count, PROBE_ROOTS_MAX,
"probe sub-cap violated: {roots:?}"
);
assert_eq!(roots.len(), PROBE_ROOTS_MAX + 4, "{roots:?}");
assert_eq!(roots.iter().filter(|u| u.starts_with("code")).count(), 4);
}
#[test]
fn seed_roots_deterministic_on_cosine_ties() {
let row = |uuid: &str, path: &str, line: i64| {
json!({"uuid": uuid, "name": "h", "kind": "rust_function", "file_path": path,
"start_line": line, "score": 0.5, "_channel": "cosine"})
};
let rows = vec![row("b", "src/a.rs", 1), row("a", "src/a.rs", 1)];
let roots = seed_roots(&rows, 4, 3);
assert_eq!(roots, vec!["a".to_string(), "b".to_string()]);
}
#[test]
fn provenance_moves_only_to_full_orchestrator_signatures() {
assert!(supersedes_caller(true, 3, 2));
assert!(
!supersedes_caller(true, 2, 2),
"equal coverage must not halve the entry point"
);
assert!(!supersedes_caller(true, 1, 2), "subset caller never wins");
assert!(
!supersedes_caller(true, 1, 0),
"1-root caller is not an orchestrator"
);
}
#[test]
fn provenance_ignores_test_callers() {
assert!(!supersedes_caller(false, 5, 2));
}
#[test]
fn prefix_prose_hits_do_not_take_leading_slots() {
let prefix_rows = json!([
{"uuid": "def", "name": "GetCallersAsync", "kind": "csharp_method",
"file_path": "src/QueryEngine.cs", "start_line": 3},
{"uuid": "webro", "name": "app-header", "kind": "html_element",
"file_path": "test_angular.html", "start_line": 1},
{"uuid": "prose", "name": "take screenshot", "kind": "markdown_section",
"fqn": "docs/tool-reference.md::… > take screenshot",
"file_path": "docs/tool-reference.md", "start_line": 12},
{"uuid": "cfg", "name": "screenshot.format", "kind": "config_property",
"file_path": "config.yaml", "start_line": 2},
]);
let mut seen = HashSet::new();
let mut combined = Vec::new();
let rejected = merge_prefix_hits(&prefix_rows, &[], None, &mut seen, &mut combined);
let names: Vec<&str> = combined
.iter()
.filter_map(|e| e.get("name").and_then(|v| v.as_str()))
.collect();
assert_eq!(
names.iter().position(|n| *n == "GetCallersAsync"),
Some(0),
"definition prefix hits keep their leading slot"
);
assert_eq!(
names.iter().position(|n| *n == "app-header"),
Some(1),
"web reference-target prefix hits keep their slot"
);
assert!(
names
.iter()
.all(|n| *n == "GetCallersAsync" || *n == "app-header"),
"no prose/config prefix row bypassed the ranker: {names:?}"
);
assert_eq!(rejected, vec!["prose".to_string(), "cfg".to_string()]);
assert!(
seen.contains("def"),
"leading slot rows are tracked for dedup"
);
assert!(!seen.contains("prose"));
assert!(
!seen.contains("cfg"),
"rejection leaves the dedup gate untouched"
);
}
#[test]
fn merge_hits_tags_rows_with_channel_and_dedups() {
let hits = vec![
json!({"uuid": "u1", "name": "a"}),
json!({"uuid": "u2", "name": "b"}),
];
let mut seen = HashSet::new();
let mut pool = Vec::new();
merge_hits(&hits, &mut seen, &mut pool, "cosine");
merge_hits(&hits, &mut seen, &mut pool, "probe");
assert_eq!(pool.len(), 2, "duplicate uuids must not re-enter the pool");
for row in &pool {
assert_eq!(
row.get(CHANNEL_FIELD).and_then(|v| v.as_str()),
Some("cosine")
);
}
}
#[test]
fn strip_internal_fields_removes_channel_marker() {
let mut rows = vec![
json!({"uuid": "u1", "name": "a", "_channel": "bridge"}),
json!([]), ];
strip_internal_fields(&mut rows);
assert!(
rows[0].get(CHANNEL_FIELD).is_none(),
"internal marker must not survive into output"
);
assert_eq!(rows[0]["uuid"], "u1");
assert!(rows[1].is_array());
}
#[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());
}
}