kardo_core/pro/

recommendations.rs

//! AI Recommendations Engine — generates recommendations locally or via cloud.
//!
//! Strategy:
//! 1. If cloud client available and connected → use Claude (better quality)
//! 2. If cloud unavailable → use local Ollama (basic recommendations)
//! 3. If Ollama unavailable → return rule-based fallback recommendations

use crate::anonymize::Anonymizer;
use crate::llm::ollama::OllamaClient;
use crate::llm::GenerateRequest;
use crate::scoring::{ProjectScore, QualityIssue};

use super::cloud::{
    AnalyzeRequest, CloudClient, FixSuggestion, Recommendation,
};

/// Safely truncate a string to at most `max_bytes` bytes without splitting a
/// multi-byte UTF-8 character.
fn safe_truncate(s: &str, max_bytes: usize) -> &str {
    if s.len() <= max_bytes {
        return s;
    }
    let mut end = max_bytes;
    while end > 0 && !s.is_char_boundary(end) {
        end -= 1;
    }
    &s[..end]
}

/// Generates AI-powered recommendations for project quality improvement.
pub struct RecommendationEngine {
    cloud_client: Option<CloudClient>,
    anonymizer: Anonymizer,
}

impl RecommendationEngine {
    /// Create a new engine, optionally with a cloud client for Claude-based analysis.
    pub fn new(cloud_client: Option<CloudClient>) -> Self {
        Self {
            cloud_client,
            anonymizer: Anonymizer::new(),
        }
    }

    /// Generate recommendations for quality issues.
    ///
    /// Tries cloud first, falls back to local Ollama, then rule-based.
    pub async fn generate_recommendations(
        &self,
        score: &ProjectScore,
        issues: &[QualityIssue],
    ) -> Vec<Recommendation> {
        // Try cloud first
        if let Some(client) = &self.cloud_client {
            let prompt = Self::build_recommendation_prompt(score, issues);
            let anonymized = self.anonymizer.anonymize(&prompt);

            let request = AnalyzeRequest {
                content: anonymized.text,
                document_type: "project_analysis".to_string(),
                context: Some(format!(
                    "Score: {:.0}/100, Traffic: {:?}",
                    score.total * 100.0,
                    score.traffic_light
                )),
                task: "recommend".to_string(),
            };

            if let Ok(response) = client.analyze(request).await {
                return response.recommendations;
            }
        }

        // Try local Ollama
        if let Some(recommendations) = self.try_ollama_recommendations(score, issues).await {
            return recommendations;
        }

        // Fallback: rule-based recommendations
        Self::rule_based_recommendations(score, issues)
    }

    /// Generate a fix suggestion for a specific issue.
    ///
    /// Tries cloud first, falls back to local Ollama.
    pub async fn suggest_fix(
        &self,
        issue: &QualityIssue,
        file_content: &str,
    ) -> Option<FixSuggestion> {
        // Anonymize the file content
        let anonymized = self.anonymizer.anonymize(file_content);

        // Try cloud
        if let Some(client) = &self.cloud_client {
            if let Ok(suggestions) = client
                .get_fix_suggestions(vec![issue.clone()], &anonymized.text)
                .await
            {
                if let Some(mut suggestion) = suggestions.into_iter().next() {
                    // De-anonymize the suggestion
                    suggestion.suggestion = Anonymizer::deanonymize(
                        &suggestion.suggestion,
                        &anonymized.replacements,
                    );
                    if let Some(snippet) = &suggestion.code_snippet {
                        suggestion.code_snippet = Some(Anonymizer::deanonymize(
                            snippet,
                            &anonymized.replacements,
                        ));
                    }
                    return Some(suggestion);
                }
            }
        }

        // Try local Ollama
        self.try_ollama_fix(issue, &anonymized.text, &anonymized.replacements)
            .await
    }

