coverage-analysis

カバレッジ分析

目的

.NET のカバレッジ証拠が何を示すのかを説明し、目標値の計算を照合して、進捗を妨げているコードを特定します。ユーザーからリスクの高い箇所、CRAP、リスクに基づく優先順位、またはリファクタリングの安全性について明示的に求められた場合に限り、複雑度／CRAP のランキングを追加します。

使用する場面

提示された .NET の行／分岐／条件の証拠、カバレッジの未達箇所や停滞、目標値の計算、またはプロジェクト全体のカバレッジに基づくリスク分析が明示的に求められた場合に、このスキルを使用します。

使用しない場面

• 名前が指定されたメソッド、クラス、ファイルの CRAP／リファクタリング安全性分析 — 代わりに crap-score スキルを使用します
• テストとの静的なソース対応付け、またはテストのないファイルの一覧作成 — find-untested-sources を使用します
• 既存テストにおける振る舞いのギャップや擬似ミューテーションのギャップ — test-gap-analysis を使用します
• テスト種別ごとのテスト特性／カテゴリ分布、またはカバレッジの形状 — test-tagging を使用します
• テストの作成や生成 — このスキルはテストが必要な箇所を特定するものであり、テストを作成するものではありません
• カバレッジや CRAP 分析と関係のない一般的なテスト実行
• .NET のカバレッジ収集のみ、または原因分析なしの生のパーセンテージ表示のみ — run-tests を使用します。.NET 以外のカバレッジ収集や分析にはネイティブツールを使用します。.NET の行／分岐の未達箇所の解釈は引き続き対象です

入力

入力	必須	デフォルト	説明
プロジェクト／ソリューションのパス	いいえ	現在のディレクトリ	.NET ソリューションまたはプロジェクトへのパス
行カバレッジのしきい値	いいえ	80%	許容可能な最低行カバレッジ
分岐カバレッジのしきい値	いいえ	70%	許容可能な最低分岐カバレッジ
既存の Cobertura パス	いいえ	指定がない場合のみ検出	優先する入力です。利用可能なレポートがある場合、テストを再実行しません
CRAP のしきい値	いいえ	30	明示的なリスク／CRAP の依頼に限り使用します
ホットスポット数	いいえ	3	明示的なリスクの依頼に限り使用します。ユーザーがより多く求めない限り、上限は 10 です

ワークスペースから任意の入力を検出します。現在のディレクトリまたは提示されたレポートで十分な場合、プロジェクトのパスを尋ねないでください。

該当する最小限の手順を選ぶ

ユーザーの意図	必要な作業	行わないこと
提示された抜粋、条件、または概要を説明する	提示された証拠に基づいて直接回答します	ツール、CRAP、調査、レポートファイル
提示された Cobertura パスを解釈する、または停滞を診断する	そのレポートを読み、合計を照合し、重要な未達箇所をすべて挙げて、直接回答します	明示的に求められない限り、テストの再実行、ツールのインストール、CRAP の計算、ファイルの生成
リスクの高い箇所をランキングする、プロジェクト全体の CRAP を計算する、またはリファクタリングの安全性を評価する	提示／既存のレポートを使用し、references/guidelines.md を読み、ランキングの前に CRAP を計算します	カバレッジのみでのランキング、または依頼されていない完全なレポートテンプレート
レポートがない状態でカバレッジを分析する	run-tests を呼び出してリポジトリに適合するランナーでカバレッジを収集し、生成されたレポートを分析します	テストコマンドを独自に選択または実行すること、リスクの依頼がない場合の CRAP
完全な Markdown／HTML／CSV レポートを作成する	まず直接回答し、その後 references/output-format.md または references/report-generation.md を読みます	回答より先にレポートを生成すること

カバレッジを分析して、カバレッジを妨げているものは何か、カバレッジが停滞している理由は何かといった表現だけでは、CRAP の依頼とはみなしません。明示的な合図には、リスクの高い箇所、CRAP、複雑度を加味した優先順位、安全にリファクタリングできるか、または複雑度とカバレッジの組み合わせを求める同等の依頼が含まれます。

既存データの優先パス

ユーザーがカバレッジの抜粋、概要、または有効な Cobertura パスを提供した場合：

