Issue #20120 - Introduce new DeprecatedInfo annotation (PR #8)

* Create DeprecatedInfo annotation

* Adjust javadoc

* Add annotation processor

* Add .DS_Store to gitignore

* Move pkgs

* Move pkgs 2

* More pkg renaming

* Create processor

* Add more validation to processor

* Bump up version

* Fix compilation errors

Author: philippemin

.gitignore

@@ -6,3 +6,6 @@ build
 
 # Intellij IDEA folder
 .idea
+
+# macOS system files
+.DS_Store

build.gradle

@@ -41,9 +41,11 @@ dependencies {
     implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
     implementation 'jakarta.annotation:jakarta.annotation-api:3.0.0'
     implementation 'org.slf4j:slf4j-api:2.0.12'
+    implementation 'com.google.auto.service:auto-service:1.1.1'
 
     compileOnly 'org.projectlombok:lombok:1.18.30'
     annotationProcessor 'org.projectlombok:lombok:1.18.30'
+    annotationProcessor 'com.google.auto.service:auto-service:1.1.1'
 
     testImplementation 'org.junit.jupiter:junit-jupiter:5.9.3'
     testImplementation 'org.assertj:assertj-core:3.25.3'

src/main/java/com/ziro/espresso/annotations/DeprecatedInfo.java

@@ -0,0 +1,45 @@
+package com.ziro.espresso.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Provides additional context for deprecated elements.
+ * <p>
+ * This annotation should be used in conjunction with {@code @Deprecated} to provide
+ * information about when the element was deprecated and when it's scheduled for removal.
+ * </p>
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({
+    ElementType.CONSTRUCTOR,
+    ElementType.FIELD,
+    ElementType.LOCAL_VARIABLE,
+    ElementType.METHOD,
+    ElementType.PACKAGE,
+    ElementType.MODULE,
+    ElementType.PARAMETER,
+    ElementType.TYPE
+})
+public @interface DeprecatedInfo {
+
+    /**
+     * Reference to the story/issue where this element was marked as deprecated.
+     * This field is mandatory.
+     *
+     * @return the story/issue reference where the element was deprecated
+     */
+    String deprecatedIn();
+
+    /**
+     * Reference to the story/issue where this element is scheduled for removal.
+     * This field is mandatory.
+     *
+     * @return the story/issue reference for removal
+     */
+    String removingIn();
+}

…otation/extensions/NonNullByDefault.java …presso/annotations/NonNullByDefault.javasrc/main/java/com/ziro/espresso/javax/annotation/extensions/NonNullByDefault.java renamed to src/main/java/com/ziro/espresso/annotations/NonNullByDefault.java src/main/java/com/ziro/espresso/javax/annotation/extensions/NonNullByDefault.java renamed to src/main/java/com/ziro/espresso/annotations/NonNullByDefault.java

@@ -1,4 +1,4 @@
-package com.ziro.espresso.javax.annotation.extensions;
+package com.ziro.espresso.annotations;
 
 import jakarta.annotation.Nonnull;
 import java.lang.annotation.Documented;

src/main/java/com/ziro/espresso/annotations/package-info.java

@@ -0,0 +1,2 @@
+@NonNullByDefault
+package com.ziro.espresso.annotations;

src/main/java/com/ziro/espresso/annotations/processors/DeprecatedInfoValidator.java

@@ -0,0 +1,48 @@
+package com.ziro.espresso.annotations.processors;
+
+import com.google.auto.service.AutoService;
+import com.ziro.espresso.annotations.DeprecatedInfo;
+import java.util.Set;
+import javax.annotation.processing.*;
+import javax.lang.model.SourceVersion;
+import javax.lang.model.element.Element;
+import javax.lang.model.element.TypeElement;
+import javax.tools.Diagnostic;
+
+@SupportedAnnotationTypes("com.ziro.espresso.annotations.DeprecatedInfo")
+@SupportedSourceVersion(SourceVersion.RELEASE_17)
+@AutoService(Processor.class)
+public class DeprecatedInfoValidator extends AbstractProcessor {
+
+    @Override
+    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
+        for (Element element : roundEnv.getElementsAnnotatedWith(DeprecatedInfo.class)) {
+            DeprecatedInfo info = element.getAnnotation(DeprecatedInfo.class);
+
+            if (info.deprecatedIn().trim().isEmpty()) {
+                processingEnv
+                        .getMessager()
+                        .printMessage(Diagnostic.Kind.ERROR, "deprecatedIn must not be empty", element);
+            }
+
+            if (info.removingIn().trim().isEmpty()) {
+                processingEnv
+                        .getMessager()
+                        .printMessage(Diagnostic.Kind.ERROR, "removingIn must not be empty", element);
+            }
+
+            if (element.getAnnotationMirrors().stream()
+                    .noneMatch(mirror -> mirror.getAnnotationType().toString().equals("java.lang.Deprecated"))) {
+
+                processingEnv
+                        .getMessager()
+                        .printMessage(
+                                Diagnostic.Kind.ERROR,
+                                "@DeprecatedInfo must be used together with @Deprecated",
+                                element);
+            }
+        }
+
+        return false;
+    }
+}

src/main/java/com/ziro/espresso/collections/package-info.java

@@ -1,4 +1,4 @@
 @NonNullByDefault
 package com.ziro.espresso.collections;
 
-import com.ziro.espresso.javax.annotation.extensions.NonNullByDefault;
+import com.ziro.espresso.annotations.NonNullByDefault;

src/main/java/com/ziro/espresso/fluent/exceptions/AbstractFluentExceptionSupport.java

@@ -2,7 +2,7 @@
 
 import com.google.common.base.Strings;
 import com.google.common.base.Throwables;
-import com.ziro.espresso.javax.annotation.extensions.NonNullByDefault;
+import com.ziro.espresso.annotations.NonNullByDefault;
 import jakarta.annotation.Nullable;
 import java.util.Optional;
 import java.util.function.Supplier;

src/main/java/com/ziro/espresso/fluent/exceptions/ExceptionDetailsStage.java

@@ -1,6 +1,6 @@
 package com.ziro.espresso.fluent.exceptions;
 
-import com.ziro.espresso.javax.annotation.extensions.NonNullByDefault;
+import com.ziro.espresso.annotations.NonNullByDefault;
 import java.util.function.Supplier;
 
 /**

src/main/java/com/ziro/espresso/fluent/exceptions/SystemUnhandledException.java

@@ -1,6 +1,6 @@
 package com.ziro.espresso.fluent.exceptions;
 
-import com.ziro.espresso.javax.annotation.extensions.NonNullByDefault;
+import com.ziro.espresso.annotations.NonNullByDefault;
 import jakarta.annotation.Nonnull;
 
 /**