4.x: Improve annotation processing diagnostics (helidon-io#11281)

* Improve annotation processing diagnostics

- Add originatingElement to io.helidon.common.types.Annotation
- Update CodegenExceptiont to take multiple originating elements using a varag (backward compatible)
- Update AptProcessor to delegate the logging of CodegenException to AptLogger
- Update AptLogger to unwrap all originating elements correctly

* Review feedback

Author: romain-grecourt

builder/tests/common-types/src/main/java/io/helidon/common/types/AnnotationBlueprint.java

@@ -99,6 +99,15 @@ interface AnnotationBlueprint {
     @Option.Singular
     List<Annotation> metaAnnotations();
 
+    /**
+     * The element used to create this instance.
+     * The type of the object depends on the environment.
+     *
+     * @return originating element
+     */
+    @Option.Redundant
+    Optional<Object> originatingElement();
+
     /**
      * The value property.
      *

codegen/apt/src/main/java/io/helidon/codegen/apt/AptAnnotationFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2025 Oracle and/or its affiliates.
+ * Copyright (c) 2023, 2026 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -87,6 +87,7 @@ private static Optional<Annotation> createAnnotation(Elements elements, Annotati
 
         return Optional.of(builder
                                    .typeName(val)
+                                   .originatingElement(am)
                                    .values(extractAnnotationValues(am, elements))
                                    .build());
     }

codegen/apt/src/main/java/io/helidon/codegen/apt/AptLogger.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024 Oracle and/or its affiliates.
+ * Copyright (c) 2023, 2026 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,13 +23,15 @@
 import javax.lang.model.element.AnnotationMirror;
 import javax.lang.model.element.AnnotationValue;
 import javax.lang.model.element.Element;
-import javax.lang.model.element.TypeElement;
 import javax.tools.Diagnostic;
 
 import io.helidon.codegen.CodegenEvent;
 import io.helidon.codegen.CodegenLogger;
 import io.helidon.codegen.CodegenOptions;
+import io.helidon.common.types.Annotation;
+import io.helidon.common.types.TypeInfo;
 import io.helidon.common.types.TypeName;
+import io.helidon.common.types.TypedElementInfo;
 
 class AptLogger implements CodegenLogger {
     private final System.Logger logger;
@@ -47,15 +49,12 @@ public void log(CodegenEvent event) {
         // we always log to system logger if info or below
         // we only log to messager if info or above
         switch (event.level()) {
-        case TRACE, DEBUG -> logSystem(event);
-        case INFO -> {
-            logSystem(event);
-            logApt(event);
-        }
-        case WARNING, ERROR -> {
-            logApt(event);
-        }
-        default -> logSystem(event);
+            case INFO -> {
+                logSystem(event);
+                logApt(event);
+            }
+            case WARNING, ERROR -> logApt(event);
+            default -> logSystem(event);
         }
     }
 
@@ -87,23 +86,40 @@ private AnnotationMirror findAnnotation(List<Object> objects) {
         for (Object object : objects) {
             if (object instanceof AnnotationMirror mirror) {
                 return mirror;
+            } else if (object instanceof Annotation annot) {
+                var o = annot.originatingElement().orElse(null);
+                if (o instanceof AnnotationMirror mirror) {
+                    return mirror;
+                }
             }
         }
         return null;
     }
 
     private Element findElement(List<Object> objects) {
-        for (Object object : objects) {
-            if (object instanceof Element e) {
-                return e;
+        for (var object : objects) {
+            var element = findElement(object);
+            if (element != null) {
+                return element;
             }
         }
-        for (Object object : objects) {
-            if (object instanceof TypeName t) {
-                TypeElement element = env.getElementUtils().getTypeElement(t.declaredName());
-                if (element != null) {
-                    return element;
-                }
+        return null;
+    }
+
+    private Element findElement(Object orig) {
+        if (orig instanceof Element element) {
+            return element;
+        } else if (orig instanceof TypeName typeName) {
+            return env.getElementUtils().getTypeElement(typeName.declaredName());
+        } else if (orig instanceof TypeInfo typeInfo) {
+            var o = typeInfo.originatingElement().orElse(null);
+            if (o instanceof Element element) {
+                return element;
+            }
+        } else if (orig instanceof TypedElementInfo elementInfo) {
+            var o = elementInfo.originatingElement().orElse(null);
+            if (o instanceof Element element) {
+                return element;
             }
         }
         return null;

codegen/apt/src/main/java/io/helidon/codegen/apt/AptProcessor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2025 Oracle and/or its affiliates.
+ * Copyright (c) 2023, 2026 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -50,6 +50,11 @@
 
 /**
  * Annotation processor that maps APT types to Helidon types, and invokes {@link io.helidon.codegen.Codegen}.
+ * <p>
+ * <b>This class is NOT part of any supported API.
+ * If you write code that depends on this, you do so at your own risk.
+ * This code and its internal interfaces are subject to change or deletion without notice.</b>
+ * </p>
  */
 @SuppressWarnings("removal")
 public final class AptProcessor extends AbstractProcessor {
@@ -61,9 +66,7 @@ public final class AptProcessor extends AbstractProcessor {
     /**
      * Only for {@link java.util.ServiceLoader}, to be loaded by compiler.
      */
-    @Deprecated
     public AptProcessor() {
-        super();
     }
 
     @Override
@@ -106,18 +109,8 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
         try {
             return doProcess(annotations, roundEnv);
         } catch (CodegenException e) {
-            Object originatingElement = e.originatingElement()
-                    .orElse(null);
-            if (originatingElement instanceof Element element) {
-                processingEnv.getMessager().printError(e.getMessage(), element);
-            } else if (originatingElement instanceof TypeName typeName) {
-                processingEnv.getMessager().printError(e.getMessage() + ", source: " + typeName.fqName());
-            } else {
-                if (originatingElement != null) {
-                    processingEnv.getMessager().printError(e.getMessage() + ", source: " + originatingElement);
-                }
-            }
-            throw e;
+            ctx.logger().log(e.toEvent(System.Logger.Level.ERROR));
+            return true;
         } finally {
             thread.setContextClassLoader(previousClassloader);
         }

codegen/codegen/src/main/java/io/helidon/codegen/CodegenException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024 Oracle and/or its affiliates.
+ * Copyright (c) 2023, 2026 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@
 
 package io.helidon.codegen;
 
+import java.util.List;
 import java.util.Optional;
 
 /**
@@ -27,7 +28,7 @@ public class CodegenException extends RuntimeException {
      * Originating element, depends on which codegen implementation is used.
      * For annotation processor, this could be the Element that caused this exception.
      */
-    private final Object originatingElement;
+    private final List<Object> originatingElement;
 
     /**
      * Constructor with a message.
@@ -36,7 +37,7 @@ public class CodegenException extends RuntimeException {
      */
     public CodegenException(String message) {
         super(message);
-        this.originatingElement = null;
+        this.originatingElement = List.of();
     }
 
     /**
@@ -47,30 +48,29 @@ public CodegenException(String message) {
      */
     public CodegenException(String message, Throwable cause) {
         super(message, cause);
-        this.originatingElement = null;
+        this.originatingElement = List.of();
     }
 
     /**
      * Constructor with a message and an originating element.
      *
-     * @param message            descriptive message
-     * @param originatingElement element that caused this exception
+     * @param message             descriptive message
+     * @param originatingElements elements that caused this exception
      */
-    public CodegenException(String message, Object originatingElement) {
-        super(message);
-        this.originatingElement = originatingElement;
+    public CodegenException(String message, Object... originatingElements) {
+        this(message, null, originatingElements);
     }
 
     /**
      * Constructor with a message, cause, and an originating element.
      *
-     * @param message            descriptive message
-     * @param cause              throwable triggering this exception
-     * @param originatingElement element that caused this exception
+     * @param message             descriptive message
+     * @param cause               throwable triggering this exception
+     * @param originatingElements element that caused this exception
      */
-    public CodegenException(String message, Throwable cause, Object originatingElement) {
+    public CodegenException(String message, Throwable cause, Object... originatingElements) {
         super(message, cause);
-        this.originatingElement = originatingElement;
+        this.originatingElement = List.of(originatingElements);
     }
 
     /**
@@ -82,7 +82,16 @@ public CodegenException(String message, Throwable cause, Object originatingEleme
      * @return originating element of this exception
      */
     public Optional<Object> originatingElement() {
-        return Optional.ofNullable(originatingElement);
+        return originatingElement.stream().findFirst();
+    }
+
+    /**
+     * Originating elements.
+     *
+     * @return originating elements of this exception
+     */
+    public List<Object> originatingElements() {
+        return originatingElement;
     }
 
     /**
@@ -112,7 +121,7 @@ public CodegenEvent toEvent(System.Logger.Level level) {
                 .level(level)
                 .message(getMessage())
                 .throwable(this)
-                .update(it -> originatingElement().ifPresent(it::addObject))
+                .update(it -> it.addObjects(originatingElements()))
                 .build();
     }
 }

codegen/codegen/src/main/java/io/helidon/codegen/CodegenLogger.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024 Oracle and/or its affiliates.
+ * Copyright (c) 2023, 2026 Oracle and/or its affiliates.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,8 @@
 
 package io.helidon.codegen;
 
+import java.util.List;
+
 /**
  * An abstraction for logging code processing and generation events.
  */
@@ -44,11 +46,13 @@ static CodegenLogger create(System.Logger logger) {
      *
      * @param level   log level to use
      * @param message message to log
+     * @param objects origin elements
      */
-    default void log(System.Logger.Level level, String message) {
+    default void log(System.Logger.Level level, String message, Object... objects) {
         log(CodegenEvent.builder()
-                    .level(level)
-                    .message(message)
-                    .build());
+                .level(level)
+                .message(message)
+                .objects(List.of(objects))
+                .build());
     }
 }