skill-veil-core 0.2.0

//! Per-section pattern evaluators.
//!
//! Each section (`keywords:` / `semantics:` / `llm:`) has its own
//! evaluator trait so the engine can wire any combination at runtime.
//! Today's bundled implementations:
//!
//! - **Keywords**: native, regex / literal substring, case-insensitive
//!   by default. Reuses the `regex` crate already in our workspace.
//! - **Semantics**: a `NotYetWired` stub that returns
//!   `Outcome::Skipped` by default. The CLI ships a fastembed-backed
//!   `all-MiniLM-L6-v2` evaluator behind the `nova-semantics` Cargo
//!   feature; the runtime `--nova-semantics` flag swaps it in via the
//!   `&dyn SemanticEvaluator` parameter on `evaluate_rule` so the
//!   parser, the engine, and every rule stay untouched.
//! - **LLM**: a `NotYetWired` stub by default. The CLI wires NOVA
//!   `llm:` patterns into the existing skill-veil LLM provider chain
//!   (`~/.skill-veil.toml [llm]`) when the runtime `--nova-llm` flag
//!   is passed, again via the `&dyn LlmEvaluator` engine parameter.
//!
//! The trait is intentionally named after a NOVA section rather than
//! "matcher" so the wiring of "section X is not implemented" surfaces
//! in operator-facing messages with the section name they expect.

use super::model::{KeywordPattern, LlmPattern, SemanticPattern};

/// Result of evaluating one named pattern against the prompt body.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Outcome {
    /// Pattern fired against the prompt.
    Match,
    /// Pattern did not match.
    NoMatch,
    /// The evaluator is not yet wired up. The engine treats this as
    /// `false` for condition evaluation but surfaces a one-time
    /// warning so operators understand the rule did not have its
    /// full machinery applied.
    Skipped,
}

impl Outcome {
    /// Boolean projection used by the `ConditionExpr` evaluator.
    /// `Skipped` collapses to `false` so a rule whose condition
    /// requires a not-yet-wired section cannot accidentally fire.
    #[must_use]
    pub fn fired(self) -> bool {
        matches!(self, Self::Match)
    }
}

/// Evaluates a single keyword pattern (literal or regex) against the
/// prompt body.
pub trait KeywordEvaluator {
    fn eval(&self, var: &str, pattern: &KeywordPattern, body: &str) -> Outcome;
}

/// Evaluates a single semantic pattern. Default impl returns
/// `Skipped` until the embedding stack is wired.
pub trait SemanticEvaluator {
    fn eval(&self, var: &str, pattern: &SemanticPattern, body: &str) -> Outcome;
}

/// Evaluates a single LLM-based pattern. Default impl returns
/// `Skipped` until the provider chain is wired.
pub trait LlmEvaluator {
    fn eval(&self, var: &str, pattern: &LlmPattern, body: &str) -> Outcome;
}

// ---- Bundled implementations --------------------------------------------

/// Native keyword evaluator: literal substring match (case-aware) +
/// regex match. Compiles each regex on first use and caches it for
/// the lifetime of the evaluator instance.
#[derive(Debug, Default)]
pub struct NativeKeywordEvaluator {
    cache: std::sync::Mutex<std::collections::HashMap<String, regex::Regex>>,
}

impl NativeKeywordEvaluator {
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    fn compiled_regex(&self, pattern: &str, case_sensitive: bool) -> Option<regex::Regex> {
        let cache_key = format!("{}|{}", if case_sensitive { "1" } else { "0" }, pattern);
        let mut cache = self.cache.lock().ok()?;
        if let Some(rx) = cache.get(&cache_key) {
            return Some(rx.clone());
        }
        let body = if case_sensitive {
            pattern.to_string()
        } else {
            // Case-insensitive: prepend the inline flag if the
            // author hasn't already.
            if pattern.starts_with("(?") {
                pattern.to_string()
            } else {
                format!("(?i){pattern}")
            }
        };
        let rx = regex::Regex::new(&body).ok()?;
        cache.insert(cache_key, rx.clone());
        Some(rx)
    }
}

impl KeywordEvaluator for NativeKeywordEvaluator {
    fn eval(&self, _var: &str, pattern: &KeywordPattern, body: &str) -> Outcome {
        if pattern.is_regex {
            match self.compiled_regex(&pattern.pattern, pattern.case_sensitive) {
                Some(rx) => {
                    if rx.is_match(body) {
                        Outcome::Match
                    } else {
                        Outcome::NoMatch
                    }
                }
                None => Outcome::NoMatch,
            }
        } else if pattern.case_sensitive {
            if body.contains(&pattern.pattern) {
                Outcome::Match
            } else {
                Outcome::NoMatch
            }
        } else if body
            .to_ascii_lowercase()
            .contains(&pattern.pattern.to_ascii_lowercase())
        {
            Outcome::Match
        } else {
            Outcome::NoMatch
        }
    }
}