    /// Build prompt for generating recommendations.
    fn build_recommendation_prompt(score: &ProjectScore, issues: &[QualityIssue]) -> String {
        let mut prompt = String::new();
        prompt.push_str(
            "You are a code documentation quality expert. \
             Analyze the following project health data and provide 3-5 actionable recommendations \
             to improve the project's documentation and AI-readiness.\n\n",
        );

        prompt.push_str(&format!(
            "## Project Score: {:.0}/100 (Traffic Light: {:?})\n\n",
            score.total * 100.0,
            score.traffic_light
        ));

        prompt.push_str("### Component Scores:\n");
        prompt.push_str(&format!(
            "- Freshness: {:.0}/100\n",
            score.components.freshness
        ));
        prompt.push_str(&format!(
            "- Configuration: {:.0}/100\n",
            score.components.configuration
        ));
        prompt.push_str(&format!(
            "- Integrity: {:.0}/100\n",
            score.components.integrity
        ));
        prompt.push_str(&format!(
            "- Agent Setup: {:.0}/100\n",
            score.components.agent_setup
        ));
        prompt.push_str(&format!(
            "- Structure: {:.0}/100\n\n",
            score.components.structure
        ));

        if !issues.is_empty() {
            prompt.push_str("### Quality Issues Found:\n");
            for (i, issue) in issues.iter().enumerate().take(10) {
                prompt.push_str(&format!(
                    "{}. [{:?}] {:?}: {} — {}\n",
                    i + 1,
                    issue.severity,
                    issue.category,
                    issue.title,
                    issue.attribution
                ));
                if let Some(suggestion) = &issue.suggestion {
                    prompt.push_str(&format!("   Suggestion: {}\n", suggestion));
                }
            }
            prompt.push('\n');
        }

        prompt.push_str(
            "Respond in JSON format with an array of recommendations:\n\
             ```json\n\
             [{\"title\": \"...\", \"description\": \"...\", \"priority\": \"high|medium|low\", \"category\": \"...\"}]\n\
             ```\n\
             Focus on the most impactful changes first. Be specific and actionable.",
        );

        prompt
    }

    /// Build prompt for generating a fix suggestion.
    fn build_fix_prompt(issue: &QualityIssue, content: &str) -> String {
        let mut prompt = String::new();
        prompt.push_str(
            "You are a documentation quality expert. \
             Given this quality issue in a documentation file, suggest a specific fix.\n\n",
        );

        prompt.push_str("## Issue\n");
        prompt.push_str(&format!("- Title: {}\n", issue.title));
        prompt.push_str(&format!("- Category: {:?}\n", issue.category));
        prompt.push_str(&format!("- Severity: {:?}\n", issue.severity));
        prompt.push_str(&format!("- Details: {}\n", issue.attribution));
        if let Some(suggestion) = &issue.suggestion {
            prompt.push_str(&format!("- Existing suggestion: {}\n", suggestion));
        }
        prompt.push('\n');

        // Include a truncated version of the file content
        let truncated = safe_truncate(content, 2000);
        prompt.push_str(&format!(
            "## File Content (may be truncated)\n```\n{}\n```\n\n",
            truncated
        ));

        prompt.push_str(
            "Respond in JSON format:\n\
             ```json\n\
             {\"suggestion\": \"...\", \"confidence\": 0.0-1.0, \"code_snippet\": \"...or null\"}\n\
             ```\n\
             Provide a clear, actionable suggestion. Include a code_snippet if applicable.",
        );

        prompt
    }

    /// Try to generate recommendations using local Ollama.
    async fn try_ollama_recommendations(
        &self,
        score: &ProjectScore,
        issues: &[QualityIssue],
    ) -> Option<Vec<Recommendation>> {
        let client = OllamaClient::new();
        let status = client.check_status().await;
        if !status.available {
            return None;
        }

        let prompt = Self::build_recommendation_prompt(score, issues);
        let anonymized = self.anonymizer.anonymize(&prompt);

        let request = GenerateRequest {
            prompt: anonymized.text,
            max_tokens: 1024,
            temperature: 0.3,
        };

        match client.generate(&request).await {
            Ok(response) => parse_recommendations_json(&response.text),
            Err(_) => None,
        }
    }

    /// Try to generate a fix suggestion using local Ollama.
    async fn try_ollama_fix(
        &self,
        issue: &QualityIssue,
        anonymized_content: &str,
        replacements: &[crate::anonymize::Replacement],
    ) -> Option<FixSuggestion> {
        let client = OllamaClient::new();
        let status = client.check_status().await;
        if !status.available {
            return None;
        }

        let prompt = Self::build_fix_prompt(issue, anonymized_content);

        let request = GenerateRequest {
            prompt,
            max_tokens: 512,
            temperature: 0.3,
        };

        match client.generate(&request).await {
            Ok(response) => {
                if let Some(mut fix) = parse_fix_json(&response.text, &issue.id) {
                    // De-anonymize
                    fix.suggestion =
                        Anonymizer::deanonymize(&fix.suggestion, replacements);
                    if let Some(snippet) = &fix.code_snippet {
                        fix.code_snippet =
                            Some(Anonymizer::deanonymize(snippet, replacements));
                    }
                    Some(fix)
                } else {
                    None
                }
            }
            Err(_) => None,
        }
    }

