using-stability-analyzer-ide-plugin

Stability Analyzer IDE プラグインの使用 — エディター内でリアルタイムに安定性を確認

Compose Compiler のレポートでは、ビルド完了後に安定性を確認できます。skydoves/compose-stability-analyzer IntelliJ プラグインなら、編集中に確認できます。ガターアイコンは各 @Composable を色分けし、ホバー時のドキュメントには理由付きのパラメーター別テーブルが表示されます。インラインヒントは各パラメーター型の横に色付きのバッジを表示し、UnstableComposable の弱い警告を出すインスペクションは、クイックフィックスで対処可能な問題を提示します。

このプラグインは Kotlin K2 Analysis API を使って、../understanding-stability-inference/SKILL.md の基盤となるものと同じ安定性ルールを評価するため、エディターのフィードバックは、後でコンパイラレポートに表示される ../diagnosing-compose-stability/SKILL.md の内容と一致します。これにより、「リリース → ビルド → レポートを読む」というサイクルを、「入力 → ガターを見る」へと短縮できます。

このスキルを使う場面

• Composable ファイルの編集中に、リアルタイムの安定性フィードバックを確認したい場合。
• レビュアーがローカルで PR を確認し、各コンポーザブルの横にあるインラインのシグナルを見たい場合。
• 新しく参加したメンバーが、ファイル内のどのコンポーザブルがスキップ不可かをひと目で確認したい場合。
• UnstableComposable という弱い警告で関数にフラグが立った理由を知りたい場合。
• ガターアイコン、インラインヒント、安定性インスペクション、IDEA プラグイン、Compose 用 K2 Analysis API、または Compose Stability Analyzer ツールウィンドウについて質問された場合。

このスキルを使わない場面

• 安定性のリグレッション時にビルドを失敗させる CI のゲート設定。../enforcing-stability-in-ci/SKILL.md を使ってください。
• ビルド時の Compose Compiler レポートの分析。../diagnosing-compose-stability/SKILL.md を使ってください。
• プラグインのツールウィンドウを使った、実行中のトレースや視覚的なカスケード調査。../visualizing-recomposition-cascades/SKILL.md を使ってください。
• コンパイラが型を分類する方法についての概念的な質問。../understanding-stability-inference/SKILL.md を使ってください。

前提条件

• Android Studio 2024.2+ または IntelliJ IDEA 2024.2+（ビルド範囲 242～261。2024.2 から 2026.1 EAP までを対象）。
• IDE プラグインのランタイムに Kotlin 2.3.0 が必要です。これは、プラグインが依存する K2 Analysis API に必要です。
• プロジェクトに Compose Compiler Gradle プラグイン（org.jetbrains.kotlin.plugin.compose）がすでに組み込まれていること。アナライザーは同じコンパイラモデルに基づいて安定性を評価します。
• 現在、開発中のプラグインはディスクからインストールします。JetBrains Marketplace への掲載は申請中です。

ワークフロー

1. ソースからプラグインをビルドする

skydoves/compose-stability-analyzer をクローンし、IDEA モジュールをビルドします。

git clone https://github.com/skydoves/compose-stability-analyzer
cd compose-stability-analyzer
./gradlew :compose-stability-analyzer-idea:buildPlugin

