coral-review-source-spec

Coral レビューソース仕様

レビューの目的

ソースをプロダクトの一部としてレビューしてください。CI、スキーマ検証、YAML の lint 結果を主に言い換えるだけのレビューは避けてください。ただし、それらの失敗が目に見え、関連性がある場合は除きます。Coral のユーザーやエージェントにとって、ソースが理解しやすく、有用で、安全で、一貫性があるかどうかに注目してください。

ワークフロー

1. 対象のソースディレクトリまたは PR の変更を特定します。
   • パスが指定されている場合は、manifest.yaml、README、関連するソースドキュメントやテストを確認します。
   • PR が指定されている場合は、sources/core/ または sources/community/ 以下の変更ファイルを探します。PR でソースが追加も更新もされていない場合は、このスキルは適用対象外であると伝え、通常のレビューを行います。
2. スタイルを判断する前に、Coral リポジトリのガイダンスを読みます。
   • CONTRIBUTING.md、特に「Source contributions」。
   • リポジトリの AGENTS.md と、対象により近い場所にある AGENTS.md。
   • sources/core/ にある類似の既存ソースと、sources/community/hn/ にあるコミュニティ向けの例。
3. 一般的な API ラッパーの理想ではなく、既存のソースのパターンと比較します。形状の似た近隣のソースを確認します。たとえば、認証不要の公開 API、トークン API、OAuth 対応 API、GraphQL API、検索中心の API、ログ／時系列 API、大規模な自動生成 API などです。
4. コードレビュー形式で結果を提示します。ファイル名と行番号を示し、重要度の高い順に指摘事項を先に並べます。未解決の質問は、指摘事項の後に記載します。実質的な問題がない場合はその旨を述べ、残るリスクやレビュー上の不足点にも触れます。

レビューチェックリスト

これらの確認は、ソースが公開する API の信頼できる公式ドキュメントに基づいて行ってください。

スコープと適合性

• ソースが適切なツリーに配置されています。コミュニティソースは sources/community/ に配置します。sources/core/ への新規追加には、CONTRIBUTING.md に従った事前の議論が必要です。外部コントリビューターからの PR は、ほとんどの場合 sources/community に配置します。
• 新しいソースをレビューする場合、既存のソースと機能が重複していないことを確認します。
• ソース名は明確で安定した小文字の名前であり、ユーザーが入力する SQL スキーマ名と一致しています。
• スコープは一貫性を保てる範囲に絞られています。小規模なソースでは、周辺的なエンドポイントをすべて公開するのではなく、主なユーザーワークフローを提供します。
• 実際の認証情報、顧客データ、内部フィクスチャ、非公開 URL がコミットされていません。
• ユーザーから見える動作、テーブル、カラム、入力値、またはセマンティクスに変更がある場合、更新されたソースの version が引き上げられています。

セットアップとドキュメント