    /// Rule-based fallback recommendations when no AI is available.
    fn rule_based_recommendations(
        score: &ProjectScore,
        issues: &[QualityIssue],
    ) -> Vec<Recommendation> {
        let mut recommendations = Vec::new();

        // Check freshness
        if score.components.freshness < 60.0 {
            recommendations.push(Recommendation {
                title: "Update stale documentation".to_string(),
                description: "Several documentation files haven't been updated recently. \
                    Review and update files that are out of sync with your codebase."
                    .to_string(),
                priority: "high".to_string(),
                category: "freshness".to_string(),
            });
        }

        // Check configuration
        if score.components.configuration < 60.0 {
            recommendations.push(Recommendation {
                title: "Improve project configuration files".to_string(),
                description: "Your README or CLAUDE.md may be missing important sections. \
                    Consider adding installation instructions, usage examples, and contribution guidelines."
                    .to_string(),
                priority: "high".to_string(),
                category: "configuration".to_string(),
            });
        }

        // Check integrity
        if score.components.integrity < 80.0 {
            recommendations.push(Recommendation {
                title: "Fix broken internal links".to_string(),
                description: "Some documentation files contain broken links to other files. \
                    Verify all internal references point to existing files."
                    .to_string(),
                priority: "medium".to_string(),
                category: "integrity".to_string(),
            });
        }

        // Check agent setup
        if score.components.agent_setup < 50.0 {
            recommendations.push(Recommendation {
                title: "Set up AI agent configuration".to_string(),
                description: "Add a CLAUDE.md or .claude/instructions file to guide AI coding assistants. \
                    This improves AI-readiness and helps agents understand your project."
                    .to_string(),
                priority: "medium".to_string(),
                category: "agent_setup".to_string(),
            });
        }

        // Check structure
        if score.components.structure < 60.0 {
            recommendations.push(Recommendation {
                title: "Organize documentation structure".to_string(),
                description: "Consider creating a docs/ directory and organizing documentation \
                    by topic (guides, API reference, architecture)."
                    .to_string(),
                priority: "low".to_string(),
                category: "structure".to_string(),
            });
        }

        // Add issue-specific recommendations for high severity
        let high_issues: Vec<_> = issues
            .iter()
            .filter(|i| matches!(i.severity, crate::scoring::IssueSeverity::Blocking | crate::scoring::IssueSeverity::High))
            .take(2)
            .collect();

        for issue in high_issues {
            if let Some(suggestion) = &issue.suggestion {
                recommendations.push(Recommendation {
                    title: issue.title.clone(),
                    description: suggestion.clone(),
                    priority: "high".to_string(),
                    category: format!("{:?}", issue.category).to_lowercase(),
                });
            }
        }

        // Limit to 5
        recommendations.truncate(5);
        recommendations
    }
}

/// Try to parse recommendation JSON from an LLM response.
fn parse_recommendations_json(text: &str) -> Option<Vec<Recommendation>> {
    // Try to find JSON array in the response
    let trimmed = text.trim();

    // Try direct parse
    if let Ok(recs) = serde_json::from_str::<Vec<Recommendation>>(trimmed) {
        return Some(recs);
    }

    // Try to extract from markdown code block
    if let Some(start) = trimmed.find('[') {
        if let Some(end) = trimmed.rfind(']') {
            let json_str = &trimmed[start..=end];
            if let Ok(recs) = serde_json::from_str::<Vec<Recommendation>>(json_str) {
                return Some(recs);
            }
        }
    }

    None
}

