--- name: coverity-triage description: Coverity の警告1件(CID)を処置する。警告の経路を呼び出し元と定義までコードで確認して本物のバグか誤検知かを判定し、修正コードと逸脱コメント(修正しない場合に Coverity に登録する 200 文字以内の文)の2つを作成して、判定・確信度・根拠(ファイル:行)とともに結果フォルダーに保存する。「条件に合う警告を取得して」「CID 20002 を処置して」「次を処置して」「この警告が本物か調べて」「修正案を出して」「逸脱コメントを書いて」「まとめを見せて」のように、C / C++ の Coverity の警告の取得、調査、修正、逸脱コメントの作成や確認を依頼されたときに使う。 allowed-tools: ["shell(uv run:*)"] --- # CID 1件の処置 Coverity の警告1件について、**修正コード**と**逸脱コメント**(修正しない場合に Coverity に登録する文)の2つを作成し、判定・確信度・根拠を添えて結果フォルダーに保存します。 修正は、スクリプトが用意する作業用コピー(リポジトリの外)に書きます。利用者のリポジトリと Coverity が変わるのは、利用者が結果を確認して OK を出した後です。利用者には、日本語で伝えます。 ## 1. 開始して CID を受け取る ``` uv run --native-tls --quiet "<このスキルのフォルダー>/scripts/triage.py" start --repo "<リポジトリ>" ``` `<リポジトリ>` は、git または svn の作業ツリーの最上位フォルダーです。どのコマンドも JSON を1つ返します。応答は、どのコマンドでも次のように扱います。 - `fetch` があれば、そこに書かれたツールを `arguments` のとおりに呼び出します(警告の一覧、または警告の経路を取得します)。ツールの応答の `done` が `false` のときは、同じ引数でもう一度呼び出します。 - `next` には、続けて実行するコマンドの全文が入っています。利用者に確認せずに、そのまま実行します(CID を受け取った応答では、2〜5章の処置を終えてから)。空(`[]`)のときは、実行するコマンドはありません。応答の内容を示して、利用者の次の入力を待ちます。 - コマンドは、1回の呼び出しで1行だけ、書かれている全文を、パスも省略せずに実行します。シェルの変数、`;` や `&&`、パイプ、`cd`、リダイレクトを使ったコマンドは、実行が許可されず、結果が保存されません。 - `message` があれば、利用者に伝えます(例「条件に合う警告は 137 件あります。設定の上限(20 件)まで取得しました」「前回の続きから進めます(残り 7 件)」)。 - `ok` が `false` で `problems` があるときは、`problems` をすべて訂正してから、`next` のコマンドを実行します。`problems` がないとき、またはツールがエラーを返したときは、エラーの文(`log` があれば、その場所も)を利用者に伝えて終了します。続きは、同じ依頼をもう一度受けたときに行います。警告の経路を取得できないときは、終了せずに、2章のとおりに調査します。 `start` の応答の `next` が同じ `start` のコマンドの間は、警告の一覧の取得と作業用コピーの準備が続いているので、もう一度実行します。`next` が空になり、応答に `take`(CID を受け取るコマンド。`… next --run "" --slot 1`)があれば、準備は完了です。ここからは、依頼ごとに次のように進めます。 - 「条件に合う警告を取得して」:一覧(`/issues.json` の CID、チェッカー、ファイル:行、Impact)を示して終わります。 - 「次を処置して」:同じ会話でも新しい会話でも、`start` のコマンドを実行し、その応答の `take` のコマンドを実行します。 - 「CID 20002 を処置して」:`take` のコマンドの末尾に `--cid 20002` を付けて実行します(`… next --run "" --slot 1 --cid 20002`)。`take` が手元にないとき(新しい会話など)は、先に `start` のコマンドを実行します。保存済みの CID を利用者の指摘でやり直すときも、同じです(処置がすべて完了していて `take` がないときも、この形のコマンドを実行します)。 - 「まとめを見せて」:6章の手順で進めます。新しい会話では、先に `start` のコマンドを実行します(応答の `run_dir` が、結果フォルダーです)。 - 「取得し直して」:`start` に `--new` を付けます。 `start` の応答の `next` が `finish` のコマンドのときは、取得済みの警告の処置がすべて完了しています。`message` を伝え、6章の「まとめを見せて」と同じ手順に進みます。 | `next` の応答の項目 | 内容 | | --- | --- | | `issue` | CID、チェッカー、ファイル(作業用コピーでのパス)、行、関数、Impact | | `issue_file` | 警告の経路(`events`。`main` が `true` のイベントが、問題の起きる場所)とチェッカーの説明(`checker_description`)。`fetch` のツールを呼び出してから読みます | | `work_dir` | 作業用コピー(取り込み先の最新のコード)。コードを読むのも、修正を書くのもここです | | `result_file` | 結果を書くファイル | | `rework` | やり直す CID(保存済みの CID、差し戻された CID)のときだけ。利用者の指摘と `points` の指摘に対応します。`patch_applied` が `true` なら、前回の修正が `work_dir` に適用済みです。前回の結果は `result_file` にあります | | `members` | 同じ原因の CID があるときだけ。修正コードは、受け取った CID と `members` の CID の警告をすべて解消するものを1つ、逸脱コメントは、そのすべてに当てはまるものを1つ作成します。`members` の CID の警告の経路と前回の結果は、`/cid//` の `issue.json` と `result.json` にあります | | `next` | 保存のコマンド | `cid` が `null` のときは、処置する CID がありません。`message` を伝えます(`next` が `finish` のコマンドのときは、6章の「まとめを見せて」と同じ手順に進みます)。応答に `cid` がなく、`next` が `start` のコマンドのときは、警告の一覧の取得または作業用コピーの準備が必要です。そのコマンドを実行し、準備が完了したら、その応答の `take` のコマンドを実行します(CID を指定された依頼では、`--cid` を付けます。結果フォルダーが新しくなることがあるため、前のコマンドは繰り返しません)。 ## 2. 調査する 警告の経路は「このように実行されると問題が起きる」という仮説です。経路の各段階が実際のコードで成立するかを、呼び出し元と定義までたどって確認します。コードは、ファイルの読み取りと検索のツールで調査します。シェルで実行するのは、このスキルのコマンド(`uv run …`)だけです。ほかのコマンド(`cat`、`grep` など)は、許可の確認で処置が止まる原因になります。 - 根拠は、実際に読んだコードの場所(リポジトリの最上位からの相対パスと行)で示します。「おそらく」「通常は」で判定しません。確認できなかったことは `summary` に書き、確信度を下げます。 - コードと、資料や説明が食い違うときは、コードを優先し、食い違いを `summary` に書きます。 - `<リポジトリ>/.coverity-triage/knowledge.md` があれば、調査の前に読みます。人が確認して書いたプロジェクトの事実(戻らない関数、呼び出し元が保証する前提など)です。使用した知識は `summary` に「プロジェクトの知識:…」と書き、可能ならコードでも確認します。推奨の方針や逸脱コメントの書き方が書かれていれば、このスキルの基準より優先します。 - `issue_file` を取得できないときは、依頼に貼り付けられた警告を使います。それもないときは、警告の行とチェッカーの説明から考えられる経路で調査し、そのことを `summary` に書きます。 調査の手順: 1. **チェッカーの観点を読む**:チェッカー名に合う資料の、該当する項目(「同じ観点」と書かれた項目も)を読みます。`MISRA` で始まる名前は [references/misra.md](references/misra.md)、`CERT` と規則の番号(`EXP34-C` など)を含む名前は [references/cert.md](references/cert.md)、そのほかは [references/standard.md](references/standard.md) です。資料は手がかりで、判定の決め手はコードです。資料にないチェッカーは、`checker_description` を読んで同じ手順で調査し、資料にないことと、判定に使用した説明を `summary` に書きます。説明もないときは、推測で判定せず、`undetermined` にします。 2. **警告の経路を順に読む**:各イベントの行の前後(目安は 20 行ずつ)を `work_dir` で読み、イベントの説明がその行のコードと合うかを確認します。`issue_file` の中のパスは Coverity のものなので、末尾が一致するファイルを `work_dir` で探します。 3. **経路が成立する条件を挙げる**:分岐の条件、引数の値、戻り値、ループの回数、マクロの値。 4. **条件を1つずつ確認する**:値の出所を、関数名・マクロ名・変数名で検索して、呼び出し元と定義までたどります。 - Coverity が認識していないことが多いもの:戻らない関数、別の関数で実施済みの検証、出力引数による初期化、ビルド設定で無効になるコード、所有権の移動、ループ回数の上限。 - 呼び出し元は、すべて確認します。条件を満たす呼び出し元が1つでもあれば、経路は成立します。どの呼び出し元も条件を満たさない(例:すべて NULL を除外してから渡す)なら、経路は成立しません。「宣言がその値を禁止していない」「将来、呼び出し元が増える可能性がある」は、本物のバグの理由にしません。 - 呼び出し元がリポジトリにない(公開 API、コールバック、割り込み)ときは、そのことを書き、推定として扱います。 - `assert`(`NDEBUG`)や `#if` / `#ifdef` のように、製品のビルド設定で結論が変わるときは、その設定をビルド設定のファイルやプロジェクトの知識で確認して判定します。設定が分からなければ、`undetermined` にします。 5. **最新のコードとの差を確認する**:`work_dir` は、Coverity が解析したコードより新しいことがあります。行がずれていたら、関数名とコードの形で同じ文を探します。同じ文が見つかり、各イベントの説明が成立するなら、行のずれを `summary` に書き、確信度は下げません。イベントの文が見つからないときや、内容が変わっているときは、その内容を `summary` に書き、確信度を `low` にします。 | 判定 | 基準 | | --- | --- | | `true_bug`(本物のバグ) | 経路が成立し、現在の呼び出し元のいずれかで実際に問題が起きる。製品でビルドされないコードの中の不具合も、これにする | | `false_positive`(誤検知) | 経路が成立しない(Coverity が認識していない条件がある、どの呼び出し元も条件を満たさない) | | `intentional`(意図的) | 経路は成立するが、設計どおりの動作で問題にならない(意図したフォールスルー、無効にしたコードそのものへの警告(DEADCODE、UNREACHABLE)など) | | `undetermined`(判定不能) | 実行時の値や外部の仕様で決まるため、コードからは判定できない | | 確信度 | 基準 | | --- | --- | | `high`(高) | 警告の経路をコードで最後まで追跡でき、根拠がすべてコードにある | | `medium`(中) | 根拠の一部が推定である(呼び出し元がリポジトリにない、マクロの展開を推定した、など) | | `low`(低) | コードから判定できない前提に依存する。または、イベントの文が `work_dir` のコードにない | 推奨(`recommendation`)は、次のように決めます。判定や推奨に迷うときは [references/criteria.md](references/criteria.md) を読みます。 - `true_bug` は修正(`fix`)。逸脱(`deviation`)にするのは、最新のコードで修正済みのときと、実行されないことや影響がないことをコードで示せるとき(製品でビルドされないコードなど)だけです。 - `false_positive` と `intentional` は、逸脱コメント(4章)を**条件を付けずに書ける**ときだけ逸脱。書けなければ修正。修正が小さく安全で、コードの意図も明確になるなら、修正でもかまいません。 - `undetermined` は、修正のリスクが小さければ修正、大きければ逸脱。確信度は `low`。 ## 3. 修正を書く `work_dir` のファイルを、通常の編集で修正します。差分は `save` が作成します。`work_dir` に残したファイルは、すべて修正コードになります。バックアップや一時ファイルは、`work_dir` に置きません。書いた後、修正したファイルを読み直し、経路が成立しなくなったこと、変更が必要な行だけであること、インデントが周囲と同じであることを確認します。 1. **最小の変更**:問題の起きる場所に至る経路が成立しなくなるのに必要な行だけを変更します。リファクタリング、整形、名前の変更は行いません。原因が1か所(サイズのマクロの定義など)にあるときは、そこを修正し、そのマクロを使うすべての場所で動作と規則への適合が保たれるかを確認します。 2. **外部仕様を保つ**:関数の引数と戻り値の型、公開ヘッダー、グローバル変数の型は変更しません。 3. **新しい MISRA・CERT の違反を作らない**:追加する行は、[references/misra.md](references/misra.md) の Rule 10.4(定数の型を相手に合わせる。`U` を付けると動作が変わる式がある)、14.4(条件は Boolean の式)、15.5〜15.7(関数の出口、`{ }`、`else`)、17.7(使用しない戻り値)に合わせます。途中で返る分岐を追加するときは、それまでに確保した資源(メモリ、開いたファイル)を解放してから返します。 4. **周囲のコードに合わせる**:インデント(タブか空白か、幅)、命名、括弧の位置、エラー処理(`goto cleanup` の後処理、エラーコードのマクロ、ログ)、コメントの書き方と言語。 5. **文字コードと改行コードを保つ**:ファイルの文字コード(UTF-8、Shift_JIS など)、BOM、改行コード(CRLF / LF)は変更しません(変わっている修正は保存されません)。日本語のコメントは、そのファイルの文字コードで表せるときだけ書きます。 この制約の中で修正できないとき(例:エラーを伝えるために、戻り値の型を変更する必要がある)は、制約を超える修正を作成し、`fix.summary` に、超えた制約とその理由、影響を受ける呼び出し元すべて(関数名で検索し、ファイル:行で列挙する)を書きます。次の2つは、修正コードの扱いが異なります。 - **最新のコードで修正済み**:`work_dir` で、経路がすでに成立しなくなっていれば(形が違っても同じです)、何も変更しません。同じ後処理を追加すると、二重クローズや二重解放になります。判定は `true_bug` のまま、`no_fix_reason` に修正済みの場所(ファイル:行)を書き、推奨は `deviation` にして、逸脱コメントにその場所を書きます。確信度は、修正済みであることをコードでどこまで確認できたかで決めます。`true_bug` で修正コードのない結果は、Coverity に「修正済み」(Action: Fix Submitted)として登録されます。 - **誤検知・意図的**:外部から見える動作を変えずに警告を解消できる修正(現在の呼び出し元では通らない防御的なチェック、初期化の明示、`(void)` による明示など)があれば作成し、動作が変わらないことを `fix.summary` に書きます。そのような修正がないときだけ、何も変更せず、`no_fix_reason` に理由を書きます。 ## 4. 逸脱コメントを書く 逸脱コメントは、この警告が**どの状況でも問題にならない**ことを述べる短い文です。Coverity に登録され、後で読む人が「修正しなくてよい理由」として使います。修正を推奨する CID にも書きます。 - 日本語で、改行・箇条書き・書式(`` ` `` や `**`)のない1行。**200 文字以内**。 - **判定**(「誤検知。」「意図的。」「本物のバグ。」のいずれか)で始め、続く1〜2文で、**問題にならない理由**(条件を付けずに断定する)と**根拠の場所**(関数名とファイル:行。例 `open_session()(src/net/session.c:120)`、範囲は `src/reader.c:55〜60`)を書きます。場所は、実際に読んで確認した、修正前のコードの行です。 - `false_positive` は「誤検知。」、`intentional` は「意図的。」、`true_bug` は「本物のバグ。」で始めます。`undetermined` は、コードで確認できた事実に合うものを選びます。 - 書くのは、問題にならない理由だけです。条件・前提・ただし書き(「ただし」「〜の場合に限る」「〜の場合は」)、推測(「おそらく」「〜と思われる」)、調査の過程、推奨や読む人への依頼・指示(「修正を推奨」「確認してください」「〜すべき」「〜すること。」)は、必要なら `summary` に書きます。コードの動作は「場合は」を使わずに書きます(「失敗すると -1 を返す」)。規則に合わない表現は、`save` が指摘します。 | | 例 | | --- | --- | | 適切 | 誤検知。find_slot() の戻り値は NULL になりうるが、呼び出し元 open_session()(src/net/session.c:120)で NULL を除外してから渡しているため、NULL を参照することはない。 | | 不適切(限定) | 誤検知。count が 0 の場合に限り items は読まれないので問題ない。 | | その修正例 | 誤検知。count は唯一の呼び出し元 flush_queue()(src/queue.c:41)で 1 以上に決まっており、items が空のまま読まれることはない。 | | 不適切(前提と指示) | 誤検知。send_all()(src/net.c:18)が len が 0 の呼び出しを除外するため範囲外を読まない。この判断の前提は呼び出し元が1つであることで、呼び出し元を変更したら見直すこと。 | | その修正例 | 誤検知。唯一の呼び出し元 send_all()(src/net.c:18)が len が 0 の呼び出しを除外してから渡しており、buf の範囲外を読むことはない。 | 条件を付けないと「問題にならない」と書けないときは、問題になりうるので、**推奨を修正に**し、逸脱コメントには、断定できる事実だけを書きます。本物のバグの例(文は、その警告の事実に合わせて書きます): - 修正しない理由がないとき:「本物のバグ。src/reader.c:42 で fgets の戻り値を確認せずに使用しており、空のファイルで NULL を参照する。」 - 実行されないことをコードで示せるとき:「本物のバグ。v1 形式の読み込みは現在の製品では無効(include/features.h:31)で、この処理は実行されない。」 - 最新のコードで修正済みのとき:「本物のバグ。最新のコードでは load_table()(src/loader.c:33〜35)で fp を閉じてから返しており、リークは解消されている。」 ## 5. 結果を書いて保存する `result_file` に、UTF-8 の JSON で書きます。 ```json { "cid": 20002, "verdict": "false_positive", "summary": "呼び出し元 2 か所とも NULL を除外してから渡している。呼び出し元はすべてリポジトリにあり、コードで確認した。", "evidence": [ {"file": "src/net/session.c", "line": 120, "note": "open_session() が find_slot() の戻り値の NULL を除外している"}, {"file": "src/net/admin.c", "line": 64, "note": "open_admin() も同様に NULL を除外している"} ], "recommendation": "deviation", "confidence": "high", "fix": {"summary": "use_slot() の先頭に NULL チェックを追加する。現在の呼び出し元では通らない分岐で、動作は変わらない。"}, "deviation": {"comment": "誤検知。find_slot() の戻り値は NULL になりうるが、呼び出し元 open_session()(src/net/session.c:120)と open_admin()(src/net/admin.c:64)で NULL を除外してから渡しているため、NULL を参照することはない。"} } ``` - `summary`:最初の文を、判定の決め手(40 文字程度)にします。続けて、確信度がその値である理由を、どの基準に該当するかが分かるように書きます(「十分に確認した」では分かりません)。Coverity のパスを `work_dir` のファイルに読み替えたときは、そのことも書きます。 - `evidence`:経路をどのコードで確認したかを、経路の順に並べます。`file` はリポジトリの最上位からの相対パス、`line` は**修正前**のコードでの行です(修正を書く前に控えておきます)。 - `fix` と `no_fix_reason` は、どちらか一方です。`work_dir` を変更したときは `fix.summary`(修正の内容と、どの条件で何が変わるか)、変更していないときは `no_fix_reason` を書きます。`recommendation` が `fix` のときは、修正が必要です。 - `deviation` には、逸脱コメントだけを書きます。Coverity に登録する Classification・Action・Severity は、`save` が逸脱コメントの判定と警告の Impact から決めて、書き加えます。 書いたら、`next` の保存のコマンド(`… save --run "" --cid 20002 --slot 1`)を、その1行だけ、そのまま実行します。`ok` が `false` のときは、`problems` をすべて訂正して、同じコマンドをもう一度実行します。3回訂正しても保存できないときは、訂正をやめて、`problems` を報告します。保存できると、修正は `patch_file` に保存され、`work_dir` は、次の CID のために修正前の状態に戻ります。 ## 6. 2つの出力を示す 保存の応答の `ok` が `true` になったら(`next` は空です)、修正コードと逸脱コメントの**両方**を、次の順で示して、終わります:CID(チェッカー、場所)、判定(確信度とその理由)、推奨、根拠(ファイル:行と内容を、経路の順にすべて)、修正コード(`fix.summary` と、保存の応答の `patch` の差分を、行を省略せずにコードブロックで。`patch` が `null` のときは、修正しない理由)、逸脱コメント(文字数を添える)、最後の行に「続けるときは「次を処置して」、修正の取り込みと逸脱コメントの登録に進むときは「まとめを見せて」と入力してください」。 「まとめを見せて」と依頼されたときは、`… finish --run ""` を実行し、応答の `next` のコマンドを、`next` が空になるまで続けて実行します(`finish` の次は、一覧を作成する `plan` のコマンドです)。`plan` の応答は、次の順で示します。`table` を、行も列も文字も変えずにそのまま表示します。`summary_file` が `null` でなければ「CID ごとの修正コードと根拠は にあります」と伝えます。最後に、`question` をそのまま書いて、回答を待ちます(`question` がないときは、`message` を伝えて終わります)。`table` と `question` は、利用者が OK を出す対象そのものです。言い換え、箇条書きへの整形、補足の追加をせずに、文字を変えずに書きます。回答は、次のように扱います。 - 「OK」:`after_ok` のコマンドを実行します。 - 選択を変更する回答(「20003 は逸脱、20007 は保留、ほかは OK」):`to_change` のコマンドの `--set =` を、変更する CID ごとの `--set`(修正は `fix`、逸脱は `deviation`、保留は `none`。この例では `--set 20003=deviation --set 20007=none`)に書き換えて実行します。回答に OK も含まれていたときだけ、その新しい応答の `after_ok` のコマンドを実行します。OK がないときは、新しい `table` と `question` を示して、回答を待ちます。 - `after_ok` のコマンドの応答:`call` のツールを呼び出して、結果を報告します(報告する内容は、スキル `coverity-apply` の3章にあります)。呼び出しが許可されなかったとき、またはエラーになったときは、報告の最後に、`if_not_called` の文を、文字を変えずに書きます(利用者が次に入力する文が入っています)。 `finish` の応答の `ok` が `false` で、`pending` または `unreviewed` があるとき(エージェントが開始した処置が残っているとき)は、`error` を伝え、その `next` は実行せずに、スキル `coverity-apply` の1章の手順で一覧を示します(その CID は、一覧に「未処置」、または「保留にする」(未検証のため)と表示されます)。