feat: dictionary provider for Strings and Integrals

src/main/java/com/code_intelligence/jazzer/junit/BUILD.bazel

@@ -38,6 +38,7 @@ java_library(
         "//examples/junit/src/test/java/com/example:__pkg__",
         "//selffuzz/src/test/java/com/code_intelligence/selffuzz:__subpackages__",
         "//src/test/java/com/code_intelligence/jazzer/junit:__pkg__",
+        "//src/test/java/com/code_intelligence/jazzer/mutation/support:__pkg__",
     ],
     exports = [
         ":lifecycle",

src/main/java/com/code_intelligence/jazzer/mutation/ArgumentsMutator.java

@@ -23,14 +23,17 @@
 import static java.util.Arrays.stream;
 import static java.util.stream.Collectors.joining;
 
+import com.code_intelligence.jazzer.mutation.annotation.DictionaryProvider;
 import com.code_intelligence.jazzer.mutation.api.ExtendedMutatorFactory;
 import com.code_intelligence.jazzer.mutation.api.PseudoRandom;
 import com.code_intelligence.jazzer.mutation.api.SerializingMutator;
 import com.code_intelligence.jazzer.mutation.combinator.InPlaceProductMutator;
 import com.code_intelligence.jazzer.mutation.combinator.MutatorCombinators;
 import com.code_intelligence.jazzer.mutation.engine.SeededPseudoRandom;
 import com.code_intelligence.jazzer.mutation.mutator.Mutators;
+import com.code_intelligence.jazzer.mutation.runtime.MutationRuntime;
 import com.code_intelligence.jazzer.mutation.support.Preconditions;
+import com.code_intelligence.jazzer.mutation.support.TypeSupport;
 import com.code_intelligence.jazzer.utils.Log;
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
@@ -97,11 +100,19 @@ public static Optional<ArgumentsMutator> forMethod(
       Log.error(validationError.getMessage());
       throw validationError;
     }
+    MutationRuntime.fuzzTestMethod = method;
+    DictionaryProvider[] typeDictionaries = method.getAnnotationsByType(DictionaryProvider.class);
     return toArrayOrEmpty(
             stream(method.getAnnotatedParameterTypes())
                 .map(
                     type -> {
-                      Optional<SerializingMutator<?>> mutator = mutatorFactory.tryCreate(type);
+                      // Forward all DictionaryProvider annotations of the fuzz test method to each
+                      // arg.
+                      AnnotatedType t = type;
+                      for (DictionaryProvider dict : typeDictionaries) {
+                        t = TypeSupport.withExtraAnnotations(t, dict);
+                      }
+                      Optional<SerializingMutator<?>> mutator = mutatorFactory.tryCreate(t);
                       if (!mutator.isPresent()) {
                         Log.error(
                             String.format(

src/main/java/com/code_intelligence/jazzer/mutation/BUILD.bazel

@@ -11,7 +11,9 @@ java_library(
         "//src/main/java/com/code_intelligence/jazzer/mutation/combinator",
         "//src/main/java/com/code_intelligence/jazzer/mutation/engine",
         "//src/main/java/com/code_intelligence/jazzer/mutation/mutator",
+        "//src/main/java/com/code_intelligence/jazzer/mutation/runtime",
         "//src/main/java/com/code_intelligence/jazzer/mutation/support",
+        "//src/main/java/com/code_intelligence/jazzer/mutation/utils",
         "//src/main/java/com/code_intelligence/jazzer/utils:log",
     ],
 )

src/main/java/com/code_intelligence/jazzer/mutation/annotation/DictionaryProvider.java

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2024 Code Intelligence GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.code_intelligence.jazzer.mutation.annotation;
+
+import static com.code_intelligence.jazzer.mutation.utils.PropertyConstraint.RECURSIVE;
+import static java.lang.annotation.ElementType.TYPE_USE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import com.code_intelligence.jazzer.mutation.utils.IgnoreRecursiveConflicts;
+import com.code_intelligence.jazzer.mutation.utils.PropertyConstraint;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Provides dictionary values to user-selected mutator types. Currently supported mutators are:
+ *
+ * <ul>
+ *   <li>String mutator
+ *   <li>Integral mutators (byte, short, int, long)
+ * </ul>
+ *
+ * <p>This annotation can be applied to fuzz test methods and any parameter type or subtype. By
+ * default, this annotation is propagated to all nested subtypes unless specified otherwise via the
+ * {@link #constraint()} attribute.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * public class MyFuzzTarget {
+ *
+ *   static Stream<?> dictionaryVisibleByAllArgumentMutators() {
+ *     return Stream.of("example1", "example2", "example3", 1232187321, -182371);
+ *   }
+ *
+ *   static Stream<?> dictionaryVisibleOnlyByAnotherInput() {
+ *     return Stream.of("code-intelligence.com", "secret.url.1082h3u21ibsdsazuvbsa.com");
+ *   }
+ *
+ *   @DictionaryProvider("dictionaryVisibleByAllArgumentMutators")
+ *   @FuzzTest
+ *   public void fuzzerTestOneInput(String input, @DictionaryProvider("dictionaryVisibleOnlyByAnotherInput") String anotherInput) {
+ *     // Fuzzing logic here
+ *   }
+ * }
+ * }</pre>
+ *
+ * In this example, the mutator for the String parameter {@code input} of the fuzz test method
+ * {@code fuzzerTestOneInput} will be using the values returned by {@code provide} method during
+ * mutation, while the mutator for String {@code anotherInput} will use values from both methods:
+ * from the method-level {@code DictionaryProvider} annotation that uses {@code provide} and the
+ * parameter-level {@code DictionaryProvider} annotation that uses {@code provideSomethingElse}.
+ */
+@Target({ElementType.METHOD, TYPE_USE})
+@Retention(RUNTIME)
+@IgnoreRecursiveConflicts
+@PropertyConstraint
+public @interface DictionaryProvider {
+  /**
+   * Specifies supplier methods that generate dictionary values for fuzzing the annotated method or
+   * type. The specified supplier methods must be static and return a {@code Stream <?>} of values.
+   * The values don't need to match the type of the annotated method or parameter exactly. The
+   * mutation framework will extract only the values that are compatible with the target type.
+   */
+  String[] value() default {""};
+
+  /**
+   * This {@code DictionaryProvider} will be used with probability {@code 1/p} by the mutator
+   * responsible for fitting types. Not all mutators respect this probability.
+   */
+  int pInv() default 10;
+
+  /**
+   * Defines the scope of the annotation. Possible values are defined in {@link
+   * com.code_intelligence.jazzer.mutation.utils.PropertyConstraint}. It is convenient to use {@code
+   * RECURSIVE} as the default value here, as dictionary objects are typically used for complex
+   * types (e.g. custom classes) where the annotation is placed directly on the method or parameter
+   * and is expected to apply to all nested fields.
+   */
+  String constraint() default RECURSIVE;
+}

src/main/java/com/code_intelligence/jazzer/mutation/combinator/SamplingUtils.java

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2025 Code Intelligence GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.code_intelligence.jazzer.mutation.combinator;
+
+import static com.code_intelligence.jazzer.mutation.support.Preconditions.require;
+import static java.util.Objects.requireNonNull;
+
+import com.code_intelligence.jazzer.mutation.api.PseudoRandom;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Optional;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+public final class SamplingUtils {
+
+  public static <T> Function<PseudoRandom, T> weightedSampler(T[] values, double[] weights) {
+    // Use Vose's alias method for O(1) sampling after O(n) preprocessing.
+    requireNonNull(values, "Values must not be null");
+    requireNonNull(weights, "Weights must not be null");
+    require(values.length > 0, "Values must not be empty");
+    require(values.length == weights.length, "Values and weights must have the same length");
+
+    double sum = Arrays.stream(weights).sum();
+    require(sum > 0, "At least one weight must be positive");
+
+    int n = values.length;
+    int[] alias = new int[n];
+    double[] probability = new double[n];
+    double[] scaledWeights = Arrays.stream(weights).map(w -> w * n / sum).toArray();
+    int[] small = new int[n];
+    int[] large = new int[n];
+    int smallCount = 0;
+    int largeCount = 0;
+    for (int i = 0; i < n; i++) {
+      if (scaledWeights[i] < 1.0) {
+        small[smallCount++] = i;
+      } else {
+        large[largeCount++] = i;
+      }
+    }
+
+    while (smallCount > 0 && largeCount > 0) {
+      int less = small[--smallCount];
+      int more = large[--largeCount];
+
+      probability[less] = scaledWeights[less];
+      alias[less] = more;
+      scaledWeights[more] = (scaledWeights[more] + scaledWeights[less]) - 1.0;
+
+      if (scaledWeights[more] < 1.0) {
+        small[smallCount++] = more;
+      } else {
+        large[largeCount++] = more;
+      }
+    }
+    while (largeCount > 0) {
+      probability[large[--largeCount]] = 1.0;
+    }
+
+    while (smallCount > 0) {
+      probability[small[--smallCount]] = 1.0;
+    }
+    return (PseudoRandom random) -> {
+      int column = random.indexIn(n);
+      return values[random.closedRange(0.0, 1.0) < probability[column] ? column : alias[column]];
+    };
+  }
+
+  public static <T> Function<PseudoRandom, T> weightedSampler(
+      List<WeightedValue<T>> weightedFunctions) {
+    requireNonNull(weightedFunctions, "Weighted functions must not be null");
+    require(!weightedFunctions.isEmpty(), "Weighted functions must not be empty");
+
+    double[] weights = weightedFunctions.stream().mapToDouble(m -> m.weight).toArray();
+
+    T[] fns = (T[]) weightedFunctions.stream().map(m -> m.value).toArray(Object[]::new);
+
+    return weightedSampler(fns, weights);
+  }
+
+  @SafeVarargs
+  public static <T> Function<PseudoRandom, T> weightedSampler(
+      Optional<WeightedValue<T>>... values) {
+    return weightedSampler(
+        Arrays.stream(values)
+            .filter(Optional::isPresent)
+            .map(Optional::get)
+            .collect(Collectors.toList()));
+  }
+
+  /**
+   * A simple struct to hold a value and its weight. It is here just for stylistic reasons, to make
+   * the definitions of weights and values more readable.
+   */
+  public static class WeightedValue<T> {
+    public final double weight;
+    public final T value;
+
+    public WeightedValue(double weight, T value) {
+      this.value = value;
+      this.weight = weight;
+    }
+
+    public static <T> WeightedValue<T> of(double weight, T fn) {
+      return new WeightedValue<>(weight, fn);
+    }
+
+    public static <T> Optional<WeightedValue<T>> ofOptional(double weight, T fn) {
+      return Optional.of(new WeightedValue<>(weight, fn));
+    }
+  }
+}

src/main/java/com/code_intelligence/jazzer/mutation/mutator/collection/ArrayMutatorFactory.java

@@ -19,6 +19,7 @@
 import static com.code_intelligence.jazzer.mutation.mutator.collection.ChunkMutations.MutationAction.pickRandomMutationAction;
 import static com.code_intelligence.jazzer.mutation.support.Preconditions.require;
 import static com.code_intelligence.jazzer.mutation.support.PropertyConstraintSupport.propagatePropertyConstraints;
+import static com.code_intelligence.jazzer.mutation.support.TypeSupport.extractRawClass;
 import static java.lang.Math.min;
 import static java.lang.String.format;
 
@@ -35,6 +36,7 @@
 import java.lang.reflect.AnnotatedArrayType;
 import java.lang.reflect.AnnotatedType;
 import java.lang.reflect.Array;
+import java.lang.reflect.Type;
 import java.util.Arrays;
 import java.util.Optional;
 import java.util.function.Predicate;
@@ -53,12 +55,16 @@ public Optional<SerializingMutator<?>> tryCreate(
 
     AnnotatedType elementType = ((AnnotatedArrayType) type).getAnnotatedGenericComponentType();
     AnnotatedType propagatedElementType = propagatePropertyConstraints(type, elementType);
-    Class<?> propagatedElementClazz = (Class<?>) propagatedElementType.getType();
-    return Optional.of(propagatedElementType)
-        .flatMap(factory::tryCreate)
-        .map(
-            elementMutator ->
-                new ArrayMutator<>(elementMutator, propagatedElementClazz, minLength, maxLength));
+    Type rawType = propagatedElementType.getType();
+    return extractRawClass(rawType)
+        .flatMap(
+            propagatedElementClass ->
+                Optional.of(propagatedElementType)
+                    .flatMap(factory::tryCreate)
+                    .map(
+                        elementMutator ->
+                            new ArrayMutator<>(
+                                elementMutator, propagatedElementClass, minLength, maxLength)));
   }
 
   enum CrossOverAction {