optionstratlib_core/error/

position.rs

/******************************************************************************
   Author: Joaquín Béjar García
   Email: jb@taunais.com
   Date: 20/12/24
******************************************************************************/

//! # Position Error Module
//!
//! This module provides error handling for position-related operations in option trading strategies.
//! It defines error types to handle various scenarios related to position validation, strategy
//! operations, and position limits.
//!
//! ## Error Types
//!
//! ### Position Error (`PositionError`)
//! The main error type with six variants:
//! * `StrategyError` - For strategy operation failures
//! * `ValidationError` - For position validation failures
//! * `LimitError` - For position limit violations
//! * `UpdateError` - For position update failures
//! * `DecimalError` - For `Decimal` arithmetic failures
//! * `PositiveError` - For `Positive` arithmetic failures
//!
//! ### Strategy Errors (`StrategyErrorKind`)
//! Handles specific strategy-related errors:
//! * Unsupported operations
//! * Strategy capacity limits
//! * Invalid configurations
//!
//! ### Validation Errors (`PositionValidationErrorKind`)
//! Handles position validation failures:
//! * Invalid position sizes
//! * Invalid prices
//! * Incompatible sides (Long/Short)
//! * Incompatible styles (Call/Put)
//! * General position invalidity
//!
//! ### Limit Errors (`PositionLimitErrorKind`)
//! Handles position limit violations:
//! * Maximum positions reached
//! * Maximum exposure reached
//!
//! ## Usage Example
//!
//! ```rust
//! use optionstratlib_core::error::position::PositionError;
//!
//! fn validate_position_size(size: f64) -> Result<(), PositionError> {
//!     if size <= 0.0 {
//!         return Err(PositionError::invalid_position_size(
//!             size,
//!             "Position size must be positive"
//!         ));
//!     }
//!     Ok(())
//! }
//! ```
//!
//! ## Helper Methods
//!
//! The module provides several helper methods for creating common errors:
//! * `unsupported_operation` - Creates an error for unsupported strategy operations
//! * `strategy_full` - Creates an error when strategy capacity is reached
//! * `invalid_position_size` - Creates an error for invalid position sizes
//! * `invalid_position_type` - Creates an error for incompatible position sides
//! * `invalid_position_style` - Creates an error for incompatible option styles
//! * `invalid_position` - Creates a general position validation error
//!
//! All error types implement `std::error::Error` and `std::fmt::Display` for proper
//! error handling and formatting capabilities.
//!
//! Target crate (ADR-0001 D6, roadmap M1-14): **core**. Owns `PositionError`, `StrategyErrorKind` (a kind enum, no strategy type inside).
//!
//! The `...Kind` enums are canonical in this module (`optionstratlib_core::error::position`) and are not
//! flattened into `optionstratlib_core::error`: the facade gathers every crate's errors
//! in one `optionstratlib::error` module, where flat kind names would collide
//! (`StrategyErrorKind` is defined in both core `error::position` and market
//! `error::chains`, `PriceErrorKind` in both analytics `error::probability`
//! and strategies `error::strategies`), so each crate keeps its kinds in its
//! kind module and the facade re-exports that module (#550).

use crate::model::types::{OptionStyle, Side};
use thiserror::Error;

/// Represents errors that can occur when managing positions in strategies
///
/// This enum provides a top-level categorization of position-related errors,
/// grouping them by their source or nature. It helps with routing errors to
/// appropriate handlers and providing context-aware error messages.
///
/// # Variants
///
/// * `StrategyError` - Errors related to strategy operations such as configuration
///   issues or capacity limitations.
///
/// * `ValidationError` - Errors related to position validation including issues
///   with size, price, or compatibility with strategy requirements.
///
/// * `LimitError` - Errors related to position limits such as maximum number of
///   positions or maximum exposure thresholds.
///
/// # Usage
///
/// This error type is typically used in trading systems where positions need to
/// be validated, managed, and executed within the context of trading strategies.
#[derive(Error, Debug)]
pub enum PositionError {
    /// Errors related to strategy operations
    #[error("Strategy error: {0}")]
    StrategyError(StrategyErrorKind),