• トップレベルの description には、ベンダー API をラップしていることだけでなく、ユーザーが何を問い合わせられるかを記載します。
• inputs ではシークレットと変数を正しく区別し、わかりやすい環境変数形式の名前を使用し、初回のセットアップを成功させるのに十分なヒントを含めます。環境変数形式の名前には、サービス固有のプレフィックスを付けます（例：API_TOKEN ではなく GITHUB_API_TOKEN）。
• 認証情報に該当する入力は、読み取り専用のスコープかどうかや、認証がオプションかどうかにかかわらず、シークレットとして扱います。名前または説明に API_KEY、TOKEN、ACCESS_TOKEN、PASSWORD、SECRET、APPLICATION_KEY、READ_KEY、ADMIN_KEY、秘密鍵、ベアラー値、認証ヘッダー値が含まれる入力は kind: secret にする必要があります。エンドポイント／ベース URL／サイト／リージョン／ドメイン／組織／アカウント／ユーザー／メールアドレスの値は kind: variable にできます。
• 認証をオプションにするために、認証情報を空のデフォルト値を持つ変数にしてはいけません。現在の source-spec で対応できる範囲では、シークレットを必須にするか、オプション認証の設計が未対応であることを明記してください。匿名でのインストールを可能にするためだけにトークンを公開してはいけません。
• 認証ドキュメントには、必要なトークンの種類、スコープまたは権限、および認証情報の取得先を記載します。
• シークレットで credential.methods を宣言する場合、各メソッドはプロバイダーがサポートするセットアップ方法と一致する必要があります。OAuth メソッドでは、デバイスコード、認可コード、またはクライアントクレデンシャルのフローを使用します。認可コードメソッドには、明示的な pkce 値、ループバックリダイレクト URI、正しいリダイレクトポートモードが必要です。また、CLI がループバックコールバックを待機中にユーザーが最終的な localhost リダイレクト URL を貼り付けられる場合は、SSH、VM、ブラウザーを分離した環境にも対応する必要があります。デバイスコードメソッドには device_authorization_url が必要で、リダイレクト URI フィールドと静的なクライアントシークレットを指定してはいけません。クライアントクレデンシャルメソッドには token_url、client.id.input、client.secret.input、client.secret.transport が必要で、リダイレクト URI フィールド、認可エンドポイント、デバイス認可エンドポイント、PKCE、Dynamic Client Registration を指定してはいけません。すべての OAuth メソッドで、エンドポイント URL、適切なクライアント ID／デフォルト値／入力の動作、該当する場合の正しいクライアントシークレットの送信方法、および最小権限のスコープが適切である必要があります。認可コードまたはデバイスコードの Dynamic Client Registration では、Coral は常にネイティブクライアントを登録します。ソース仕様では web アプリケーションタイプを設定できません。また、request_refresh_token_grant: true は、プロバイダーがリフレッシュトークンのグラント登録に対応している場合にのみ指定してください。OAuth で保護された Streamable HTTP の MCP ソースでは、プロバイダーがリソースインジケーターを必要とする場合、oauth.resource を含めます。OAuth URL テンプレートで参照できるのは、シークレット以外の URL コンポーネントに使う、宣言済みの kind: variable 入力のみです。
• OAuth メソッドは実行時の認証に代わるものではありません。プロバイダーが求める場所に応じて、保存されたシークレットを auth、リクエストヘッダー、クエリパラメーター、または本文フィールドから引き続き参照します。
• OAuth のセットアップ手順には、ユーザー独自の OAuth クライアントが必要かどうか、該当する場合に登録するリダイレクト URI、付与するスコープ、リフレッシュトークンの発行に必要なプロバイダー／クライアント設定を記載します。プロバイダーが利用可能な expires_in メタデータを返す場合に限り、クライアントクレデンシャルメソッドでは、有効期間の短いアクセストークンを再発行する方法を利用できます。それ以外の場合、ユーザーはトークンの有効期限が切れた後に再接続する必要があります。プロバイダーがリフレッシュトークンを発行しないその他のメソッドでも、アクセストークンの有効期限が切れた際に再接続が必要であることを明記してください。
• OAuth とトークン貼り付けの両方のセットアップに対応する場合は、優先する方法が明確に伝わるよう、メソッドの順序とラベルを設定します。通常は OAuth を先に、source_config のフォールバックを次にします。
• 複雑なソースには、セットアップ手順、スキーマの概要、クエリ例を含む README またはマニフェストのガイドを用意します。
• 動作、セットアップ、ソースのセマンティクス、および例の変更は、同じ PR でドキュメントに反映します。

クエリの使いやすさ

