fitts 0.2.1

//! Deck scheduler with Fitts-based priority ordering.
//!
//! # Architecture
//!
//! The scheduler manages decks of flashcards and provides:
//! - SM-2 interval scheduling (via `FittsScheduler`)
//! - Fitts' Law difficulty prediction for card ordering
//! - Deck statistics and due card management
//!
//! # Consistency: 4 Ratings ↔ 4 Difficulty Levels
//!
//! Both concepts use 4 values for consistency:
//!
//! | Rating (input) | DifficultyLevel (output) | Response Time |
//! |----------------|--------------------------|---------------|
//! | Easy           | Easy                     | < 4s          |
//! | Good           | Medium                   | 4-10s         |
//! | Hard           | Hard                     | 10-20s        |
//! | Again          | VeryHard                 | ≥ 20s         |
//!
//! **Rating** = user feedback after review ("How well did I recall?")
//! **DifficultyLevel** = model prediction before review ("How hard will this be?")
//!
//! # Example
//!
//! ```rust
//! use fitts::{Scheduler, SchedulerConfig, CardState, Rating};
//!
//! let mut scheduler = Scheduler::new(SchedulerConfig::default());
//!
//! // Add cards
//! scheduler.add_card("vocab", "apple", CardState::default());
//! scheduler.add_card("vocab", "house", CardState::default());
//!
//! // Get due cards (ordered by difficulty)
//! let due = scheduler.get_due_cards("vocab").unwrap();
//!
//! // Review a card
//! let result = scheduler.review("vocab", "apple", Rating::Good).unwrap();
//! println!("Next interval: {} days", result.card.interval_days);
//! ```

use crate::fitts::FittsModel;
use crate::integration::{CardState, FittsScheduler, Rating, ReviewInput, ReviewResult};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use thiserror::Error;

/// Scheduler errors.
#[derive(Debug, Clone, Error)]
pub enum SchedulerError {
    #[error("Deck '{0}' not found")]
    DeckNotFound(String),
    #[error("Card '{card_id}' not found in deck '{deck_id}'")]
    CardNotFound { card_id: String, deck_id: String },
}

/// Predicted difficulty level based on Fitts' Law response time.
///
/// 4 levels matching the 4 Rating options for conceptual consistency:
/// - **Easy** ↔ Rating::Easy (quick recall, < 4s)
/// - **Medium** ↔ Rating::Good (normal effort, 4-10s)
/// - **Hard** ↔ Rating::Hard (significant effort, 10-20s)
/// - **VeryHard** ↔ Rating::Again (struggling, ≥ 20s)
///
/// This is a **prediction** (output), not user feedback (input).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum DifficultyLevel {
    /// Quick recall (< 4 seconds) - expects Rating::Easy
    Easy,
    /// Normal effort (4-10 seconds) - expects Rating::Good
    Medium,
    /// Significant effort (10-20 seconds) - expects Rating::Hard
    Hard,
    /// Struggling (≥ 20 seconds) - expects Rating::Again
    VeryHard,
}

impl DifficultyLevel {
    /// Classify response time into difficulty level.
    ///
    /// Thresholds chosen to align with expected ratings:
    /// - Easy: instant/quick recall → user likely rates Easy
    /// - Medium: some hesitation → user likely rates Good
    /// - Hard: significant effort → user likely rates Hard
    /// - VeryHard: struggling → user likely rates Again
    pub fn from_response_time(rt: f64) -> Self {
        match rt {
            t if t < 4.0 => Self::Easy,
            t if t < 10.0 => Self::Medium,
            t if t < 20.0 => Self::Hard,
            _ => Self::VeryHard,
        }
    }

    /// Get expected rating for this difficulty level.
    ///
    /// This is what we predict the user will rate the card.
    pub fn expected_rating(&self) -> Rating {
        match self {
            Self::Easy => Rating::Easy,
            Self::Medium => Rating::Good,
            Self::Hard => Rating::Hard,
            Self::VeryHard => Rating::Again,
        }
    }

