allow rules a project has no code for, and guard the import instead

Failing on an empty selection was the wrong call. Seven of the eight rules that
narrow their input have a legitimate empty case - no records, no controllers, no
@Store classes, nobody using @nested - and one of them described this repository
before this branch: a project whose only test is the ArchitectureTest has no
@test methods at all. Whether that code exists is the project's business.

allowEmptyShould(true) was never what protected against a dead rule either. It
fires on what a consumer's code happens to contain and says nothing about whether
a rule's logic works: the counterpart rule that started this had a perfectly
non-empty selection and a broken condition. The guarantee is the red test per
rule in this project, so all 13 rules now tolerate an empty selection.

That leaves one case worth failing on. A mistyped or moved package in
@AnalyzeClasses imports nothing, and every rule then passes without looking at a
single class. AnalyzedPackagesMustContainClassesArchRule turns that into one
failure naming the cause, instead of five rules passing silently and eight
reporting that they checked nothing. It is in both collections, so it applies
wherever the toolbox is used.

EmptySelectionTest is inverted to match: it now pins that every rule accepts a
project with nothing for it to check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: SirCotare

readme.md

@@ -47,12 +47,19 @@ static {
 
 The same applies to `ArchRuleConfig.TEST_CLASS_SUFFIXES` when a project introduces a new test type.
 
-### Every rule must be able to fail
+### Rules your project has no code for
 
-No rule uses `allowEmptyShould(true)`. A rule that selects nothing would otherwise report success,
-which is indistinguishable from a rule that is satisfied - and that is how a broken rule survives
-unnoticed. So a rule whose selection comes up empty fails, and the fix is either to remove the rule
-collection you do not need or to add the code it is meant to check.
+Every rule tolerates a selection that comes up empty, so a rule simply passes on a project it does
+not apply to. Whether a project has records, controllers, `@Store` classes or `@Nested` test classes
+is the project's business, not something this library requires.
+
+That each rule can actually fail is guaranteed by a red test per rule in this repository, rather than
+by making your build fail over code you do not have. An empty selection says nothing about whether a
+rule's logic works.
+
+One case is a real problem though, and `analyzed_packages_must_contain_classes` covers it: if the
+packages given to `@AnalyzeClasses` are mistyped or have moved, nothing is imported and every other
+rule would pass without looking at a single class. That fails, once, with a message naming the cause.
 
 ### Opting out
 

src/main/java/it/aboutbits/archunit/toolbox/BaseArchRuleCollection.java

@@ -1,5 +1,6 @@
 package it.aboutbits.archunit.toolbox;
 
+import it.aboutbits.archunit.toolbox.rule.base.AnalyzedPackagesMustContainClassesArchRule;
 import it.aboutbits.archunit.toolbox.rule.base.BlacklistAnnotationsArchRule;
 import it.aboutbits.archunit.toolbox.rule.base.BlacklistClassesArchRule;
 import it.aboutbits.archunit.toolbox.rule.base.BlacklistMethodsArchRule;
@@ -15,6 +16,7 @@
 
 @NullMarked
 public interface BaseArchRuleCollection extends
+        AnalyzedPackagesMustContainClassesArchRule,
         BlacklistAnnotationsArchRule,
         BlacklistClassesArchRule,
         BlacklistMethodsArchRule,

src/main/java/it/aboutbits/archunit/toolbox/CommonArchRuleCollection.java

@@ -1,11 +1,13 @@
 package it.aboutbits.archunit.toolbox;
 
+import it.aboutbits.archunit.toolbox.rule.base.AnalyzedPackagesMustContainClassesArchRule;
 import it.aboutbits.archunit.toolbox.rule.common.ControllerRequestMappingsMustBeSecurityTested;
 import it.aboutbits.archunit.toolbox.rule.common.SortMappingsExhaustiveArchRule;
 import org.jspecify.annotations.NullMarked;
 
 @NullMarked
 public interface CommonArchRuleCollection extends
+        AnalyzedPackagesMustContainClassesArchRule,
         ControllerRequestMappingsMustBeSecurityTested,
         SortMappingsExhaustiveArchRule {
 }

src/main/java/it/aboutbits/archunit/toolbox/rule/base/AnalyzedPackagesMustContainClassesArchRule.java

@@ -0,0 +1,30 @@
+package it.aboutbits.archunit.toolbox.rule.base;
+
+import com.tngtech.archunit.core.domain.JavaClasses;
+import com.tngtech.archunit.junit.ArchTest;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Checks that the analyzed packages contain any classes at all.
+ * <p>
+ * Every other rule tolerates an empty selection, because whether a project has records, controllers
+ * or @Nested test classes is the project's business and not something this library gets to require.
+ * That leaves exactly one dangerous case: a mistyped or moved package in @AnalyzeClasses imports
+ * nothing, and every rule then passes without looking at a single class. This rule is what turns that
+ * into a failure, once, with a message that names the actual problem.
+ * </p>
+ */
+@SuppressWarnings({"checkstyle:InterfaceIsType", "java:S1214"})
+@NullMarked
+public interface AnalyzedPackagesMustContainClassesArchRule {
+    @SuppressWarnings({"unused", "checkstyle:MethodName", "java:S100"})
+    @ArchTest
+    default void analyzed_packages_must_contain_classes(JavaClasses classes) {
+        if (classes.isEmpty()) {
+            throw new AssertionError(
+                    "No classes were imported, so none of the architecture rules checked anything. "
+                            + "Verify the packages passed to @AnalyzeClasses."
+            );
+        }
+    }
+}

src/main/java/it/aboutbits/archunit/toolbox/rule/base/BlacklistAnnotationsArchRule.java

@@ -64,6 +64,7 @@ public interface BlacklistAnnotationsArchRule {
     default void no_blacklisted_annotations_are_used(JavaClasses classes) {
         classes()
                 .should(new NotUseBlacklistedAnnotations())
+                .allowEmptyShould(true)
                 .check(classes);
     }
 

src/main/java/it/aboutbits/archunit/toolbox/rule/base/BlacklistClassesArchRule.java

@@ -35,6 +35,7 @@ public boolean test(JavaClass javaClass) {
                             }
                         }
                 )
