graph_d 1.3.2

//! Error types for GQL operations.

use std::fmt;

/// Result type for GQL operations.
pub type GqlResult<T> = std::result::Result<T, GqlError>;

/// Errors that can occur during GQL parsing and execution.
///
/// This enum represents all possible error conditions in the GQL subsystem,
/// from lexical analysis through execution. Each variant includes contextual
/// information to help diagnose and fix the issue.
///
/// # Security Note
///
/// Error messages include structural information (positions, names, types)
/// but never include property values to prevent sensitive data leakage.
/// Satisfies: S3 (No sensitive data in error messages)
#[derive(Debug, Clone)]
pub enum GqlError {
    /// Lexical analysis error during tokenization.
    ///
    /// Occurs when the input contains invalid characters or malformed tokens.
    LexError {
        /// Human-readable description of the lexical error
        message: String,
        /// Character position in the input where the error occurred
        position: usize,
    },
    /// Parse error during syntax analysis.
    ///
    /// Occurs when the token sequence doesn't match valid GQL grammar.
    ParseError {
        /// Human-readable description of the parse error
        message: String,
        /// The problematic token that caused the parse failure, if available
        token: Option<String>,
        /// Character position in the input where the error occurred
        position: usize,
    },
    /// Semantic error during validation.
    ///
    /// Occurs when the query is syntactically valid but semantically incorrect
    /// (e.g., referencing undefined variables).
    SemanticError {
        /// Human-readable description of the semantic error
        message: String,
    },
    /// Execution error during query evaluation.
    ///
    /// Occurs when a valid query cannot be executed against the graph.
    ExecutionError {
        /// Human-readable description of the execution error
        message: String,
    },
    /// Graph database error from the underlying storage layer.
    GraphError(crate::GraphError),
    /// Type mismatch error in expressions or comparisons.
    ///
    /// Occurs when an operation receives incompatible types.
    TypeError {
        /// The type that was expected
        expected: String,
        /// The type that was actually provided
        found: String,
    },
    /// Variable not found in query scope.
    VariableNotFound {
        /// The name of the undefined variable
        name: String,
    },
    /// Label not found on node.
    LabelNotFound {
        /// The name of the missing label
        name: String,
    },
    /// Property not found on node or relationship.
    PropertyNotFound {
        /// The name of the missing property (key only, never the value)
        name: String,
    },
}

impl fmt::Display for GqlError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            GqlError::LexError { message, position } => {
                write!(f, "Lexical error at position {position}: {message}")
            }
            GqlError::ParseError {
                message,
                token,
                position,
            } => {
                if let Some(token) = token {
                    write!(
                        f,
                        "Parse error at position {position} near '{token}': {message}"
                    )
                } else {
                    write!(f, "Parse error at position {position}: {message}")
                }
            }
            GqlError::SemanticError { message } => {
                write!(f, "Semantic error: {message}")
            }
            GqlError::ExecutionError { message } => {
                write!(f, "Execution error: {message}")
            }
            GqlError::GraphError(err) => {
                write!(f, "Graph error: {err}")
            }
            GqlError::TypeError { expected, found } => {
                write!(f, "Type error: expected {expected}, found {found}")
            }
            GqlError::VariableNotFound { name } => {
                write!(f, "Variable not found: {name}")
            }
            GqlError::LabelNotFound { name } => {
                write!(f, "Label not found: {name}")
            }
            GqlError::PropertyNotFound { name } => {
                write!(f, "Property not found: {name}")
            }
        }
    }
}

impl std::error::Error for GqlError {}

impl From<crate::GraphError> for GqlError {
    fn from(err: crate::GraphError) -> Self {
        GqlError::GraphError(err)
    }
}