waddling-errors 0.7.3

#[cfg(feature = "std")]
use std::string::String;

/// Metadata for sequence definitions (only available with `metadata` feature)
///
/// This struct is used by the `sequence!` macro to store compile-time metadata
/// about sequence numbers, which can be used for documentation generation and
/// enhanced error messages.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SequenceMetadata {
    /// The sequence number (1-999)
    pub number: u16,

    /// The constant name of the sequence (e.g., "MISSING")
    pub name: &'static str,

    /// Optional description of what this sequence represents
    pub description: Option<&'static str>,

    /// Typical severity level for errors in this sequence
    pub typical_severity: Option<&'static str>,

    /// Hints for resolving errors in this sequence
    pub hints: &'static [&'static str],

    /// Related error codes or sequences
    pub related: &'static [&'static str],

    /// Version/date when this sequence was introduced
    pub introduced: Option<&'static str>,
}

impl SequenceMetadata {
    /// Check if this sequence has any metadata beyond just the number and name
    pub const fn has_metadata(&self) -> bool {
        self.description.is_some()
            || self.typical_severity.is_some()
            || !self.hints.is_empty()
            || !self.related.is_empty()
            || self.introduced.is_some()
    }
}

/// Runtime diagnostic metadata for error handling
///
/// This struct contains ONLY the essential information needed at runtime for
/// error handling, categorization, and user-facing messages. Documentation-heavy
/// fields (descriptions, code examples) are NOT included to minimize binary size.
///
/// Use this for production error handling where documentation is not needed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DiagnosticRuntime {
    /// The severity level (Error, Warning, Info, etc.)
    pub severity: crate::Severity,

    /// Optional namespace identifier for multi-service environments
    ///
    /// When set, enables WDP Part 7 combined IDs (e.g., "nsHash-codeHash").
    /// Format: lowercase with underscores (e.g., "auth_service", "payment_lib")
    pub namespace: Option<&'static str>,

    /// Pre-computed 5-character base62 namespace hash (WDP Part 7)
    ///
    /// Computed using xxHash64 with seed "wdp-ns-v1" at compile time.
    /// Only present when `namespace` is set.
    pub namespace_hash: Option<&'static str>,

    /// The component identifier
    pub component: &'static str,

    /// The primary category identifier
    pub primary: &'static str,

    /// The sequence identifier (constant name like "MISSING")
    pub sequence: &'static str,

    /// The sequence numeric value (e.g., 1 for MISSING)
    pub sequence_value: u16,

    /// The full error code string (e.g., "E.CRYPTO.SALT.001")
    pub code: &'static str,

    /// Message template with {{field}} placeholders
    ///
    /// Use `{{field}}` for regular fields and `{{pii/field}}` for PII fields.
    /// Example: `"Token for {{pii/email}} expired at {{timestamp}}"`
    pub message: &'static str,

    /// Non-PII field names used in the message template
    ///
    /// These are referenced as `{{field}}` in the message and sent in the `f` object
    /// in the wire protocol.
    pub fields: &'static [&'static str],

    /// PII field names used in the message template
    ///
    /// These are referenced as `{{pii/field}}` in the message and sent in the
    /// `pii.data` object in the wire protocol. Clients should handle these with
    /// appropriate access control and redaction.
    pub pii_fields: &'static [&'static str],

    /// Whether this diagnostic contains PII placeholders
    ///
    /// Automatically derived from whether `pii_fields` is non-empty.
    /// Useful for quick filtering and compliance checks.
    pub contains_pii: bool,

    /// Role-based visibility: "Public", "Developer", or "Internal"
    pub role: Option<&'static str>,

    /// Tags for categorization and filtering
    pub tags: &'static [&'static str],

    /// Related error codes for cross-referencing
    pub related_codes: &'static [&'static str],

    /// Runtime hints (end-user facing)
    pub hints_runtime: &'static [&'static str],

    /// Hints available in both runtime and compile-time contexts
    pub hints_both: &'static [&'static str],

    /// Role-gated hints for runtime context (for doc generation)
    /// Format: [("hint", "Public"), ("hint2", "Developer"), ...]
    #[cfg(feature = "metadata")]
    pub hints_runtime_gated: &'static [(&'static str, &'static str)],

    /// Role-gated hints for both contexts (for doc generation)
    /// Format: [("hint", "Public"), ("hint2", "Developer"), ...]
    #[cfg(feature = "metadata")]
    pub hints_both_gated: &'static [(&'static str, &'static str)],

    /// Role-gated tags (for doc generation)
    /// Format: [("tag", "Public"), ("tag2", "Developer"), ...]
    #[cfg(feature = "metadata")]
    pub tags_gated: &'static [(&'static str, &'static str)],

    /// Role-gated related codes (for doc generation)
    /// Format: [("code", "Public"), ("code2", "Developer"), ...]
    #[cfg(feature = "metadata")]
    pub related_codes_gated: &'static [(&'static str, &'static str)],

    /// Pre-computed 5-character base62 hash
    ///
    /// This hash is computed at compile time using the global hash configuration
    /// and embedded as a constant. It provides a compact identifier for the error
    /// code that can be used in logs, catalogs, and network protocols.
    pub hash: &'static str,
}

