Add incremental validation

Validation is modified when using `useIncrementalValidation=true` to not fail when encountering additions, which are known to be backwards compatible. Instead spits out warnings to allow developers commiting the file early with the changes they have made.

The use case is to pair it with CI-run :check (:apiDump) task and commit updated API after merge - considering all steps are automated. In cases where the API is not compatible, the task fails similarly to `useIncrementalValidation=false` or simply _the default_.

It's acknowledged that using `useIncrementalValidation=true` might cause issues when building upon a feature (or PR) in which cases the .api file might be left out in its previous state, not commited to the VCS. In which case the developer might prefer leaving the option in the default state (false).

To the naked eye it might be apparent that checking only removals (leading `-`) is naive, but since the api diff add two distinct lines for changes (one leading `-`, other `+`), this naive approach proves working for all considered use-cases.

README.md

@@ -90,6 +90,11 @@ apiValidation {
      */
     validationDisabled = true
 
+    /**
+     * Flag to allow incremental validation, ie. apiCheck task will not fail for incremental changes.
+     */
+    useIncrementalValidation = true
+
     /**
      * A path to a subdirectory inside the project root directory where dumps should be stored.
      */
@@ -129,6 +134,11 @@ apiValidation {
      */
     validationDisabled = false
 
+    /**
+     * Flag to allow incremental validation, ie. apiCheck task will not fail for incremental changes.
+     */
+    useIncrementalValidation = true
+
     /**
      * A path to a subdirectory inside the project root directory where dumps should be stored.
      */

api/binary-compatibility-validator.api

@@ -9,6 +9,7 @@ public class kotlinx/validation/ApiValidationExtension {
 	public final fun getPublicClasses ()Ljava/util/Set;
 	public final fun getPublicMarkers ()Ljava/util/Set;
 	public final fun getPublicPackages ()Ljava/util/Set;
+	public final fun getUseIncrementalValidation ()Z
 	public final fun getValidationDisabled ()Z
 	public final fun setAdditionalSourceSets (Ljava/util/Set;)V
 	public final fun setApiDumpDirectory (Ljava/lang/String;)V
@@ -19,6 +20,7 @@ public class kotlinx/validation/ApiValidationExtension {
 	public final fun setPublicClasses (Ljava/util/Set;)V
 	public final fun setPublicMarkers (Ljava/util/Set;)V
 	public final fun setPublicPackages (Ljava/util/Set;)V
+	public final fun setUseIncrementalValidation (Z)V
 	public final fun setValidationDisabled (Z)V
 }
 
@@ -49,9 +51,11 @@ public class kotlinx/validation/KotlinApiCompareTask : org/gradle/api/DefaultTas
 	public fun <init> (Lorg/gradle/api/model/ObjectFactory;)V
 	public final fun getApiBuildDir ()Ljava/io/File;
 	public final fun getDummyOutputFile ()Ljava/io/File;
+	public final fun getIncremental ()Z
 	public final fun getNonExistingProjectApiDir ()Ljava/lang/String;
 	public final fun getProjectApiDir ()Ljava/io/File;
 	public final fun setApiBuildDir (Ljava/io/File;)V
+	public final fun setIncremental (Z)V
 	public final fun setNonExistingProjectApiDir (Ljava/lang/String;)V
 	public final fun setProjectApiDir (Ljava/io/File;)V
 }

src/functionalTest/kotlin/kotlinx/validation/test/IncrementalTest.kt

@@ -0,0 +1,149 @@
+/*
+ * Copyright 2016-2024 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 kotlinx.validation.test
+
+import kotlinx.validation.api.*
+import org.junit.*
+
+class IncrementalTest : BaseKotlinGradleTest() {
+
+    @Test
+    fun `fails when removing source lines`() {
+        val runner = test {
+            buildGradleKts {
+                resolve("/examples/gradle/base/withPlugin.gradle.kts")
+                resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
+            }
+            kotlin("IncrementalBase.kt") {
+                resolve("/examples/classes/IncrementalRemoval.kt")
+            }
+            apiFile(rootProjectDir.name) {
+                resolve("/examples/classes/Incremental.dump")
+            }
+            runner {
+                arguments.add(":apiCheck")
+            }
+        }
+        runner.buildAndFail().apply {
+            assertTaskFailure(":apiCheck")
+        }
+    }
+
+    @Test
+    fun `fails when modifying source lines`() {
+        val runner = test {
+            buildGradleKts {
+                resolve("/examples/gradle/base/withPlugin.gradle.kts")
+                resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
+            }
+            kotlin("IncrementalBase.kt") {
+                resolve("/examples/classes/IncrementalModification.kt")
+            }
+            apiFile(rootProjectDir.name) {
+                resolve("/examples/classes/Incremental.dump")
+            }
+            runner {
+                arguments.add(":apiCheck")
+            }
+        }
+        runner.buildAndFail().apply {
+            assertTaskFailure(":apiCheck")
+        }
+    }
+
+    @Test
+    fun `succeeds when adding source lines`() {
+        val runner = test {
+            buildGradleKts {
+                resolve("/examples/gradle/base/withPlugin.gradle.kts")
+                resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
+            }
+            kotlin("IncrementalBase.kt") {
+                resolve("/examples/classes/IncrementalAddition.kt")
+            }
+            apiFile(rootProjectDir.name) {
+                resolve("/examples/classes/Incremental.dump")
+            }
+            runner {
+                arguments.add(":apiCheck")
+            }
+        }
+        runner.build().apply {
+            assertTaskSuccess(":apiCheck")
+        }
+    }
+
+    @Test
+    fun `does not dump when removing source lines`() {
+        val runner = test {
+            buildGradleKts {
+                resolve("/examples/gradle/base/withPlugin.gradle.kts")
+                resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
+            }
+            kotlin("IncrementalBase.kt") {
+                resolve("/examples/classes/IncrementalRemoval.kt")
+            }
+            apiFile(rootProjectDir.name) {
+                resolve("/examples/classes/Incremental.dump")
+            }
+            runner {
+                arguments.add(":apiCheck")
+            }
+        }
+        runner.buildAndFail().apply {
+            assertTaskFailure(":apiCheck")
+            assertTaskNotRun(":apiDump")
+        }
+    }
+
+    @Test
+    fun `does not dump when modifying source lines`() {
+        val runner = test {
+            buildGradleKts {
+                resolve("/examples/gradle/base/withPlugin.gradle.kts")
+                resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
+            }
+            kotlin("IncrementalBase.kt") {
+                resolve("/examples/classes/IncrementalModification.kt")
+            }
+            apiFile(rootProjectDir.name) {
+                resolve("/examples/classes/Incremental.dump")
+            }
+            runner {
+                arguments.add(":apiCheck")
+            }
+        }
+        runner.buildAndFail().apply {
+            assertTaskFailure(":apiCheck")
+            assertTaskNotRun(":apiDump")
+        }
+    }
+
+    @Ignore
+    @Test
+    fun `updates dump when adding source lines`() {
+        val runner = test {
+            buildGradleKts {
+                resolve("/examples/gradle/base/withPlugin.gradle.kts")
+                resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
+            }
+            kotlin("IncrementalBase.kt") {
+                resolve("/examples/classes/IncrementalAddition.kt")
+            }
+            apiFile(rootProjectDir.name) {
+                resolve("/examples/classes/Incremental.dump")
+            }
+            runner {
+                arguments.add(":apiCheck")
+            }
+        }
+        runner.build().apply {
+            assertTaskSuccess(":apiCheck")
+            assertTaskSuccess(":apiDump")
+        }
+    }
+
+}

src/functionalTest/resources/examples/classes/Incremental.dump

@@ -0,0 +1,16 @@
+public final class foo/Incremental {
+	public fun <init> (Ljava/lang/Object;)V
+	public final fun component1 ()Ljava/lang/Object;
+	public final fun copy (Ljava/lang/Object;)Lfoo/Incremental;
+	public static synthetic fun copy$default (Lfoo/Incremental;Ljava/lang/Object;ILjava/lang/Object;)Lfoo/Incremental;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getId ()Ljava/lang/Object;
+	public fun hashCode ()I
+	public final fun integer ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class foo/IncrementalBaseKt {
+	public static final fun getId ()Ljava/lang/Object;
+	public static final fun sum ([I)I
+}

src/functionalTest/resources/examples/classes/IncrementalAddition.kt

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2016-2024 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 foo
+
+data class Incremental(val id: Any) {
+    fun integer() = 42
+    fun double() = 4.2
+}
+
+fun sum(vararg integers: Int) = integers.sum()
+fun mus(vararg integers: Int) = integers.sum()
+
+val id: Any = 42
+val id2: Any = 24

src/functionalTest/resources/examples/classes/IncrementalBase.kt

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2016-2024 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 foo
+
+data class Incremental(val id: Any) {
+    fun integer() = 42
+}
+
+fun sum(vararg integers: Int) = integers.sum()
+
+val id: Any = 42

src/functionalTest/resources/examples/classes/IncrementalModification.kt

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2016-2024 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 foo
+
+data class Incremental(val id: String) {
+    fun integer() = 42.0
+}
+
+fun sumOfInts(vararg integers: Int) = integers.sum()
+
+val id: Int = 42

src/functionalTest/resources/examples/classes/IncrementalRemoval.kt

@@ -0,0 +1,8 @@
+/*
+ * Copyright 2016-2024 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 foo
+
+class Incremental

src/functionalTest/resources/examples/gradle/configuration/incremental/incremental.gradle.kts

@@ -0,0 +1,8 @@
+/*
+ * Copyright 2016-2024 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.
+ */
+
+configure<kotlinx.validation.ApiValidationExtension> {
+    useIncrementalValidation = true
+}

src/main/kotlin/ApiValidationExtension.kt

@@ -12,6 +12,12 @@ public open class ApiValidationExtension {
      */
     public var validationDisabled: Boolean = false
 
+    /**
+     * Replaces hard errors during validation with warnings if only additions have been made since the last public API
+     * snapshot. This can prove useful when publishing incremental API changes without additional human interaction.
+     */
+    public var useIncrementalValidation: Boolean = false
+
     /**
      * Fully qualified package names that are not consider public API.
      * For example, it could be `kotlinx.coroutines.internal` or `kotlinx.serialization.implementation`.
@@ -36,17 +42,17 @@ public open class ApiValidationExtension {
     public var ignoredClasses: MutableSet<String> = HashSet()
 
     /**
-     * Fully qualified names of annotations that can be used to explicitly mark public declarations. 
+     * Fully qualified names of annotations that can be used to explicitly mark public declarations.
      * If at least one of [publicMarkers], [publicPackages] or [publicClasses] is defined,
-     * all declarations not covered by any of them will be considered non-public. 
+     * all declarations not covered by any of them will be considered non-public.
      * [ignoredPackages], [ignoredClasses] and [nonPublicMarkers] can be used for additional filtering.
      */
     public var publicMarkers: MutableSet<String> = HashSet()
 
     /**
-     * Fully qualified package names that contain public declarations. 
+     * Fully qualified package names that contain public declarations.
      * If at least one of [publicMarkers], [publicPackages] or [publicClasses] is defined,
-     * all declarations not covered by any of them will be considered non-public. 
+     * all declarations not covered by any of them will be considered non-public.
      * [ignoredPackages], [ignoredClasses] and [nonPublicMarkers] can be used for additional filtering.
      */
     public var publicPackages: MutableSet<String> = HashSet()

src/main/kotlin/BinaryCompatibilityValidatorPlugin.kt

@@ -274,6 +274,7 @@ private fun Project.configureCheckTasks(
         isEnabled = apiCheckEnabled(projectName, extension) && apiBuild.map { it.enabled }.getOrElse(true)
         group = "verification"
         description = "Checks signatures of public API against the golden value in API folder for $projectName"
+        incremental = extension.useIncrementalValidation
         compareApiDumps(apiReferenceDir = apiCheckDir.get(), apiBuildDir = apiBuildDir.get())
         dependsOn(apiBuild)
     }

src/main/kotlin/IncrementalVerification.kt

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2016-2024 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 kotlinx.validation
+
+import org.gradle.api.logging.Logger
+
+internal class IncrementalVerification(private val subject: String, private val logger: Logger): Verification {
+    override fun verify(diffSet: Collection<String>) {
+        var containsAdditions = false
+        var containsRemovals = false
+        out@ for (diff in diffSet) {
+            for (line in diff.split("\n")) {
+                when {
+                    line.startsWith("+++") || line.startsWith("---") -> continue
+                    line.startsWith("-") -> containsRemovals = true
+                    line.startsWith("+") -> containsAdditions = true
+                }
+                if (containsRemovals) break@out
+            }
+        }
+        check(!containsRemovals) {
+            val diffText = diffSet.joinToString("\n\n")
+            "Incremental API check failed for project $subject.\n$diffText\n\n You can run :$subject:apiDump task to overwrite API declarations. These changes likely break compatibility with existing consumers using library '$subject', consider incrementing major version code for your next release"
+        }
+        if (containsAdditions) {
+            logger.warn("API is incrementally compatible with previous version, however is not identical to the API file provided.")
+        }
+    }
+}