suppression.md

抑制

重複レポートは、そこに載っているものが読む価値を持って初めて役に立ちます。抑制は、プロジェクトが保守していないコード・手で書いていないコード・統合しようのないコードが、他を押しのけないようにするための仕組みです。

分類はポリシーが何をしようと必ず記録されます。そのため --show-suppressed は隠したグループを、それぞれの理由とともに一覧でき、JSON と SARIF にはフラグに関係なく抑制された finding が含まれます。記録済みの実行を再生すると、現在のポリシーではなく、その実行が適用した抑制がそのまま表示されます。

1.0 前の面です。 既定値は Structural モードが報告する内容の一部であり、それと一緒に測っています。それを変更する設定キーのほうは、文書化もテストもされていますが、約束に値するだけの実利用を経ていないため、リリース間で変わり得ます。

3 つの扱い

ほとんどのポリシーは次の 3 値のいずれかを取ります。

• hide — 一覧に出しません。
• rank-down — 挙動の重複より後ろに置きます。
• report — 計測どおりの priority のままにします。

分類が確実な事実ではなく強い示唆である場合は、既定を rank-down にしています。スクロールする読み手にはまだ見えていて、そうしない読み手の邪魔にはならないためです。

パスで

[suppression]
# paths = []                        # 隠すパス glob
# vendored-paths = [...]            # 自分では書かない vendored ツリー

vendored-paths には慣用的な集合（third_party・vendor・external・deps・subprojects・node_modules・.venv とその類）が入っており、既定で隠します。依存先の中の重複を消すのはこのプロジェクトの仕事ではないからです。このキーを設定すると既定値を置き換え、[] にすれば他のツリーと同じように読みます。--include-vendored は 1 回の実行だけこれを解除します。

vendored ツリーとプロジェクト自身のコードにまたがる重複は、どちらの設定でも見えたままです。これはここに挙げるすべてのルールに共通します。グループが隠れるのは、そのすべての出現箇所が隠す対象に当たるときだけです。

所属ユニット名で

# symbols = []                      # 所属ユニット名に対する glob

出現箇所が属するユニットの名前に対して照合します。ファイル全体を隠さずに、生成されたアクセサ 1 系統だけを静かにしたいときの手段です。C / C++ ではデストラクタは ~Name、演算子は記号の前に空白を置かない正規の綴り（operator== など）で命名されます。変換演算子は operator bool のように単語の間の空白だけを残します。これは Fast と Structural のどちらでも同じです。

生成コード

# generated-markers = ["@generated", "do not edit", "automatically generated", "auto-generated", "autogenerated"]

先頭数行にこれらのバナーを持つファイルは機械の出力であり、その重複は生成器のものであって保守の問題ではありません。大文字小文字は無視します。設定すると既定値を置き換えるので、自分の生成器のバナーを足すときはこれらも一緒に並べます。

こうしたファイルはファイルの探索時に除外されます。重複を探す前に外れるため、サマリで件数が数えられるだけです。--show-suppressed には一覧されず、「グループはすべての出現箇所が該当するときだけ隠す」という規則の対象にもなりません。

テストコード

# test-paths = ["**/tests/**", "**/test/**", "**/__tests__/**", "**/*_test.*", "**/*_tests.*", "**/test_*.*", "**/*_spec.*"]
# test-code = "rank-down"

テストコードは設計として繰り返します。引数ひとつだけが違う 20 ケースは、統合すべき重複ではなくスイートです。パスによる証拠は、ソース側の証拠（Rust のテスト属性、C / C++ のフレームワークのケースマクロ）と組み合わせて判断します。crate がテスト専用と宣言した Rust モジュールは、分割された複数ファイルを含め、どこに書かれていてもテストコードとして数えます。

スイートとそれが動かす対象の両方にまたがるグループはテストコードではなく、そう分類もしません。

boilerplate の形

[suppression.boilerplate]
# trivial-body = "rank-down"
# forwarding = "hide"
# macro-repetition = "rank-down"
# guarded-dispatch = "hide"
# configured-answer = "hide"
# composed-answer = "hide"
# built-answer = "hide"

これらが指すのはファイルではなく形です。呼び出し 1 つに転送するだけの本体、定数を返すだけの match アーム、条件 1 つで分岐するディスパッチなどが該当します。統合しても得より手間が上回ることが多く、報告すれば本当に読むべきものが埋もれます。

--include-trivial は、1 回の実行だけ、単純な形の predicate グループを計測どおりの priority に戻します。predicate ファミリを明示的にレビューしたいときのための形です。

整数幅ファミリ

# width-family = "hide"

型のある言語では整数幅ごとに 1 本ずつ書くことがしばしば必要なので、既定では隠します。macro・generic・template でその関数群を一度だけ書けるなら report に設定してください。

退化した繰り返し

# entropy-ratio-floor = 0.60

このキーはファイルの最上位に置き、[suppression] の外に書きます。

この正規化済み content entropy の比を下回るグループは、ルーチンではなく同じ数トークンの繰り返しとして印を付けます。値は同じトークン長のグループが持ち得る最大のエントロピーに対する相対値なので、クローンの長さをそのままノイズフィルタにしてしまうことはありません。

ID で

# clone-ids = []

特定のグループを安定 ID で名指しします。プロジェクトがその 1 件の重複について判断を下していて、それをより一般的に表す規則が無い場合の手段です。ID は 1 つのグループの内容を表すので、その内容が変われば一致しなくなります。これは意図した挙動です。判断はそのときのコードについて下されたものだからです。

baseline も、凍結したグループの内容をキーにする点は同じです。承認したグループのコピーをすべて編集した場合や、内容の新しいコピーを足した場合は、baseline の判断が引き継がれず、そのグループは新規として現れます。baseline は各出現箇所の位置も記録しているため、スキャンは「削除された項目のあった場所に新しいグループが立っている」と述べられますが、この注記は置き換わったことを説明するだけで、何も隠しません。

モード

これらの分類は構文構造を必要とするため、適用されるのは Structural と Semantic のスキャンで、Fast のスキャンでは利用できないことを明示します。大きなツリーで Fast のレポートが有用な長さを超える主な理由がこれです。解析モードを参照してください。