truman 0.1.0

Truman secret scanner facade — Rust library re-exporting core and detectors with collect and streaming APIs
Documentation
//! `truman`: facade crate re-exporting core + detectors.
//!
//! Downstream users depend only on this crate:
//! ```rust,no_run
//! use truman::{default_registry, ScanConfig, Scanner};
//! let registry = default_registry();
//! let scanner = Scanner::new(registry, ScanConfig::default());
//! let findings = scanner.scan_paths(&["."]);
//! println!("found {}", findings.len());
//! ```
//!
//! ## Custom detector + streaming (prints without waiting for full scan)
//!
//! ```rust,no_run
//! use truman::{Detector, DetectorContext, RawFinding};
//! #[derive(Debug)] struct MyDetector;
//! impl Detector for MyDetector {
//!     fn name(&self) -> &'static str { "MyDetector" }
//!     fn secret_type(&self) -> &str { "My Secret" }
//!     fn detect(&self, line: &str, _ctx: &DetectorContext) -> Vec<RawFinding> {
//!         match line.find("hunter2") {
//!             Some(s) => vec![RawFinding::new("hunter2".into(), s, s + 7)],
//!             None => vec![],
//!         }
//!     }
//! }
//! use std::path::PathBuf;
//! use truman::{default_registry_with_config, scan_paths_streaming, ScanEvent};
//! let (mut registry, config) = default_registry_with_config();
//! registry.register(MyDetector);
//! let paths = vec![PathBuf::from(".")];
//! let mut cb = |ev: ScanEvent| {
//!     if let ScanEvent::Finding(f) = ev {
//!         println!("{}:{}: {}", f.location.file.display(), f.location.span.line, f.hashed_secret);
//!     }
//!     true
//! };
//! scan_paths_streaming(&paths, &config, &registry, &mut cb);
//! ```

pub use truman_core::*;
pub use truman_detectors::default_registry;

use std::path::PathBuf;

/// Streaming callback: receives [`ScanEvent`]s, returns `true` to
/// continue or `false` to abort early.
///
/// Per-file subsequences are always `FileStart` → `Finding*` → `FileDone` in
/// order; across files, completion order is not guaranteed when scanning
/// with `jobs != 1` (pass `jobs = 1` for deterministic sorted-file order).
pub type ScanCallback<'a> = &'a mut dyn FnMut(ScanEvent) -> bool;

/// Default scan config (currently [`ScanConfig::default`]).
pub fn default_config() -> ScanConfig {
    ScanConfig::default()
}

/// Default registry + default config together.
///
/// Returns `(registry, config)` so callers can tweak `config` (filters,
/// detector selection) and/or `registry` (register custom detectors)
/// before scanning.
pub fn default_registry_with_config() -> (DetectorRegistry, ScanConfig) {
    (truman_detectors::default_registry(), ScanConfig::default())
}

/// Streaming scan over `paths` (files or dirs).
///
/// Thin wrapper around [`Scanner::scan_paths_streaming`]: builds a
/// [`Scanner`] via `Scanner::new(registry.clone(), config.clone())` and
/// delegates directory walking and `FileStart`/`Finding`/`FileDone`
/// emission to it (no own `walk_dir` / `skip_file`
/// pre-filter, so skipped files still emit `FileStart`/`FileDone`).
///
/// Files are scanned in parallel across `config.jobs` threads (default: all
/// cores); per-file event order is preserved while file completion order is
/// not guaranteed when `jobs != 1`.
///
/// Returns `true` when all files completed, `false` if the callback
/// aborted early.
pub fn scan_paths_streaming(
    paths: &[PathBuf],
    config: &ScanConfig,
    registry: &DetectorRegistry,
    callback: ScanCallback,
) -> bool {
    let scanner = Scanner::new(registry.clone(), config.clone());
    // `Scanner::scan_file_with_callback` takes `&mut impl FnMut` (Sized),
    // so forward the `dyn` callback through a concrete closure.
    let mut fwd = |ev: ScanEvent| -> bool { callback(ev) };
    scanner.scan_paths_streaming(paths, &mut fwd)
}

/// Convenience collect wrapper: build a [`Scanner`] from `registry` +
/// `config` and return all findings via [`Scanner::scan_paths`]
/// (dirs handled via Scanner's walk).
///
/// Files are scanned in parallel across `config.jobs` threads (default: all
/// cores); results are sorted for deterministic output.
pub fn scan_paths_collect(
    paths: &[PathBuf],
    config: &ScanConfig,
    registry: &DetectorRegistry,
) -> Vec<Finding> {
    let scanner = Scanner::new(registry.clone(), config.clone());
    scanner.scan_paths(paths)
}

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

    #[test]
    fn facade_collect_stripe_exact_span() {
        // Temp file with a Stripe key on line 1; assert exact Span.
        let dir = std::env::temp_dir();
        let path = dir.join(format!("truman-facade-{}.txt", std::process::id()));
        let secret = "sk_live_aaaaaaaaaaaaaaaaaaaaaaaa";
        let line = format!("key = \"{secret}\"");
        std::fs::write(&path, format!("{line}\n")).unwrap();

        let (registry, config) = default_registry_with_config();
        let paths = vec![path.clone()];
        let findings = scan_paths_collect(&paths, &config, &registry);
        std::fs::remove_file(&path).ok();

        assert_eq!(
            findings.len(),
            1,
            "expected one Stripe finding: {findings:?}"
        );
        let f = &findings[0];
        assert_eq!(f.detector, "StripeDetector");
        assert_eq!(f.location.file, path);
        assert_eq!(f.location.span.line, 1);
        let start = line.find(secret).unwrap();
        assert_eq!(f.location.span.col_start, start);
        assert_eq!(f.location.span.col_end, start + secret.len());
        assert_eq!(f.location.span.snippet(), Some(secret));
        // Plaintext kept in memory but never serialized; hash is SHA1 hex.
        assert_eq!(f.secret, secret);
        assert_eq!(f.hashed_secret, hash_secret(secret));
        assert_eq!(f.hashed_secret.len(), 40);
    }

    #[test]
    fn facade_streaming_callback_sees_finding_immediately() {
        let dir = std::env::temp_dir();
        let path = dir.join(format!("truman-facade-stream-{}.txt", std::process::id()));
        let secret = "sk_live_aaaaaaaaaaaaaaaaaaaaaaaa";
        std::fs::write(&path, format!("key = \"{secret}\"\n")).unwrap();

        let (registry, config) = default_registry_with_config();
        let paths = vec![path.clone()];
        let mut seen = 0usize;
        let mut saw_filedone = false;
        let completed = scan_paths_streaming(&paths, &config, &registry, &mut |ev: ScanEvent| {
            match ev {
                ScanEvent::Finding(_) => {
                    seen += 1;
                }
                ScanEvent::FileDone(_) => {
                    saw_filedone = true;
                }
                _ => {}
            }
            true
        });
        std::fs::remove_file(&path).ok();
        assert!(completed);
        assert_eq!(seen, 1);
        assert!(saw_filedone);
    }
}