// Copyright (C) 2025 Christian Mauduit <ufoot@ufoot.org>

use crate::errors::*;

/// Trait for defining conditional connectivity between nodes.
///
/// `Topology` allows you to dynamically control which connections are allowed
/// in a mesh. This enables features like one-way passages, conditional doors,
/// or state-dependent pathfinding.
///
/// # Use Cases
///
/// - One-way passages (allow movement from A→B but not B→A)
/// - Doors that can open/close based on game state
/// - Conditional gates requiring keys or other conditions
/// - Dynamic environments where connectivity changes over time
///
/// # Example
///
/// ```
/// use shortestpath::mesh_topo::Topology;
///
/// // A topology that only allows movement in increasing index order (one-way)
/// struct OneWayTopology;
///
/// impl Topology for OneWayTopology {
///     fn allowed(&self, from: usize, to: usize) -> Result<bool, shortestpath::Error> {
///         Ok(to > from) // Only allow moving to higher indices
///     }
/// }
/// ```
pub trait Topology {
    /// Checks if movement from one node to another is allowed.
    ///
    /// # Arguments
    ///
    /// * `from` - The index of the source node
    /// * `to` - The index of the destination node
    ///
    /// # Returns
    ///
    /// `Ok(true)` if the connection is allowed, `Ok(false)` if blocked,
    /// or an `Err` if there's an error checking the topology
    fn allowed(&self, from: usize, to: usize) -> Result<bool>;
}
