kardo_core/rules/

mod.rs

//! Configurable rules engine for Kardo (ESLint-like pattern).
//!
//! Provides a `Rule` trait that analysis checks implement, along with
//! `RuleContext` (project data), `RuleViolation` (detected issues),
//! `RuleSet` (collection of rules), and `RuleConfig` (per-rule settings).

pub mod builtin;
pub mod plugin;

use std::collections::{HashMap, HashSet};

use serde::{Deserialize, Serialize};

use crate::analysis::{
    AgentSetupResult, ConfigQualityResult, FreshnessResult, IntegrityResult, StructureResult,
};
use crate::git::GitFileInfo;
use crate::parser::ParsedDocument;
use crate::scanner::DiscoveredFile;

// ── Rule Category ──

/// Broad category a rule belongs to, matching the scoring components.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RuleCategory {
    Freshness,
    Configuration,
    Integrity,
    AgentSetup,
    Structure,
    Custom,
}

impl RuleCategory {
    pub fn label(&self) -> &'static str {
        match self {
            RuleCategory::Freshness => "Freshness",
            RuleCategory::Configuration => "Configuration",
            RuleCategory::Integrity => "Integrity",
            RuleCategory::AgentSetup => "Agent Setup",
            RuleCategory::Structure => "Structure",
            RuleCategory::Custom => "Custom",
        }
    }
}

// ── Severity ──

/// How severe a rule violation is.
///
/// Serializes as `error`/`warning`/`info`, but also accepts `high`/`medium`/`low`
/// as aliases (for YAML rule definitions).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Severity {
    #[serde(alias = "high")]
    Error,
    #[serde(alias = "medium")]
    Warning,
    #[serde(alias = "low")]
    Info,
}

// ── Rule Config ──

/// Per-rule configuration: enable/disable and severity override.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RuleConfig {
    /// Whether the rule is enabled.
    pub enabled: bool,
    /// Override the default severity.
    pub severity: Option<Severity>,
    /// Arbitrary rule-specific options (e.g. `max_days: 90`).
    #[serde(default)]
    pub options: HashMap<String, serde_json::Value>,
}

impl Default for RuleConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            severity: None,
            options: HashMap::new(),
        }
    }
}

// ── Rule Context ──

/// Snapshot of project data available to rules during evaluation.
///
/// Contains both raw scan data (files, parsed docs, git info) and
/// analysis results (freshness, integrity, etc.) so that rules can
/// operate at whichever level of abstraction they prefer.
pub struct RuleContext<'a> {
    // ── Raw scan data ──
    /// All discovered files in the project.
    pub files: &'a [DiscoveredFile],
    /// Set of all known relative paths (for link validation).
    pub known_paths: &'a HashSet<String>,
    /// Parsed markdown documents keyed by relative path.
    pub parsed_docs: &'a HashMap<String, ParsedDocument>,
    /// Git metadata per file.
    pub git_infos: &'a [GitFileInfo],
    /// Project root path.
    pub project_root: &'a std::path::Path,

    // ── Analysis results ──
    /// Freshness / staleness analysis results.
    pub freshness: Option<&'a FreshnessResult>,
    /// Reference integrity analysis results.
    pub integrity: Option<&'a IntegrityResult>,
    /// Configuration quality analysis results.
    pub config_quality: Option<&'a ConfigQualityResult>,
    /// Agent setup infrastructure analysis results.
    pub agent_setup: Option<&'a AgentSetupResult>,
    /// Project structure quality analysis results.
    pub structure: Option<&'a StructureResult>,
}

// ── Rule Violation ──

/// A violation produced when a rule detects an issue.
#[derive(Debug, Clone, Serialize)]
pub struct RuleViolation {
    /// Unique rule ID that produced this violation (e.g. "freshness/stale-doc").
    pub rule_id: String,
    /// Category the rule belongs to.
    pub category: RuleCategory,
    /// Severity of this violation.
    pub severity: Severity,
    /// File that triggered the violation, if applicable.
    pub file_path: Option<String>,
    /// Human-readable title.
    pub title: String,
    /// Why this matters for AI tools (attribution message).
    pub attribution: String,
    /// Actionable suggestion to fix the issue.
    pub suggestion: Option<String>,
}

// ── Rule Trait ──

/// A single quality rule that can be evaluated against a project.
///
/// Rules are stateless: all data comes via `RuleContext`.
/// Each rule has a unique ID (e.g. "freshness/stale-doc"),
/// a default severity, and a category.
pub trait Rule: Send + Sync {
    /// Unique identifier for this rule (e.g. "freshness/stale-doc").
    fn id(&self) -> &str;

