feat: add example and test suites

Author: zmh-program

Cargo.toml

@@ -42,3 +42,19 @@ panic = "abort"
 [profile.dev]
 opt-level = 0
 debug = true
+
+[[example]]
+name = "basic_analysis"
+path = "examples/basic_analysis.rs"
+
+[[example]]
+name = "github_token_analysis"
+path = "examples/github_token_analysis.rs"
+
+[[example]]
+name = "compare_repositories"
+path = "examples/compare_repositories.rs"
+
+[[example]]
+name = "custom_analysis"
+path = "examples/custom_analysis.rs"

README.md

@@ -9,7 +9,7 @@ A fast code analysis tool for remote repositories with multi-platform support.
 
 ## Features
 
-- **Asynchronous Repository Processing**: Non-blocking HTTP client with concurrent stream processing for efficient remote repository fetching and decompression
+- **Asynchronous Repository Processing**: Non-blocking HTTP client with async streaming request processing for efficient remote repository fetching and decompression, optimized for **low memory usage** and **serverless environments**
 - **Multi-Platform URL Resolution**: Features intelligent URL parsing engine that normalizes different Git hosting platform APIs (GitHub, GitLab, Bitbucket, Codeberg) into unified archive endpoints with branch/commit resolution
 - **Streaming Archive Analysis**: Processes tar.gz archives directly in memory using streaming decompression without temporary file extraction, reducing I/O overhead and memory footprint
 - **Language Detection Engine**: Implements rule-based file extension and content analysis system supporting 150+ programming languages with configurable pattern matching and statistical computation (use tokei [languages map](https://github.com/XAMPPRocky/tokei/blob/master/languages.json))

examples/README.md

@@ -0,0 +1,89 @@
+# Examples
+
+This directory contains examples demonstrating how to use the bytes-radar library.
+
+## Available Examples
+
+### 1. Basic Analysis (`basic_analysis.rs`)
+
+Demonstrates basic usage of the RemoteAnalyzer to analyze a public repository.
+
+```bash
+cargo run --example basic_analysis
+```
+
+This example analyzes the bytes-radar repository itself and displays:
+- Project summary statistics
+- Language breakdown
+- Total lines, files, and size information
+
+### 2. GitHub Token Analysis (`github_token_analysis.rs`)
+
+Shows how to use GitHub authentication for private repositories.
+
+```bash
+export GITHUB_TOKEN=your_github_token_here
+cargo run --example github_token_analysis
+```
+
+Make sure to:
+1. Set the `GITHUB_TOKEN` environment variable
+2. Update the repository URL in the example to point to your private repo
+3. Ensure your token has access to the repository
+
+### 3. Compare Repositories (`compare_repositories.rs`)
+
+Compares multiple repositories and ranks them by various metrics.
+
+```bash
+cargo run --example compare_repositories
+```
+
+This example:
+- Analyzes multiple popular repositories
+- Compares them side by side
+- Ranks by complexity and documentation ratios
+- Demonstrates batch processing
+
+### 4. Custom Analysis (`custom_analysis.rs`)
+
+Demonstrates manual construction of project analysis without remote fetching.
+
+```bash
+cargo run --example custom_analysis
+```
+
+This example shows how to:
+- Create FileMetrics manually
+- Build a ProjectAnalysis step by step
+- Use different file categories
+- Display detailed file-by-file information
+
+## Running All Examples
+
+To run all examples in sequence:
+
+```bash
+cargo run --example basic_analysis
+cargo run --example custom_analysis
+cargo run --example compare_repositories
+
+# For github_token_analysis, set your token first:
+export GITHUB_TOKEN=your_token
+cargo run --example github_token_analysis
+```
+
+## Notes
+
+- Examples that analyze remote repositories require an internet connection
+- GitHub token examples require valid authentication
+- Some examples may take time to complete due to network requests
+- Adjust timeout values if you experience connection issues
+
+## Customizing Examples
+
+Feel free to modify these examples:
+- Change repository URLs to analyze your own projects
+- Adjust timeout values for slower connections
+- Add error handling for production use
+- Experiment with different output formats in the CLI 

examples/basic_analysis.rs

@@ -0,0 +1,48 @@
+use bytes_radar::{RemoteAnalyzer, Result};
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut analyzer = RemoteAnalyzer::new();
+
+    analyzer.set_timeout(60);
+
+    let url = "https://github.com/zmh-program/bytes-radar";
+
+    println!("Analyzing repository: {}", url);
+
+    let project_analysis = analyzer.analyze_url(url).await?;
+
+    let summary = project_analysis.get_summary();
+
+    println!("\nProject Analysis Summary:");
+    println!("Project Name: {}", summary.project_name);
+    println!("Total Files: {}", summary.total_files);
+    println!("Total Lines: {}", summary.total_lines);
+    println!("Code Lines: {}", summary.total_code_lines);
+    println!("Comment Lines: {}", summary.total_comment_lines);
+    println!("Blank Lines: {}", summary.total_blank_lines);
+    println!("Total Size: {} bytes", summary.total_size_bytes);
+    println!("Language Count: {}", summary.language_count);
+    if let Some(primary_lang) = &summary.primary_language {
+        println!("Primary Language: {}", primary_lang);
+    }
+    println!(
+        "Complexity Ratio: {:.2}%",
+        summary.overall_complexity_ratio * 100.0
+    );
+    println!(
+        "Documentation Ratio: {:.2}%",
+        summary.overall_documentation_ratio * 100.0
+    );
+
+    println!("\nLanguage Breakdown:");
+    let language_stats = project_analysis.get_language_statistics();
+    for stats in language_stats {
+        println!(
+            "  {}: {} files, {} lines",
+            stats.language_name, stats.file_count, stats.total_lines
+        );
+    }
+
+    Ok(())
+}

examples/compare_repositories.rs

@@ -0,0 +1,102 @@
+use bytes_radar::{RemoteAnalyzer, Result};
+use std::collections::HashMap;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let repositories = vec![
+        "https://github.com/rust-lang/rust",
+        "https://github.com/microsoft/vscode",
+        "https://github.com/facebook/react",
+        "https://github.com/golang/go",
+    ];
+
+    let mut analyzer = RemoteAnalyzer::new();
+    analyzer.set_timeout(180);
+
+    println!("Comparing {} repositories...\n", repositories.len());
+
+    let mut results = HashMap::new();
+
+    for repo in &repositories {
+        println!("Analyzing: {}", repo);
+
+        match analyzer.analyze_url(repo).await {
+            Ok(analysis) => {
+                let summary = analysis.get_summary();
+                results.insert(repo.to_string(), summary);
+                println!("✓ Completed: {}", repo);
+            }
+            Err(e) => {
+                eprintln!("✗ Failed {}: {}", repo, e);
+            }
+        }
+        println!();
+    }
+
+    if results.is_empty() {
+        println!("No repositories were successfully analyzed.");
+        return Ok(());
+    }
+
+    println!("=== Repository Comparison ===\n");
+
+    println!(
+        "{:<20} {:>10} {:>12} {:>12} {:>15}",
+        "Repository", "Files", "Total Lines", "Code Lines", "Primary Lang"
+    );
+    println!("{}", "-".repeat(75));
+
+    for (repo, summary) in &results {
+        let repo_name = repo.split('/').last().unwrap_or(repo);
+        let primary_lang = summary.primary_language.as_deref().unwrap_or("Unknown");
+
+        println!(
+            "{:<20} {:>10} {:>12} {:>12} {:>15}",
+            repo_name,
+            summary.total_files,
+            summary.total_lines,
+            summary.total_code_lines,
+            primary_lang
+        );
+    }
+
+    println!("\n=== Complexity Analysis ===\n");
+
+    let mut complexity_ranking: Vec<_> = results.iter().collect();
+    complexity_ranking.sort_by(|a, b| {
+        b.1.overall_complexity_ratio
+            .partial_cmp(&a.1.overall_complexity_ratio)
+            .unwrap()
+    });
+
+    for (i, (repo, summary)) in complexity_ranking.iter().enumerate() {
+        let repo_name = repo.split('/').last().unwrap_or(repo);
+        println!(
+            "{}. {}: {:.1}% code ratio",
+            i + 1,
+            repo_name,
+            summary.overall_complexity_ratio * 100.0
+        );
+    }
+
+    println!("\n=== Documentation Analysis ===\n");
+
+    let mut doc_ranking: Vec<_> = results.iter().collect();
+    doc_ranking.sort_by(|a, b| {
+        b.1.overall_documentation_ratio
+            .partial_cmp(&a.1.overall_documentation_ratio)
+            .unwrap()
+    });
+
+    for (i, (repo, summary)) in doc_ranking.iter().enumerate() {
+        let repo_name = repo.split('/').last().unwrap_or(repo);
+        println!(
+            "{}. {}: {:.1}% documentation ratio",
+            i + 1,
+            repo_name,
+            summary.overall_documentation_ratio * 100.0
+        );
+    }
+
+    Ok(())
+}

