waddling-errors 0.7.3

//! Catalog Renderer - Efficient Documentation Distribution
//!
//! This module provides a renderer that generates a catalog (lookup table)
//! mapping error hashes to their documentation. This enables:
//!
//! - **Compact network payloads**: Send hash + fields instead of full error
//! - **Client-side i18n**: Translate catalog locally
//! - **Offline support**: Cache catalog for offline use
//! - **IoT efficiency**: Devices send tiny payloads, server expands with catalog
//!
//! ## Use Cases
//!
//! ### 1. IoT Devices
//! ```text
//! Device: Sends "hCF3I,45.2" (12 bytes)
//! Server: Has catalog, expands to "E.SENSOR.TEMP.OVERHEAT: temp=45.2°C"
//! ```
//!
//! ### 2. Mobile Apps
//! ```text
//! Initial: Download catalog once (50 KB)
//! Ongoing: API sends {"h": "hCF3I", "f": {...}} (40 bytes)
//! App: Looks up hash in cached catalog
//! ```
//!
//! ### 3. Multi-language Support
//! ```text
//! English catalog: {"hCF3I": {"message": "Token expired"}}
//! Spanish catalog: {"hCF3I": {"message": "Token expirado"}}
//! Client picks language-specific catalog
//! ```

use crate::doc_generator::{DocRegistry, renderer::Renderer, types::ErrorDoc};
use crate::traits::Role;
use std::format;
#[cfg(feature = "runtime-hash")]
use std::fs::File;
#[cfg(feature = "runtime-hash")]
use std::io::Write;
use std::path::Path;
use std::string::String;

/// Catalog format type
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CatalogFormat {
    /// Full format with all documentation fields
    Full,
    /// Compact format with minimal fields for production
    Compact,
    /// Minimal format with only essential fields (smallest)
    Minimal,
}

/// Catalog renderer for generating hash-to-error lookup tables
///
/// This renderer creates a JSON catalog that maps error hashes to their
/// documentation, enabling efficient error transmission and client-side expansion.
///
/// ## Output Format (Full)
///
/// ```json
/// {
///   "version": "1.0.0",
///   "generated": "2024-11-19T15:00:00Z",
///   "algorithm": "base62-ahash-v1",
///   "role": "Public",
///   "errors": {
///     "hCF3I": {
///       "code": "E.AUTH.TOKEN.001",
///       "severity": "Error",
///       "message": "Token expired at {expiry}",
///       "hints": ["Use refresh token endpoint"],
///       "tags": ["auth", "security"],
///       "docs_url": "https://docs.example.com/errors/E.AUTH.TOKEN.001"
///     }
///   }
/// }
/// ```
///
/// ## Output Format (Compact)
///
/// ```json
/// {
///   "v": "1.0.0",
///   "a": "base62-ahash-v1",
///   "e": {
///     "hCF3I": ["E.AUTH.TOKEN.001", "E", "Token expired at {expiry}"]
///   }
/// }
/// ```
///
/// ## Output Format (Minimal)
///
/// ```json
/// {
///   "hCF3I": ["E.AUTH.TOKEN.001", "Token expired at {expiry}"]
/// }
/// ```
pub struct CatalogRenderer {
    format: CatalogFormat,
    include_hints: bool,
    include_tags: bool,
    include_docs_url: bool,
}

impl CatalogRenderer {
    /// Create a new catalog renderer with full format
    pub fn new() -> Self {
        Self {
            format: CatalogFormat::Full,
            include_hints: true,
            include_tags: true,
            include_docs_url: true,
        }
    }

    /// Create a catalog renderer with compact format
    pub fn compact() -> Self {
        Self {
            format: CatalogFormat::Compact,
            include_hints: true,
            include_tags: false,
            include_docs_url: false,
        }
    }

    /// Create a catalog renderer with minimal format (smallest size)
    pub fn minimal() -> Self {
        Self {
            format: CatalogFormat::Minimal,
            include_hints: false,
            include_tags: false,
            include_docs_url: false,
        }
    }

    /// Set the catalog format
    pub fn with_format(mut self, format: CatalogFormat) -> Self {
        self.format = format;
        self
    }

    /// Set whether to include hints
    pub fn with_hints(mut self, include: bool) -> Self {
        self.include_hints = include;
        self
    }

