refactor: type review context provenance

Author: haasonsaas

src/core/context.rs

@@ -6,15 +6,16 @@ use std::path::Path;
 use std::path::PathBuf;
 
 use crate::core::function_chunker::find_enclosing_boundary_line;
-use crate::core::SymbolIndex;
+use crate::core::{ContextProvenance, SymbolIndex};
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct LLMContextChunk {
     pub file_path: PathBuf,
     pub content: String,
     pub context_type: ContextType,
     pub line_range: Option<(usize, usize)>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub provenance: Option<String>,
+    pub provenance: Option<ContextProvenance>,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
@@ -25,6 +26,52 @@ pub enum ContextType {
     Documentation,
 }
 
+impl LLMContextChunk {
+    pub fn new(
+        file_path: impl Into<PathBuf>,
+        content: impl Into<String>,
+        context_type: ContextType,
+    ) -> Self {
+        Self {
+            file_path: file_path.into(),
+            content: content.into(),
+            context_type,
+            line_range: None,
+            provenance: None,
+        }
+    }
+
+    pub fn file_content(file_path: impl Into<PathBuf>, content: impl Into<String>) -> Self {
+        Self::new(file_path, content, ContextType::FileContent)
+    }
+
+    pub fn definition(file_path: impl Into<PathBuf>, content: impl Into<String>) -> Self {
+        Self::new(file_path, content, ContextType::Definition)
+    }
+
+    pub fn reference(file_path: impl Into<PathBuf>, content: impl Into<String>) -> Self {
+        Self::new(file_path, content, ContextType::Reference)
+    }
+
+    pub fn documentation(file_path: impl Into<PathBuf>, content: impl Into<String>) -> Self {
+        Self::new(file_path, content, ContextType::Documentation)
+    }
+
+    pub fn with_line_range(mut self, line_range: (usize, usize)) -> Self {
+        self.line_range = Some(line_range);
+        self
+    }
+
+    pub fn with_provenance(mut self, provenance: ContextProvenance) -> Self {
+        self.provenance = Some(provenance);
+        self
+    }
+
+    pub fn provenance_label(&self) -> Option<String> {
+        self.provenance.as_ref().map(ToString::to_string)
+    }
+}
+
 pub struct ContextFetcher {
     repo_path: PathBuf,
 }
@@ -71,13 +118,10 @@ impl ContextFetcher {
                         file_lines[start_idx..end_idx].join("\n"),
                         MAX_CONTEXT_CHARS,
                     );
-                    chunks.push(LLMContextChunk {
-                        file_path: file_path.clone(),
-                        content: chunk_content,
-                        context_type: ContextType::FileContent,
-                        line_range: Some((expanded_start, expanded_end)),
-                        provenance: None,
-                    });
+                    chunks.push(
+                        LLMContextChunk::file_content(file_path.clone(), chunk_content)
+                            .with_line_range((expanded_start, expanded_end)),
+                    );
                 }
             }
         }
@@ -135,13 +179,10 @@ impl ContextFetcher {
                 continue;
             }
 
-            chunks.push(LLMContextChunk {
-                file_path: relative_path.to_path_buf(),
-                content: snippet,
-                context_type: ContextType::Reference,
-                line_range: None,
-                provenance: None,
-            });
+            chunks.push(LLMContextChunk::reference(
+                relative_path.to_path_buf(),
+                snippet,
+            ));
         }
 
         Ok(chunks)
@@ -184,13 +225,10 @@ impl ContextFetcher {
                                 MAX_CONTEXT_CHARS,
                             );
 
-                            chunks.push(LLMContextChunk {
-                                file_path: file_path.clone(),
-                                content: definition_content,
-                                context_type: ContextType::Definition,
-                                line_range: Some((start_line + 1, end_line)),
-                                provenance: None,
-                            });
+                            chunks.push(
+                                LLMContextChunk::definition(file_path.clone(), definition_content)
+                                    .with_line_range((start_line + 1, end_line)),
+                            );
                         }
                     }
                 }
