make the opt-outs usable once, and close the blacklist hole

Addresses the review on #4, all three points verified against reverts.

The opt-outs are read with areNotMetaAnnotatedWith / isMetaAnnotatedWith instead
of the direct-only variants, so a project carries @ArchIgnoreNoProductionCounterpart
on one stereotype of its own rather than repeating it on 74 classes. ArchUnit counts
a direct annotation as meta-annotated, so annotating a single class still works.
@ArchIgnoreGroupName gets the same treatment in all three places it is read: it is
the sibling opt-out with the identical ergonomics problem, and leaving it direct-only
would be half a fix.

Architecture tests are exempted from the production-counterpart rule by package,
via .._architecture.. alongside .._support.. / .._config.., so dropping the
hardcoded "ArchitectureTest" name does not push boilerplate onto every consumer.
Deliberately not added to TestClassVisibilityArchRule: being package private is as
achievable for an architecture test as for any other test, so the two exclusion
lists encode different facts and are meant to differ.

org.junit.jupiter.api.Assertions.assertThrowsExactly is blacklisted again. It only
ever existed under the AssertJ namespace that the previous commit removed, so the
cleanup dropped the house rule along with the bogus entry. Now covered by a fixture
that actually calls it, not only by a list assertion.

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

Author: SirCotare

readme.md

@@ -73,7 +73,26 @@ Two annotations exempt a class from a specific rule. Neither is meta-annotated w
 | `@ArchIgnoreGroupName` | a `@Nested` test class | needing a production method of the same name, for a class that only groups tests |
 
 Use `@ArchIgnoreNoProductionCounterpart` for a test named after the behaviour it describes rather than
-after a production class, and on your own `ArchitectureTest`.
+after a production class.
+
+Both are read as meta-annotations, so a project declares its intent once on its own stereotype instead
+of repeating the annotation on every class:
+
+```java
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@ArchIgnoreNoProductionCounterpart
+public @interface BusinessTest {
+}
+```
+
+Annotating a single class directly still works — ArchUnit counts a direct annotation as
+meta-annotated.
+
+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.
 
 ## Local Development
 

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

