use serde_json::json;
use std::collections::HashSet;
use std::path::Path;
use super::SearchContext;
use super::coverage::{
CallerBridge, PROBE_ROOTS_MAX, TOP_ROOTS, annotate_root_coverage, seed_roots,
};
use super::rank;
use crate::db::vector::{ExactNameProbe, KindScopeSearch, UuidProbe, VectorSearchExt as _};
pub(crate) const CHANNEL_FIELD: &str = "_channel";
pub(crate) 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);
}
}
}
pub(super) 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);
}
}
}
pub(super) 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))
}
pub(crate) fn pool_window(max_results: usize, path_restricted: bool) -> usize {
const PATH_POOL_CEILING: usize = 600;
if path_restricted {
rank::candidate_limit(max_results)
.saturating_mul(3)
.min(PATH_POOL_CEILING)
} else {
rank::candidate_limit(max_results)
}
}
pub(crate) 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 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
}
}
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");
}
#[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 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());
}
}