Merge pull request #18696 from paldepind/shared-bb-dominates

Shared: Use edge dominance terminology in basic block library

csharp/ql/lib/change-notes/2025-02-11-basic-block-rename.md

@@ -0,0 +1,6 @@
+---
+category: deprecated
+---
+* The predicates `immediatelyControls` and `controls` on the `ConditionBlock`
+  class have been deprecated in favor of the newly added `dominatingEdge`
+  predicate.

csharp/ql/lib/semmle/code/csharp/controlflow/BasicBlocks.qll

@@ -202,6 +202,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_ `e` if it can
+   * only be reached through `e`.
+   *
+   * 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, ControlFlow::SuccessorType s) {
+    super.edgeDominates(dominated, s)
+  }
+
   /**
    * Holds if this basic block strictly post-dominates basic block `bb`.
    *
@@ -296,11 +319,14 @@ final class JoinBlockPredecessor extends BasicBlock, BasicBlocksImpl::JoinPredec
  * control flow.
  */
 final class ConditionBlock extends BasicBlock, BasicBlocksImpl::ConditionBasicBlock {
-  predicate immediatelyControls(BasicBlock succ, ConditionalSuccessor s) {
-    super.immediatelyControls(succ, s)
+  /** DEPRECATED: Use `edgeDominates` instead. */
+  deprecated predicate immediatelyControls(BasicBlock succ, ConditionalSuccessor s) {
+    this.getASuccessor(s) = succ and
+    BasicBlocksImpl::dominatingEdge(this, succ)
   }
 
-  predicate controls(BasicBlock controlled, ConditionalSuccessor s) {
-    super.controls(controlled, s)
+  /** DEPRECATED: Use `edgeDominates` instead. */
+  deprecated predicate controls(BasicBlock controlled, ConditionalSuccessor s) {
+    super.edgeDominates(controlled, s)
   }
 }

csharp/ql/lib/semmle/code/csharp/controlflow/ControlFlowElement.qll

@@ -225,6 +225,6 @@ class ControlFlowElement extends ExprOrStmtParent, @control_flow_element {
     this.controlsBlockSplit(controlled, s, cb)
     or
     cb.getLastNode() = this.getAControlFlowNode() and
-    cb.controls(controlled, s)
+    cb.edgeDominates(controlled, s)
   }
 }

csharp/ql/lib/semmle/code/csharp/dataflow/internal/SsaImpl.qll

@@ -1119,7 +1119,7 @@ private module DataFlowIntegrationInput implements Impl::DataFlowIntegrationInpu
     exists(ConditionBlock conditionBlock, ControlFlow::SuccessorTypes::ConditionalSuccessor s |
       guard.getAControlFlowNode() = conditionBlock.getLastNode() and
       s.getValue() = branch and
-      conditionBlock.controls(bb, s)
+      conditionBlock.edgeDominates(bb, s)
     )
   }
 

csharp/ql/test/library-tests/controlflow/graph/Condition.ql

@@ -4,7 +4,8 @@ import ControlFlow
 query predicate conditionBlock(
   BasicBlocks::ConditionBlock cb, BasicBlock controlled, boolean testIsTrue
 ) {
-  cb.controls(controlled, any(SuccessorTypes::ConditionalSuccessor s | testIsTrue = s.getValue()))
+  cb.edgeDominates(controlled,
+    any(SuccessorTypes::ConditionalSuccessor s | testIsTrue = s.getValue()))
 }
 
 ControlFlow::Node successor(ControlFlow::Node node, boolean kind) {