• テーブルではユーザーにとって有用な概念をモデル化します。ユーザー、プロジェクト、チャンネル、サービス、チーム、リポジトリ、メタデータなどのディメンションテーブルは、簡単に使い始められます。
• カーディナリティが高いエンドポイントやコストのかかるエンドポイントでは、フィルターを必須にするか、保守的な fetch_limit_default 値を設定します。
• 必須フィルターは明示し、テーブルの description または guide に記載します。
• ガイドでは、使い始める方法、結合に使用する ID、プロバイダー固有のタイムスタンプやクエリ構文に関する注意点を説明します。
• クエリテキストを受け取り、順位付けされた候補を返すプロバイダーのエンドポイントには、search_limits、安定した結果識別子、有用な候補メタデータを備えた kind: search のテーブル関数を使用します。取得以外のテーブル関数では、スコープ付きの子コレクション、期間指定ログ、メトリクスクエリ、詳細操作などのパラメーター化された操作に対し、デフォルトの種類を維持します。通常のテーブルフィルターは、完全一致検索、スコープ指定、またはプロバイダー側のフィルタリングに使用します。mode: contains は部分文字列の一致に限られます。プロバイダー固有の検索をフィルターとしてモデル化している場合は、その旨を指摘し、kind: search 関数を必須としてください。
• テーブル、テーブル関数、カラムの名前は、スネークケースで安定しており、分かりやすいものにします。テーブル名とテーブル関数名は、ソース内の大文字と小文字を区別しないリレーション名前空間で一意でなければなりません。テーブル関数名は SQL 識別子の構文に従い、ASCII の英字またはアンダースコアで始め、その後には ASCII の英字、数字、アンダースコアのみを使用してください。テーブル名には、シンプルな snake_case を推奨します。互換性のために引用符で囲んだ SQL テーブル名を使用することは有効ですが、ソースを意図的に生成している場合を除き、プロバイダーの不自然な操作名をそのまま使わないでください。

HTTP と API のセマンティクス

• base_url と入力値に基づく URL によって、一般的なケースを不必要に煩雑にすることなく、ホスト型、クラウド、リージョン別、エンタープライズ向けのバリエーションに対応します。
• 認証ヘッダーとリクエストヘッダーは、必要に応じて API バージョンや Accept ヘッダーを含め、プロバイダーの仕様に合わせます。
• ページネーションモード、カーソルパス、ページサイズの上限、結果パスは、推測したパターンではなく、実際の API レスポンスを反映したものにします。
• プロバイダーの API の挙動に応じて、ok_path、error_path、allow_404_empty、レート制限のヒントを設定します。
• 必要な API 権限は、公開する読み取り専用の機能に必要な範囲を超えないようにします。

カラム設計

• カラムでは安定した識別子を保持し、利用可能な場合は人間が読みやすい名前を含めます。
• 不透明な ID や非常に大きな数値 ID には通常 Utf8 を使用します。数値として比較または集計する値には、数値型を使用してください。
• Coral が確実に解析または導出できる場合、重要な時刻には Timestamp カラムを公開します。有用な場合に限り、プロバイダーの生のタイムスタンプフィールドを残してください。
• nullable はプロバイダーの実際の仕様に合わせます。例にたまたま値が含まれていたという理由だけで、フィールドを非 null にしないでください。
• ネストされたオブジェクトは、幅広く有用なフィールドに限ってフラット化します。それ以外の場合は、脆弱で価値の低いカラムを作るのではなく、JSON またはテキストのカラムを公開してください。
• カラムの説明は簡潔で、ユーザーに分かりやすいものにします。

スタイルの一貫性

• YAML は読みやすくし、既存のマニフェストの順序に従います。順序は、識別情報、入力／認証／ベース URL、テストクエリ、関数／テーブルです。
• 既存のコアソースでは、短いテーブルの説明に guide ブロックを組み合わせて使用しています。この分け方を推奨します。
• README がある場合は、既存のソース README の構成に合わせ、認証、該当する場合はレート制限、テーブルのカテゴリまたはスキーマの概要、例を含めます。
• 初めて利用するユーザーにも分かりやすい表現にします。ユーザー向けのソース仕様の範囲に含まれる場合を除き、Coral の内部実装用語は避けてください。

出力形式

具体的な指摘から始めます。重要度ラベルは役立つ場合にのみ使用し、問題を要約の下に埋もれさせないでください。次の形式を推奨します。

Findings
- High: `sources/community/foo/manifest.yaml:42` marks `created_at` non-null, but the provider omits it for imported records...
- Medium: `sources/community/foo/README.md:18` shows setup but never states the required token scope...

Open questions
- Is endpoint X intentionally omitted from the first version?

Review notes
- I treated CI lint/schema checks as out of scope unless visible in the diff.

問題が見つからない場合は、その旨を明記し、実際の認証情報を利用できない、CI ログを確認していないなどの制約も記載してください。

ソースと API ドキュメントの食い違いを指摘する場合は、必ず該当する API ドキュメントのページへのリンクを含めてください。