use std::sync::Arc;
use crate::db::graph::{DEFAULT_MAX_TARGETS, GraphDb, QueryExt};
use crate::models::RepoScope;
use crate::cli_tools::json_target_name;
use crate::cli_tools::append_signature_if_present;
use crate::cli_tools::compact_signature;
use crate::cli_tools::format_file_line;
use crate::cli_tools::resolution::{ResolutionView, overload_label};
use crate::cli_tools::search_hybrid_context::enrich::is_test_reference;
use std::collections::{BTreeSet, HashSet};
const MODULE_ENTITY: &str = "<module>";
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct CallersFormat {
pub include_tests: bool,
}
pub async fn run_find_callers(
entity_name: &str,
repo: &RepoScope,
graph_db: &Arc<GraphDb>,
max_targets: Option<usize>,
kinds: Option<&str>,
) -> anyhow::Result<serde_json::Value> {
let repo_names = repo.filter_names();
let max_targets = max_targets.unwrap_or(DEFAULT_MAX_TARGETS);
let references = graph_db
.find_references(entity_name, &repo_names, max_targets, kinds)
.await?;
Ok(references)
}
const REL_TYPES: &[(&str, &str)] = &[
("calls", "Calls (function/method invocations)"),
("extends", "Extends (class inheritance)"),
("implements", "Implements (interface implementation)"),
("references", "References (type annotations/usages)"),
("macro_calls", "Macro calls (macro invocations)"),
("references_dom", "DOM references (JS → HTML element id)"),
("uses_css_class", "CSS class usage (JS → CSS class)"),
("imports_script", "Script imports (HTML → JS file)"),
("imports_stylesheet", "Stylesheet imports (HTML → CSS file)"),
("uses_backend", "Backend usage (VCL)"),
("uses_probe", "Probe usage (VCL)"),
("uses_acl", "ACL usage (VCL)"),
("includes", "File includes (VCL)"),
("imports_vmod", "VMOD imports (VCL)"),
("declared_unused", "Declared unused (VCL)"),
("routes_to", "HTTP routes (endpoint → handler)"),
("overridden_by", "Overridden by (method implementations)"),
("overrides", "Overrides (declared supertype methods)"),
(
"dispatched_calls",
"Dispatched calls (bound to an override or supertype method)",
),
(
"http_calls",
"HTTP callers (heuristic: client call → endpoint)",
),
];
pub fn format_references_result(entity_name: &str, references: &serde_json::Value) -> String {
format_references_result_with(entity_name, references, CallersFormat::default())
}
pub fn format_references_result_with(
entity_name: &str,
references: &serde_json::Value,
format: CallersFormat,
) -> String {
let mut output = format!("# References to `{}`\n\n", entity_name);
output.push_str(&format_resolution_markdown(references));
let rel_types = REL_TYPES;
let total_refs: usize = rel_types
.iter()
.filter_map(|(key, _)| references.get(key).and_then(|v| v.as_array()))
.map(|arr| arr.len())
.sum();
if total_refs == 0 {
match ResolutionView::from_references(references) {
Some(view) if view.count() > 0 || view.total_targets() > 0 => {
output.push_str(&format!(
"No references found for `{}`. This entity may be unused.\n",
entity_name
))
}
Some(view) if !view.overload_notice(true).is_empty() => {
output.push_str(&view.overload_notice(true));
output.push('\n');
}
Some(view) if view.hidden_non_code() > 0 => output.push_str(&format!(
"No code entity matched `{}` — see the disclosure above; the name only \
hit documentation/config/build metadata.\n",
entity_name
)),
Some(_) => output.push_str(&format!(
"No entity named `{}` was found in the indexed scope. \
Check the spelling, the repository scope (`--repo`), or search \
semantically with `search_hybrid_context` first.\n",
entity_name
)),
None => output.push_str(&format!(
"No references found for `{}`. This entity may be unused.\n",
entity_name
)),
}
return output;
}
let single_repo = single_repo(references, rel_types);
output.push_str(&found_line(
references,
total_refs,
single_repo.as_deref(),
format,
));
let style = RowStyle {
label_repos: single_repo.is_none(),
include_tests: format.include_tests,
};
let mut multiple_targets = false;
let mut overloaded = std::collections::HashSet::new();
if let Some(view) = ResolutionView::from_references(references) {
multiple_targets = view.count() > 1 || view.total_targets() > 1;
overloaded = view.overloaded_fqns();
let caveat = view.partial_counts_caveat();
if !caveat.is_empty() {
output.push_str(&format!("> **{}**\n", caveat));
output.push_str("> Re-run with a fully qualified name, or raise `max_targets`, for the complete set.\n\n");
}
}
for &(key, label) in rel_types {
if let Some(arr) = references.get(key).and_then(|v| v.as_array())
&& !arr.is_empty()
{
output.push_str(&format!("## {} ({})\n\n", label, arr.len()));
output.push_str(&format_relationship_bucket(
entity_name,
arr,
multiple_targets || matches!(key, "dispatched_calls" | "http_calls"),
&overloaded,
style,
));
}
}
output
}
fn found_line(
references: &serde_json::Value,
total_refs: usize,
single_repo: Option<&str>,
format: CallersFormat,
) -> String {
let repo_label = single_repo
.map(|repo| format!(" (repo: {repo})"))
.unwrap_or_default();
let tests = REL_TYPES
.iter()
.filter_map(|(key, _)| references.get(key).and_then(|v| v.as_array()))
.flatten()
.filter(|row| is_test_reference(row))
.count();
let tests_note = if tests > 0 && !format.include_tests {
format!(" — {tests} in tests, counted but not listed (`include_tests` lists them)")
} else {
String::new()
};
format!(
"Found {total_refs} reference(s) across all relationship types{repo_label}{tests_note}:\n\n"
)
}
fn format_resolution_markdown(references: &serde_json::Value) -> String {
let Some(view) = ResolutionView::from_references(references) else {
return String::new();
};
let mut output = format!("{}:\n", view.summary());
output.push_str(&view.target_bullets());
output.push('\n');
if view.is_fuzzy() {
output.push_str(&format!(
"> **Fuzzy match** — no entity matched `{}` exactly. The {} target(s) below were\n\
> found by substring match and may be unrelated. Re-run with an exact name or a\n\
> fully qualified name (e.g. `Namespace.Type.Member`) for precise results.\n\n",
view.query(),
view.count()
));
}
if view.is_truncated() {
output.push_str(&format!(
"> **Truncated** — {} targets matched; showing the first {} by FQN.\n\n",
view.total_targets(),
view.count()
));
}
let hidden = view.hidden_notice(true);
if !hidden.is_empty() {
output.push_str(&format!("> {hidden}\n\n"));
}
if view.count() == 0 && view.kind_filter() == "explicit" {
output.push_str(
"> Scope: an explicit `kinds` allow-list was applied; empty resolution means no \
matching entity of those kinds exists in scope.\n\n",
);
}
output
}
fn format_relationship_bucket(
entity_name: &str,
arr: &[serde_json::Value],
multiple_targets: bool,
overloaded: &HashSet<&str>,
style: RowStyle,
) -> String {
use std::collections::BTreeMap;
let mut grouped: BTreeMap<Option<String>, Vec<&serde_json::Value>> = BTreeMap::new();
for entity in arr {
grouped
.entry(target_group_key(entity))
.or_default()
.push(entity);
}
let show_targets = grouped.len() > 1 || multiple_targets;
let mut output = String::new();
for (target_key, entities) in grouped {
if let Some(target_key) = target_key.filter(|_| show_targets) {
output.push_str(&format_target_header(
entities[0],
entity_name,
&target_key,
overloaded,
style,
));
}
output.push_str(&format_group_rows(&entities, style));
output.push('\n');
}
output
}
#[derive(Debug, Clone, Copy)]
struct RowStyle {
label_repos: bool,
include_tests: bool,
}
fn format_group_rows(entities: &[&serde_json::Value], style: RowStyle) -> String {
let files_with_rows: HashSet<&str> = entities
.iter()
.filter(|e| !is_module(e))
.filter_map(|e| file_of(e))
.collect();
let (folded, kept): (Vec<&serde_json::Value>, Vec<&serde_json::Value>) = entities
.iter()
.partition(|e| is_module(e) && file_of(e).is_some_and(|f| files_with_rows.contains(f)));
let (listed, tests): (Vec<&serde_json::Value>, Vec<&serde_json::Value>) = kept
.into_iter()
.partition(|e| style.include_tests || !is_test_reference(e));
let mut output: String = listed
.iter()
.map(|e| format_reference_row(e, style.label_repos))
.collect();
let mut notes = Vec::new();
if !tests.is_empty() {
let more = if listed.is_empty() { "" } else { "+" };
notes.push(format!(
"{more}{} in tests (`include_tests` lists them)",
tests.len()
));
}
if !folded.is_empty() {
notes.push(format!(
"{} import row(s) folded into the rows of their file",
folded.len()
));
}
if !notes.is_empty() {
output.push_str(&format!("- {}\n", notes.join("; ")));
}
output
}
fn file_of(entity: &serde_json::Value) -> Option<&str> {
entity.get("file_path").and_then(|v| v.as_str())
}
fn is_module(entity: &serde_json::Value) -> bool {
entity.get("name").and_then(|v| v.as_str()) == Some(MODULE_ENTITY)
}
fn format_reference_row(entity: &serde_json::Value, label_repo: bool) -> String {
let name = entity.get("name").and_then(|v| v.as_str()).unwrap_or("?");
let mut row = match entity.get("kind").and_then(|v| v.as_str()) {
Some(kind) => format!("- **`{name}`** ({kind})"),
None => format!("- **`{name}`**"),
};
if let Some(file_path) = entity.get("file_path").and_then(|v| v.as_str()) {
let path = match entity.get("start_line").and_then(|v| v.as_i64()) {
Some(start_line) => format!("{file_path}:{start_line}"),
None => file_path.to_string(),
};
let repo = entity
.get("repo_name")
.and_then(|v| v.as_str())
.filter(|_| label_repo);
row.push_str(" at ");
row.push_str(&format_file_line(&path, repo));
}
if let Some(signature) = entity
.get("signature")
.and_then(|v| v.as_str())
.and_then(compact_signature)
{
row.push_str(&format!(" — `{signature}`"));
}
row.push('\n');
row
}
fn single_repo(references: &serde_json::Value, rel_types: &[(&str, &str)]) -> Option<String> {
let rows = rel_types
.iter()
.filter_map(|(key, _)| references.get(key).and_then(|v| v.as_array()))
.flatten();
let row_repos = rows.flat_map(|row| {
["repo_name", "target_repo_name"]
.into_iter()
.filter_map(move |field| row.get(field).and_then(|v| v.as_str()))
});
let target_repos = references
.pointer("/resolution/targets")
.and_then(|v| v.as_array())
.into_iter()
.flatten()
.filter_map(|target| target.get("repo_name").and_then(|v| v.as_str()));
let repos: BTreeSet<&str> = row_repos
.chain(target_repos)
.filter(|repo| !repo.is_empty())
.collect();
let mut repos = repos.into_iter();
match (repos.next(), repos.next()) {
(Some(repo), None) => Some(repo.to_string()),
_ => None,
}
}
fn format_target_header(
first_entity: &serde_json::Value,
entity_name: &str,
target_key: &str,
overloaded: &HashSet<&str>,
style: RowStyle,
) -> String {
let target_name = overload_label(
&json_target_name(first_entity, entity_name),
first_entity
.get("target_name")
.and_then(|v| v.as_str())
.unwrap_or(""),
first_entity
.get("target_signature")
.and_then(|v| v.as_str()),
overloaded,
);
let target_repo = first_entity
.get("target_repo_name")
.and_then(|v| v.as_str())
.filter(|_| style.label_repos);
let mut output = format!(
"### Target: `{}` at {}\n\n",
target_name,
format_file_line(target_key, target_repo)
);
if let Some(target_sig) = first_entity
.get("target_signature")
.and_then(|v| v.as_str())
.and_then(compact_signature)
{
output.push_str(&format!("Signature: `{}`\n\n", target_sig));
}
output
}
fn target_group_key(entity: &serde_json::Value) -> Option<String> {
let target_file = entity
.get("target_file_path")
.and_then(|v| v.as_str())
.filter(|s| !s.is_empty())?;
Some(
match entity.get("target_start_line").and_then(|v| v.as_i64()) {
Some(target_line) => format!("{}:{}", target_file, target_line),
None => target_file.to_string(),
},
)
}
pub fn format_reference_entry(entity: &serde_json::Value) -> String {
let mut output = String::new();
if let Some(name) = entity.get("name").and_then(|v| v.as_str()) {
if let Some(kind) = entity.get("kind").and_then(|v| v.as_str()) {
output.push_str(&format!("- **`{}`** ({})", name, kind));
} else {
output.push_str(&format!("- **`{}`**", name));
}
}
let repo = entity.get("repo_name").and_then(|v| v.as_str());
if let Some(file_path) = entity.get("file_path").and_then(|v| v.as_str()) {
let path = match entity.get("start_line").and_then(|v| v.as_i64()) {
Some(start_line) => format!("{}:{}", file_path, start_line),
None => file_path.to_string(),
};
output.push_str(" at ");
output.push_str(&format_file_line(&path, repo));
}
output.push('\n');
append_signature_if_present(&mut output, entity);
output.push('\n');
output
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn row(name: &str, kind: &str, file: &str, line: i64, repo: &str) -> serde_json::Value {
json!({
"name": name, "kind": kind, "file_path": file, "start_line": line,
"repo_name": repo, "target_repo_name": repo,
"target_fqn": "com.x.Ledger.post", "target_file_path": "src/Ledger.java",
"target_start_line": 3
})
}
fn ledger_references(calls: Vec<serde_json::Value>) -> serde_json::Value {
json!({
"calls": calls,
"resolution": {
"query": "Ledger.post", "tier": "exact_fqn", "fuzzy": false, "truncated": false,
"total_targets": 1,
"targets": [{"name": "post", "fqn": "com.x.Ledger.post", "kind": "method",
"file_path": "src/Ledger.java", "start_line": 3, "repo_name": "shop"}]
}
})
}
#[test]
fn test_callers_are_counted_and_listed_only_on_request() {
let mut test_row = row(
"postsEntry",
"method",
"src/test/LedgerTest.java",
9,
"shop",
);
let mut rust_test = row("inline_case", "rust_function", "src/ledger.rs", 40, "shop");
rust_test["is_test_context"] = json!(true);
test_row["signature"] = json!("()");
let references = ledger_references(vec![
row("bill", "method", "src/Invoicer.java", 12, "shop"),
test_row,
rust_test,
]);
let compact = format_references_result("Ledger.post", &references);
assert!(compact.contains("## Calls (function/method invocations) (3)"));
assert!(compact.contains("- **`bill`** (method) at `src/Invoicer.java:12`\n"));
assert!(!compact.contains("postsEntry"));
assert!(!compact.contains("inline_case"));
assert!(compact.contains("- +2 in tests (`include_tests` lists them)\n"));
assert!(compact.contains(
"Found 3 reference(s) across all relationship types (repo: shop) — 2 in tests"
));
let full = format_references_result_with(
"Ledger.post",
&references,
CallersFormat {
include_tests: true,
},
);
assert!(full.contains("postsEntry") && full.contains("inline_case"));
assert!(!full.contains("in tests"));
}
#[test]
fn test_callers_only_in_tests_have_no_plus_sign() {
let references = ledger_references(vec![row(
"postsEntry",
"method",
"src/test/LedgerTest.java",
9,
"shop",
)]);
let formatted = format_references_result("Ledger.post", &references);
assert!(formatted.contains("- 1 in tests (`include_tests` lists them)\n"));
}
#[test]
fn test_single_repository_is_named_once() {
let references = ledger_references(vec![
row("bill", "method", "src/Invoicer.java", 12, "shop"),
row("refund", "method", "src/Refunder.java", 8, "shop"),
]);
let formatted = format_references_result("Ledger.post", &references);
let rows: Vec<&str> = formatted
.lines()
.filter(|l| l.starts_with("- **`"))
.collect();
assert_eq!(rows.len(), 2);
assert!(rows.iter().all(|r| !r.contains("(repo: ")));
assert!(formatted.contains("across all relationship types (repo: shop):"));
assert!(formatted.contains("`src/Invoicer.java:12`\n- **`refund`**"));
}
#[test]
fn test_several_repositories_label_every_row() {
let references = ledger_references(vec![
row("bill", "method", "src/Invoicer.java", 12, "shop"),
row("audit", "method", "src/Audit.java", 4, "audit"),
]);
let formatted = format_references_result("Ledger.post", &references);
assert!(formatted.contains("at `src/Invoicer.java:12` (repo: shop)"));
assert!(formatted.contains("at `src/Audit.java:4` (repo: audit)"));
assert!(formatted.contains("across all relationship types:"));
}
#[test]
fn test_import_rows_fold_into_their_file() {
let references = ledger_references(vec![
row("<module>", "function", "src/Invoicer.java", 1, "shop"),
row("Invoicer", "class", "src/Invoicer.java", 5, "shop"),
row("<module>", "function", "src/Unused.java", 1, "shop"),
]);
let formatted = format_references_result("Ledger.post", &references);
assert!(!formatted.contains("`<module>`** (function) at `src/Invoicer.java:1`"));
assert!(formatted.contains("`<module>`** (function) at `src/Unused.java:1`"));
assert!(formatted.contains("- 1 import row(s) folded into the rows of their file\n"));
}
#[test]
fn test_signature_is_on_the_row_and_empty_ones_are_dropped() {
let mut with_sig = row("bill", "method", "src/Invoicer.java", 12, "shop");
with_sig["signature"] = json!("public void bill(\n String id\n)");
let mut empty_sig = row("run", "method", "src/Job.java", 3, "shop");
empty_sig["signature"] = json!("()");
let formatted =
format_references_result("Ledger.post", &ledger_references(vec![with_sig, empty_sig]));
assert!(formatted.contains("at `src/Invoicer.java:12` — `public void bill(String id)`\n"));
assert!(formatted.contains("at `src/Job.java:3`\n"));
assert!(!formatted.contains("Signature: `()`"));
}
#[test]
fn test_format_references_result_empty() {
let references = json!({
"calls": [],
"extends": [],
"implements": [],
"references": []
});
let formatted = format_references_result("MyEntity", &references);
assert!(formatted.contains("No references found"));
}
#[test]
fn test_format_references_result_with_data() {
let references = json!({
"calls": [
{
"name": "caller1",
"kind": "method",
"file_path": "file1.java",
"start_line": 10,
"signature": "void caller1()"
}
],
"extends": [],
"implements": [],
"references": []
});
let formatted = format_references_result("MyEntity", &references);
assert!(formatted.contains("caller1"));
assert!(formatted.contains("file1.java:10"));
}
#[test]
fn test_format_references_result_with_multiple_relationship_types() {
let references = json!({
"calls": [{"name": "caller1", "kind": "method", "file_path": "file1.java", "start_line": 10}],
"extends": [{"name": "ChildClass", "kind": "class", "file_path": "file2.java", "start_line": 20}],
"implements": [{"name": "ImplClass", "kind": "class", "file_path": "file3.java", "start_line": 30}],
"references": [{"name": "refUser", "kind": "method", "file_path": "file4.java", "start_line": 40}]
});
let formatted = format_references_result("MyEntity", &references);
assert!(formatted.contains("Found 4 reference(s)"));
assert!(formatted.contains("Calls (function/method invocations)"));
assert!(formatted.contains("Extends (class inheritance)"));
assert!(formatted.contains("Implements (interface implementation)"));
assert!(formatted.contains("References (type annotations/usages)"));
}
#[test]
fn test_format_reference_entry_complete() {
let entity = json!({
"name": "myMethod",
"kind": "method",
"file_path": "src/Handler.java",
"start_line": 42,
"signature": "public void myMethod() throws Exception"
});
let formatted = format_reference_entry(&entity);
assert!(formatted.contains("myMethod"));
assert!(formatted.contains("method"));
assert!(formatted.contains("src/Handler.java:42"));
assert!(formatted.contains("public void myMethod() throws Exception"));
}
#[test]
fn test_format_reference_entry_without_line_number() {
let entity = json!({
"name": "myMethod",
"kind": "method",
"file_path": "src/Handler.java"
});
let formatted = format_reference_entry(&entity);
assert!(formatted.contains("myMethod"));
assert!(formatted.contains("src/Handler.java"));
assert!(!formatted.contains(":"));
}
#[test]
fn test_format_reference_entry_without_kind() {
let entity = json!({
"name": "UnknownEntity",
"file_path": "src/Unknown.java",
"start_line": 50
});
let formatted = format_reference_entry(&entity);
assert!(formatted.contains("UnknownEntity"));
assert!(formatted.contains("src/Unknown.java:50"));
}
#[test]
fn format_reference_entry_appends_repo_annotation() {
let entity = json!({
"name": "caller1",
"kind": "method",
"file_path": "file1.java",
"start_line": 10,
"repo_name": "alpha"
});
let formatted = format_reference_entry(&entity);
assert!(formatted.contains("file1.java:10"), "got {formatted}");
assert!(formatted.contains("(repo: alpha)"), "got {formatted}");
}
#[test]
fn format_reference_entry_without_repo_omits_annotation() {
let entity = json!({
"name": "caller1",
"kind": "method",
"file_path": "file1.java",
"start_line": 10
});
let formatted = format_reference_entry(&entity);
assert!(!formatted.contains("(repo:"), "got {formatted}");
}
#[test]
fn format_reference_entry_with_empty_repo_omits_annotation() {
let entity = json!({
"name": "caller1",
"kind": "method",
"file_path": "file1.java",
"start_line": 10,
"repo_name": ""
});
let formatted = format_reference_entry(&entity);
assert!(!formatted.contains("(repo:"), "got {formatted}");
}
#[test]
fn target_header_labels_target_repo() {
let references = json!({
"calls": [
{
"name": "caller1", "kind": "function",
"file_path": "a.rs", "start_line": 1,
"target_name": "find_me",
"target_file_path": "orphans.rs", "target_start_line": 92,
"repo_name": "alpha", "target_repo_name": "beta"
},
{
"name": "caller2", "kind": "function",
"file_path": "b.rs", "start_line": 2,
"target_name": "find_me",
"target_file_path": "rust.rs", "target_start_line": 445,
"repo_name": "alpha", "target_repo_name": "gamma"
}
],
"extends": [],
"implements": [],
"references": []
});
let formatted = format_references_result("find_me", &references);
assert!(formatted.contains("### Target:"));
assert!(formatted.contains("(repo: beta)"), "got {formatted}");
assert!(formatted.contains("(repo: gamma)"), "got {formatted}");
}
#[test]
fn test_format_references_result_only_extends() {
let references = json!({
"calls": [],
"extends": [
{"name": "ChildClass1", "kind": "class", "file_path": "file1.java", "start_line": 10},
{"name": "ChildClass2", "kind": "class", "file_path": "file2.java", "start_line": 20}
],
"implements": [],
"references": []
});
let formatted = format_references_result("BaseClass", &references);
assert!(formatted.contains("Found 2 reference(s)"));
assert!(formatted.contains("Extends (class inheritance) (2)"));
assert!(!formatted.contains("Calls (function/method invocations)"));
}
#[test]
fn test_format_references_result_dead_code() {
let references = json!({
"calls": [],
"extends": [],
"implements": [],
"references": []
});
let formatted = format_references_result("UnusedMethod", &references);
assert!(formatted.contains("No references found"));
assert!(formatted.contains("This entity may be unused"));
}
#[test]
fn test_format_references_result_multiple_targets_same_name() {
let references = json!({
"calls": [
{
"name": "caller1",
"kind": "function",
"file_path": "src/parser/orphans.rs",
"start_line": 8,
"target_name": "find_nearest_entity_by_line",
"target_file_path": "src/parser/orphans.rs",
"target_start_line": 92,
"target_signature": "pub(crate) fn find_nearest_entity_by_line(entities: &[ParsedEntity], target_line: usize) -> usize"
},
{
"name": "caller2",
"kind": "function",
"file_path": "src/parser/languages/rust.rs",
"start_line": 258,
"target_name": "find_nearest_entity_by_line",
"target_file_path": "src/parser/languages/rust.rs",
"target_start_line": 445,
"target_signature": "fn find_nearest_entity_by_line(entities: &[ParsedEntity], line: usize) -> usize"
},
{
"name": "caller3",
"kind": "function",
"file_path": "src/parser/orphans.rs",
"start_line": 175,
"target_name": "find_nearest_entity_by_line",
"target_file_path": "src/parser/orphans.rs",
"target_start_line": 92,
"target_signature": "pub(crate) fn find_nearest_entity_by_line(entities: &[ParsedEntity], target_line: usize) -> usize"
}
],
"extends": [],
"implements": [],
"references": []
});
let formatted = format_references_result("find_nearest_entity_by_line", &references);
assert!(formatted.contains("Found 3 reference(s)"));
assert!(formatted.contains("### Target:"));
assert!(formatted.contains("src/parser/orphans.rs:92"));
assert!(formatted.contains("src/parser/languages/rust.rs:445"));
assert!(formatted.contains("pub(crate) fn find_nearest_entity_by_line"));
assert!(formatted.contains("fn find_nearest_entity_by_line"));
assert!(formatted.contains("caller1"));
assert!(formatted.contains("caller2"));
assert!(formatted.contains("caller3"));
}
#[test]
fn test_format_references_result_target_order_is_deterministic() {
let references = json!({
"calls": [
{
"name": "caller_z", "kind": "function",
"file_path": "src/z.rs", "start_line": 1,
"target_name": "shared", "target_file_path": "src/zeta.rs",
"target_start_line": 20
},
{
"name": "caller_a", "kind": "function",
"file_path": "src/a.rs", "start_line": 1,
"target_name": "shared", "target_file_path": "src/alpha.rs",
"target_start_line": 5
},
{
"name": "caller_m", "kind": "function",
"file_path": "src/m.rs", "start_line": 1,
"target_name": "shared", "target_file_path": "src/mu.rs",
"target_start_line": 99
}
],
"extends": [],
"implements": [],
"references": []
});
let formatted = format_references_result("shared", &references);
let alpha = formatted
.find("src/alpha.rs:5")
.expect("alpha target present");
let mu = formatted.find("src/mu.rs:99").expect("mu target present");
let zeta = formatted
.find("src/zeta.rs:20")
.expect("zeta target present");
assert!(
alpha < mu && mu < zeta,
"targets must render sorted by file:line, not in map order"
);
}
#[test]
fn test_format_references_result_renders_override_buckets() {
let references = json!({
"calls": [],
"extends": [],
"implements": [],
"references": [],
"overridden_by": [
{"name": "Session.getUniqueId", "kind": "groovy_method",
"file_path": "Session.groovy", "start_line": 26}
],
"overrides": [
{"name": "ISession.getUniqueId", "kind": "groovy_method",
"file_path": "ISession.groovy", "start_line": 3}
]
});
let formatted = format_references_result("getUniqueId", &references);
assert!(formatted.contains("Found 2 reference(s)"));
assert!(formatted.contains("Overridden by (method implementations)"));
assert!(formatted.contains("Overrides (declared supertype methods)"));
assert!(formatted.contains("Session.getUniqueId"));
assert!(formatted.contains("ISession.getUniqueId"));
}
#[test]
fn test_format_references_result_dispatched_calls_name_bound_method() {
let references = json!({
"calls": [],
"dispatched_calls": [
{"name": "options", "kind": "method",
"file_path": "src/web/LookupController.java", "start_line": 12,
"target_name": "listOptions",
"target_fqn": "com.acme.DefaultLookupService.listOptions",
"target_file_path": "src/service/DefaultLookupService.java",
"target_start_line": 8}
],
"resolution": {
"query": "LookupService.listOptions",
"tier": "fqn_suffix",
"fuzzy": false,
"truncated": false,
"total_targets": 1,
"targets": [{"fqn": "com.acme.LookupService.listOptions"}]
}
});
let formatted = format_references_result("LookupService.listOptions", &references);
assert!(formatted.contains("Found 1 reference(s)"));
assert!(!formatted.contains("may be unused"));
assert!(formatted.contains("Dispatched calls (bound to an override or supertype method)"));
assert!(
formatted.contains("### Target: `com.acme.DefaultLookupService.listOptions`"),
"the bound method must be named:\n{formatted}"
);
assert!(formatted.contains("**`options`**"));
}
#[test]
fn test_format_references_result_single_target_no_grouping() {
let references = json!({
"calls": [
{
"name": "caller1",
"kind": "method",
"file_path": "file1.java",
"start_line": 10,
"target_name": "myMethod",
"target_file_path": "src/Handler.java",
"target_start_line": 42,
"target_signature": "public void myMethod()"
},
{
"name": "caller2",
"kind": "method",
"file_path": "file2.java",
"start_line": 20,
"target_name": "myMethod",
"target_file_path": "src/Handler.java",
"target_start_line": 42,
"target_signature": "public void myMethod()"
}
],
"extends": [],
"implements": [],
"references": []
});
let formatted = format_references_result("myMethod", &references);
assert!(formatted.contains("Found 2 reference(s)"));
assert!(!formatted.contains("### Target:"));
assert!(formatted.contains("caller1"));
assert!(formatted.contains("caller2"));
}
#[test]
fn test_format_renders_resolution_header() {
let references = json!({
"calls": [{"name": "caller1", "kind": "method", "file_path": "file1.java", "start_line": 10}],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "Off",
"tier": "exact_name",
"fuzzy": false,
"truncated": false,
"targets": [
{
"uuid": "uuid-123",
"name": "Off",
"fqn": "OpenLogi.Core.Gestures.GestureOwner.Off",
"kind": "csharp_record",
"file_path": "src/OpenLogi.Core/Gestures/GestureOwner.cs",
"start_line": 15
}
]
}
});
let formatted = format_references_result("Off", &references);
assert!(formatted.contains("Resolved to 1 target by exact name match:"));
assert!(formatted.contains("OpenLogi.Core.Gestures.GestureOwner.Off"));
assert!(formatted.contains("csharp_record"));
assert!(formatted.contains("src/OpenLogi.Core/Gestures/GestureOwner.cs:15"));
}
#[test]
fn test_format_renders_fuzzy_warning() {
let references = json!({
"calls": [{"name": "caller1", "kind": "method", "file_path": "file1.java", "start_line": 10}],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "Offlin",
"tier": "fuzzy",
"fuzzy": true,
"truncated": false,
"targets": [
{
"uuid": "uuid-123",
"name": "OfflineSlot",
"fqn": "OpenLogi.Tests.Hid.InventoryDedupeTests.OfflineSlot",
"kind": "csharp_method",
"file_path": "src/OpenLogi.Tests/Hid/InventoryDedupeTests.cs",
"start_line": 20
}
]
}
});
let formatted = format_references_result("Offlin", &references);
assert!(formatted.contains("**Fuzzy match**"));
assert!(formatted.contains("no entity matched `Offlin` exactly."));
}
#[test]
fn test_format_renders_truncation_notice() {
let references = json!({
"calls": [{"name": "caller1", "kind": "method", "file_path": "file1.java", "start_line": 10}],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "DuplicateName",
"tier": "exact_name",
"fuzzy": false,
"truncated": true,
"total_targets": 112,
"targets": [
{
"uuid": "uuid-123",
"name": "DuplicateName",
"fqn": "Some.Namespace.DuplicateName",
"kind": "class",
"file_path": "src/Duplicate.java",
"start_line": 10
}
]
}
});
let formatted = format_references_result("DuplicateName", &references);
assert!(
formatted.contains("**Truncated** — 112 targets matched; showing the first 1 by FQN.")
);
}
#[test]
fn test_format_without_resolution_key_is_unchanged() {
let references = json!({
"calls": [{"name": "caller1", "kind": "method", "file_path": "file1.java", "start_line": 10}],
"extends": [],
"implements": [],
"references": []
});
let formatted = format_references_result("myMethod", &references);
let expected = "# References to `myMethod`\n\n\
Found 1 reference(s) across all relationship types:\n\n\
## Calls (function/method invocations) (1)\n\n\
- **`caller1`** (method) at `file1.java:10`\n\n";
assert_eq!(formatted, expected);
}
fn truncated_resolution_with_21_callers() -> serde_json::Value {
let calls: Vec<serde_json::Value> = (0..21)
.map(|i| {
json!({
"name": format!("caller{}", i),
"kind": "function",
"file_path": format!("src/caller_{}.rs", i),
"start_line": i,
})
})
.collect();
json!({
"calls": calls,
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "delete",
"tier": "exact_name",
"fuzzy": false,
"truncated": true,
"total_targets": 112,
"targets": [
{
"uuid": "uuid-1",
"name": "delete",
"fqn": "repo::module::delete",
"kind": "method",
"file_path": "src/target.rs",
"start_line": 1
}
]
}
})
}
#[test]
fn format_partial_counts_caveat_is_empty_when_not_truncated() {
let bare = json!({
"calls": [{"name": "caller1", "kind": "method", "file_path": "f.rs", "start_line": 1}],
"extends": [],
"implements": [],
"references": []
});
let view = ResolutionView::from_references(&bare);
if let Some(view) = view {
assert_eq!(view.partial_counts_caveat(), "");
}
let complete = json!({
"resolution": {
"tier": "exact_name",
"truncated": false,
"total_targets": 3,
"targets": [{"fqn": "A"}, {"fqn": "B"}, {"fqn": "C"}]
}
});
let view = ResolutionView::from_references(&complete).expect("resolution");
assert_eq!(view.partial_counts_caveat(), "");
}
#[test]
fn format_partial_counts_caveat_uses_true_total_not_sample_size() {
let references = json!({
"resolution": {
"tier": "exact_name",
"truncated": true,
"total_targets": 112,
"targets": [{"fqn": "A"}]
}
});
let view = ResolutionView::from_references(&references).expect("resolution");
assert_eq!(
view.partial_counts_caveat(),
"Counts below are partial — they cover only the 1 of 112 targets shown."
);
}
#[test]
fn format_renders_partial_counts_caveat_when_targets_truncated() {
let formatted = format_references_result("delete", &truncated_resolution_with_21_callers());
assert!(
formatted
.contains("Counts below are partial — they cover only the 1 of 112 targets shown."),
"got:\n{formatted}"
);
assert!(formatted.contains("Re-run with a fully qualified name, or raise `max_targets`"));
}
#[test]
fn format_bucket_counts_remain_samples_of_the_real_thing() {
let formatted = format_references_result("delete", &truncated_resolution_with_21_callers());
assert!(formatted.contains("## Calls (function/method invocations) (21)"));
let caveat = formatted
.find("Counts below are partial")
.expect("caveat present");
let buckets = formatted.find("## Calls").expect("bucket header");
assert!(caveat < buckets, "caveat must precede the bucket counts");
}
#[test]
fn format_omits_partial_counts_caveat_when_not_truncated() {
let references = json!({
"calls": [
{"name": "caller1", "kind": "method", "file_path": "file1.java", "start_line": 10},
{"name": "caller2", "kind": "method", "file_path": "file2.java", "start_line": 20}
],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "myMethod",
"tier": "exact_name",
"fuzzy": false,
"truncated": false,
"total_targets": 1,
"targets": [{}]
}
});
let formatted = format_references_result("myMethod", &references);
assert!(!formatted.contains("Counts below are partial"));
assert!(!formatted.contains("Truncated"));
}
#[test]
fn format_no_references_with_truncated_resolution_still_discloses_truncation() {
let references = json!({
"calls": [],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "delete",
"tier": "exact_name",
"fuzzy": false,
"truncated": true,
"total_targets": 112,
"targets": []
}
});
let formatted = format_references_result("delete", &references);
assert!(formatted.contains("No references found"));
assert!(formatted.contains("**Truncated** — 112 targets matched; showing the first 0"));
assert!(!formatted.contains("Counts below are partial"));
}
#[test]
fn format_attributes_callers_when_only_one_homonym_has_them() {
let references = json!({
"calls": [
{
"name": "handleClick",
"kind": "function",
"file_path": "src/channels/ChannelsPage.tsx",
"start_line": 30,
"target_fqn": "channels.ChannelsPage.onDelete",
"target_name": "onDelete",
"target_file_path": "src/channels/ChannelsPage.tsx",
"target_start_line": 20,
"target_signature": "function onDelete(channelId: string)"
}
],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "onDelete",
"tier": "exact_name",
"fuzzy": false,
"truncated": false,
"total_targets": 2,
"targets": [
{
"fqn": "channels.ChannelsPage.onDelete",
"file_path": "src/channels/ChannelsPage.tsx",
"start_line": 20
},
{
"fqn": "profile.ProfilePage.onDelete",
"file_path": "src/profile/ProfilePage.tsx",
"start_line": 69
}
]
}
});
let formatted = format_references_result("onDelete", &references);
assert!(
formatted.contains("### Target: `channels.ChannelsPage.onDelete`"),
"got:\n{formatted}"
);
assert!(formatted.contains("src/channels/ChannelsPage.tsx:20"));
assert!(formatted.contains("handleClick"));
assert!(
!formatted.contains("### Target: `profile.ProfilePage.onDelete`"),
"callerless homonym must not be attributed:\n{formatted}"
);
}
#[test]
fn format_attributes_callers_when_resolution_truncated_to_one_shown() {
let references = json!({
"calls": [
{
"name": "caller1",
"kind": "function",
"file_path": "src/caller.rs",
"start_line": 3,
"target_fqn": "repo::module::delete",
"target_name": "delete",
"target_file_path": "src/target.rs",
"target_start_line": 1
}
],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "delete",
"tier": "exact_name",
"fuzzy": false,
"truncated": true,
"total_targets": 112,
"targets": [
{
"fqn": "repo::module::delete",
"file_path": "src/target.rs",
"start_line": 1
}
]
}
});
let formatted = format_references_result("delete", &references);
assert!(
formatted.contains("### Target: `repo::module::delete`"),
"got:\n{formatted}"
);
assert!(formatted.contains("src/target.rs:1"));
}
#[test]
fn format_single_resolved_target_keeps_concise_form() {
let references = json!({
"calls": [
{
"name": "caller1",
"kind": "method",
"file_path": "file1.java",
"start_line": 10,
"target_fqn": "myapp::Handler::myMethod",
"target_name": "myMethod",
"target_file_path": "src/Handler.java",
"target_start_line": 42
},
{
"name": "caller2",
"kind": "method",
"file_path": "file2.java",
"start_line": 20,
"target_fqn": "myapp::Handler::myMethod",
"target_name": "myMethod",
"target_file_path": "src/Handler.java",
"target_start_line": 42
}
],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "myMethod",
"tier": "exact_fqn",
"fuzzy": false,
"truncated": false,
"total_targets": 1,
"targets": [
{
"fqn": "myapp::Handler::myMethod",
"file_path": "src/Handler.java",
"start_line": 42
}
]
}
});
let formatted = format_references_result("myMethod", &references);
assert!(formatted.contains("Found 2 reference(s)"));
assert!(
!formatted.contains("### Target:"),
"single-target resolution must stay headerless:\n{formatted}"
);
}
#[test]
fn format_attributes_every_relationship_bucket() {
let row = json!({
"name": "someCaller",
"kind": "method",
"file_path": "src/caller.java",
"start_line": 10,
"target_fqn": "com.acme.MyService.myMethod",
"target_name": "myMethod",
"target_file_path": "src/MyService.java",
"target_start_line": 42
});
let references = json!({
"calls": [row],
"extends": [row],
"implements": [row],
"references": [row],
"overridden_by": [row],
"overrides": [row],
"resolution": {
"query": "myMethod",
"tier": "exact_name",
"fuzzy": false,
"truncated": false,
"total_targets": 2,
"targets": [
{"fqn": "com.acme.MyService.myMethod"},
{"fqn": "com.other.MyService.myMethod"}
]
}
});
let formatted = format_references_result("myMethod", &references);
assert!(formatted.contains("Calls (function/method invocations)"));
assert!(formatted.contains("Extends (class inheritance)"));
assert!(formatted.contains("Implements (interface implementation)"));
assert!(formatted.contains("References (type annotations/usages)"));
assert!(formatted.contains("Overridden by (method implementations)"));
assert!(formatted.contains("Overrides (declared supertype methods)"));
assert_eq!(
formatted.matches("### Target:").count(),
6,
"every bucket must attribute its caller:\n{formatted}"
);
}
#[test]
fn format_never_fabricates_target_header_without_identity() {
let formatted = format_references_result("delete", &truncated_resolution_with_21_callers());
assert!(
!formatted.contains("### Target:"),
"unattributable rows must stay headerless:\n{formatted}"
);
assert!(!formatted.contains("unknown"));
}
fn all_hidden_resolution() -> serde_json::Value {
json!({
"calls": [],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "cargo",
"tier": "fuzzy",
"fuzzy": true,
"truncated": false,
"total_targets": 0,
"kind_filter": "code_default",
"hidden_non_code": 93,
"hidden_kinds": [
"build_dependency",
"cargo_feature",
"cargo_package",
"markdown_section",
"project_identity"
],
"targets": []
}
})
}
#[test]
fn format_discloses_hidden_non_code_matches() {
let formatted = format_references_result("cargo", &all_hidden_resolution());
assert!(
formatted.contains("**Non-code matches hidden** — 93 entities matched `cargo`"),
"got:\n{formatted}"
);
assert!(formatted.contains("build_dependency"));
assert!(formatted.contains("markdown_section"));
assert!(formatted.contains("kinds=all"));
assert!(
!formatted.contains("This entity may be unused"),
"got:\n{formatted}"
);
assert!(!formatted.contains("No entity named"));
}
#[test]
fn format_zero_targets_zero_hidden_says_not_found() {
let references = json!({
"calls": [],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "no_such_thing",
"tier": "fuzzy",
"fuzzy": true,
"truncated": false,
"total_targets": 0,
"kind_filter": "code_default",
"hidden_non_code": 0,
"hidden_kinds": [],
"targets": []
}
});
let formatted = format_references_result("no_such_thing", &references);
assert!(
formatted.contains("No entity named `no_such_thing` was found in the indexed scope"),
"got:\n{formatted}"
);
assert!(!formatted.contains("This entity may be unused"));
assert!(!formatted.contains("Non-code matches hidden"));
}
#[test]
fn format_keeps_unused_wording_when_code_target_resolved() {
let references = json!({
"calls": [],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "legacy_fn",
"tier": "exact_name",
"fuzzy": false,
"truncated": false,
"total_targets": 1,
"kind_filter": "code_default",
"hidden_non_code": 0,
"hidden_kinds": [],
"targets": [
{"fqn": "app::legacy_fn", "name": "legacy_fn", "kind": "rust_function"}
]
}
});
let formatted = format_references_result("legacy_fn", &references);
assert!(formatted.contains("No references found for `legacy_fn`"));
assert!(formatted.contains("This entity may be unused"));
assert!(!formatted.contains("Non-code matches hidden"));
assert!(!formatted.contains("No entity named"));
}
#[test]
fn format_omits_hidden_notice_when_none_hidden() {
let references = json!({
"calls": [{"name": "caller1", "kind": "method", "file_path": "file1.java", "start_line": 10}],
"extends": [],
"implements": [],
"references": [],
"resolution": {
"query": "myMethod",
"tier": "exact_name",
"fuzzy": false,
"truncated": false,
"total_targets": 1,
"kind_filter": "code_default",
"hidden_non_code": 0,
"hidden_kinds": [],
"targets": [{"fqn": "app.myMethod"}]
}
});
let formatted = format_references_result("myMethod", &references);
assert!(!formatted.contains("Non-code matches hidden"));
}
#[test]
fn format_renders_extended_relationship_buckets() {
let references = json!({
"calls": [],
"extends": [],
"implements": [],
"references": [],
"macro_calls": [
{"name": "main", "kind": "rust_function", "file_path": "sample.rs", "start_line": 145}
],
"references_dom": [
{"name": "submitBtn", "kind": "rust_function", "file_path": "ui.js", "start_line": 12}
],
"uses_css_class": [],
"imports_script": [],
"imports_stylesheet": [],
"uses_backend": [],
"uses_probe": [],
"uses_acl": [],
"includes": [],
"imports_vmod": [],
"declared_unused": [],
"overridden_by": [],
"overrides": []
});
let formatted = format_references_result("init_vec", &references);
assert!(formatted.contains("Macro calls (macro invocations)"));
assert!(formatted.contains("DOM references (JS → HTML element id)"));
assert!(!formatted.contains("CSS class usage"));
assert!(formatted.contains("Found 2 reference(s)"));
assert!(formatted.contains("submitBtn"));
let references = json!({
"calls": [],
"extends": [],
"implements": [],
"references": [],
"references_dom": [
{"name": "main", "kind": "rust_function", "file_path": "ui.js", "start_line": 3}
],
"macro_calls": [],
"imports_script": [],
"imports_stylesheet": [],
"uses_backend": [],
"uses_probe": [],
"uses_acl": [],
"includes": [],
"imports_vmod": [],
"declared_unused": [],
});
let formatted = format_references_result("copybutton__status", &references);
assert!(formatted.contains("DOM references"));
}
}