Improve automatic resolution of class import dependencies #785

When importing classes there will always be some dependencies that are missing. E.g. we import package `com.myapp`, but naturally those classes will at least depend on classes in `java.lang`. ArchUnit has an automatic import dependency resolution process to pick up such missing classes from the classpath (by default).
However, this resolution process was somewhat inconsistent. It would in a first run resolve all missing member types, then in a second run resolve all missing access targets, then supertypes and then annotations. Thus, e.g. classes that were discovered when resolving supertypes would not have their member types resolved anymore, which could lead to surprising behavior. Also, some dependencies were not automatically resolved, in particular:

* generic type signatures
* enclosing classes of nested classes
* component types of array types
* types of declared thrown exceptions
* target types of instanceof checks
* referenced class objects

This PR consolidates the resolution process and fixes these shortcomings. It does so by registering all import dependencies already withing the ASM visitors. This way, once all the classes picked originally are imported we now have a set of class names that are needed as dependencies. When we run the importer again to resolve these missing types we will again transitively register the types these types were missing. By distinguishing 6 types of dependencies (member types, accesses, supertypes, enclosing types, annotations and generic type signatures) we can control how deeply we want to resolve each of these sort of dependencies. How many iterations we make for each such type is now configurable via `archunit.properties`. The defaults are configured in a way that the behavior is similar to before, except that the mentioned shortcomings are now fixed. I.e. we resolve one level for member types and accesses, so all the "used types" of the imported classes are present. The other types of dependencies we resolve until we have registered all needed types. That way (meta-)annotations, generic signatures, etc., are all fully resolved. This should provide a reasonable default behavior and also fix most issues that ever occurred because of inconsistent resolution behavior.

archunit-integration-test/src/test/resources/archunit.properties

@@ -1,3 +1,5 @@
+import.dependencyResolutionProcess.maxIterationsForEnclosingTypes=0
+import.dependencyResolutionProcess.maxIterationsForGenericSignatureTypes=0
 extension.archunit-example-extension.enabled=false
 extension.archunit-example-extension.example-prop=exampleValue
 freeze.store.default.path=../archunit-example/example-plain/src/test/resources/frozen

archunit-junit/junit4/src/test/resources/archunit.properties

@@ -0,0 +1,2 @@
+import.dependencyResolutionProcess.maxIterationsForEnclosingTypes=0
+import.dependencyResolutionProcess.maxIterationsForGenericSignatureTypes=0

archunit-junit/junit5/engine/src/test/resources/archunit.properties

@@ -0,0 +1,2 @@
+import.dependencyResolutionProcess.maxIterationsForEnclosingTypes=0
+import.dependencyResolutionProcess.maxIterationsForGenericSignatureTypes=0

archunit/src/jdk9test/java/com/tngtech/archunit/core/importer/testexamples/annotations/AnotherAnnotationWithAnnotationParameter.java

@@ -0,0 +1,5 @@
+package com.tngtech.archunit.core.importer.testexamples.annotations;
+
+public @interface AnotherAnnotationWithAnnotationParameter {
+    SomeAnnotationWithAnnotationParameter value();
+}

archunit/src/jdk9test/java/com/tngtech/archunit/core/importer/testexamples/annotations/SomeAnnotationWithAnnotationParameter.java

@@ -0,0 +1,5 @@
+package com.tngtech.archunit.core.importer.testexamples.annotations;
+
+public @interface SomeAnnotationWithAnnotationParameter {
+    SomeAnnotationWithClassParameter value();
+}

archunit/src/jdk9test/java/com/tngtech/archunit/core/importer/testexamples/annotations/SomeAnnotationWithClassParameter.java

@@ -0,0 +1,5 @@
+package com.tngtech.archunit.core.importer.testexamples.annotations;
+
+public @interface SomeAnnotationWithClassParameter {
+    Class<?> value();
+}

archunit/src/jdk9test/java/com/tngtech/archunit/core/importer/testexamples/classhierarchy/Child.java

@@ -0,0 +1,4 @@
+package com.tngtech.archunit.core.importer.testexamples.classhierarchy;
+
+public class Child extends Parent implements ParentInterfaceDirect {
+}

archunit/src/jdk9test/java/com/tngtech/archunit/core/importer/testexamples/classhierarchy/GrandParent.java

@@ -0,0 +1,4 @@
+package com.tngtech.archunit.core.importer.testexamples.classhierarchy;
+
+public class GrandParent implements ParentInterfaceIndirect {
+}

archunit/src/jdk9test/java/com/tngtech/archunit/core/importer/testexamples/classhierarchy/GrandParentInterfaceDirect.java

@@ -0,0 +1,4 @@
+package com.tngtech.archunit.core.importer.testexamples.classhierarchy;
+
+public interface GrandParentInterfaceDirect {
+}

