Add Support for Specifying Annotations that Break Compatibility

README.md

@@ -1,7 +1,7 @@
 # metalava-gradle
 [![Build](https://github.com/tylerbwong/metalava-gradle/actions/workflows/build.yml/badge.svg)](https://github.com/tylerbwong/metalava-gradle/actions/workflows/build.yml)
 [![Gradle Plugin Portal](https://img.shields.io/maven-metadata/v/https/plugins.gradle.org/m2/me/tylerbwong/gradle/metalava/me.tylerbwong.gradle.metalava.gradle.plugin/maven-metadata.xml.svg?colorB=007ec6&label=Gradle%20Plugin%20Portal)](https://plugins.gradle.org/plugin/me.tylerbwong.gradle.metalava)
-[![Metalava](https://img.shields.io/badge/Metalava-1.0.0--alpha10-orange)](https://maven.google.com/web/index.html#com.android.tools.metalava:metalava:1.0.0-alpha10)
+[![Metalava](https://img.shields.io/badge/Metalava-1.0.0--alpha11-orange)](https://maven.google.com/web/index.html#com.android.tools.metalava:metalava:1.0.0-alpha11)
 
 A Gradle plugin for [Metalava](https://android.googlesource.com/platform/tools/metalava/), AOSP's tool for API metadata extraction and compatibility tracking.
 

plugin/src/main/kotlin/me/tylerbwong/gradle/metalava/extension/MetalavaExtension.kt

@@ -17,7 +17,7 @@ open class MetalavaExtension @Inject constructor(
     /**
      * The version of Metalava to use.
      */
-    val version: Property<String> = objectFactory.property<String>().also { it.set("1.0.0-alpha10") }
+    val version: Property<String> = objectFactory.property<String>().also { it.set("1.0.0-alpha11") }
 
     /**
      * A custom Metalava JAR to use instead of the embedded dependency.
@@ -61,6 +61,14 @@ open class MetalavaExtension @Inject constructor(
      */
     val hiddenAnnotations: SetProperty<String> = objectFactory.setProperty()
 
+    /**
+     * A comma separated list of fully qualified annotation names.
+     *
+     * Treat elements annotated with the passed in annotations as important for API compatibility.
+     * (e.g. @Composable)
+     */
+    val apiCompatAnnotations: SetProperty<String> = objectFactory.setProperty()
+
     /**
      * Whether the signature file being read should be interpreted as having encoded its types using
      * Kotlin style types: a suffix of "?" for nullable types, no suffix for non nullable types, and

plugin/src/main/kotlin/me/tylerbwong/gradle/metalava/task/BaseMetalavaTask.kt

@@ -38,6 +38,10 @@ internal abstract class BaseMetalavaTask(
     @get:Input
     val hiddenAnnotations: SetProperty<String> = objectFactory.setProperty()
 
+    @get:Optional
+    @get:Input
+    val apiCompatAnnotations: SetProperty<String> = objectFactory.setProperty()
+
     @get:Optional
     @get:Input
     val arguments: SetProperty<String> = objectFactory.setProperty()

plugin/src/main/kotlin/me/tylerbwong/gradle/metalava/task/MetalavaCheckCompatibilityTask.kt

@@ -45,6 +45,7 @@ internal abstract class MetalavaCheckCompatibilityTask @Inject constructor(
         metalavaGenerateSignatureInternal(filenameOverride = tempFilename.get(), awaitWork = true)
         val hidePackages = hiddenPackages.get().flatMap { listOf("--hide-package", it) }
         val hideAnnotations = hiddenAnnotations.get().flatMap { listOf("--hide-annotation", it) }
+        val apiCompatAnnotations = apiCompatAnnotations.get().flatMap { listOf("--api-compat-annotation", it) }
 
         val args: List<String> = listOf(
             "--format=${format.get()}",
@@ -53,7 +54,7 @@ internal abstract class MetalavaCheckCompatibilityTask @Inject constructor(
             "--check-compatibility:${apiType.get()}:released",
             filename.get(),
         ) + reportWarningsAsErrors.get().flag("--warnings-as-errors") + reportLintsAsErrors.get()
-            .flag("--lints-as-errors") + hidePackages + hideAnnotations + arguments.get()
+            .flag("--lints-as-errors") + hidePackages + hideAnnotations + apiCompatAnnotations + arguments.get()
         executeMetalavaWork(args)
     }
 
@@ -92,6 +93,7 @@ internal abstract class MetalavaCheckCompatibilityTask @Inject constructor(
                 javaSourceLevel.set(extension.javaSourceLevel)
                 hiddenPackages.set(extension.hiddenPackages)
                 hiddenAnnotations.set(extension.hiddenAnnotations)
+                apiCompatAnnotations.set(extension.apiCompatAnnotations)
                 apiType.set(extension.apiType)
                 inputKotlinNulls.set(extension.inputKotlinNulls)
                 reportWarningsAsErrors.set(extension.reportWarningsAsErrors)

plugin/src/main/kotlin/me/tylerbwong/gradle/metalava/task/MetalavaGenerateSignatureTask.kt

@@ -82,6 +82,7 @@ internal abstract class MetalavaGenerateSignatureTask @Inject constructor(
             .joinToString(File.pathSeparator)
         val hidePackages = hiddenPackages.get().flatMap { listOf("--hide-package", it) }
         val hideAnnotations = hiddenAnnotations.get().flatMap { listOf("--hide-annotation", it) }
+        val apiCompatAnnotations = apiCompatAnnotations.get().flatMap { listOf("--api-compat-annotation", it) }
         val keepFilename = keepFilename.orNull
         val keepFileFlags = if (!keepFilename.isNullOrEmpty()) {
             listOf("--proguard", keepFilename)
@@ -95,7 +96,7 @@ internal abstract class MetalavaGenerateSignatureTask @Inject constructor(
             "--java-source", "${javaSourceLevel.get()}",
             "--classpath", fullClasspath,
             "--source-path", sourcePaths,
-        ) + hidePackages + hideAnnotations + keepFileFlags + arguments.get()
+        ) + hidePackages + hideAnnotations + apiCompatAnnotations + keepFileFlags + arguments.get()
         executeMetalavaWork(args, awaitWork)
     }
 
@@ -129,6 +130,7 @@ internal abstract class MetalavaGenerateSignatureTask @Inject constructor(
                 javaSourceLevel.set(extension.javaSourceLevel)
                 hiddenPackages.set(extension.hiddenPackages)
                 hiddenAnnotations.set(extension.hiddenAnnotations)
+                apiCompatAnnotations.set(extension.apiCompatAnnotations)
                 keepFilename.set(extension.keepFilename)
                 arguments.set(extension.arguments)
             }

samples/kotlin-dsl-compose/build.gradle.kts

@@ -15,6 +15,7 @@ android {
 
 metalava {
     filename.set("api/$name-api.txt")
+    apiCompatAnnotations.set(listOf("androidx.compose.runtime.Composable"))
 }
 
 dependencies {