cargo-bless

A Cargo subcommand that checks your dependencies against blessed.rs recommendations and suggests modern alternatives.

cargo-bless checks whether your Rust dependency tree is modern, boring, and defensible.

What it does

• Scans your Cargo.toml dependency tree (direct + transitive, with features)
• Matches against a built-in rule database sourced from blessed.rs
• Detects single-crate replacements and combo optimizations (e.g. dropping serde_json when reqwest has the json feature)
• Runs a built-in bullshit detector code audit for suspicious Rust complexity patterns
• Fetches live metadata from crates.io (latest version, downloads) and GitHub (last push, archived status)
• Optionally applies safe fixes to your Cargo.toml with --fix (preview first with --dry-run)

What cargo-bless is not

• It is not a replacement for cargo audit, cargo deny, or license/security policy tooling.
• It is not automatic truth. Recommendations include confidence, migration risk, autofix safety, and evidence source.
• It is not a source rewriter. --fix only applies rules marked as safe Cargo.toml-only edits.
• It is not a command to blindly run in production without reading the report.

Installation

From crates.io:

cargo install cargo-bless

From source:

git clone https://github.com/Ruffian-L/cargo-bless
cd cargo-bless
cargo install --path .

Usage

cargo bless                  # scan and report
cargo bless bs               # run only the bullshit detector code audit
cargo bless bs --diff        # audit only lines changed since HEAD
cargo bless --fix --dry-run  # preview changes without writing
cargo bless --fix            # apply changes (creates .bak backup)
cargo bless --update-rules   # fetch latest rules from blessed.rs
cargo bless --json           # output suggestions as JSON
cargo bless --offline        # skip network calls, use local cache only
cargo bless --no-audit-code  # skip the default code audit

CLI Flags

Policy File (bless.toml)

Drop a bless.toml next to your Cargo.toml to customize behavior:

# Ignore specific packages
ignore_packages = ["internal-crate"]

# Per-package overrides
[packages.lazy_static]
suppress = true
keep_reason = "We use lazy_static for cross-crate compatibility"

# Global settings
[settings]
offline = true
max_suggestions = 10

[code_audit]
ignore_paths = ["src/generated", "tests/fixtures"]
ignore_kinds = ["UnwrapAbuse"]

Or pass a custom path: cargo bless --policy=custom-bless.toml

Example

$ cargo bless

🔥 cargo-bless v0.1.3

📋 Scanning dependencies...

📦 Direct dependencies (16)
  • reqwest 0.12.28 [json, default-tls, ...]
  • serde_json 1.0.149 [default, ...]
  ...

Found 16 direct deps, 317 total.

🌐 Fetching live intelligence...

🚀 Modernization report for my-project v0.1.0

 • [LOW] reqwest+serde_json → reqwest with "json" feature
   [HIGH confidence] [LOW risk] [autofix: Cargo.toml-only] evidence: crate docs
   reqwest can deserialize JSON directly when its json feature is enabled; cargo-bless only suggests this when serde_json is not used directly in source
      latest: v0.13.2, 64.6M recent downloads

0 high-impact upgrades available.

🧨 Bullshit detector code audit
Scanned 8 Rust files.
🚨 Bullshit detected: 2 findings
unwrap abuse: 1, fake complexity: 1

 • unwrap abuse src/main.rs:14:35
   unwrap() is a runtime trap dressed up as confidence.
   Fix: Propagate the error with ?, add context, or handle the failure explicitly.

$ cargo bless --fix --dry-run

🔍 Dry-run: the following changes would be made:

--- Cargo.toml (original)
+++ Cargo.toml (modified)

- serde_json = "1"

Changes that would be applied:
  ✓ Removed `serde_json`, enabled `json` feature on `reqwest`

Built-in rules

Each rule carries trust metadata:

• impact: how important the dependency choice may be.
• confidence: how strong the recommendation is.
• migration_risk: how likely the change is to require careful review.
• autofix_safety: whether cargo bless --fix may edit Cargo.toml.
• evidence_source: where the recommendation is grounded.

Rules are embedded at compile time from data/suggestions.json. PRs to add more are welcome.

How --fix works

Only suggestions marked autofix_safety = "CargoTomlOnly" are auto-fixable.

StdReplacement, Unmaintained, ModernAlternative, and ComboWin are reported but not auto-fixed by default, since they usually require source code changes or architectural judgment.

Code-audit findings are advisory in this release. --fix only edits dependency declarations in Cargo.toml; it never rewrites Rust source files.

Before any write, --fix creates a Cargo.toml.bak backup and runs cargo update afterward.

How it works

1. cargo_metadata parses the full resolved dependency tree with features
2. Rules from data/suggestions.json are matched against direct deps (single-crate and combo patterns)
3. crates_io_api::SyncClient fetches live metadata (cached to ~/.cache/cargo-bless/ with 1-hour TTL)
4. reqwest checks GitHub for pushed_at, archived, and star count
5. The bullshit detector scans Rust files under src, tests, examples, and benches for static complexity patterns
6. toml_edit applies fixes while preserving comments and formatting

Network calls are non-fatal — if you're offline, the rule-based report still works.

License

MIT -- see LICENSE-MIT.