/// A code snippet definition for documentation
///
/// This struct represents a single code example with rich metadata including
/// language, correct/incorrect code, explanation, and role-based visibility.
#[cfg(feature = "metadata")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CodeSnippetDef {
    /// Programming language for syntax highlighting (e.g., "rust", "javascript", "python")
    pub language: Option<&'static str>,

    /// Code snippet showing incorrect usage
    pub wrong: Option<&'static str>,

    /// Code snippet showing correct usage
    pub correct: Option<&'static str>,

    /// Explanation of why the correct version is better
    pub explanation: Option<&'static str>,

    /// Role-based visibility: "Public", "Developer", or "Internal"
    pub role: &'static str,
}

/// Compile-time documentation metadata
///
/// This struct contains verbose documentation, code examples, and detailed
/// explanations that are ONLY used during documentation generation. These fields
/// are NOT included in runtime binaries when the `metadata` feature is disabled.
///
/// Use this for generating comprehensive documentation while keeping production
/// binaries lean.
#[cfg(feature = "metadata")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DiagnosticDocs {
    /// Human-readable description (can be verbose)
    pub description: Option<&'static str>,

    /// Role-gated code snippets with rich metadata
    /// Multiple snippets allowed, each with its own role visibility
    pub code_snippets: &'static [CodeSnippetDef],

    /// URL to detailed documentation
    pub docs_url: Option<&'static str>,

    /// Version when this diagnostic was introduced
    pub introduced: Option<&'static str>,

    /// Version when this diagnostic was deprecated (if applicable)
    pub deprecated: Option<&'static str>,

    /// Compile-time hints (developer/documentation facing)
    pub hints_compiletime: &'static [&'static str],

    /// Related error codes for documentation cross-referencing
    pub see_also: &'static [&'static str],

    /// Role-gated hints for compile-time context (for doc generation)
    /// Format: [("hint", "Public"), ("hint2", "Developer"), ...]
    #[cfg(feature = "metadata")]
    pub hints_compiletime_gated: &'static [(&'static str, &'static str)],

    /// Role-gated see also (for doc generation)
    /// Format: [("code", "Public"), ("code2", "Developer"), ...]
    #[cfg(feature = "metadata")]
    pub see_also_gated: &'static [(&'static str, &'static str)],
}

/// Complete diagnostic with both runtime and documentation metadata
///
/// This combines DiagnosticRuntime (always present) with DiagnosticDocs
/// (only with metadata feature). Use this for comprehensive documentation
/// generation where all information is needed.
#[cfg(feature = "metadata")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DiagnosticComplete {
    /// Runtime metadata (always present)
    pub runtime: DiagnosticRuntime,

    /// Compile-time documentation (only with metadata feature)
    pub docs: Option<DiagnosticDocs>,
}