/// Try to parse fix suggestion JSON from an LLM response.
fn parse_fix_json(text: &str, issue_id: &str) -> Option<FixSuggestion> {
    let trimmed = text.trim();

    #[derive(serde::Deserialize)]
    struct PartialFix {
        suggestion: String,
        confidence: f64,
        code_snippet: Option<String>,
    }

    // Try direct parse
    if let Ok(fix) = serde_json::from_str::<PartialFix>(trimmed) {
        return Some(FixSuggestion {
            issue_id: issue_id.to_string(),
            suggestion: fix.suggestion,
            confidence: fix.confidence,
            code_snippet: fix.code_snippet,
        });
    }

    // Try to extract from markdown code block
    if let Some(start) = trimmed.find('{') {
        if let Some(end) = trimmed.rfind('}') {
            let json_str = &trimmed[start..=end];
            if let Ok(fix) = serde_json::from_str::<PartialFix>(json_str) {
                return Some(FixSuggestion {
                    issue_id: issue_id.to_string(),
                    suggestion: fix.suggestion,
                    confidence: fix.confidence,
                    code_snippet: fix.code_snippet,
                });
            }
        }
    }

    None
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::scoring::{
        IssueCategory, IssueSeverity, ProjectScore, QualityIssue, TrafficLight,
    };
    use crate::scoring::types::ComponentScores;

    fn make_test_score(total: f64) -> ProjectScore {
        ProjectScore {
            total,
            components: ComponentScores {
                freshness: total * 100.0,
                configuration: total * 100.0,
                integrity: total * 100.0,
                agent_setup: total * 100.0,
                structure: total * 100.0,
            },
            traffic_light: TrafficLight::from_score(total),
            issues: vec![],
        }
    }

    fn make_test_issues() -> Vec<QualityIssue> {
        vec![
            QualityIssue::new(
                "stale-001".to_string(),
                Some("README.md".to_string()),
                IssueCategory::Freshness,
                IssueSeverity::High,
                "README.md is stale".to_string(),
                "Not updated in 90 days".to_string(),
                Some("Update README.md with current project status".to_string()),
            ),
            QualityIssue::new(
                "integrity-001".to_string(),
                Some("docs/guide.md".to_string()),
                IssueCategory::Integrity,
                IssueSeverity::Medium,
                "Broken link in guide.md".to_string(),
                "Link to setup.md is broken".to_string(),
                Some("Fix or remove the broken link".to_string()),
            ),
        ]
    }

    #[test]
    fn test_build_recommendation_prompt() {
        let score = make_test_score(0.65);
        let issues = make_test_issues();
        let prompt = RecommendationEngine::build_recommendation_prompt(&score, &issues);

        assert!(prompt.contains("documentation quality expert"));
        assert!(prompt.contains("65/100"));
        assert!(prompt.contains("README.md is stale"));
        assert!(prompt.contains("JSON format"));
    }

    #[test]
    fn test_build_fix_prompt() {
        let issue = make_test_issues().remove(0);
        let content = "# README\n\nOld content here.";
        let prompt = RecommendationEngine::build_fix_prompt(&issue, content);

        assert!(prompt.contains("README.md is stale"));
        assert!(prompt.contains("Old content here"));
        assert!(prompt.contains("JSON format"));
    }

    #[test]
    fn test_rule_based_recommendations_low_score() {
        let mut score = make_test_score(0.4);
        score.components.freshness = 40.0;
        score.components.configuration = 30.0;
        score.components.agent_setup = 20.0;
        let issues = make_test_issues();

        let recs = RecommendationEngine::rule_based_recommendations(&score, &issues);
        assert!(!recs.is_empty());
        assert!(recs.len() <= 5);
        // Should have freshness and configuration recommendations
        assert!(recs.iter().any(|r| r.category == "freshness"));
        assert!(recs.iter().any(|r| r.category == "configuration"));
    }

    #[test]
    fn test_rule_based_recommendations_high_score() {
        let score = make_test_score(0.95);
        let recs = RecommendationEngine::rule_based_recommendations(&score, &[]);
        // High score = few or no recommendations
        assert!(recs.is_empty());
    }

    #[test]
    fn test_parse_recommendations_json_direct() {
        let json = r#"[{"title":"Test","description":"Desc","priority":"high","category":"structure"}]"#;
        let recs = parse_recommendations_json(json);
        assert!(recs.is_some());
        assert_eq!(recs.unwrap().len(), 1);
    }

    #[test]
    fn test_parse_recommendations_json_in_code_block() {
        let text = "Here are my recommendations:\n```json\n[{\"title\":\"Test\",\"description\":\"Desc\",\"priority\":\"low\",\"category\":\"docs\"}]\n```";
        let recs = parse_recommendations_json(text);
        assert!(recs.is_some());
    }

    #[test]
    fn test_parse_fix_json() {
        let json = r##"{"suggestion":"Add a header","confidence":0.88,"code_snippet":"# Header"}"##;
        let fix = parse_fix_json(json, "test-001");
        assert!(fix.is_some());
        let fix = fix.unwrap();
        assert_eq!(fix.issue_id, "test-001");
        assert!((fix.confidence - 0.88).abs() < f64::EPSILON);
    }

    #[test]
    fn test_parse_fix_json_invalid() {
        let fix = parse_fix_json("not json at all", "test-001");
        assert!(fix.is_none());
    }

    #[tokio::test]
    async fn test_generate_recommendations_no_cloud_no_ollama() {
        // No cloud, no Ollama running → should return rule-based
        let engine = RecommendationEngine::new(None);
        let mut score = make_test_score(0.4);
        score.components.freshness = 30.0;
        let issues = make_test_issues();

        let recs = engine.generate_recommendations(&score, &issues).await;
        // Should get fallback rule-based recommendations
        assert!(!recs.is_empty());
    }
}