パッケージ化されたプラグインは compose-stability-analyzer-idea/build/distributions/*.zip に出力されます。

2. ディスクからインストールする

IDE で Settings → Plugins → ⚙ → Install Plugin from Disk… を開き、手順 1 で生成した ZIP を選択します。プロンプトが表示されたら IDE を再起動してください。まだ JetBrains Marketplace でプラグインを探さないでください。執筆時点では掲載内容の審査中です。

3. 設定パネルを確認する

Settings → Tools → Compose Stability Analyzer を開きます。isStabilityCheckEnabled がオンになっていることを確認します。すべてのトグルは StabilitySettingsState から読み込まれ、次のとおりです。

キー	デフォルト	効果
isStabilityCheckEnabled	true	すべてのエディター機能のマスタースイッチです。
isStrongSkippingEnabled	true	Compose Compiler 2.0.20+ のランタイムに合わせ、Strong Skipping が有効な状態で分類します。
showGutterIcons	true	各 @Composable の横のガターに色付きアイコンを表示します。
showGutterIconsOnlyForUnskippable	false	緑／グレーのアイコンを非表示にし、問題がある場合のみ表示します。密度の高いファイルで使用します。
showGutterIconsInTests	false	テストのソースルート内にもガターアイコンを表示します。
showWarnings	true	UnstableComposable インスペクションを有効にします。
showInlineHints	true	色付きのパラメーター型バッジをインラインで表示します。
showOnlyUnstableHints	false	安定したパラメーターのインラインバッジを非表示にします。
stableGutterColorRGB	#5FB865 (95, 184, 101)	安定したコンポーザブルのガター／ヒントの色です。
unstableGutterColorRGB	#E8684A (232, 104, 74)	不安定なコンポーザブルのガター／ヒントの色です。
runtimeGutterColorRGB	#F0C674 (240, 198, 116)	ランタイム安定性を持つコンポーザブルのガター／ヒントの色です。
stableHintColorRGB / unstableHintColorRGB / runtimeHintColorRGB	上記のデフォルト値	インラインヒントの色を上書きします。
ignoredTypePatterns	""	安定しているものとして扱う型の、改行またはカンマ区切りの glob リストです。
stabilityConfigurationPath	""	コンパイラーが読み込むものと同じ stability_config.conf への任意のパスです。
isHeatmapEnabled	true	ライブ再コンポジションヒートマップを有効にします（../visualizing-recomposition-cascades/SKILL.md を参照）。

エディター内の分類がコンパイラーの分類と一致するように、stabilityConfigurationPath にプロジェクトの stability_config.conf を指定します。

4. ガターの色を確認する

@Composable 関数を含む Kotlin ファイルを開きます。それぞれの横に色付きアイコンが表示されることを確認します。4 色とその意味は次のとおりです。

色	16 進数	意味
緑	#5FB865	スキップ可能です。すべてのパラメーターが安定しています。
赤	#E8684A	不安定なパラメーターが少なくとも 1 つあります。スキップできません。
黄	#F0C674	ランタイム安定性を持つパラメーターが少なくとも 1 つあります（別々のコンパイル単位をまたいで解決されます）。
グレー	#808080	パラメーターがありません（それでも再起動可能ですが、自明にスキップ可能です）。

ガターがグレーでも問題ありません。比較するものがない関数です。緑のガターは、引数が等しい場合に Compose が再コンポジションをスキップするとアナライザーが判断していることを示します。赤または黄色のガターは診断結果です。親が再コンポジションすると、その関数は必要以上に再コンポジションされます。

5. ホバーしてパラメーターテーブルを確認する

任意のコンポーザブル名にカーソルを合わせます。StabilityDocumentationProvider が提供するポップアップには、スキップ可能かどうかを示すバッジ、パラメーターごとの安定性分類を示すテーブル、そしてアナライザーが特定できる場合は推奨される修正（例：「List<Item> を ImmutableList でラップする」）が表示されます。コンパイラーの完全なレポートを開く前のトリアージに使用してください。

6. 密度の高いファイル向けにインラインヒントを調整する

StabilityInlayHintsProvider は、関数シグネチャ内の各パラメーター型の横に色付きバッジを表示します。コンポーザブルが多い画面では、表示が煩雑になることがあります。Settings → Tools → Compose Stability Analyzer で showOnlyUnstableHints を有効にすると、安定したパラメーターのバッジが非表示になり、対応が必要なものだけが残ります。さらに表示を抑えたい場合は、showGutterIconsOnlyForUnskippable を有効にすると、ガターには赤／黄色のみが表示されます。

7. UnstableComposable の検査を読み取る

StabilityInspection（短縮名 UnstableComposable、グループ Compose、重大度は弱い警告）は、少なくとも 1 つの不安定なパラメーターを持つ、スキップ不可のコンポーザブルにフラグを付けます。これは編集中、および Code → Inspect Code… で実行されます。この検査結果は、次の 2 つの方法で表示されます。

• エディター内の弱い警告を示す下線。
• Compose / Unstable Composable の下にグループ化された、Inspection Results ツールウィンドウ内の検出結果。

これは意図的に弱い警告です。スキップ可能性は診断情報であり、ビルドを妨げるエラーではありません。ファイルを赤くしたり、コミットをブロックしたり、それだけで CI を失敗させたりすることはありません。バックログのシグナルとして扱ってください。

8. 正当な理由がある場合にのみクイックフィックスを適用する

この検査には、下線の付いたコンポーザブルで Alt+Enter を押すと表示される、2 つの抑制インテントが用意されています。

• @Suppress("NonSkippableComposable") — AddSuppressAnnotationFix / AddSuppressIntentionAction によって適用されます。開発者が許容できると判断した関数（例：ホットパス上で決して使われないデバッグオーバーレイ）で、検査を無効にします。
• @Suppress("ParamsComparedByRef") — 同じ修正方法ですが、対象範囲はより狭く、パラメーターを意図的に参照で比較する場合に警告を無効にします。

抑制は対象の関数だけに適用してください。ファイルスコープに適用してはいけません。

9. ホットパスに @TraceRecomposition を付ける

AddTraceRecompositionIntention は、任意の @Composable で Alt+Enter を押すと使用できます。ライブヒートマップと ../../measurement/tracing-recompositions-at-runtime/SKILL.md が使用する、ランタイム計測のエントリーポイントである @TraceRecomposition アノテーションを挿入します。ガターで疑わしいホットコンポーザブルを特定したら、これを使用してください。

パターン

パターン：ホットパス内の赤いガターは、ビルドが成功していても対処が必要です

// WRONG
PriceTicker has a red gutter icon.
Build is green, the team ships, jank reports come in two days later.

// WRONG because: the inspection is a weak warning by design and does not block the build.
// The gutter is the only signal until the developer opens the compiler reports.
// Treat red gutters on hot-path composables as actionable; confirm with
// `../diagnosing-compose-stability/SKILL.md`, then fix via `../stabilizing-compose-types/SKILL.md`.

// RIGHT
PriceTicker has a red gutter icon.
Hover -> "price: Price unstable (var price)".
Open the compiler reports for confirmation.
Stabilize `Price` (val + immutable fields) per `../stabilizing-compose-types/SKILL.md`.
Gutter turns green; confirm with the live heatmap per `../visualizing-recomposition-cascades/SKILL.md`.

パターン：抑制は関数に適用し、ファイルには適用しないでください

// WRONG
@file:Suppress("UnstableComposable")

package com.example.feature.cart

// WRONG because: file-level suppression hides every future regression in that file.
// New unstable composables added to the file will never surface in the inspection.

// RIGHT — narrow, justified suppression on a single function
@Suppress("NonSkippableComposable")
@Composable
fun DebugOverlay(state: MutableState<DebugInfo>) {
    // dev-only overlay; never on hot path; intentional MutableState parameter.
}

パターン：ガターを 100% 緑にすることを追求しないでください

// WRONG
"All composables in :feature-search must show green gutters before merge."

// WRONG because: skippability is a diagnostic, not a KPI. Some composables legitimately
// take unstable parameters (interop with Java POJOs, third-party data classes the team
// does not own). The goal is "no regression in hot-path composables", not "all green".
// Use `../enforcing-stability-in-ci/SKILL.md` to gate against regressions, not absolutes.

// RIGHT
Hot-path composables (list rows, scroll items, animation tickers) are green or yellow.
Cold-path composables (settings screens, debug tools) may be red and that is acceptable.

パターン：ノイズは検査の無効化ではなく、設定で抑えてください

// WRONG
Settings -> Editor -> Inspections -> Compose -> Unstable Composable -> off

// WRONG because: turning the inspection off globally silences real regressions
// across the whole codebase. The next unstable parameter slipping into a hot
// composable will not surface anywhere in the editor.

// RIGHT
Settings -> Tools -> Compose Stability Analyzer:
  showGutterIconsOnlyForUnskippable = true
  showOnlyUnstableHints = true
The inspection stays on; only the visual noise is reduced.

パターン：エディター内の分類をコンパイラーと一致させてください

// RIGHT — in Settings -> Tools -> Compose Stability Analyzer
isStrongSkippingEnabled = true
stabilityConfigurationPath = "<repo-root>/stability_config.conf"

コンパイラーは Kotlin 2.0.20 以降で強いスキップがデフォルトで有効になっており、同じ stability_config.conf（../stabilizing-compose-types/SKILL.md を参照）を参照します。両方の設定を一致させると、開発者に表示されるガターの色と、../diagnosing-compose-stability/SKILL.md でコンパイラーが出力する内容が一致します。

必須ルール

• ホットパス内のコンポーザブルに赤または黄色のガターが表示された場合、必ず対応が必要な問題として扱ってください。../diagnosing-compose-stability/SKILL.md に従ってコンパイラのレポートを確認し、../stabilizing-compose-types/SKILL.md に従って修正してください。
• stabilityConfigurationPath は、Compose コンパイラが読み込むものと同じ stability_config.conf を指すように必ず設定してください。エディターとコンパイラの分類が一致するようにするためです。
• ファイル単位の @file:Suppress("UnstableComposable") は絶対に適用しないでください。特定の関数に @Suppress("NonSkippableComposable") または @Suppress("ParamsComparedByRef") を適用し、理由をコメントに記載してください。
• ノイズを抑えるためにインスペクションをグローバルに無効化してはいけません。まず、設定 → ツール → Compose Stability Analyzer で showGutterIconsOnlyForUnskippable = true と showOnlyUnstableHints = true に調整してください。
• ガターを 100％緑にしようと追求してはいけません。スキップ可能かどうかは診断情報であり、KPI ではありません。安定性設定は契約であり、魔法ではありません。可変型を安定としてマークするとコンパイラは開発者を信頼しますが、契約に違反すると再コンポジションが通知されないまま抜け落ちます。
• 推奨： Kotlin 2.0.20 以降でアナライザーの分類をコンパイラの実際のランタイム動作と一致させるため、isStrongSkippingEnabled = true を維持してください。
• 推奨： ホットパスの疑いがあるコンポーザブルに Add @TraceRecomposition インテンションを使って @TraceRecomposition を適用し、../../measurement/tracing-recompositions-at-runtime/SKILL.md に従ってランタイム側を設定してください。
• 推奨： 開発中はディスクからインストールしてください。JetBrains Marketplace の掲載は保留中のため、まだ利用可能であると想定してはいけません。

検証

• 設定 → プラグイン → ⚙ → ディスクからプラグインをインストール… からプラグインをインストールし、IDE を再起動している。
• 設定 → ツール → Compose Stability Analyzer が表示され、isStabilityCheckEnabled が有効になっている。
• @Composable 宣言を含む Kotlin ファイルを開くと、それぞれの横に色付きのガターアイコンが表示される。
• コンポーザブル名にカーソルを合わせると、StabilityDocumentationProvider が提供するパラメーター安定性テーブルのポップアップが表示される。
• 関数シグネチャ内の各パラメーターの横にインラインのパラメーター型ヒントが表示される。showOnlyUnstableHints を切り替えると、安定したパラメーターのヒントが非表示になる。
• 開いているファイルに既知の不安定なコンポーザブルがある場合、UnstableComposable インスペクション（グループ Compose、弱い警告）が少なくとも 1 つを検出する。
• 警告対象のコンポーザブルで Alt+Enter を押すと、@Suppress("NonSkippableComposable") と @Suppress("ParamsComparedByRef") のクイックフィックスが表示される。
• 任意の @Composable で Alt+Enter を押すと、Add @TraceRecomposition インテンションが表示される。
• stabilityConfigurationPath が、プロジェクトの Gradle 設定で Compose Compiler が使用するものと同じ stability_config.conf を指している。

参考資料

• skydoves/compose-stability-analyzer — https://github.com/skydoves/compose-stability-analyzer
• 同リポジトリ内の compose-stability-analyzer-idea モジュール — https://github.com/skydoves/compose-stability-analyzer/tree/main/compose-stability-analyzer-idea
• skydoves、「Optimize App Performance by Mastering Stability」 — https://medium.com/proandroiddev/optimize-app-performance-by-mastering-stability-in-jetpack-compose-69f40a8c785d
• Compose の安定性の概要 — https://developer.android.com/develop/ui/compose/performance/stability
• Strong Skipping — https://developer.android.com/develop/ui/compose/performance/stability/strongskipping
• IntelliJ Platform K2 Analysis API — https://plugins.jetbrains.com/docs/intellij/analysis-api.html

赤いガターをビルド失敗にする CI 側のゲート設定については、../enforcing-stability-in-ci/SKILL.md をご覧ください。ガターの色と一致するビルド時の Compose Compiler レポートについては、../diagnosing-compose-stability/SKILL.md をご覧ください。赤いガターを緑にする上流の型修正については、../stabilizing-compose-types/SKILL.md をご覧ください。同じプラグイン内の調査ツール（カスケードビジュアライザー、ライブヒートマップ）については、../visualizing-recomposition-cascades/SKILL.md をご覧ください。Add @TraceRecomposition のインテンションが設定する実行時インストルメンテーションについては、../../measurement/tracing-recompositions-at-runtime/SKILL.md をご覧ください。