rust-crate-discovery

Rust クレートの発見と評価

情報源：crates.io API、docs.rs、GitHub REST API、RustSec Advisory Database。

このスキルは、クレートを Cargo.toml に追加する前の発見と評価の段階を担当します。同梱の Python ツール（scripts/crate_eval.py）を使って 4 つの情報源から情報を取得し、重み付けした 0～100 のスコア、文字評価（A/B/C/D/F）、危険信号の一覧、および推奨を提示します。導入後のガバナンス（rust-dependencies）、マニフェストの仕組み（rust-cargo-build）、semver（rust-semver）は対象外です。

対応範囲

✅ 得意なこと

1. crates.io をキーワード、カテゴリ、名前で検索し、候補をランキング形式で表示します
2. 1 つのクレートを詳細に評価し、crates.io、docs.rs、GitHub、RustSec からメタデータを取得します
3. 2 つ以上のクレートをサブスコアの内訳付きで横並びに比較します
4. 各クレートを 6 つの評価軸（採用状況（30）、メンテナンス（25）、ドキュメント（15）、成熟度（15）、コミュニティ（10）、ライセンス（5））で 0～100 点で評価します
5. 古さ、アドバイザリ、ドキュメントなし、採用数の少なさと入れ替わりの多さ、メンテナーが 1 人であることによるバス係数、ソースリポジトリなし、ライセンス不明などの危険要素を検出します
6. 最適な選択肢を推奨し、ユーザーが採用する前に阻害要因を提示します
7. 人が読めるレポート、または機械可読な JSON（エージェント向け）で出力します

⚠️ 前提条件

1. ネットワークアクセス（ツールは crates.io、docs.rs、GitHub、RustSec から情報を取得します）
2. Python 3.9 以降（外部 pip パッケージ不要。標準ライブラリのみ）

❌ 対象外

1. 導入後のガバナンス（cargo-deny の設定、ライセンスポリシー、アドバイザリへの対応ワークフロー）→ rust-dependencies
2. Cargo.toml のフィールドの意味→ rust-cargo-build
3. semver と破壊的変更の分類→ rust-semver
4. クレートの代わりにどの std 型を使うか→ rust-stdlib

データのプライバシー

このスキルは、crates.io、docs.rs、GitHub、RustSec に HTTP リクエストを送信します。User-Agent にはツールが識別できる情報が含まれます。ユーザーデータの収集や送信は行いません。URL パスに含まれるクレート名（公開レジストリのデータ）のみが送信されます。非公開または独自のクレート名の場合は、手動でのレビューをおすすめします。

---

評価ツール — scripts/crate_eval.py

標準ライブラリのみを使用する Python スクリプトです。サブコマンドは 3 つあります。

# 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

ワークフロー

1. 検索 — search "<domain keyword>" を実行して候補を見つけます。ダウンロード数と更新時期を基に上位 5～10 件を確認します。
2. 候補を絞り込む — 採用実績が無視できない程度（ダウンロード数 1,000 以上）で、最近も活動がある名前を 2～4 個選びます。
3. 比較 — compare <names...> を実行して、横並びのスコアカードを取得します。
4. 危険信号を調査する — 最有力候補について、危険信号の一覧を確認します。セキュリティアドバイザリがある場合は採用を見送り、更新の停滞やメンテナーが 1 人であることへの懸念は調査します。
5. 適合性を確認する — スコアが測るのは健全性であり、用途への適合性ではありません。クレートのドキュメントを読み、API の形状（rust-api-design の観点）を確認し、ユースケースを満たすことを確かめます。
6. 引き継ぐ — 採用後は cargo-deny（rust-dependencies）を設定し、バージョンポリシー（rust-semver）を固定します。

出力の見方

=== 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

• 評価 + スコア — 健全性を一目で把握できます
• サブスコア — どの評価軸が強いか、弱いかを確認できます
• 注記（+）— 肯定的なシグナル
• 危険信号（!）— 採用前に調査すべき懸念
• 推奨 — 判定（RECOMMENDED / LIKELY SUITABLE / ACCEPTABLE / CAUTION / BLOCK / RISKY）

---

スコアリングモデル

