Go: deprecate ConditionGuardNode

Author: Claude

go/ql/lib/change-notes/2026-08-17-deprecate-condition-guard-node.md

@@ -0,0 +1,4 @@
+---
+category: deprecated
+---
+* `ControlFlow::ConditionGuardNode` has been deprecated and no longer has any instances. Use the `Guard` class and the `guardEnsures`, `guardEnsuresEq`, `guardEnsuresNeq` and `guardEnsuresLeq` predicates from `semmle.go.controlflow.Guards` instead.

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

@@ -261,10 +261,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;
 
@@ -297,43 +299,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

@@ -58,28 +58,6 @@ module IR {
     n.isAfterValue(cc, any(MatchingSuccessor t | t.isMatch()))
   }
 
-  /**
-   * Holds if `n` is a genuine boolean condition-guard node: an "after" node
-   * that records exactly one of the true/false outcomes of a boolean
-   * condition.
-   *
-   * The shared CFG library's `isAfterTrue`/`isAfterFalse` are deliberately
-   * permissive when used for step-endpoint matching: a plain "after" node (or
-   * a merged leaf node) satisfies both of them. A real guard node is
-   * distinguished by satisfying exactly one of them.
-   */
-  private predicate isConditionGuardNode(ControlFlow::Node n) {
-    n.isAfterTrue(_) and not n.isAfterFalse(_)
-    or
-    n.isAfterFalse(_) and not n.isAfterTrue(_)
-    or
-    exists(Expr condition, MatchingSuccessor successor |
-      condition =
-        any(ExpressionSwitchStmt switch | not exists(switch.getExpr())).getACase().getAnExpr() and
-      n.isAfterValue(condition, successor)
-    )
-  }
-
   /**
    * An IR instruction.
    */
@@ -89,8 +67,6 @@ module IR {
       or
       this.isAdditional(_, _)
       or
-      isConditionGuardNode(this)
-      or
       // The successful-match node of a type-switch case that binds an implicit
       // variable hosts that variable's declaration/assignment (see
       // `TypeSwitchImplicitVariableInstruction`).
@@ -101,8 +77,7 @@ module IR {
       // 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 and the `ConditionGuardInstruction` for each branch
-      // captures the outcome, so no separate value instruction is needed.
+      // across branches, so no separate value instruction is needed.
       exists(Expr e |
         (e instanceof NotExpr or e instanceof LogicalBinaryExpr) and
         not isInBooleanCondContext(e) and
@@ -199,8 +174,6 @@ module IR {
       or
       this instanceof GoInstruction and result = "go"
       or
-      this instanceof ConditionGuardInstruction and result = "condition guard"
-      or
       this instanceof ReturnInstruction and result = "return"
       or
       this instanceof WriteResultInstruction and result = "result write"
@@ -224,11 +197,6 @@ module IR {
     }
   }
 
-  /** A condition guard instruction, representing a known boolean outcome for a condition. */
-  private class ConditionGuardInstruction extends Instruction {
-    ConditionGuardInstruction() { isConditionGuardNode(this) }
-  }
-
   /**
    * An IR instruction representing the evaluation of an expression.
    */