Check that @API and @Deprecated annotations are consistent

* both must be declared
* `API.status()` must be `DEPRECATED`
* `since()` attributes must match

Author: marcphilipp

junit-jupiter-api/src/templates/resources/main/org/junit/jupiter/api/condition/JRE.java.jte

@@ -133,7 +133,7 @@ public enum JRE {
 	 * @deprecated in favor of {@link #currentJre()}
 	 */
 	@API(status = DEPRECATED, since = "5.12")
-	@Deprecated
+	@Deprecated(since = "5.12")
 	public static JRE currentVersion() {
 		return currentJre();
 	}

platform-tooling-support-tests/src/archUnit/java/platform/tooling/support/tests/ArchUnitTests.java

@@ -10,14 +10,17 @@
 
 package platform.tooling.support.tests;
 
+import static com.tngtech.archunit.base.DescribedPredicate.and;
 import static com.tngtech.archunit.base.DescribedPredicate.describe;
 import static com.tngtech.archunit.base.DescribedPredicate.not;
 import static com.tngtech.archunit.core.domain.JavaClass.Predicates.ANONYMOUS_CLASSES;
 import static com.tngtech.archunit.core.domain.JavaClass.Predicates.TOP_LEVEL_CLASSES;
 import static com.tngtech.archunit.core.domain.JavaClass.Predicates.resideInAPackage;
 import static com.tngtech.archunit.core.domain.JavaClass.Predicates.simpleName;
 import static com.tngtech.archunit.core.domain.JavaClass.Predicates.simpleNameEndingWith;
+import static com.tngtech.archunit.core.domain.JavaMember.Predicates.declaredIn;
 import static com.tngtech.archunit.core.domain.JavaModifier.PUBLIC;
+import static com.tngtech.archunit.core.domain.properties.CanBeAnnotated.Predicates.annotatedWith;
 import static com.tngtech.archunit.core.domain.properties.HasModifiers.Predicates.modifier;
 import static com.tngtech.archunit.core.domain.properties.HasName.Predicates.name;
 import static com.tngtech.archunit.core.domain.properties.HasName.Predicates.nameContaining;
@@ -26,7 +29,9 @@
 import static com.tngtech.archunit.lang.conditions.ArchPredicates.are;
 import static com.tngtech.archunit.lang.conditions.ArchPredicates.have;
 import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
+import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.members;
 import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;
+import static org.apiguardian.api.API.Status.DEPRECATED;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
@@ -35,6 +40,7 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 import java.util.Arrays;
+import java.util.Objects;
 import java.util.function.BiPredicate;
 import java.util.stream.Stream;
 
@@ -43,6 +49,8 @@
 import com.tngtech.archunit.core.domain.JavaClasses;
 import com.tngtech.archunit.core.domain.JavaPackage;
 import com.tngtech.archunit.core.domain.PackageMatcher;
+import com.tngtech.archunit.core.domain.properties.HasAnnotations;
+import com.tngtech.archunit.core.domain.properties.HasSourceCodeLocation;
 import com.tngtech.archunit.junit.AnalyzeClasses;
 import com.tngtech.archunit.junit.ArchTest;
 import com.tngtech.archunit.lang.ArchCondition;
@@ -81,7 +89,7 @@ class ArchUnitTests {
 			.and(not(describe("are Kotlin SAM type implementations", simpleName("")))) //
 			.and(not(describe("are Kotlin-generated classes that contain only top-level functions",
 				simpleNameEndingWith("Kt")))) //
-			.and(not(describe("are shadowed", resideInAPackage("..shadow..")))) //
+			.and(notShadowed()) //
 			.should().beAnnotatedWith(API.class);
 
 	@SuppressWarnings("unused")
@@ -101,6 +109,22 @@ class ArchUnitTests {
 	private final ArchRule jupiterAssertionsShouldBeSelfContained = classes().that(jupiterAssertions) //
 			.should(onlyBeAccessedByClassesThat(jupiterAssertions));
 
+	@SuppressWarnings("unused")
+	@ArchTest
+	private final ArchRule deprecatedAnnotationOnMembersShouldBeDeclaredConsistently = members() //
+			.that(annotatedWith(Deprecated.class)) //
+			.or(haveApiAnnotationWithDeprecatedStatus()) //
+			.and(declaredIn(notShadowed())) //
+			.should(haveBothAnnotationsWithMatchingSinceAttributes());
+
+	@SuppressWarnings("unused")
+	@ArchTest
+	private final ArchRule deprecatedAnnotationOnClassesShouldBeDeclaredConsistently = classes() //
+			.that(annotatedWith(Deprecated.class)) //
+			.or(haveApiAnnotationWithDeprecatedStatus()) //
+			.and(notShadowed()) //
+			.should(haveBothAnnotationsWithMatchingSinceAttributes());
+
 	@ArchTest
 	void packagesShouldBeNullMarked(JavaClasses classes) {
 		var exclusions = Stream.of( //
@@ -203,6 +227,31 @@ private static ArchCondition<? super JavaClass> haveContainerAnnotationWithSameT
 			(expectedTarget, actualTarget) -> Arrays.equals(expectedTarget.value(), actualTarget.value())));
 	}
 
+	private static <T extends HasAnnotations<?> & HasSourceCodeLocation> ArchCondition<T> haveBothAnnotationsWithMatchingSinceAttributes() {
+		return ArchCondition.from( //
+			DescribedPredicate.and( //
+				annotatedWith(Deprecated.class), haveApiAnnotationWithDeprecatedStatus(), //
+				haveSinceAttributeMatchingApiAnnotation()));
+	}
+
+	private static <T extends HasAnnotations<?> & HasSourceCodeLocation> DescribedPredicate<T> haveApiAnnotationWithDeprecatedStatus() {
+		return and(annotatedWith(API.class), describe("status() is DEPRECATED",
+			element -> element.getAnnotationOfType(API.class).status() == DEPRECATED));
+	}
+
+	private static <T extends HasAnnotations<?> & HasSourceCodeLocation> DescribedPredicate<T> haveSinceAttributeMatchingApiAnnotation() {
+		return describe("@API(since) equals @Deprecated(since)", element -> {
+			var deprecatedAnnotation = element.getAnnotationOfType(Deprecated.class);
+			var apiAnnotation = element.getAnnotationOfType(API.class);
+			return deprecatedAnnotation.since() != null //
+					&& Objects.equals(deprecatedAnnotation.since(), apiAnnotation.since());
+		});
+	}
+
+	private static DescribedPredicate<JavaClass> notShadowed() {
+		return not(describe("are shadowed", resideInAPackage("..shadow..")));
+	}
+
 	private static class RepeatableAnnotationPredicate<T extends Annotation> extends DescribedPredicate<JavaClass> {
 
 		private final Class<T> annotationType;