st/

scanner_interest.rs

//
// -----------------------------------------------------------------------------
//  INTEREST SCORING: Surfacing What Matters
//
//  This module is the heart of Smart Tree's intelligent scanning. Instead of
//  listing everything, we score each file/folder by "interest" - how relevant
//  is this to the developer or AI right now?
//
//  Key concepts:
//  - TraversalPath: How did we reach this location? (direct, symlink, mount, etc.)
//  - InterestScore: A 0.0-1.0 score with breakdown of contributing factors
//  - InterestLevel: Human-friendly categorization (Boring → Critical)
//
//  "The goal is signal, not noise." - Omni
// -----------------------------------------------------------------------------
//

use crate::scanner::FilesystemType;
use serde::{Deserialize, Serialize};
use std::path::PathBuf;
use std::time::SystemTime;

/// How we reached this location during traversal.
/// This context helps understand if a path is "real" or indirect.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum TraversalPath {
    /// Directly under the scan root via normal directory traversal
    Direct,

    /// Reached via symbolic link
    Symlink {
        /// The actual target of the symlink
        target: PathBuf,
        /// Whether the target exists
        target_exists: bool,
    },

    /// Crossed a mount point boundary
    Mount {
        /// The filesystem type we're now on
        filesystem: FilesystemType,
        /// Mount point path
        mount_point: PathBuf,
    },

    /// Reached via recursive traversal into a nested structure
    Recursive {
        /// How deep we are from the original interesting location
        depth: usize,
        /// The original path that led us here
        original: PathBuf,
    },

    /// Inside a dependency/vendor directory (node_modules, vendor, etc.)
    Dependency {
        /// Type of dependency manager
        manager: DependencyManager,
        /// Root of the dependency tree
        dep_root: PathBuf,
    },
}

/// Types of dependency managers we recognize
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum DependencyManager {
    /// npm/yarn/pnpm (node_modules)
    Npm,
    /// Cargo (target/debug, target/release)
    Cargo,
    /// pip/venv/virtualenv
    Python,
    /// Go modules (vendor)
    Go,
    /// Ruby gems (vendor/bundle)
    Ruby,
    /// Composer (vendor)
    Composer,
    /// Maven/Gradle (.m2, build)
    Java,
    /// Unknown dependency manager
    Unknown,
}

impl DependencyManager {
    /// Get the typical directory name for this dependency manager
    pub fn dir_name(&self) -> &'static str {
        match self {
            Self::Npm => "node_modules",
            Self::Cargo => "target",
            Self::Python => ".venv",
            Self::Go => "vendor",
            Self::Ruby => "vendor",
            Self::Composer => "vendor",
            Self::Java => "build",
            Self::Unknown => "",
        }
    }

    /// Detect dependency manager from a directory name
    pub fn from_dir_name(name: &str) -> Option<Self> {
        match name {
            "node_modules" => Some(Self::Npm),
            "target" => Some(Self::Cargo),
            ".venv" | "venv" | ".virtualenv" | "virtualenv" => Some(Self::Python),
            "vendor" => Some(Self::Go), // Could also be Ruby/Composer - context needed
            ".m2" | "build" | "out" => Some(Self::Java),
            _ => None,
        }
    }
}

/// Full traversal context for a node
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TraversalContext {
    /// How we reached this location
    pub path: TraversalPath,

    /// Depth from scan root
    pub depth_from_root: usize,

    /// Is this path inside a git worktree?
    pub in_git_worktree: bool,

    /// Is this inside a submodule?
    pub in_submodule: bool,

    /// Parent directory interest level (for inheritance)
    pub parent_interest: Option<InterestLevel>,
}

impl Default for TraversalContext {
    fn default() -> Self {
        Self {
            path: TraversalPath::Direct,
            depth_from_root: 0,
            in_git_worktree: false,
            in_submodule: false,
            parent_interest: None,
        }
    }
}