    /// Set whether to include tags
    pub fn with_tags(mut self, include: bool) -> Self {
        self.include_tags = include;
        self
    }

    /// Set whether to include docs URL
    pub fn with_docs_url(mut self, include: bool) -> Self {
        self.include_docs_url = include;
        self
    }

    /// Render catalog in full format (WDP Part 9a compliant)
    ///
    /// Output format:
    /// ```json
    /// {
    ///   "version": "1.0.0",
    ///   "generated": "2024-01-15T10:30:00Z",
    ///   "namespace": "auth_service",       // optional
    ///   "namespace_hash": "h4tYw2",        // optional
    ///   "diags": {
    ///     "jGKFp": {
    ///       "code": "E.AUTH.TOKEN.001",
    ///       "severity": "E",
    ///       "message": "Token expired at {{timestamp}}",
    ///       "description": "The JWT token has exceeded its TTL",
    ///       "hints": ["Use /auth/refresh endpoint"],
    ///       "tags": ["auth", "security"],
    ///       "fields": ["timestamp"]
    ///     }
    ///   }
    /// }
    /// ```
    #[allow(dead_code, unused_variables, unused_mut)]
    fn render_full(
        &self,
        registry: &DocRegistry,
        errors: &[&ErrorDoc],
        filter_role: Option<Role>,
    ) -> String {
        let mut output = String::from("{\n");
        output.push_str(&format!("  \"version\": \"{}\",\n", registry.version()));

        // Generate timestamp (fallback to 0 if system time is before UNIX_EPOCH)
        let timestamp = match std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH) {
            Ok(dur) => dur.as_secs(),
            Err(_) => 0,
        };
        output.push_str(&format!("  \"generated\": \"{}\",\n", timestamp));

        // Check if we have namespace info from the first error (all should share same namespace)
        // Use registry.first_error() for deterministic access (lexicographically smallest code)
        #[cfg(feature = "runtime-hash")]
        if let Some(first_error) = registry.first_error()
            && let Some(ns) = &first_error.namespace
        {
            output.push_str(&format!("  \"namespace\": \"{}\",\n", escape_json(ns)));
            if let Some(ns_hash) = &first_error.namespace_hash {
                output.push_str(&format!("  \"namespace_hash\": \"{}\",\n", ns_hash));
            }
        }

        if let Some(role) = filter_role {
            output.push_str(&format!("  \"role\": \"{:?}\",\n", role));
        }

        // WDP 9a: Use "diags" not "errors"
        output.push_str("  \"diags\": {\n");

        let mut first = true;
        for error in errors {
            #[cfg(feature = "runtime-hash")]
            {
                // Use combined_id() for namespace-aware catalogs
                if let Some(key) = error.combined_id() {
                    if !first {
                        output.push_str(",\n");
                    }
                    first = false;

                    output.push_str(&format!("    \"{}\": {{\n", key));
                    output.push_str(&format!("      \"code\": \"{}\",\n", error.code));
                    output.push_str(&format!("      \"severity\": \"{}\",\n", error.severity));

                    // WDP 9a: message is the template with {{field}} placeholders
                    let message_template = convert_to_wdp_placeholders(&error.message);
                    output.push_str(&format!(
                        "      \"message\": \"{}\",\n",
                        escape_json(&message_template)
                    ));

                    // WDP 9a: description is the detailed explanation
                    if !error.description.is_empty() {
                        output.push_str(&format!(
                            "      \"description\": \"{}\",\n",
                            escape_json(&error.description)
                        ));
                    }

                    if self.include_hints {
                        let hints = filter_role
                            .map(|r| error.hints_for_role(r))
                            .unwrap_or_default();
                        output.push_str("      \"hints\": [");
                        for (i, hint) in hints.iter().enumerate() {
                            if i > 0 {
                                output.push_str(", ");
                            }
                            output.push_str(&format!("\"{}\"", escape_json(hint)));
                        }
                        output.push_str("],\n");
                    }

                    if self.include_tags {
                        let tags = filter_role
                            .map(|r| error.tags_for_role(r))
                            .unwrap_or_default();
                        output.push_str("      \"tags\": [");
                        for (i, tag) in tags.iter().enumerate() {
                            if i > 0 {
                                output.push_str(", ");
                            }
                            output.push_str(&format!("\"{}\"", escape_json(tag)));
                        }
                        output.push_str("],\n");
                    }

                    // WDP 9a: fields array listing placeholder names
                    if !error.fields.is_empty() {
                        output.push_str("      \"fields\": [");
                        for (i, field) in error.fields.iter().enumerate() {
                            if i > 0 {
                                output.push_str(", ");
                            }
                            output.push_str(&format!("\"{}\"", escape_json(field)));
                        }
                        output.push_str("],\n");
                    }

                    if self.include_docs_url
                        && let Some(url) = &error.docs_url
                    {
                        output.push_str(&format!("      \"docs_url\": \"{}\",\n", url));
                    }

                    // Remove trailing comma from last field
                    if output.ends_with(",\n") {
                        output.truncate(output.len() - 2);
                        output.push('\n');
                    }

                    output.push_str("    }");
                }
            }

            #[cfg(not(feature = "runtime-hash"))]
            {
                // Without hash feature, skip this error
                let _ = error;
            }
        }

