"""
Configuration-specific exceptions.

Provides a unified exception hierarchy for all configuration-related errors
across the MarkiTect project.
"""

from typing import Optional, Dict, Any


class ConfigurationError(Exception):
    """Base exception for configuration-related errors.

    Provides enhanced error context and troubleshooting guidance.

    Args:
        message: Human-readable error description
        field: Specific configuration field that caused the error
        value: The invalid value (if applicable)
        suggestion: Suggested fix for the error
        context: Additional context information
    """

    def __init__(self,
                 message: str,
                 field: Optional[str] = None,
                 value: Optional[Any] = None,
                 suggestion: Optional[str] = None,
                 context: Optional[Dict[str, Any]] = None):
        super().__init__(message)
        self.field = field
        self.value = value
        self.suggestion = suggestion
        self.context = context or {}

    def __str__(self) -> str:
        """Enhanced string representation with troubleshooting guidance."""
        parts = [super().__str__()]

        if self.field:
            parts.append(f"Field: {self.field}")

        if self.value is not None:
            parts.append(f"Value: {self.value}")

        if self.suggestion:
            parts.append(f"Suggestion: {self.suggestion}")

        return " | ".join(parts)


class ConfigValidationError(ConfigurationError):
    """Configuration validation specific errors.

    Raised when configuration values fail validation checks.
    """
    pass


class ConfigFileError(ConfigurationError):
    """Configuration file related errors.

    Raised when configuration files cannot be read, parsed, or found.
    """
    pass


class EnvironmentVariableError(ConfigurationError):
    """Environment variable related errors.

    Raised when required environment variables are missing or invalid.
    """
    pass