GH-1041 - Revamp JavaPackage's sub-package traversal to retain empty intermediate packages.

Author: odrotbohm

spring-modulith-core/src/main/java/org/springframework/modulith/core/JavaPackage.java

@@ -59,6 +59,7 @@ public class JavaPackage implements DescribedIterable<JavaClass>, Comparable<Jav
 	private final PackageName name;
 	private final Classes classes, packageClasses;
 	private final Supplier<Set<JavaPackage>> directSubPackages;
+	private final Supplier<JavaPackages> subPackages;
 
 	/**
 	 * Creates a new {@link JavaPackage} for the given {@link Classes}, name and whether to include all sub-packages.
@@ -75,13 +76,13 @@ private JavaPackage(Classes classes, PackageName name, boolean includeSubPackage
 		this.packageClasses = classes
 				.that(resideInAPackage(name.asFilter(includeSubPackages)));
 		this.name = name;
-		this.directSubPackages = SingletonSupplier.of(() -> packageClasses.stream() //
-				.map(it -> it.getPackageName()) //
-				.filter(Predicate.not(name::hasName)) //
-				.map(it -> extractDirectSubPackage(it)) //
-				.distinct() //
-				.map(it -> of(classes, it)) //
-				.collect(Collectors.toSet()));
+
+		this.directSubPackages = () -> detectSubPackages()
+				.filter(this::isDirectParentOf)
+				.collect(Collectors.toUnmodifiableSet());
+
+		this.subPackages = SingletonSupplier.of(() -> detectSubPackages()
+				.collect(collectingAndThen(toUnmodifiableList(), JavaPackages::new)));
 	}
 
 	/**
@@ -92,7 +93,7 @@ private JavaPackage(Classes classes, PackageName name, boolean includeSubPackage
 	 * @return
 	 */
 	public static JavaPackage of(Classes classes, String name) {
-		return new JavaPackage(classes, new PackageName(name), true);
+		return new JavaPackage(classes, PackageName.of(name), true);
 	}
 
 	/**
@@ -333,13 +334,7 @@ Classes getClasses(Iterable<JavaPackage> exclusions) {
 	 * @since 1.3
 	 */
 	JavaPackages getSubPackages() {
-
-		return packageClasses.stream() //
-				.map(JavaClass::getPackageName)
-				.filter(Predicate.not(name::hasName))
-				.distinct()
-				.map(it -> new JavaPackage(classes, new PackageName(it), true))
-				.collect(collectingAndThen(toUnmodifiableList(), JavaPackages::new));
+		return subPackages.get();
 	}
 
 	/**
@@ -390,6 +385,21 @@ public <A extends Annotation> Optional<A> findAnnotation(Class<A> annotationType
 				});
 	}
 
+	/**
+	 * Returns whether the current {@link JavaPackage} is the direct parent of the given one.
+	 *
+	 * @param reference must not be {@literal null}.
+	 * @since 1.4
+	 */
+	boolean isDirectParentOf(JavaPackage reference) {
+
+		Assert.notNull(reference, "Reference JavaPackage must not be null!");
+
+		var name = reference.getPackageName();
+
+		return name.hasParent() && this.getPackageName().equals(name.getParent());
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see com.tngtech.archunit.base.HasDescription#getDescription()
@@ -399,6 +409,17 @@ public String getDescription() {
 		return classes.getDescription();
 	}
 
+	private Stream<JavaPackage> detectSubPackages() {
+
+		return packageClasses.stream() //
+				.map(JavaClass::getPackageName)
+				.filter(Predicate.not(name::hasName))
+				.map(PackageName::of)
+				.flatMap(name::expandUntil)
+				.distinct()
+				.map(it -> new JavaPackage(classes, it, true));
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see java.lang.Iterable#iterator()
@@ -461,24 +482,6 @@ public int hashCode() {
 		return Objects.hash(classes, directSubPackages.get(), name, packageClasses);
 	}
 
-	/**
-	 * Extract the direct sub-package name of the given candidate.
-	 *
-	 * @param candidate
-	 * @return will never be {@literal null}.
-	 */
-	private String extractDirectSubPackage(String candidate) {
-
-		if (candidate.length() <= name.length()) {
-			return candidate;
-		}
-
-		int subSubPackageIndex = candidate.indexOf('.', name.length() + 1);
-		int endIndex = subSubPackageIndex == -1 ? candidate.length() : subSubPackageIndex;
-
-		return candidate.substring(0, endIndex);
-	}
-
 	static Comparator<JavaPackage> reverse() {
 		return (left, right) -> -left.compareTo(right);
 	}

spring-modulith-core/src/main/java/org/springframework/modulith/core/PackageName.java

@@ -15,6 +15,13 @@
  */
 package org.springframework.modulith.core;
 
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 
@@ -27,6 +34,8 @@
  */
 class PackageName implements Comparable<PackageName> {
 
+	private static final Map<String, PackageName> PACKAGE_NAMES = new HashMap<>();
+
 	private final String name;
 	private final String[] segments;
 
@@ -35,12 +44,23 @@ class PackageName implements Comparable<PackageName> {
 	 *
 	 * @param name must not be {@literal null}.
 	 */
-	public PackageName(String name) {
+	private PackageName(String name) {
+		this(name, name.split("\\."));
+	}
+
+	/**
+	 * Creates a new {@link PackageName} with the given name and segments.
+	 *
+	 * @param name must not be {@literal null}.
+	 * @param segments must not be {@literal null}.
+	 */
+	private PackageName(String name, String[] segments) {
 
 		Assert.notNull(name, "Name must not be null!");
+		Assert.notNull(segments, "Segments must not be null!");
 
 		this.name = name;
-		this.segments = name.split("\\.");
+		this.segments = segments;
 	}
 
 	/**
@@ -49,11 +69,41 @@ public PackageName(String name) {
 	 * @param fullyQualifiedName must not be {@literal null} or empty.
 	 * @return will never be {@literal null}.
 	 */
-	public static PackageName ofType(String fullyQualifiedName) {
+	static PackageName ofType(String fullyQualifiedName) {
 
 		Assert.notNull(fullyQualifiedName, "Type name must not be null!");
 
-		return new PackageName(ClassUtils.getPackageName(fullyQualifiedName));
+		return PackageName.of(ClassUtils.getPackageName(fullyQualifiedName));
+	}
+
+	/**
+	 * Returns the {@link PackageName} with the given name.
+	 *
+	 * @param name must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 * @since 1.4
+	 */
+	static PackageName of(String name) {
+
+		Assert.notNull(name, "Name must not be null!");
+
+		return PACKAGE_NAMES.computeIfAbsent(name, PackageName::new);
+	}
+
+	/**
+	 * Returns the {@link PackageName} for the given segments.
+	 *
+	 * @param segments must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 * @since 1.4
+	 */
+	static PackageName of(String[] segments) {
+
+		Assert.notNull(segments, "Segments must not be null!");
+
+		var name = Stream.of(segments).collect(Collectors.joining("."));
+
+		return PACKAGE_NAMES.computeIfAbsent(name, it -> new PackageName(name, segments));
 	}
 
 	/**
@@ -132,6 +182,10 @@ boolean isParentPackageOf(PackageName reference) {
 		return reference.name.startsWith(name + ".");
 	}
 
+	boolean isDirectParentOf(PackageName reference) {
+		return this.equals(getParent());
+	}
+
 	/**
 	 * Returns whether the package name contains the given one, i.e. if the given one either is the current one or a
 	 * sub-package of it.
@@ -185,6 +239,48 @@ public int compareTo(PackageName o) {
 		return segments.length - o.segments.length;
 	}
 
+	/**
+	 * Returns the names of sub-packages of the current one until the given reference {@link PackageName}.
+	 *
+	 * @param reference must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 * @since 1.4
+	 */
+	Stream<PackageName> expandUntil(PackageName reference) {
+
+		Assert.notNull(reference, "Reference must not be null!");
+
+		if (!reference.isSubPackageOf(this) || !reference.hasParent()) {
+			return Stream.empty();
+		}
+
+		if (isDirectParentOf(reference)) {
+			return Stream.of(reference);
+		}
+
+		return Stream.concat(expandUntil(reference.getParent()), Stream.of(reference));
+	}
+
+	/**
+	 * Returns whether the current {@link PackageName} has a parent.
+	 *
+	 * @since 1.4
+	 */
+	boolean hasParent() {
+		return segments.length > 1;
+	}
+
+	/**
+	 * Returns the parent {@link PackageName}.
+	 *
+	 * @return can be {@literal null}.
+	 * @since 1.4
+	 */
+	@Nullable
+	PackageName getParent() {
+		return PackageName.of(Arrays.copyOf(segments, segments.length - 1));
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see java.lang.Object#toString()

spring-modulith-core/src/test/java/org/springframework/modulith/core/JavaPackageUnitTests.java

@@ -116,4 +116,16 @@ void samePackagesConsideredEqual() {
 		assertThat(first.equals(second)).isTrue();
 		assertThat(second.equals(first)).isTrue();
 	}
+
+	@Test // GH-1039
+	void detectsIntermediateSubPackages() {
+
+		var packages = TestUtils.getPackage("with").getSubPackages();
+
+		assertThat(packages)
+				.extracting(JavaPackage::getName)
+				.containsExactly("with.many",
+						"with.many.intermediate",
+						"with.many.intermediate.packages");
+	}
 }

spring-modulith-core/src/test/java/org/springframework/modulith/core/PackageNameUnitTests.java

@@ -31,12 +31,12 @@ class PackageNameUnitTests {
 	@Test // GH-578
 	void sortsPackagesByNameAndDepth() {
 
-		var comAcme = new PackageName("com.acme");
-		var comAcmeA = new PackageName("com.acme.a");
-		var comAcmeAFirst = new PackageName("com.acme.a.first");
-		var comAcmeAFirstOne = new PackageName("com.acme.a.first.one");
-		var comAcmeASecond = new PackageName("com.acme.a.second");
-		var comAcmeB = new PackageName("com.acme.b");
+		var comAcme = PackageName.of("com.acme");
+		var comAcmeA = PackageName.of("com.acme.a");
+		var comAcmeAFirst = PackageName.of("com.acme.a.first");
+		var comAcmeAFirstOne = PackageName.of("com.acme.a.first.one");
+		var comAcmeASecond = PackageName.of("com.acme.a.second");
+		var comAcmeB = PackageName.of("com.acme.b");
 
 		assertThat(List.of(comAcmeAFirstOne, comAcmeB, comAcmeASecond, comAcmeAFirst, comAcme, comAcmeA)
 				.stream()
@@ -48,8 +48,8 @@ void sortsPackagesByNameAndDepth() {
 	@Test // GH-802
 	void caculatesNestingCorrectly() {
 
-		var comAcme = new PackageName("com.acme");
-		var comAcmeA = new PackageName("com.acme.a");
+		var comAcme = PackageName.of("com.acme");
+		var comAcmeA = PackageName.of("com.acme.a");
 
 		assertThat(comAcme.contains(comAcme)).isTrue();
 		assertThat(comAcme.contains(comAcmeA)).isTrue();

spring-modulith-core/src/test/java/org/springframework/modulith/core/TestUtils.java

@@ -85,28 +85,28 @@ public static Classes getClasses(Class<?> packageType) {
 				.that(resideInAPackage(packageType.getPackage().getName() + "..")));
 	}
 
-	public static JavaPackage getPackage(Class<?> packageType) {
-		return JavaPackage.of(TestUtils.getClasses(packageType), packageType.getPackageName());
-	}
+	public static Classes getClasses(String packageName) {
 
-	public static ApplicationModule getApplicationModule(String packageName) {
+		Assert.hasText(packageName, "Package name must not be null or empty!");
 
-		var pkg = getPackage(packageName);
-		var source = ApplicationModuleSource.from(pkg, pkg.getLocalName());
+		return Classes.of(new ClassFileImporter()
+				.importPackages(packageName));
+	}
 
-		return new ApplicationModule(source);
+	public static JavaPackage getPackage(Class<?> packageType) {
+		return JavaPackage.of(TestUtils.getClasses(packageType), packageType.getPackageName());
 	}
 
-	private static JavaPackage getPackage(String name) {
+	public static JavaPackage getPackage(String name) {
 		return JavaPackage.of(getClasses(name), name);
 	}
 
-	private static Classes getClasses(String packageName) {
+	public static ApplicationModule getApplicationModule(String packageName) {
 
-		Assert.hasText(packageName, "Package name must not be null or empty!");
+		var pkg = getPackage(packageName);
+		var source = ApplicationModuleSource.from(pkg, pkg.getLocalName());
 
-		return Classes.of(new ClassFileImporter()
-				.importPackages(packageName));
+		return new ApplicationModule(source);
 	}
 
 	private static ApplicationModules of(ModulithMetadata metadata, DescribedPredicate<JavaClass> ignores) {

spring-modulith-core/src/test/java/with/many/intermediate/packages/Marker.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package with.many.intermediate.packages;
+
+/**
+ * @author Oliver Drotbohm
+ */
+class Marker {}