waddling-errors 0.7.3

//! Rendering functionality for DocRegistry

#[cfg(feature = "std")]
use std::{boxed::Box, eprintln, format, path::Path, string::String, vec::Vec};

#[cfg(all(feature = "doc-gen", feature = "runtime-hash", feature = "std"))]
use waddling_errors_hash::load_doc_gen_config;

/// Sanitize a project name for use in filenames
///
/// Replaces characters that are invalid or problematic in filenames with underscores.
/// Preserves alphanumeric characters, hyphens, underscores, and dots.
fn sanitize_filename(name: &str) -> String {
    name.chars()
        .map(|c| {
            if c.is_alphanumeric() || c == '-' || c == '_' || c == '.' {
                c
            } else {
                '_'
            }
        })
        .collect()
}

use super::{
    html,
    registry::DocRegistry,
    renderer::Renderer,
    types::{ComponentLocation, ComponentMeta, ErrorDoc},
};
use crate::traits::Role;

#[cfg(feature = "std")]
use std::collections::HashMap;

/// Create a renderer instance from a format name
///
/// Supported formats:
/// - `"json"` - JSON renderer
/// - `"html"` - HTML renderer
/// - `"catalog"` - Full catalog renderer
/// - `"catalog-compact"` - Compact catalog renderer
/// - `"catalog-min"` - Minimal catalog renderer
///
/// Returns `None` for unknown format names.
#[cfg(feature = "doc-gen")]
#[allow(dead_code)]
fn create_renderer(format: &str) -> Option<Box<dyn Renderer>> {
    match format {
        "json" => Some(Box::new(super::renderer::JsonRenderer)),
        "html" => Some(Box::new(super::renderer::HtmlRenderer::new())),
        "catalog" => Some(Box::new(super::catalog_renderer::CatalogRenderer::new())),
        "catalog-compact" => Some(Box::new(super::catalog_renderer::CatalogRenderer::compact())),
        "catalog-min" => Some(Box::new(super::catalog_renderer::CatalogRenderer::minimal())),
        _ => {
            #[cfg(feature = "std")]
            eprintln!(
                "Warning: Unknown documentation format '{}', skipping",
                format
            );
            None
        }
    }
}

impl DocRegistry {
    /// Render documentation using the provided renderers
    ///
    /// Generates documentation files for all provided renderers without role filtering.
    /// Each renderer will create one file: `{project_name}.{format_name}`
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use waddling_errors::doc_generator::{DocRegistry, JsonRenderer, HtmlRenderer};
    ///
    /// let mut registry = DocRegistry::new("MyProject", "1.0.0");
    /// // ... register errors ...
    ///
    /// registry.render(vec![
    ///     Box::new(JsonRenderer),
    ///     Box::new(HtmlRenderer::new()),
    /// ], "target/docs")?;
    /// // Generates: MyProject.json, MyProject.html
    /// # Ok::<(), std::io::Error>(())
    /// ```
    pub fn render(
        &mut self,
        renderers: Vec<Box<dyn Renderer>>,
        output_dir: impl AsRef<Path>,
    ) -> std::io::Result<()> {
        // Update metadata counts before rendering
        self.update_metadata_counts();

        let dir = output_dir.as_ref();
        std::fs::create_dir_all(dir)?;

        // Render with each renderer (no role filtering, but format filtering applied)
        for renderer in &renderers {
            let format_name = renderer.format_name();

            // Filter errors to only those that requested this format
            // If formats is empty, include the error (backward compatibility for manual registration)
            let error_refs: Vec<&ErrorDoc> = self
                .errors
                .values()
                .filter(|e| e.formats.is_empty() || e.formats.iter().any(|f| f == format_name))
                .collect();

            let sanitized_name = sanitize_filename(&self.project_name);
            let filename = format!("{}.{}", sanitized_name, renderer.format_name());
            let output_path = dir.join(filename);
            renderer.render(self, &error_refs, &output_path, None)?;
        }

        Ok(())
    }

