guardy/lib.rs
1//! # Guardy - Fast, secure git hooks in Rust
2//!
3//! Guardy is a high-performance git hooks framework written in Rust that provides:
4//!
5//! - **Fast Security Scanning**: Multi-threaded secret detection with entropy analysis
6//! - **Protected File Synchronization**: Keep configuration files in sync across repositories
7//! - **Comprehensive Git Hook Support**: Pre-commit, pre-push, and other git hooks
8//! - **Flexible Configuration**: YAML, TOML, and JSON configuration support
9//!
10//! ## Quick Start
11//!
12//! ### Installation
13//!
14//! ```bash
15//! # Install from crates.io
16//! cargo install guardy
17//!
18//! # Or clone and build
19//! git clone https://github.com/deepbrainspace/guardy
20//! cd guardy
21//! cargo build --release
22//! ```
23//!
24//! ### Basic Usage
25//!
26//! ```bash
27//! # Install git hooks in your repository
28//! guardy install
29//!
30//! # Scan files for secrets
31//! guardy scan src/
32//!
33//! # Check status
34//! guardy status
35//!
36//! # Sync protected files
37//! guardy sync
38//! ```
39//!
40//! ## Git Hooks Integration
41//!
42//! Guardy provides flexible git hook management with both built-in actions and custom commands.
43//! Hooks can be configured to run secret scanning, file synchronization, and custom commands.
44//!
45//! ### Hook Configuration Example
46//!
47//! ```yaml
48//! hooks:
49//! pre-commit:
50//! enabled: true
51//! builtin: ["scan_secrets"] # Built-in secret scanning
52//! custom:
53//! - command: "cargo fmt --check"
54//! description: "Check code formatting"
55//! fail_on_error: true
56//!
57//! pre-push:
58//! enabled: true
59//! custom:
60//! - command: "guardy sync update --force --config ./guardy.yaml"
61//! description: "Sync protected files before push"
62//! fail_on_error: true
63//! ```
64//!
65//! ## Repository Synchronization
66//!
67//! The sync feature allows you to keep files synchronized from upstream repositories.
68//! This is particularly useful for maintaining consistent configurations across multiple projects.
69//!
70//! ### Automating Sync with Hooks
71//!
72//! You can integrate sync into your git workflow to ensure files stay synchronized:
73//!
74//! ```yaml
75//! sync:
76//! repos:
77//! - name: "shared-configs"
78//! repo: "https://github.com/org/shared-configs"
79//! version: "v1.0.0" # Can be tag, branch, or commit
80//! source_path: ".github"
81//! dest_path: "./.github"
82//! include: ["**/*"]
83//! exclude: ["*.md"]
84//!
85//! hooks:
86//! pre-push:
87//! enabled: true
88//! custom:
89//! - command: "guardy sync update --force --config ./guardy.yaml"
90//! description: "Ensure configs are synchronized"
91//! fail_on_error: true
92//! ```
93//!
94//! This configuration ensures that protected files are restored to their canonical versions
95//! before pushing changes, preventing drift from the upstream configuration.
96//!
97//! ## Library Usage
98//!
99//! Guardy can also be used as a library for building custom security tools:
100//!
101//! ```rust,no_run
102//! use std::path::Path;
103//!
104//! use guardy::scan::Scanner;
105//!
106//! // Create scanner with global config
107//! let scanner = Scanner::new()?;
108//!
109//! // Scan files for secrets with streaming output
110//! let stats = scanner.scan(&[Path::new("src/").to_path_buf()])?;
111//!
112//! // Results are streamed during scanning
113//! println!("Scanned {} files, found {} matches", stats.files_scanned, stats.total_matches);
114//! # Ok::<(), Box<dyn std::error::Error>>(())
115//! ```
116
117//! ## Protected File Sync
118//!
119//! Keep configuration files synchronized across repositories:
120//!
121//! ```yaml
122//! # guardy.yaml
123//! sync:
124//! repos:
125//! - name: "shared-config"
126//! repo: "https://github.com/yourorg/shared-configs"
127//! version: "main"
128//! source_path: "."
129//! dest_path: "."
130//! include: ["*.yml", "*.json"]
131//! exclude: [".git"]
132//! ```
133//!
134//! ```bash
135//! # Show what has changed
136//! guardy sync diff
137//!
138//! # Update files interactively
139//! guardy sync
140//!
141//! # Force update all changes
142//! guardy sync --force
143//! ```
144//!
145//! ## Features
146//!
147//! - **Multi-threaded scanning** with configurable parallelism
148//! - **Entropy-based secret detection** for high accuracy
149//! - **Git integration** with hooks and remote operations
150//! - **File synchronization** with diff visualization
151//! - **Multiple output formats** (JSON, HTML, plain text)
152//! - **Comprehensive configuration** via YAML/TOML/JSON
153
154pub mod cli;
155pub mod config;
156pub mod git;
157pub mod hooks;
158pub mod scan; // High-performance scanner with scan-v3 optimizations
159pub mod shared;
160pub mod sync;