Skip to content

Commit 890c116

Browse files
diareusediareuse
committed
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.
1 parent 10f8e7e commit 890c116

15 files changed

+322
-15
lines changed

‎README.md

+10
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,11 @@ apiValidation {
9292
*/
9393
validationDisabled = true
9494
95+
/**
96+
* Flag to allow incremental validation, ie. apiCheck task will not fail for incremental changes.
97+
*/
98+
useIncrementalValidation = true
99+
95100
/**
96101
* A path to a subdirectory inside the project root directory where dumps should be stored.
97102
*/
@@ -131,6 +136,11 @@ apiValidation {
131136
*/
132137
validationDisabled = false
133138

139+
/**
140+
* Flag to allow incremental validation, ie. apiCheck task will not fail for incremental changes.
141+
*/
142+
useIncrementalValidation = true
143+
134144
/**
135145
* A path to a subdirectory inside the project root directory where dumps should be stored.
136146
*/

‎api/binary-compatibility-validator.api

+4
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ public class kotlinx/validation/ApiValidationExtension {
1010
public final fun getPublicClasses ()Ljava/util/Set;
1111
public final fun getPublicMarkers ()Ljava/util/Set;
1212
public final fun getPublicPackages ()Ljava/util/Set;
13+
public final fun getUseIncrementalValidation ()Z
1314
public final fun getValidationDisabled ()Z
1415
public final fun klib (Lkotlin/jvm/functions/Function1;)V
1516
public final fun setAdditionalSourceSets (Ljava/util/Set;)V
@@ -21,6 +22,7 @@ public class kotlinx/validation/ApiValidationExtension {
2122
public final fun setPublicClasses (Ljava/util/Set;)V
2223
public final fun setPublicMarkers (Ljava/util/Set;)V
2324
public final fun setPublicPackages (Ljava/util/Set;)V
25+
public final fun setUseIncrementalValidation (Z)V
2426
public final fun setValidationDisabled (Z)V
2527
}
2628

@@ -79,8 +81,10 @@ public class kotlinx/validation/KotlinApiCompareTask : org/gradle/api/DefaultTas
7981
public field generatedApiFile Ljava/io/File;
8082
public field projectApiFile Ljava/io/File;
8183
public fun <init> (Lorg/gradle/api/model/ObjectFactory;)V
84+
public final fun getIncremental ()Z
8285
public final fun getGeneratedApiFile ()Ljava/io/File;
8386
public final fun getProjectApiFile ()Ljava/io/File;
87+
public final fun setIncremental (Z)V
8488
public final fun setGeneratedApiFile (Ljava/io/File;)V
8589
public final fun setProjectApiFile (Ljava/io/File;)V
8690
}

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

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
/*
2+
* Copyright 2016-2024 JetBrains s.r.o.
3+
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
4+
*/
5+
6+
package kotlinx.validation.test
7+
8+
import kotlinx.validation.api.*
9+
import org.junit.*
10+
11+
class IncrementalTest : BaseKotlinGradleTest() {
12+
13+
@Test
14+
fun `fails when removing source lines`() {
15+
val runner = test {
16+
buildGradleKts {
17+
resolve("/examples/gradle/base/withPlugin.gradle.kts")
18+
resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
19+
}
20+
kotlin("IncrementalBase.kt") {
21+
resolve("/examples/classes/IncrementalRemoval.kt")
22+
}
23+
apiFile(rootProjectDir.name) {
24+
resolve("/examples/classes/Incremental.dump")
25+
}
26+
runner {
27+
arguments.add(":apiCheck")
28+
}
29+
}
30+
runner.buildAndFail().apply {
31+
assertTaskFailure(":apiCheck")
32+
}
33+
}
34+
35+
@Test
36+
fun `fails when modifying source lines`() {
37+
val runner = test {
38+
buildGradleKts {
39+
resolve("/examples/gradle/base/withPlugin.gradle.kts")
40+
resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
41+
}
42+
kotlin("IncrementalBase.kt") {
43+
resolve("/examples/classes/IncrementalModification.kt")
44+
}
45+
apiFile(rootProjectDir.name) {
46+
resolve("/examples/classes/Incremental.dump")
47+
}
48+
runner {
49+
arguments.add(":apiCheck")
50+
}
51+
}
52+
runner.buildAndFail().apply {
53+
assertTaskFailure(":apiCheck")
54+
}
55+
}
56+
57+
@Test
58+
fun `succeeds when adding source lines`() {
59+
val runner = test {
60+
buildGradleKts {
61+
resolve("/examples/gradle/base/withPlugin.gradle.kts")
62+
resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
63+
}
64+
kotlin("IncrementalBase.kt") {
65+
resolve("/examples/classes/IncrementalAddition.kt")
66+
}
67+
apiFile(rootProjectDir.name) {
68+
resolve("/examples/classes/Incremental.dump")
69+
}
70+
runner {
71+
arguments.add(":apiCheck")
72+
}
73+
}
74+
runner.build().apply {
75+
assertTaskSuccess(":apiCheck")
76+
}
77+
}
78+
79+
@Test
80+
fun `does not dump when removing source lines`() {
81+
val runner = test {
82+
buildGradleKts {
83+
resolve("/examples/gradle/base/withPlugin.gradle.kts")
84+
resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
85+
}
86+
kotlin("IncrementalBase.kt") {
87+
resolve("/examples/classes/IncrementalRemoval.kt")
88+
}
89+
apiFile(rootProjectDir.name) {
90+
resolve("/examples/classes/Incremental.dump")
91+
}
92+
runner {
93+
arguments.add(":apiCheck")
94+
}
95+
}
96+
runner.buildAndFail().apply {
97+
assertTaskFailure(":apiCheck")
98+
assertTaskNotRun(":apiDump")
99+
}
100+
}
101+
102+
@Test
103+
fun `does not dump when modifying source lines`() {
104+
val runner = test {
105+
buildGradleKts {
106+
resolve("/examples/gradle/base/withPlugin.gradle.kts")
107+
resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
108+
}
109+
kotlin("IncrementalBase.kt") {
110+
resolve("/examples/classes/IncrementalModification.kt")
111+
}
112+
apiFile(rootProjectDir.name) {
113+
resolve("/examples/classes/Incremental.dump")
114+
}
115+
runner {
116+
arguments.add(":apiCheck")
117+
}
118+
}
119+
runner.buildAndFail().apply {
120+
assertTaskFailure(":apiCheck")
121+
assertTaskNotRun(":apiDump")
122+
}
123+
}
124+
125+
@Ignore
126+
@Test
127+
fun `updates dump when adding source lines`() {
128+
val runner = test {
129+
buildGradleKts {
130+
resolve("/examples/gradle/base/withPlugin.gradle.kts")
131+
resolve("/examples/gradle/configuration/incremental/incremental.gradle.kts")
132+
}
133+
kotlin("IncrementalBase.kt") {
134+
resolve("/examples/classes/IncrementalAddition.kt")
135+
}
136+
apiFile(rootProjectDir.name) {
137+
resolve("/examples/classes/Incremental.dump")
138+
}
139+
runner {
140+
arguments.add(":apiCheck")
141+
}
142+
}
143+
runner.build().apply {
144+
assertTaskSuccess(":apiCheck")
145+
assertTaskSuccess(":apiDump")
146+
}
147+
}
148+
149+
}

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

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
public final class foo/Incremental {
2+
public fun <init> (Ljava/lang/Object;)V
3+
public final fun component1 ()Ljava/lang/Object;
4+
public final fun copy (Ljava/lang/Object;)Lfoo/Incremental;
5+
public static synthetic fun copy$default (Lfoo/Incremental;Ljava/lang/Object;ILjava/lang/Object;)Lfoo/Incremental;
6+
public fun equals (Ljava/lang/Object;)Z
7+
public final fun getId ()Ljava/lang/Object;
8+
public fun hashCode ()I
9+
public final fun integer ()I
10+
public fun toString ()Ljava/lang/String;
11+
}
12+
13+
public final class foo/IncrementalBaseKt {
14+
public static final fun getId ()Ljava/lang/Object;
15+
public static final fun sum ([I)I
16+
}

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

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
/*
2+
* Copyright 2016-2024 JetBrains s.r.o.
3+
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
4+
*/
5+
6+
package foo
7+
8+
data class Incremental(val id: Any) {
9+
fun integer() = 42
10+
fun double() = 4.2
11+
}
12+
13+
fun sum(vararg integers: Int) = integers.sum()
14+
fun mus(vararg integers: Int) = integers.sum()
15+
16+
val id: Any = 42
17+
val id2: Any = 24

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

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/*
2+
* Copyright 2016-2024 JetBrains s.r.o.
3+
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
4+
*/
5+
6+
package foo
7+
8+
data class Incremental(val id: Any) {
9+
fun integer() = 42
10+
}
11+
12+
fun sum(vararg integers: Int) = integers.sum()
13+
14+
val id: Any = 42

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

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/*
2+
* Copyright 2016-2024 JetBrains s.r.o.
3+
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
4+
*/
5+
6+
package foo
7+
8+
data class Incremental(val id: String) {
9+
fun integer() = 42.0
10+
}
11+
12+
fun sumOfInts(vararg integers: Int) = integers.sum()
13+
14+
val id: Int = 42

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

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
/*
2+
* Copyright 2016-2024 JetBrains s.r.o.
3+
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
4+
*/
5+
6+
package foo
7+
8+
class Incremental

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

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
/*
2+
* Copyright 2016-2024 JetBrains s.r.o.
3+
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
4+
*/
5+
6+
configure<kotlinx.validation.ApiValidationExtension> {
7+
useIncrementalValidation = true
8+
}

‎src/main/kotlin/ApiValidationExtension.kt

+10-4
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,12 @@ public open class ApiValidationExtension {
1414
*/
1515
public var validationDisabled: Boolean = false
1616

17+
/**
18+
* Replaces hard errors during validation with warnings if only additions have been made since the last public API
19+
* snapshot. This can prove useful when publishing incremental API changes without additional human interaction.
20+
*/
21+
public var useIncrementalValidation: Boolean = false
22+
1723
/**
1824
* Fully qualified package names that are not consider public API.
1925
* For example, it could be `kotlinx.coroutines.internal` or `kotlinx.serialization.implementation`.
@@ -38,17 +44,17 @@ public open class ApiValidationExtension {
3844
public var ignoredClasses: MutableSet<String> = HashSet()
3945

4046
/**
41-
* Fully qualified names of annotations that can be used to explicitly mark public declarations.
47+
* Fully qualified names of annotations that can be used to explicitly mark public declarations.
4248
* If at least one of [publicMarkers], [publicPackages] or [publicClasses] is defined,
43-
* all declarations not covered by any of them will be considered non-public.
49+
* all declarations not covered by any of them will be considered non-public.
4450
* [ignoredPackages], [ignoredClasses] and [nonPublicMarkers] can be used for additional filtering.
4551
*/
4652
public var publicMarkers: MutableSet<String> = HashSet()
4753

4854
/**
49-
* Fully qualified package names that contain public declarations.
55+
* Fully qualified package names that contain public declarations.
5056
* If at least one of [publicMarkers], [publicPackages] or [publicClasses] is defined,
51-
* all declarations not covered by any of them will be considered non-public.
57+
* all declarations not covered by any of them will be considered non-public.
5258
* [ignoredPackages], [ignoredClasses] and [nonPublicMarkers] can be used for additional filtering.
5359
*/
5460
public var publicPackages: MutableSet<String> = HashSet()

‎src/main/kotlin/BinaryCompatibilityValidatorPlugin.kt

+1
Original file line numberDiff line numberDiff line change
@@ -305,6 +305,7 @@ private fun Project.configureCheckTasks(
305305
isEnabled = apiCheckEnabled(projectName, extension) && apiBuild.map { it.enabled }.getOrElse(true)
306306
group = "verification"
307307
description = "Checks signatures of public API against the golden value in API folder for $projectName"
308+
incremental = extension.useIncrementalValidation
308309
projectApiFile = apiCheckDir.get().resolve(jvmDumpFileName)
309310
generatedApiFile = apiBuildDir.get().resolve(jvmDumpFileName)
310311
dependsOn(apiBuild)

‎src/main/kotlin/IncrementalVerification.kt

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
/*
2+
* Copyright 2016-2024 JetBrains s.r.o.
3+
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
4+
*/
5+
6+
package kotlinx.validation
7+
8+
import org.gradle.api.logging.Logger
9+
10+
internal class IncrementalVerification(private val subject: String, private val logger: Logger): Verification {
11+
override fun verify(diffSet: Collection<String>) {
12+
var containsAdditions = false
13+
var containsRemovals = false
14+
out@ for (diff in diffSet) {
15+
for (line in diff.split("\n")) {
16+
when {
17+
line.startsWith("+++") || line.startsWith("---") -> continue
18+
line.startsWith("-") -> containsRemovals = true
19+
line.startsWith("+") -> containsAdditions = true
20+
}
21+
if (containsRemovals) break@out
22+
}
23+
}
24+
check(!containsRemovals) {
25+
val diffText = diffSet.joinToString("\n\n")
26+
"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"
27+
}
28+
if (containsAdditions) {
29+
logger.warn("API is incrementally compatible with previous version, however is not identical to the API file provided.")
30+
}
31+
}
32+
}

0 commit comments

Comments
 (0)