Go: deprecate the guard-reasoning members of ConditionGuardNode

Agent-Logs-Url: https://github.com/github/codeql/sessions/d505ffcf-a693-4b67-9dc3-54fa92e27896

Co-authored-by: owen-mc <62447351+owen-mc@users.noreply.github.com>

Author: Claude

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

@@ -0,0 +1,4 @@
+---
+category: deprecated
+---
+* The guard-reasoning member predicates of `ControlFlow::ConditionGuardNode` (`ensures`, `ensuresLeq`, `ensuresEq`, `ensuresNeq` and `dominates`) have been deprecated. Use the `Guard` class and the `guardEnsures`, `guardEnsuresEq`, `guardEnsuresNeq` and `guardEnsuresLeq` predicates from `semmle.go.controlflow.Guards` instead. The `ConditionGuardNode` class itself remains, since it is part of the control-flow graph.

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

@@ -297,43 +297,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())
     }