/// Interest level - human-readable categorization of importance
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub enum InterestLevel {
    /// Not worth showing (generated files, caches, etc.)
    Boring = 0,

    /// Exists but rarely relevant (most dependencies, build artifacts)
    #[default]
    Background = 1,

    /// Worth knowing about but not urgent
    Notable = 2,

    /// Should be surfaced to the user
    Important = 3,

    /// Must be shown - security issues, breaking changes, critical files
    Critical = 4,
}

impl InterestLevel {
    /// Get emoji representation
    pub fn emoji(&self) -> &'static str {
        match self {
            Self::Boring => "💤",
            Self::Background => "📦",
            Self::Notable => "📝",
            Self::Important => "🔥",
            Self::Critical => "⚠️",
        }
    }

    /// Get color name for terminal output
    pub fn color(&self) -> &'static str {
        match self {
            Self::Boring => "bright_black",
            Self::Background => "white",
            Self::Notable => "cyan",
            Self::Important => "yellow",
            Self::Critical => "red",
        }
    }

    /// Convert from float score to level
    pub fn from_score(score: f32) -> Self {
        match score {
            s if s >= 0.8 => Self::Critical,
            s if s >= 0.6 => Self::Important,
            s if s >= 0.4 => Self::Notable,
            s if s >= 0.2 => Self::Background,
            _ => Self::Boring,
        }
    }
}

/// Risk level for security-related factors
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub enum RiskLevel {
    /// No risk detected
    None = 0,
    /// Informational finding
    Info = 1,
    /// Low risk - worth noting
    Low = 2,
    /// Medium risk - should be reviewed
    Medium = 3,
    /// High risk - needs attention
    High = 4,
    /// Critical risk - immediate action needed
    Critical = 5,
}

impl RiskLevel {
    pub fn emoji(&self) -> &'static str {
        match self {
            Self::None => "",
            Self::Info => "ℹ️",
            Self::Low => "🔵",
            Self::Medium => "🟡",
            Self::High => "🟠",
            Self::Critical => "🔴",
        }
    }
}

/// Factors that contribute to a node's interest score
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum InterestFactor {
    /// File was recently modified
    RecentlyModified {
        /// Hours since last modification
        hours_ago: f32,
        /// Contribution to score (0.0-1.0)
        weight: f32,
    },

    /// Security pattern detected
    SecurityPattern {
        /// Risk level of the finding
        risk: RiskLevel,
        /// Brief description
        description: String,
        /// Contribution to score
        weight: f32,
    },

    /// This is a key project file (README, Cargo.toml, package.json, etc.)
    KeyProjectFile {
        /// Type of key file
        file_type: KeyFileType,
        /// Contribution to score
        weight: f32,
    },

    /// Changed since last scan
    ChangedSinceLastScan {
        /// Type of change
        change: ChangeType,
        /// Contribution to score
        weight: f32,
    },

    /// In a "hot" directory with frequent changes
    HotDirectory {
        /// Number of changes in recent period
        change_count: u32,
        /// Contribution to score
        weight: f32,
    },

    /// Suspicious dependency detected
    SuspiciousDependency {
        /// Reason for suspicion
        reason: String,
        /// Contribution to score
        weight: f32,
    },

    /// Git-related interest (uncommitted changes, conflicts, etc.)
    GitStatus {
        /// Type of git status
        status: GitStatusType,
        /// Contribution to score
        weight: f32,
    },

    /// Code complexity or size concern
    Complexity {
        /// Description of the complexity factor
        description: String,
        /// Contribution to score
        weight: f32,
    },

    /// Inside a dependency tree (usually reduces interest)
    InDependencyTree {
        /// Depth inside dependency tree
        depth: usize,
        /// Negative contribution to score
        weight: f32,
    },

    /// Custom user-defined interest factor
    Custom {
        /// Name of the custom factor
        name: String,
        /// Contribution to score
        weight: f32,
    },
}

