kore_fileformat 1.1.4

/// Complete documentation and API guide
///
/// Provides:
/// - API documentation
/// - Query syntax guide
/// - Performance tuning guide
/// - Architecture overview
/// - Troubleshooting guide

/// API documentation
#[derive(Clone, Debug)]
pub struct ApiDocumentation {
    pub title: String,
    pub description: String,
    pub version: String,
    pub endpoints: Vec<ApiEndpoint>,
}

#[derive(Clone, Debug)]
pub struct ApiEndpoint {
    pub path: String,
    pub method: String,
    pub description: String,
    pub request_body: String,
    pub response: String,
    pub examples: Vec<String>,
}

impl ApiDocumentation {
    pub fn new(title: &str, version: &str) -> Self {
        Self {
            title: title.to_string(),
            description:
                "Complete API reference for KORE Query Engine".to_string(),
            version: version.to_string(),
            endpoints: Vec::new(),
        }
    }

    pub fn add_endpoint(mut self, endpoint: ApiEndpoint) -> Self {
        self.endpoints.push(endpoint);
        self
    }

    pub fn format_doc(&self) -> String {
        let mut doc = format!(
            "# {} API Documentation\n\n\
            Version: {}\n\n\
            {}\n\n\
            ## Endpoints\n\n",
            self.title, self.version, self.description
        );

        for endpoint in &self.endpoints {
            doc.push_str(&format!(
                "### {} {}\n\n\
                {}\n\n\
                **Request Body:**\n\
                ```\n\
                {}\n\
                ```\n\n\
                **Response:**\n\
                ```\n\
                {}\n\
                ```\n\n",
                endpoint.method, endpoint.path, endpoint.description, endpoint.request_body,
                endpoint.response
            ));
        }

        doc
    }
}

/// Query syntax guide
#[derive(Clone, Debug)]
pub struct QuerySyntaxGuide {
    pub title: String,
    pub examples: Vec<QueryExample>,
}

#[derive(Clone, Debug)]
pub struct QueryExample {
    pub name: String,
    pub description: String,
    pub query: String,
    pub explanation: String,
}

impl QuerySyntaxGuide {
    pub fn new() -> Self {
        Self {
            title: "KORE Query Syntax Guide".to_string(),
            examples: Vec::new(),
        }
    }

    pub fn add_example(mut self, example: QueryExample) -> Self {
        self.examples.push(example);
        self
    }

    pub fn format_guide(&self) -> String {
        let mut guide = format!("# {}\n\n", self.title);

        for example in &self.examples {
            guide.push_str(&format!(
                "## {}\n\n\
                {}\n\n\
                **Query:**\n\
                ```sql\n\
                {}\n\
                ```\n\n\
                **Explanation:**\n\
                {}\n\n",
                example.name, example.description, example.query, example.explanation
            ));
        }

        guide
    }
}

impl Default for QuerySyntaxGuide {
    fn default() -> Self {
        Self::new()
    }
}

/// Performance tuning guide
#[derive(Clone, Debug)]
pub struct PerformanceTuningGuide {
    pub sections: Vec<TuningSection>,
}

#[derive(Clone, Debug)]
pub struct TuningSection {
    pub title: String,
    pub recommendations: Vec<String>,
    pub expected_improvement: String,
}

impl PerformanceTuningGuide {
    pub fn new() -> Self {
        Self {
            sections: Vec::new(),
        }
    }

    pub fn add_section(mut self, section: TuningSection) -> Self {
        self.sections.push(section);
        self
    }

    pub fn format_guide(&self) -> String {
        let mut guide = "# Performance Tuning Guide\n\n".to_string();

        for section in &self.sections {
            guide.push_str(&format!("## {}\n\n", section.title));
            for rec in &section.recommendations {
                guide.push_str(&format!("- {}\n", rec));
            }
            guide.push_str(&format!(
                "\nExpected Improvement: {}\n\n",
                section.expected_improvement
            ));
        }

        guide
    }
}

impl Default for PerformanceTuningGuide {
    fn default() -> Self {
        Self::new()
    }
}

/// Architecture overview
#[derive(Clone, Debug)]
pub struct ArchitectureOverview {
    pub title: String,
    pub modules: Vec<ModuleDescription>,
    pub data_flow: String,
}

#[derive(Clone, Debug)]
pub struct ModuleDescription {
    pub name: String,
    pub purpose: String,
    pub key_components: Vec<String>,
}

impl ArchitectureOverview {
    pub fn new(title: &str) -> Self {
        Self {
            title: title.to_string(),
            modules: Vec::new(),
            data_flow:
                "Input Query → Parser → Optimizer → Executor → Results"
                    .to_string(),
        }
    }

    pub fn add_module(mut self, module: ModuleDescription) -> Self {
        self.modules.push(module);
        self
    }

    pub fn format_overview(&self) -> String {
        let mut overview = format!(
            "# {} Architecture\n\n\
            ## Data Flow\n\
            {}\n\n\
            ## Modules\n\n",
            self.title, self.data_flow
        );

        for module in &self.modules {
            overview.push_str(&format!(
                "### {}\n\n\
                Purpose: {}\n\n\
                Key Components:\n",
                module.name, module.purpose
            ));

            for component in &module.key_components {
                overview.push_str(&format!("- {}\n", component));
            }
            overview.push('\n');
        }

        overview
    }
}

/// Troubleshooting guide
#[derive(Clone, Debug)]
pub struct TroubleshootingGuide {
    pub issues: Vec<Issue>,
}

#[derive(Clone, Debug)]
pub struct Issue {
    pub symptom: String,
    pub cause: String,
    pub solution: String,
}

