Jetpack Compose Compiler Report Reveals Stability Misclassification in Complex UI Trees

Answer the Exact Question First

At what point should developers trust the compiler’s default stability classification versus manually annotating classes with @Stable or @Immutable?

• If a type is defined in your project, is final, has only val properties, and uses immutable collections, the compiler’s inference is usually safe.
• When a type comes from an external library, contains var fields, is open, or uses mutable Kotlin List/Map, trust the compiler’s default of unstable unless you can prove the library guarantees immutability.
• Only annotate a type manually when you have full control over its implementation and can guarantee that its state never changes after construction (or that changes are properly surfaced via observable mechanisms).

How to Establish Consistent Guidelines Across a Large Codebase

• Adopt a rule‑based policy: annotate @Immutable only for data classes that are final, all properties are val, and use Kotlinx immutable collections.
• Use @Stable for types that expose mutable state but guarantee that any mutation will trigger recomposition (e.g., via MutableState).
• Reject annotations on external types; instead, wrap them in an internal immutable façade.
• Require a code‑review check that verifies the contract: no var, no open classes, no mutable collections.

Automated Verification Approaches

• Enable the Compose compiler report (add -Pplugin:androidx.compose.compiler.plugins.kotlin:stabilityReport=true) and inspect the Stability section for non‑skippable composables.
• Add a static‑analysis rule (Detekt or custom lint) that flags @Stable/@Immutable on classes with var, open declarations, or mutable collections.
• Run a recomposition trace in integration tests: if a composable that should skip still recomposes, the annotation is likely incorrect.
• Automate a nightly check that regenerates the compiler report and fails the build if new unstable parameters appear.

Practical Steps for Your Codebase

1. Enable the compiler report in build.gradle.kts:

   tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
       kotlinOptions.freeCompilerArgs += "-Pplugin:androidx.compose.compiler.plugins.kotlin:stabilityReport=true"
   }
   

2. Run a build and open compose-stability-report.html.
3. Identify non‑skippable composables that receive external types.
4. For each flagged type, confirm:
   • Is it under your control?
   • Does it expose var fields or mutable collections?
   • Can you guarantee it won’t mutate after construction?
5. If yes, add @Immutable (or @Stable if shallow stability suffices). If no, wrap the type in an internal immutable façade or keep it unannotated.
6. Add a static‑analysis rule to catch future misuse automatically.
7. Schedule a nightly build that regenerates the report and asserts the number of non‑skippable composables does not increase.

Missing Diagnostic Detail

To refine the recommendation, could you share which external library types are being passed to your composables? Knowing the exact classes would help determine whether a façade or a manual annotation is appropriate.