        output.push_str("\n  }\n");
        output.push_str("}\n");
        output
    }

    /// Render catalog in compact format (WDP Part 9a compliant)
    ///
    /// Output format uses abbreviated field names:
    /// - `v` → version
    /// - `g` → generated
    /// - `ns` → namespace (optional)
    /// - `nsh` → namespace_hash (optional)
    /// - `wd` → diags
    /// - `c` → code, `s` → severity, `m` → message, `d` → description
    /// - `h` → hints, `t` → tags, `f` → fields
    #[allow(dead_code, unused_variables, unused_mut)]
    fn render_compact(
        &self,
        registry: &DocRegistry,
        errors: &[&ErrorDoc],
        filter_role: Option<Role>,
    ) -> String {
        let mut output = String::from("{\"v\":\"");
        output.push_str(registry.version());
        output.push('"');

        // Add namespace info if present
        // Use registry.first_error() for deterministic access (lexicographically smallest code)
        #[cfg(feature = "runtime-hash")]
        if let Some(first_error) = registry.first_error()
            && let Some(ns) = &first_error.namespace
        {
            output.push_str(",\"ns\":\"");
            output.push_str(&escape_json(ns));
            output.push('"');
            if let Some(ns_hash) = &first_error.namespace_hash {
                output.push_str(",\"nsh\":\"");
                output.push_str(ns_hash);
                output.push('"');
            }
        }

        // WDP 9a: Use "wd" for diags (compact)
        output.push_str(",\"wd\":{");

        let mut first = true;
        for error in errors {
            #[cfg(feature = "runtime-hash")]
            {
                if let Some(key) = error.combined_id() {
                    if !first {
                        output.push(',');
                    }
                    first = false;

                    output.push('"');
                    output.push_str(&key);
                    output.push_str("\":{\"c\":\"");
                    output.push_str(&error.code);
                    output.push_str("\",\"s\":\"");
                    output.push_str(&error.severity);
                    output.push_str("\",\"m\":\"");
                    let message_template = convert_to_wdp_placeholders(&error.message);
                    output.push_str(&escape_json(&message_template));
                    output.push('"');

                    if !error.description.is_empty() {
                        output.push_str(",\"d\":\"");
                        output.push_str(&escape_json(&error.description));
                        output.push('"');
                    }

                    if self.include_hints {
                        let hints = filter_role
                            .map(|r| error.hints_for_role(r))
                            .unwrap_or_default();
                        if !hints.is_empty() {
                            output.push_str(",\"h\":[");
                            for (i, hint) in hints.iter().enumerate() {
                                if i > 0 {
                                    output.push(',');
                                }
                                output.push('"');
                                output.push_str(&escape_json(hint));
                                output.push('"');
                            }
                            output.push(']');
                        }
                    }

                    if self.include_tags {
                        let tags = filter_role
                            .map(|r| error.tags_for_role(r))
                            .unwrap_or_default();
                        if !tags.is_empty() {
                            output.push_str(",\"t\":[");
                            for (i, tag) in tags.iter().enumerate() {
                                if i > 0 {
                                    output.push(',');
                                }
                                output.push('"');
                                output.push_str(&escape_json(tag));
                                output.push('"');
                            }
                            output.push(']');
                        }
                    }

                    if !error.fields.is_empty() {
                        output.push_str(",\"f\":[");
                        for (i, field) in error.fields.iter().enumerate() {
                            if i > 0 {
                                output.push(',');
                            }
                            output.push('"');
                            output.push_str(&escape_json(field));
                            output.push('"');
                        }
                        output.push(']');
                    }

                    output.push('}');
                }
            }

            #[cfg(not(feature = "runtime-hash"))]
            {
                let _ = error;
            }
        }

        output.push_str("}}");
        output
    }

    /// Render catalog in minimal format (WDP Part 9a compliant)
    ///
    /// Output format - array-based, smallest size:
    /// ```json
    /// {
    ///   "jGKFp": ["E.AUTH.TOKEN.001", "Token expired at {{timestamp}}"]
    /// }
    /// ```
    #[allow(dead_code, unused_variables, unused_mut)]
    fn render_minimal(&self, errors: &[&ErrorDoc], _filter_role: Option<Role>) -> String {
        let mut output = String::from("{");

        let mut first = true;
        for error in errors {
            #[cfg(feature = "runtime-hash")]
            {
                if let Some(key) = error.combined_id() {
                    if !first {
                        output.push(',');
                    }
                    first = false;

                    output.push('"');
                    output.push_str(&key);
                    output.push_str("\":[\"");
                    output.push_str(&error.code);
                    output.push_str("\",\"");
                    let message_template = convert_to_wdp_placeholders(&error.message);
                    output.push_str(&escape_json(&message_template));
                    output.push_str("\"]");
                }
            }

            #[cfg(not(feature = "runtime-hash"))]
            {
                let _ = error;
            }
        }

        output.push('}');
        output
    }
}

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

