Sync (#154)

* Add processable visitors

* Created `DominatorCalculator.maybeDominates` to use instead of `dominates`, which no longer throws an exception

* Version and release notes

---------

Co-authored-by: toon.willemot <toon.willemot@guardsquare.com>
Co-authored-by: luis.carneiro <luis.carneiro@guardsquare.com>

Author: 3 people

base/src/main/java/proguard/analysis/CallResolver.java

@@ -422,7 +422,9 @@ private void addCall(
     boolean alwaysInvoked = true;
     if (useDominatorAnalysis) {
       alwaysInvoked =
-          dominatorCalculator.dominates(location.offset, DominatorCalculator.EXIT_NODE_OFFSET);
+          dominatorCalculator
+              .maybeDominates(location.offset, DominatorCalculator.EXIT_NODE_OFFSET)
+              .orElse(false);
     }
     Call call =
         instantiateCall(

base/src/main/java/proguard/analysis/DominatorCalculator.java

@@ -27,6 +27,7 @@
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.Set;
 import proguard.classfile.Clazz;
 import proguard.classfile.Method;
@@ -121,7 +122,10 @@ public DominatorCalculator(boolean ignoreExceptions) {
    * @param dominator The potentially dominating instruction's offset
    * @param inferior The potentially dominated instruction's offset
    * @return true if the potential dominator is indeed guaranteed to be executed before the inferior
+   * @deprecated Callers should use {@link #maybeDominates} to handle an optional value instead of
+   *     an exception.
    */
+  @Deprecated
   public boolean dominates(int dominator, int inferior) {
     BitSet dominators = dominatorMap.get(inferior);
     if (dominators == null) {
@@ -134,6 +138,25 @@ public boolean dominates(int dominator, int inferior) {
     return dominators.get(offsetToIndex(dominator));
   }
 
+  /**
+   * Check if one instruction dominates another one. If this is the case, the dominating instruction
+   * is guaranteed to be executed before the inferior instruction. Should you wish to check whether
+   * an instruction is guaranteed to be executed once the containing method is invoked, you can use
+   * the virtual inferior {@link #EXIT_NODE_OFFSET} as a collection for all return instructions.
+   *
+   * @param dominator The potentially dominating instruction's offset
+   * @param inferior The potentially dominated instruction's offset
+   * @return Optional.true if the potential dominator is indeed guaranteed to be executed before the
+   *     inferior, Optional.false if not and Optional.empty when no dominator information is known.
+   */
+  public Optional<Boolean> maybeDominates(int dominator, int inferior) {
+    BitSet dominators = dominatorMap.get(inferior);
+    if (dominators == null) {
+      return Optional.empty();
+    }
+    return Optional.of(dominators.get(offsetToIndex(dominator)));
+  }
+
   /**
    * As we introduced {@link #ENTRY_NODE_OFFSET} and {@link #EXIT_NODE_OFFSET} as virtual
    * instruction offsets, the rest of the instructions are shifted by those two places. In order to