markitect-main/markitect/exceptions.py

"""
Markitect domain-specific exceptions.

This module provides a hierarchy of exceptions for the Markitect markdown processing system.
All exceptions preserve context and support proper exception chaining.
"""

from typing import Optional, Dict, Any


class MarkitectError(Exception):
    """Base exception for all Markitect operations.

    Provides enhanced error context and proper exception chaining support.

    Args:
        message: Human-readable error description
        cause: Original exception that caused this error (for chaining)
        context: Additional context information as key-value pairs
    """

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

        # Automatically chain if cause is provided
        if cause:
            self.__cause__ = cause

    def __str__(self) -> str:
        """Enhanced string representation with context."""
        base_message = super().__str__()

        if self.context:
            context_info = ", ".join(f"{k}={v}" for k, v in self.context.items())
            base_message = f"{base_message} [Context: {context_info}]"

        return base_message


class DocumentError(MarkitectError):
    """Errors related to document processing and management.

    Raised when:
    - Document parsing fails
    - Document structure is invalid
    - Document metadata is corrupt
    """
    pass


class ASTError(MarkitectError):
    """Errors related to Abstract Syntax Tree operations.

    Raised when:
    - AST parsing fails
    - AST structure is invalid
    - AST transformation fails
    """
    pass


class CacheError(MarkitectError):
    """Errors related to cache operations.

    Raised when:
    - Cache read/write operations fail
    - Cache corruption is detected
    - Cache invalidation fails
    """
    pass


class DatabaseError(MarkitectError):
    """Errors related to database operations.

    Raised when:
    - Database connection fails
    - Query execution fails
    - Data integrity violations occur
    """
    pass


class SchemaError(MarkitectError):
    """Errors related to schema validation and processing.

    Raised when:
    - Schema validation fails
    - Schema parsing errors occur
    - Schema generation fails
    """
    pass


class ValidationError(MarkitectError):
    """Errors related to document validation against schemas.

    Raised when:
    - Document doesn't match schema
    - Validation rules are violated
    - Required fields are missing
    """
    pass


class GraphQLError(MarkitectError):
    """Errors related to GraphQL operations.

    Raised when:
    - GraphQL query parsing fails
    - GraphQL execution errors occur
    - GraphQL schema issues are encountered
    """
    pass


class ConfigurationError(MarkitectError):
    """Errors related to configuration and setup.

    Raised when:
    - Configuration files are missing or invalid
    - Environment setup is incomplete
    - Required settings are not configured
    """
    pass


class FileNotFoundError(MarkitectError):
    """Errors when requested files cannot be found.

    Raised when:
    - Markdown files don't exist at specified paths
    - Required resource files are missing
    - Cache files cannot be located
    """
    pass


class InvalidDepthError(MarkitectError):
    """Errors related to invalid depth parameters.

    Raised when:
    - Depth parameters are negative or zero
    - Depth values exceed reasonable limits
    - Depth configuration is invalid
    """
    pass


class SchemaValidationError(MarkitectError):
    """Errors during schema validation process.

    Raised when:
    - Schema validation process fails
    - Document structure analysis fails
    - Validation comparison encounters errors
    """
    pass


class InvalidSchemaError(MarkitectError):
    """Errors related to invalid JSON schemas.

    Raised when:
    - JSON schema format is invalid
    - Schema doesn't conform to JSON Schema specification
    - Schema file cannot be loaded or parsed
    """
    pass


class InvalidInstructionTypeError(MarkitectError):
    """Errors related to invalid content instruction types.

    Raised when:
    - Instruction type is not one of the supported types
    - Instruction type parameter is malformed
    - Instruction type conflicts with other options
    """
    pass