ryo_suggest/

trigger.rs

//! SuggestTrigger and SuggestStrategy - Control re-evaluation timing
//!
//! For high-performance LLM-driven refactoring, we need fine-grained control
//! over when Suggest re-evaluation occurs. Evaluating after every AC change
//! would create a bottleneck.

use std::collections::HashSet;
use std::path::PathBuf;
use std::time::{Duration, Instant};

use ryo_analysis::SymbolId;
use serde::{Deserialize, Serialize};

/// Unique identifier for a Goal
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct GoalId(pub u64);

impl GoalId {
    pub fn new(id: u64) -> Self {
        Self(id)
    }
}

/// Unique identifier for a Wave (collection of Goals)
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct WaveId(pub u64);

impl WaveId {
    pub fn new(id: u64) -> Self {
        Self(id)
    }
}

/// Changes to AnalysisContext (used for incremental updates)
#[derive(Debug, Clone, Default)]
pub struct AcChanges {
    /// Newly added symbols
    pub added: Vec<SymbolId>,

    /// Modified symbols (content changed)
    pub modified: Vec<SymbolId>,

    /// Removed symbols
    pub removed: Vec<SymbolId>,
}

impl AcChanges {
    /// Create empty changes
    pub fn new() -> Self {
        Self::default()
    }

    /// Check if there are no changes
    pub fn is_empty(&self) -> bool {
        self.added.is_empty() && self.modified.is_empty() && self.removed.is_empty()
    }

    /// Get all affected symbols (added + modified)
    pub fn affected_symbols(&self) -> impl Iterator<Item = &SymbolId> {
        self.added.iter().chain(self.modified.iter())
    }

    /// Total number of changes
    pub fn len(&self) -> usize {
        self.added.len() + self.modified.len() + self.removed.len()
    }

    /// Merge another set of changes into this one
    pub fn merge(&mut self, other: AcChanges) {
        self.added.extend(other.added);
        self.modified.extend(other.modified);
        self.removed.extend(other.removed);

        // Remove duplicates
        self.added.sort();
        self.added.dedup();
        self.modified.sort();
        self.modified.dedup();
        self.removed.sort();
        self.removed.dedup();
    }
}

/// Trigger for suggestion re-evaluation
#[derive(Debug, Clone)]
pub enum SuggestTrigger {
    /// A single Goal completed (1 Goal = 1 logical unit of work)
    GoalCompleted { goal_id: GoalId, changes: AcChanges },

    /// A Wave completed (e.g., debug wave, feature wave)
    /// Multiple Goals form a Wave
    WaveCompleted {
        wave_id: WaveId,
        goal_count: usize,
        changes: AcChanges,
    },

    /// Manual trigger (user requested refresh)
    Manual,

    /// Periodic timer (e.g., every 30 seconds idle)
    Periodic { elapsed: Duration },

    /// File watcher detected external changes
    FileChanged { paths: Vec<PathBuf> },
}

impl SuggestTrigger {
    /// Get the kind of this trigger (for strategy matching)
    pub fn kind(&self) -> TriggerKind {
        match self {
            Self::GoalCompleted { .. } => TriggerKind::GoalCompleted,
            Self::WaveCompleted { .. } => TriggerKind::WaveCompleted,
            Self::Manual => TriggerKind::Manual,
            Self::Periodic { .. } => TriggerKind::Periodic,
            Self::FileChanged { .. } => TriggerKind::FileChanged,
        }
    }

    /// Get the associated changes (if any)
    pub fn changes(&self) -> Option<&AcChanges> {
        match self {
            Self::GoalCompleted { changes, .. } => Some(changes),
            Self::WaveCompleted { changes, .. } => Some(changes),
            _ => None,
        }
    }
}

/// Kind of trigger (for strategy configuration)
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum TriggerKind {
    GoalCompleted,
    WaveCompleted,
    Manual,
    Periodic,
    FileChanged,
}

/// Granularity of re-evaluation
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
pub enum EvalGranularity {
    /// Re-evaluate after every Goal (default for interactive)
    #[default]
    PerGoal,

    /// Re-evaluate after every Wave (for debug/batch operations)
    PerWave,

    /// Re-evaluate after N goals
    EveryNGoals(usize),

