feat: add configurable max number of mutations for ValuePools

Author: oetr

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

@@ -104,6 +104,12 @@
    */
   double p() default 0.1;
 
+  /**
+   * If the mutator selects a value from this {@code ValuePool}, it will perform up to {@code
+   * maxMutations} additional mutations on the selected value.
+   */
+  int maxMutations() default 1;
+
   /**
    * Defines the scope of the annotation. Possible values are defined in {@link
    * com.code_intelligence.jazzer.mutation.utils.PropertyConstraint}. By default, it's {@code

src/main/java/com/code_intelligence/jazzer/mutation/mutator/lang/ValuePoolMutatorFactory.java

@@ -74,12 +74,17 @@ private static final class ValuePoolMutator<T> extends SerializingMutator<T> {
     private final SerializingMutator<T> mutator;
     private final List<T> userValues;
     private final double poolUsageProbability;
+    private final int maxMutations;
 
     ValuePoolMutator(
-        SerializingMutator<T> mutator, List<T> userValues, double poolUsageProbability) {
+        SerializingMutator<T> mutator,
+        List<T> userValues,
+        double poolUsageProbability,
+        int maxMutations) {
       this.mutator = mutator;
       this.userValues = userValues;
       this.poolUsageProbability = poolUsageProbability;
+      this.maxMutations = maxMutations;
     }
 
     @SuppressWarnings("unchecked")
@@ -106,7 +111,8 @@ static <T> SerializingMutator<T> wrapIfValuesExist(
       }
 
       double p = valuePoolRegistry.extractFirstProbability(type);
-      return new ValuePoolMutator<>(mutator, userValues, p);
+      int maxMutations = valuePoolRegistry.extractFirstMaxMutations(type);
+      return new ValuePoolMutator<>(mutator, userValues, p, maxMutations);
     }
 
     /**
@@ -138,8 +144,8 @@ private static <T> boolean isSerializationStable(SerializingMutator<T> mutator,
     @Override
     public String toDebugString(Predicate<Debuggable> isInCycle) {
       return String.format(
-          "%s (values: %d p: %.2f)",
-          mutator.toDebugString(isInCycle), userValues.size(), poolUsageProbability);
+          "%s (values: %d p: %.2f, maxMutations: %d)",
+          mutator.toDebugString(isInCycle), userValues.size(), poolUsageProbability, maxMutations);
     }
 
     @Override
@@ -174,19 +180,30 @@ public T init(PseudoRandom prng) {
     @Override
     public T mutate(T value, PseudoRandom prng) {
       if (prng.closedRange(0.0, 1.0) < poolUsageProbability) {
-        if (prng.choice()) {
-          return prng.pickIn(userValues);
-        } else {
-          // treat the value from valuePool as a starting point for mutation
-          return mutator.mutate(prng.pickIn(userValues), prng);
+        value = prng.pickIn(userValues);
+        // Treat the user value as a starting point for mutation
+        int mutations = prng.closedRange(0, maxMutations);
+        for (int i = 0; i < mutations; i++) {
+          value = mutator.mutate(value, prng);
         }
+        return value;
       }
       return mutator.mutate(value, prng);
     }
 
     @Override
     public T crossOver(T value, T otherValue, PseudoRandom prng) {
-      return mutator.crossOver(value, otherValue, prng);
+      if (prng.closedRange(0.0, 1.0) < poolUsageProbability) {
+        value = prng.pickIn(userValues);
+        // Treat the user value as a starting point for crossOver
+        int mutations = prng.closedRange(0, maxMutations);
+        for (int i = 0; i < mutations; i++) {
+          value = mutator.crossOver(value, prng.pickIn(userValues), prng);
+        }
+        return value;
+      } else {
+        return mutator.crossOver(value, otherValue, prng);
+      }
     }
   }
 }

src/main/java/com/code_intelligence/jazzer/mutation/support/ValuePoolRegistry.java

@@ -79,6 +79,17 @@ public double extractFirstProbability(AnnotatedType type) {
     return p;
   }
 
+  public int extractFirstMaxMutations(AnnotatedType type) {
+    ValuePool[] valuePoolAnnotations = type.getAnnotationsByType(ValuePool.class);
+    if (valuePoolAnnotations.length == 0) {
+      // If we are here, it's a bug in the caller.
+      throw new IllegalStateException("Expected to find @ValuePool, but found none.");
+    }
+    int maxMutations = valuePoolAnnotations[0].maxMutations();
+    require(maxMutations >= 0, "@ValuePool maxMutations must be >= 0, but was " + maxMutations);
+    return maxMutations;
+  }
+
   public Stream<?> extractUserValues(AnnotatedType type) {
     Stream<?> valuesFromSourceMethods =
         getValuePoolAnnotations(type).stream()

src/test/java/com/code_intelligence/jazzer/mutation/support/ValuePoolsTest.java

@@ -22,6 +22,7 @@
 import static com.code_intelligence.jazzer.mutation.support.TypeSupport.withExtraAnnotations;
 import static com.code_intelligence.jazzer.mutation.utils.PropertyConstraint.DECLARATION;
 import static com.google.common.truth.Truth.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import com.code_intelligence.jazzer.mutation.annotation.ValuePool;
 import java.io.IOException;
@@ -89,6 +90,45 @@ void testExtractFirstProbability_TwoWithLastUsed() {
     assertThat(p).isEqualTo(0.2);
   }
 
+  @Test
+  void testExtractFirstMaxMutations_Default() {
+    AnnotatedType type = new TypeHolder<@ValuePool("myPool") String>() {}.annotatedType();
+    int maxMutations = valuePools.extractFirstMaxMutations(type);
+    assertThat(maxMutations).isEqualTo(1);
+  }
+
+  @Test
+  void testExtractFirstMaxMutations_OneUserDefined() {
+    AnnotatedType type =
+        new TypeHolder<
+            @ValuePool(value = "myPool2", maxMutations = 10) String>() {}.annotatedType();
+    int maxMutations = valuePools.extractFirstMaxMutations(type);
+    assertThat(maxMutations).isEqualTo(10);
+  }
+
+  @Test
+  void testExtractMaxMutations_TwoWithLastUsed() {
+    AnnotatedType type =
+        withExtraAnnotations(
+            new TypeHolder<
+                @ValuePool(value = "myPool", maxMutations = 2) String>() {}.annotatedType(),
+            new ValuePoolBuilder().value("myPool2").maxMutations(10).build());
+    int maxMutations = valuePools.extractFirstMaxMutations(type);
+    assertThat(maxMutations).isEqualTo(2);
+  }
+
+  @Test
+  void testExtractFirstMaxMutations_Negative() {
+    AnnotatedType type =
+        new TypeHolder<
+            @ValuePool(value = "myPool2", maxMutations = -1) String>() {}.annotatedType();
+    assertThat(
+            assertThrows(
+                IllegalArgumentException.class, () -> valuePools.extractFirstMaxMutations(type)))
+        .hasMessageThat()
+        .contains("@ValuePool maxMutations must be >= 0");
+  }
+
   @Test
   void testExtractRawValues_OneAnnotation() {
     AnnotatedType type = new TypeHolder<@ValuePool("myPool") String>() {}.annotatedType();
@@ -353,13 +393,15 @@ private static class ValuePoolBuilder {
     private String[] value;
     private String[] files;
     private double p;
+    private int maxMutations;
     private String constraint;
 
     public ValuePoolBuilder() {
       try {
         value = (String[]) getDefault("value");
         files = (String[]) getDefault("files");
         p = (double) getDefault("p");
+        maxMutations = (int) getDefault("maxMutations");
         constraint = (String) getDefault("constraint");
       } catch (NoSuchMethodException e) {
         throw new RuntimeException("Could not load ValuePool defaults", e);
@@ -385,6 +427,11 @@ public ValuePoolBuilder p(double p) {
       return this;
     }
 
+    public ValuePoolBuilder maxMutations(int maxMutations) {
+      this.maxMutations = maxMutations;
+      return this;
+    }
+
     public ValuePoolBuilder constraint(String constraint) {
       this.constraint = constraint;
       return this;
@@ -393,6 +440,7 @@ public ValuePoolBuilder constraint(String constraint) {
     public ValuePool build() {
       final String[] value = this.value;
       final double p = this.p;
+      final int maxMutations = this.maxMutations;
       final String constraint = this.constraint;
 
       return new ValuePool() {
@@ -416,6 +464,11 @@ public double p() {
           return p;
         }
 
+        @Override
+        public int maxMutations() {
+          return maxMutations;
+        }
+
         @Override
         public String constraint() {
           return constraint;
@@ -430,13 +483,18 @@ public boolean equals(Object o) {
           return Arrays.equals(this.value(), other.value())
               && Arrays.equals(this.files(), other.files())
               && this.p() == other.p()
+              && this.maxMutations() == other.maxMutations()
               && this.constraint().equals(other.constraint());
         }
 
         @Override
         public int hashCode() {
           return Objects.hash(
-              Arrays.hashCode(value()), Arrays.hashCode(files()), p(), constraint());
+              Arrays.hashCode(value()),
+              Arrays.hashCode(files()),
+              p(),
+              maxMutations(),
+              constraint());
         }
 
         @Override
@@ -449,6 +507,8 @@ public String toString() {
               + String.join(", ", files())
               + "}, p="
               + p()
+              + ", maxMutations="
+              + maxMutations()
               + ", constraint="
               + constraint()
               + ")";