#[cfg(feature = "metadata")]
impl crate::traits::ErrorMetadata for DiagnosticComplete {
    fn code(&self) -> &'static str {
        self.runtime.code
    }

    fn description(&self) -> Option<&'static str> {
        // First try to get from docs, then fall back to None
        self.docs.as_ref().and_then(|d| d.description)
    }

    fn hints(&self) -> &'static [&'static str] {
        // Combine runtime and docs hints
        // For now, return runtime hints + both contexts
        // Note: This is a limitation - we can't dynamically combine slices into a new static slice
        // So we'll return just the runtime hints
        self.runtime.hints_runtime
    }

    fn role(&self) -> crate::traits::Role {
        // Parse the role string from runtime metadata
        match self.runtime.role {
            Some("Public") => crate::traits::Role::Public,
            Some("Developer") => crate::traits::Role::Developer,
            Some("Internal") => crate::traits::Role::Internal,
            _ => crate::traits::Role::Public, // Default to Public
        }
    }

    fn docs_url(&self) -> Option<&'static str> {
        self.docs.as_ref().and_then(|d| d.docs_url)
    }

    fn examples(&self) -> &'static [&'static str] {
        // Return the message as an example
        &[]
    }

    fn related_codes(&self) -> &'static [&'static str] {
        // Combine runtime related_codes and docs see_also
        // For now, just return runtime related_codes
        self.runtime.related_codes
    }

    fn since_version(&self) -> Option<&'static str> {
        self.docs.as_ref().and_then(|d| d.introduced)
    }
}

/// Complete diagnostic metadata with full 4-part error code
///
/// **DEPRECATED**: Use `DiagnosticRuntime` for runtime error handling,
/// `DiagnosticDocs` for compile-time documentation, or `DiagnosticComplete`
/// for both. This struct is kept for backward compatibility.
///
/// This struct is generated by the `diag!` macro and provides comprehensive
/// documentation for a complete diagnostic definition. Unlike the individual
/// component/primary/sequence metadata, this represents a **complete error**
/// with all parts and usage information.
///
/// This is used **only for documentation generation** - frameworks like QuackPatch
/// build their own invocation layer on top of this metadata.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DiagnosticMetadata {
    /// The severity level (Error, Warning, Info, etc.)
    pub severity: crate::Severity,

    /// The component identifier
    pub component: &'static str,

    /// The primary category identifier
    pub primary: &'static str,

    /// The sequence identifier (constant name like "MISSING")
    pub sequence: &'static str,

    /// The sequence numeric value (e.g., 1 for MISSING)
    pub sequence_value: u16,

    /// Message template with {field} placeholders
    pub message: &'static str,

    /// Field names used in the message template
    pub fields: &'static [&'static str],

    /// Human-readable description of this diagnostic
    pub description: Option<&'static str>,

    /// Helpful hints for resolving this diagnostic
    pub hints: &'static [&'static str],

    /// Role-gated code snippets with rich metadata
    #[cfg(feature = "metadata")]
    pub code_snippets: &'static [CodeSnippetDef],

    /// Role-based visibility: "Public", "Developer", or "Internal"
    pub role: Option<&'static str>,

    /// Tags for categorization and filtering
    pub tags: &'static [&'static str],

    /// Related error codes for cross-referencing
    pub related_codes: &'static [&'static str],

    /// URL to detailed documentation
    pub docs_url: Option<&'static str>,

    /// Version when this diagnostic was introduced
    pub introduced: Option<&'static str>,

    /// Version when this diagnostic was deprecated (if applicable)
    pub deprecated: Option<&'static str>,
}