    /// Re-evaluate only on manual trigger (maximum throughput)
    ManualOnly,
}

/// Strategy for controlling suggestion re-evaluation timing
#[derive(Debug, Clone)]
pub struct SuggestStrategy {
    /// Re-evaluation granularity
    pub granularity: EvalGranularity,

    /// Minimum interval between evaluations
    pub min_interval: Duration,

    /// Maximum pending changes before forcing evaluation
    pub max_pending_changes: usize,

    /// Enabled trigger kinds
    pub enabled_triggers: HashSet<TriggerKind>,
}

impl Default for SuggestStrategy {
    fn default() -> Self {
        Self {
            granularity: EvalGranularity::PerGoal,
            min_interval: Duration::from_millis(100),
            max_pending_changes: 50,
            enabled_triggers: [
                TriggerKind::GoalCompleted,
                TriggerKind::WaveCompleted,
                TriggerKind::Manual,
            ]
            .into_iter()
            .collect(),
        }
    }
}

impl SuggestStrategy {
    /// Interactive preset: evaluate after every goal
    pub fn interactive() -> Self {
        Self::default()
    }

    /// HighPerf preset: minimize re-evaluation overhead
    pub fn high_perf() -> Self {
        Self {
            granularity: EvalGranularity::PerWave,
            min_interval: Duration::from_millis(500),
            max_pending_changes: 200,
            enabled_triggers: [TriggerKind::WaveCompleted, TriggerKind::Manual]
                .into_iter()
                .collect(),
        }
    }

    /// Batch preset: only manual evaluation
    pub fn batch() -> Self {
        Self {
            granularity: EvalGranularity::ManualOnly,
            min_interval: Duration::from_secs(1),
            max_pending_changes: 1000,
            enabled_triggers: [TriggerKind::Manual].into_iter().collect(),
        }
    }

    /// Check if a trigger should cause re-evaluation
    pub fn should_evaluate(&self, trigger: &SuggestTrigger, pending: &PendingChanges) -> bool {
        let kind = trigger.kind();

        // Check if trigger kind is enabled
        if !self.enabled_triggers.contains(&kind) {
            return false;
        }

        // Check minimum interval
        if pending.last_eval.elapsed() < self.min_interval {
            // Unless we've accumulated too many changes
            if pending.changes.len() < self.max_pending_changes {
                return false;
            }
        }

        // Check granularity
        match self.granularity {
            EvalGranularity::PerGoal => {
                matches!(trigger, SuggestTrigger::GoalCompleted { .. })
                    || matches!(trigger, SuggestTrigger::Manual)
            }
            EvalGranularity::PerWave => {
                matches!(trigger, SuggestTrigger::WaveCompleted { .. })
                    || matches!(trigger, SuggestTrigger::Manual)
            }
            EvalGranularity::EveryNGoals(n) => {
                pending.goal_count >= n || matches!(trigger, SuggestTrigger::Manual)
            }
            EvalGranularity::ManualOnly => matches!(trigger, SuggestTrigger::Manual),
        }
    }

    /// Set granularity
    pub fn with_granularity(mut self, granularity: EvalGranularity) -> Self {
        self.granularity = granularity;
        self
    }

    /// Set minimum interval
    pub fn with_min_interval(mut self, interval: Duration) -> Self {
        self.min_interval = interval;
        self
    }

    /// Enable a trigger kind
    pub fn enable_trigger(mut self, kind: TriggerKind) -> Self {
        self.enabled_triggers.insert(kind);
        self
    }

    /// Disable a trigger kind
    pub fn disable_trigger(mut self, kind: TriggerKind) -> Self {
        self.enabled_triggers.remove(&kind);
        self
    }
}

/// Accumulated changes waiting for evaluation
#[derive(Debug)]
pub struct PendingChanges {
    /// Number of completed goals since last evaluation
    pub goal_count: usize,

    /// Accumulated changes
    pub changes: AcChanges,

    /// Last evaluation time
    pub last_eval: Instant,
}

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

impl PendingChanges {
    /// Create new pending changes tracker
    pub fn new() -> Self {
        Self {
            goal_count: 0,
            changes: AcChanges::default(),
            last_eval: Instant::now(),
        }
    }

