Move from bcv plugin to KGP api validation (#6362)

* build: Move from the binary-compatibility-validator plugin to KGP ABI validation

* build: Validate the ABI of sentry-opentelemetry-agentless
Co-Authored-By: Markus Hintersteiner <markus.hintersteiner@sentry.io>

* build: Drop the apiDump and apiCheck aliases in favour of the KGP task names

* build: Restore the root build file changes from main lost in the merge

* build: Chain the ABI filters onto the abiValidation lookup

---------

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>

Author: markushi

.claude/skills/create-java-pr/SKILL.md

@@ -74,7 +74,7 @@ Derive the branch name from the changes being made. Use `feat/`, `fix/`, `ref/`,
 ## Step 2: Format Code and Regenerate API Files
 
 ```bash
-./gradlew spotlessApply apiDump
+./gradlew spotlessApply updateKotlinAbi
 ```
 
 This is **required** before every PR in this repo. It formats all Java/Kotlin code via Spotless and regenerates the `.api` binary compatibility files.

.cursor/BUGBOT.md

@@ -120,6 +120,6 @@ rule file in [`.cursor/rules/`](rules) for the area the diff touches (`api`, `op
 ## What NOT to flag
 
 - Formatting and import order — Spotless owns it.
-- Contents of generated `.api` files, beyond confirming `apiDump` was run.
+- Contents of generated `.api` files, beyond confirming `updateKotlinAbi` was run.
 - Conventional commit / PR title format, and missing changelog entries — CI and Danger check both.
 - Speculative refactors or improvements unrelated to the diff.

.cursor/rules/api.mdc

@@ -6,9 +6,9 @@ description: Public API surface, binary compatibility, and common classes to mod
 
 ## API Compatibility
 
-Public API is tracked via `.api` files generated by the [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator) Gradle plugin. Each module has its own file at `<module>/api/<module>.api`.
+Public API is tracked via `.api` files generated by the [ABI validation](https://kotlinlang.org/docs/gradle-binary-compatibility-validation.html) built into the Kotlin Gradle plugin. Each module has its own file at `<module>/api/<module>.api`.
 
-- **Never edit `.api` files manually.** Run `./gradlew apiDump` to regenerate them.
+- **Never edit `.api` files manually.** Run `./gradlew updateKotlinAbi` to regenerate them.
 - `./gradlew check` validates current code against `.api` files and fails on unintended changes.
 - `@ApiStatus.Internal` marks classes/methods as internal — they still appear in `.api` files but are not part of the public contract.
 - `@ApiStatus.Experimental` marks API that may change in future versions.

.cursor/rules/options.mdc

@@ -112,4 +112,4 @@ When a feature has its own capture path (e.g. `captureLog`), the relevant classe
 4. `ManifestMetadataReader.java` — Android manifest support (if Android-relevant)
 5. `SentryAutoConfigurationTest.kt` — Spring Boot property binding tests (all three Spring Boot modules)
 6. Tests for all of the above (`SentryOptionsTest`, `ExternalOptionsTest`, `ManifestMetadataReaderTest`)
-7. Run `./gradlew apiDump` — the nested class and its methods appear in `sentry.api`
+7. Run `./gradlew updateKotlinAbi` — the nested class and its methods appear in `sentry.api`

AGENTS.md

@@ -9,7 +9,7 @@ rule file in `.cursor/rules/`:
 
 | Rule | Read it when working on |
 |---|---|
-| `api` | Public API surface, binary compatibility, `.api` files, `apiDump`, `IScope`/`IScopes`/`Sentry` static API, protocol classes |
+| `api` | Public API surface, binary compatibility, `.api` files, `updateKotlinAbi`, `IScope`/`IScopes`/`Sentry` static API, protocol classes |
 | `options` | `SentryOptions`, namespaced options, `ExternalOptions`, `sentry.properties`, `ManifestMetadataReader`, Spring Boot properties |
 | `scopes` | Scope management, forking, lifecycle, `ScopeType`, thread-local storage, scope bleeding, Hub → Scopes migration |
 | `deduplication` | Duplicate event detection, `DuplicateEventDetectionEventProcessor`, `enableDeduplication` |
@@ -42,7 +42,7 @@ The project uses **Gradle** with Kotlin DSL. Key build files:
 
 ```bash
 # Format code and regenerate .api files (REQUIRED before committing)
-./gradlew spotlessApply apiDump
+./gradlew spotlessApply updateKotlinAbi
 
 # Run all tests and linter
 ./gradlew check
@@ -74,7 +74,7 @@ resolves the per-module test task, including integration test suites, for you.
 3. **Use todo tracking**: Work through todo items, marking them as complete as you go
 4. **High-level communication**: Give high-level explanations of changes made, not step-by-step descriptions
 5. **Simplicity first**: Make every task and code change as simple as possible. Avoid massive or complex changes. Impact as little code as possible.
-6. **Format and regenerate**: Once done, format code and regenerate .api files: `./gradlew spotlessApply apiDump`
+6. **Format and regenerate**: Once done, format code and regenerate .api files: `./gradlew spotlessApply updateKotlinAbi`
 7. **Propose commit**: As final step, git stage relevant files and propose (but not execute) a single git commit command. This applies to implementation work; when the task is to open a PR, the `create-java-pr` skill takes over from here and does commit, push, and open it.
 
 ## Repository Skills

CONTRIBUTING.md

@@ -81,7 +81,7 @@ or
 
 # Binary compatibility validation
 
-To prevent breaking ABI changes and exposing things we should not, we make use of https://github.com/Kotlin/binary-compatibility-validator. If your change intended to introduce a new public method/property or modify the existing one you can overwrite the API declarations to make CI happy as follows (overwrites them from scratch):
+To prevent breaking ABI changes and exposing things we should not, we make use of https://kotlinlang.org/docs/gradle-binary-compatibility-validation.html. If your change intended to introduce a new public method/property or modify the existing one you can overwrite the API declarations to make CI happy as follows (overwrites them from scratch):
 
 ```shell
 make api
@@ -90,7 +90,7 @@ make api
 or 
 
 ```shell
-./gradlew apiDump
+./gradlew updateKotlinAbi
 ```
 
 However, if your change did not intend to modify the public API, consider changing the method/property visibility or removing the change altogether.

Makefile

@@ -32,7 +32,7 @@ checkFormat:
 
 # Binary compatibility validator
 api:
-	./gradlew apiDump
+	./gradlew updateKotlinAbi
 
 # Assemble release and Android test apk of the uitest-android module
 assembleUiTestRelease:

build-logic/build.gradle.kts

@@ -16,6 +16,10 @@ gradlePlugin {
       id = "io.sentry.jdk-target"
       implementationClass = "io.sentry.gradle.JdkTargetConvention"
     }
+    register("sentryApiValidation") {
+      id = "io.sentry.api-validation"
+      implementationClass = "io.sentry.gradle.SentryApiValidationPlugin"
+    }
     register("sentryAnimalSniffer") {
       id = "io.sentry.animalsniffer"
       implementationClass = "io.sentry.gradle.SentryAnimalSnifferPlugin"

build-logic/src/main/kotlin/io/sentry/gradle/ApiValidationExtension.kt

@@ -0,0 +1,12 @@
+package io.sentry.gradle
+
+import org.gradle.api.provider.SetProperty
+
+/** Configuration for the `io.sentry.api-validation` convention plugin. */
+abstract class ApiValidationExtension {
+  /**
+   * Packages that are public to the JVM but not part of the SDK's API, and so are left out of the
+   * dump. Subpackages are left out too.
+   */
+  abstract val ignoredPackages: SetProperty<String>
+}

build-logic/src/main/kotlin/io/sentry/gradle/SentryApiValidationPlugin.kt

@@ -0,0 +1,47 @@
+package io.sentry.gradle
+
+import org.gradle.api.GradleException
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.api.plugins.ExtensionAware
+import org.gradle.kotlin.dsl.create
+import org.jetbrains.kotlin.gradle.dsl.abi.AbiValidationExtension
+import org.jetbrains.kotlin.gradle.dsl.abi.AbiValidationMultiplatformExtension
+import org.jetbrains.kotlin.gradle.dsl.abi.ExperimentalAbiValidation
+
+private val KOTLIN_PLUGIN_IDS =
+  listOf(
+    "org.jetbrains.kotlin.jvm",
+    "org.jetbrains.kotlin.android",
+    "org.jetbrains.kotlin.multiplatform",
+  )
+
+/**
+ * Checks the public ABI of a module against the dump checked into its `api` directory, using the
+ * Kotlin Gradle plugin's own ABI validation. Adds `checkKotlinAbi`, which `check` depends on, and
+ * `updateKotlinAbi`, which rewrites the dump.
+ */
+@OptIn(ExperimentalAbiValidation::class)
+class SentryApiValidationPlugin : Plugin<Project> {
+  override fun apply(project: Project) {
+    val extension = project.extensions.create<ApiValidationExtension>("sentryApiValidation")
+
+    // The abiValidation extension only exists once a Kotlin plugin has been applied, and a module
+    // may list this plugin before that one.
+    KOTLIN_PLUGIN_IDS.forEach {
+      project.pluginManager.withPlugin(it) { enable(project, extension) }
+    }
+  }
+
+  private fun enable(project: Project, extension: ApiValidationExtension) {
+    val kotlin = project.extensions.getByName("kotlin") as ExtensionAware
+    when (val abi = kotlin.extensions.getByName("abiValidation")) {
+      is AbiValidationMultiplatformExtension -> abi.also { it.enabled.set(true) }
+      is AbiValidationExtension -> abi.also { it.enabled.set(true) }
+      else -> throw GradleException("Unexpected abiValidation extension: ${abi.javaClass.name}")
+    }.filters {
+      // Lazy, because the module configures the extension after this plugin has been applied.
+      exclude { byNames.addAll(extension.ignoredPackages.map { it.map { pkg -> "$pkg.**" } }) }
+    }
+  }
+}