cleansh_core/
engine.rs

1// cleansh-core/src/engine.rs
2//! Defines the core SanitizationEngine trait and related data structures.
3//!
4//! The `SanitizationEngine` trait provides a pluggable interface for different
5//! sanitization methods (e.g., regex, entropy). This module defines the
6//! contract that all such engines must adhere to, ensuring a consistent
7//! and interchangeable core API for `cleansh`.
8//!
9//! License: MIT OR APACHE 2.0
10
11use anyhow::Result;
12use tokio::sync::mpsc;
13
14// Publicly exposed types from other modules
15use crate::config::{RedactionConfig, RedactionSummaryItem};
16use crate::profiles::EngineOptions;
17use crate::sanitizers::compiler::CompiledRules;
18use crate::audit_log::AuditLog;
19use crate::redaction_match::RedactionMatch;
20
21/// A trait that defines the core functionality of a sanitization engine.
22///
23/// This trait decouples the high-level application logic from the specific
24/// implementation of a sanitization method, allowing for different engines
25/// to be used interchangeably.
26pub trait SanitizationEngine: Send + Sync {
27    /// Performs full sanitization on the provided content.
28    ///
29    /// This method is responsible for finding all sensitive data, applying
30    /// redactions, and generating a summary of all matched items. It returns
31    /// the fully sanitized content and a summary of all redaction events.
32    ///
33    /// # Arguments
34    /// * `content` - The input string to sanitize.
35    /// * `source_id` - The name or identifier of the source being processed.
36    /// * `run_id` - A unique identifier for the current sanitization run.
37    /// * `input_hash` - A hash of the original input content for integrity checks.
38    /// * `user_id` - The user ID associated with the sanitization run.
39    /// * `reason` - The reason for the sanitization.
40    /// * `outcome` - The outcome of the sanitization.
41    /// * `audit_log` - An optional mutable reference to an `AuditLog` instance for logging events.
42    fn sanitize(
43        &self,
44        content: &str,
45        source_id: &str,
46        run_id: &str,
47        input_hash: &str,
48        user_id: &str,
49        reason: &str,
50        outcome: &str,
51        audit_log: Option<&mut AuditLog>,
52    ) -> Result<(String, Vec<RedactionSummaryItem>)>;
53
54    /// Analyzes the provided content for sensitive data without performing redaction.
55    ///
56    /// This method is used specifically for the `--stats-only` command. It returns
57    /// a summary of all matched items, but the original content is not modified.
58    ///
59    /// # Arguments
60    /// * `content` - The input string to scan.
61    /// * `source_id` - An identifier for the source of the content (e.g., a file path).
62    fn analyze_for_stats(&self, content: &str, source_id: &str) -> Result<Vec<RedactionSummaryItem>>;
63
64    /// Finds all matches and prepares them for an interactive TUI session.
65    ///
66    /// This method returns a flattened vector of `RedactionMatch` instances,
67    /// each with a stable sort order, a source ID, and a canonical hash.
68    ///
69    /// # Arguments
70    /// * `content` - The input string to scan.
71    /// * `source_id` - An identifier for the source of the content (e.g., a file path).
72    fn find_matches_for_ui(&self, content: &str, source_id: &str) -> Result<Vec<RedactionMatch>>;
73
74    /// Returns the statistical "heat" (entropy) for each character in the input.
75    /// This allows the UI to render heatmaps via dependency inversion.
76    fn get_heat_scores(&self, content: &str) -> Vec<f64>;
77
78    /// Returns a reference to the `CompiledRules` used by the engine.
79    ///
80    /// This is used by external components, such as the statistics command,
81    /// to access and display information about the rules without needing
82    /// to recompile them.
83    fn compiled_rules(&self) -> &CompiledRules;
84
85    /// Returns a reference to the engine's configuration.
86    fn get_rules(&self) -> &RedactionConfig;
87
88    /// Returns a reference to the engine's options.
89    fn get_options(&self) -> &EngineOptions;
90
91    /// Sets the remediation channel for the self-healing orchestrator.
92    /// This enables v0.2.0 "Tee-Logic" where matches are sent asynchronously for healing.
93    fn set_remediation_tx(&mut self, tx: mpsc::Sender<RedactionMatch>);
94}
cleansh_core/engine.rs

cleansh_core/
engine.rs