impl Renderer for CatalogRenderer {
    fn format_name(&self) -> &str {
        match self.format {
            CatalogFormat::Full => "catalog",
            CatalogFormat::Compact => "catalog-compact",
            CatalogFormat::Minimal => "catalog-min",
        }
    }

    #[allow(unused_variables)]
    fn render(
        &self,
        registry: &DocRegistry,
        errors: &[&ErrorDoc],
        output_path: &Path,
        filter_role: Option<Role>,
    ) -> std::io::Result<()> {
        #[cfg(not(feature = "runtime-hash"))]
        {
            Err(std::io::Error::new(
                std::io::ErrorKind::Unsupported,
                "Catalog renderer requires the 'hash' feature to be enabled",
            ))
        }

        #[cfg(feature = "runtime-hash")]
        {
            let content = match self.format {
                CatalogFormat::Full => self.render_full(registry, errors, filter_role),
                CatalogFormat::Compact => self.render_compact(registry, errors, filter_role),
                CatalogFormat::Minimal => self.render_minimal(errors, filter_role),
            };

            let mut file = File::create(output_path)?;
            file.write_all(content.as_bytes())?;
            Ok(())
        }
    }
}

/// Escape JSON special characters per RFC 8259
///
/// Escapes:
/// - `"` → `\"`
/// - `\` → `\\`
/// - `/` → `\/` (prevents XSS when embedded in HTML script tags)
/// - Control characters U+0000-U+001F:
///   - `\b` (U+0008), `\t` (U+0009), `\n` (U+000A), `\f` (U+000C), `\r` (U+000D)
///   - Others as `\uXXXX`
#[allow(dead_code)]
fn escape_json(s: &str) -> String {
    let mut result = String::with_capacity(s.len() + 16);
    for c in s.chars() {
        match c {
            '"' => result.push_str("\\\""),
            '\\' => result.push_str("\\\\"),
            '/' => result.push_str("\\/"), // solidus - prevents </script> XSS in HTML embedding
            '\u{0008}' => result.push_str("\\b"), // backspace
            '\u{0009}' => result.push_str("\\t"), // tab
            '\u{000A}' => result.push_str("\\n"), // newline
            '\u{000C}' => result.push_str("\\f"), // form feed
            '\u{000D}' => result.push_str("\\r"), // carriage return
            // Other control characters (U+0000-U+001F except those above)
            c if c < '\u{0020}' => {
                result.push_str(&format!("\\u{:04x}", c as u32));
            }
            c => result.push(c),
        }
    }
    result
}

