rust-crate-discovery

# Rust Crate Discovery and Evaluation > Authority: [crates.io API](https://crates.io/data-access), [docs.rs](https://docs.rs), [GitHub REST API](https://docs.github.com/en/rest), [RustSec Advisory Database](https://rustsec.org/). This skill owns the **discovery + evaluation phase** before a crate enters your `Cargo.toml`. It uses a bundled Python tool (`scripts/crate_eval.py`) to fetch signals from 4 sources and produce a weighted 0-100 score with a letter grade (A/B/C/D/F), red-flag list, and a recommendation. It does **not** own post-adoption governance (`rust-dependencies`), manifest mechanics (`rust-cargo-build`), or semver (`rust-semver`). ## Capability Boundaries ### ✅ Strengths 1. Search crates.io by keyword, category, or name — returns ranked candidates 2. Evaluate a single crate in depth: fetch metadata from crates.io + docs.rs + GitHub + RustSec 3. Compare 2+ crates side-by-side with subscore breakdown 4. Score each crate 0-100 across 6 dimensions: adoption (30), maintenance (25), documentation (15), maturity (15), community (10), license (5) 5. Flag red concerns: stale, advisories, no docs, low adoption with churn, single-maintainer bus factor, no source repo, license missing 6. Recommend the best fit, surfacing blocking concerns before the user adopts 7. Output as human-readable report or machine-readable JSON (for agent consumption) ### ⚠️ Prerequisites 1. Network access (the tool fetches from crates.io, docs.rs, GitHub, RustSec) 2. Python 3.9+ (no external pip packages — stdlib only) ### ❌ Out of Scope 1. Post-adoption governance (cargo-deny config, license policy, advisory response workflow) → `rust-dependencies` 2. Cargo.toml field semantics → `rust-cargo-build` 3. Semver and breaking-change classification → `rust-semver` 4. Which std type to use instead of a crate → `rust-stdlib` ## Data Privacy This skill makes outbound HTTP requests to crates.io, docs.rs, GitHub, and RustSec. The User-Agent identifies the tool. No user data is collected or transmitted beyond the crate name in the URL path (which is public registry data). For private/proprietary crate names, prefer manual review. --- # The Evaluation Tool — `scripts/crate_eval.py` A stdlib-only Python script. Three subcommands: ```bash # Search candidates python3 scripts/crate_eval.py search "orm" python3 scripts/crate_eval.py search "http client" --limit 5 python3 scripts/crate_eval.py search "logging" --category "development-tools::debugging" # Evaluate one crate in depth python3 scripts/crate_eval.py eval rbatis python3 scripts/crate_eval.py eval rbatis --json # machine-readable python3 scripts/crate_eval.py eval rbatis -v # show raw signals python3 scripts/crate_eval.py eval rbatis --skip-github # faster, less signal # Compare multiple candidates python3 scripts/crate_eval.py compare rbatis diesel sea-orm sqlx ``` ## Workflow 1. **Search** — `search "<domain keyword>"` to surface candidates. Inspect the top 5-10 by downloads and recency. 2. **Shortlist** — pick 2-4 names with non-trivial adoption (≥1k downloads) and recent activity. 3. **Compare** — `compare <names...>` to get the side-by-side scorecard. 4. **Investigate red flags** — for the top pick, read the red-flag list. Block on security advisories; investigate stale or single-maintainer concerns. 5. **Verify fit** — the score measures *health*, not *fitness*. Read the crate's docs, check its API shape (`rust-api-design` lens), confirm it covers your use case. 6. **Hand off** — once adopted, set up `cargo-deny` (`rust-dependencies`) and pin version policy (`rust-semver`). ## Reading the output ``` === rbatis === A (92/100) — RECOMMENDED — strong fit, low risk version 4.9.6 | 657,356 downloads (19,938 recent) | license: Apache-2.0 Subscores: adoption █████████████░░░░░░░░░░░░ 27/30 maintenance ████████████░░░░░░░░░░░░░ 25/25 ... Red flags: ! license not declared ``` - **Grade + score** — at-a-glance health - **Subscores** — which dimensions are strong/weak - **Notes** (`+`) — positive signals - **Red flags** (`!`) — concerns to investigate before adopting - **Recommendation** — verdict (RECOMMENDED / LIKELY SUITABLE / ACCEPTABLE / CAUTION / BLOCK / RISKY) --- # Scoring Model | Dimension | Max | What it measures | Key signals | |-----------|-----|------------------|-------------| | **Adoption** | 30 | Is anyone using this? | all-time downloads, recent (90-day) downloads | | **Maintenance** | 25 | Is it actively maintained? | last crates.io update, version count, GitHub last commit | | **Documentation** | 15 | Can users learn it? | docs.rs build, description, docs URL, repo link | | **Maturity** | 15 | Is the API stable? | age, stable version ≥1.0, has repo | | **Community** | 10 | Is there a contributor base? | GitHub stars, contributors | | **License** | 5 | Is it permissive? | permissive (MIT/Apache/BSD) preferred; copyleft penalized | | **Total** | 100 | | | ## Grade bands | Grade | Score | Meaning | |-------|-------|---------| | **A** | ≥85 | Excellent — recommended | | **B** | 70-84 | Good — likely suitable | | **C** | 55-69 | Acceptable — verify fit | | **D** | 40-54 | Risky — investigate before use | | **F** | <40 | Avoid — significant concerns | See `references/scoring-rubric.md` for the full formula and signal weights. --- # Red Flags Catalog The tool surfaces specific concerns. Always read these before adopting. | Flag | Severity | Action | |------|---------|--------| | RustSec advisory | **Block** | Pin to fixed version or pick alternative | | No release in >12 months | High | Check if abandoned; consider fork or alternative | | Last GitHub commit >6 months | High | Activity may have moved elsewhere | | No docs.rs build | Medium | API docs may be missing; check manually | | License not declared | Medium | Treat as proprietary; cannot use without clarification | | Low adoption with many versions | Medium | Churn without traction; investigate quality | | Pre-1.0 with 20+ versions | Medium | API likely unstable across minor bumps | | Single maintainer + low adoption | Medium | Bus factor risk; consider backing up or forking | | No source repository | High | Cannot audit; avoid | See `references/red-flags.md` for the full catalog and decision guidance. --- # Decision Shortcuts | Question | Answer | |---------|--------| | Which crate for X? | `search "X"`, then `compare` top 3-4 | | Is this crate safe? | `eval <name>`; check red flags for advisories | | Is it maintained? | `eval <name>`; check maintenance subscore + last update | | Is the API stable? | `eval <name>`; check maturity subscore + version ≥1.0 | | What's the license? | `eval <name>`; appears in signals | | A vs B vs C? | `compare A B C`; pick highest score without blocking red flags | | Score says A but it doesn't fit my use case | Trust the fit check over the score — score measures health, not fitness | ## When the score is misleading - **Niche crates** — a domain-specific crate may have low downloads but be the only option. Score will understate; rely on manual review. - **New crates** — recent releases have low adoption signals; check maintainer track record instead. - **Forks** — a fork may have few downloads but be the maintained successor. Check the parent crate's status. - **Internal/private crates** — not on crates.io; this tool won't help. Use manual review. --- ## Resources - [Scoring Rubric](references/scoring-rubric.md) — full formula, log-scale parameters, subscore breakdowns - [Red Flags Catalog](references/red-flags.md) — full flag list with severity and action - [API Endpoints Reference](references/api-endpoints.md) — the 4 data sources and their endpoints - [Evaluation Workflow Examples](examples/evaluation-examples.md) — worked scenarios (ORM choice, HTTP client, logging) - [`scripts/crate_eval.py`](scripts/crate_eval.py) — the evaluation tool (run with `python3`) ## Upstream Sources - [crates.io API](https://crates.io/data-access) — search, crate metadata, version downloads - [docs.rs](https://docs.rs) — documentation build status, version presence - [GitHub REST API](https://docs.github.com/en/rest) — stars, contributors, last commit, open issues - [RustSec Advisory Database](https://rustsec.org/) — known vulnerabilities - [crates.io-index](https://github.com/rust-lang/crates.io-index) — registry index (alternative to API)