Introduce 'nonPublicMarkers' configuration to exclude API that is effectively non-public from API dump

Co-authored-by: ilya-g <ilya.gorbunov@jetbrains.com>

Fixes #17

Author: qwwdfsad

README.md

@@ -63,6 +63,18 @@ apiValidation {
      * Sub-projects that are excluded from API validation 
      */
     ignoredProjects += ["benchmarks", "examples"]
+    
+    /**
+     * Set of annotations that exclude API from being public.
+     * Typically, it is all kinds of `@InternalApi` annotations that mark 
+     * effectively private API that cannot be actually private for technical reasons.
+     */
+    nonPublicMarkers += ["my.package.MyInternalApiAnnotation"]
+
+    /**
+     * Flag to programmatically disable compatibility validator
+     */
+    validationDisabled = true
 }
 ```
 

src/main/kotlin/ApiValidationExtension.kt

@@ -22,4 +22,10 @@ open class ApiValidationExtension {
      * Projects that are ignored by the API check.
      */
     public var ignoredProjects: MutableSet<String> = HashSet()
+
+    /**
+     * Fully qualified names of annotations that effectively exclude declarations from being public.
+     * Example of such annotation could be `kotlinx.coroutines.InternalCoroutinesApi`.
+     */
+    public var nonPublicMarkers: MutableSet<String> = HashSet()
 }

src/main/kotlin/ExternalApi.kt

@@ -6,7 +6,7 @@
 package kotlinx.validation
 
 /**
- * API that is used externally and programmatically by Kotlin standard library
+ * API that is used externally and programmatically by binary-compatibility-validator tool in Kotlin standard library
  */
 @Retention(AnnotationRetention.SOURCE)
-annotation class ExternalApi
+annotation class ExternalApi

src/main/kotlin/KotlinApiBuildTask.kt

@@ -40,6 +40,7 @@ open class KotlinApiBuildTask : DefaultTask() {
             .map { it.inputStream() }
             .loadApiFromJvmClasses()
             .filterOutNonPublic(extension.ignoredPackages)
+            .filterOutAnnotated(extension.nonPublicMarkers.map { it.replace(".", "/") }.toSet())
 
         outputApiDir.resolve("${project.name}.api").bufferedWriter().use { writer ->
             signatures

src/main/kotlin/api/AsmMetadataLoading.kt

@@ -6,7 +6,7 @@
 package kotlinx.validation.api
 
 import kotlinx.metadata.jvm.*
-import org.objectweb.asm.Opcodes
+import org.objectweb.asm.*
 import org.objectweb.asm.tree.*
 
 val ACCESS_NAMES = mapOf(
@@ -70,8 +70,14 @@ private fun List<Any>.annotationValue(key: String): Any? {
     return null
 }
 
-private fun findAnnotation(annotationName: String, visibleAnnotations: List<AnnotationNode>?, invisibleAnnotations: List<AnnotationNode>?, includeInvisible: Boolean): AnnotationNode? =
+private fun findAnnotation(
+    annotationName: String,
+    visibleAnnotations: List<AnnotationNode>?,
+    invisibleAnnotations: List<AnnotationNode>?,
+    includeInvisible: Boolean
+): AnnotationNode? =
     visibleAnnotations?.firstOrNull { it.refersToName(annotationName) }
-            ?: if (includeInvisible) invisibleAnnotations?.firstOrNull { it.refersToName(annotationName) } else null
+        ?: if (includeInvisible) invisibleAnnotations?.firstOrNull { it.refersToName(annotationName) } else null
 
-fun AnnotationNode.refersToName(name: String) = desc.startsWith('L') && desc.endsWith(';') && desc.regionMatches(1, name, 0, name.length)
+fun AnnotationNode.refersToName(name: String) =
+    desc.startsWith('L') && desc.endsWith(';') && desc.regionMatches(1, name, 0, name.length)

src/main/kotlin/api/KotlinMetadataSignature.kt

@@ -7,8 +7,7 @@ package kotlinx.validation.api
 
 import kotlinx.metadata.jvm.*
 import kotlinx.validation.*
-import org.objectweb.asm.tree.FieldNode
-import org.objectweb.asm.tree.MethodNode
+import org.objectweb.asm.tree.*
 
 @ExternalApi // Only name is part of the API, nothing else is used by stdlib
 data class ClassBinarySignature(
@@ -19,7 +18,8 @@ data class ClassBinarySignature(
     val memberSignatures: List<MemberBinarySignature>,
     val access: AccessFlags,
     val isEffectivelyPublic: Boolean,
-    val isNotUsedWhenEmpty: Boolean
+    val isNotUsedWhenEmpty: Boolean,
+    val annotations: List<AnnotationNode>
 ) {
     val signature: String
         get() = "${access.getModifierString()} class $name" + if (supertypes.isEmpty()) "" else " : ${supertypes.joinToString()}"
@@ -31,6 +31,7 @@ interface MemberBinarySignature {
     val desc: String get() = jvmMember.desc
     val access: AccessFlags
     val isPublishedApi: Boolean
+    val annotations: List<AnnotationNode>
 
     fun isEffectivelyPublic(classAccess: AccessFlags, classVisibility: ClassVisibility?) =
         access.isPublic && !(access.isProtected && classAccess.isFinal)
@@ -46,7 +47,8 @@ interface MemberBinarySignature {
 data class MethodBinarySignature(
     override val jvmMember: JvmMethodSignature,
     override val isPublishedApi: Boolean,
-    override val access: AccessFlags
+    override val access: AccessFlags,
+    override val annotations: List<AnnotationNode>
 ) : MemberBinarySignature {
     override val signature: String
         get() = "${access.getModifierString()} fun $name $desc"
@@ -87,12 +89,17 @@ data class MethodBinarySignature(
 }
 
 fun MethodNode.toMethodBinarySignature() =
-        MethodBinarySignature(JvmMethodSignature(name, desc), isPublishedApi(), AccessFlags(access))
+    MethodBinarySignature(
+        JvmMethodSignature(name, desc),
+        isPublishedApi(),
+        AccessFlags(access),
+        annotations(visibleAnnotations, invisibleAnnotations))
 
 data class FieldBinarySignature(
     override val jvmMember: JvmFieldSignature,
     override val isPublishedApi: Boolean,
-    override val access: AccessFlags
+    override val access: AccessFlags,
+    override val annotations: List<AnnotationNode>
 ) : MemberBinarySignature {
     override val signature: String
         get() = "${access.getModifierString()} field $name $desc"
@@ -104,7 +111,11 @@ data class FieldBinarySignature(
 }
 
 fun FieldNode.toFieldBinarySignature() =
-        FieldBinarySignature(JvmFieldSignature(name, desc), isPublishedApi(), AccessFlags(access))
+    FieldBinarySignature(
+        JvmFieldSignature(name, desc),
+        isPublishedApi(),
+        AccessFlags(access),
+        annotations(visibleAnnotations, invisibleAnnotations))
 
 private val MemberBinarySignature.kind: Int
     get() = when (this) {

src/main/kotlin/api/KotlinSignaturesLoading.kt

@@ -8,17 +8,16 @@ package kotlinx.validation.api
 import kotlinx.validation.*
 import org.objectweb.asm.*
 import org.objectweb.asm.tree.*
-import java.io.InputStream
-import java.util.jar.JarFile
-
+import java.io.*
+import java.util.jar.*
 
 @ExternalApi
 @Suppress("unused")
-fun JarFile.loadApiFromJvmClasses(visibilityFilter: (String) -> Boolean = { true }): List<ClassBinarySignature> =
+public fun JarFile.loadApiFromJvmClasses(visibilityFilter: (String) -> Boolean = { true }): List<ClassBinarySignature> =
         classEntries().map { entry -> getInputStream(entry) }.loadApiFromJvmClasses(visibilityFilter)
 
 @ExternalApi
-fun Sequence<InputStream>.loadApiFromJvmClasses(visibilityFilter: (String) -> Boolean = { true }): List<ClassBinarySignature> {
+public fun Sequence<InputStream>.loadApiFromJvmClasses(visibilityFilter: (String) -> Boolean = { true }): List<ClassBinarySignature> {
     val classNodes = map {
         it.use { stream ->
             val classNode = ClassNode()
@@ -46,16 +45,35 @@ fun Sequence<InputStream>.loadApiFromJvmClasses(visibilityFilter: (String) -> Bo
                 ClassBinarySignature(
                     name, superName, outerClassName, supertypes, memberSignatures, classAccess,
                     isEffectivelyPublic(mVisibility),
-                    metadata.isFileOrMultipartFacade() || isDefaultImpls(metadata)
+                    metadata.isFileOrMultipartFacade() || isDefaultImpls(metadata),
+                    annotations(visibleAnnotations, invisibleAnnotations)
                 )
         }}
         .asIterable()
         .sortedBy { it.name }
 }
 
+internal fun List<ClassBinarySignature>.filterOutAnnotated(targetAnnotations: Set<String>): List<ClassBinarySignature> {
+    if (targetAnnotations.isEmpty()) return this
+    return filter {
+        it.annotations.all { ann -> !targetAnnotations.any { ann.refersToName(it) }  }
+    }.map {
+        ClassBinarySignature(
+            it.name,
+            it.superName,
+            it.outerName,
+            it.supertypes,
+            it.memberSignatures.filter { it.annotations.all { ann -> !targetAnnotations.any { ann.refersToName(it) } } },
+            it.access,
+            it.isEffectivelyPublic,
+            it.isNotUsedWhenEmpty,
+            it.annotations
+        )
+    }
+}
 
 @ExternalApi
-fun List<ClassBinarySignature>.filterOutNonPublic(nonPublicPackages: Collection<String> = emptyList()): List<ClassBinarySignature> {
+public fun List<ClassBinarySignature>.filterOutNonPublic(nonPublicPackages: Collection<String> = emptyList()): List<ClassBinarySignature> {
     val nonPublicPaths = nonPublicPackages.map { it.replace('.', '/') + '/' }
     val classByName = associateBy { it.name }
 
@@ -93,10 +111,10 @@ fun List<ClassBinarySignature>.filterOutNonPublic(nonPublicPackages: Collection<
 }
 
 @ExternalApi
-fun List<ClassBinarySignature>.dump() = dump(to = System.out)
+public fun List<ClassBinarySignature>.dump() = dump(to = System.out)
 
 @ExternalApi
-fun <T : Appendable> List<ClassBinarySignature>.dump(to: T): T {
+public fun <T : Appendable> List<ClassBinarySignature>.dump(to: T): T {
     forEach { classApi ->
         with(to) {
             append(classApi.signature).appendln(" {")
@@ -111,4 +129,7 @@ fun <T : Appendable> List<ClassBinarySignature>.dump(to: T): T {
 
 private fun JarFile.classEntries() = Sequence { entries().iterator() }.filter {
     !it.isDirectory && it.name.endsWith(".class") && !it.name.startsWith("META-INF/")
-}
+}
+
+internal fun annotations(l1: List<AnnotationNode>?, l2: List<AnnotationNode>?): List<AnnotationNode> =
+    ((l1 ?: emptyList()) + (l2 ?: emptyList()))