    /// Render documentation with role-based filtering
    ///
    /// Generates documentation files for all provided renderers, creating three files
    /// per renderer (one for each role: Public, Developer, Internal).
    ///
    /// Files are named: `{project_name}-{role}.{format_name}`
    ///
    /// # Role Hierarchy
    ///
    /// - **Public** (`-pub`): Most restrictive, only public-facing errors
    /// - **Developer** (`-dev`): Includes public + developer errors
    /// - **Internal** (`-int`): Least restrictive, includes all errors
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use waddling_errors::doc_generator::{DocRegistry, JsonRenderer, HtmlRenderer};
    ///
    /// let mut registry = DocRegistry::new("MyProject", "1.0.0");
    /// // ... register errors ...
    ///
    /// registry.render_all_roles(vec![
    ///     Box::new(JsonRenderer),
    ///     Box::new(HtmlRenderer::new()),
    /// ], "target/docs")?;
    /// // Generates:
    /// //   MyProject-pub.json, MyProject-pub.html
    /// //   MyProject-dev.json, MyProject-dev.html
    /// //   MyProject-int.json, MyProject-int.html
    /// # Ok::<(), std::io::Error>(())
    /// ```
    pub fn render_all_roles(
        &mut self,
        renderers: Vec<Box<dyn Renderer>>,
        output_dir: impl AsRef<Path>,
    ) -> std::io::Result<()> {
        // Update metadata counts before rendering
        self.update_metadata_counts();

        let dir = output_dir.as_ref();
        std::fs::create_dir_all(dir)?;

        // Render for each renderer
        for renderer in &renderers {
            let format_name = renderer.format_name();

            // Render for each role
            for role in [Role::Public, Role::Developer, Role::Internal] {
                // Filter errors by format AND role, then materialize gated fields
                // If formats is empty, include the error (backward compatibility)
                let filtered: Vec<ErrorDoc> = self
                    .errors
                    .values()
                    .filter(|e| {
                        // First check format filter
                        let format_match =
                            e.formats.is_empty() || e.formats.iter().any(|f| f == format_name);
                        if !format_match {
                            return false;
                        }
                        // Then check role filter
                        let error_role = e.role.as_deref();
                        html::is_visible_at_role(error_role, role)
                    })
                    .map(|e| {
                        let mut filtered_error = e.clone();

                        // Filter code snippets by role
                        filtered_error.code_snippets = e
                            .code_snippets
                            .iter()
                            .filter(|snippet| {
                                let snippet_role = snippet.role.as_deref().or(e.role.as_deref());
                                html::is_visible_at_role(snippet_role, role)
                            })
                            .cloned()
                            .collect();

                        filtered_error
                    })
                    .collect();

                let filtered_errors: Vec<&ErrorDoc> = filtered.iter().collect();

                // Filter component locations by role
                let filtered_components: HashMap<String, ComponentMeta> = self
                    .components
                    .iter()
                    .map(|(name, comp)| {
                        let filtered_locations: Vec<ComponentLocation> = comp
                            .locations
                            .iter()
                            .filter(|loc| html::is_visible_at_role(loc.role.as_deref(), role))
                            .cloned()
                            .collect();

                        let mut filtered_comp = comp.clone();
                        filtered_comp.locations = filtered_locations;
                        (name.clone(), filtered_comp)
                    })
                    .collect();

                // Temporarily swap filtered components
                let original_components =
                    std::mem::replace(&mut self.components, filtered_components);

                let role_suffix = match role {
                    Role::Public => "pub",
                    Role::Developer => "dev",
                    Role::Internal => "int",
                };

                let sanitized_name = sanitize_filename(&self.project_name);
                let filename = format!(
                    "{}-{}.{}",
                    sanitized_name,
                    role_suffix,
                    renderer.format_name()
                );
                let output_path = dir.join(filename);

                // Render with role-filtered data (already filtered, no need for renderer to filter)
                renderer.render(self, &filtered_errors, &output_path, Some(role))?;

                // Restore original components
                self.components = original_components;
            }
        }

        Ok(())
    }