• それを信頼できる入力として扱い、そこから開始します。
• ソースマッピングが必要な場合を除き、ソリューションやテストプロジェクトを特定しないでください。
• dotnet test を実行したり、ReportGenerator をインストールしたり、カバレッジパッケージを追加したり、references/setup-discovery.md または references/report-generation.md を読んだりしないでください。
• ユーザーが保存可能な完全なレポートを要求していない限り、coverage-analysis.md を作成したり、レポート用ディレクトリを作成したりしないでください。
• 解釈や停滞に関する質問では、回答に必要な証拠だけを解析してください。プロジェクト全体のリスクを明示的に求められた場合は、references/guidelines.md に記載されたバンドル済みスクリプトを使用してください。

読み取り／表示操作の失敗は、指定されたパスが存在しない証拠にはなりません。失敗の種類を分類してから、対象を絞った存在確認を一度だけ行ってください。正規パスが引き続きワークスペース内にあることを確認したうえで、ツールの利用可否、転送、またはパスの正規化に関する失敗が確認された場合に限り、正規化したパスまたは別の読み取り方法を使用してください。コンテンツの除外、アクセス許可／ポリシー、ワークスペース境界、または不明な失敗の場合は停止してください。独立した確認でも失敗した場合に限り、パスがないと報告してください。検索範囲を広げたり、別の成果物で代用したりしないでください。

収集パス

利用可能なカバレッジの証拠がなく、それを必要とする分析をユーザーが求めている場合に限り、このパスを使用してください。

1. references/setup-discovery.md を読みます。
2. 要求されたルートの下から見つかった既存の Cobertura を優先します。
3. 見つからない場合は、リポジトリのオーバーレイ、プラットフォーム、ランナー、コマンドの選択に run-tests を使用し、エントリーポイントごとに一度だけ Cobertura を収集してもらいます。
4. 生成された Cobertura を分析します。CRAP の計算は、リスク分析が明示的に要求された場合に限ります。

ワークスペース内に、このパスで必要なプロジェクト／テストのマニフェストがある場合は、直接調査を行い、収集を run-tests に委任してください。現在のワークスペースで確認や生成が可能なファイルを、ユーザーに添付したり、事前にカバレッジを実行したりするよう求めないでください。

製品コードは変更しないでください。収集のために必要となる付随的なテストプロジェクトの変更は run-tests が担当します。最終分析には、その変更と元に戻すコマンドを記載してください。

自動収集パスの対象は SDK スタイルのプロジェクトです。従来型の非 SDK プロジェクト、または packages.config を使用するプロジェクトでは、リポジトリが管理するカバレッジコマンドだけを使用してください。そのようなコマンドがない場合は停止し、Cobertura XML を要求してください。プロジェクトの移行、SDK スタイルのプロバイダーの注入、ラッパープロジェクトの作成、別のアセンブリからの代替カバレッジの報告は、決して行わないでください。

解釈と算術上の不変条件

• 行のヒットで証明できるのは実行されたことだけであり、両方の判定結果が実行されたことではありません。
• condition-coverage="50% (1/2)" が証明するのは、報告対象の結果の一方が実行されたことだけで、どちらが実行されたかは分かりません。反対の結果を強制するテストを推奨してください。ソースがない場合、ありそうな述語を決めつけたり、true と false のどちらが未実行かを断言したりしてはいけません。複合述語については、該当する場合、各オペランドと短絡評価の組み合わせを個別に実行する必要があると述べてください。ソースまたはより詳細な XML がない限り、具体的な組み合わせを推測してはいけません。
• 全体の合計は、Cobertura のカバー済み行数と有効行数から算出してください。目標 T に対して、必要なカバー済み行数は ceiling(valid lines × T) です。
• 予測カバレッジは (current covered lines + newly covered distinct lines) / valid lines です。メソッドを完全にカバーするなど、前提を明記してください。
• あるメンバーが目標に到達できるか尋ねられた場合、予測される最大合計と、提示されたメンバーまたは行の増加分のうち目標達成に十分な具体的な組み合わせを少なくとも 1 つ示してください。提示された組み合わせではどれも十分でない場合は、その旨を述べてください。
• 複数メンバーで目標を達成する場合、正確な組み合わせと、達成後のカバー済み行数／有効行数を示してください。「別のメンバーと組み合わせる」だけでは不十分です。
• メンバーごとの未達分をプロジェクト全体の合計と照合してください。メソッドの行範囲は重複したり、クラスレベルの行を含まなかったりするため、メソッドのカウントをプロジェクト全体の確定値として合算してはいけません。
• あるメンバーの未カバー行がプロジェクト全体の合計と正確に一致し、かつ目標未達のメンバーがほかに存在しない場合を除き、そのメンバーを唯一の、すべての、または残りすべての未達分と呼んではいけません。
• 提示または抽出された目標未達のメンバーをすべて挙げてください。ただし、詳細さは状況に応じて調整し、まず阻害要因を示したうえで、残りは 1 文または簡潔な表にまとめてください。