archunit/src/jdk9test/java/com/tngtech/archunit/core/importer/testexamples/classhierarchy/GrandParentInterfaceIndirect.java

@@ -0,0 +1,4 @@
+package com.tngtech.archunit.core.importer.testexamples.classhierarchy;
+
+public interface GrandParentInterfaceIndirect {
+}

archunit/src/jdk9test/java/com/tngtech/archunit/core/importer/testexamples/classhierarchy/Parent.java

@@ -0,0 +1,4 @@
+package com.tngtech.archunit.core.importer.testexamples.classhierarchy;
+
+public class Parent extends GrandParent {
+}

archunit/src/jdk9test/java/com/tngtech/archunit/core/importer/testexamples/classhierarchy/ParentInterfaceDirect.java

@@ -0,0 +1,4 @@
+package com.tngtech.archunit.core.importer.testexamples.classhierarchy;
+
+public interface ParentInterfaceDirect extends GrandParentInterfaceDirect {
+}

archunit/src/jdk9test/java/com/tngtech/archunit/core/importer/testexamples/classhierarchy/ParentInterfaceIndirect.java

@@ -0,0 +1,4 @@
+package com.tngtech.archunit.core.importer.testexamples.classhierarchy;
+
+public interface ParentInterfaceIndirect extends GrandParentInterfaceIndirect {
+}

archunit/src/main/java/com/tngtech/archunit/core/domain/JavaClass.java

