pmat 3.11.0

//! O(1) Hooks Cache Demo (PMAT-453)
//!
//! This example demonstrates the O(1) hooks cache functionality that provides
//! instant (<5ms) pre-commit hook decisions by caching git tree hash and
//! analysis results.
//!
//! # Performance Comparison
//!
//! | Mode | Time | Description |
//! |------|------|-------------|
//! | Cache Hit | ~2ms | O(1) - Returns cached result |
//! | Cache Miss | ~30s | O(n) - Full analysis required |
//!
//! # Usage
//!
//! ```bash
//! # Initialize the cache
//! pmat hooks cache init
//!
//! # Check cache status
//! pmat hooks cache status
//!
//! # Run hooks with O(1) cache check
//! pmat hooks run -v
//!
//! # View cache metrics (CB-031)
//! pmat hooks cache metrics
//!
//! # Clear cache to force full re-run
//! pmat hooks cache clear
//! ```
//!
//! # Architecture
//!
//! The cache uses a 3-level hash hierarchy:
//!
//! - **Level 0**: Git tree hash (whole repo) - O(1) check
//! - **Level 1**: Per-gate hash (staged files only) - O(gates) check
//! - **Level 2**: Per-file hash (individual files) - O(changed) check
//!
//! # Compliance Checks
//!
//! - **CB-030**: O(1) Hooks Capable - verifies cache structure exists
//! - **CB-031**: Cache Health - monitors hit rate >= 60%
//!
//! Run `cargo run --example hooks_cache_demo` to see the API in action.

/// Demonstrates the HooksCacheManager API
fn main() {
    println!("=== PMAT Hooks Cache Demo (PMAT-453) ===\n");

    // In a real scenario, you would use the actual HooksCacheManager
    // Here we demonstrate the concepts and CLI usage

    println!("1. Initialize Cache:");
    println!("   $ pmat hooks cache init");
    println!("   Creates: .pmat/hooks-cache/");
    println!("            ├── tree-hash.json   (Level 0)");
    println!("            ├── gates/           (Level 1)");
    println!("            ├── files/           (Level 2)");
    println!("            └── metrics.json     (CB-031)");
    println!();

    println!("2. Check Cache Status:");
    println!("   $ pmat hooks cache status");
    println!("   Shows: HIT (cached result) or MISS (reason)");
    println!();

    println!("3. Run with O(1) Cache:");
    println!("   $ pmat hooks run -v");
    println!();
    println!("   On CACHE HIT (~2ms):");
    println!("   🎯 O(1) Cache HIT - Skipping full analysis");
    println!("      Cached result: Pass");
    println!("      Cached at: 2024-01-14 10:05:19 UTC");
    println!("      Check time: 2.06ms");
    println!("   ✅ All quality gates passed (cached)");
    println!();
    println!("   On CACHE MISS (~30s):");
    println!("   📝 Cache MISS: Tree hash changed");
    println!("      Running full analysis...");
    println!("   [Full quality gate analysis runs]");
    println!("   ✅ All pre-commit checks passed");
    println!();

    println!("4. View Metrics (CB-031):");
    println!("   $ pmat hooks cache metrics");
    println!("   Shows hit rate, timing, and health status");
    println!();

    println!("5. Clear Cache:");
    println!("   $ pmat hooks cache clear");
    println!("   Forces full re-run on next commit");
    println!();

    println!("6. Compliance Check:");
    println!("   $ pmat comply check");
    println!("   Validates CB-030 (O(1) capable) and CB-031 (cache health)");
    println!();

    // Demonstrate the cache result types
    println!("=== Cache Result Types ===\n");

    demonstrate_cache_results();

    println!("\n=== Performance Benefits ===\n");
    println!("Before O(1) Cache:");
    println!("  - Every commit: 30-60 seconds of analysis");
    println!("  - Scales with project size: O(n)");
    println!("  - Blocks developer flow");
    println!();
    println!("After O(1) Cache:");
    println!("  - Unchanged code: <5ms (target: <5ms, actual: ~2ms)");
    println!("  - Only runs full analysis when needed");
    println!("  - 1000x faster for unchanged code");
    println!();

    println!("=== Integration Example ===\n");
    println!("Add to .git/hooks/pre-commit:");
    println!();
    println!("#!/bin/bash");
    println!("# PMAT O(1) Pre-commit Hook");
    println!("pmat hooks run --cache || exit 1");
    println!();
}

/// Demonstrate the different cache result types
fn demonstrate_cache_results() {
    // Simulate cache check results
    let scenarios = vec![
        ("Cache HIT", "Pass", "Code unchanged since last check"),
        (
            "Cache HIT",
            "Fail",
            "Previous check failed, code still unchanged",
        ),
        ("Cache MISS", "NoCacheFile", "First run or cache cleared"),
        (
            "Cache MISS",
            "TreeHashChanged",
            "Code changed, need re-analysis",
        ),
        ("Cache MISS", "ConfigHashChanged", "Quality config changed"),
        ("Cache MISS", "VersionChanged", "PMAT version upgraded"),
        ("Cache MISS", "CacheStale", "Cache older than 7 days"),
    ];

    for (status, result, description) in scenarios {
        println!("  {} ({}): {}", status, result, description);
    }
}

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

    #[test]
    fn test_demo_runs() {
        // Just verify the demo code compiles and runs
        demonstrate_cache_results();
    }
}