Shared: Use edge dominance in basic block library

ruby/ql/lib/codeql/ruby/controlflow/BasicBlocks.qll

@@ -168,6 +168,29 @@ final class BasicBlock extends BasicBlocksImpl::BasicBlock {
    */
   BasicBlock getImmediateDominator() { result = super.getImmediateDominator() }
 
+  /**
+   * Holds if the edge with successor type `s` out of this basic block is a
+   * dominating edge for `dominated`.
+   *
+   * That is, all paths reaching `dominated` from the entry point basic
+   * block must go through the `s` edge out of this basic block.
+   *
+   * Edge dominance is similar to node dominance except it concerns edges
+   * instead of nodes: A basic block is dominated by a _basic block_ `bb` if it
+   * can only be reached through `bb` and dominated by an _edge_ `s` if it can
+   * only be reached through `s`.
+   *
+   * Note that where all basic blocks (except the entry basic block) are
+   * strictly dominated by at least one basic block, a basic block may not be
+   * dominated by any edge. If an edge dominates a basic block `bb`, then
+   * both endpoints of the edge dominates `bb`. The converse is not the case,
+   * as there may be multiple paths between the endpoints with none of them
+   * dominating.
+   */
+  predicate edgeDominates(BasicBlock dominated, SuccessorType s) {
+    super.edgeDominates(dominated, s)
+  }
+
   /**
    * Holds if this basic block strictly post-dominates basic block `bb`.
    *
@@ -248,21 +271,26 @@ final class JoinBlockPredecessor extends BasicBlock, BasicBlocksImpl::JoinPredec
  */
 final class ConditionBlock extends BasicBlock, BasicBlocksImpl::ConditionBasicBlock {
   /**
+   * DEPRECATED: Use `edgeDominates` instead.
+   *
    * Holds if basic block `succ` is immediately controlled by this basic
    * block with conditional value `s`. That is, `succ` is an immediate
    * successor of this block, and `succ` can only be reached from
    * the callable entry point by going via the `s` edge out of this basic block.
    */
-  predicate immediatelyControls(BasicBlock succ, ConditionalSuccessor s) {
-    super.immediatelyControls(succ, s)
+  deprecated predicate immediatelyControls(BasicBlock succ, ConditionalSuccessor s) {
+    this.getASuccessor(s) = succ and
+    BasicBlocksImpl::dominatingEdge(this, succ)
   }
 
   /**
+   * DEPRECATED: Use `edgeDominates` instead.
+   *
    * Holds if basic block `controlled` is controlled by this basic block with
    * conditional value `s`. That is, `controlled` can only be reached from the
    * callable entry point by going via the `s` edge out of this basic block.
    */
-  predicate controls(BasicBlock controlled, ConditionalSuccessor s) {
-    super.controls(controlled, s)
+  deprecated predicate controls(BasicBlock controlled, ConditionalSuccessor s) {
+    super.edgeDominates(controlled, s)
   }
 }

ruby/ql/lib/codeql/ruby/controlflow/internal/Guards.qll

@@ -6,6 +6,6 @@ predicate guardControlsBlock(CfgNodes::AstCfgNode guard, BasicBlock bb, boolean
   exists(ConditionBlock conditionBlock, SuccessorTypes::ConditionalSuccessor s |
     guard = conditionBlock.getLastNode() and
     s.getValue() = branch and
-    conditionBlock.controls(bb, s)
+    conditionBlock.edgeDominates(bb, s)
   )
 }

ruby/ql/lib/codeql/ruby/dataflow/internal/DataFlowPrivate.qll

@@ -2387,7 +2387,7 @@ module TypeInference {
     |
       m = resolveConstantReadAccess(pattern.getExpr()) and
       cb.getLastNode() = pattern and
-      cb.controls(read.getBasicBlock(),
+      cb.edgeDominates(read.getBasicBlock(),
         any(SuccessorTypes::MatchingSuccessor match | match.getValue() = true)) and
       caseRead = def.getARead() and
       read = def.getARead() and

ruby/ql/lib/codeql/ruby/security/ConditionalBypassCustomizations.qll

@@ -47,7 +47,7 @@ module ConditionalBypass {
 
     SensitiveActionGuardConditional() {
       exists(ConditionBlock cb, BasicBlock controlled |
-        cb.controls(controlled, _) and
+        cb.edgeDominates(controlled, _) and
         controlled.getANode() = action.asExpr() and
         cb.getLastNode() = this.asExpr()
       )

ruby/ql/test/library-tests/controlflow/graph/BasicBlocks.ql

@@ -10,8 +10,8 @@ query predicate immediateDominator(BasicBlock bb1, BasicBlock bb2) {
   bb1.getImmediateDominator() = bb2
 }
 
-query predicate controls(ConditionBlock bb1, BasicBlock bb2, SuccessorType t) {
-  bb1.controls(bb2, t)
+query predicate controls(ConditionBlock bb1, BasicBlock bb2, SuccessorTypes::ConditionalSuccessor t) {
+  bb1.edgeDominates(bb2, t)
 }
 
 query predicate successor(ConditionBlock bb1, BasicBlock bb2, SuccessorType t) {

ruby/ql/test/library-tests/dataflow/barrier-guards/barrier-guards.ql

@@ -14,7 +14,7 @@ query predicate newStyleBarrierGuards(DataFlow::Node n) {
 
 query predicate controls(CfgNode condition, BasicBlock bb, SuccessorTypes::ConditionalSuccessor s) {
   exists(ConditionBlock cb |
-    cb.controls(bb, s) and
+    cb.edgeDominates(bb, s) and
     condition = cb.getLastNode()
   )
 }