cargo-advisor

cargo-advisor is the decision layer for Cargo: explainable crate recommendation, comparison, explanation, and local dependency review with explicit receipts.

The project is local-first. It keeps the evidence boundary narrow on purpose:

• recommend picks from a curated, checked-in catalog by intent and goal.
• compare explains tradeoffs across named crates in that catalog.
• explain turns one crate into a recommendation narrative.
• review inspects local Cargo.toml and Cargo.lock files for overlapping dependency decisions.
• Every result stays explanation-first and includes confidence, tradeoffs, trust notes, and receipts.

This project uses review, not audit. It does not fake live crates.io, docs.rs, RustSec, download, or maintenance evidence. If a source is not consulted, the output should say so.

Install

Install from crates.io:

cargo install cargo-advisor

For local development, you can still install from the workspace path:

cargo install --path crates/cargo-advisor-cli --locked

That installs the cargo-advisor binary as a Cargo subcommand, so you can run:

cargo advisor recommend cli --goal "small binary"

You can also run it from the workspace without installing:

cargo run -p cargo-advisor -- recommend cli --goal "small binary"

Usage

Examples:

cargo advisor recommend cli-parsing
cargo advisor recommend cli --goal "fastest to ship"
cargo advisor recommend http-client --goal blocking --format json
cargo advisor compare reqwest ureq hyper --for http-client
cargo advisor explain thiserror --for error-handling
cargo advisor review --manifest-path ./Cargo.toml --lockfile ./Cargo.lock

Current intent coverage:

• cli-parsing
• config
• logging-tracing
• http-client
• http-server
• serialization
• async-runtime
• error-handling
• testing
• database-access

Output Contract

The default renderer is text, but --format json exposes the same explanation-first contract in machine-readable form. Shared concepts across commands:

• summary
• recommendation
• confidence
• tradeoffs
• trust_notes
• receipts

Command-specific JSON fixtures are checked in under tests/fixtures/contracts/ as release/reference fixtures for the explanation-first output contract.

The current contract is documented in docs/v0.1-plan.md.

Workspace

The workspace currently has five crates:

• crates/cargo-advisor-cli: binary and command parser
• crates/advisor-core: shared report models and decision logic
• crates/advisor-catalog: curated intent catalog
• crates/advisor-evidence: local evidence loading and receipts
• crates/advisor-output: text and JSON rendering

Verification

Phase planning lives in BUILD.md. CI mirrors the local verification bar in ci.yml:

cargo fmt --all --check
cargo test --workspace
cargo check --workspace
cargo clippy --workspace --all-targets -- -D warnings

Release Hygiene

• Dual-licensed under MIT OR Apache-2.0; see LICENSE-MIT and LICENSE-APACHE.
• Release notes live in CHANGELOG.md.
• The local release checklist lives in RELEASE.md.

Design Boundaries

• Recommendations stay deterministic and checked into source.
• Review findings are heuristic and local-only.
• External evidence integrations remain future work until their receipts and trust boundaries are visible in output.