impl DiagnosticRuntime {
    /// Default values for metadata-gated fields (used with .. syntax in struct initialization)
    #[cfg(feature = "metadata")]
    pub const INIT_WITH_DEFAULTS: Self = Self {
        severity: crate::Severity::Error,
        namespace: None,
        namespace_hash: None,
        component: "",
        primary: "",
        sequence: "",
        sequence_value: 0,
        code: "",
        message: "",
        fields: &[],
        pii_fields: &[],
        contains_pii: false,
        role: None,
        tags: &[],
        related_codes: &[],
        hints_runtime: &[],
        hints_both: &[],
        hints_runtime_gated: &[],
        hints_both_gated: &[],
        tags_gated: &[],
        related_codes_gated: &[],
        hash: "",
    };

    /// Default values for non-metadata builds (used with .. syntax in struct initialization)
    #[cfg(not(feature = "metadata"))]
    pub const INIT_WITH_DEFAULTS: Self = Self {
        severity: crate::Severity::Error,
        namespace: None,
        namespace_hash: None,
        component: "",
        primary: "",
        sequence: "",
        sequence_value: 0,
        code: "",
        message: "",
        fields: &[],
        pii_fields: &[],
        contains_pii: false,
        role: None,
        tags: &[],
        related_codes: &[],
        hints_runtime: &[],
        hints_both: &[],
        hash: "",
    };

    /// Get the full diagnostic code as parts (severity, component, primary, sequence)
    pub const fn code_parts(&self) -> (&'static str, &'static str, &'static str, &'static str) {
        // Use single character severity codes (E, W, I, C, B, T, H, S, K)
        let severity_str = match self.severity {
            crate::Severity::Error => "E",
            crate::Severity::Warning => "W",
            crate::Severity::Info => "I",
            crate::Severity::Critical => "C",
            crate::Severity::Blocked => "B",
            crate::Severity::Trace => "T",
            crate::Severity::Help => "H",
            crate::Severity::Success => "S",
            crate::Severity::Completed => "K",
        };
        (severity_str, self.component, self.primary, self.sequence)
    }

    /// Get the full diagnostic code as a string (e.g., "E.Auth.InvalidCredentials.MISSING")
    ///
    /// Note: This uses the sequence NAME. For canonical format with numeric sequence,
    /// use `canonical_code()` instead.
    #[cfg(feature = "std")]
    pub fn full_code(&self) -> String {
        let (sev, comp, prim, seq) = self.code_parts();
        std::format!("{}.{}.{}.{}", sev, comp, prim, seq)
    }

    /// Get the canonical diagnostic code with zero-padded numeric sequence (e.g., "E.AUTH.TOKEN.001")
    ///
    /// This is the WDP-conformant format used in documentation and wire protocols.
    /// Component and primary are always uppercased to ensure canonical form.
    #[cfg(feature = "std")]
    pub fn canonical_code(&self) -> String {
        let severity_str = match self.severity {
            crate::Severity::Error => "E",
            crate::Severity::Warning => "W",
            crate::Severity::Info => "I",
            crate::Severity::Critical => "C",
            crate::Severity::Blocked => "B",
            crate::Severity::Trace => "T",
            crate::Severity::Help => "H",
            crate::Severity::Success => "S",
            crate::Severity::Completed => "K",
        };
        std::format!(
            "{}.{}.{}.{:03}",
            severity_str,
            self.component.to_ascii_uppercase(),
            self.primary.to_ascii_uppercase(),
            self.sequence_value
        )
    }

    /// Check if this diagnostic has field placeholders
    pub const fn has_fields(&self) -> bool {
        !self.fields.is_empty()
    }

    /// Check if this diagnostic has any hints (runtime or both)
    pub const fn has_hints(&self) -> bool {
        !self.hints_runtime.is_empty() || !self.hints_both.is_empty()
    }

