valknut_rs/

lib.rs

//! # Valknut-RS: High-Performance Code Analysis Engine
//!
//! A Rust implementation of the valknut code analysis platform, designed for superior
//! performance and memory safety. This library provides comprehensive code analysis
//! capabilities including:
//!
//! - **Statistical Analysis**: Bayesian normalization and feature scoring
//! - **Graph Analysis**: Dependency graphs, centrality metrics, and cycle detection  
//! - **Similarity Detection**: LSH-based duplicate detection and MinHash signatures
//! - **Refactoring Analysis**: Code smell detection and refactoring opportunities
//! - **Multi-language Support**: Python, JavaScript, TypeScript, Rust, Go
//!
//! ## Performance Features
//!
//! - Zero-cost abstractions with compile-time optimizations
//! - SIMD-accelerated mathematical computations  
//! - Lock-free concurrent data structures
//! - Memory-efficient probabilistic algorithms
//! - Async-first design for I/O operations
//!
//! ## Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────┐
//! │                        API Layer                            │
//! ├─────────────────────────────────────────────────────────────┤
//! │  Core Engine  │  Detectors  │  Language  │  I/O & Reports  │
//! │              │             │  Adapters  │                 │
//! │ • Scoring    │ • Graph     │ • Python   │ • Cache         │
//! │ • Bayesian   │ • LSH/Hash  │ • JS/TS    │ • Reports       │
//! │ • Pipeline   │ • Structure │ • Rust     │                 │
//! │ • Config     │ • Coverage  │ • Go       │                 │
//! └─────────────────────────────────────────────────────────────┘
//! ```
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! use valknut_rs::{ValknutEngine, AnalysisConfig};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let config = AnalysisConfig::default()
//!         .with_language("python")
//!         .enable_all_modules();
//!
//!     let mut engine = ValknutEngine::new(config).await?;
//!     let results = engine.analyze_directory("./src").await?;
//!     
//!     println!("Analysis completed: {} files processed", results.files_analyzed());
//!     Ok(())
//! }
//! ```

#![warn(missing_docs)]
#![warn(unsafe_code)]
#![warn(clippy::all)]
#![warn(clippy::pedantic)]
#![warn(clippy::suspicious)]
#![allow(clippy::module_name_repetitions)]
#![allow(clippy::similar_names)]
#![allow(clippy::too_many_lines)]
#![allow(clippy::doc_markdown)]
#![allow(clippy::missing_errors_doc)]
#![allow(clippy::missing_panics_doc)]
#![allow(clippy::struct_excessive_bools)]
#![allow(clippy::fn_params_excessive_bools)]
#![allow(clippy::too_many_arguments)]
#![allow(clippy::type_complexity)]
#![cfg_attr(docsrs, feature(doc_cfg))]
// Additional allows for tests and examples
#![cfg_attr(test, allow(clippy::unwrap_used))]
#![cfg_attr(test, allow(clippy::expect_used))]

// Memory allocator selection (mutually exclusive)
#[cfg(all(feature = "mimalloc", not(feature = "jemalloc")))]
#[global_allocator]
static ALLOC: mimalloc::MiMalloc = mimalloc::MiMalloc;

#[cfg(all(feature = "jemalloc", not(feature = "mimalloc")))]
#[global_allocator]
static ALLOC: jemallocator::Jemalloc = jemallocator::Jemalloc;

// Core analysis engine modules
pub mod core {
    //! Core analysis algorithms and data structures.

    pub mod arena_analysis;
    pub mod ast;
    pub mod config;
    pub mod coverage_discovery;
    pub mod dependency;
    pub mod errors;
    pub mod featureset;
    pub mod file_utils;
    pub mod interned_entities;
    pub mod interning;
    pub mod partitioning;
    pub mod pipeline;
    pub mod scoring;

    // Re-export AST types at original paths for backward compatibility
    pub use ast::service as ast_service;
    pub use ast::utils as ast_utils;
    pub use ast::visitor as unified_visitor;

    // Re-export scoring types at original paths for backward compatibility
    pub use scoring::bayesian;
}

// Specialized detection algorithms
pub mod detectors {
    //! Specialized code analysis detectors.

    pub mod bundled;
    pub mod cohesion;
    pub mod complexity;
    pub mod coverage;
    pub mod graph;
    pub mod lsh;
    pub mod refactoring;
    pub mod structure;
}

// Language-specific AST adapters
#[path = "lang/mod.rs"]
pub mod lang;

// I/O, caching, and reporting
pub mod io {
    //! I/O operations, caching, and report generation.

    pub mod cache;
    pub mod reports;
}

// AI refactoring oracle
pub mod oracle;

// Documentation audit utilities
pub mod doc_audit;

// Public API and engine interface
pub mod api {
    //! High-level API and engine interface.

    pub mod config_types;
    pub mod engine;
    pub mod results;
}

// Re-export primary types for convenience
pub use crate::core::pipeline::AnalysisResults;
pub use api::config_types::AnalysisConfig;
pub use api::engine::ValknutEngine;
pub use core::errors::{Result, ValknutError, ValknutResultExt};

#[cfg(test)]
mod test_coverage_integration;

/// Library version information
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Build-time feature detection
pub mod features {
    //! Runtime feature detection.

    /// Check if SIMD acceleration is available
    pub const fn has_simd() -> bool {
        cfg!(feature = "simd")
    }

    /// Check if parallel processing is enabled
    pub const fn has_parallel() -> bool {
        cfg!(feature = "parallel")
    }
}

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

    #[test]
    fn version_constant_is_non_empty() {
        assert!(
            !VERSION.trim().is_empty(),
            "VERSION should contain the crate version at build time"
        );
    }

    #[test]
    fn feature_flags_match_cfg_settings() {
        assert_eq!(
            features::has_simd(),
            cfg!(feature = "simd"),
            "has_simd should mirror the compile-time cfg flag"
        );
        assert_eq!(
            features::has_parallel(),
            cfg!(feature = "parallel"),
            "has_parallel should mirror the compile-time cfg flag"
        );
    }

    #[test]
    fn analysis_config_reexports_support_builder_flows() {
        let config = AnalysisConfig::default()
            .disable_all_modules()
            .with_language("rust")
            .enable_all_modules()
            .with_confidence_threshold(0.6)
            .exclude_pattern("target/generated/*");

        assert!(config.modules.complexity);
        assert!(config.modules.coverage);
        assert!(
            config.languages.enabled.iter().any(|lang| lang == "rust"),
            "builder should append requested language"
        );
        assert!(
            config
                .files
                .exclude_patterns
                .iter()
                .any(|pattern| pattern.contains("generated")),
            "exclude pattern from builder should be retained"
        );
        assert!(
            config.validate().is_ok(),
            "valid builder configuration should pass validation"
        );

        let essentials = AnalysisConfig::default().essential_modules_only();
        assert!(essentials.modules.complexity);
        assert!(!essentials.modules.dependencies);
        assert!(!essentials.modules.coverage);

        let invalid = AnalysisConfig::default().with_confidence_threshold(1.5);
        assert!(
            invalid.validate().is_err(),
            "confidence thresholds outside 0.0-1.0 should be rejected"
        );
    }
}