aaai_core/audit/
engine.rs

1//! Audit engine: matches DiffEntries against AuditDefinition → AuditResult.
2
3use crate::audit::warning;
4use crate::config::definition::AuditDefinition;
5use crate::diff::entry::{DiffEntry, DiffType};
6use super::result::{AuditResult, AuditStatus, FileAuditResult};
7use super::strategy;
8
9/// The stateless audit evaluator.
10///
11/// Compares a list of [`DiffEntry`] items against an [`AuditDefinition`] and
12/// produces an [`AuditResult`] containing per-file verdicts and an overall summary.
13///
14/// # Example
15///
16/// ```rust,no_run
17/// use aaai_core::{DiffEngine, AuditEngine, AuditDefinition};
18/// use std::path::Path;
19///
20/// let diffs = DiffEngine::compare(Path::new("./before"), Path::new("./after")).unwrap();
21/// let definition = AuditDefinition::new_empty();
22/// let result = AuditEngine::evaluate(&diffs, &definition);
23/// assert!(result.summary.total >= 0);
24/// ```
25pub struct AuditEngine;
26
27/// Options for audit evaluation.
28#[derive(Debug, Clone, Default)]
29pub struct AuditOptions {
30    /// Warning kind IDs to suppress (e.g. ["no-approver"]).
31    pub suppress_warnings: Vec<String>,
32}
33
34impl AuditEngine {
35    /// Evaluate all diff entries against the audit definition.
36    ///
37    /// Returns an [`AuditResult`] with per-file [`FileAuditResult`] items and an
38    /// [`AuditSummary`] containing aggregated counts and the overall passing verdict.
39    pub fn evaluate(diffs: &[DiffEntry], definition: &AuditDefinition) -> AuditResult {
40        Self::evaluate_with_options(diffs, definition, &AuditOptions::default())
41    }
42
43    /// Evaluate with custom options.
44    ///
45    /// Use [`AuditOptions`] to suppress specific [`crate::audit::warning::AuditWarning`]
46    /// kinds (e.g. `no-approver`) without modifying the definition file.
47    pub fn evaluate_with_options(
48        diffs: &[DiffEntry],
49        definition: &AuditDefinition,
50        options: &AuditOptions,
51    ) -> AuditResult {
52        let mut results = Vec::new();
53
54        for diff in diffs {
55            let mut result = judge(diff, definition);
56            // Filter suppressed warnings.
57            if !options.suppress_warnings.is_empty() {
58                result.warnings.retain(|w| {
59                    !options.suppress_warnings.iter().any(|s| s == w.kind())
60                });
61            }
62            results.push(result);
63        }
64
65        AuditResult::new(results)
66    }
67}
68
69fn judge(diff: &DiffEntry, definition: &AuditDefinition) -> FileAuditResult {
70    // Diff-level errors (Unreadable / Incomparable) → always Error.
71    if diff.diff_type.is_error() {
72        return FileAuditResult {
73            diff: diff.clone(),
74            entry: None,
75            status: AuditStatus::Error,
76            detail: diff.error_detail.clone().or_else(|| {
77                Some("File could not be read or compared.".into())
78            }),
79            warnings: Vec::new(),
80        };
81    }
82
83    // Unchanged entries have no diff to audit — auto-OK regardless of rules.
84    if diff.diff_type == DiffType::Unchanged {
85        return FileAuditResult {
86            diff: diff.clone(),
87            entry: definition.find_entry(&diff.path).cloned(),
88            status: AuditStatus::Ok,
89            detail: None,
90            warnings: Vec::new(),
91        };
92    }
93
94    // Look up the matching entry.
95    let entry = match definition.find_entry(&diff.path) {
96        Some(e) => e,
97        None => {
98            return FileAuditResult {
99                diff: diff.clone(),
100                entry: None,
101                status: AuditStatus::Pending,
102                detail: Some("No audit rule defined for this path.".into()),
103                warnings: Vec::new(),
104            };
105        }
106    };
107
108    // Disabled entries → Ignored.
109    if !entry.enabled {
110        return FileAuditResult {
111            diff: diff.clone(),
112            entry: Some(entry.clone()),
113            status: AuditStatus::Ignored,
114            detail: Some("Entry is disabled.".into()),
115            warnings: Vec::new(),
116        };
117    }
118
119    // RFC 044 — Expired approval → Pending (needs renewal).
120    // `entry` data is preserved so the Inspector can show the old approval
121    // details alongside the expiry badge.
122    if entry.is_expired() {
123        return FileAuditResult {
124            diff: diff.clone(),
125            entry: Some(entry.clone()),
126            status: AuditStatus::Pending,
127            detail: Some("Approval has expired and needs renewal.".into()),
128            warnings: Vec::new(),
129        };
130    }
131
132    // Empty reason → treat as Pending (not yet human-approved).
133    if entry.reason.trim().is_empty() {
134        return FileAuditResult {
135            diff: diff.clone(),
136            entry: Some(entry.clone()),
137            status: AuditStatus::Pending,
138            detail: Some("Entry exists but has no reason — human approval required.".into()),
139            warnings: Vec::new(),
140        };
141    }
142
143    // Diff-type mismatch → Failed.
144    if entry.diff_type != diff.diff_type {
145        return FileAuditResult {
146            diff: diff.clone(),
147            entry: Some(entry.clone()),
148            status: AuditStatus::Failed,
149            detail: Some(format!(
150                "Expected diff type {:?} but found {:?}.",
151                entry.diff_type, diff.diff_type
152            )),
153            warnings: Vec::new(),
154        };
155    }
156
157    // Content strategy check.
158    match strategy::evaluate(&entry.strategy, diff) {
159        Ok(()) => {
160            let warns = warning::collect(diff, entry);
161            FileAuditResult {
162                diff: diff.clone(),
163                entry: Some(entry.clone()),
164                status: AuditStatus::Ok,
165                detail: None,
166                warnings: warns,
167            }
168        }
169        Err(msg) => FileAuditResult {
170            diff: diff.clone(),
171            entry: Some(entry.clone()),
172            status: AuditStatus::Failed,
173            detail: Some(msg),
174            warnings: Vec::new(),
175        },
176    }
177}
aaai_core/audit/engine.rs

aaai_core/audit/
engine.rs
