Update docs for stabilityConfigurationFiles (#140)

* Add optional and improve conditional logics

* Update docs for stabilityConfigurationFiles

Author: skydoves

README.md

@@ -878,6 +878,46 @@ composeStabilityAnalyzer {
 }
 ```
 
+#### `stabilityConfigurationFiles` Option
+
+You can provide stability configuration files to tell `stabilityCheck` which types should be treated as stable, even if the compiler marks them as unstable. This matches the [Compose compiler's stability configuration file](https://developer.android.com/develop/ui/compose/performance/stability/fix#configuration-file) format, so you can reuse the same file for both the compiler and stability validation.
+
+This is useful when:
+- Third-party library types don't have `@Stable` or `@Immutable` annotations
+- Code-generated types are effectively stable but the compiler can't infer it
+- You want the stability check to respect the same overrides as the Compose compiler
+
+```kotlin
+composeStabilityAnalyzer {
+    stabilityValidation {
+        // Use the same stability configuration file as the Compose compiler
+        stabilityConfigurationFiles.add(
+            rootProject.layout.projectDirectory.file("stability_config.conf")
+        )
+    }
+}
+```
+
+**Example `stability_config.conf`:**
+
+```
+// Types from third-party libraries
+com.google.firebase.auth.FirebaseUser
+com.squareup.moshi.JsonAdapter
+
+// All types in a package
+com.example.generated.*
+
+// All types in a package and its sub-packages
+com.example.models.**
+```
+
+The file supports `*` (single-level wildcard) and `**` (multi-level wildcard) patterns. Lines starting with `//` are treated as comments.
+
+When `stabilityConfigurationFiles` is set, the `stabilityCheck` task treats any parameter type matching these patterns as stable. This means:
+- New composables with all parameters matching these patterns won't be flagged
+- Parameter stability changes from UNSTABLE to a matching type won't be reported as regressions
+
 **Why ignore packages/classes**
 
 If you don't want to track:

compose-stability-analyzer-idea/src/main/resources/icons/stability.svg

@@ -126,6 +126,13 @@ composeStabilityAnalyzer {
 
         // Allow checks without a baseline file (default: false)
         allowMissingBaseline.set(false)
+
+        // Add stability configuration file
+        // Matches compose's identical property
+        // (see https://developer.android.com/develop/ui/compose/performance/stability/fix#configuration-file)
+        stabilityConfigurationFiles.add(
+            rootProject.layout.projectDirectory.file("stability_config.conf")
+        )
     }
 }
 ```
@@ -158,6 +165,33 @@ composeStabilityAnalyzer {
 }
 ```
 
+### `stabilityConfigurationFiles`
+
+You can provide stability configuration files to tell `stabilityCheck` which types should be treated as stable, even if the compiler marks them as unstable. This uses the same format as the [Compose compiler's stability configuration file](https://developer.android.com/develop/ui/compose/performance/stability/fix#configuration-file), so you can reuse the same file for both the compiler and stability validation.
+
+```kotlin
+composeStabilityAnalyzer {
+    stabilityValidation {
+        stabilityConfigurationFiles.add(
+            rootProject.layout.projectDirectory.file("stability_config.conf")
+        )
+    }
+}
+```
+
+The configuration file contains fully-qualified type names, one per line. Lines starting with `//` are treated as comments. Wildcard patterns are supported: `*` matches a single package segment and `**` matches across package boundaries.
+
+```
+// stability_config.conf
+com.google.firebase.auth.FirebaseUser
+com.example.generated.*
+com.example.models.**
+```
+
+When these files are configured, the `stabilityCheck` task treats any parameter type matching these patterns as stable. This affects the comparison in two ways: new composables whose parameters all match these patterns won't be flagged, and parameter stability regressions to a matching type won't be reported.
+
+This is particularly useful when your project already uses a stability configuration file for the Compose compiler. By pointing `stabilityConfigurationFiles` to the same file, the stability validation respects the same overrides, keeping the two in sync.
+
 ## Excluding Composables
 
 Some composables shouldn't be included in stability validation: preview composables that only exist for Android Studio previews, debug-only screens, or experimental features still under active development. Use the `@IgnoreStabilityReport` annotation to exclude them.

docs/gradle-plugin/stability-validation.md

@@ -151,6 +151,8 @@ com.example.ThirdPartyModel
 com.google.firebase.auth.FirebaseUser
 ```
 
+The same configuration file can also be used with the [Stability Validation](gradle-plugin/stability-validation.md#stabilityconfigurationfiles) Gradle task. By pointing `stabilityConfigurationFiles` to this file, the `stabilityCheck` task respects the same overrides as the Compose compiler, so types you've declared stable won't be flagged as regressions.
+
 ## Cross-Module Stability
 
 Types from other modules that were **not compiled with the Compose compiler** are treated as unstable by default. This is a conservative decision, because the Compose compiler in your module can't inspect the source code of external modules, so it can't verify stability.

docs/stability-concepts.md

@@ -96,6 +96,7 @@ public abstract class StabilityCheckTask : DefaultTask() {
   public abstract val allowMissingBaseline: Property<Boolean>
 
   @get:InputFiles
+  @get:Optional
   @get:PathSensitive(PathSensitivity.RELATIVE)
   public abstract val stabilityConfigurationFiles: ListProperty<RegularFile>
 
@@ -152,15 +153,9 @@ public abstract class StabilityCheckTask : DefaultTask() {
     val currentStability = parseStabilityFromCompiler(inputFile)
     val referenceStability = parseStabilityFile(referenceFile)
 
-    val stabilityConfigurationMatchers = stabilityConfigurationFiles.get()
+    val stabilityConfigurationMatchers = stabilityConfigurationFiles.getOrElse(emptyList())
       .flatMap { configRegularFile ->
-        val file = configRegularFile.asFile
-
-        if (!file.exists()) {
-          return@flatMap emptyList()
-        }
-
-        StabilityConfigParser.fromFile(file.path).stableTypeMatchers
+        StabilityConfigParser.fromFile(configRegularFile.asFile.path).stableTypeMatchers
       }
 
     val differences =