examples/custom_analysis.rs

@@ -0,0 +1,75 @@
+use bytes_radar::{FileCategory, FileMetrics, ProjectAnalysis, Result};
+
+fn main() -> Result<()> {
+    let mut project = ProjectAnalysis::new("my-rust-project");
+
+    let main_rs = FileMetrics::new("src/main.rs", "Rust".to_string(), 50, 35, 10, 5)?
+        .with_category(FileCategory::Source)
+        .with_size_bytes(1200);
+
+    let lib_rs = FileMetrics::new("src/lib.rs", "Rust".to_string(), 80, 60, 15, 5)?
+        .with_category(FileCategory::Source)
+        .with_size_bytes(2000);
+
+    let test_rs = FileMetrics::new(
+        "tests/integration_test.rs",
+        "Rust".to_string(),
+        45,
+        35,
+        5,
+        5,
+    )?
+    .with_category(FileCategory::Test)
+    .with_size_bytes(950);
+
+    let readme_md = FileMetrics::new("README.md", "Markdown".to_string(), 25, 20, 0, 5)?
+        .with_category(FileCategory::Documentation)
+        .with_size_bytes(600);
+
+    let cargo_toml = FileMetrics::new("Cargo.toml", "TOML".to_string(), 15, 12, 2, 1)?
+        .with_category(FileCategory::Configuration)
+        .with_size_bytes(400);
+
+    project.add_file_metrics(main_rs)?;
+    project.add_file_metrics(lib_rs)?;
+    project.add_file_metrics(test_rs)?;
+    project.add_file_metrics(readme_md)?;
+    project.add_file_metrics(cargo_toml)?;
+
+    let summary = project.get_summary();
+
+    println!("=== Custom Project Analysis ===\n");
+    println!("Project: {}", summary.project_name);
+    println!("Total Files: {}", summary.total_files);
+    println!("Total Lines: {}", summary.total_lines);
+    println!("Code Lines: {}", summary.total_code_lines);
+    println!("Comment Lines: {}", summary.total_comment_lines);
+    println!("Blank Lines: {}", summary.total_blank_lines);
+    println!("Total Size: {} bytes", summary.total_size_bytes);
+
+    println!("\n=== Language Breakdown ===");
+    for stats in project.get_language_statistics() {
+        println!("{}:", stats.language_name);
+        println!("  Files: {}", stats.file_count);
+        println!("  Lines: {}", stats.total_lines);
+        println!("  Code: {}", stats.code_lines);
+        println!("  Comments: {}", stats.comment_lines);
+        println!("  Complexity: {:.1}%", stats.complexity_ratio * 100.0);
+        println!("  Documentation: {:.1}%", stats.documentation_ratio * 100.0);
+        println!();
+    }
+
+    println!("=== File Details ===");
+    for (lang_name, lang_analysis) in &project.language_analyses {
+        println!("{}:", lang_name);
+        for file in &lang_analysis.file_metrics {
+            println!(
+                "  {} ({:?}): {} lines, {} bytes",
+                file.file_path, file.category, file.total_lines, file.size_bytes
+            );
+        }
+        println!();
+    }
+
+    Ok(())
+}

