Go: deprecate ConditionGuardNode

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: owen-mc

go/ql/lib/semmle/go/controlflow/ControlFlowGraph.qll

@@ -258,10 +258,12 @@ module ControlFlow {
   }
 
   /**
+   * DEPRECATED: Use `Guard` from `semmle.go.controlflow.Guards` instead.
+   *
    * A control-flow node recording the fact that a certain expression has a known
    * Boolean value at this point in the program.
    */
-  class ConditionGuardNode extends IR::Instruction {
+  deprecated class ConditionGuardNode extends IR::Instruction {
     Expr cond;
     boolean outcome;
 
@@ -292,43 +294,69 @@ module ControlFlow {
       b = false
     }
 
-    /** Holds if this guard ensures that the result of `nd` is `b`. */
-    predicate ensures(DataFlow::Node nd, boolean b) {
+    /**
+     * DEPRECATED: Use `Guard.controls` from `semmle.go.controlflow.Guards`
+     * instead.
+     *
+     * Holds if this guard ensures that the result of `nd` is `b`.
+     */
+    deprecated predicate ensures(DataFlow::Node nd, boolean b) {
       this.ensuresAux(any(Expr e | nd = DataFlow::exprNode(e)), b)
     }
 
-    /** Holds if this guard ensures that `lesser <= greater + bias` holds. */
-    predicate ensuresLeq(DataFlow::Node lesser, DataFlow::Node greater, int bias) {
+    /**
+     * DEPRECATED: Use `guardEnsuresLeq` from `semmle.go.controlflow.Guards`
+     * instead.
+     *
+     * Holds if this guard ensures that `lesser <= greater + bias` holds.
+     */
+    deprecated predicate ensuresLeq(DataFlow::Node lesser, DataFlow::Node greater, int bias) {
       exists(DataFlow::RelationalComparisonNode rel, boolean b |
-        this.ensures(rel, b) and
+        this.ensuresAux(rel.asExpr(), b) and
         rel.leq(b, lesser, greater, bias)
       )
       or
-      this.ensuresEq(lesser, greater) and
+      exists(DataFlow::EqualityTestNode eq, boolean b |
+        this.ensuresAux(eq.asExpr(), b) and
+        eq.eq(b, lesser, greater)
+      ) and
       bias = 0
     }
 
-    /** Holds if this guard ensures that `i = j` holds. */
-    predicate ensuresEq(DataFlow::Node i, DataFlow::Node j) {
+    /**
+     * DEPRECATED: Use `guardEnsuresEq` from `semmle.go.controlflow.Guards`
+     * instead.
+     *
+     * Holds if this guard ensures that `i = j` holds.
+     */
+    deprecated predicate ensuresEq(DataFlow::Node i, DataFlow::Node j) {
       exists(DataFlow::EqualityTestNode eq, boolean b |
-        this.ensures(eq, b) and
+        this.ensuresAux(eq.asExpr(), b) and
         eq.eq(b, i, j)
       )
     }
 
-    /** Holds if this guard ensures that `i != j` holds. */
-    predicate ensuresNeq(DataFlow::Node i, DataFlow::Node j) {
+    /**
+     * DEPRECATED: Use `guardEnsuresNeq` from `semmle.go.controlflow.Guards`
+     * instead.
+     *
+     * Holds if this guard ensures that `i != j` holds.
+     */
+    deprecated predicate ensuresNeq(DataFlow::Node i, DataFlow::Node j) {
       exists(DataFlow::EqualityTestNode eq, boolean b |
-        this.ensures(eq, b.booleanNot()) and
+        this.ensuresAux(eq.asExpr(), b.booleanNot()) and
         eq.eq(b, i, j)
       )
     }
 
     /**
+     * DEPRECATED: Use `Guard.controls` from `semmle.go.controlflow.Guards`
+     * instead.
+     *
      * Holds if this guard dominates basic block `bb`, that is, the guard
      * is known to hold at `bb`.
      */
-    predicate dominates(ReachableBasicBlock bb) {
+    deprecated predicate dominates(ReachableBasicBlock bb) {
       this = bb.getANode() or
       this.dominates(bb.getImmediateDominator())
     }

go/ql/lib/semmle/go/controlflow/IR.qll

@@ -80,9 +80,11 @@ module IR {
       typeSwitchCaseMatch(this, _)
       or
       // `NotExpr` and `LogicalBinaryExpr` are not in `postOrInOrder`, so they
-      // have no `isIn` node. Use their combined after-node as the value-producing
-      // instruction, but not a value-specific after-node, which is already a
-      // `ConditionGuardInstruction`.
+      // have no `isIn` node. When such an expression is not in a conditional
+      // context (so it has a single combined after-node rather than per-branch
+      // value-after-nodes), use that after-node as the value-producing
+      // instruction. In conditional contexts the value is already split
+      // across branches, so no separate value instruction is needed.
       exists(Expr e |
         (e instanceof NotExpr or e instanceof LogicalBinaryExpr) and
         this.isAfter(e) and

go/ql/test/library-tests/semmle/go/controlflow/Guards/Guards.expected

@@ -271,3 +271,5 @@ modelBarrierResult
 | guards.go:360:27:360:33 | pointer | model null | model-null |
 | guards.go:363:31:363:37 | pointer | model not null | model-not-null |
 | guards.go:366:34:366:40 | pointer | model no exception | model-no-exception |
+legacyConditionGuardCount
+| 88 |

go/ql/test/library-tests/semmle/go/controlflow/Guards/Guards.ql

@@ -49,3 +49,7 @@ query predicate modelBarrierResult(DataFlow::Node node, string label, string kin
     barrierNode(node, kind, _)
   )
 }
+
+deprecated query predicate legacyConditionGuardCount(int guardCount) {
+  guardCount = count(ControlFlow::ConditionGuardNode guard)
+}