    /// Record a goal completion
    pub fn record_goal(&mut self, changes: AcChanges) {
        self.goal_count += 1;
        self.changes.merge(changes);
    }

    /// Take all pending changes and reset
    pub fn take(&mut self) -> (usize, AcChanges) {
        let goal_count = self.goal_count;
        let changes = std::mem::take(&mut self.changes);
        self.goal_count = 0;
        self.last_eval = Instant::now();
        (goal_count, changes)
    }

    /// Reset without taking changes
    pub fn reset(&mut self) {
        self.goal_count = 0;
        self.changes = AcChanges::default();
        self.last_eval = Instant::now();
    }

    /// Check if there are pending changes
    pub fn has_pending(&self) -> bool {
        self.goal_count > 0 || !self.changes.is_empty()
    }
}

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

    #[test]
    fn test_ac_changes_merge() {
        let mut c1 = AcChanges {
            added: vec![
                SymbolId::parse("1v1").unwrap(),
                SymbolId::parse("2v1").unwrap(),
            ],
            modified: vec![SymbolId::parse("3v1").unwrap()],
            removed: vec![],
        };

        let c2 = AcChanges {
            added: vec![
                SymbolId::parse("2v1").unwrap(),
                SymbolId::parse("4v1").unwrap(),
            ],
            modified: vec![
                SymbolId::parse("3v1").unwrap(),
                SymbolId::parse("5v1").unwrap(),
            ],
            removed: vec![SymbolId::parse("6v1").unwrap()],
        };

        c1.merge(c2);

        assert_eq!(c1.added.len(), 3); // 1, 2, 4 (deduplicated)
        assert_eq!(c1.modified.len(), 2); // 3, 5 (deduplicated)
        assert_eq!(c1.removed.len(), 1); // 6
    }

    #[test]
    fn test_strategy_per_goal() {
        // Use min_interval of 0 for testing granularity logic
        let strategy = SuggestStrategy::interactive().with_min_interval(Duration::ZERO);
        let pending = PendingChanges::new();

        let trigger = SuggestTrigger::GoalCompleted {
            goal_id: GoalId::new(1),
            changes: AcChanges::default(),
        };

        assert!(strategy.should_evaluate(&trigger, &pending));
    }

    #[test]
    fn test_strategy_per_wave() {
        // Use min_interval of 0 for testing granularity logic
        let strategy = SuggestStrategy::high_perf().with_min_interval(Duration::ZERO);
        let pending = PendingChanges::new();

        // Goal trigger should not evaluate in PerWave mode (trigger kind not enabled)
        let goal_trigger = SuggestTrigger::GoalCompleted {
            goal_id: GoalId::new(1),
            changes: AcChanges::default(),
        };
        assert!(!strategy.should_evaluate(&goal_trigger, &pending));

        // Wave trigger should evaluate
        let wave_trigger = SuggestTrigger::WaveCompleted {
            wave_id: WaveId::new(1),
            goal_count: 5,
            changes: AcChanges::default(),
        };
        assert!(strategy.should_evaluate(&wave_trigger, &pending));
    }

    #[test]
    fn test_strategy_manual_only() {
        // Use min_interval of 0 for testing granularity logic
        let strategy = SuggestStrategy::batch().with_min_interval(Duration::ZERO);
        let pending = PendingChanges::new();

        // Neither goal nor wave should evaluate (trigger kinds not enabled)
        let goal_trigger = SuggestTrigger::GoalCompleted {
            goal_id: GoalId::new(1),
            changes: AcChanges::default(),
        };
        assert!(!strategy.should_evaluate(&goal_trigger, &pending));

        // Manual should evaluate
        assert!(strategy.should_evaluate(&SuggestTrigger::Manual, &pending));
    }

    #[test]
    fn test_pending_changes() {
        let mut pending = PendingChanges::new();

        assert!(!pending.has_pending());

        pending.record_goal(AcChanges {
            added: vec![SymbolId::parse("1v1").unwrap()],
            ..Default::default()
        });

        assert!(pending.has_pending());
        assert_eq!(pending.goal_count, 1);

        let (count, changes) = pending.take();
        assert_eq!(count, 1);
        assert_eq!(changes.added.len(), 1);
        assert!(!pending.has_pending());
    }
}