@@ -222,13 +260,13 @@ impl ContextFetcher {
                         continue;
                     }
                     let snippet = truncate_with_notice(location.snippet.clone(), MAX_CONTEXT_CHARS);
-                    chunks.push(LLMContextChunk {
-                        file_path: location.file_path.clone(),
-                        content: snippet,
-                        context_type: ContextType::Definition,
-                        line_range: Some(location.line_range),
-                        provenance: location.provenance.clone(),
-                    });
+                    let mut chunk =
+                        LLMContextChunk::definition(location.file_path.clone(), snippet)
+                            .with_line_range(location.line_range);
+                    if let Some(provenance) = location.provenance.clone() {
+                        chunk = chunk.with_provenance(provenance);
+                    }
+                    chunks.push(chunk);
                 }
             }
         }
@@ -244,13 +282,12 @@ impl ContextFetcher {
                 continue;
             }
             let snippet = truncate_with_notice(location.snippet, MAX_CONTEXT_CHARS);
-            chunks.push(LLMContextChunk {
-                file_path: location.file_path,
-                content: snippet,
-                context_type: ContextType::Definition,
-                line_range: Some(location.line_range),
-                provenance: location.provenance,
-            });
+            let mut chunk = LLMContextChunk::definition(location.file_path, snippet)
+                .with_line_range(location.line_range);
+            if let Some(provenance) = location.provenance {
+                chunk = chunk.with_provenance(provenance);
+            }
+            chunks.push(chunk);
         }
 
         for location in index.multi_hop_locations(
@@ -264,13 +301,12 @@ impl ContextFetcher {
                 continue;
             }
             let snippet = truncate_with_notice(location.snippet, MAX_CONTEXT_CHARS);
-            chunks.push(LLMContextChunk {
-                file_path: location.file_path,
-                content: snippet,
-                context_type: ContextType::Reference,
-                line_range: Some(location.line_range),
-                provenance: location.provenance,
-            });
+            let mut chunk = LLMContextChunk::reference(location.file_path, snippet)
+                .with_line_range(location.line_range);
+            if let Some(provenance) = location.provenance {
+                chunk = chunk.with_provenance(provenance);
+            }
+            chunks.push(chunk);
         }
 
         Ok(chunks)