/// Stub for semantic evaluation. Always returns `Skipped`. Used as
/// the default when the CLI is not built with `--features nova-semantics`
/// (or the runtime model fails to load). The CLI's
/// `CosineSemanticEvaluator` (backed by `all-MiniLM-L6-v2` via
/// fastembed) is the production replacement and is wired in via the
/// `&dyn SemanticEvaluator` engine parameter.
#[derive(Debug, Default, Clone, Copy)]
pub struct NotYetWiredSemantic;

impl SemanticEvaluator for NotYetWiredSemantic {
    fn eval(&self, _var: &str, _pattern: &SemanticPattern, _body: &str) -> Outcome {
        Outcome::Skipped
    }
}

/// Stub for LLM evaluation. Always returns `Skipped`. Used as the
/// default when the CLI is not invoked with `--nova-llm` (or no
/// `[llm]` section is configured). The CLI's `ProviderLlmEvaluator`
/// (backed by the existing skill-veil provider chain) is the
/// production replacement and is wired in via the `&dyn LlmEvaluator`
/// engine parameter.
#[derive(Debug, Default, Clone, Copy)]
pub struct NotYetWiredLlm;

impl LlmEvaluator for NotYetWiredLlm {
    fn eval(&self, _var: &str, _pattern: &LlmPattern, _body: &str) -> Outcome {
        Outcome::Skipped
    }
}

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

    fn kw(pattern: &str, is_regex: bool, case: bool) -> KeywordPattern {
        KeywordPattern {
            pattern: pattern.to_string(),
            is_regex,
            case_sensitive: case,
        }
    }

    /// Contract: literal patterns are case-insensitive by default.
    /// Pre-fix a hand-rolled `contains` would have been case-sensitive
    /// silently — and broken every NOVA rule that doesn't pass
    /// `case:true`.
    #[test]
    fn literal_keyword_is_case_insensitive_by_default() {
        let ev = NativeKeywordEvaluator::new();
        let p = kw("Ignore Previous", false, false);
        assert_eq!(
            ev.eval("$x", &p, "please ignore previous instructions"),
            Outcome::Match
        );
    }

    /// Contract: literal pattern with `case_sensitive: true` only
    /// fires on an exact-case substring.
    #[test]
    fn literal_keyword_respects_case_sensitive() {
        let ev = NativeKeywordEvaluator::new();
        let p = kw("HACK", false, true);
        assert_eq!(ev.eval("$x", &p, "i want to HACK things"), Outcome::Match);
        assert_eq!(ev.eval("$x", &p, "i want to hack things"), Outcome::NoMatch);
    }

    /// Contract: regex patterns compile once and are cached. A
    /// repeated call must NOT re-compile (covered indirectly by
    /// matching twice and asserting cache populated).
    #[test]
    fn regex_keyword_matches_with_inline_flags() {
        let ev = NativeKeywordEvaluator::new();
        let p = kw(r"\bfoo\d+\b", true, false);
        assert_eq!(ev.eval("$x", &p, "matches FOO42 here"), Outcome::Match);
        assert_eq!(ev.eval("$x", &p, "no number"), Outcome::NoMatch);
    }

    /// Contract: an invalid regex from a parsed rule does NOT panic;
    /// it returns `NoMatch` so a single bad pattern cannot crash a
    /// scan. The parser already rejects most invalid regexes at load
    /// time; this is the belt-and-suspenders.
    #[test]
    fn invalid_regex_returns_nomatch_not_panic() {
        let ev = NativeKeywordEvaluator::new();
        let p = kw(r"(unclosed", true, false);
        assert_eq!(ev.eval("$x", &p, "anything"), Outcome::NoMatch);
    }

    /// Contract: stub evaluators return `Skipped`, never `Match`,
    /// so a rule that depends on a not-yet-wired capability cannot
    /// accidentally fire.
    #[test]
    fn stub_evaluators_return_skipped() {
        let s = NotYetWiredSemantic;
        let l = NotYetWiredLlm;
        let sem = SemanticPattern {
            pattern: "x".into(),
            threshold: 0.5,
        };
        let llm = LlmPattern {
            pattern: "y".into(),
            threshold: 0.5,
        };
        assert_eq!(s.eval("$x", &sem, "body"), Outcome::Skipped);
        assert_eq!(l.eval("$x", &llm, "body"), Outcome::Skipped);
        assert!(!Outcome::Skipped.fired());
    }
}