codometer-triage

codometer の失敗への対処

--check の実行では、異なる種類の検出事項が3つ報告され、それぞれに異なる対応が必要です。「チェックに失敗した」と反応するのではなく、どの検出事項が発生したかを読み取ることが、このスキルの大部分を占めます。

超過

メトリクスが設定された上限を超えました。レポートには、メトリクス名、上限値、重大度が表示されます。

• warn は超過を表示しますが、終了コードは変更しません。実行は失敗していません。数値が注視すべき方向に動いていることを事前に知らせるものです。
• fail は終了コード 1 を返します。ただし、実行時にゲートとして --check limits を指定した場合に限ります。同じ超過を測定する codometer measure --config <path> は、ゲートを要求していないため、問題があるとは報告しません。

反射的に上限の value を引き上げるのは解決策になりません。 上限はコードベースの状態に関する約束を守るためにあります。その約束を破った変更と同時に上限を緩めると、チェックが記録するはずだった証拠が消え、次に超過したときには、すでに悪化したコードベースが出発点になります。実際に測定されているものを減らしてください。

• サイズの超過：報告値ではなく、入力自体が出力するものを減らします。依存関係を削る、バンドルを分割する、使われていないコードを削除するなどの方法があります。codometer-configure スキルでは、入力の宣言方法と、コンパイル済みの出力を正しく指定する方法を説明しています。サイズが、それを生成したコードより大きく見えるよくある原因は、入力が本来より多くのものを測定していることです。
• 規約カウントの超過（何かが多すぎる、または少なすぎる）：カウントは通常正確です。修正すべきなのはカウンターの value ではなく、カウンターが監視しているコードです。
• コメント予算の超過は、他のカスタム統計と同じく、通常の limits[] エントリーで custom.<label> メトリクスに対してゲートされます。ただし、測定対象がリポジトリ全体の件数ではなく1つのブロックであるため、instances には合計だけでなく、超過した各ブロックのファイル名と行番号が記録されます。そのブロックを簡潔にするか、内容を記述できる余地のあるドキュメントに詳細を移してください。カウントを信頼する前に、どのリーダーが測定したかを確認してください。シェル、TOML、SQL、HCL では行スキャナーが使われ、文字列リテラル内のコメント記号もコメントとして読み取ります。また、Python はインタープリターを実行できない場合、コメントが一切測定されません。どちらの注意点についても、codometer-configure スキルで詳しく説明しています。
• 対象言語のコメント予算が設定されていない場合、超過にはなりません。 単に測定されていないだけです。codometer がコメントを解析できる言語をリポジトリに追加しても、その言語に対する comment セレクターを誰も追加していなければ、予算が宣言されるまで、その言語のブロックには予算がありません。これは、ツールの偽陰性として診断すべきものでは決してありません。

このメトリクスが今後維持すべき値として、上限の数値自体が単に誤っていた場合は（今回の変更が原因なのではなく、恒常的な判断として）、意図的な編集として別途変更し、その理由を説明してください。1回のチェックを通すための副作用として変更してはいけません。

古さ

--check reports は、コミット済みのレポートと最新の測定結果を比較し、上限が関係するかどうかにかかわらず、両者が一致しない場合に失敗します。原因は2つあり、実際のリグレッションなのはそのうち1つだけです。

• コードが実際に変更されているのに、コミット済みのレポートが再測定されていません。--output-json／--output-markdown を指定して再実行し、レポートを更新してください。
• ランタイムが変更されています。 圧縮サイズは Node のバージョンに依存します。バンドルされた zlib はリリースごとに異なるため、ある Node バージョンで作成されたレポートを別のバージョンでチェックすると、コードに変更がなくても古いと判定されます。ソースに変更があったと結論づける前に、他のすべての用途でリポジトリが固定しているものと正確に同じランタイムでチェックしてください。

超過と古さは、同じ実行で発生した場合でも別々の検出事項として報告されます。一方を他方の兆候として読み取らないでください。

完全に失敗した実行

上記のどちらとも異なり、実行自体が完了できず、その結果は指標に含められるのではなく、レポート内の failures にまとめられます。

• どこにも紐付かない上限。 指標のパスが、実行で実際に測定された測定値を指定していません。スペルミスがある場合、入力で実行されていない分析を指定している場合、または2つの入力のどちらを指すのか実際に曖昧な場合があります。設定内のパスを修正してください。指標パスの解決方法と、曖昧なパスを推測せず拒否する理由については、codometer-configure スキルで説明しています。
• 上限を設定した入力に一致するファイルがありません。 入力に対する上限の宣言は、そのファイルが存在することを前提としています。そのため、一致するファイルがない場合は、globが一致しなくなったか、それらのファイルを生成するはずのビルドが実行されていません。設定を変更する前に、ビルドの手順を確認してください。上限を設定していない入力に一致するファイルがなくても、特に問題はなく、失敗として報告されません。
• 測定を始める前に設定自体が拒否された場合。 format がない場合、同じ種類の outputs エントリが2つある場合、カスタム統計量で patterns／symbols／comment のいずれも指定されていない場合、または outputs エントリが、トップレベルの custom 配列で宣言されていない custom ラベルを選択している場合は、それぞれ理由を示して読み込み時に実行が失敗します。プレーンなオブジェクトではなく関数をエクスポートする設定も、同じ問題の目立ちにくい形です。設定を関数として扱う方法はすでにないため、その設定は認識されず、空の設定にフォールバックします。その結果、実際の原因を示すのではなく、format がないために失敗します。コマンドラインではなく設定を修正してください。--config を一切指定せずに実行すると、測定を始める前に拒否されます。設定ファイルを指定する --config <path> を渡してください。

1回の実行で発生したすべての失敗はまとめて報告されるため、3件が報告された場合は、再試行すればよい不安定な実行と考えず、修正すべき問題が3つあると考えてください。

--output-json／--output-markdown を使う前に

2つの --output-* フラグと --check は独立しており、相互に推定される関係はありません。すべてのフラグの一覧は codometer-measure スキルに記載されています。--output-* フラグと --check reports を組み合わせると、その組み合わせは拒否されます。同じ実行で書き出したばかりのレポートが古い状態になることはないため、この組み合わせはレポートを最新にする方法ではなく、修正すべき設定ミスです。

--inputs [globs...] も --check とは独立しています。measure の実行対象を指定したglobだけに絞っても、実行がゲートとして機能するか、書き出しを行うかは変わりません。measure に --directory はありません。実行では常に、プロセス自身の作業ディレクトリが測定されます。-d, --directory が引き続き使えるのは configuration サブコマンドだけです。これはディレクトリの設定を測定するためではなく、その設定がどのように解決されるかを一覧表示するためのものです。