    /// Human-readable name.
    fn name(&self) -> &str;

    /// Short description of what this rule checks.
    fn description(&self) -> &str;

    /// Category this rule belongs to.
    fn category(&self) -> RuleCategory;

    /// Default severity when the rule is violated.
    fn default_severity(&self) -> Severity;

    /// Evaluate the rule against the project context.
    /// Returns zero or more violations.
    fn evaluate(&self, ctx: &RuleContext, config: &RuleConfig) -> Vec<RuleViolation>;
}

// ── Rule Set ──

/// A named collection of rules with per-rule configuration.
pub struct RuleSet {
    /// Display name (e.g. "default", "strict", "nextjs").
    pub name: String,
    /// Registered rules.
    rules: Vec<Box<dyn Rule>>,
    /// Per-rule config overrides, keyed by rule ID.
    config: HashMap<String, RuleConfig>,
}

impl RuleSet {
    /// Create a new empty rule set.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            rules: Vec::new(),
            config: HashMap::new(),
        }
    }

    /// Create a rule set pre-loaded with all builtin rules.
    pub fn with_defaults() -> Self {
        let mut set = Self::new("default");
        set.add_rule(Box::new(builtin::StaleFreshnessRule));
        set.add_rule(Box::new(builtin::CouplingPenaltyRule));
        set.add_rule(Box::new(builtin::BrokenLinkRule));
        set.add_rule(Box::new(builtin::MissingClaudeMdRule));
        set.add_rule(Box::new(builtin::MissingReadmeRule));
        set.add_rule(Box::new(builtin::ShortConfigRule));
        set.add_rule(Box::new(builtin::GenericConfigRule));
        set
    }

    /// Register a rule.
    pub fn add_rule(&mut self, rule: Box<dyn Rule>) {
        self.rules.push(rule);
    }

    /// Set config for a specific rule by ID.
    pub fn configure(&mut self, rule_id: impl Into<String>, config: RuleConfig) {
        self.config.insert(rule_id.into(), config);
    }

    /// Enable or disable a rule by ID.
    pub fn set_enabled(&mut self, rule_id: &str, enabled: bool) {
        self.config
            .entry(rule_id.to_string())
            .or_default()
            .enabled = enabled;
    }

    /// Get the effective config for a rule (default if not overridden).
    pub fn effective_config(&self, rule_id: &str) -> RuleConfig {
        self.config.get(rule_id).cloned().unwrap_or_default()
    }

    /// Run all enabled rules and collect results with metadata.
    pub fn check_all(&self, ctx: &RuleContext) -> Vec<RuleResult> {
        let mut results = Vec::new();

        for rule in &self.rules {
            let config = self.effective_config(rule.id());
            if !config.enabled {
                continue;
            }

            let violations = rule.evaluate(ctx, &config);
            let severity = config.severity.unwrap_or_else(|| rule.default_severity());

            results.push(RuleResult {
                rule_id: rule.id().to_string(),
                rule_name: rule.name().to_string(),
                category: rule.category(),
                severity,
                violations,
            });
        }

        results
    }

    /// Run all enabled rules and collect violations (flat list, sorted by severity).
    pub fn evaluate(&self, ctx: &RuleContext) -> Vec<RuleViolation> {
        let mut violations = Vec::new();

        for rule in &self.rules {
            let config = self.effective_config(rule.id());
            if !config.enabled {
                continue;
            }

            let mut rule_violations = rule.evaluate(ctx, &config);

            // Apply severity override from config
            if let Some(severity_override) = config.severity {
                for v in &mut rule_violations {
                    v.severity = severity_override;
                }
            }

            violations.extend(rule_violations);
        }

        // Sort: errors first, then warnings, then info
        violations.sort_by_key(|v| match v.severity {
            Severity::Error => 0,
            Severity::Warning => 1,
            Severity::Info => 2,
        });

        violations
    }

    /// List all registered rule IDs.
    pub fn rule_ids(&self) -> Vec<&str> {
        self.rules.iter().map(|r| r.id()).collect()
    }

    /// Number of registered rules.
    pub fn len(&self) -> usize {
        self.rules.len()
    }

    /// Whether the set is empty.
    pub fn is_empty(&self) -> bool {
        self.rules.is_empty()
    }
}

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

// ── Rule Result ──

/// Result of running a single rule (includes metadata).
#[derive(Debug, Clone, Serialize)]
pub struct RuleResult {
    pub rule_id: String,
    pub rule_name: String,
    pub category: RuleCategory,
    pub severity: Severity,
    pub violations: Vec<RuleViolation>,
}

