feat: ground reviews with semantic retrieval and structured analyzer signals

Author: haasonsaas

src/adapters/llm.rs

@@ -162,6 +162,18 @@ pub trait LLMAdapter: Send + Sync {
     async fn complete(&self, request: LLMRequest) -> Result<LLMResponse>;
     fn model_name(&self) -> &str;
 
+    /// Embed one or more texts for semantic retrieval and feedback learning.
+    async fn embed(&self, _texts: &[String]) -> Result<Vec<Vec<f32>>> {
+        Err(anyhow::anyhow!(
+            "Embeddings are not supported by adapter for model {}",
+            self.model_name()
+        ))
+    }
+
+    fn supports_embeddings(&self) -> bool {
+        false
+    }
+
     /// Multi-turn chat with tool use support.
     /// Default impl flattens to a single `complete()` call (no tool support).
     async fn chat(&self, request: ChatRequest) -> Result<ChatResponse> {

src/adapters/openai.rs

@@ -33,6 +33,12 @@ struct OpenAIResponsesRequest {
     max_output_tokens: usize,
 }
 
+#[derive(Serialize)]
+struct OpenAIEmbeddingRequest {
+    model: String,
+    input: Vec<String>,
+}
+
 #[derive(Serialize, Deserialize)]
 struct Message {
     role: String,
@@ -88,6 +94,17 @@ struct OpenAIResponsesUsage {
     total_tokens: usize,
 }
 
+#[derive(Deserialize)]
+struct OpenAIEmbeddingResponse {
+    data: Vec<OpenAIEmbeddingData>,
+}
+
+#[derive(Deserialize)]
+struct OpenAIEmbeddingData {
+    embedding: Vec<f32>,
+    index: usize,
+}
+
 // === Chat API types (for tool use / function calling) ===
 
 #[derive(Serialize)]
@@ -216,6 +233,41 @@ impl LLMAdapter for OpenAIAdapter {
         &self.config.model_name
     }
 
+    async fn embed(&self, texts: &[String]) -> Result<Vec<Vec<f32>>> {
+        if texts.is_empty() {
+            return Ok(Vec::new());
+        }
+
+        let request = OpenAIEmbeddingRequest {
+            model: self.config.model_name.clone(),
+            input: texts.to_vec(),
+        };
+
+        let url = format!("{}/embeddings", self.base_url);
+        let response = common::send_with_retry_config("OpenAI", &self.retry_config, &mut || {
+            self.client
+                .post(&url)
+                .header("Authorization", format!("Bearer {}", self.api_key))
+                .header("Content-Type", "application/json")
+                .json(&request)
+        })
+        .await
+        .context("Failed to send embedding request to OpenAI")?;
+
+        let embedding_response: OpenAIEmbeddingResponse = response
+            .json()
+            .await
+            .context("Failed to parse OpenAI embedding response")?;
+
+        let mut data = embedding_response.data;
+        data.sort_by_key(|item| item.index);
+        Ok(data.into_iter().map(|item| item.embedding).collect())
+    }
+
+    fn supports_embeddings(&self) -> bool {
+        true
+    }
+
     async fn chat(&self, request: ChatRequest) -> Result<ChatResponse> {
         let mut messages: Vec<OpenAIChatMessage> = Vec::new();
 

src/commands/misc.rs

@@ -166,7 +166,7 @@ pub async fn lsp_check_command(path: PathBuf, config: config::Config) -> Result<
 }
 
 pub async fn feedback_command(
-    config: config::Config,
+    mut config: config::Config,
     accept: Option<PathBuf>,
     reject: Option<PathBuf>,
     feedback_path: Option<PathBuf>,
@@ -180,6 +180,7 @@ pub async fn feedback_command(
     };
 
     let feedback_path = feedback_path.unwrap_or_else(|| config.feedback_path.clone());
+    config.feedback_path = feedback_path.clone();
     let content = tokio::fs::read_to_string(&input_path).await?;
     let mut comments: Vec<core::Comment> = serde_json::from_str(&content)?;
 
@@ -209,6 +210,11 @@ pub async fn feedback_command(
         action
     );
 
+    let is_accepted = action == "accept";
+    for comment in &comments {
+        let _ = review::record_semantic_feedback_example(&config, comment, is_accepted).await;
+    }
+
     // Also record in the convention store for learned suppression/boost patterns
     let convention_path = resolve_convention_store_path_for_feedback(&config);
     if let Some(ref cpath) = convention_path {
@@ -218,7 +224,6 @@ pub async fn feedback_command(
             .and_then(|j| ConventionStore::from_json(j).ok())
             .unwrap_or_default();
         let now = chrono::Utc::now().to_rfc3339();
-        let is_accepted = action == "accept";
         for comment in &comments {
             let file_patterns = review::derive_file_patterns(&comment.file_path);
             cstore.record_feedback(

src/commands/review.rs

@@ -92,10 +92,10 @@ pub async fn review_command(
             .await?;
 
         // Run pre-analyzers to get additional context
-        let analyzer_chunks = plugin_manager
+        let pre_analysis = plugin_manager
             .run_pre_analyzers(diff, &repo_path_str)
             .await?;
-        context_chunks.extend(analyzer_chunks);
+        context_chunks.extend(pre_analysis.context_chunks);
 
         // Extract symbols from diff and fetch their definitions
         let symbols = crate::review::extract_symbols_from_diff(diff);

src/commands/smart_review.rs

@@ -153,10 +153,10 @@ pub async fn smart_review_command(
             .await?;
 
         // Run pre-analyzers to get additional context
-        let analyzer_chunks = plugin_manager
+        let pre_analysis = plugin_manager
             .run_pre_analyzers(diff, &repo_path_str)
             .await?;
-        context_chunks.extend(analyzer_chunks);
+        context_chunks.extend(pre_analysis.context_chunks);
 
         // Get path-specific configuration
         let path_config = config.get_path_config(&diff.file_path);

src/config.rs

@@ -314,6 +314,32 @@ pub struct Config {
     /// Minimum number of feedback observations before adjusting confidence (default 5).
     #[serde(default = "default_feedback_min_observations")]
     pub feedback_min_observations: usize,
+
+    /// Enable semantic repository retrieval for related code context.
+    #[serde(default = "default_false")]
+    pub semantic_rag: bool,
+
+    #[serde(default = "default_semantic_rag_max_files")]
+    pub semantic_rag_max_files: usize,
+
+    #[serde(default = "default_semantic_rag_top_k")]
+    pub semantic_rag_top_k: usize,
+
+    #[serde(default = "default_semantic_rag_min_similarity")]
+    pub semantic_rag_min_similarity: f32,
+
+    /// Enable embedding-backed feedback memory on top of aggregate stats.
+    #[serde(default)]
+    pub semantic_feedback: bool,
+
+    #[serde(default = "default_semantic_feedback_similarity")]
+    pub semantic_feedback_similarity: f32,
+
+    #[serde(default = "default_semantic_feedback_min_examples")]
+    pub semantic_feedback_min_examples: usize,
+
+    #[serde(default = "default_semantic_feedback_max_neighbors")]
+    pub semantic_feedback_max_neighbors: usize,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
@@ -482,6 +508,14 @@ impl Default for Config {
             verification_max_comments: default_verification_max_comments(),
             enhanced_feedback: false,
             feedback_min_observations: default_feedback_min_observations(),
+            semantic_rag: false,
+            semantic_rag_max_files: default_semantic_rag_max_files(),
+            semantic_rag_top_k: default_semantic_rag_top_k(),
+            semantic_rag_min_similarity: default_semantic_rag_min_similarity(),
+            semantic_feedback: false,
+            semantic_feedback_similarity: default_semantic_feedback_similarity(),
+            semantic_feedback_min_examples: default_semantic_feedback_min_examples(),
+            semantic_feedback_max_neighbors: default_semantic_feedback_max_neighbors(),
         }
     }
 }
@@ -914,6 +948,28 @@ impl Config {
         if self.feedback_suppression_threshold == 0 {
             self.feedback_suppression_threshold = default_feedback_suppression_threshold();
         }
+        if self.semantic_rag_max_files == 0 {
+            self.semantic_rag_max_files = default_semantic_rag_max_files();
+        }
+        if self.semantic_rag_top_k == 0 {
+            self.semantic_rag_top_k = default_semantic_rag_top_k();
+        }
+        if !self.semantic_rag_min_similarity.is_finite() {
+            self.semantic_rag_min_similarity = default_semantic_rag_min_similarity();
+        } else {
+            self.semantic_rag_min_similarity = self.semantic_rag_min_similarity.clamp(0.0, 1.0);
+        }
+        if !self.semantic_feedback_similarity.is_finite() {
+            self.semantic_feedback_similarity = default_semantic_feedback_similarity();
+        } else {
+            self.semantic_feedback_similarity = self.semantic_feedback_similarity.clamp(0.0, 1.0);
+        }
+        if self.semantic_feedback_min_examples == 0 {
+            self.semantic_feedback_min_examples = default_semantic_feedback_min_examples();
+        }
+        if self.semantic_feedback_max_neighbors == 0 {
+            self.semantic_feedback_max_neighbors = default_semantic_feedback_max_neighbors();
+        }
     }
 
     pub fn get_path_config(&self, file_path: &Path) -> Option<&PathConfig> {
@@ -1300,6 +1356,30 @@ fn default_feedback_min_observations() -> usize {
     5
 }
 
+fn default_semantic_rag_max_files() -> usize {
+    500
+}
+
+fn default_semantic_rag_top_k() -> usize {
+    5
+}
+
+fn default_semantic_rag_min_similarity() -> f32 {
+    0.25
+}
+
+fn default_semantic_feedback_similarity() -> f32 {
+    0.82
+}
+
+fn default_semantic_feedback_min_examples() -> usize {
+    3
+}
+
+fn default_semantic_feedback_max_neighbors() -> usize {
+    8
+}
+
 fn normalize_comment_types(values: &[String]) -> Vec<String> {
     if values.is_empty() {
         return default_comment_types();

src/core/mod.rs

@@ -20,6 +20,7 @@ pub mod pr_history;
 pub mod pr_summary;
 pub mod prompt;
 pub mod rules;
+pub mod semantic;
 pub mod smart_review_prompt;
 pub mod symbol_graph;
 pub mod symbol_index;
@@ -36,5 +37,11 @@ pub use git::{validate_ref_name, GitIntegration};
 pub use pr_summary::{PRSummaryGenerator, SummaryOptions};
 pub use prompt::{PromptBuilder, SpecializedPassKind};
 pub use rules::{active_rules_for_file, load_rules_from_patterns, ReviewRule};
+pub use semantic::{
+    build_feedback_embedding_text, default_index_path, default_semantic_feedback_path,
+    embed_texts_with_fallback, find_similar_feedback_examples, load_semantic_feedback_store,
+    refresh_semantic_index, save_semantic_feedback_store, semantic_context_for_diff,
+    SemanticFeedbackExample, SemanticFeedbackStore,
+};
 pub use smart_review_prompt::SmartReviewPromptBuilder;
 pub use symbol_index::SymbolIndex;

src/core/prompt.rs

@@ -69,15 +69,19 @@ fn shared_review_principles() -> &'static str {
 fn shared_output_contract(category_label: &str, no_issues_message: &str) -> String {
     format!(
         r#"Response contract:
-- Format every finding as:
-  Line [number]{{ [rule:<id>] optional}}: [{category_label}] - [specific problem]. [Impact]. [Smallest safe fix].
-- For concrete local fixes, add this block immediately after the finding:
-  <<<ORIGINAL
-  <code copied from the diff>
-  ===
-  <improved code>
-  >>>SUGGESTED
-- If no relevant issues are found, respond with: {no_issues_message}"#
+ - Preferred format: return a JSON array only. Each finding object must use this schema:
+   {{"line": 42, "category": "{category_label}", "issue": "specific problem", "impact": "why it matters", "fix": "smallest safe fix", "rule_id": "optional.rule.id", "severity": "warning", "confidence": 0.91, "fix_effort": "low", "tags": ["optional-tag"], "original_code": "optional", "suggested_code": "optional"}}
+ - Only include `original_code` and `suggested_code` when you can quote a precise local edit from the diff.
+ - If no relevant issues are found, return `[]`.
+ - Fallback only if strict JSON is impossible:
+   Line [number]{{ [rule:<id>] optional}}: [{category_label}] - [specific problem]. [Impact]. [Smallest safe fix].
+ - For concrete local fixes in fallback mode, add this block immediately after the finding:
+   <<<ORIGINAL
+   <code copied from the diff>
+   ===
+   <improved code>
+   >>>SUGGESTED
+ - If fallback mode finds no relevant issues, respond with: {no_issues_message}"#
     )
 }
 
@@ -471,6 +475,16 @@ mod tests {
             .contains("bugs, security vulnerabilities, or performance issues"));
     }
 
+    #[test]
+    fn default_prompt_prefers_json_output_contract() {
+        let config = PromptConfig::default();
+        assert!(config
+            .system_prompt
+            .contains("Preferred format: return a JSON array only"));
+        assert!(config.system_prompt.contains("\"line\": 42"));
+        assert!(config.system_prompt.contains("return `[]`"));
+    }
+
     #[test]
     fn security_prompt_focuses_on_security() {
         let prompt = build_security_prompt();