@@ -24,6 +24,7 @@ public interface BlacklistMethodsArchRule {
                     // We should use `assertThatExceptionOfType(...).isThrownBy(...)` instead of `assertThatThrownBy(...)`
                     "org.assertj.core.api.Assertions.assertThatThrownBy",
                     "org.junit.jupiter.api.Assertions.assertThrows",
+                    "org.junit.jupiter.api.Assertions.assertThrowsExactly",
                     "org.junit.jupiter.api.Assertions.assertDoesNotThrow",
                     // assertThat (allowed is only org.assertj.core.api.Assertions.assertThat)
                     "org.assertj.core.api.AssertionsForClassTypes.assertThat",

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

@@ -19,13 +19,24 @@ public interface TestClassInCorrectPackageArchRule {
     default void test_classes_should_be_in_the_same_package_as_their_production_code(JavaClasses classes) {
         classes().that(TestClassNames.testClasses())
                 .and()
-                .areNotAnnotatedWith(org.junit.jupiter.api.Disabled.class)
+                .areNotMetaAnnotatedWith(org.junit.jupiter.api.Disabled.class)
                 .and()
-                .areNotAnnotatedWith(com.tngtech.archunit.junit.ArchIgnore.class)
+                .areNotMetaAnnotatedWith(com.tngtech.archunit.junit.ArchIgnore.class)
                 .and()
-                .areNotAnnotatedWith(it.aboutbits.archunit.toolbox.support.ArchIgnoreNoProductionCounterpart.class)
+                /*
+                 * Meta-annotated, not annotated: a project marks its scenario tests with one
+                 * stereotype of its own that carries this annotation, rather than repeating the
+                 * annotation on every class. ArchUnit counts a direct annotation as meta-annotated,
+                 * so annotating a single class still works.
+                 */
+                .areNotMetaAnnotatedWith(it.aboutbits.archunit.toolbox.support.ArchIgnoreNoProductionCounterpart.class)
                 .and()
-                .resideOutsideOfPackages(".._support..", ".._config..")
+                /*
+                 * An architecture test is named after no production class by definition. Excluded by
+                 * package here, but deliberately not in TestClassVisibilityArchRule: being package
+                 * private is just as achievable for an architecture test as for any other test.
+                 */
+                .resideOutsideOfPackages(".._support..", ".._config..", ".._architecture..")
                 .should(new BeInTheSamePackageAsTheProductionClass(classes))
                 .allowEmptyShould(true)
                 .check(classes);

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

@@ -23,15 +23,15 @@ public interface TestNestedClassMatchNameArchRule {
     default void nested_test_classes_have_matching_production_method_name(JavaClasses classes) {
         classes().that(TestClassNames.testClasses())
                 .and()
-                .areNotAnnotatedWith(org.junit.jupiter.api.Disabled.class)
+                .areNotMetaAnnotatedWith(org.junit.jupiter.api.Disabled.class)
                 .and()
-                .areNotAnnotatedWith(com.tngtech.archunit.junit.ArchIgnore.class)
+                .areNotMetaAnnotatedWith(com.tngtech.archunit.junit.ArchIgnore.class)
                 .and()
                 /*
                  * A test class that declares it has no production counterpart has no production
                  * methods to match its @Nested classes against either.
                  */
-                .areNotAnnotatedWith(it.aboutbits.archunit.toolbox.support.ArchIgnoreNoProductionCounterpart.class)
+                .areNotMetaAnnotatedWith(it.aboutbits.archunit.toolbox.support.ArchIgnoreNoProductionCounterpart.class)
                 .should(new HaveNestedClassesThatHaveAMatchingProductionMethodName(classes))
                 .allowEmptyShould(true)
                 .check(classes);
@@ -53,7 +53,7 @@ public void check(JavaClass testClass, ConditionEvents events) {
                     .stream()
                     .filter(clazz -> clazz.getName().startsWith(testClass.getName() + "$")
                             && clazz.isAnnotatedWith(org.junit.jupiter.api.Nested.class)
-                            && !clazz.isAnnotatedWith(it.aboutbits.archunit.toolbox.support.ArchIgnoreGroupName.class)
+                            && !clazz.isMetaAnnotatedWith(it.aboutbits.archunit.toolbox.support.ArchIgnoreGroupName.class)
                             && !clazz.getName().endsWith("$Validation")
                     )
                     .collect(Collectors.toSet());
@@ -83,7 +83,7 @@ public void check(JavaClass testClass, ConditionEvents events) {
                         .stream()
                         .anyMatch(clazz -> clazz.getName().startsWith(nestedClass.getName() + "$")
                                 && clazz.isAnnotatedWith(org.junit.jupiter.api.Nested.class)
-                                && !clazz.isAnnotatedWith(it.aboutbits.archunit.toolbox.support.ArchIgnoreGroupName.class)
+                                && !clazz.isMetaAnnotatedWith(it.aboutbits.archunit.toolbox.support.ArchIgnoreGroupName.class)
                                 && !clazz.getName().endsWith("$Validation")
                         )
                 ) {

src/main/java/it/aboutbits/archunit/toolbox/rule/common/ControllerRequestMappingsMustBeSecurityTested.java

@@ -91,8 +91,8 @@ public void check(JavaMethod method, ConditionEvents events) {
                     .stream()
                     .anyMatch(clazz -> isExpectedNestedClass(clazz.getName(), expectedNestedClassName)
                             && clazz.isAnnotatedWith(org.junit.jupiter.api.Nested.class)
-                            && !clazz.isAnnotatedWith(com.tngtech.archunit.junit.ArchIgnore.class)
-                            && !clazz.isAnnotatedWith(it.aboutbits.archunit.toolbox.support.ArchIgnoreGroupName.class)
+                            && !clazz.isMetaAnnotatedWith(com.tngtech.archunit.junit.ArchIgnore.class)
+                            && !clazz.isMetaAnnotatedWith(it.aboutbits.archunit.toolbox.support.ArchIgnoreGroupName.class)
                     );
 
             if (!nestedMethodTestClassFound) {

src/test/java/it/aboutbits/archunit/fixture/blacklistmethods/badjunitassertion/CallsJunitAssertThrowsExactly.java

@@ -0,0 +1,11 @@
+package it.aboutbits.archunit.fixture.blacklistmethods.badjunitassertion;
+
+import org.junit.jupiter.api.Assertions;
+
+public class CallsJunitAssertThrowsExactly {
+    public void check() {
+        Assertions.assertThrowsExactly(IllegalStateException.class, () -> {
+            throw new IllegalStateException();
+        });
+    }
+}

src/test/java/it/aboutbits/archunit/fixture/nestedclassname/goodmetagroup/TestGroup.java

@@ -0,0 +1,16 @@
+package it.aboutbits.archunit.fixture.nestedclassname.goodmetagroup;
+
+import it.aboutbits.archunit.toolbox.support.ArchIgnoreGroupName;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// A project's own marker for a purely organisational @Nested class, carrying the opt-out as a
+/// meta-annotation.
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@ArchIgnoreGroupName
+public @interface TestGroup {
+}

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

@@ -0,0 +1,6 @@
+package it.aboutbits.archunit.fixture.nestedclassname.goodmetagroup;
+
+public class Widget {
+    public void doWork() {
+    }
+}

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

@@ -0,0 +1,16 @@
+package it.aboutbits.archunit.fixture.nestedclassname.goodmetagroup;
+
+import org.junit.jupiter.api.Nested;
+
+class WidgetTest {
+    /// Matches Widget.doWork(), so the rule has a nested class to actually check.
+    @Nested
+    class DoWork {
+    }
+
+    /// Groups tests only. Widget has no someGrouping() method, and must not be expected to.
+    @Nested
+    @TestGroup
+    class SomeGrouping {
+    }
+}

src/test/java/it/aboutbits/archunit/fixture/nestedclassname/goodmetaoptout/BusinessScenario.java

@@ -0,0 +1,15 @@
+package it.aboutbits.archunit.fixture.nestedclassname.goodmetaoptout;
+
+import it.aboutbits.archunit.toolbox.support.ArchIgnoreNoProductionCounterpart;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// A project's own test stereotype, carrying the opt-out as a meta-annotation.
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@ArchIgnoreNoProductionCounterpart
+public @interface BusinessScenario {
+}