impl RuleResult {
    /// Whether this rule produced any violations.
    pub fn has_violations(&self) -> bool {
        !self.violations.is_empty()
    }

    /// Number of violations.
    pub fn violation_count(&self) -> usize {
        self.violations.len()
    }
}

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

    /// A trivial test rule: flags any file named "bad.md".
    struct BadFileRule;

    impl Rule for BadFileRule {
        fn id(&self) -> &str { "test/bad-file" }
        fn name(&self) -> &str { "Bad File Check" }
        fn description(&self) -> &str { "Flags files named bad.md" }
        fn category(&self) -> RuleCategory { RuleCategory::Structure }
        fn default_severity(&self) -> Severity { Severity::Warning }

        fn evaluate(&self, ctx: &RuleContext, _config: &RuleConfig) -> Vec<RuleViolation> {
            ctx.files
                .iter()
                .filter(|f| f.relative_path.ends_with("bad.md"))
                .map(|f| RuleViolation {
                    rule_id: self.id().to_string(),
                    category: self.category(),
                    severity: self.default_severity(),
                    file_path: Some(f.relative_path.clone()),
                    title: format!("{} should be renamed", f.relative_path),
                    attribution: "File name suggests low quality".to_string(),
                    suggestion: Some("Rename to a descriptive name".to_string()),
                })
                .collect()
        }
    }

    /// A rule that always passes.
    struct AlwaysPassRule;

    impl Rule for AlwaysPassRule {
        fn id(&self) -> &str { "test/always-pass" }
        fn name(&self) -> &str { "Always Pass" }
        fn description(&self) -> &str { "Never produces violations" }
        fn category(&self) -> RuleCategory { RuleCategory::Configuration }
        fn default_severity(&self) -> Severity { Severity::Error }

        fn evaluate(&self, _ctx: &RuleContext, _config: &RuleConfig) -> Vec<RuleViolation> {
            vec![]
        }
    }

    fn make_file(relative_path: &str) -> DiscoveredFile {
        DiscoveredFile {
            path: PathBuf::from(relative_path),
            relative_path: relative_path.to_string(),
            size: 100,
            modified_at: None,
            extension: Some("md".to_string()),
            is_markdown: true,
            content_hash: "abc123".to_string(),
        }
    }

    // Test helper: creates empty shared data for RuleContext.
    // Each test must create known/parsed/git locally before calling this.
    fn empty_known() -> HashSet<String> { HashSet::new() }
    fn empty_parsed() -> HashMap<String, ParsedDocument> { HashMap::new() }
    fn empty_git() -> Vec<GitFileInfo> { vec![] }

    #[test]
    fn test_rule_set_empty() {
        let rs = RuleSet::new("empty");
        assert!(rs.is_empty());
        assert_eq!(rs.len(), 0);
    }

    #[test]
    fn test_rule_set_add_and_evaluate() {
        let mut rs = RuleSet::new("test");
        rs.add_rule(Box::new(BadFileRule));
        rs.add_rule(Box::new(AlwaysPassRule));

        assert_eq!(rs.len(), 2);
        assert_eq!(rs.rule_ids(), vec!["test/bad-file", "test/always-pass"]);

        let files = vec![make_file("README.md"), make_file("bad.md")];
        let known = HashSet::new();
        let parsed = HashMap::new();
        let git: Vec<GitFileInfo> = vec![];
        let ctx = RuleContext {
            files: &files,
            known_paths: &known,
            parsed_docs: &parsed,
            git_infos: &git,
            project_root: std::path::Path::new("/tmp/test"),
            freshness: None,
            integrity: None,
            config_quality: None,
            agent_setup: None,
            structure: None,
        };

        let violations = rs.evaluate(&ctx);
        assert_eq!(violations.len(), 1);
        assert_eq!(violations[0].rule_id, "test/bad-file");
        assert_eq!(violations[0].file_path.as_deref(), Some("bad.md"));
    }

    #[test]
    fn test_rule_disabled() {
        let mut rs = RuleSet::new("test");
        rs.add_rule(Box::new(BadFileRule));
        rs.set_enabled("test/bad-file", false);

        let files = vec![make_file("bad.md")];
        let known = empty_known();
        let parsed = empty_parsed();
        let git = empty_git();
        let ctx = RuleContext {
            files: &files,
            known_paths: &known,
            parsed_docs: &parsed,
            git_infos: &git,
            project_root: std::path::Path::new("/tmp/test"),
            freshness: None,
            integrity: None,
            config_quality: None,
            agent_setup: None,
            structure: None,
        };
        let violations = rs.evaluate(&ctx);
        assert!(violations.is_empty(), "Disabled rule should not fire");
    }

    #[test]
    fn test_severity_override() {
        let mut rs = RuleSet::new("strict");
        rs.add_rule(Box::new(BadFileRule));
        rs.configure("test/bad-file", RuleConfig {
            enabled: true,
            severity: Some(Severity::Error),
            options: HashMap::new(),
        });

        let files = vec![make_file("bad.md")];
        let known = empty_known();
        let parsed = empty_parsed();
        let git = empty_git();
        let ctx = RuleContext {
            files: &files,
            known_paths: &known,
            parsed_docs: &parsed,
            git_infos: &git,
            project_root: std::path::Path::new("/tmp/test"),
            freshness: None,
            integrity: None,
            config_quality: None,
            agent_setup: None,
            structure: None,
        };
        let violations = rs.evaluate(&ctx);
        assert_eq!(violations.len(), 1);
        assert_eq!(violations[0].severity, Severity::Error); // overridden from Warning
    }

    #[test]
    fn test_no_violations_for_clean_project() {
        let mut rs = RuleSet::new("test");
        rs.add_rule(Box::new(BadFileRule));

        let files = vec![make_file("README.md"), make_file("docs/guide.md")];
        let known = empty_known();
        let parsed = empty_parsed();
        let git = empty_git();
        let ctx = RuleContext {
            files: &files,
            known_paths: &known,
            parsed_docs: &parsed,
            git_infos: &git,
            project_root: std::path::Path::new("/tmp/test"),
            freshness: None,
            integrity: None,
            config_quality: None,
            agent_setup: None,
            structure: None,
        };
        let violations = rs.evaluate(&ctx);
        assert!(violations.is_empty());
    }

    #[test]
    fn test_violations_sorted_by_severity() {
        // Create a rule that emits both Warning and Error
        struct MixedSeverityRule;
        impl Rule for MixedSeverityRule {
            fn id(&self) -> &str { "test/mixed" }
            fn name(&self) -> &str { "Mixed" }
            fn description(&self) -> &str { "Emits mixed severities" }
            fn category(&self) -> RuleCategory { RuleCategory::Freshness }
            fn default_severity(&self) -> Severity { Severity::Warning }

            fn evaluate(&self, _ctx: &RuleContext, _config: &RuleConfig) -> Vec<RuleViolation> {
                vec![
                    RuleViolation {
                        rule_id: self.id().to_string(),
                        category: self.category(),
                        severity: Severity::Info,
                        file_path: None,
                        title: "Info issue".to_string(),
                        attribution: "Low priority".to_string(),
                        suggestion: None,
                    },
                    RuleViolation {
                        rule_id: self.id().to_string(),
                        category: self.category(),
                        severity: Severity::Error,
                        file_path: None,
                        title: "Error issue".to_string(),
                        attribution: "Critical".to_string(),
                        suggestion: None,
                    },
                ]
            }
        }

        let mut rs = RuleSet::new("test");
        rs.add_rule(Box::new(MixedSeverityRule));

        let files: Vec<DiscoveredFile> = vec![];
        let known = empty_known();
        let parsed = empty_parsed();
        let git = empty_git();
        let ctx = RuleContext {
            files: &files,
            known_paths: &known,
            parsed_docs: &parsed,
            git_infos: &git,
            project_root: std::path::Path::new("/tmp/test"),
            freshness: None,
            integrity: None,
            config_quality: None,
            agent_setup: None,
            structure: None,
        };
        let violations = rs.evaluate(&ctx);

        assert_eq!(violations.len(), 2);
        assert_eq!(violations[0].severity, Severity::Error);
        assert_eq!(violations[1].severity, Severity::Info);
    }

    #[test]
    fn test_effective_config_default() {
        let rs = RuleSet::new("test");
        let config = rs.effective_config("nonexistent/rule");
        assert!(config.enabled);
        assert!(config.severity.is_none());
    }

    #[test]
    fn test_rule_config_options() {
        let mut rs = RuleSet::new("test");
        rs.add_rule(Box::new(AlwaysPassRule));

        let mut options = HashMap::new();
        options.insert("max_days".to_string(), serde_json::json!(90));
        options.insert("strict".to_string(), serde_json::json!(true));

        rs.configure("test/always-pass", RuleConfig {
            enabled: true,
            severity: None,
            options,
        });

        let config = rs.effective_config("test/always-pass");
        assert_eq!(config.options.get("max_days"), Some(&serde_json::json!(90)));
        assert_eq!(config.options.get("strict"), Some(&serde_json::json!(true)));
    }
}