dep-insight 1.0.0

# 🧩 dep-insight

[![Crates.io](https://img.shields.io/crates/v/dep-insight.svg)](https://crates.io/crates/dep-insight)
[![Documentation](https://docs.rs/dep-insight/badge.svg)](https://docs.rs/dep-insight)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> **Your Rust Project's Detective Friend!**

`dep-insight` is a powerful dependency analysis, auditing, and visualization tool for Rust projects. It helps you understand your project's dependency graph, find duplicates, check for security vulnerabilities, audit licenses, and visualize everything in an interactive web view.

## ✨ Features

- 🔍 **Dependency Analysis**: Understand your complete dependency tree
- ⚠️ **Duplicate Detection**: Find and consolidate duplicate crate versions
- 🛡️ **Security Auditing**: Scan for known vulnerabilities via RustSec (optional)
- ⚖️ **License Compliance**: Track licenses and enforce policies
- ⏱️ **Heavy Crate Detection**: Identify dependencies with large transitive graphs
- 🎨 **Interactive Visualization**: Beautiful D3.js-based dependency graphs
- 📊 **Multiple Output Formats**: Terminal, JSON, and HTML reports
- 🏢 **Workspace Support**: Works seamlessly with cargo workspaces

## 🚀 Installation

```bash
cargo install dep-insight
```

## 📖 Usage

### Global Options

- **--no-color**: Disable colored output (also respects NO_COLOR env var and TTY detection)
- **-v, --verbose**: Enable verbose logging
- **-q, --quiet**: Suppress non-error output
- **--profile**: Show performance diagnostics
- **--config <path>**: Use a custom config file (works with analyze, duplicates, visualize, and audit commands)

### Basic Analysis

```bash
# Analyze current project
cargo dep-insight analyze

# Analyze specific project
cargo dep-insight analyze /path/to/project

# Run with security audit (requires audit feature)
cargo dep-insight analyze --audit

# Output JSON
cargo dep-insight analyze --json report.json

# Generate HTML report
cargo dep-insight analyze --html deps.html
```

### Find Duplicates

```bash
cargo dep-insight duplicates
```

### View Dependency Tree

```bash
# Show dependency tree
cargo dep-insight tree

# ASCII-only output
cargo dep-insight tree --ascii

# Focus on specific package in workspace
cargo dep-insight tree --package my-crate
```

### Interactive Visualization

```bash
# Generate and open HTML visualization
cargo dep-insight visualize

# Save without opening
cargo dep-insight visualize --out report.html --no-open
```

### Security & License Audit

Requires the `audit` feature:

```bash
cargo install dep-insight --features audit
cargo dep-insight audit
```

Note: The audit command respects the `audit.fetch` setting in `.depinsight.toml`. Set `fetch = false` to avoid fetching the RustSec database and run in offline mode.

### Configuration Validation

```bash
cargo dep-insight config validate
```

## ⚙️ Configuration

Create a `.depinsight.toml` in your project root:

```toml
[output]
color = true
max_heavy = 10

[audit]
# requires 'audit' feature
fetch = false

[license]
# deny or warn on specific licenses (use SPDX short identifiers)
# Note: SPDX parser normalizes "-only" suffixes (e.g., "GPL-3.0-only" → "GPL-3.0")
deny = ["GPL-3.0", "AGPL-3.0"]
warn = ["LGPL-2.1"]

[online]
# requires 'online' feature
crates_io = false
rate_limit_per_min = 10
```

## 📊 JSON Schema

The JSON output follows a versioned schema:

```json
{
  "schema_version": "1.0",
  "tool": {
    "name": "dep-insight",
    "version": "0.3.0"
  },
  "workspace_root": "/path/to/project",
  "summary": {
    "total_dependencies": 56,
    "unique_crates": 42,
    "duplicate_crates": 4
  },
  "diagnostics": {
    "duplicates": [...],
    "vulnerabilities": [...],
    "licenses": {...},
    "heavy": [...]
  },
  "graph": {
    "nodes": [...],
    "edges": [...]
  },
  "suggestions": [...]
}
```

## 📚 Library Usage

`dep-insight` can also be used as a library:

```rust
use dep_insight::{analyze_project, report_to_json};

fn main() -> anyhow::Result<()> {
    // Analyze without security audit
    let report = analyze_project(".", false)?;
    println!("Found {} dependencies", report.summary.total_dependencies);
    
    // Export to JSON
    let json = report_to_json(&report)?;
    std::fs::write("report.json", json)?;
    
    Ok(())
}
```

## 🔧 Features

- `web` (default): Enable HTML visualization with embedded assets
- `audit`: Enable security vulnerability scanning via RustSec
- `online`: Enable online features like crates.io API queries

```bash
# Install with all features
cargo install dep-insight --all-features

# Install without web assets
cargo install dep-insight --no-default-features
```

## 🛠️ Development

### Build

```bash
cargo build --release
```

### Test

```bash
cargo test --all
```

### Format & Lint

```bash
cargo fmt --all
cargo clippy --all-targets -- -D warnings
```

## 📋 Requirements

- Rust 1.70+ (MSRV)
- Cargo projects with `Cargo.toml` and optionally `Cargo.lock`

## 🐛 Troubleshooting

### "No Cargo.lock found"

Run `cargo generate-lockfile` in your project to create a lockfile for more accurate dependency resolution.

### "Failed to load cargo metadata"

Ensure you're running the command in a valid Cargo project directory.

### Offline Mode

By default, `dep-insight` works offline. Enable `audit` or `online` features only if you need vulnerability scanning or crates.io queries.

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes using conventional commits
4. Push to the branch
5. Open a Pull Request

## 📜 License

Licensed under the MIT License. See [LICENSE](LICENSE) for details.

## 🔒 Security

See [SECURITY.md](SECURITY.md) for reporting security vulnerabilities.

## 📝 Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.

## 👤 Author

**Eshan Roy** - [Tonmoy Infrastructure & Vision](https://tivision.dev)

## 🌟 Acknowledgments

- Built with [Rust](https://www.rust-lang.org/)
- Visualization powered by [D3.js](https://d3js.org/)
- Security data from [RustSec](https://rustsec.org/)

## 💡 Stability

- **Public library API**: Follows SemVer strictly
- **CLI human-readable output**: Best-effort stability; use `--json` for stable machine parsing
- **JSON schema**: Versioned and backwards compatible within major versions

---

Made with ❤️ by the TIVision team