update BCV to 0.13.1 (#7)

- implement explicit-public properties
- tidy up test data
- minor README updates

Author: aSemy

README.md

@@ -3,20 +3,22 @@
 
 # Kotlin Binary Compatibility Validator (Mirror Universe)
 
-[BCV-MU](https://github.com/adamko-dev/kotlin-binary-compatibility-validator-mu) is a
-re-imagined [Gradle](https://gradle.org/) Plugin for
-[Kotlin/binary-compatibility-validator](https://github.com/Kotlin/binary-compatibility-validator).
+[BCV-MU](https://github.com/adamko-dev/kotlin-binary-compatibility-validator-mu)
+is a [Gradle](https://gradle.org/) Plugin that validates the public JVM binary API of libraries, to
+make sure that breaking changes are tracked.
 
-This plugin validates the public JVM binary API of libraries to make sure that breaking changes are
-tracked.
+BCV-MU is based on
+[Kotlin/binary-compatibility-validator](https://github.com/Kotlin/binary-compatibility-validator),
+and contains improvements to better work with the Gradle API, especially in large projects.
 
-Read more in the BCV project:
+Read more about the validation of the public API in the BCV project:
 
 * [What constitutes the public API?](https://github.com/Kotlin/binary-compatibility-validator/#what-constitutes-the-public-api)
 * [What makes an incompatible change to the public binary API?](https://github.com/Kotlin/binary-compatibility-validator/#what-makes-an-incompatible-change-to-the-public-binary-api)
 
-(The [Mirror Universe](https://en.wikipedia.org/wiki/Mirror_Universe) tag was chosen because I hope
-to banish this plugin as soon the improvements here are merged upstream.)
+(The MU tag was chosen because I hope to banish this plugin to the
+[Mirror Universe](https://en.wikipedia.org/wiki/Mirror_Universe)
+as soon the improvements here are merged upstream.)
 
 ### Description
 
@@ -30,7 +32,7 @@ or (**experimentally**) [as a Settings plugin](#settings-plugin) in `settings.gr
 
 The minimal supported Gradle version is 7.6.
 
-By default, BCV-MU uses BCV version `0.13.0`, which can be overridden, but may introduce runtime
+By default, BCV-MU uses BCV version `0.13.1`, which can be overridden, but may introduce runtime
 errors.
 
 ### Build plugin
@@ -75,6 +77,14 @@ plugins {
 }
 
 binaryCompatibilityValidator {
+
+  // Explicitly include specific classes, markers, or packages.
+  // If any class, marker, or package is defined then all other declarations will be excluded.
+  // If no explicit public declarations are defined, then all declarations will be included by default.
+  publicClasses.add("com.company.api.FooPublicClass")
+  publicMarkers.add("com.company.api.ExplicitApiAnnotation")
+  publicPackages.add("com.company.api")
+
   // Packages that are excluded from public API dumps even if they contain public API.
   ignoredPackages.add("kotlinx.coroutines.internal")
   // Classes (fully qualified) that are excluded from public API dumps even if they contain public API.
@@ -88,14 +98,14 @@ binaryCompatibilityValidator {
   bcvEnabled.set(true)
 
   // Override the default BCV version
-  kotlinxBinaryCompatibilityValidatorVersion.set("0.13.0")
+  kotlinxBinaryCompatibilityValidatorVersion.set("0.13.1")
 }
 ```
 
 ##### Advanced configuration
 
-BCV automatically generates 'targets' for each Kotlin/JVM target that it finds.
-These targets can be specifically modified, or manually defined, for fine-grained control.
+BCV automatically generates 'targets' for each Kotlin/JVM source set that it finds.
+these `BCVTarget`s can be specifically modified, or manually defined, for fine-grained control.
 
 ```kotlin
 // build.gradle.kts

gradle/libs.versions.toml

@@ -5,7 +5,7 @@ kotlinGradle = "1.6.0"
 javaDiffUtils = "4.12"
 junit = "5.9.2"
 kotest = "5.5.5"
-kotlinx-bcv = "0.13.0"
+kotlinx-bcv = "0.13.1"
 
 gradlePluginPublishPlugin = "1.1.0"
 shadowPlugin = "8.1.0"

modules/bcv-gradle-plugin-functional-tests/build.gradle.kts

@@ -23,7 +23,6 @@ dependencies {
   testFixturesApi(testFixtures(projects.modules.bcvGradlePlugin))
 }
 
-
 @Suppress("UnstableApiUsage")
 testing.suites {
   withType<JvmTestSuite>().configureEach {

modules/bcv-gradle-plugin-functional-tests/src/functionalTest/kotlin/kotlinx/validation/test/JavaTestFixturesTest.kt

@@ -125,7 +125,7 @@ private fun FunSpec.createTestFixturesProject(
     buildGradleKts = """
         |plugins {
         |  kotlin("jvm") version "1.7.10"
-        |  id("dev.adamko.kotlin.binary-compatibility-validator") version "0.0.4-SNAPSHOT"
+        |  id("dev.adamko.kotlin.binary-compatibility-validator") version "0.0.5-SNAPSHOT"
         |  `java-test-fixtures`
         |}
         |

modules/bcv-gradle-plugin-functional-tests/src/functionalTest/kotlin/kotlinx/validation/test/MixedMarkersTest.kt

@@ -0,0 +1,36 @@
+package kotlinx.validation.test
+
+import dev.adamko.kotlin.binary_compatibility_validator.test.utils.api.*
+import dev.adamko.kotlin.binary_compatibility_validator.test.utils.build
+import dev.adamko.kotlin.binary_compatibility_validator.test.utils.shouldHaveTaskWithOutcome
+import org.gradle.testkit.runner.TaskOutcome.SUCCESS
+import org.junit.jupiter.api.Test
+
+class MixedMarkersTest : BaseKotlinGradleTest() {
+
+  @Test
+  fun testMixedMarkers() {
+    val runner = test {
+      buildGradleKts {
+        resolve("/examples/gradle/base/withPlugin.gradle.kts")
+        resolve("/examples/gradle/configuration/publicMarkers/mixedMarkers.gradle.kts")
+      }
+
+      kotlin("MixedAnnotations.kt") {
+        resolve("/examples/classes/MixedAnnotations.kt")
+      }
+
+      apiFile(projectName = rootProjectDir.name) {
+        resolve("/examples/classes/MixedAnnotations.dump")
+      }
+
+      runner {
+        arguments.add(":apiCheck")
+      }
+    }
+
+    runner.build {
+      shouldHaveTaskWithOutcome(":apiCheck", SUCCESS)
+    }
+  }
+}

modules/bcv-gradle-plugin-functional-tests/src/functionalTest/kotlin/kotlinx/validation/test/NonPublicMarkersTest.kt

@@ -2,7 +2,6 @@ package kotlinx.validation.test
 
 import dev.adamko.kotlin.binary_compatibility_validator.test.utils.api.*
 import dev.adamko.kotlin.binary_compatibility_validator.test.utils.build
-import dev.adamko.kotlin.binary_compatibility_validator.test.utils.shouldHaveOutcome
 import dev.adamko.kotlin.binary_compatibility_validator.test.utils.shouldHaveTaskWithOutcome
 import org.gradle.testkit.runner.TaskOutcome.SUCCESS
 import org.junit.jupiter.api.Test

modules/bcv-gradle-plugin-functional-tests/src/functionalTest/kotlin/kotlinx/validation/test/PublicMarkersTest.kt

@@ -0,0 +1,40 @@
+package kotlinx.validation.test
+
+import dev.adamko.kotlin.binary_compatibility_validator.test.utils.api.*
+import dev.adamko.kotlin.binary_compatibility_validator.test.utils.build
+import dev.adamko.kotlin.binary_compatibility_validator.test.utils.shouldHaveTaskWithOutcome
+import org.gradle.testkit.runner.TaskOutcome.SUCCESS
+import org.junit.jupiter.api.Test
+
+class PublicMarkersTest : BaseKotlinGradleTest() {
+
+  @Test
+  fun testPublicMarkers() {
+    val runner = test {
+      buildGradleKts {
+        resolve("/examples/gradle/base/withPlugin.gradle.kts")
+        resolve("/examples/gradle/configuration/publicMarkers/markers.gradle.kts")
+      }
+
+      kotlin("ClassWithPublicMarkers.kt") {
+        resolve("/examples/classes/ClassWithPublicMarkers.kt")
+      }
+
+      kotlin("ClassInPublicPackage.kt") {
+        resolve("/examples/classes/ClassInPublicPackage.kt")
+      }
+
+      apiFile(projectName = rootProjectDir.name) {
+        resolve("/examples/classes/ClassWithPublicMarkers.dump")
+      }
+
+      runner {
+        arguments.add(":apiCheck")
+      }
+    }
+
+    runner.build {
+      shouldHaveTaskWithOutcome(":apiCheck", SUCCESS)
+    }
+  }
+}

modules/bcv-gradle-plugin-functional-tests/src/functionalTest/kotlin/kotlinx/validation/test/SettingsPluginDslTest.kt

@@ -154,7 +154,7 @@ buildscript {
 
 
 plugins {
-  id("dev.adamko.kotlin.binary-compatibility-validator") version "0.0.4-SNAPSHOT"
+  id("dev.adamko.kotlin.binary-compatibility-validator") version "0.0.5-SNAPSHOT"
 }
 
 include(

modules/bcv-gradle-plugin-functional-tests/src/functionalTest/resources/examples/classes/AnotherBuildConfig.kt

@@ -1,12 +1,7 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o.
- * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
- */
-
 package org.different.pack
 
 public class BuildConfig {
-    public val p1 = 1
+  public val p1 = 1
 
-    public fun f1() = p1
-}
+  public fun f1() = p1
+}

modules/bcv-gradle-plugin-functional-tests/src/functionalTest/resources/examples/classes/BuildConfig.kt

@@ -1,12 +1,7 @@
-/*
- * Copyright 2016-2020 JetBrains s.r.o.
- * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
- */
-
 package com.company
 
 public class BuildConfig {
-    public val property = 1
+  public val property = 1
 
-    public fun function() = property
-}
+  public fun function() = property
+}