continuous-integration.md

継続的インテグレーション

1.0 前の面です。 文書化もテストもされていますが、約束に値するだけの実利用を経ていないため、リリース間で変わり得ます。

codehelion が自動チェックに提供するものは 3 つで、いずれもローカル実行の終了コードです。サービスもアカウントもネットワーク通信も要りません。

増えた重複に対するゲート

codehelion scan --mode structural \
  --baseline codehelion-baseline.json \
  --fail-on-findings

baseline が持っていない findings が残ったときに終了コード 3 を返します。baseline は現状のツリーを 1 度スキャンして作るので、このチェックが答える問いは 1 つです。この変更は、元々無かった重複を増やしたか。

これは意図して比率ではありません。「重複率を N% 未満に保つ」形のゲートは、N を上げれば答えたことになりますし、コードベースが育つだけで勝手に動きます — 同じ割合で重複しながらサイズが倍になったツリーは、パーセンテージが下がったと報告します。baseline は群を数えるのではなく名指すので、落ちるのは追加であり、それを解消するのは重複を消すか、残すという判断を記録するかのどちらかです。

ファイルの作成と更新はベースラインに、例外を通すのではなく群を残す判断の記録は抑制にあります。

seam に対するゲート

seam とは、一緒に変更されるものとしてプロジェクトが書き留めたファイルの集合です。1 つのルールを実装しなければならない 2 つの frontend、2 言語で保たれる文書の対、といったものです。

codehelion guard --since "$MERGE_BASE" --deny-asymmetric

変更が seam のメンバーの一部に触れて他に触れていないとき、終了コード 3 を返します。--deny-asymmetric を付けなければ報告して 0 を返すので、始めるならこの形からです。台帳が無い、または空の場合は何も報告せず 0 を返すため、seam を 1 つも書き留める前にこのステップを足しても無害です。

これが捕まえるのは、コンパイラやテストから見えるかぎりでは完成していて、台帳だけが記録している意味で未完成な変更です。同時に、正しい変更に対して最も発火しやすいチェックでもあります — 意図的に触れなかったメンバーがあれば、それは非対称な変更です。呼び出しごとの例外はありません。報告が過剰な seam は members をより細かく切ります。台帳の内容と、それが区別できないことはseam 追跡にあります。

code scanning のビューに載せる

codehelion scan --mode structural --format sarif --output codehelion.sarif

出力は SARIF 2.1.0 のログです。GitHub の場合:

- run: codehelion scan --mode structural --format sarif --output codehelion.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: codehelion.sarif

クローングループ 1 つが result 1 つになり、canonical instance が primary location、各出現が related location です。グループの安定 ID は partialFingerprints に載るので、行が動くたびに閉じて開き直すのではなく、消費側がスキャンをまたいで同じグループだと認識できます。抑制されたグループは落とさず、SARIF の suppression を付けて出力します。

クローンのルールはすべて note レベルで報告します。重複は固有の深刻度を持つ欠陥クラスではなく、スキャン自身の順位付けは消費側の severity 軸とは別の量だからです。したがって、アップロードはゲートではなくビューです。ビルドを落とすのは上の 2 つのチェックの終了コードのほうです。seam のサマリはログに入りません — SARIF は findings のための形であり、seam のサマリは findings ではありません。

実行が残すもの

スキャンは .codehelion/ 配下のローカル SQLite データベースに記録します。runner の上ではそのデータベースは runner と一緒に消えますが、失われるのはサマリが出す実行間の比較だけです。baseline はスキャンが読まれた条件に紐づくので、開発者と違う読み方をするジョブ — モードが違う、.h の文法判断が違う — は、その開発者が作った baseline と一致しません。

マシンの外へ出るものはありません。ネットワークアクセスの禁止は設定ではなく依存ポリシーと lint で強制されており、ローカル実行と信頼に書いてあります。

終了コード

0 完了、1 続行できない運用上のエラー、2 コマンドラインの誤り、3 ゲートの発火。全体はコマンドラインにあります。