|
| 1 | +import javassist.CtBehavior |
| 2 | +import javassist.CtClass |
| 3 | +import javassist.bytecode.AccessFlag |
| 4 | +import javassist.bytecode.AnnotationsAttribute |
| 5 | +import javassist.bytecode.InnerClassesAttribute |
| 6 | +import javassist.bytecode.annotation.ArrayMemberValue |
| 7 | +import javassist.bytecode.annotation.IntegerMemberValue |
| 8 | +import javassist.bytecode.annotation.StringMemberValue |
| 9 | +import japicmp.model.AccessModifier |
| 10 | +import kotlin.metadata.Attributes |
| 11 | +import kotlin.metadata.Visibility |
| 12 | +import kotlin.metadata.jvm.JvmExtensionsKt |
| 13 | +import kotlin.metadata.jvm.JvmMetadataUtil |
| 14 | +import kotlin.metadata.jvm.KotlinClassMetadata |
| 15 | + |
| 16 | +import java.net.JarURLConnection |
| 17 | + |
| 18 | +// Kotlin compiles internal declarations, lambdas and anonymous objects to public bytecode, and keeps their real visibility |
| 19 | +// only in @kotlin.Metadata. It also marks members that compiled callers still link to as synthetic. Compare only what a |
| 20 | +// compiled Kotlin or Java caller can link to. |
| 21 | + |
| 22 | +class ClassSide { |
| 23 | + boolean ownApi |
| 24 | + String outerName |
| 25 | + Set<String> hidden = [] as Set |
| 26 | + Set<String> apiMembers = [] as Set |
| 27 | +} |
| 28 | + |
| 29 | +def API = [Visibility.PUBLIC, Visibility.PROTECTED] as Set |
| 30 | + |
| 31 | +def readMetadata = { CtClass ctClass -> |
| 32 | + def ann = ctClass.classFile.getAttribute(AnnotationsAttribute.visibleTag)?.getAnnotation('kotlin.Metadata') |
| 33 | + if (ann == null) return null |
| 34 | + def value = { String n -> ann.getMemberValue(n) } |
| 35 | + def ints = { String n -> value(n) == null ? null : (((ArrayMemberValue) value(n)).value.collect { ((IntegerMemberValue) it).value } as int[]) } |
| 36 | + def strs = { String n -> value(n) == null ? null : (((ArrayMemberValue) value(n)).value.collect { ((StringMemberValue) it).value } as String[]) } |
| 37 | + def str = { String n -> value(n) == null ? null : ((StringMemberValue) value(n)).value } |
| 38 | + def i = { String n -> value(n) == null ? null : ((IntegerMemberValue) value(n)).value } |
| 39 | + KotlinClassMetadata.readLenient(JvmMetadataUtil.Metadata(i('k'), ints('mv'), strs('d1'), strs('d2'), str('xs'), str('pn'), i('xi'))) |
| 40 | +} |
| 41 | + |
| 42 | +def outerNameOf = { CtClass ctClass -> |
| 43 | + def inner = (InnerClassesAttribute) ctClass.classFile.getAttribute(InnerClassesAttribute.tag) |
| 44 | + def index = inner == null ? null : (0..<inner.tableLength()).find { inner.innerClass(it) == ctClass.name } |
| 45 | + index == null ? null : inner.outerClass(index) |
| 46 | +} |
| 47 | + |
| 48 | +def isSynthetic = { int accessFlags -> (accessFlags & AccessFlag.SYNTHETIC) != 0 } |
| 49 | + |
| 50 | +def classSide = { CtClass ctClass -> |
| 51 | + def side = new ClassSide(ownApi: !isSynthetic(ctClass.classFile.accessFlags), outerName: outerNameOf(ctClass)) |
| 52 | + def md = readMetadata(ctClass) |
| 53 | + if (md == null) return side |
| 54 | + if (md instanceof KotlinClassMetadata.SyntheticClass) { |
| 55 | + side.ownApi = false |
| 56 | + return side |
| 57 | + } |
| 58 | + def owner = 'L' + ctClass.name.replace('.', '/') + ';' |
| 59 | + // A caller that omits a default argument links to the synthetic name$default bridge, or the synthetic constructor |
| 60 | + // that takes a DefaultConstructorMarker. |
| 61 | + def defaultBridge = { declaration, signature, String receiver, String marker -> |
| 62 | + if (!declaration.valueParameters.any { Attributes.getDeclaresDefaultValue(it) }) return null |
| 63 | + def masks = 'I' * ((declaration.valueParameters.size() + 31).intdiv(32)) |
| 64 | + def params = signature.descriptor.substring(1, signature.descriptor.indexOf(')')) |
| 65 | + def name = signature.name == '<init>' ? '<init>' : signature.name + '$default' |
| 66 | + name + '(' + receiver + params + masks + marker + signature.descriptor.substring(signature.descriptor.indexOf(')')) |
| 67 | + } |
| 68 | + def add = { declaration, signature, String bridge = null -> |
| 69 | + if (signature == null) return |
| 70 | + def api = declaration != null && Attributes.getVisibility(declaration) in API |
| 71 | + if (!api) { |
| 72 | + side.hidden << signature.name + signature.descriptor |
| 73 | + return |
| 74 | + } |
| 75 | + side.apiMembers << signature.name + signature.descriptor |
| 76 | + if (bridge != null) side.apiMembers << bridge |
| 77 | + } |
| 78 | + def addFunctions = { functions, String receiver -> |
| 79 | + functions.each { f -> |
| 80 | + def signature = JvmExtensionsKt.getSignature(f) |
| 81 | + add(f, signature, signature == null ? null : defaultBridge(f, signature, receiver, 'Ljava/lang/Object;')) |
| 82 | + } |
| 83 | + } |
| 84 | + def addProperties = { properties -> |
| 85 | + properties.each { p -> |
| 86 | + add(p.getter, JvmExtensionsKt.getGetterSignature(p)) |
| 87 | + add(p.setter, JvmExtensionsKt.getSetterSignature(p)) |
| 88 | + } |
| 89 | + } |
| 90 | + if (md instanceof KotlinClassMetadata.Class) { |
| 91 | + def km = md.kmClass |
| 92 | + addFunctions(km.functions, owner) |
| 93 | + addProperties(km.properties) |
| 94 | + km.constructors.each { c -> |
| 95 | + def signature = JvmExtensionsKt.getSignature(c) |
| 96 | + add(c, signature, signature == null ? null : defaultBridge(c, signature, '', 'Lkotlin/jvm/internal/DefaultConstructorMarker;')) |
| 97 | + } |
| 98 | + side.ownApi = side.ownApi && Attributes.getVisibility(km) in API |
| 99 | + } |
| 100 | + if (md instanceof KotlinClassMetadata.FileFacade || md instanceof KotlinClassMetadata.MultiFileClassPart) { |
| 101 | + addFunctions(md.kmPackage.functions, '') |
| 102 | + addProperties(md.kmPackage.properties) |
| 103 | + // A file facade holds only top-level declarations, so with none public it has nothing to link to. |
| 104 | + side.ownApi = side.ownApi && !side.apiMembers.isEmpty() |
| 105 | + } |
| 106 | + side |
| 107 | +} |
| 108 | + |
| 109 | +// japicmp passes every class of both jars, filtered only by its options, so no classes means the options filter out the |
| 110 | +// whole jar. |
| 111 | +if (jApiClasses.isEmpty()) { |
| 112 | + throw new IllegalStateException("japicmp-maven-plugin compared no classes, so its <includes> or <excludes> leave out the " + |
| 113 | + "whole jar and no break can fail the build. Remove them. A break planned for the next major gets an <exclude> naming " + |
| 114 | + "that member, with the version set to that major's X.0.0-SNAPSHOT.") |
| 115 | +} |
| 116 | + |
| 117 | +// japicmp hands this script only the classes, so the options come from a class and the version from the pom.properties |
| 118 | +// maven-jar-plugin puts in the jar under comparison. |
| 119 | +def options = jApiClasses.first().@options |
| 120 | +def narrowing = [ |
| 121 | + '<excludes>' : options.filters.excludes*.toString().unique(), |
| 122 | + '<includes>' : options.filters.includes*.toString().unique(), |
| 123 | + '<overrideCompatibilityChangeParameters>': options.overrideCompatibilityChanges.collect { |
| 124 | + "${it.compatibilityChange} binaryCompatible=${it.binaryCompatible}" |
| 125 | + }, |
| 126 | + '<accessModifier>' : options.accessModifier == AccessModifier.PROTECTED ? [] : [options.accessModifier.name()], |
| 127 | + '<includeSynthetic>' : options.includeSynthetic ? [] : ['false'], |
| 128 | +].findAll { name, values -> !values.isEmpty() } |
| 129 | +if (!narrowing.isEmpty()) { |
| 130 | + def newClass = jApiClasses.find { it.newClass.present }.newClass.get() |
| 131 | + def jar = ((JarURLConnection) newClass.classPool.find(newClass.name).openConnection()).jarFile |
| 132 | + def pomProperties = new Properties() |
| 133 | + pomProperties.load(jar.getInputStream(jar.entries().find { it.name.startsWith('META-INF/maven/') && it.name.endsWith('/pom.properties') })) |
| 134 | + def version = pomProperties.getProperty('version') |
| 135 | + if (!(version ==~ /\d+\.0\.0(-SNAPSHOT)?/)) { |
| 136 | + def major = version.substring(0, version.indexOf('.')) |
| 137 | + throw new IllegalStateException("japicmp-maven-plugin narrows the API check at version ${version}, which is not an X.0.0 " + |
| 138 | + "version:\n" + narrowing.collect { name, values -> " ${name}: ${values.join(', ')}" }.join('\n') + |
| 139 | + "\nOnly a major's X.0.0-SNAPSHOT may narrow it, for the breaks that major plans. If these belong to the ${major}.0.0 " + |
| 140 | + "release that just shipped, delete them. Otherwise delete them and keep the old signature as a @Deprecated overload. " + |
| 141 | + "In Kotlin, @Deprecated(level = DeprecationLevel.HIDDEN) keeps it for compiled callers only.") |
| 142 | + } |
| 143 | +} |
| 144 | + |
| 145 | +def info = jApiClasses.collectEntries { c -> |
| 146 | + [c.fullyQualifiedName, [old: c.oldClass.map { classSide(it) }.orElse(null), new: c.newClass.map { classSide(it) }.orElse(null)]] |
| 147 | +} |
| 148 | +// japicmp leaves out classes that aren't public in bytecode, such as a private Kotlin class, so a class whose outer class |
| 149 | +// is missing here is nested in one of those. |
| 150 | +def isApiOn |
| 151 | +isApiOn = { String name, String sideName -> |
| 152 | + def side = info[name]?.get(sideName) |
| 153 | + side != null && side.ownApi && (side.outerName == null || isApiOn(side.outerName, sideName)) |
| 154 | +} |
| 155 | +def isApiClass = { String name -> ['old', 'new'].any { isApiOn(name, it) } } |
| 156 | + |
| 157 | +def memberApiOn = { ClassSide side, String signature, int accessFlags -> |
| 158 | + !(signature in side.hidden) && (!isSynthetic(accessFlags) || signature in side.apiMembers) |
| 159 | +} |
| 160 | +def behaviorApiOn = { ClassSide side, CtBehavior b -> memberApiOn(side, b.methodInfo.name + b.methodInfo.descriptor, b.methodInfo.accessFlags) } |
| 161 | +def isApiBehavior = { d, Optional oldB, Optional newB -> |
| 162 | + oldB.map { behaviorApiOn(d.old, it) }.orElse(false) || newB.map { behaviorApiOn(d.new, it) }.orElse(false) |
| 163 | +} |
| 164 | +def isApiField = { f -> |
| 165 | + f.oldFieldOptional.map { !isSynthetic(it.fieldInfo2.accessFlags) }.orElse(false) || |
| 166 | + f.newFieldOptional.map { !isSynthetic(it.fieldInfo2.accessFlags) }.orElse(false) |
| 167 | +} |
| 168 | + |
| 169 | +// japicmp ignores the list this script returns and reads the one it passed in, so edit that one in place. |
| 170 | +def nonApiClass = { !isApiClass(it.fullyQualifiedName) } |
| 171 | +def droppedClasses = jApiClasses.count(nonApiClass) |
| 172 | +jApiClasses.removeIf(nonApiClass) |
| 173 | +def droppedMembers = 0 |
| 174 | +jApiClasses.each { c -> |
| 175 | + def d = info[c.fullyQualifiedName] |
| 176 | + def nonApiMethod = { !isApiBehavior(d, it.oldMethod, it.newMethod) } |
| 177 | + def nonApiConstructor = { !isApiBehavior(d, it.oldConstructor, it.newConstructor) } |
| 178 | + def nonApiField = { !isApiField(it) } |
| 179 | + droppedMembers += c.methods.count(nonApiMethod) + c.constructors.count(nonApiConstructor) + c.fields.count(nonApiField) |
| 180 | + c.methods.removeIf(nonApiMethod) |
| 181 | + c.constructors.removeIf(nonApiConstructor) |
| 182 | + c.fields.removeIf(nonApiField) |
| 183 | +} |
| 184 | +println "[japicmp-kotlin-public] dropped ${droppedClasses} non-API classes and ${droppedMembers} non-API members" |
| 185 | + |
| 186 | +def breaking = { element -> element.compatibilityChanges.findAll { !it.binaryCompatible }*.type } |
| 187 | +def isDataClass = { CtClass ct -> |
| 188 | + def md = ct == null ? null : readMetadata(ct) |
| 189 | + md instanceof KotlinClassMetadata.Class && Attributes.isData(md.kmClass) |
| 190 | +} |
| 191 | +def problems = [] |
| 192 | +info.each { name, d -> |
| 193 | + if (isApiOn(name, 'old') && d.new != null && !d.new.ownApi) problems << " ${name}: public in the last release, now internal or private in Kotlin" |
| 194 | +} |
| 195 | +jApiClasses.each { c -> |
| 196 | + def name = c.fullyQualifiedName |
| 197 | + def simpleName = name.substring(name.lastIndexOf('.') + 1) |
| 198 | + def lines = [] |
| 199 | + breaking(c).each { lines << " ${name}: ${it}" } |
| 200 | + breaking(c.superclass).each { lines << " ${name} superclass: ${it}" } |
| 201 | + c.interfaces.each { i -> breaking(i).each { lines << " ${name} implements ${i.fullyQualifiedName}: ${it}" } } |
| 202 | + c.constructors.each { m -> breaking(m).each { lines << " ${name}#${simpleName}(${m.parameters*.type.join(', ')}): ${it}" } } |
| 203 | + c.methods.each { m -> breaking(m).each { lines << " ${name}#${m.name}(${m.parameters*.type.join(', ')}): ${it}" } } |
| 204 | + c.fields.each { f -> breaking(f).each { lines << " ${name}#${f.name}: ${it}" } } |
| 205 | + if (lines.isEmpty()) return |
| 206 | + problems.addAll(lines) |
| 207 | + if (isDataClass(c.oldClass.orElse(null)) && c.methods.any { it.name.startsWith('copy') && !breaking(it).isEmpty() }) { |
| 208 | + problems << " -> ${name} is a Kotlin data class, so a new or changed property changes its constructor and copy() for " + |
| 209 | + "compiled callers. Keep the old copy() as a @Deprecated(level = DeprecationLevel.HIDDEN) overload with the same " + |
| 210 | + "default arguments that forwards to the new one, and keep the old constructor with @JvmOverloads or a secondary constructor." |
| 211 | + } else if (lines.any { it.contains('$default(') || it.contains('kotlin.jvm.internal.DefaultConstructorMarker)') }) { |
| 212 | + problems << " -> A name\$default method or a constructor ending in DefaultConstructorMarker is what Kotlin callers link to when " + |
| 213 | + "they leave out a default argument. Keep the default argument. If the parameters changed, keep the old signature as a " + |
| 214 | + "@Deprecated(level = DeprecationLevel.HIDDEN) overload with the same default arguments." |
| 215 | + } |
| 216 | +} |
| 217 | +if (!problems.isEmpty()) { |
| 218 | + throw new IllegalStateException("Binary-incompatible change to the public API since the last release:\n" + problems.join('\n') + |
| 219 | + "\nCode compiled against the last release fails with NoSuchMethodError or a similar linkage error. Keep the old signature " + |
| 220 | + "as a @Deprecated overload. In Kotlin, @Deprecated(level = DeprecationLevel.HIDDEN) keeps it for compiled callers only. " + |
| 221 | + "If the break is planned for the next major, set the version in pom.xml to that major's X.0.0-SNAPSHOT and add the text " + |
| 222 | + "before the colon as an <exclude> under <parameter><excludes> of japicmp-maven-plugin, with a TODO comment naming that major.") |
| 223 | +} |
| 224 | +jApiClasses |
0 commit comments