impl InterestFactor {
    /// Get the weight contribution of this factor
    pub fn weight(&self) -> f32 {
        match self {
            Self::RecentlyModified { weight, .. } => *weight,
            Self::SecurityPattern { weight, .. } => *weight,
            Self::KeyProjectFile { weight, .. } => *weight,
            Self::ChangedSinceLastScan { weight, .. } => *weight,
            Self::HotDirectory { weight, .. } => *weight,
            Self::SuspiciousDependency { weight, .. } => *weight,
            Self::GitStatus { weight, .. } => *weight,
            Self::Complexity { weight, .. } => *weight,
            Self::InDependencyTree { weight, .. } => *weight,
            Self::Custom { weight, .. } => *weight,
        }
    }

    /// Get a short description of this factor
    pub fn description(&self) -> String {
        match self {
            Self::RecentlyModified { hours_ago, .. } => {
                format!("Modified {:.1}h ago", hours_ago)
            }
            Self::SecurityPattern { description, .. } => description.clone(),
            Self::KeyProjectFile { file_type, .. } => {
                format!("Key file: {:?}", file_type)
            }
            Self::ChangedSinceLastScan { change, .. } => {
                format!("Changed: {:?}", change)
            }
            Self::HotDirectory { change_count, .. } => {
                format!("{} recent changes", change_count)
            }
            Self::SuspiciousDependency { reason, .. } => reason.clone(),
            Self::GitStatus { status, .. } => format!("Git: {:?}", status),
            Self::Complexity { description, .. } => description.clone(),
            Self::InDependencyTree { depth, .. } => {
                format!("Dependency depth: {}", depth)
            }
            Self::Custom { name, .. } => name.clone(),
        }
    }
}

/// Types of key project files
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum KeyFileType {
    /// README, CHANGELOG, etc.
    Documentation,
    /// Cargo.toml, package.json, etc.
    BuildConfig,
    /// .env, config.toml, etc.
    Configuration,
    /// main.rs, index.js, etc.
    EntryPoint,
    /// LICENSE, COPYING
    License,
    /// .github/workflows, .gitlab-ci.yml
    CiConfig,
    /// Dockerfile, docker-compose.yml
    Container,
    /// CLAUDE.md, .cursorrules, etc.
    AiConfig,
}

/// Types of changes detected between scans
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum ChangeType {
    /// File was added
    Added,
    /// File content was modified
    Modified,
    /// File was deleted
    Deleted,
    /// File permissions changed
    PermissionChanged,
    /// File was renamed/moved
    Renamed,
    /// File type changed (e.g., regular file to symlink)
    TypeChanged,
}

impl ChangeType {
    pub fn emoji(&self) -> &'static str {
        match self {
            Self::Added => "+",
            Self::Modified => "~",
            Self::Deleted => "-",
            Self::PermissionChanged => "🔐",
            Self::Renamed => "→",
            Self::TypeChanged => "⚡",
        }
    }
}

/// Git status types that affect interest
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum GitStatusType {
    /// Uncommitted changes
    Uncommitted,
    /// Merge conflict
    Conflict,
    /// Staged for commit
    Staged,
    /// Untracked file
    Untracked,
    /// Ahead of remote
    Ahead,
    /// Behind remote
    Behind,
}

/// Interest score with breakdown of contributing factors
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InterestScore {
    /// Overall interest score (0.0 = boring, 1.0 = critical)
    pub score: f32,

    /// Factors that contributed to this score
    pub factors: Vec<InterestFactor>,

    /// Human-friendly interest level
    pub level: InterestLevel,

    /// When this score was calculated
    pub calculated_at: SystemTime,
}

impl InterestScore {
    /// Create a new interest score from factors
    pub fn from_factors(factors: Vec<InterestFactor>) -> Self {
        let score = factors.iter().map(|f| f.weight()).sum::<f32>().clamp(0.0, 1.0);
        let level = InterestLevel::from_score(score);

        Self {
            score,
            factors,
            level,
            calculated_at: SystemTime::now(),
        }
    }

    /// Create a default "boring" score
    pub fn boring() -> Self {
        Self {
            score: 0.0,
            factors: vec![],
            level: InterestLevel::Boring,
            calculated_at: SystemTime::now(),
        }
    }

