feat: dictionary provider for Strings and Integrals

[oetr]

This allows the users to annotate fuzz tests methods or any type by @DictionaryProvider and provide values directly to the type mutators. Currently, only String and Integral mutators make use of this feature, but this feature makes sense for other types as well.

The main motivation is to work around libFuzzer's TORC (table of recent compares) limitation of 64 bytes. libFuzzer dictionaries suffer from the same limitation. But with this PR, the issue below is found in no time.

  public static Stream<?> myDict() {
    return Stream.of(
        "0123456789abcdef".repeat(50),
        "sitting duck suprime".repeat(53),
        // We can mix all kinds of values in the same dictionary.
        // Each mutator only takes the values it can use.
        123);
  }

  @FuzzTest
  // Just propagate the dictionary to all types of the fuzz test method that can use it.
  @DictionaryProvider(
      value = {"myDict"},
      // Don't want to wait, force String mutators to use dictionary values every other time.
      pInv = 2)
  public static void fuzzerTestOneInput(
      @NotNull @WithUtf8Length(max = 10000) String data,
      @NotNull @WithUtf8Length(max = 10000) String data2) {
    /*
     * libFuzzer's table of recent compares only allows 64 bytes, so asking the fuzzer to construct
     * these long strings would run for a very very long time without finding them. With a
     * DictionaryProvider this problem is trivial, because we can directly provide these long strings to
     * the fuzzer, and also force that they are used more often by setting pInv to a low value.
     */
    if (data.equals("0123456789abcdef".repeat(50))
        && data2.equals("sitting duck suprime".repeat(53))) {
      throw new FuzzerSecurityIssueLow("Found the long string!");
    }
  }

[Copilot]

Pull Request Overview

This PR adds dictionary provider support to the mutation framework, enabling users to provide custom dictionary values for fuzzing through the @DictionaryProvider annotation. The implementation:

• Introduces MutatorRuntime class to provide runtime information (including the fuzz test method) to mutators
• Adds @DictionaryProvider annotation that references static methods returning Stream<?> of dictionary values
• Updates all MutatorFactory implementations to accept MutatorRuntime parameter
• Implements dictionary support for String and integral mutators using weighted sampling
• Adds SamplingUtils with Vose's alias method for efficient O(1) weighted sampling
• Includes comprehensive tests for the new functionality

Reviewed Changes

Copilot reviewed 85 out of 85 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
DictionaryProvider.java	New annotation for specifying dictionary provider methods with probability control
MutatorRuntime.java	New runtime info class providing fuzz test method to mutators
DictionaryProviderSupport.java	Helper methods to extract dictionary values from provider methods
IgnoreRecursiveConflicts.java	Meta-annotation to allow duplicate annotations during type hierarchy propagation
SamplingUtils.java	Weighted sampling utilities using Vose's alias method
StringMutatorFactory.java	Implements dictionary support for String mutators
IntegralMutatorFactory.java	Implements dictionary support for integral type mutators
MutatorFactory.java	Updated interface to accept MutatorRuntime parameter
ArgumentsMutator.java	Forwards method-level @DictionaryProvider annotations to parameters
TestSupport.java	Adds helper methods for creating dummy MutatorRuntime in tests
All other factory files	Updated to pass through MutatorRuntime parameter

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.