feat(review): bias semantic retrieval with graph-ranked files

Use symbol-graph related files to prioritize semantic RAG candidates before global similarity ranking, surface the graph-ranked hint in semantic context, add coverage for the ranking behavior, and mark TODO.md item #37 complete.

Author: haasonsaas

TODO.md

@@ -67,7 +67,7 @@ This roadmap is derived from deep research into Greptile's public docs, blog, MC
 34. [ ] Add "similar implementation" lookup so repeated patterns and divergences are explicit.
 35. [ ] Add cross-file blast-radius summaries to findings when a change affects many callers.
 36. [ ] Add graph freshness/version metadata so reviews know whether they are using stale repository intelligence.
-37. [ ] Add graph-backed ranking of related files before semantic RAG retrieval.
+37. [x] Add graph-backed ranking of related files before semantic RAG retrieval.
 38. [ ] Add graph query traces to `dag_traces` or review artifacts for explainability and debugging.
 39. [x] Add graph-aware eval fixtures that require multi-hop code understanding to pass.
 40. [ ] Split `src/core/symbol_graph.rs` into construction, persistence, traversal, and ranking modules as it grows.

src/core/semantic.rs

@@ -247,25 +247,38 @@ pub async fn semantic_context_for_diff(
     embedding_adapter: Option<&dyn LLMAdapter>,
     limit: usize,
     min_similarity: f32,
+    preferred_files: &[PathBuf],
 ) -> Vec<LLMContextChunk> {
     let query_texts = build_query_texts(diff, file_content);
     if query_texts.is_empty() {
         return Vec::new();
     }
 
     let query_embeddings = embed_texts_with_fallback(embedding_adapter, &query_texts).await;
-    let matches =
-        find_related_chunks_for_diff(index, &query_embeddings, diff, limit, min_similarity);
+    let matches = find_related_chunks_for_diff(
+        index,
+        &query_embeddings,
+        diff,
+        limit,
+        min_similarity,
+        preferred_files,
+    );
+    let preferred_file_ranks = build_preferred_file_ranks(preferred_files);
 
     let mut seen = HashSet::new();
     let mut chunks = Vec::new();
     for semantic_match in matches {
         if !seen.insert(semantic_match.chunk.key.clone()) {
             continue;
         }
+        let ranking_note = preferred_file_ranks
+            .get(&semantic_match.chunk.file_path)
+            .map(|rank| format!(", graph-ranked file #{}", rank + 1))
+            .unwrap_or_default();
         let content = format!(
-            "Semantic match (similarity {:.2})\nSymbol: {}\nSummary: {}\nCode:\n{}",
+            "Semantic match (similarity {:.2}{})\nSymbol: {}\nSummary: {}\nCode:\n{}",
             semantic_match.similarity,
+            ranking_note,
             semantic_match.chunk.symbol_name,
             semantic_match.chunk.summary,
             semantic_match.chunk.code_excerpt,
@@ -323,8 +336,10 @@ fn find_related_chunks_for_diff(
     diff: &UnifiedDiff,
     limit: usize,
     min_similarity: f32,
+    preferred_files: &[PathBuf],
 ) -> Vec<SemanticMatch> {
     let changed_ranges = changed_line_ranges(diff);
+    let preferred_file_ranks = build_preferred_file_ranks(preferred_files);
     let mut best_matches: HashMap<String, SemanticMatch> = HashMap::new();
 
     for query_embedding in query_embeddings {
@@ -351,11 +366,34 @@ fn find_related_chunks_for_diff(
     }
 
     let mut matches = best_matches.into_values().collect::<Vec<_>>();
-    matches.sort_by(|a, b| b.similarity.total_cmp(&a.similarity));
+    matches.sort_by(|a, b| {
+        let a_rank = preferred_file_ranks
+            .get(&a.chunk.file_path)
+            .copied()
+            .unwrap_or(usize::MAX);
+        let b_rank = preferred_file_ranks
+            .get(&b.chunk.file_path)
+            .copied()
+            .unwrap_or(usize::MAX);
+        a_rank
+            .cmp(&b_rank)
+            .then_with(|| b.similarity.total_cmp(&a.similarity))
+            .then_with(|| a.chunk.key.cmp(&b.chunk.key))
+    });
     matches.truncate(limit.max(1));
     matches
 }
 
+fn build_preferred_file_ranks(preferred_files: &[PathBuf]) -> HashMap<PathBuf, usize> {
+    let mut preferred_file_ranks = HashMap::new();
+    for (rank, file_path) in preferred_files.iter().enumerate() {
+        preferred_file_ranks
+            .entry(file_path.clone())
+            .or_insert(rank);
+    }
+    preferred_file_ranks
+}
+
 pub fn find_similar_feedback_examples(
     store: &SemanticFeedbackStore,
     query_embedding: &[f32],
@@ -622,8 +660,76 @@ mod tests {
             }],
         };
 
-        let chunks = semantic_context_for_diff(&index, &diff, None, None, 3, 0.1).await;
+        let chunks = semantic_context_for_diff(&index, &diff, None, None, 3, 0.1, &[]).await;
         assert_eq!(chunks.len(), 1);
         assert!(chunks[0].content.contains("Semantic match"));
     }
+
+    #[test]
+    fn find_related_chunks_for_diff_prioritizes_graph_ranked_files() {
+        let mut index = SemanticIndex::default();
+        index.entries.insert(
+            "src/graph.rs:helper:1:5".to_string(),
+            SemanticChunk {
+                key: "src/graph.rs:helper:1:5".to_string(),
+                file_path: PathBuf::from("src/graph.rs"),
+                symbol_name: "graph_helper".to_string(),
+                line_range: (1, 5),
+                summary: "Graph-ranked helper".to_string(),
+                embedding_text: "graph-ranked helper".to_string(),
+                code_excerpt: "fn graph_helper() {}".to_string(),
+                embedding: vec![0.8, 0.6],
+                content_hash: "graph".to_string(),
+            },
+        );
+        index.entries.insert(
+            "src/other.rs:helper:1:5".to_string(),
+            SemanticChunk {
+                key: "src/other.rs:helper:1:5".to_string(),
+                file_path: PathBuf::from("src/other.rs"),
+                symbol_name: "other_helper".to_string(),
+                line_range: (1, 5),
+                summary: "Higher-similarity helper".to_string(),
+                embedding_text: "higher-similarity helper".to_string(),
+                code_excerpt: "fn other_helper() {}".to_string(),
+                embedding: vec![1.0, 0.0],
+                content_hash: "other".to_string(),
+            },
+        );
+
+        let diff = UnifiedDiff {
+            old_content: None,
+            new_content: None,
+            file_path: PathBuf::from("src/current.rs"),
+            is_new: false,
+            is_deleted: false,
+            is_binary: false,
+            hunks: vec![DiffHunk {
+                old_start: 1,
+                old_lines: 0,
+                new_start: 1,
+                new_lines: 1,
+                context: String::new(),
+                changes: vec![DiffLine {
+                    old_line_no: None,
+                    new_line_no: Some(1),
+                    change_type: ChangeType::Added,
+                    content: "graph-aware semantic ranking".to_string(),
+                }],
+            }],
+        };
+
+        let matches = find_related_chunks_for_diff(
+            &index,
+            &[vec![1.0, 0.0]],
+            &diff,
+            2,
+            0.1,
+            &[PathBuf::from("src/graph.rs")],
+        );
+
+        assert_eq!(matches.len(), 2);
+        assert_eq!(matches[0].chunk.file_path, PathBuf::from("src/graph.rs"));
+        assert_eq!(matches[1].chunk.file_path, PathBuf::from("src/other.rs"));
+    }
 }

src/review/pipeline/file_context/sources/supplemental.rs

@@ -1,8 +1,12 @@
+use std::collections::HashSet;
+use std::path::PathBuf;
+
 use anyhow::Result;
 
 use crate::config;
 use crate::core;
 
+use super::super::super::context::extract_symbols_from_diff;
 use super::super::super::services::PipelineServices;
 use super::super::super::session::ReviewSession;
 
@@ -15,6 +19,7 @@ pub(in super::super) async fn add_semantic_context(
     let Some(index) = session.semantic_index.as_ref() else {
         return;
     };
+    let preferred_files = graph_ranked_semantic_files(services, session, diff);
 
     let semantic_chunks = core::semantic_context_for_diff(
         index,
@@ -26,11 +31,59 @@ pub(in super::super) async fn add_semantic_context(
         services.embedding_adapter.as_deref(),
         services.config.semantic_rag_top_k,
         services.config.semantic_rag_min_similarity,
+        &preferred_files,
     )
     .await;
     context_chunks.extend(semantic_chunks);
 }
 
+fn graph_ranked_semantic_files(
+    services: &PipelineServices,
+    session: &ReviewSession,
+    diff: &core::UnifiedDiff,
+) -> Vec<PathBuf> {
+    let Some(index) = session.symbol_index.as_ref() else {
+        return Vec::new();
+    };
+
+    let symbols = extract_symbols_from_diff(diff);
+    if symbols.is_empty() {
+        return Vec::new();
+    }
+
+    let retriever = core::SymbolContextRetriever::new(
+        index,
+        core::SymbolRetrievalPolicy::new(
+            services.config.symbol_index_max_locations,
+            services.config.symbol_index_graph_hops,
+            services.config.symbol_index_graph_max_files,
+        ),
+    );
+    let related_locations = retriever.related_symbol_locations(&diff.file_path, &symbols);
+
+    let mut preferred_files = Vec::new();
+    let mut seen = HashSet::new();
+
+    for location in related_locations.definition_locations {
+        if location.file_path == diff.file_path || !seen.insert(location.file_path.clone()) {
+            continue;
+        }
+        preferred_files.push(location.file_path);
+    }
+
+    let mut reference_files = related_locations
+        .reference_locations
+        .into_iter()
+        .map(|location| location.file_path)
+        .filter(|file_path| file_path != &diff.file_path)
+        .filter(|file_path| seen.insert(file_path.clone()))
+        .collect::<Vec<_>>();
+    reference_files.sort();
+    preferred_files.extend(reference_files);
+
+    preferred_files
+}
+
 pub(in super::super) async fn add_path_context(
     services: &PipelineServices,
     diff: &core::UnifiedDiff,