+                .allowEmptyShould(true)
                 .check(classes);
     }
 }

src/main/java/it/aboutbits/archunit/toolbox/rule/base/BlacklistMethodsArchRule.java

@@ -68,6 +68,7 @@ public interface BlacklistMethodsArchRule {
     default void no_blacklisted_methods_are_used(JavaClasses classes) {
         classes()
                 .should(new NotUseBlacklistedMethods())
+                .allowEmptyShould(true)
                 .check(classes);
     }
 

src/main/java/it/aboutbits/archunit/toolbox/rule/base/EnforceJspecifyArchRule.java

@@ -21,6 +21,7 @@ default void top_level_classes_must_be_annotated_with_jspecify(JavaClasses class
                 .beAnnotatedWith(org.jspecify.annotations.NullMarked.class)
                 .orShould()
                 .beAnnotatedWith(org.jspecify.annotations.NullUnmarked.class)
+                .allowEmptyShould(true)
                 .check(classes);
     }
 }

src/main/java/it/aboutbits/archunit/toolbox/rule/base/NoSystemOutOrErrArchRule.java

@@ -20,6 +20,7 @@ public interface NoSystemOutOrErrArchRule {
     default void no_system_out_or_err_is_used(JavaClasses classes) {
         classes()
                 .should(new NotUseSystemOutOrErr())
+                .allowEmptyShould(true)
                 .check(classes);
     }
 

src/main/java/it/aboutbits/archunit/toolbox/rule/base/RecordPropertiesMustBeAccessedViaAccessorArchRule.java

@@ -45,5 +45,6 @@ public void check(JavaField field, ConditionEvents events) {
                         }
                     }
                 }
-            });
+            })
+            .allowEmptyShould(true);
 }