    /// Get human-readable description.
    pub fn description(&self) -> &'static str {
        match self {
            Self::Easy => "Quick recall",
            Self::Medium => "Normal effort",
            Self::Hard => "Significant effort",
            Self::VeryHard => "Struggling",
        }
    }

    /// Get all difficulty levels in order (easiest to hardest).
    pub fn all() -> [Self; 4] {
        [Self::Easy, Self::Medium, Self::Hard, Self::VeryHard]
    }
}

/// Card scheduled for review with predictions.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ScheduledCard {
    /// Card identifier.
    pub card_id: String,
    /// Current card state.
    pub state: CardState,
    /// Predicted response time (seconds).
    pub predicted_rt: f64,
    /// Predicted retrievability (0-1).
    pub retrievability: f64,
    /// Difficulty classification.
    pub difficulty: DifficultyLevel,
}

/// Scheduler configuration.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SchedulerConfig {
    /// Maximum cards to review per session.
    pub max_cards_per_session: usize,
    /// Maximum new cards per day.
    pub new_cards_per_day: usize,
}

impl Default for SchedulerConfig {
    fn default() -> Self {
        Self {
            max_cards_per_session: 20,
            new_cards_per_day: 10,
        }
    }
}

/// A deck of flashcards.
#[derive(Debug, Clone, Default)]
pub struct Deck {
    pub cards: HashMap<String, CardState>,
}

/// Main scheduler for managing decks and reviews.
#[derive(Debug, Clone)]
pub struct Scheduler {
    /// Configuration.
    pub config: SchedulerConfig,
    /// SM-2 + Fitts scheduler.
    pub fitts: FittsScheduler,
    /// Decks by ID.
    pub decks: HashMap<String, Deck>,
}

impl Default for Scheduler {
    fn default() -> Self {
        Self::new(SchedulerConfig::default())
    }
}

impl Scheduler {
    /// Create scheduler with configuration.
    pub fn new(config: SchedulerConfig) -> Self {
        Self {
            config,
            fitts: FittsScheduler::new(),
            decks: HashMap::new(),
        }
    }

    /// Create scheduler with custom Fitts model.
    pub fn with_fitts(config: SchedulerConfig, fitts: FittsModel) -> Self {
        Self {
            config,
            fitts: FittsScheduler::with_fitts(fitts),
            decks: HashMap::new(),
        }
    }

    /// Add a card to a deck.
    ///
    /// Creates the deck if it doesn't exist.
    pub fn add_card(&mut self, deck_id: &str, card_id: &str, state: CardState) {
        self.decks
            .entry(deck_id.to_string())
            .or_default()
            .cards
            .insert(card_id.to_string(), state);
    }

    /// Get due cards from a deck, ordered by difficulty (hardest first).
    ///
    /// Returns cards that are:
    /// - New (never reviewed)
    /// - Due for review (past their scheduled date)
    ///
    /// Cards are sorted by predicted response time (highest first),
    /// so the most difficult cards are reviewed first while the
    /// user is mentally fresh.
    pub fn get_due_cards(&self, deck_id: &str) -> Result<Vec<ScheduledCard>, SchedulerError> {
        let deck = self
            .decks
            .get(deck_id)
            .ok_or_else(|| SchedulerError::DeckNotFound(deck_id.to_string()))?;

        let mut due: Vec<_> = deck
            .cards
            .iter()
            .filter(|(_, state)| state.is_due() || state.repetitions == 0)
            .map(|(id, state)| {
                let (rt, retr) = self.fitts.predict(state);
                ScheduledCard {
                    card_id: id.clone(),
                    state: state.clone(),
                    predicted_rt: rt,
                    retrievability: retr,
                    difficulty: DifficultyLevel::from_response_time(rt),
                }
            })
            .collect();

        // Sort by predicted RT (hardest first)
        due.sort_by(|a, b| {
            b.predicted_rt
                .partial_cmp(&a.predicted_rt)
                .unwrap_or(std::cmp::Ordering::Equal)
        });

        // Limit to session size
        due.truncate(self.config.max_cards_per_session);

        Ok(due)
    }

