address review: lookup cost, null mappings, and an upgrade note

Four review comments on #4.

The two counterpart lookups scanned every imported class per test class. JavaClasses
is map-backed by fully qualified name, so both are now contain()/get(). New fixture
nestedclassname.goodgroup pins that a production class nested inside another is still
found, since its name contains a '$' and nothing covered that before - without it a
keying difference would have passed silently, the badgroup fixture expecting a
violation either way.

SortMappings gets the null-value fixture: a static field that reads back as null
yields nothing to compare, so the rule reports rather than calling it exhaustive.
The undeterminable-enum and non-enum-key paths remain untested.

Readme gains an upgrade note naming what breaks when a consumer moves off 1.2.0 -
revived rules surfacing real violations, and the new empty-import failure - and the
opt-out section now says that @disabled and @ArchIgnore are matched through
meta-annotations too, so a stereotype carrying either exempts its classes.

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

Author: SirCotare

readme.md

@@ -16,6 +16,25 @@ Add this library to the classpath by adding the following maven dependency. Vers
 </dependency>
 ```
 
+## Upgrading to 1.3.0
+
+**This release will fail builds that passed on 1.2.0, on purpose.** Nine rules were silently
+reporting success because they matched nothing; fixing them turns real violations into build
+failures for the first time. Expect two kinds:
+
+- **Revived rules surface real violations.** Chiefly the two that were fully dead:
+  `test_classes_should_be_in_the_same_package_as_their_production_code` and
+  `nested_test_classes_have_matching_production_method_name`. Triage them with the opt-out
+  stereotype described under [Opting out](#opting-out) before annotating classes one at a time.
+  The stricter paths (`getCodeUnits()` reaching constructors and field initializers, exact
+  security-test matching, `SortMappings` reporting what it cannot read) surfaced nothing in a
+  large codebase, so noise from those is unlikely.
+- **`analyzed_packages_must_contain_classes` is new and fails on an empty import.** If the
+  packages given to `@AnalyzeClasses` are mistyped or have moved, that is now a failure instead
+  of 13 rules quietly passing.
+
+Nothing else needs a migration: no rule fails over code your project does not have.
+
 ## Usage
 
 Implement one of the provided rule collections in your own architecture test.
@@ -90,6 +109,12 @@ public @interface BusinessTest {
 Annotating a single class directly still works — ArchUnit counts a direct annotation as
 meta-annotated.
 
+The same applies to `@Disabled` and ArchUnit's `@ArchIgnore`, which these rules also honour: a
+stereotype that carries either of them exempts every class using it. That matches how JUnit and the
+ArchUnit engine themselves read those two annotations — a class whose tests do not run is not held to
+naming rules — but it does mean a stereotype can exempt more than it appears to, so keep an eye on
+what your own test annotations carry.
+
 Architecture tests need neither: any class in a package named `_architecture` is exempt from the
 production-counterpart rule, alongside the existing `_support` and `_config` exclusions. Use the
 annotation for the one-off that lives elsewhere.

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

@@ -61,11 +61,9 @@ public void check(JavaClass testClass, ConditionEvents events) {
             var productionClassSimpleName = TestClassNames.productionClassSimpleName(testClass.getSimpleName());
             var productionClassFullName = testClass.getPackageName() + "." + productionClassSimpleName;
 
-            var productionClass = allClasses.stream()
-                    .filter(clazz -> clazz.getFullName().equals(productionClassFullName))
-                    .findFirst();
-
-            if (productionClass.isEmpty()) {
+            // JavaClasses is map-backed by fully qualified name, so this is a lookup rather than a
+            // scan of every imported class per test class.
+            if (!allClasses.contain(productionClassFullName)) {
                 var message = "Test class <%s> does not have a matching production class <%s> in the same package (%s.java:0)".formatted(
                         testClass.getFullName(),
                         productionClassFullName,

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

@@ -122,16 +122,15 @@ public void check(JavaClass testClass, ConditionEvents events) {
                         enclosingClassSuffix.orElse("")
                 );
 
-                var productionClassOptional = allClasses.stream()
-                        .filter(clazz -> clazz.getFullName().equals(productionClassName))
-                        .findFirst();
-
                 /*
                  * Reported whether or not the @Nested class is inside a @Nested group. Without a
                  * production class there is nothing to match the name against, so staying silent
                  * here means the @Nested class is never checked at all.
+                 *
+                 * JavaClasses is map-backed by fully qualified name, so this is a lookup rather than
+                 * a scan of every imported class per @Nested class.
                  */
-                if (productionClassOptional.isEmpty()) {
+                if (!allClasses.contain(productionClassName)) {
                     var message = "The @Nested test class <%s> (%s.java:%s)%ndoes not have a matching production class <%s>".formatted(
                             nestedClass.getName(),
                             nestedClassBaseClassSimpleName,
@@ -140,7 +139,7 @@ public void check(JavaClass testClass, ConditionEvents events) {
                     );
                     events.add(SimpleConditionEvent.violated(nestedClass, message));
                 } else {
-                    var productionClass = productionClassOptional.get();
+                    var productionClass = allClasses.get(productionClassName);
 
                     var methodExists = productionClass.getMethods()
                             .stream()

src/test/java/it/aboutbits/archunit/fixture/nestedclassname/goodgroup/Widget.java

@@ -0,0 +1,8 @@
+package it.aboutbits.archunit.fixture.nestedclassname.goodgroup;
+
+public class Widget {
+    public static class DeleteAction {
+        public void deleteAll() {
+        }
+    }
+}

src/test/java/it/aboutbits/archunit/fixture/nestedclassname/goodgroup/WidgetTest.java

@@ -0,0 +1,14 @@
+package it.aboutbits.archunit.fixture.nestedclassname.goodgroup;
+
+import org.junit.jupiter.api.Nested;
+
+/// The @Nested group maps onto the production nested class Widget$DeleteAction, so the lookup has to
+/// resolve a fully qualified name containing a '$'.
+class WidgetTest {
+    @Nested
+    class DeleteAction {
+        @Nested
+        class DeleteAll {
+        }
+    }
+}

src/test/java/it/aboutbits/archunit/fixture/sortmappings/badnullvalue/WidgetSort.java

@@ -0,0 +1,6 @@
+package it.aboutbits.archunit.fixture.sortmappings.badnullvalue;
+
+public enum WidgetSort {
+    NAME,
+    CREATED_AT
+}

src/test/java/it/aboutbits/archunit/fixture/sortmappings/badnullvalue/WidgetStore.java

@@ -0,0 +1,14 @@
+package it.aboutbits.archunit.fixture.sortmappings.badnullvalue;
+
+import it.aboutbits.springboot.toolbox.persistence.SortMappings;
+import it.aboutbits.springboot.toolbox.stereotype.Store;
+
+/// A field that reads back as null yields no mappings to compare, so the rule cannot verify it.
+@Store("widget")
+public class WidgetStore {
+    static final SortMappings<WidgetSort> SORT_MAPPINGS = null;
+
+    public Object mappings() {
+        return SORT_MAPPINGS;
+    }
+}

src/test/java/it/aboutbits/archunit/toolbox/rule/base/TestNestedClassMatchNameArchRuleTest.java

@@ -46,6 +46,13 @@ void a_nested_test_class_whose_production_class_is_missing_entirely_is_reported(
                 .hasMessageContaining("does not have a matching production class");
     }
 
+    /// Pins that a production class nested inside another is found: its fully qualified name
+    /// contains a '$', and the lookup is by that name.
+    @Test
+    void a_nested_group_matching_a_production_nested_class_is_accepted() {
+        nested_test_classes_have_matching_production_method_name(fixture("nestedclassname.goodgroup"));
+    }
+
     @Test
     void a_nested_test_class_matching_a_production_method_is_accepted() {
         nested_test_classes_have_matching_production_method_name(fixture("nestedclassname.good"));

src/test/java/it/aboutbits/archunit/toolbox/rule/common/SortMappingsExhaustiveArchRuleTest.java

@@ -34,6 +34,18 @@ void a_non_static_sort_mappings_field_is_reported() {
         assertThat(failure).hasMessageContaining("must be static");
     }
 
+    /// Reading the field succeeds but yields nothing to compare, so there is no basis on which to
+    /// call the mappings exhaustive.
+    @Test
+    void a_sort_mappings_field_that_reads_back_as_null_is_reported() {
+        var classes = fixture("sortmappings.badnullvalue");
+
+        var failure = violationOf(() -> sort_mappings_cover_all_sort_enum_values(classes));
+
+        assertThat(violationCount(failure)).isEqualTo(1);
+        assertThat(failure).hasMessageContaining("did not yield a Map (got null)");
+    }
+
     @Test
     void exhaustive_sort_mappings_are_accepted() {
         sort_mappings_cover_all_sort_enum_values(fixture("sortmappings.good"));