    /// Create a critical score with a single reason
    pub fn critical(reason: String) -> Self {
        Self {
            score: 1.0,
            factors: vec![InterestFactor::SecurityPattern {
                risk: RiskLevel::Critical,
                description: reason,
                weight: 1.0,
            }],
            level: InterestLevel::Critical,
            calculated_at: SystemTime::now(),
        }
    }

    /// Check if this score indicates the node should be shown by default
    pub fn should_show(&self) -> bool {
        self.level >= InterestLevel::Notable
    }

    /// Get a summary of why this is interesting
    pub fn summary(&self) -> String {
        if self.factors.is_empty() {
            return String::from("No notable factors");
        }

        self.factors
            .iter()
            .map(|f| f.description())
            .collect::<Vec<_>>()
            .join(", ")
    }
}

impl Default for InterestScore {
    fn default() -> Self {
        Self {
            score: 0.1,
            factors: vec![],
            level: InterestLevel::Background,
            calculated_at: SystemTime::now(),
        }
    }
}

/// Default weights for interest calculation
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InterestWeights {
    /// Weight for recently modified files (within 24h)
    pub recent_modification: f32,

    /// Weight for critical security findings
    pub security_critical: f32,

    /// Weight for key project files
    pub key_file: f32,

    /// Weight for files changed since last scan
    pub changed_since_scan: f32,

    /// Weight for files in hot directories
    pub hot_directory: f32,

    /// Negative weight for dependency tree depth
    pub dependency_depth_penalty: f32,

    /// Base interest for files with git changes
    pub git_changes: f32,
}

impl Default for InterestWeights {
    fn default() -> Self {
        Self {
            recent_modification: 0.3,
            security_critical: 1.0,
            key_file: 0.5,
            changed_since_scan: 0.4,
            hot_directory: 0.3,
            dependency_depth_penalty: -0.1,
            git_changes: 0.35,
        }
    }
}

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

    #[test]
    fn test_interest_level_from_score() {
        assert_eq!(InterestLevel::from_score(0.0), InterestLevel::Boring);
        assert_eq!(InterestLevel::from_score(0.1), InterestLevel::Boring);
        assert_eq!(InterestLevel::from_score(0.3), InterestLevel::Background);
        assert_eq!(InterestLevel::from_score(0.5), InterestLevel::Notable);
        assert_eq!(InterestLevel::from_score(0.7), InterestLevel::Important);
        assert_eq!(InterestLevel::from_score(0.9), InterestLevel::Critical);
        assert_eq!(InterestLevel::from_score(1.0), InterestLevel::Critical);
    }

    #[test]
    fn test_interest_score_from_factors() {
        let factors = vec![
            InterestFactor::RecentlyModified {
                hours_ago: 2.0,
                weight: 0.3,
            },
            InterestFactor::KeyProjectFile {
                file_type: KeyFileType::BuildConfig,
                weight: 0.5,
            },
        ];

        let score = InterestScore::from_factors(factors);
        assert!((score.score - 0.8).abs() < 0.01);
        assert_eq!(score.level, InterestLevel::Critical);
    }

    #[test]
    fn test_interest_score_clamping() {
        let factors = vec![
            InterestFactor::SecurityPattern {
                risk: RiskLevel::Critical,
                description: "Bad thing".to_string(),
                weight: 1.0,
            },
            InterestFactor::HotDirectory {
                change_count: 100,
                weight: 0.5,
            },
        ];

        let score = InterestScore::from_factors(factors);
        // Should clamp to 1.0
        assert_eq!(score.score, 1.0);
    }

    #[test]
    fn test_dependency_manager_detection() {
        assert_eq!(
            DependencyManager::from_dir_name("node_modules"),
            Some(DependencyManager::Npm)
        );
        assert_eq!(
            DependencyManager::from_dir_name("target"),
            Some(DependencyManager::Cargo)
        );
        assert_eq!(
            DependencyManager::from_dir_name(".venv"),
            Some(DependencyManager::Python)
        );
        assert_eq!(DependencyManager::from_dir_name("src"), None);
    }
}