/// Convert single-brace placeholders {field} to WDP double-brace {{field}}
///
/// WDP Part 9a requires double-brace syntax for field placeholders in messages.
/// This function converts existing single-brace templates to WDP format.
///
/// # Examples
/// - `"Token expired at {timestamp}"` → `"Token expired at {{timestamp}}"`
/// - `"User {user_id} not found"` → `"User {{user_id}} not found"`
#[allow(dead_code)]
fn convert_to_wdp_placeholders(message: &str) -> String {
    let mut result = String::with_capacity(message.len() * 2);
    let mut chars = message.chars().peekable();

    while let Some(c) = chars.next() {
        if c == '{' {
            // Check if it's already double-braced
            if chars.peek() == Some(&'{') {
                // Already WDP format, keep as-is
                result.push('{');
                result.push(chars.next().unwrap());
            } else {
                // Single brace, convert to double
                result.push_str("{{");
            }
        } else if c == '}' {
            // Check if it's already double-braced
            if chars.peek() == Some(&'}') {
                // Already WDP format, keep as-is
                result.push('}');
                result.push(chars.next().unwrap());
            } else {
                // Single brace, convert to double
                result.push_str("}}");
            }
        } else {
            result.push(c);
        }
    }

    result
}

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

    #[test]
    fn test_escape_json() {
        // Basic strings unchanged
        assert_eq!(escape_json("hello"), "hello");

        // Quote and backslash escaping
        assert_eq!(escape_json("hello\"world"), "hello\\\"world");
        assert_eq!(escape_json("back\\slash"), "back\\\\slash");

        // Common control characters (shorthand escapes)
        assert_eq!(escape_json("line1\nline2"), "line1\\nline2");
        assert_eq!(escape_json("tab\there"), "tab\\there");
        assert_eq!(escape_json("return\rhere"), "return\\rhere");
        assert_eq!(escape_json("form\x0Cfeed"), "form\\ffeed");
        assert_eq!(escape_json("back\x08space"), "back\\bspace");

        // Other control characters (U+0000-U+001F) as \uXXXX
        assert_eq!(escape_json("null\x00char"), "null\\u0000char");
        assert_eq!(escape_json("bell\x07ring"), "bell\\u0007ring");
        assert_eq!(escape_json("escape\x1Bseq"), "escape\\u001bseq");

        // Combined escaping
        assert_eq!(
            escape_json("quote\"tab\tnull\x00end"),
            "quote\\\"tab\\tnull\\u0000end"
        );

        // Unicode passthrough (non-control chars are fine)
        assert_eq!(escape_json("日本語"), "日本語");
        assert_eq!(escape_json("emoji 🦆"), "emoji 🦆");
    }

    #[test]
    fn test_convert_to_wdp_placeholders() {
        // Single brace to double brace
        assert_eq!(
            convert_to_wdp_placeholders("Token expired at {timestamp}"),
            "Token expired at {{timestamp}}"
        );

        // Multiple fields
        assert_eq!(
            convert_to_wdp_placeholders("User {user_id} has {count} items"),
            "User {{user_id}} has {{count}} items"
        );

        // Already double-braced (WDP format) - keep as-is
        assert_eq!(
            convert_to_wdp_placeholders("Already {{formatted}}"),
            "Already {{formatted}}"
        );

        // No placeholders
        assert_eq!(
            convert_to_wdp_placeholders("No placeholders here"),
            "No placeholders here"
        );
    }

    #[test]
    fn test_catalog_format_types() {
        let full = CatalogRenderer::new();
        assert_eq!(full.format_name(), "catalog");

        let compact = CatalogRenderer::compact();
        assert_eq!(compact.format_name(), "catalog-compact");

        let minimal = CatalogRenderer::minimal();
        assert_eq!(minimal.format_name(), "catalog-min");
    }

    #[test]
    fn test_catalog_builder() {
        let renderer = CatalogRenderer::new()
            .with_format(CatalogFormat::Compact)
            .with_hints(false)
            .with_tags(false);

        assert_eq!(renderer.format, CatalogFormat::Compact);
        assert!(!renderer.include_hints);
        assert!(!renderer.include_tags);
    }
}