    /// Review a card and update its state.
    ///
    /// Accepts either a `Rating` or `ReviewInput` (rating + response time).
    /// If response time is provided, calibrates the Fitts model.
    pub fn review(
        &mut self,
        deck_id: &str,
        card_id: &str,
        input: impl Into<ReviewInput>,
    ) -> Result<ReviewResult, SchedulerError> {
        let deck = self
            .decks
            .get_mut(deck_id)
            .ok_or_else(|| SchedulerError::DeckNotFound(deck_id.to_string()))?;

        let state = deck
            .cards
            .get(card_id)
            .ok_or_else(|| SchedulerError::CardNotFound {
                card_id: card_id.to_string(),
                deck_id: deck_id.to_string(),
            })?;

        let result = self.fitts.review(state.clone(), input);
        deck.cards.insert(card_id.to_string(), result.card.clone());

        Ok(result)
    }

    /// Get deck statistics.
    pub fn deck_stats(&self, deck_id: &str) -> Result<DeckStats, SchedulerError> {
        let deck = self
            .decks
            .get(deck_id)
            .ok_or_else(|| SchedulerError::DeckNotFound(deck_id.to_string()))?;

        let total = deck.cards.len();
        let due = deck.cards.values().filter(|c| c.is_due()).count();
        let new = deck.cards.values().filter(|c| c.repetitions == 0).count();
        let learning = deck
            .cards
            .values()
            .filter(|c| c.repetitions > 0 && c.interval_days < 21.0)
            .count();
        let mature = deck
            .cards
            .values()
            .filter(|c| c.interval_days >= 21.0)
            .count();

        Ok(DeckStats {
            total,
            due,
            new,
            learning,
            mature,
        })
    }
}

