Compose stability: annotations, ImmutableList, and a check that enforces both

[solcott]

What

This branch does the Compose stability work in two halves. The first twelve commits are the manual pass — @Immutable/@Stable annotations on the model and screen states, ImmutableList from each repository's public signature onward, and the rules written down in CLAUDE.md. The last commit makes the machine check all of it, because prose in a rules file is enforced by whoever remembers to read it.

The check

A new compose.stability convention plugin turns on the Compose compiler's own metrics and reports for the six modules that apply the compiler plugin (:ui, :domain, :shared, :app, :webApp, :desktopApp) and registers composeStabilityCheck. It fails on a class the compiler inferred as unstable, and on a restartable composable that is not skippable. A runtime class passes — its stability turns on a generic argument settled at run time.

Exceptions live in config/compose/unstable-classes.txt and config/compose/unskippable-composables.txt, one <module>:<fully.qualified.Name> per line, each with a comment. There is no aggregate task: Gradle's cross-project name matching already fans composeStabilityCheck out to all six.

Detekt's UnstableCollections is also on now, covering the same ground at the source level.

Two properties of the Compose plugin that shaped the wiring

Only metricsDestination is per-target. The plugin appends <target>/<compilation> to the metrics path but hands reportsDestination to every compilation verbatim, and a KMP module's targets share a Kotlin module name — ui/build/classes/kotlin/jvm/main and .../android/main both hold Recipes_ui.kotlin_module. So all six targets write the same Recipes_ui-classes.txt and the last to run wins. The check depends on exactly one compile task, which leaves a single writer. That is also why it is not wired into check, and why CI runs it as its own step before build.

reportsDestination is registered as a compiler input, not an output. A compile task whose reports had been deleted still counted as up to date and quietly wrote nothing — four of six modules failed with "no reports found" on a perfectly healthy tree. The plugin declares the directory as an output of the one designated compile task, which fixes that and additionally keeps that task the last writer after a full build.

Triage

:ui, :domain, :shared and :desktopApp came back clean — the manual pass holds up. Four classes are allowlisted, each checked individually:

• AndroidAppGraph.Impl and WebAppGraph.Impl — nothing hands a graph to a composable on those platforms; main() reads graph.circuit and graph.subCircuit off it. DesktopAppGraph is the exception, and it is absent from the list: RecipeWindow(graph: DesktopAppGraph, ...) does take one, it carries @Stable, and :desktopApp reports nothing.
• MainActivity and RecipeApplication — Android framework entry points, never composable parameters. Annotating either @Stable would be a lie.

One deliberate non-change

UnstableCollections flags RecipesProducer.produceByIngredients(ingredients: Set<String>). The compiler report settles it: that function carries no flags — it returns a value, so it is neither restartable nor skippable, and the parameter's stability is inert. Switching to ImmutableSet would buy nothing at run time and cost either a persistent-set copy per recomposition at the call site or a kotlinx-serialization serializer for RecipesScreen.ByIngredient, which has none for immutable collections. It is a @Suppress with that reasoning recorded instead.

Verification

ktfmtCheck checkSortDependencies, detektAll, composeStabilityCheck, all six KMP targets for :domain/:ui/:shared, plus :app:assembleDebug, :desktopApp:build, :webApp:build, and :domain:jvmTest (91 tests) — all green.

Both checks were also confirmed to fail when they should, since one that has never been seen fail is not yet known to work: removing the @Suppress produced the detekt finding, and a scratch class ScratchUnstable(var counter: Int) produced Unstable classes (1) naming it. Worth noting from that experiment — the scratch composable came out restartable skippable despite its unstable parameter, which is strong skipping working as intended and confirms the skippability half of the check only catches genuine cases.

🤖 Generated with Claude Code