impl TroubleshootingGuide {
    pub fn new() -> Self {
        Self {
            issues: Vec::new(),
        }
    }

    pub fn add_issue(mut self, issue: Issue) -> Self {
        self.issues.push(issue);
        self
    }

    pub fn format_guide(&self) -> String {
        let mut guide = "# Troubleshooting Guide\n\n".to_string();

        for issue in &self.issues {
            guide.push_str(&format!(
                "## {}\n\n\
                **Cause:** {}\n\n\
                **Solution:** {}\n\n",
                issue.symptom, issue.cause, issue.solution
            ));
        }

        guide
    }
}

impl Default for TroubleshootingGuide {
    fn default() -> Self {
        Self::new()
    }
}

/// Release notes
#[derive(Clone, Debug)]
pub struct ReleaseNotes {
    pub version: String,
    pub release_date: String,
    pub features: Vec<String>,
    pub improvements: Vec<String>,
    pub bug_fixes: Vec<String>,
    pub breaking_changes: Vec<String>,
}

impl ReleaseNotes {
    pub fn new(version: &str, date: &str) -> Self {
        Self {
            version: version.to_string(),
            release_date: date.to_string(),
            features: Vec::new(),
            improvements: Vec::new(),
            bug_fixes: Vec::new(),
            breaking_changes: Vec::new(),
        }
    }

    pub fn v0_3_0() -> Self {
        Self {
            version: "0.3.0".to_string(),
            release_date: "2026-05-10".to_string(),
            features: vec![
                "Query parallelization (3.4x speedup)".to_string(),
                "Memory pooling (20% reduction)".to_string(),
                "JOIN algorithm optimization (3.5x speedup)".to_string(),
                "Real-world benchmark suite".to_string(),
            ],
            improvements: vec![
                "Query optimization engine".to_string(),
                "Baseline performance tracking".to_string(),
                "Advanced execution strategies".to_string(),
            ],
            bug_fixes: vec!["Fixed borrow checker issues in benchmarking"
                .to_string()],
            breaking_changes: vec![],
        }
    }

    pub fn format_notes(&self) -> String {
        let mut notes = format!(
            "# Release Notes - Version {}\n\n\
            **Release Date:** {}\n\n\
            ## Features\n\n",
            self.version, self.release_date
        );

        for feature in &self.features {
            notes.push_str(&format!("- {}\n", feature));
        }

        notes.push_str("\n## Improvements\n\n");
        for improvement in &self.improvements {
            notes.push_str(&format!("- {}\n", improvement));
        }

        notes.push_str("\n## Bug Fixes\n\n");
        for fix in &self.bug_fixes {
            notes.push_str(&format!("- {}\n", fix));
        }

        if !self.breaking_changes.is_empty() {
            notes.push_str("\n## Breaking Changes\n\n");
            for change in &self.breaking_changes {
                notes.push_str(&format!("- {}\n", change));
            }
        }

        notes
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_api_endpoint() {
        let endpoint = ApiEndpoint {
            path: "/query".to_string(),
            method: "POST".to_string(),
            description: "Execute query".to_string(),
            request_body: "{}".to_string(),
            response: "{}".to_string(),
            examples: vec![],
        };

        assert_eq!(endpoint.method, "POST");
    }

    #[test]
    fn test_api_documentation() {
        let doc = ApiDocumentation::new("KORE API", "1.0.0");
        assert_eq!(doc.version, "1.0.0");
        let formatted = doc.format_doc();
        assert!(formatted.contains("API Documentation"));
    }

    #[test]
    fn test_query_example() {
        let example = QueryExample {
            name: "Simple Select".to_string(),
            description: "Basic SELECT query".to_string(),
            query: "SELECT * FROM users".to_string(),
            explanation: "Returns all rows".to_string(),
        };

        assert_eq!(example.name, "Simple Select");
    }

    #[test]
    fn test_query_syntax_guide() {
        let guide = QuerySyntaxGuide::new();
        let formatted = guide.format_guide();
        assert!(formatted.contains("Query Syntax Guide"));
    }

    #[test]
    fn test_tuning_section() {
        let section = TuningSection {
            title: "Indexing".to_string(),
            recommendations: vec!["Create indexes on filtered columns"
                .to_string()],
            expected_improvement: "2-3x speedup".to_string(),
        };

        assert_eq!(section.title, "Indexing");
    }

    #[test]
    fn test_architecture_overview() {
        let overview = ArchitectureOverview::new("KORE");
        let formatted = overview.format_overview();
        assert!(formatted.contains("Architecture"));
        assert!(formatted.contains("Data Flow"));
    }

    #[test]
    fn test_issue() {
        let issue = Issue {
            symptom: "Query timeout".to_string(),
            cause: "Missing index".to_string(),
            solution: "Create index on filtered column".to_string(),
        };

        assert_eq!(issue.symptom, "Query timeout");
    }

    #[test]
    fn test_troubleshooting_guide() {
        let guide = TroubleshootingGuide::new();
        let formatted = guide.format_guide();
        assert!(formatted.contains("Troubleshooting Guide"));
    }

    #[test]
    fn test_release_notes_v0_3_0() {
        let notes = ReleaseNotes::v0_3_0();
        assert_eq!(notes.version, "0.3.0");
        assert!(notes.features.len() > 0);
        let formatted = notes.format_notes();
        assert!(formatted.contains("0.3.0"));
    }

    #[test]
    fn test_release_notes_formatting() {
        let notes = ReleaseNotes::new("1.0.0", "2026-06-01");
        let formatted = notes.format_notes();
        assert!(formatted.contains("Release Notes"));
        assert!(formatted.contains("1.0.0"));
    }
}