feat(review): trace graph context queries

Capture symbol-graph, reverse-dependency, and graph-ranked semantic lookups as graph_query dag traces during file-context assembly, carry them through review results and eval artifacts, add focused trace tests, and mark TODO.md item #38 complete.

Author: haasonsaas

TODO.md

@@ -68,7 +68,7 @@ This roadmap is derived from deep research into Greptile's public docs, blog, MC
 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. [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.
+38. [x] 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/review/pipeline/file_context.rs

@@ -10,6 +10,7 @@ mod sources;
 use crate::config;
 use crate::core;
 
+use super::context::extract_symbols_from_diff;
 use super::services::PipelineServices;
 use super::session::ReviewSession;
 
@@ -18,6 +19,7 @@ pub(super) struct PreparedFileContext {
     pub path_config: Option<config::PathConfig>,
     pub deterministic_comments: Vec<core::Comment>,
     pub context_chunks: Vec<core::LLMContextChunk>,
+    pub graph_query_traces: Vec<core::dag::DagExecutionTrace>,
 }
 
 pub(super) async fn assemble_file_context(
@@ -30,18 +32,66 @@ pub(super) async fn assemble_file_context(
     let path_config = services.config.get_path_config(&diff.file_path).cloned();
     let mut context_chunks =
         base::initial_context_chunks(services, diff, pre_analysis_context).await?;
+    let diff_symbols = extract_symbols_from_diff(diff);
+    let mut graph_query_records = Vec::new();
 
-    sources::add_symbol_context(services, session, diff, &mut context_chunks).await?;
-    sources::add_related_file_context(services, session, diff, &mut context_chunks);
-    sources::add_semantic_context(services, session, diff, &mut context_chunks).await;
+    sources::add_symbol_context(
+        services,
+        session,
+        diff,
+        &diff_symbols,
+        &mut context_chunks,
+        &mut graph_query_records,
+    )
+    .await?;
+    sources::add_related_file_context(
+        services,
+        session,
+        diff,
+        &mut context_chunks,
+        &mut graph_query_records,
+    );
+    sources::add_semantic_context(
+        services,
+        session,
+        diff,
+        &diff_symbols,
+        &mut context_chunks,
+        &mut graph_query_records,
+    )
+    .await;
     sources::add_path_context(services, diff, path_config.as_ref(), &mut context_chunks).await?;
     sources::inject_repository_context(services, diff, &mut context_chunks).await?;
 
+    if !diff_symbols.is_empty() && !graph_query_records.is_empty() {
+        graph_query_records.insert(
+            0,
+            sources::trace_record(
+                format!("seed_symbols={}", summarize_seed_symbols(&diff_symbols)),
+                0,
+            ),
+        );
+    }
+
+    let graph_query_traces = sources::build_graph_query_trace(&diff.file_path, graph_query_records)
+        .into_iter()
+        .collect();
+
     Ok(finalize::finalize_file_context(
         services,
         diff,
         path_config,
         deterministic_comments,
         context_chunks,
+        graph_query_traces,
     ))
 }
+
+fn summarize_seed_symbols(symbols: &[String]) -> String {
+    let shown = symbols.iter().take(6).cloned().collect::<Vec<_>>();
+    let mut summary = shown.join(", ");
+    if symbols.len() > shown.len() {
+        summary.push_str(&format!(" (+{} more)", symbols.len() - shown.len()));
+    }
+    summary
+}

src/review/pipeline/file_context/finalize.rs

@@ -10,6 +10,7 @@ pub(super) fn finalize_file_context(
     path_config: Option<config::PathConfig>,
     deterministic_comments: Vec<core::Comment>,
     mut context_chunks: Vec<core::LLMContextChunk>,
+    graph_query_traces: Vec<core::dag::DagExecutionTrace>,
 ) -> PreparedFileContext {
     let active_rules = core::active_rules_for_file(
         &services.review_rules,
@@ -33,5 +34,6 @@ pub(super) fn finalize_file_context(
         path_config,
         deterministic_comments,
         context_chunks,
+        graph_query_traces,
     }
 }

src/review/pipeline/file_context/sources.rs

@@ -6,8 +6,11 @@ mod repo;
 mod supplemental;
 #[path = "sources/symbols.rs"]
 mod symbols;
+#[path = "sources/traces.rs"]
+mod traces;
 
 pub(super) use related::add_related_file_context;
 pub(super) use repo::inject_repository_context;
 pub(super) use supplemental::{add_path_context, add_semantic_context};
 pub(super) use symbols::add_symbol_context;
+pub(super) use traces::{build_graph_query_trace, trace_record};

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

@@ -1,18 +1,85 @@
+use std::time::Instant;
+
 use crate::core;
 
 use super::super::super::context::gather_related_file_context;
 use super::super::super::services::PipelineServices;
 use super::super::super::session::ReviewSession;
+use super::traces::{trace_record, MAX_GRAPH_TRACE_DETAILS};
 
 pub(in super::super) fn add_related_file_context(
     services: &PipelineServices,
     session: &ReviewSession,
     diff: &core::UnifiedDiff,
     context_chunks: &mut Vec<core::LLMContextChunk>,
+    graph_query_records: &mut Vec<core::dag::DagExecutionRecord>,
 ) {
     if let Some(index) = session.symbol_index.as_ref() {
+        let lookup_started = Instant::now();
         let caller_chunks =
             gather_related_file_context(index, &diff.file_path, &services.repo_path);
+        append_related_file_trace_records(
+            graph_query_records,
+            &caller_chunks,
+            lookup_started.elapsed().as_millis() as u64,
+        );
         context_chunks.extend(caller_chunks);
     }
 }
+
+fn append_related_file_trace_records(
+    graph_query_records: &mut Vec<core::dag::DagExecutionRecord>,
+    caller_chunks: &[core::LLMContextChunk],
+    duration_ms: u64,
+) {
+    let reverse_dependencies = caller_chunks
+        .iter()
+        .filter(|chunk| {
+            matches!(
+                chunk.provenance.as_ref(),
+                Some(core::ContextProvenance::ReverseDependencySummary)
+            )
+        })
+        .map(|chunk| chunk.file_path.display().to_string())
+        .collect::<Vec<_>>();
+
+    graph_query_records.push(trace_record(
+        format!("reverse_dependency_hits={}", reverse_dependencies.len()),
+        duration_ms,
+    ));
+    for (index, file_path) in reverse_dependencies
+        .iter()
+        .take(MAX_GRAPH_TRACE_DETAILS)
+        .enumerate()
+    {
+        graph_query_records.push(trace_record(
+            format!("reverse_dependency_hit[{index}]={file_path}"),
+            0,
+        ));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::append_related_file_trace_records;
+    use crate::core;
+    use std::path::PathBuf;
+
+    #[test]
+    fn related_file_trace_records_only_capture_reverse_dependencies() {
+        let chunks = vec![
+            core::LLMContextChunk::reference(PathBuf::from("src/caller.rs"), "caller".to_string())
+                .with_provenance(core::ContextProvenance::ReverseDependencySummary),
+            core::LLMContextChunk::reference(PathBuf::from("tests/file.rs"), "test".to_string())
+                .with_provenance(core::ContextProvenance::RelatedTestFile),
+        ];
+
+        let mut records = Vec::new();
+        append_related_file_trace_records(&mut records, &chunks, 4);
+
+        assert_eq!(records[0].name, "reverse_dependency_hits=1");
+        assert_eq!(records[0].duration_ms, 4);
+        assert_eq!(records[1].name, "reverse_dependency_hit[0]=src/caller.rs");
+        assert_eq!(records.len(), 2);
+    }
+}

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

@@ -1,25 +1,37 @@
 use std::collections::HashSet;
 use std::path::PathBuf;
+use std::time::Instant;
 
 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;
+use super::traces::{trace_record, MAX_GRAPH_TRACE_DETAILS};
 
 pub(in super::super) async fn add_semantic_context(
     services: &PipelineServices,
     session: &ReviewSession,
     diff: &core::UnifiedDiff,
+    symbols: &[String],
     context_chunks: &mut Vec<core::LLMContextChunk>,
+    graph_query_records: &mut Vec<core::dag::DagExecutionRecord>,
 ) {
     let Some(index) = session.semantic_index.as_ref() else {
         return;
     };
-    let preferred_files = graph_ranked_semantic_files(services, session, diff);
+    let should_trace_graph_ranking = session.symbol_index.is_some() && !symbols.is_empty();
+    let ranking_started = Instant::now();
+    let preferred_files = graph_ranked_semantic_files(services, session, diff, symbols);
+    if should_trace_graph_ranking {
+        append_semantic_preference_trace_records(
+            graph_query_records,
+            &preferred_files,
+            ranking_started.elapsed().as_millis() as u64,
+        );
+    }
 
     let semantic_chunks = core::semantic_context_for_diff(
         index,
@@ -41,12 +53,12 @@ fn graph_ranked_semantic_files(
     services: &PipelineServices,
     session: &ReviewSession,
     diff: &core::UnifiedDiff,
+    symbols: &[String],
 ) -> 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();
     }
@@ -59,7 +71,7 @@ fn graph_ranked_semantic_files(
             services.config.symbol_index_graph_max_files,
         ),
     );
-    let related_locations = retriever.related_symbol_locations(&diff.file_path, &symbols);
+    let related_locations = retriever.related_symbol_locations(&diff.file_path, symbols);
 
     let mut preferred_files = Vec::new();
     let mut seen = HashSet::new();
@@ -84,6 +96,27 @@ fn graph_ranked_semantic_files(
     preferred_files
 }
 
+fn append_semantic_preference_trace_records(
+    graph_query_records: &mut Vec<core::dag::DagExecutionRecord>,
+    preferred_files: &[PathBuf],
+    duration_ms: u64,
+) {
+    graph_query_records.push(trace_record(
+        format!("semantic_preferred_files={}", preferred_files.len()),
+        duration_ms,
+    ));
+    for (index, file_path) in preferred_files
+        .iter()
+        .take(MAX_GRAPH_TRACE_DETAILS)
+        .enumerate()
+    {
+        graph_query_records.push(trace_record(
+            format!("semantic_preferred_file[{index}]={}", file_path.display()),
+            0,
+        ));
+    }
+}
+
 pub(in super::super) async fn add_path_context(
     services: &PipelineServices,
     diff: &core::UnifiedDiff,
@@ -117,3 +150,22 @@ pub(in super::super) async fn add_path_context(
 
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::append_semantic_preference_trace_records;
+    use std::path::PathBuf;
+
+    #[test]
+    fn semantic_preference_trace_records_keep_ranked_order() {
+        let preferred_files = vec![PathBuf::from("src/auth.rs"), PathBuf::from("src/db.rs")];
+
+        let mut records = Vec::new();
+        append_semantic_preference_trace_records(&mut records, &preferred_files, 7);
+
+        assert_eq!(records[0].name, "semantic_preferred_files=2");
+        assert_eq!(records[0].duration_ms, 7);
+        assert_eq!(records[1].name, "semantic_preferred_file[0]=src/auth.rs");
+        assert_eq!(records[2].name, "semantic_preferred_file[1]=src/db.rs");
+    }
+}