    /// Errors related to position validation
    #[error("Validation error: {0}")]
    ValidationError(PositionValidationErrorKind),

    /// Errors related to position limits
    #[error("Limit error: {0}")]
    LimitError(PositionLimitErrorKind),

    /// Error during position update
    ///
    /// This variant is triggered when attempts to update option position parameters or data fail.
    // #[error("Position update error for field '{field}': {reason}")]
    // UpdateError {
    //     /// The position field that failed to update
    //     field: String,
    //     /// Detailed explanation of the position update failure
    //     reason: String,
    // },
    /// Errors related to position update
    #[error("Update error: {0}")]
    UpdateError(PositionUpdateErrorKind),

    /// Decimal arithmetic failures propagated from monetary-flow
    /// computations (overflow, division by zero, conversion).
    ///
    /// Produced when a checked Decimal helper in `model::decimal`
    /// surfaces a [`crate::error::DecimalError`] from inside a
    /// `Position` method (for example `pnl_at_expiration` or
    /// `unrealized_pnl`). Propagated transparently via the
    /// `#[from]` cascade so callers keep matching `PositionError`.
    #[error(transparent)]
    DecimalError(#[from] crate::error::DecimalError),

    /// `Positive` arithmetic failures propagated from cost and fee
    /// computations (overflow, division by zero, broken positivity
    /// invariant).
    ///
    /// Produced when a checked `Positive` helper surfaces a
    /// [`positive::PositiveError`] from inside a `Position` method (for
    /// example `total_cost` or `fees`, where the premium and the fees are
    /// accumulated and then scaled by the contract quantity). Propagated
    /// transparently via the `#[from]` cascade so callers keep matching
    /// `PositionError`.
    #[error(transparent)]
    PositiveError(#[from] positive::PositiveError),

    /// Contract-level failures propagated from the option the position
    /// holds.
    ///
    /// Produced when `Options::intrinsic_value` surfaces an
    /// [`crate::error::OptionsError`] inside a `Position` or `Leg` P&L
    /// method. Both types are core-owned, so the position layer reports a
    /// contract failure with its own error instead of borrowing the pricing
    /// layer's (roadmap M1-10).
    #[error(transparent)]
    Options(#[from] crate::error::OptionsError),

    /// The current time was asked for and this build has no clock.
    #[error(transparent)]
    Clock(#[from] crate::error::ClockError),
}

/// Specific errors that can occur in strategy operations
///
/// This enum captures detailed error types related to strategy operations,
/// providing specific information about why a strategy operation failed.
/// These errors typically occur during strategy management operations
/// such as adding positions, updating configurations, or executing trades.
///
/// # Variants
///
/// * `UnsupportedOperation` - Indicates that the attempted operation is not
///   supported by the particular strategy type.
///
/// * `StrategyFull` - Indicates that the strategy has reached its maximum
///   capacity for positions.
///
/// * `InvalidConfiguration` - Indicates that the strategy configuration is
///   invalid or inconsistent.
///
/// # Usage
///
/// Used when validating and executing strategy operations to provide detailed
/// error information about why an operation could not be completed.
#[derive(Error, Debug)]
pub enum StrategyErrorKind {
    /// Operation is not supported by this strategy
    ///
    /// Occurs when attempting to perform an operation that is not compatible
    /// with the current strategy type.
    #[error("Operation '{operation}' not supported by strategy '{strategy_type}'")]
    UnsupportedOperation {
        /// The type of strategy that doesn't support the operation
        strategy_type: String,

        /// The name of the operation that was attempted
        operation: String,
    },

    /// Strategy has reached its maximum capacity
    ///
    /// Occurs when attempting to add more positions than a strategy can handle.
    #[error("Strategy '{strategy_type}' is full (max positions: {max_positions})")]
    StrategyFull {
        /// The type of strategy that reached its capacity
        strategy_type: String,

        /// The maximum number of positions the strategy can hold
        max_positions: usize,
    },

    /// Invalid strategy configuration
    ///
    /// Occurs when the strategy's configuration parameters are invalid or inconsistent.
    #[error("Invalid strategy configuration: {0}")]
    InvalidConfiguration(String),
}

/// Errors related to position validation
///
/// This enum represents errors that can occur during position validation checks.
/// These errors typically happen when attempting to create or modify a position
/// with invalid or incompatible parameters.
///
/// # Variants
///
/// * `InvalidSize` - The position size is invalid (e.g., zero, negative, or too large).
///
/// * `InvalidPrice` - The position price is invalid (e.g., negative or unrealistic).
///
/// * `IncompatibleSide` - The position side (long/short) is incompatible with the strategy.
///
/// * `IncompatibleStyle` - The option style is incompatible with the strategy.
///
/// * `InvalidPosition` - The position is invalid for other specific reasons.
///
///
/// # Usage
///
/// Used when validating positions to ensure they meet all requirements before
/// being added to a strategy or executed in a trading system.
#[derive(Error, Debug)]
pub enum PositionValidationErrorKind {
    /// Position size is invalid
    ///
    /// Occurs when the specified position size violates size constraints.
    #[error("Invalid position size {size}: {reason}")]
    InvalidSize {
        /// The invalid size value
        size: f64,

        /// Explanation of why the size is invalid
        reason: String,
    },

    /// Position price is invalid
    ///
    /// Occurs when the specified price violates price constraints or is unrealistic.
    #[error("Invalid position price {price}: {reason}")]
    InvalidPrice {
        /// The invalid price value
        price: f64,

        /// Explanation of why the price is invalid
        reason: String,
    },

    /// Position type is incompatible with strategy
    ///
    /// Occurs when the position side (long/short) conflicts with strategy requirements.
    #[error("Incompatible position side {position_side:?}: {reason}")]
    IncompatibleSide {
        /// The incompatible position side
        position_side: Side,

        /// Explanation of why the side is incompatible
        reason: String,
    },

    /// Option style is incompatible with strategy
    ///
    /// Occurs when the option style (American/European) conflicts with strategy requirements.
    #[error("Incompatible option style {style:?}: {reason}")]
    IncompatibleStyle {
        /// The incompatible option style
        style: OptionStyle,

        /// Explanation of why the style is incompatible
        reason: String,
    },

    /// Position is invalid for other reasons
    ///
    /// A general error for positions that fail validation for reasons not covered by other variants.
    #[error("Invalid position: {reason}")]
    InvalidPosition {
        /// Explanation of why the position is invalid
        reason: String,
    },
}

/// Represents errors related to position limits in trading operations.
///
/// This enum captures different types of limit violations that can occur when
/// managing trading positions, such as exceeding the maximum number of allowed
/// positions or reaching the maximum exposure threshold for a portfolio.
///
/// # Variants
///
/// * `MaxPositionsReached` - Error indicating that the maximum number of allowed
///   positions has been reached, preventing the creation of additional positions.
///
/// * `MaxExposureReached` - Error indicating that the maximum allowed financial
///   exposure has been reached, preventing positions that would increase exposure.
///
/// # Usage
///
/// This error type is typically used in position management systems, risk control
/// mechanisms, and trading platforms to enforce safety limits and prevent excessive
/// risk taking.
///
#[derive(Error, Debug)]
pub enum PositionLimitErrorKind {
    /// Error indicating the maximum number of positions has been reached
    ///
    /// This variant is triggered when attempting to create a new position would
    /// exceed the configured maximum number of positions allowed in a portfolio
    /// or trading account.
    #[error("Maximum positions reached: {current}/{maximum}")]
    MaxPositionsReached {
        /// The current number of positions in the portfolio
        current: usize,
        /// The maximum number of positions allowed
        maximum: usize,
    },

    /// Error indicating the maximum allowed exposure has been reached
    ///
    /// This variant is triggered when a new position or modification would cause
    /// the total portfolio exposure to exceed the configured maximum risk threshold.
    /// Exposure is typically measured in monetary terms based on position value or risk.
    #[error("Maximum exposure reached: {current_exposure}/{max_exposure}")]
    MaxExposureReached {
        /// The current financial exposure level of the portfolio
        current_exposure: f64,
        /// The maximum allowed exposure level
        max_exposure: f64,
    },
}

/// Represents errors related to position update in trading operations.
///
/// This enum captures a specific error in an option position update.
/// The specified field to be updated can return an error.
///
/// # Variants
///
/// * `PositionFieldUpdateFailure` - Error in the update of a specific positon field.
///
/// # Usage
///
/// This error type is typically used in position management systems and trading platforms to
/// prevent a wrong position update.
///
#[derive(Error, Debug)]
pub enum PositionUpdateErrorKind {
    /// Error during position update
    ///
    /// This variant is triggered when attempts to update option position parameters or data fail.
    #[error("Position update error for field '{field}': {reason}")]
    PositionFieldUpdateFailure {
        /// The position field that failed to update
        field: String,
        /// Detailed explanation of the position update failure reason
        reason: String,
    },
}

/// Factory methods for creating position-related errors
///
/// This implementation provides a set of convenience factory methods for creating
/// different types of position errors. These methods create properly structured
/// error instances with clear, descriptive information about what went wrong.
///
/// # Methods
///
/// These factory methods simplify error creation throughout the codebase and ensure
/// that errors have consistent formatting and information.
impl PositionError {
    /// Creates an error for operations not supported by a specific strategy type
    ///
    /// # Parameters
    ///
    /// * `strategy_type` - The name or identifier of the strategy that doesn't support the operation
    /// * `operation` - The name of the unsupported operation that was attempted
    ///
    /// # Returns
    ///
    /// A `PositionError::StrategyError` variant with UnsupportedOperation details
    #[must_use]
    #[cold]
    #[inline(never)]
    pub fn unsupported_operation(strategy_type: &str, operation: &str) -> Self {
        PositionError::StrategyError(StrategyErrorKind::UnsupportedOperation {
            strategy_type: strategy_type.to_string(),
            operation: operation.to_string(),
        })
    }

    /// Creates an error when a strategy has reached its maximum position capacity
    ///
    /// # Parameters
    ///
    /// * `strategy_type` - The name or identifier of the strategy that is at capacity
    /// * `max_positions` - The maximum number of positions the strategy can hold
    ///
    /// # Returns
    ///
    /// A `PositionError::StrategyError` variant with StrategyFull details
    #[must_use]
    #[cold]
    #[inline(never)]
    pub fn strategy_full(strategy_type: &str, max_positions: usize) -> Self {
        PositionError::StrategyError(StrategyErrorKind::StrategyFull {
            strategy_type: strategy_type.to_string(),
            max_positions,
        })
    }

    /// Creates an error for invalid position size values
    ///
    /// # Parameters
    ///
    /// * `size` - The invalid position size value
    /// * `reason` - A description of why the size is invalid
    ///
    /// # Returns
    ///
    /// A `PositionError::ValidationError` variant with InvalidSize details
    #[must_use]
    #[cold]
    #[inline(never)]
    pub fn invalid_position_size(size: f64, reason: &str) -> Self {
        PositionError::ValidationError(PositionValidationErrorKind::InvalidSize {
            size,
            reason: reason.to_string(),
        })
    }

    /// Creates an error for incompatible position side/direction
    ///
    /// # Parameters
    ///
    /// * `position_side` - The position side (Long or Short) that is incompatible
    /// * `reason` - A description of why the position side is incompatible
    ///
    /// # Returns
    ///
    /// A `PositionError::ValidationError` variant with IncompatibleSide details
    #[must_use]
    #[cold]
    #[inline(never)]
    pub fn invalid_position_type(position_side: Side, reason: String) -> Self {
        PositionError::ValidationError(PositionValidationErrorKind::IncompatibleSide {
            position_side,
            reason,
        })
    }

    /// Creates an error for incompatible option style
    ///
    /// # Parameters
    ///
    /// * `style` - The option style (Call or Put) that is incompatible
    /// * `reason` - A description of why the option style is incompatible
    ///
    /// # Returns
    ///
    /// A `PositionError::ValidationError` variant with IncompatibleStyle details
    #[must_use]
    #[cold]
    #[inline(never)]
    pub fn invalid_position_style(style: OptionStyle, reason: String) -> Self {
        PositionError::ValidationError(PositionValidationErrorKind::IncompatibleStyle {
            style,
            reason,
        })
    }

    /// Creates a generic invalid position error
    ///
    /// # Parameters
    ///
    /// * `reason` - A description of why the position is invalid
    ///
    /// # Returns
    ///
    /// A `PositionError::ValidationError` variant with InvalidPosition details
    #[must_use]
    #[cold]
    #[inline(never)]
    pub fn invalid_position(reason: &str) -> Self {
        PositionError::ValidationError(PositionValidationErrorKind::InvalidPosition {
            reason: reason.to_string(),
        })
    }

    /// Creates an error for invalid position update
    ///
    /// # Parameters
    ///
    /// * `field` - The option position field that failed to update
    /// * `reason` - A description of why the option position field failed to update
    ///
    /// # Returns
    ///
    /// A `PositionError::UpdateError` variant with PositionFieldUpdateFailure details
    #[must_use]
    #[cold]
    #[inline(never)]
    pub fn invalid_position_update(field: String, reason: String) -> Self {
        PositionError::UpdateError(PositionUpdateErrorKind::PositionFieldUpdateFailure {
            field,
            reason,
        })
    }
}

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

    #[test]
    fn test_error_messages() {
        let error = PositionError::unsupported_operation("TestStrategy", "add_position");
        assert!(error.to_string().contains("TestStrategy"));
        assert!(error.to_string().contains("add_position"));
    }

    #[test]
    fn test_invalid_position_size() {
        let error = PositionError::invalid_position_size(-1.0, "Size cannot be negative");
        assert!(matches!(
            error,
            PositionError::ValidationError(PositionValidationErrorKind::InvalidSize { .. })
        ));
    }
}

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

    #[test]
    fn test_validation_error_display() {
        let error = PositionValidationErrorKind::InvalidSize {
            size: -1.0,
            reason: "Size must be positive".to_string(),
        };

        assert!(error.to_string().contains("-1"));
        assert!(error.to_string().contains("Size must be positive"));

        let error = PositionValidationErrorKind::IncompatibleSide {
            position_side: Side::Long,
            reason: "Strategy requires short positions".to_string(),
        };
        assert!(error.to_string().contains("Long"));
        assert!(error.to_string().contains("Strategy requires short"));
    }

    #[test]
    fn test_limit_error_display() {
        let error = PositionLimitErrorKind::MaxPositionsReached {
            current: 5,
            maximum: 4,
        };
        assert!(error.to_string().contains("5"));
        assert!(error.to_string().contains("4"));

        let error = PositionLimitErrorKind::MaxExposureReached {
            current_exposure: 1000.0,
            max_exposure: 500.0,
        };
        assert!(error.to_string().contains("1000"));
        assert!(error.to_string().contains("500"));
    }

    #[test]
    fn test_invalid_position_constructor() {
        let error = PositionError::invalid_position("bad position");
        assert!(matches!(
            error,
            PositionError::ValidationError(PositionValidationErrorKind::InvalidPosition { .. })
        ));
    }

    #[test]
    fn test_position_error_helper_methods() {
        let error = PositionError::invalid_position_size(-1.0, "Must be positive");
        assert!(matches!(
            error,
            PositionError::ValidationError(PositionValidationErrorKind::InvalidSize { .. })
        ));

        let error = PositionError::invalid_position_type(
            Side::Long,
            "Strategy requires short positions".to_string(),
        );
        assert!(matches!(
            error,
            PositionError::ValidationError(PositionValidationErrorKind::IncompatibleSide { .. })
        ));
    }

    #[test]
    fn test_strategy_error_helper_methods() {
        let error = PositionError::strategy_full("Iron Condor", 4);
        assert!(matches!(
            error,
            PositionError::StrategyError(StrategyErrorKind::StrategyFull { .. })
        ));

        let error = PositionError::unsupported_operation("Iron Condor", "add_leg");
        assert!(matches!(
            error,
            PositionError::StrategyError(StrategyErrorKind::UnsupportedOperation { .. })
        ));
    }

    #[test]
    fn test_position_error_validation_error() {
        let error = PositionError::ValidationError(PositionValidationErrorKind::InvalidSize {
            size: -1.0,
            reason: "Size must be positive".to_string(),
        });
        assert_eq!(
            format!("{error}"),
            "Validation error: Invalid position size -1: Size must be positive"
        );
    }

    #[test]
    fn test_position_error_limit_error() {
        let error = PositionError::LimitError(PositionLimitErrorKind::MaxPositionsReached {
            current: 10,
            maximum: 5,
        });
        assert_eq!(
            format!("{error}"),
            "Limit error: Maximum positions reached: 10/5"
        );
    }

    #[test]
    fn test_strategy_error_strategy_full() {
        let error = StrategyErrorKind::StrategyFull {
            strategy_type: "Iron Condor".to_string(),
            max_positions: 10,
        };
        assert_eq!(
            format!("{error}"),
            "Strategy 'Iron Condor' is full (max positions: 10)"
        );
    }

    #[test]
    fn test_strategy_error_invalid_configuration() {
        let error = StrategyErrorKind::InvalidConfiguration("Invalid risk parameters".to_string());
        assert_eq!(
            format!("{error}"),
            "Invalid strategy configuration: Invalid risk parameters"
        );
    }

    #[test]
    fn test_position_validation_error_invalid_price() {
        let error = PositionValidationErrorKind::InvalidPrice {
            price: 105.5,
            reason: "Outside allowable range".to_string(),
        };
        assert_eq!(
            format!("{error}"),
            "Invalid position price 105.5: Outside allowable range"
        );
    }

    #[test]
    fn test_position_validation_error_invalid_position() {
        let error = PositionValidationErrorKind::InvalidPosition {
            reason: "Position size exceeds margin".to_string(),
        };
        assert_eq!(
            format!("{error}"),
            "Invalid position: Position size exceeds margin"
        );
    }

    #[test]
    fn test_position_validation_error_incompatible_style() {
        let error = PositionValidationErrorKind::IncompatibleStyle {
            style: OptionStyle::Call,
            reason: "Unsupported for Call options".to_string(),
        };
        assert_eq!(
            format!("{error}"),
            "Incompatible option style OptionStyle::Call: Unsupported for Call options"
        );
    }

    #[test]
    fn test_position_update_error() {
        let error = PositionUpdateErrorKind::PositionFieldUpdateFailure {
            field: "premium".to_string(),
            reason: "Missing call ask price for long call position".to_string(),
        };
        assert_eq!(
            format!("{error}"),
            "Position update error for field 'premium': Missing call ask price for long call position"
        );
    }

    #[test]
    fn test_position_update_error_helper_method() {
        let error = PositionError::invalid_position_update(
            "premium".to_string(),
            "Missing call ask price for long call position".to_string(),
        );
        assert_eq!(
            format!("{error}"),
            "Update error: Position update error for field 'premium': Missing call ask price for long call position"
        );
    }
}