examples/github_token_analysis.rs

@@ -0,0 +1,51 @@
+use bytes_radar::{RemoteAnalyzer, Result};
+use std::env;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let github_token =
+        env::var("GITHUB_TOKEN").expect("Please set GITHUB_TOKEN environment variable");
+
+    let mut analyzer = RemoteAnalyzer::new();
+    analyzer.set_github_token(&github_token);
+    analyzer.set_timeout(120);
+
+    let url = "https://github.com/your-username/your-repo";
+
+    println!("Analyzing private repository: {}", url);
+    println!("Using GitHub token for authentication...");
+
+    match analyzer.analyze_url(url).await {
+        Ok(project_analysis) => {
+            let summary = project_analysis.get_summary();
+
+            println!("\nPrivate Repository Analysis:");
+            println!("Project: {}", summary.project_name);
+            println!("Files: {}", summary.total_files);
+            println!("Lines of Code: {}", summary.total_code_lines);
+
+            println!("\nTop 5 Languages by Line Count:");
+            let mut language_stats = project_analysis.get_language_statistics();
+            language_stats.sort_by(|a, b| b.total_lines.cmp(&a.total_lines));
+
+            for (i, stats) in language_stats.iter().take(5).enumerate() {
+                println!(
+                    "  {}. {}: {} lines ({} files)",
+                    i + 1,
+                    stats.language_name,
+                    stats.total_lines,
+                    stats.file_count
+                );
+            }
+        }
+        Err(e) => {
+            eprintln!("Failed to analyze repository: {}", e);
+            eprintln!("Make sure:");
+            eprintln!("1. GITHUB_TOKEN is set and valid");
+            eprintln!("2. Token has access to the repository");
+            eprintln!("3. Repository URL is correct");
+        }
+    }
+
+    Ok(())
+}