Skip to content

Commit ef6cb85

Browse files
authored
Merge pull request #947 from graphql-java-kickstart/agent-friendly-p3-api-jar-checks
Check the binary API and the packaged jar in mvn verify
2 parents d754faa + 9c15610 commit ef6cb85

4 files changed

Lines changed: 393 additions & 3 deletions

File tree

‎AGENTS.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,9 @@ Bugfixes and small features stop at this skill.
4747
## Releases
4848

4949
Follow the [Releasing a version](https://github.com/graphql-java-kickstart/graphql-java-tools/wiki/Releasing-a-version) wiki
50-
page. `github-build.sh` and `.github/workflows/release.yml` do the version bump, tag and publish.
50+
page. `github-build.sh` and `.github/workflows/release.yml` do the version bump, tag and publish. After an X.0.0 release,
51+
delete the `<excludes>` under japicmp-maven-plugin in `pom.xml`. The version is X.0.1-SNAPSHOT by then and the API check
52+
fails while they remain.
5153

5254
## Rules that need judgment
5355

@@ -86,7 +88,7 @@ happening. "docs only" means nothing does yet, so the rule depends on you readin
8688
| Argument conversion goes through one entry point | docs only |
8789
| An input field's Java type comes from the mapping Jackson uses, not from guessed getters | docs only |
8890
| Every recursive walk over the type graph handles cycles, and a test covers a cycle | docs only |
89-
| Public signatures stay binary compatible, data class `copy()` and `componentN` included | docs only |
91+
| Public signatures stay binary compatible, data class `copy()` and `componentN` included | japicmp with `build/japicmp-kotlin-public.groovy` at `mvn verify`, which allows excludes and other narrowing options only at an X.0.0 version |
9092
| Remove the plumbing a change leaves unused | Compiler warnings for unused locals, docs only for the rest |
9193
| A new warning or build error names the type and the item and uses `SourceLocation.describe()` for its location | docs only |
9294
| A check keyed on a class name or an exception type has a test that fails when the dependency moves it | docs only |
@@ -102,7 +104,7 @@ happening. "docs only" means nothing does yet, so the rule depends on you readin
102104
| The first commit of a fix tests the neighbouring shapes, not just the reported one | docs only |
103105
| The build passes on JDK 17, the lowest supported version | CI on JDK 17, 21 and 25 |
104106
| Run verify-tools before you push a schema-building change | docs only |
105-
| The packaged jar holds `module-info.class`, its non-static `requires` resolve from the runtime dependencies, and every class targets the pom's `java.version` | docs only |
107+
| The packaged jar holds `module-info.class`, its non-static `requires` resolve from the runtime dependencies, and every class targets the pom's `java.version` | `build/JarCheck.java` at `mvn verify` |
106108
| Compiler warnings fail the build | `-Werror` and `failOnWarning` in `pom.xml` |
107109
| Check every claim in a PR body or release note at the current head | docs only |
108110
| Keep a comment only for a non-obvious why, with no history and no issue numbers outside a TODO | docs only |

‎build/JarCheck.java‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
import java.io.DataInputStream;
2+
import java.io.File;
3+
import java.io.IOException;
4+
import java.io.InputStream;
5+
import java.lang.module.Configuration;
6+
import java.lang.module.FindException;
7+
import java.lang.module.ModuleDescriptor;
8+
import java.lang.module.ModuleFinder;
9+
import java.lang.module.ResolutionException;
10+
import java.nio.file.Path;
11+
import java.util.ArrayList;
12+
import java.util.Arrays;
13+
import java.util.Collections;
14+
import java.util.List;
15+
import java.util.Set;
16+
import java.util.TreeMap;
17+
import java.util.jar.JarEntry;
18+
import java.util.jar.JarFile;
19+
20+
public class JarCheck {
21+
public static void main(String[] args) throws IOException {
22+
Path jar = Path.of(args[0]);
23+
int release = Integer.parseInt(args[1]);
24+
int expectedMajor = release + 44;
25+
String runtimeClasspath = args[2];
26+
List<String> expectedClasses = Arrays.asList(args).subList(3, args.length);
27+
List<String> problems = new ArrayList<>();
28+
29+
TreeMap<Integer, List<String>> byMajor = new TreeMap<>();
30+
ModuleDescriptor descriptor = null;
31+
try (JarFile jarFile = new JarFile(jar.toFile())) {
32+
for (String expected : expectedClasses) {
33+
if (jarFile.getJarEntry(expected.replace('.', '/') + ".class") == null) {
34+
problems.add("The jar has no " + expected + ". Check <sourceDirectory> in pom.xml: Kotlin and Java sources live in src/main/kotlin.");
35+
}
36+
}
37+
for (JarEntry entry : Collections.list(jarFile.entries())) {
38+
if (!entry.getName().endsWith(".class")) continue;
39+
try (DataInputStream data = new DataInputStream(jarFile.getInputStream(entry))) {
40+
data.readInt();
41+
data.readUnsignedShort();
42+
int major = data.readUnsignedShort();
43+
byMajor.computeIfAbsent(major, k -> new ArrayList<>()).add(entry.getName());
44+
}
45+
}
46+
JarEntry moduleInfo = jarFile.getJarEntry("module-info.class");
47+
if (moduleInfo != null) {
48+
try (InputStream in = jarFile.getInputStream(moduleInfo)) {
49+
descriptor = ModuleDescriptor.read(in);
50+
}
51+
}
52+
}
53+
byMajor.forEach((major, classes) -> {
54+
if (major != expectedMajor) {
55+
problems.add(classes.size() + " classes are Java " + (major - 44) + " bytecode (major " + major + "), expected Java " + release
56+
+ " (major " + expectedMajor + "), e.g. " + classes.get(0)
57+
+ ". Set <jvmTarget>${java.version}</jvmTarget> on kotlin-maven-plugin and <release>${java.version}</release> on maven-compiler-plugin.");
58+
}
59+
});
60+
61+
if (descriptor == null) {
62+
problems.add("The jar has no module-info.class. Keep src/main/kotlin/module-info.java, which maven-compiler-plugin compiles into the jar.");
63+
} else {
64+
List<Path> modulePath = new ArrayList<>();
65+
modulePath.add(jar);
66+
for (String entry : runtimeClasspath.split(File.pathSeparator)) {
67+
if (!entry.isEmpty() && !Path.of(entry).equals(jar)) modulePath.add(Path.of(entry));
68+
}
69+
try {
70+
Configuration.resolve(ModuleFinder.of(modulePath.toArray(Path[]::new)), List.of(ModuleLayer.boot().configuration()),
71+
ModuleFinder.of(), Set.of(descriptor.name()));
72+
} catch (FindException | ResolutionException e) {
73+
problems.add("A JPMS application with only this jar's compile and runtime dependencies can't start: " + e.getMessage()
74+
+ ". A module from a provided or optional dependency must be 'requires static' in module-info.java.");
75+
}
76+
}
77+
78+
if (!problems.isEmpty()) {
79+
System.err.println("Jar check failed for " + jar.getFileName() + ":");
80+
problems.forEach(p -> System.err.println(" " + p));
81+
System.exit(1);
82+
}
83+
int classCount = byMajor.values().stream().mapToInt(List::size).sum();
84+
System.out.println("Jar check passed for " + jar.getFileName() + ": " + classCount + " classes, all major " + expectedMajor
85+
+ ", module " + descriptor.name() + " resolves against the runtime classpath.");
86+
}
87+
}

‎build/japicmp-kotlin-public.groovy‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
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

Comments
 (0)