chore: enable Kotlin explicitApi() and Binary Compatibility Validator (.api dumps)

- Enable kotlin explicitApi() across published modules (:library, :clustering, :data, :heatmaps, :ui)
- Add explicit public visibility and return types to all public Kotlin symbols across modules
- Configure Binary Compatibility Validator (BCV) for AGP 9.3 via build-logic convention plugin and root aggregate tasks
- Generate and commit baseline .api dumps for :library, :clustering, :data, :heatmaps, and :ui
- Add apiCheck to the CI Pull Request test workflow

Fixes #1794

Author: dkhawk

.github/workflows/test.yml

@@ -46,4 +46,4 @@ jobs:
       run: echo "MAPS_API_KEY=dummy" > secrets.properties
 
     - name: Build modules
-      run: ./gradlew build koverXmlReportDebug --stacktrace
+      run: ./gradlew build apiCheck koverXmlReportDebug --stacktrace

build-logic/convention/build.gradle.kts

@@ -30,6 +30,7 @@ dependencies {
     implementation(libs.dokka.gradle.plugin)
     implementation(libs.kover.gradle.plugin)
     implementation(libs.gradle.maven.publish.plugin)
+    implementation(libs.binary.compatibility.validator)
 }
 
 gradlePlugin {

build-logic/convention/src/main/kotlin/PublishingConventionPlugin.kt

@@ -18,8 +18,11 @@
 import com.vanniktech.maven.publish.AndroidSingleVariantLibrary
 import com.vanniktech.maven.publish.MavenPublishBaseExtension
 import kotlinx.kover.gradle.plugin.dsl.KoverProjectExtension
+import kotlinx.validation.KotlinApiBuildTask
+import kotlinx.validation.KotlinApiCompareTask
 import org.gradle.api.Plugin
 import org.gradle.api.Project
+import org.gradle.api.tasks.Copy
 import org.gradle.kotlin.dsl.*
 
 class PublishingConventionPlugin : Plugin<Project> {
@@ -28,6 +31,7 @@ class PublishingConventionPlugin : Plugin<Project> {
             applyPlugins()
             configureKover()
             configureVanniktechPublishing()
+            configureBinaryCompatibilityValidator()
         }
     }
 
@@ -106,4 +110,65 @@ class PublishingConventionPlugin : Plugin<Project> {
             }
         }
     }
+
+    private fun Project.configureBinaryCompatibilityValidator() {
+        val ignoredProjects = setOf("demo", "visual-testing", "lint-checks", "maps-utils")
+        if (name in ignoredProjects) return
+
+        val projectName = name
+        val apiFile = layout.projectDirectory.file("api/$projectName.api")
+        val buildApiFile = layout.buildDirectory.file("api/$projectName.api")
+
+        afterEvaluate {
+            val bundleTask = tasks.findByName("bundleLibCompileToJarRelease") ?: return@afterEvaluate
+            val classesJar = layout.buildDirectory.file(
+                "intermediates/compile_library_classes_jar/release/bundleLibCompileToJarRelease/classes.jar"
+            )
+
+            val apiBuild = tasks.register<KotlinApiBuildTask>("apiBuild") {
+                group = "verification"
+                description = "Builds public API declaration for $projectName."
+                inputJar.set(classesJar)
+                outputApiFile.set(buildApiFile)
+                ignoredClasses.addAll(
+                    "com.google.maps.android.R",
+                    "com.google.maps.android.clustering.R",
+                    "com.google.maps.android.data.R",
+                    "com.google.maps.android.heatmaps.R",
+                    "com.google.maps.android.ui.R",
+                    "com.google.maps.android.BuildConfig",
+                    "com.google.maps.android.clustering.BuildConfig",
+                    "com.google.maps.android.data.BuildConfig",
+                    "com.google.maps.android.heatmaps.BuildConfig",
+                    "com.google.maps.android.ui.BuildConfig",
+                )
+                dependsOn(bundleTask)
+            }
+
+            val apiDump = tasks.register<Copy>("apiDump") {
+                group = "verification"
+                description = "Syncs public API declarations of $projectName to the project api/ directory."
+                from(apiBuild.flatMap { it.outputApiFile })
+                into(apiFile.asFile.parentFile)
+                dependsOn(apiBuild)
+            }
+
+            val apiCheck = tasks.register<KotlinApiCompareTask>("apiCheck") {
+                group = "verification"
+                description = "Checks public API declarations of $projectName against the committed api/$projectName.api."
+                projectApiFile.set(apiFile)
+                generatedApiFile.set(apiBuild.flatMap { it.outputApiFile })
+                dependsOn(apiBuild)
+            }
+
+            tasks.findByName("check")?.dependsOn(apiCheck)
+
+            rootProject.tasks.matching { it.name == "apiDump" }.configureEach {
+                dependsOn(apiDump)
+            }
+            rootProject.tasks.matching { it.name == "apiCheck" }.configureEach {
+                dependsOn(apiCheck)
+            }
+        }
+    }
 }

build.gradle.kts

@@ -19,6 +19,21 @@ import java.util.Properties
 
 plugins {
     id("com.vanniktech.maven.publish") version libs.versions.gradleMavenPublishPlugin.get() apply false
+    alias(libs.plugins.binary.compatibility.validator)
+}
+
+apiValidation {
+    ignoredProjects += listOf("demo", "visual-testing", "lint-checks", "maps-utils")
+}
+
+val apiDump = tasks.register("apiDump") {
+    group = "verification"
+    description = "Dumps public API declarations for all library modules."
+}
+
+val apiCheck = tasks.register("apiCheck") {
+    group = "verification"
+    description = "Checks that public API declarations match the committed .api files."
 }
 
 buildscript {