    /// Render documentation using global configuration
    ///
    /// This is a convenience method that automatically loads configuration from:
    /// 1. Environment variables (`WADDLING_DOC_FORMATS`, `WADDLING_DOC_OUTPUT_DIR`)
    /// 2. Cargo.toml `[package.metadata.waddling-errors]`
    /// 3. Default (no generation if no formats configured)
    ///
    /// This method **always generates role-based documentation** (3 files per format),
    /// matching the behavior of the `diag!` macro with auto-registration.
    ///
    /// # Output Files
    ///
    /// For each configured format, generates three files with role filtering:
    /// - `{project}-pub.{format}` - Public role (most restrictive)
    /// - `{project}-dev.{format}` - Developer role (includes public + developer)
    /// - `{project}-int.{format}` - Internal role (least restrictive, all errors)
    ///
    /// # Configuration
    ///
    /// In `Cargo.toml`:
    /// ```toml
    /// [package.metadata.waddling-errors]
    /// doc_formats = ["json", "html"]
    /// doc_output_dir = "target/docs"
    /// ```
    ///
    /// Or via environment variables:
    /// ```bash
    /// WADDLING_DOC_FORMATS=json,html WADDLING_DOC_OUTPUT_DIR=docs cargo build
    /// ```
    ///
    /// # Supported Formats
    ///
    /// - `"json"` - JSON documentation
    /// - `"html"` - HTML documentation
    /// - `"catalog"` - Full catalog (hash-to-error mapping)
    /// - `"catalog-compact"` - Compact catalog
    /// - `"catalog-min"` - Minimal catalog
    ///
    /// Unknown format names are ignored with a warning.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use waddling_errors::doc_generator::DocRegistry;
    /// use waddling_errors::traits::Role;
    ///
    /// let mut registry = DocRegistry::new("MyApp", "1.0.0");
    ///
    /// // Register errors (manual or from macros)
    /// // registry.register_code_extended(...)?;
    ///
    /// // Generate docs using global config (Cargo.toml or env vars)
    /// registry.render_with_global_config()?;
    ///
    /// // If doc_formats = ["json", "html"], generates:
    /// //   MyApp-pub.json, MyApp-dev.json, MyApp-int.json
    /// //   MyApp-pub.html, MyApp-dev.html, MyApp-int.html
    /// # Ok::<(), std::io::Error>(())
    /// ```
    ///
    /// # Returns
    ///
    /// - `Ok(())` if documentation was generated successfully or no formats configured
    /// - `Err(io::Error)` if file writing fails
    ///
    /// # Feature Requirements
    ///
    /// Requires both `doc-gen` and `hash` features to be enabled.
    #[cfg(all(feature = "doc-gen", feature = "runtime-hash"))]
    pub fn render_with_global_config(&mut self) -> std::io::Result<()> {
        // Load global configuration from Cargo.toml or environment variables
        let config = load_doc_gen_config();

        // If no formats configured, do nothing (not an error)
        if config.formats.is_empty() {
            return Ok(());
        }

        // Create renderer instances from format names
        let renderers: Vec<Box<dyn Renderer>> = config
            .formats
            .iter()
            .filter_map(|fmt| create_renderer(fmt))
            .collect();

        // If no valid renderers created, do nothing
        if renderers.is_empty() {
            return Ok(());
        }

        // Always use role-based rendering (3 files per format)
        self.render_all_roles(renderers, config.output_dir)
    }
}

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

    #[test]
    fn test_sanitize_filename_spaces() {
        assert_eq!(sanitize_filename("My Project"), "My_Project");
        assert_eq!(sanitize_filename("Web App System"), "Web_App_System");
    }

    #[test]
    fn test_sanitize_filename_special_chars() {
        assert_eq!(sanitize_filename("Web/API:Server"), "Web_API_Server");
        assert_eq!(sanitize_filename("Test<>Project"), "Test__Project");
        assert_eq!(sanitize_filename("Project?Name!"), "Project_Name_");
        assert_eq!(sanitize_filename("file|name*here"), "file_name_here");
    }

    #[test]
    fn test_sanitize_filename_preserves_safe_chars() {
        assert_eq!(sanitize_filename("v1.0.0"), "v1.0.0");
        assert_eq!(sanitize_filename("my-app_v2"), "my-app_v2");
        assert_eq!(sanitize_filename("test.app-name_123"), "test.app-name_123");
    }

    #[test]
    fn test_sanitize_filename_unicode() {
        // Unicode alphanumeric should be preserved
        assert_eq!(sanitize_filename("Überproject"), "Überproject");
        assert_eq!(sanitize_filename("项目名称"), "项目名称");
        assert_eq!(sanitize_filename("プロジェクト"), "プロジェクト");
    }

    #[test]
    fn test_sanitize_filename_mixed() {
        assert_eq!(sanitize_filename("My Project: v1.0"), "My_Project__v1.0");
        assert_eq!(
            sanitize_filename("Test (beta) [2024]"),
            "Test__beta___2024_"
        );
    }

    #[test]
    fn test_sanitize_filename_edge_cases() {
        assert_eq!(sanitize_filename(""), "");
        assert_eq!(sanitize_filename("___"), "___");
        assert_eq!(sanitize_filename("..."), "...");
        assert_eq!(sanitize_filename("123"), "123");
    }

    #[cfg(feature = "doc-gen")]
    #[test]
    fn test_create_renderer_json() {
        let renderer = create_renderer("json");
        assert!(renderer.is_some());
        assert_eq!(renderer.unwrap().format_name(), "json");
    }

    #[cfg(feature = "doc-gen")]
    #[test]
    fn test_create_renderer_html() {
        let renderer = create_renderer("html");
        assert!(renderer.is_some());
        assert_eq!(renderer.unwrap().format_name(), "html");
    }

    #[cfg(feature = "doc-gen")]
    #[test]
    fn test_create_renderer_catalog_variants() {
        let catalog = create_renderer("catalog");
        assert!(catalog.is_some());
        assert_eq!(catalog.unwrap().format_name(), "catalog");

        let compact = create_renderer("catalog-compact");
        assert!(compact.is_some());
        assert_eq!(compact.unwrap().format_name(), "catalog-compact");

        let minimal = create_renderer("catalog-min");
        assert!(minimal.is_some());
        assert_eq!(minimal.unwrap().format_name(), "catalog-min");
    }

    #[cfg(feature = "doc-gen")]
    #[test]
    fn test_create_renderer_unknown_format() {
        let renderer = create_renderer("unknown-format");
        assert!(renderer.is_none());
    }

    #[cfg(all(feature = "doc-gen", feature = "runtime-hash"))]
    #[test]
    fn test_render_with_global_config_no_formats() {
        // When no formats are configured, should not error
        let mut registry = DocRegistry::new("TestProject", "1.0.0");

        // Should succeed with no-op when formats list is empty
        let result = registry.render_with_global_config();
        assert!(result.is_ok());
    }
}