@@ -441,12 +477,12 @@ mod tests {
         assert_eq!(graph_chunk.context_type, ContextType::Definition);
         assert!(graph_chunk.content.contains("validate_token"));
         assert!(graph_chunk
-            .provenance
+            .provenance_label()
             .as_deref()
             .unwrap_or_default()
             .contains("symbol graph"));
         assert!(graph_chunk
-            .provenance
+            .provenance_label()
             .as_deref()
             .unwrap_or_default()
             .contains("calls"));

src/core/context_provenance.rs

@@ -0,0 +1,186 @@
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum ContextProvenance {
+    ActiveReviewRules,
+    Analyzer {
+        name: String,
+    },
+    CustomContextNotes,
+    DependencyGraphNeighborhood,
+    PathSpecificFocusAreas,
+    PatternRepositoryContext {
+        source: String,
+    },
+    PatternRepositorySource {
+        source: String,
+    },
+    RelatedTestFile,
+    ReverseDependencySummary,
+    SemanticRetrieval {
+        similarity: f32,
+        symbol_name: String,
+    },
+    SymbolGraphPath {
+        relation_path: Vec<String>,
+        hops: usize,
+        relevance: f32,
+    },
+}
+
+impl ContextProvenance {
+    pub fn analyzer(name: impl Into<String>) -> Self {
+        Self::Analyzer { name: name.into() }
+    }
+
+    pub fn pattern_repository_context(source: impl Into<String>) -> Self {
+        Self::PatternRepositoryContext {
+            source: source.into(),
+        }
+    }
+
+    pub fn pattern_repository_source(source: impl Into<String>) -> Self {
+        Self::PatternRepositorySource {
+            source: source.into(),
+        }
+    }
+
+    pub fn semantic_retrieval(similarity: f32, symbol_name: impl Into<String>) -> Self {
+        Self::SemanticRetrieval {
+            similarity,
+            symbol_name: symbol_name.into(),
+        }
+    }
+
+    pub fn symbol_graph_path(relation_path: Vec<String>, hops: usize, relevance: f32) -> Self {
+        Self::SymbolGraphPath {
+            relation_path,
+            hops,
+            relevance,
+        }
+    }
+
+    pub fn ranking_bonus(&self) -> i32 {
+        match self {
+            Self::ActiveReviewRules => 120,
+            Self::PatternRepositorySource { .. } => 40,
+            Self::PatternRepositoryContext { .. } => 35,
+            Self::SemanticRetrieval { .. } => 25,
+            Self::SymbolGraphPath {
+                relation_path,
+                hops,
+                ..
+            } => {
+                let mut bonus = 50;
+                if *hops == 1 {
+                    bonus += 15;
+                }
+                if relation_path.iter().any(|step| {
+                    step.eq_ignore_ascii_case("calls") || step.eq_ignore_ascii_case("called-by")
+                }) {
+                    bonus += 10;
+                }
+                bonus
+            }
+            Self::Analyzer { .. }
+            | Self::CustomContextNotes
+            | Self::DependencyGraphNeighborhood
+            | Self::PathSpecificFocusAreas
+            | Self::RelatedTestFile
+            | Self::ReverseDependencySummary => 0,
+        }
+    }
+
+    pub fn verification_bonus(&self) -> i32 {
+        match self {
+            Self::SymbolGraphPath { .. } => 80,
+            Self::SemanticRetrieval { .. } => 30,
+            _ => 0,
+        }
+    }
+
+    fn label(&self) -> String {
+        match self {
+            Self::ActiveReviewRules => "active review rules".to_string(),
+            Self::Analyzer { name } => format!("{} analyzer", name),
+            Self::CustomContextNotes => "custom context notes".to_string(),
+            Self::DependencyGraphNeighborhood => "dependency graph neighborhood".to_string(),
+            Self::PathSpecificFocusAreas => "path-specific focus areas".to_string(),
+            Self::PatternRepositoryContext { source } => {
+                format!("pattern repository: {}", source)
+            }
+            Self::PatternRepositorySource { source } => {
+                format!("pattern repository source: {}", source)
+            }
+            Self::RelatedTestFile => "related test file".to_string(),
+            Self::ReverseDependencySummary => "reverse dependency summary".to_string(),
+            Self::SemanticRetrieval {
+                similarity,
+                symbol_name,
+            } => format!(
+                "semantic retrieval (similarity={:.2}, symbol={})",
+                similarity, symbol_name
+            ),
+            Self::SymbolGraphPath {
+                relation_path,
+                hops,
+                relevance,
+            } => format!(
+                "symbol graph path: {} (hops={}, relevance={:.2})",
+                if relation_path.is_empty() {
+                    "seed".to_string()
+                } else {
+                    relation_path.join(" -> ")
+                },
+                hops,
+                relevance
+            ),
+        }
+    }
+}
+
+impl fmt::Display for ContextProvenance {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.label())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::ContextProvenance;
+
+    #[test]
+    fn symbol_graph_path_formats_and_scores() {
+        let provenance = ContextProvenance::symbol_graph_path(
+            vec!["calls".to_string(), "uses".to_string()],
+            1,
+            0.42,
+        );
+
+        assert_eq!(
+            provenance.to_string(),
+            "symbol graph path: calls -> uses (hops=1, relevance=0.42)"
+        );
+        assert_eq!(provenance.ranking_bonus(), 75);
+        assert_eq!(provenance.verification_bonus(), 80);
+    }
+
+    #[test]
+    fn active_rules_and_pattern_repository_have_stable_labels() {
+        assert_eq!(
+            ContextProvenance::ActiveReviewRules.to_string(),
+            "active review rules"
+        );
+        assert_eq!(
+            ContextProvenance::pattern_repository_source("org/repo").to_string(),
+            "pattern repository source: org/repo"
+        );
+        assert_eq!(
+            ContextProvenance::pattern_repository_context("org/repo").to_string(),
+            "pattern repository: org/repo"
+        );
+    }
+}