回答の要件

ユーザーの質問には、最初の 2～4 文で回答してください。

• 抜粋または算術に関する質問： 説明を 1 つと、次に優先すべきテストまたはメンバーを示してください。ダッシュボードは不要です。
• 既存レポートの解釈または停滞に関する質問： 全体の行カバレッジ／分岐カバレッジ、阻害要因となるメンバー、目標達成への影響を照合した結果、および推奨事項を 1～3 件示してください。簡潔な表は最大 1 つにしてください。
• リスク／CRAP の明示的な依頼： デフォルトでは実際のホットスポット上位 3 件を、複雑度／カバレッジ／CRAP の値、残りのフラグ付き件数、および優先事項 1～3 件とともに示してください。ホットスポット表から、完全にカバーされていてリスクの低いメソッドは除外してください。ユーザーがより多い件数を求めない限り、10 行を超えてはいけません。リファクタリングの安全性を評価する場合は、カバレッジ率だけでなく CRAP に基づいてリスクの高いメソッドを順位付けし、比較的安全でカバレッジの高いメソッドは別途挙げてください。
• 全レポートの明示的な依頼： references/output-format.md を読み、レポートを保存してください。その場合にのみ保存します。

実在する成果物だけを報告してください。ファイルの依頼がない場合、アクセスできない出力パスや、任意のファイル書き込みが失敗したことを告知してはいけません。

任意レポート

HTML／CSV／Markdown ファイルは通常の分析には含まれません。ユーザーがレポートファイルまたは CI 成果物を明示的に依頼した場合にのみ生成してください。

1. まず、カバレッジ／リスクに関する直接的な回答を提示してください。
2. Markdown の全レポートを作成する場合は、references/output-format.md を読み、保存してください。
3. HTML／CSV を作成する場合は、その後に references/report-generation.md を読んでください。直接的な回答を提示する前に ReportGenerator をインストールしてはいけません。また、失敗したインストールを再試行してはいけません。

検証

• 提供されたレポートを、テストの実行やツールのインストールなしで使用したことを確認してください。
• 影響を予測する前に、カバー済み行数、有効行数、未カバー行数の合計を照合してください。
• 示した阻害要因のすべてが、提供または抽出された根拠に基づくことを確認してください。
• CRAP の依頼があった場合は、references/guidelines.md を参照してスコアを 1 つ抜き取り確認してください。
• ファイルの依頼があった場合は、パスを報告する前にファイルの存在を確認してください。

よくある落とし穴

• 既存のレポートがある場合にセットアップ作業を始める — いったん止めて、まず指定された成果物を分析します。
• 一般的な分析で CRAP を実行する — いったん止めます。CRAP の実行には、リスクを明示的に意図している必要があります。
• 1 つのメソッドをギャップ全体と見なす — まず、カバーされていない個別の行と、しきい値未満の項目全体を照合します。
• 小さな依頼にダッシュボードを作る — 直接回答するか、表を 1 つ作る程度に規模を抑えます。
• 収集で Cobertura が生成されない — 収集の失敗を報告します。代わりのカバレッジを捏造してはいけません。
• コンパイラーが生成したメソッド名 — 非同期処理、ラムダ、またはローカル関数の名前に不審な点がある場合は、ユーザーが記述したメンバーとして提示する前に、ソースコードと照合します。
• テストの終了コードが 1 — カバレッジが存在する場合があるため、警告を添えて続行します。それ以外のビルド失敗でゼロ以外の終了コードが返された場合は、収集処理を中止します。