cargo-perspective 0.1.0

# Cargo Perspective

**A visual TreeMap analyzer for Rust dependency usage**

[![Crates.io](https://img.shields.io/crates/v/cargo-perspective.svg)](https://crates.io/crates/cargo-perspective)
[![Documentation](https://docs.rs/cargo-perspective/badge.svg)](https://docs.rs/cargo-perspective)
[![License](https://img.shields.io/badge/license-MIT%2FUnlicense-blue.svg)](https://github.com/cryptopatrick/cargo-perspective)

Inspired by [GrandPerspective](https://grandperspectiv.sourceforge.net/), Cargo Perspective helps you understand which dependencies your Rust project uses most by visualizing them in an interactive TreeMap.

## Overview

Cargo Perspective analyzes your Rust project's dependencies and visualizes how often each crate is called throughout your codebase. Unlike traditional dependency trees, it shows you **actual usage patterns**, not just the dependency graph.

Each rectangle in the TreeMap represents a crate, sized proportionally to how many times it's called in your code. This helps you:
- Identify which dependencies are actually used (vs. just declared)
- Spot over-reliance on specific crates
- Find opportunities to optimize or reduce dependencies
- Understand your project's true dependency footprint

## Key Features

### MVP (v0.1) - ✅ Complete
- **AST-based call analysis**: Scans Rust source files to count function, method, and macro calls to dependencies
- **Interactive TreeMap visualization**: Built with Dioxus, showing crates as rectangles sized by call count
- **Hover tooltips**: Display crate name, call count, and dependency type (direct/transitive)
- **Zoom functionality**: Click on a crate to zoom into its methods (future enhancement)
- **CLI and GUI modes**:
  - `--gui`: Launch interactive TreeMap (default)
  - `--text`: Legacy text-based report mode (from deppy.sh)

### Planned Features
- **v0.2**: Color coding by execution time (green = fast, red = slow), transitive dep filtering
- **v0.3**: AI-assisted call pattern analysis, feature-level breakdowns
- **v1.0**: Export to PNG/SVG, persistent caching, workspace support

## Architecture

```
cargo-perspective/
├── src/
│   ├── analysis.rs      # AST-based call counting using syn
│   ├── treemap.rs       # Squarified TreeMap layout algorithm
│   ├── types.rs         # Core data structures (ProjectAnalysis, TreeMapNode, etc.)
│   ├── ui.rs            # Dioxus desktop UI
│   └── main.rs          # CLI entry point
└── Cargo.toml
```

## Quick Start

```bash
# Clone the repository
git clone https://github.com/cryptopatrick/cargo-perspective
cd cargo-perspective

# Build the project
cargo build --release

# Run on your Rust project
cargo-perspective --gui

# Or use text mode for quick stats
cargo-perspective --text
```

### Options

```
--skip-build     Skip the initial cargo build step
--gui            Launch interactive TreeMap visualization (default)
--text           Show text-based analysis report
```

## How It Works

1. **Metadata Collection**: Uses `cargo metadata` to build the dependency graph
2. **AST Analysis**: Parses all `.rs` files with `syn` to detect calls like:
   - Function calls: `tokio::spawn(...)`
   - Method calls: `stream.read_to_end()`
   - Macros: `println!`, `tokio::select!`
3. **TreeMap Layout**: Applies squarified TreeMap algorithm for optimal rectangle aspect ratios
4. **Visualization**: Renders with Dioxus in a native desktop window

## Examples

```bash
# Analyze this project itself
cd cargo-perspective
cargo run --bin cargo-perspective -- --skip-build --gui

# Output:
# Analyzing project dependencies...
# Found 3 crates with 3 total calls
# Launching GUI...
#
# [TreeMap shows: cargo_metadata (50%), anyhow (16.7%), regex (16.7%), etc.]
```

The original bash script (`_dev/deppy.sh`) is now available as `--text` mode for quick terminal-based analysis.

## Contributing
Contributions are welcome! 
Please see our [contributing guidelines](CONTRIBUTING.md) for details on:
- Code style and testing requirements
- Submitting bug reports and feature requests
- Development setup and workflow

## License
This project is licensed under MIT. See [LICENSE](LICENSE) for details.