@@ -136,7 +136,7 @@ public Set<JavaClass> get() {
     private Map<String, JavaAnnotation<JavaClass>> annotations = emptyMap();
     private JavaClassDependencies javaClassDependencies = new JavaClassDependencies(this);  // just for stubs; will be overwritten for imported classes
     private ReverseDependencies reverseDependencies = ReverseDependencies.EMPTY;  // just for stubs; will be overwritten for imported classes
-    private final CompletionProcess completionProcess = CompletionProcess.start();
+    private final CompletionProcess completionProcess;
 
     JavaClass(JavaClassBuilder builder) {
         source = checkNotNull(builder.getSource());
@@ -151,6 +151,7 @@ public Set<JavaClass> get() {
         reflectSupplier = Suppliers.memoize(new ReflectClassSupplier());
         sourceCodeLocation = SourceCodeLocation.of(this);
         javaPackage = JavaPackage.simple(this);
+        completionProcess = builder.isStub() ? CompletionProcess.stub() : CompletionProcess.start();
     }
 
     /**
@@ -648,6 +649,11 @@ public List<JavaTypeVariable<JavaClass>> getTypeParameters() {
         return typeParameters;
     }
 
+    @PublicAPI(usage = ACCESS)
+    public Set<InstanceofCheck> getInstanceofChecks() {
+        return members.getInstanceofChecks();
+    }
+
     @PublicAPI(usage = ACCESS)
     public Set<ReferencedClassObject> getReferencedClassObjects() {
         return members.getReferencedClassObjects();
@@ -1545,6 +1551,19 @@ public static List<String> namesOf(Iterable<Class<?>> paramTypes) {
         return formatNamesOf(paramTypes);
     }
 
+    /**
+     * @return all throws declarations on any method or constructor of this class
+     *         (e.g. {@code void method() throws SomeException})
+     */
+    @PublicAPI(usage = ACCESS)
+    public Set<ThrowsDeclaration<? extends JavaCodeUnit>> getThrowsDeclarations() {
+        ImmutableSet.Builder<ThrowsDeclaration<? extends JavaCodeUnit>> result = ImmutableSet.builder();
+        for (JavaCodeUnit codeUnit : getCodeUnits()) {
+            result.addAll(codeUnit.getThrowsClause());
+        }
+        return result.build();
+    }
+
     private static class Superclass {
         private static final Superclass ABSENT = new Superclass(Optional.<JavaType>empty());
 
@@ -1646,7 +1665,74 @@ static EnclosingDeclaration ofClass(Optional<JavaClass> clazz) {
         }
     }
 
-    private static class CompletionProcess {
+    private abstract static class CompletionProcess {
+        private static final CompletionProcess stubCompletionProcess = new CompletionProcess() {
+            @Override
+            boolean hasFinished() {
+                return false;
+            }
+
+            @Override
+            public void markClassHierarchyComplete() {
+            }
+
+            @Override
+            public void markEnclosingDeclarationComplete() {
+            }
+
+            @Override
+            public void markTypeParametersComplete() {
+            }
+
+            @Override
+            public void markGenericSuperclassComplete() {
+            }
+
+            @Override
+            public void markGenericInterfacesComplete() {
+            }
+
+            @Override
+            public void markMembersComplete() {
+            }
+
+            @Override
+            public void markAnnotationsComplete() {
+            }
+
+            @Override
+            public void markDependenciesComplete() {
+            }
+        };
+
+        abstract boolean hasFinished();
+
+        public abstract void markClassHierarchyComplete();
+
+        public abstract void markEnclosingDeclarationComplete();
+
+        public abstract void markTypeParametersComplete();
+
+        public abstract void markGenericSuperclassComplete();
+
+        public abstract void markGenericInterfacesComplete();
+
+        public abstract void markMembersComplete();
+
+        public abstract void markAnnotationsComplete();
+
+        public abstract void markDependenciesComplete();
+
+        static CompletionProcess start() {
+            return new FullCompletionProcess();
+        }
+
+        static CompletionProcess stub() {
+            return stubCompletionProcess;
+        }
+    }
+
+    private static class FullCompletionProcess extends CompletionProcess {
         private boolean classHierarchyComplete = false;
         private boolean enclosingDeclarationComplete = false;
         private boolean typeParametersComplete = false;
@@ -1656,9 +1742,7 @@ private static class CompletionProcess {
         private boolean annotationsComplete = false;
         private boolean dependenciesComplete = false;
 
-        private CompletionProcess() {
-        }
-
+        @Override
         boolean hasFinished() {
             return classHierarchyComplete
                     && enclosingDeclarationComplete
@@ -1670,41 +1754,45 @@ boolean hasFinished() {
                     && dependenciesComplete;
         }
 
+        @Override
         public void markClassHierarchyComplete() {
             this.classHierarchyComplete = true;
         }
 
+        @Override
         public void markEnclosingDeclarationComplete() {
             this.enclosingDeclarationComplete = true;
         }
 
+        @Override
         public void markTypeParametersComplete() {
             this.typeParametersComplete = true;
         }
 
+        @Override
         public void markGenericSuperclassComplete() {
             this.genericSuperclassComplete = true;
         }
 
+        @Override
         public void markGenericInterfacesComplete() {
             this.genericInterfacesComplete = true;
         }
 
+        @Override
         public void markMembersComplete() {
             this.membersComplete = true;
         }
 
+        @Override
         public void markAnnotationsComplete() {
             this.annotationsComplete = true;
         }
 
+        @Override
         public void markDependenciesComplete() {
             this.dependenciesComplete = true;
         }
-
-        static CompletionProcess start() {
-            return new CompletionProcess();
-        }
     }
 
     public static final class Functions {

archunit/src/main/java/com/tngtech/archunit/core/domain/JavaClassDependencies.java

@@ -185,10 +185,8 @@ private Set<Dependency> genericParameterTypeArgumentDependencies(JavaCodeUnit co
 
     private Set<Dependency> throwsDeclarationDependenciesFromSelf() {
         ImmutableSet.Builder<Dependency> result = ImmutableSet.builder();
-        for (JavaCodeUnit codeUnit : javaClass.getCodeUnits()) {
-            for (ThrowsDeclaration<? extends JavaCodeUnit> throwsDeclaration : codeUnit.getThrowsClause()) {
-                result.addAll(Dependency.tryCreateFromThrowsDeclaration(throwsDeclaration));
-            }
+        for (ThrowsDeclaration<? extends JavaCodeUnit> throwsDeclaration : javaClass.getThrowsDeclarations()) {
+            result.addAll(Dependency.tryCreateFromThrowsDeclaration(throwsDeclaration));
         }
         return result.build();
     }
@@ -206,10 +204,8 @@ private Set<Dependency> annotationDependenciesFromSelf() {
 
     private Set<Dependency> instanceofCheckDependenciesFromSelf() {
         ImmutableSet.Builder<Dependency> result = ImmutableSet.builder();
-        for (JavaCodeUnit codeUnit : javaClass.getCodeUnits()) {
-            for (InstanceofCheck instanceofCheck : codeUnit.getInstanceofChecks()) {
-                result.addAll(Dependency.tryCreateFromInstanceofCheck(instanceofCheck));
-            }
+        for (InstanceofCheck instanceofCheck : javaClass.getInstanceofChecks()) {
+            result.addAll(Dependency.tryCreateFromInstanceofCheck(instanceofCheck));
         }
         return result.build();
     }

archunit/src/main/java/com/tngtech/archunit/core/domain/JavaClassMembers.java

@@ -196,6 +196,14 @@ Set<JavaEnumConstant> getEnumConstants() {
         return result.build();
     }
 
+    Set<InstanceofCheck> getInstanceofChecks() {
+        ImmutableSet.Builder<InstanceofCheck> result = ImmutableSet.builder();
+        for (JavaCodeUnit codeUnit : codeUnits) {
+            result.addAll(codeUnit.getInstanceofChecks());
+        }
+        return result.build();
+    }
+
     Set<ReferencedClassObject> getReferencedClassObjects() {
         ImmutableSet.Builder<ReferencedClassObject> result = ImmutableSet.builder();
         for (JavaCodeUnit codeUnit : codeUnits) {