small improvements

src/main/java/io/quarkus/gizmo2/MethodTyped.java

@@ -52,6 +52,13 @@ default boolean isPrimitiveReturn() {
         return returnType().isPrimitive();
     }
 
+    /**
+     * {@return the number of parameters}
+     */
+    default int parameterCount() {
+        return type().parameterCount();
+    }
+
     /**
      * {@return the type of the parameter with the given index}
      *

src/main/java/io/quarkus/gizmo2/creator/BlockCreator.java

@@ -381,7 +381,7 @@ default void dec(Assignable var) {
     // arrays
 
     /**
-     * Create a new, empty array of the given type.
+     * Create a new, empty array of the given type with given size.
      *
      * @param componentType the component type (must not be {@code null})
      * @param size the size of the array (must not be {@code null})
@@ -390,7 +390,18 @@ default void dec(Assignable var) {
     Expr newEmptyArray(ClassDesc componentType, Expr size);
 
     /**
-     * Create a new, empty array of the given type.
+     * Create a new, empty array of the given type with given size.
+     *
+     * @param componentType the component type (must not be {@code null})
+     * @param size the size of the array
+     * @return the expression for the new array (not {@code null})
+     */
+    default Expr newEmptyArray(ClassDesc componentType, int size) {
+        return newEmptyArray(componentType, Constant.of(size));
+    }
+
+    /**
+     * Create a new, empty array of the given type with given size.
      *
      * @param componentType the component type (must not be {@code null})
      * @param size the size of the array (must not be {@code null})
@@ -400,6 +411,17 @@ default Expr newEmptyArray(Class<?> componentType, Expr size) {
         return newEmptyArray(Util.classDesc(componentType), size);
     }
 
+    /**
+     * Create a new, empty array of the given type with given size.
+     *
+     * @param componentType the component type (must not be {@code null})
+     * @param size the size of the array
+     * @return the expression for the new array (not {@code null})
+     */
+    default Expr newEmptyArray(Class<?> componentType, int size) {
+        return newEmptyArray(Util.classDesc(componentType), Constant.of(size));
+    }
+
     /**
      * Create a new array with the given type, initialized with the given values.
      *
@@ -2514,7 +2536,7 @@ default void returnIntZero() {
      * @param type the exception type (must not be {@code null})
      */
     default void throw_(ClassDesc type) {
-        throw_(new_(type, List.of()));
+        throw_(new_(type));
     }
 
     /**
@@ -2524,7 +2546,17 @@ default void throw_(ClassDesc type) {
      * @param message the message (must not be {@code null})
      */
     default void throw_(ClassDesc type, String message) {
-        throw_(new_(type, List.of(Constant.of(message))));
+        throw_(new_(type, Constant.of(message)));
+    }
+
+    /**
+     * Throw a new exception of the given type with a message.
+     *
+     * @param type the exception type (must not be {@code null})
+     * @param message the message (must not be {@code null})
+     */
+    default void throw_(ClassDesc type, Expr message) {
+        throw_(new_(type, message));
     }
 
     /**
@@ -2540,7 +2572,7 @@ default void throw_(Class<? extends Throwable> type) {
      * Throw a new exception of the given type with a message.
      *
      * @param type the exception type (must not be {@code null})
-     * @param message the message (must not be {@code null})
+     * @param message the message
      */
     default void throw_(Class<? extends Throwable> type, String message) {
         if (message == null) {
@@ -2550,6 +2582,20 @@ default void throw_(Class<? extends Throwable> type, String message) {
         }
     }
 
+    /**
+     * Throw a new exception of the given type with a message.
+     *
+     * @param type the exception type (must not be {@code null})
+     * @param message the message
+     */
+    default void throw_(Class<? extends Throwable> type, Expr message) {
+        if (message == null) {
+            throw_(type);
+        } else {
+            throw_(Util.classDesc(type), message);
+        }
+    }
+
     // useful helpers/utilities
 
     /**

src/main/java/io/quarkus/gizmo2/desc/ConstructorDesc.java

@@ -5,6 +5,7 @@
 import java.lang.constant.MethodTypeDesc;
 import java.lang.invoke.MethodType;
 import java.util.List;
+import java.util.stream.Stream;
 
 import io.quarkus.gizmo2.impl.ConstructorDescImpl;
 import io.quarkus.gizmo2.impl.Util;
@@ -16,7 +17,7 @@ public sealed interface ConstructorDesc extends MemberDesc permits ConstructorDe
     /**
      * Construct a new instance.
      *
-     * @param owner the descriptor of the class which contains the member (must not be {@code null})
+     * @param owner the descriptor of the class which contains the constructor (must not be {@code null})
      * @param type the descriptor of the type of the constructor (must not be {@code null})
      * @return the constructor descriptor (not {@code null})
      */
@@ -27,7 +28,7 @@ static ConstructorDesc of(ClassDesc owner, MethodTypeDesc type) {
     /**
      * Construct a new instance for a zero-parameter constructor.
      *
-     * @param owner the descriptor of the class which contains the member (must not be {@code null})
+     * @param owner the descriptor of the class which contains the constructor (must not be {@code null})
      * @return the constructor descriptor (not {@code null})
      */
     static ConstructorDesc of(ClassDesc owner) {
@@ -37,7 +38,30 @@ static ConstructorDesc of(ClassDesc owner) {
     /**
      * Construct a new instance.
      *
-     * @param owner the descriptor of the class which contains the member (must not be {@code null})
+     * @param owner the descriptor of the class which contains the constructor (must not be {@code null})
+     * @param paramTypes a list of parameter types (must not be {@code null})
+     * @return the constructor descriptor (not {@code null})
+     */
+    static ConstructorDesc of(ClassDesc owner, Class<?>... paramTypes) {
+        ClassDesc[] params = Stream.of(paramTypes).map(Util::classDesc).toArray(ClassDesc[]::new);
+        return of(owner, MethodTypeDesc.of(ConstantDescs.CD_void, params));
+    }
+
+    /**
+     * Construct a new instance.
+     *
+     * @param owner the descriptor of the class which contains the constructor (must not be {@code null})
+     * @param paramTypes a list of descriptors corresponding to the parameter types (must not be {@code null})
+     * @return the constructor descriptor (not {@code null})
+     */
+    static ConstructorDesc of(ClassDesc owner, ClassDesc... paramTypes) {
+        return of(owner, MethodTypeDesc.of(ConstantDescs.CD_void, paramTypes));
+    }
+
+    /**
+     * Construct a new instance.
+     *
+     * @param owner the descriptor of the class which contains the constructor (must not be {@code null})
      * @param paramTypes a list of descriptors corresponding to the parameter types (must not be {@code null})
      * @return the constructor descriptor (not {@code null})
      */
@@ -48,7 +72,7 @@ static ConstructorDesc of(ClassDesc owner, List<ClassDesc> paramTypes) {
     /**
      * Construct a new instance.
      *
-     * @param owner the class which contains the member (must not be {@code null})
+     * @param owner the class which contains the constructor (must not be {@code null})
      * @param type the descriptor of the type of the constructor (must not be {@code null})
      * @return the constructor descriptor (not {@code null})
      */
@@ -59,7 +83,7 @@ static ConstructorDesc of(Class<?> owner, MethodTypeDesc type) {
     /**
      * Construct a new instance.
      *
-     * @param owner the class which contains the member (must not be {@code null})
+     * @param owner the class which contains the constructor (must not be {@code null})
      * @param type the type of the constructor (must not be {@code null})
      * @return the constructor descriptor (not {@code null})
      */
@@ -70,7 +94,7 @@ static ConstructorDesc of(Class<?> owner, MethodType type) {
     /**
      * Construct a new instance.
      *
-     * @param owner the class which contains the member (must not be {@code null})
+     * @param owner the class which contains the constructor (must not be {@code null})
      * @param paramTypes a list of parameter types (must not be {@code null})
      * @return the constructor descriptor (not {@code null})
      */
@@ -81,7 +105,7 @@ static ConstructorDesc of(Class<?> owner, Class<?>... paramTypes) {
     /**
      * Construct a new instance.
      *
-     * @param owner the class which contains the member (must not be {@code null})
+     * @param owner the class which contains the constructor (must not be {@code null})
      * @param paramTypes a list of parameter types (must not be {@code null})
      * @return the constructor descriptor (not {@code null})
      */

src/main/java/io/quarkus/gizmo2/impl/ConstructorDescImpl.java

@@ -1,6 +1,7 @@
 package io.quarkus.gizmo2.impl;
 
 import java.lang.constant.ClassDesc;
+import java.lang.constant.ConstantDescs;
 import java.lang.constant.MethodTypeDesc;
 import java.util.Objects;
 
@@ -12,6 +13,9 @@ public final class ConstructorDescImpl implements ConstructorDesc {
     private final int hashCode;
 
     public ConstructorDescImpl(final ClassDesc owner, final MethodTypeDesc type) {
+        if (!ConstantDescs.CD_void.equals(type.returnType())) {
+            throw new IllegalArgumentException("Constructor descriptor must have a return type of void");
+        }
         this.owner = owner;
         this.type = type;
         hashCode = Objects.hash(owner, "<init>", type);

src/main/java/io/quarkus/gizmo2/impl/Item.java

@@ -18,6 +18,7 @@
 import io.quarkus.gizmo2.impl.constant.ConstantImpl;
 
 public abstract non-sealed class Item implements Expr {
+    private final String creationSite = Util.trackCreationSite();
 
     public String itemName() {
         return getClass().getSimpleName();
@@ -51,7 +52,7 @@ Node verify(Node node) {
             // we don't care about this one
             node = actual.pop(node);
         }
-        throw missing(toString());
+        throw missing();
     }
 
     /**
@@ -166,16 +167,21 @@ protected Node process(Node node, BiFunction<Item, Node, Node> op) {
      */
     protected Node forEachDependency(Node node, BiFunction<Item, Node, Node> op) {
         if (node == null) {
-            throw missing(toString());
+            throw missing();
         }
         // no dependencies
         return node.prev();
     }
 
-    static IllegalStateException missing(String itemToString) {
-        return new IllegalStateException(
-                "Item is not at its expected location (use a variable to store values which are used away from their definition site): "
-                        + itemToString);
+    private IllegalStateException missing() {
+        if (creationSite == null) {
+            return new IllegalStateException("Item " + this + " is not at its expected location (declare a LocalVar"
+                    + " to store values which are used away from their creation site)\nTo track Item creation sites"
+                    + " and get an improved exception message, add the system property `gizmo.trackCreations`");
+        } else {
+            return new IllegalStateException("Item " + this + " created at " + creationSite + " is not at its expected"
+                    + " location (declare a LocalVar to store values which are used away from their creation site)");
+        }
     }
 
     public abstract void writeCode(CodeBuilder cb, BlockCreatorImpl block);

src/main/java/io/quarkus/gizmo2/impl/Util.java

@@ -30,6 +30,9 @@ public final class Util {
      */
     public static final ClassDesc[] NO_DESCS = new ClassDesc[0];
 
+    // set system property means enabled, even with an empty value, except if the value is `false`
+    private static final boolean trackCreations = !"false".equals(System.getProperty("gizmo.trackCreations", "false"));
+
     private Util() {
     }
 
@@ -136,6 +139,18 @@ public static String detailedStackTrace() {
         return b.toString();
     }
 
+    public static String trackCreationSite() {
+        return trackCreations ? callerOutsideGizmo() : null;
+    }
+
+    private static String callerOutsideGizmo() {
+        return SW.walk(stream -> stream
+                .filter(it -> !it.getClassName().startsWith("io.quarkus.gizmo2"))
+                .findFirst()
+                .map(it -> it.getClassName() + "." + it.getMethodName() + "():" + it.getLineNumber())
+                .orElseThrow(IllegalStateException::new));
+    }
+
     // TODO: move to using smallrye-common-search
     public static int binarySearch(int from, int to, IntPredicate test) {
         int low = from;