    /// Get all runtime hints (combines runtime-specific and both)
    pub fn all_hints(&self) -> impl Iterator<Item = &&'static str> {
        self.hints_runtime.iter().chain(self.hints_both.iter())
    }

    /// Check if this diagnostic has a namespace
    pub const fn has_namespace(&self) -> bool {
        self.namespace.is_some()
    }

    /// Get the compact ID (5-character hash)
    ///
    /// Returns the pre-computed hash for this diagnostic code.
    pub const fn compact_id(&self) -> &'static str {
        self.hash
    }

    /// Get the combined ID (WDP Part 7 format: "nsHash-codeHash")
    ///
    /// Returns the 11-character combined ID if namespace is set,
    /// otherwise returns just the 5-character compact ID.
    ///
    /// # Examples
    ///
    /// ```ignore
    /// // With namespace: "h4tYw2-81E9g"
    /// // Without namespace: "81E9g"
    /// let id = diag.combined_id();
    /// ```
    #[cfg(feature = "std")]
    pub fn combined_id(&self) -> std::string::String {
        match self.namespace_hash {
            Some(ns_hash) => std::format!("{}-{}", ns_hash, self.hash),
            None => std::string::String::from(self.hash),
        }
    }
}

#[cfg(feature = "metadata")]
impl DiagnosticDocs {
    /// Check if this diagnostic has any hints (compile-time or both)
    pub const fn has_hints(&self) -> bool {
        !self.hints_compiletime.is_empty()
    }

    /// Check if this has any documentation beyond basic fields
    pub const fn has_comprehensive_docs(&self) -> bool {
        self.description.is_some()
            || !self.code_snippets.is_empty()
            || self.docs_url.is_some()
            || !self.hints_compiletime.is_empty()
    }
}

#[cfg(feature = "metadata")]
impl DiagnosticComplete {
    /// Get the full diagnostic code as parts (severity, component, primary, sequence)
    pub const fn code_parts(&self) -> (&'static str, &'static str, &'static str, &'static str) {
        self.runtime.code_parts()
    }

    /// Get the full diagnostic code as a string (uses sequence NAME)
    ///
    /// For canonical format with numeric sequence, use `canonical_code()` instead.
    #[cfg(feature = "std")]
    pub fn full_code(&self) -> String {
        self.runtime.full_code()
    }

    /// Get the canonical diagnostic code with zero-padded numeric sequence (e.g., "E.AUTH.TOKEN.001")
    ///
    /// This is the WDP-conformant format used in documentation and wire protocols.
    #[cfg(feature = "std")]
    pub fn canonical_code(&self) -> String {
        self.runtime.canonical_code()
    }

    /// Get all hints (runtime + both + compile-time)
    pub fn all_hints(&self) -> impl Iterator<Item = &'static str> + '_ {
        let runtime_hints = self.runtime.hints_runtime.iter().copied();
        let both_hints = self.runtime.hints_both.iter().copied();
        let compile_hints = self
            .docs
            .as_ref()
            .map(|d| d.hints_compiletime.iter().copied())
            .into_iter()
            .flatten();

        runtime_hints.chain(both_hints).chain(compile_hints)
    }
}

impl DiagnosticMetadata {
    /// Get the full diagnostic code as parts (severity, component, primary, sequence)
    pub const fn code_parts(&self) -> (&'static str, &'static str, &'static str, &'static str) {
        // Use single character severity codes (E, W, I, C, B, T, H, S, K)
        let severity_str = match self.severity {
            crate::Severity::Error => "E",
            crate::Severity::Warning => "W",
            crate::Severity::Info => "I",
            crate::Severity::Critical => "C",
            crate::Severity::Blocked => "B",
            crate::Severity::Trace => "T",
            crate::Severity::Help => "H",
            crate::Severity::Success => "S",
            crate::Severity::Completed => "K",
        };
        (severity_str, self.component, self.primary, self.sequence)
    }

    /// Get the full diagnostic code as a string (e.g., "Error.Auth.InvalidCredentials.MISSING")
    #[cfg(feature = "std")]
    pub fn full_code(&self) -> String {
        let (sev, comp, prim, seq) = self.code_parts();
        std::format!("{}.{}.{}.{}", sev, comp, prim, seq)
    }

    /// Check if this diagnostic has field placeholders
    pub const fn has_fields(&self) -> bool {
        !self.fields.is_empty()
    }

    /// Check if this diagnostic has hints
    pub const fn has_hints(&self) -> bool {
        !self.hints.is_empty()
    }
}