/// Deck statistics.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DeckStats {
    /// Total cards in deck.
    pub total: usize,
    /// Cards currently due.
    pub due: usize,
    /// New cards (never reviewed).
    pub new: usize,
    /// Learning cards (interval < 21 days).
    pub learning: usize,
    /// Mature cards (interval ≥ 21 days).
    pub mature: usize,
}

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

    // ==================== CONSISTENCY TESTS ====================

    #[test]
    fn test_rating_and_difficulty_have_same_count() {
        // Both should have exactly 4 values
        let ratings = [Rating::Again, Rating::Hard, Rating::Good, Rating::Easy];
        let difficulties = DifficultyLevel::all();

        assert_eq!(
            ratings.len(),
            difficulties.len(),
            "Rating and DifficultyLevel must have same number of values"
        );
    }

    #[test]
    fn test_difficulty_to_expected_rating_mapping() {
        // Each DifficultyLevel maps to exactly one Rating
        assert_eq!(DifficultyLevel::Easy.expected_rating(), Rating::Easy);
        assert_eq!(DifficultyLevel::Medium.expected_rating(), Rating::Good);
        assert_eq!(DifficultyLevel::Hard.expected_rating(), Rating::Hard);
        assert_eq!(DifficultyLevel::VeryHard.expected_rating(), Rating::Again);
    }

    #[test]
    fn test_difficulty_levels_are_ordered() {
        // Easy < 4, Medium [4,10), Hard [10,20), VeryHard >= 20
        assert_eq!(
            DifficultyLevel::from_response_time(3.9),
            DifficultyLevel::Easy
        );
        assert_eq!(
            DifficultyLevel::from_response_time(4.0),
            DifficultyLevel::Medium
        );
        assert_eq!(
            DifficultyLevel::from_response_time(9.9),
            DifficultyLevel::Medium
        );
        assert_eq!(
            DifficultyLevel::from_response_time(10.0),
            DifficultyLevel::Hard
        );
        assert_eq!(
            DifficultyLevel::from_response_time(19.9),
            DifficultyLevel::Hard
        );
        assert_eq!(
            DifficultyLevel::from_response_time(20.0),
            DifficultyLevel::VeryHard
        );
    }

    #[test]
    fn test_all_ratings_are_success_or_failure() {
        // Only Again is failure, all others are success
        let ratings = [Rating::Again, Rating::Hard, Rating::Good, Rating::Easy];
        let failures: Vec<_> = ratings.iter().filter(|r| !r.is_success()).collect();
        let successes: Vec<_> = ratings.iter().filter(|r| r.is_success()).collect();

        assert_eq!(
            failures.len(),
            1,
            "Exactly one rating should be failure (Again)"
        );
        assert_eq!(
            successes.len(),
            3,
            "Three ratings should be success (Hard, Good, Easy)"
        );
        assert_eq!(failures[0], &Rating::Again);
    }

    // ==================== DIFFICULTY CLASSIFICATION TESTS ====================

    #[test]
    fn test_difficulty_level_classification() {
        assert_eq!(
            DifficultyLevel::from_response_time(1.0),
            DifficultyLevel::Easy
        );
        assert_eq!(
            DifficultyLevel::from_response_time(3.0),
            DifficultyLevel::Easy
        );
        assert_eq!(
            DifficultyLevel::from_response_time(5.0),
            DifficultyLevel::Medium
        );
        assert_eq!(
            DifficultyLevel::from_response_time(15.0),
            DifficultyLevel::Hard
        );
        assert_eq!(
            DifficultyLevel::from_response_time(25.0),
            DifficultyLevel::VeryHard
        );
    }

    #[test]
    fn test_difficulty_descriptions() {
        assert_eq!(DifficultyLevel::Easy.description(), "Quick recall");
        assert_eq!(DifficultyLevel::Medium.description(), "Normal effort");
        assert_eq!(DifficultyLevel::Hard.description(), "Significant effort");
        assert_eq!(DifficultyLevel::VeryHard.description(), "Struggling");
    }

    // ==================== SCHEDULER TESTS ====================

    #[test]
    fn test_add_and_get_due() {
        let mut scheduler = Scheduler::default();
        scheduler.add_card("deck1", "card1", CardState::default());
        scheduler.add_card("deck1", "card2", CardState::default());

        let due = scheduler.get_due_cards("deck1").unwrap();
        assert_eq!(due.len(), 2); // New cards are due
    }

    #[test]
    fn test_review() {
        let mut scheduler = Scheduler::default();
        scheduler.add_card("deck1", "card1", CardState::default());

        let result = scheduler.review("deck1", "card1", Rating::Good).unwrap();
        assert_eq!(result.card.repetitions, 1);
        assert_eq!(result.card.interval_days, 1.0);

        let stats = scheduler.deck_stats("deck1").unwrap();
        assert_eq!(stats.new, 0);
        assert_eq!(stats.learning, 1);
    }

    #[test]
    fn test_deck_not_found() {
        let scheduler = Scheduler::default();
        let result = scheduler.get_due_cards("nonexistent");
        assert!(matches!(result, Err(SchedulerError::DeckNotFound(_))));
    }

    #[test]
    fn test_card_not_found() {
        let mut scheduler = Scheduler::default();
        scheduler.add_card("deck1", "card1", CardState::default());

        let result = scheduler.review("deck1", "card2", Rating::Good);
        assert!(matches!(result, Err(SchedulerError::CardNotFound { .. })));
    }

    #[test]
    fn test_difficulty_ordering() {
        let mut scheduler = Scheduler::default();

        scheduler.add_card(
            "deck1",
            "easy",
            CardState {
                interval_days: 1.0,
                ease_factor: 2.5,
                ..Default::default()
            },
        );
        scheduler.add_card(
            "deck1",
            "hard",
            CardState {
                interval_days: 30.0,
                ease_factor: 1.3,
                ..Default::default()
            },
        );

        let due = scheduler.get_due_cards("deck1").unwrap();
        assert!(
            due[0].predicted_rt >= due[1].predicted_rt,
            "Hardest should be first"
        );
    }

    #[test]
    fn test_deck_stats() {
        let mut scheduler = Scheduler::default();

        scheduler.add_card("deck1", "new1", CardState::default());
        scheduler.add_card("deck1", "new2", CardState::default());
        scheduler.add_card(
            "deck1",
            "learning",
            CardState {
                repetitions: 3,
                interval_days: 7.0,
                ..Default::default()
            },
        );
        scheduler.add_card(
            "deck1",
            "mature",
            CardState {
                repetitions: 10,
                interval_days: 30.0,
                ..Default::default()
            },
        );

        let stats = scheduler.deck_stats("deck1").unwrap();
        assert_eq!(stats.total, 4);
        assert_eq!(stats.new, 2);
        assert_eq!(stats.learning, 1);
        assert_eq!(stats.mature, 1);
    }
}