feat: @DictionaryProvider - propagate values to type mutators

This is just the enabling work. Methods and types annotated by
@DictionaryProvider recursively propagate this annotation down the
type hierarchy by default (can set to be for the annotated type only).

Any mutator can now be adapted to use the user-provided values
this annotation points to.

Author: oetr

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,6 +23,7 @@
 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;
@@ -32,6 +33,7 @@
 import com.code_intelligence.jazzer.mutation.mutator.Mutators;
 import com.code_intelligence.jazzer.mutation.runtime.MutatorRuntime;
 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;
@@ -99,12 +101,19 @@ public static Optional<ArgumentsMutator> forMethod(
       throw validationError;
     }
     MutatorRuntime runtime = MutatorRuntime.forFuzzTestMethod(method);
+    DictionaryProvider[] typeDictionaries = method.getAnnotationsByType(DictionaryProvider.class);
     return toArrayOrEmpty(
             stream(method.getAnnotatedParameterTypes())
                 .map(
                     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(runtime, type);
+                          mutatorFactory.tryCreate(runtime, t);
                       if (!mutator.isPresent()) {
                         Log.error(
                             String.format(

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

@@ -13,6 +13,7 @@ java_library(
         "//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,88 @@
+/*
+ * 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;
+
+/**
+ * Specifies provider methods that generate dictionary values for fuzzing the annotated method or
+ * type. The specified provider methods must be static, parameterless, 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.
+ *
+ * <p>The annotation can be applied to methods and parameters of any type. When applied to complex
+ * types (e.g. custom classes), the annotation is expected to apply to all nested fields unless
+ * specified otherwise via the {@link #constraint()} attribute.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * public class MyFuzzTarget {
+ *
+ *   public Stream<?> provide() {
+ *     return Stream.of("example1", "example2", "example3", 1232187321, -182371);
+ *   }
+ *
+ *   public Stream<?> provideSomethingElse() {
+ *     return Stream.of("code-intelligence.com", "secret.url.1082h3u21ibsdsazuvbsa.com");
+ *   }
+ *
+ *   @DictionaryProvider("provide")
+ *   @FuzzTest
+ *   public void fuzzerTestOneInput(String input, @DictionaryProvider("provideSomethingElse") 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 {
+  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/support/DictionaryProviderSupport.java

@@ -0,0 +1,111 @@
+/*
+ * 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.support;
+
+import static com.code_intelligence.jazzer.mutation.support.Preconditions.require;
+
+import com.code_intelligence.jazzer.mutation.annotation.DictionaryProvider;
+import com.code_intelligence.jazzer.mutation.runtime.MutatorRuntime;
+import java.lang.reflect.AnnotatedType;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Optional;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+public class DictionaryProviderSupport {
+
+  /**
+   * Extract inverse probability of the very first {@code DictionaryProvider} annotation on the
+   * given type. The {@code @DictionaryProvider} annotation directly on the type is preferred; if
+   * there is none, the first one appended because of {@code PropertyConstraint.RECURSIVE} is used.
+   * Any further {@code @DictionaryProvider} annotations appended later to this type because of
+   * {@code PropertyConstraint.RECURSIVE}, are ignored. Callers should ensure that at least one
+   * {@code @DictionaryProvider} annotation is present on the type.
+   */
+  public static int extractFirstInvProbability(AnnotatedType type) {
+    // If there are several @DictionaryProvider annotations on the type, this will take the most
+    // immediate one, because @DictionaryProvider is not repeatable.
+    DictionaryProvider[] dictObj = type.getAnnotationsByType(DictionaryProvider.class);
+    if (dictObj.length == 0) {
+      // If we are here, it's a bug in the caller.
+      throw new IllegalStateException("Expected to find @DictionaryProvider, but found none.");
+    }
+    int pInv = dictObj[0].pInv();
+    require(pInv >= 2, "@DictionaryProvider.pInv must be at least 2");
+    return pInv;
+  }
+
+  /** Extract the provider streams using MutatorRuntime */
+  public static Optional<Stream<?>> extractRawValues(MutatorRuntime runtime, AnnotatedType type) {
+    DictionaryProvider[] providers =
+        Arrays.stream(type.getAnnotations())
+            .filter(a -> a instanceof DictionaryProvider)
+            .map(a -> (DictionaryProvider) a)
+            .toArray(DictionaryProvider[]::new);
+    if (providers.length == 0) {
+      return Optional.empty();
+    }
+    HashSet<String> providerMethodNames =
+        Arrays.stream(providers)
+            .map(DictionaryProvider::value)
+            .flatMap(Arrays::stream)
+            .filter(name -> !name.isEmpty())
+            .collect(Collectors.toCollection(HashSet::new));
+    if (providerMethodNames.isEmpty()) {
+      return Optional.empty();
+    }
+    Map<String, Method> fuzzTestMethods =
+        Arrays.stream(runtime.fuzzTestMethod.getDeclaringClass().getDeclaredMethods())
+            .filter(m -> m.getParameterCount() == 0)
+            .filter(m -> m.getReturnType().equals(Stream.class))
+            .filter(
+                m ->
+                    (m.getModifiers()
+                            & (java.lang.reflect.Modifier.PUBLIC
+                                | java.lang.reflect.Modifier.STATIC))
+                        == (java.lang.reflect.Modifier.PUBLIC | java.lang.reflect.Modifier.STATIC))
+            .collect(Collectors.toMap(Method::getName, m -> m));
+    return Optional.ofNullable(
+        providerMethodNames.stream()
+            .flatMap(
+                name -> {
+                  Method m = fuzzTestMethods.get(name);
+                  if (m == null) {
+                    throw new IllegalStateException(
+                        "No method named "
+                            + name
+                            + " with signature 'public static Stream<?> "
+                            + name
+                            + "()' found in class "
+                            + runtime.fuzzTestMethod.getDeclaringClass().getName());
+                  }
+                  try {
+                    m.setAccessible(true);
+                    return (Stream<?>) m.invoke(null);
+                  } catch (IllegalAccessException e) {
+                    throw new RuntimeException(e);
+                  } catch (InvocationTargetException e) {
+                    throw new RuntimeException(e);
+                  }
+                })
+            .distinct());
+  }
+}

src/test/java/com/code_intelligence/jazzer/mutation/support/BUILD.bazel

@@ -30,6 +30,8 @@ java_test_suite(
     runner = "junit5",
     deps = [
         ":test_support",
+        "//deploy:jazzer-project",
+        "//src/main/java/com/code_intelligence/jazzer/junit:fuzz_test",
         "//src/main/java/com/code_intelligence/jazzer/mutation/annotation",
         "//src/main/java/com/code_intelligence/jazzer/mutation/support",
         "//src/main/java/com/code_intelligence/jazzer/mutation/utils",