Quarry

Quarry is a Rust library for mining type information from the Rust standard library. It provides access to struct field information, including private fields, by analyzing the actual standard library installed on your system.

Note: The API is currently unstable.

Scope and Limitations

Current Focus: Quarry currently analyzes structs only. Popular types like Option<T> and Result<T, E> (which are enums) cannot be analyzed yet.

Planned Features: Support for enums, traits, and other types is planned for future releases. If you need enum analysis immediately, consider using rustdoc directly.

Overview

Quarry dynamically analyzes the Rust standard library installed on your system to extract detailed information about structs, including:

• Field names and types (including private fields)
• Visibility (public/private)
• Struct type (named, tuple, or unit struct)
• Full module path resolution

Requirements

To use the full functionality of Quarry, you need:

1. Nightly Rust toolchain (for rustdoc JSON generation):

   rustup toolchain install nightly
   

2. Rust source code (for analyzing the standard library):

   rustup component add rust-src --toolchain nightly
   

Installation

Add this to your Cargo.toml:

[dependencies]
quarry = "0.1.0"

Usage

Basic Usage

use quarry::mine_struct_info;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Analyze alloc::string::String (requires full module path)
    let result = mine_struct_info("alloc::string::String")?;
    
    println!("Struct: {}", result.name);
    println!("Simple name: {}", result.simple_name);
    println!("Module path: {}", result.module_path);
    
    // Print fields (including private fields)
    for field in result.fields {
        println!("  {} -> {} (public: {})", 
            field.name, field.type_name, field.is_public);
    }
    
    Ok(())
}

Full Module Paths Required

Quarry requires explicit, full module paths to ensure unambiguous type resolution:

// ✅ Correct usage - full module paths
let string_info = mine_struct_info("alloc::string::String")?;
let vec_info = mine_struct_info("alloc::vec::Vec")?;
let hashmap_info = mine_struct_info("std::collections::HashMap")?;

// ❌ Incorrect usage - will fail
let result = mine_struct_info("String"); // Error: requires full path
let result = mine_struct_info("Vec");    // Error: requires full path

Cache Management

Quarry caches the analyzed standard library information for performance:

use quarry::{init_stdlib_cache, cache_stats, clear_stdlib_cache};

// Initialize cache explicitly (optional)
init_stdlib_cache()?;

// Check cache statistics
let (count, initialized) = cache_stats()?;
println!("Cache has {} types, initialized: {}", count, initialized);

// Clear cache if needed
clear_stdlib_cache();

Listing Available Types

use quarry::list_stdlib_structs;

// Get all available standard library struct types
let structs = list_stdlib_structs()?;
for struct_name in structs {
    println!("{}", struct_name);
}

Checking Type Availability

use quarry::is_stdlib_struct;

// Quick check if a type exists in the standard library
if is_stdlib_struct("alloc::string::String") {
    println!("String is available in the standard library");
}

Debugging and Logging

Quarry includes comprehensive debug logging throughout the analysis pipeline. This is especially useful for understanding what's happening during cache initialization, type lookup, and rustdoc generation.

Enabling Debug Logs

Quarry uses the standard log crate for logging. To see debug output, add env_logger to your dependencies and initialize it:

[dependencies]
env_logger = "0.11"

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the logger to see debug output
    env_logger::init();
    
    // Your code here...
}

Then run your application with the RUST_LOG environment variable:

# See all debug logs
RUST_LOG=debug cargo run

# See only Quarry debug logs
RUST_LOG=quarry=debug cargo run

# See only standard library module logs
RUST_LOG=quarry::stdlib=debug cargo run

Examples

Quarry includes comprehensive examples that demonstrate its capabilities:

Basic Usage Example

cargo run --example basic_usage

Shows fundamental usage including:

• Simple struct analysis
• Field information extraction
• Error handling
• Basic output formatting

Advanced Usage Example

cargo run --example advanced_usage

Demonstrates advanced features including:

• Cache management and statistics
• Bulk type analysis
• Type discovery and filtering
• Performance testing

Both examples can be run with debug logging:

RUST_LOG=quarry=debug cargo run --example basic_usage
RUST_LOG=quarry=debug cargo run --example advanced_usage

How It Works

Quarry uses the following approach:

1. Dynamic Analysis: Uses rustdoc to analyze the actual standard library source code installed on your system
2. Direct JSON Parsing: Parses the generated rustdoc JSON output directly to extract struct information including private fields
3. In-Memory Caching: Stores the parsed struct information in a lookup table for fast subsequent queries
4. Exact Path Matching: Takes user input as exact module paths (e.g., "alloc::string::String") and looks them up directly in the cache

Architecture

┌─────────────────┐
│   Your Code     │  mine_struct_info("alloc::string::String")
└─────────────────┘
          │
          ▼
┌─────────────────┐
│     Quarry      │  First call: run cargo doc → parse JSON → populate cache
│   (Public API)  │  Subsequent calls: direct lookup in cache
└─────────────────┘
          │
          ▼
┌─────────────────┐       ┌─────────────────┐
│  Memory Cache   │       │ Standard Library│
│   (HashMap)     │       │   Source Code   │
│ "alloc::string  │       │  (rust-src)     │
│ ::String" → ... │       └─────────────────┘
└─────────────────┘                │
                                   ▼
                          ┌─────────────────┐
                          │  cargo doc      │
                          │ --output-format │
                          │     json        │
                          └─────────────────┘

Error Handling

Quarry provides detailed error information:

• TypeNotFound: The requested type was not found in the standard library
• NotAStruct: The requested type exists but is not a struct
• StdlibAnalysis: Failed to generate or parse rustdoc JSON (usually due to missing nightly toolchain or rust-src)
• Io: File system or process execution errors

Limitations

• Standard Library Only: Currently only supports types from std, alloc, and core crates
• Nightly Rust Required: Requires nightly Rust toolchain for rustdoc JSON generation
• rust-src Component Required: Requires rust-src component for standard library analysis
• Struct Types Only: Currently focuses on struct types (enum and trait support will be added in future versions)
• Performance: Initial cache initialization depends on rustdoc generation speed

Contributing

Contributions are welcome! Please feel free to submit an issue or a pull request.

License

MIT License - see LICENSE file for details.