評価項目	最大点	評価内容	主な指標
採用状況	30	利用者はいるか？	累計ダウンロード数、直近（90日間）のダウンロード数
メンテナンス状況	25	活発にメンテナンスされているか？	crates.io の最終更新日、バージョン数、GitHub の最終コミット
ドキュメント	15	ユーザーが使い方を学べるか？	docs.rs のビルド状況、説明、ドキュメント URL、リポジトリへのリンク
成熟度	15	API は安定しているか？	経過期間、安定版が ≥1.0、リポジトリの有無
コミュニティ	10	貢献者の基盤はあるか？	GitHub のスター数、貢献者数
ライセンス	5	寛容なライセンスか？	寛容なライセンス（MIT/Apache/BSD）を優先し、コピーレフトは減点
合計	100

グレード区分

グレード	スコア	意味
A	≥85	優秀 — 推奨
B	70-84	良好 — おそらく適しています
C	55-69	許容範囲 — 適合性を確認してください
D	40-54	リスクあり — 使用前に調査してください
F	<40	回避 — 懸念事項が重大です

完全な計算式と指標の重み付けについては、references/scoring-rubric.md を参照してください。

---

注意事項カタログ

このツールは具体的な懸念事項を提示します。採用する前に、必ずこれらを確認してください。

フラグ	重大度	対応
RustSec アドバイザリ	ブロック	修正版に固定するか、代替を選んでください
12 か月以上リリースなし	高	放棄されていないか確認し、フォークまたは代替を検討してください
GitHub の最終コミットから 6 か月以上	高	活動が別の場所に移っている可能性があります
docs.rs のビルドなし	中	API ドキュメントがない可能性があります。手動で確認してください
ライセンスの記載なし	中	プロプライエタリとして扱い、明確化なしに使用しないでください
バージョン数が多いのに採用数が少ない	中	利用が伸びないまま変更が重ねられています。品質を調査してください
1.0 より前でバージョン数が 20 以上	中	マイナーバージョンの更新でも API が不安定な可能性があります
メンテナーが 1 人で採用数も少ない	中	バス係数のリスクがあります。バックアップまたはフォークを検討してください
ソースリポジトリなし	高	監査できません。回避してください

完全なカタログと判断のガイダンスについては、references/red-flags.md を参照してください。

---

判断の簡易ガイド

質問	回答
X にはどのクレートがよいですか？	search "X" を実行し、上位 3～4 件を compare で比較してください
このクレートは安全ですか？	eval <name> を実行し、注意事項でアドバイザリを確認してください
メンテナンスされていますか？	eval <name> を実行し、メンテナンスのサブスコアと最終更新日を確認してください
API は安定していますか？	eval <name> を実行し、成熟度のサブスコアとバージョン ≥1.0 を確認してください
ライセンスは何ですか？	eval <name> を実行してください。シグナルに表示されます
A と B と C のどれがよいですか？	compare A B C を実行し、ブロック対象の注意事項がない中で最高スコアのものを選んでください
スコアは A ですが、ユースケースに合いません	スコアより適合性の確認を重視してください。スコアが測るのは健全性であり、適合性ではありません

スコアが誤解を招く場合

• ニッチなクレート — ドメイン固有のクレートは、ダウンロード数が少なくても唯一の選択肢かもしれません。スコアは実態より低くなります。手動レビューを頼りにしてください。
• 新しいクレート — リリースから日が浅いクレートは採用状況の指標が低くなります。代わりにメンテナーの実績を確認してください。
• フォーク — ダウンロード数は少なくても、メンテナンスされている後継版である可能性があります。元のクレートの状況を確認してください。
• 内部／プライベートクレート — crates.io にないため、このツールでは役に立ちません。手動でレビューしてください。

---

リソース

• スコアリング基準 — 完全な計算式、対数スケールのパラメーター、サブスコアの内訳
• 注意事項カタログ — 重大度と対応を含む全フラグ一覧
• API エンドポイントのリファレンス — 4 つのデータソースとそのエンドポイント
• 評価ワークフローの例 — シナリオ例（ORM の選択、HTTP クライアント、ロギング）
• scripts/crate_eval.py — 評価ツール（python3 で実行）

上流の情報源

• crates.io API — 検索、クレートのメタデータ、バージョンのダウンロード
• docs.rs — ドキュメントのビルド状況、バージョンの有無
• GitHub REST API — スター数、コントリビューター、最終コミット、未解決のイシュー
• RustSec Advisory Database — 既知の脆弱性
• crates.io-index — レジストリインデックス（API の代替）