feat: add configurable max number of mutations for ValuePools

Author: oetr

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

@@ -101,6 +101,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,28 @@ 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
+        for (int i = 0; i < prng.closedRange(0, maxMutations); 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
+        for (int i = 0; i < prng.closedRange(0, maxMutations); 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

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

@@ -85,6 +85,46 @@ 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);
+  }
+
+  // assert that maxMutatiosn throws when negative
+  @Test
+  void testExtractFirstMaxMutations_Negative() {
+    AnnotatedType type =
+        new TypeHolder<
+            @ValuePool(value = "myPool2", maxMutations = -1) String>() {}.annotatedType();
+    try {
+      valuePools.extractFirstMaxMutations(type);
+    } catch (IllegalArgumentException e) {
+      assertThat(e.getMessage()).contains("@ValuePool maxMutations must be >= 0");
+    }
+  }
+
   @Test
   void testExtractRawValues_OneAnnotation() {
     AnnotatedType type = new TypeHolder<@ValuePool("myPool") String>() {}.annotatedType();
@@ -385,13 +425,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);
@@ -412,6 +454,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;
@@ -426,6 +473,7 @@ public ValuePool build() {
       final String[] value = this.value;
       final String[] files = this.files;
       final double p = this.p;
+      final int maxMutations = this.maxMutations;
       final String constraint = this.constraint;
 
       return new ValuePool() {
@@ -449,6 +497,11 @@ public double p() {
           return p;
         }
 
+        @Override
+        public int maxMutations() {
+          return maxMutations;
+        }
+
         @Override
         public String constraint() {
           return constraint;
@@ -472,7 +525,8 @@ public int hashCode() {
           hash += Arrays.hashCode(value()) * 127;
           hash += Arrays.hashCode(files()) * 31 * 127;
           hash += Double.hashCode(p()) * 31 * 31 * 127;
-          hash += constraint().hashCode() * 31 * 31 * 31 * 127;
+          hash += Integer.hashCode(maxMutations()) * 31 * 31 * 31 * 127;
+          hash += constraint().hashCode() * 31 * 31 * 31 * 31 * 127;
           return hash;
         }
 
@@ -486,6 +540,8 @@ public String toString() {
               + String.join(", ", files())
               + "}, p="
               + p()
+              + ", maxMutations="
+              + maxMutations()
               + ", constraint="
               + constraint()
               + ")";