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,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.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;
@@ -104,7 +106,13 @@ public static Optional<ArgumentsMutator> forMethod(
             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

@@ -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,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/support/DictionaryProviderSupport.java

@@ -0,0 +1,108 @@
+/*
+ * 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.MutationRuntime;
+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(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(MutationRuntime.fuzzTestMethod.getDeclaringClass().getDeclaredMethods())
+            .filter(m -> m.getParameterCount() == 0)
+            .filter(m -> m.getReturnType().equals(Stream.class))
+            .filter(
+                m ->
+                    (m.getModifiers() & java.lang.reflect.Modifier.STATIC)
+                        == 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(
+                        "Found no static supplier method 'Stream<?> "
+                            + name
+                            + "()' in class "
+                            + MutationRuntime.fuzzTestMethod.getDeclaringClass().getName());
+                  }
+                  try {
+                    m.setAccessible(true);
+                    return (Stream<?>) m.invoke(null);
+                  } catch (IllegalAccessException e) {
+                    throw new IllegalStateException("Cannot access method " + name, e);
+                  } catch (InvocationTargetException e) {
+                    throw new RuntimeException(
+                        "Supplier method " + name + " threw an exception", e.getCause());
+                  }
+                })
+            .distinct());
+  }
+}

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

@@ -29,6 +29,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",