Go: migrate control flow graph to shared CFG library

go/ql/lib/change-notes/2026-03-30-shared-cfg-library.md

@@ -0,0 +1,4 @@
+---
+category: fix
+---
+* The Go control flow graph implementation has been migrated to use the shared CFG library. This is an internal change with no user-visible API changes.

go/ql/lib/printCfg.ql

@@ -0,0 +1,53 @@
+/**
+ * @name Print CFG
+ * @description Produces a representation of a file's Control Flow Graph.
+ *              This query is used by the VS Code extension.
+ * @id go/print-cfg
+ * @kind graph
+ * @tags ide-contextual-queries/print-cfg
+ */
+
+import go
+import semmle.go.controlflow.ControlFlowGraph
+private import semmle.go.controlflow.ControlFlowGraphShared
+
+external string selectedSourceFile();
+
+private predicate selectedSourceFileAlias = selectedSourceFile/0;
+
+external int selectedSourceLine();
+
+private predicate selectedSourceLineAlias = selectedSourceLine/0;
+
+external int selectedSourceColumn();
+
+private predicate selectedSourceColumnAlias = selectedSourceColumn/0;
+
+module ViewCfgQueryInput implements GoCfg::ControlFlow::ViewCfgQueryInputSig<File> {
+  predicate selectedSourceFile = selectedSourceFileAlias/0;
+
+  predicate selectedSourceLine = selectedSourceLineAlias/0;
+
+  predicate selectedSourceColumn = selectedSourceColumnAlias/0;
+
+  predicate cfgScopeSpan(
+    CfgScope scope, File file, int startLine, int startColumn, int endLine, int endColumn
+  ) {
+    file = scope.getFile() and
+    scope.getLocation().getStartLine() = startLine and
+    scope.getLocation().getStartColumn() = startColumn and
+    exists(Location loc |
+      loc.getEndLine() = endLine and
+      loc.getEndColumn() = endColumn and
+      loc = scope.(FuncDef).getBody().getLocation()
+    )
+    or
+    file = scope.(File) and
+    startLine = 1 and
+    startColumn = 1 and
+    endLine = file.getNumberOfLines() and
+    endColumn = 999999
+  }
+}
+
+import GoCfg::ControlFlow::ViewCfgQuery<File, ViewCfgQueryInput>

go/ql/lib/semmle/go/PrintAst.qll

@@ -1,7 +1,7 @@
 /**
  * Provides queries to pretty-print a Go AST as a graph.
  */
-overlay[local]
+overlay[local?]
 module;
 
 import go

go/ql/lib/semmle/go/Scopes.qll

@@ -437,11 +437,12 @@ class Function extends ValueEntity, @functionobject {
    * This predicate is an over-approximation: it may hold for functions that can never
    * return normally, but it never fails to hold for functions that can.
    *
-   * Note this is declared here and not in `DeclaredFunction` so that library models can override this
-   * by extending `Function` rather than having to remember to extend `DeclaredFunction`.
+   * Library models should not override this predicate; override `mustNotReturnNormally`
+   * instead, so that the control-flow graph construction can take the model into account.
    */
   predicate mayReturnNormally() {
     not this.mustPanic() and
+    not this.mustNotReturnNormally() and
     (ControlFlow::mayReturnNormally(this.getFuncDecl()) or not exists(this.getBody()))
   }
 
@@ -461,6 +462,16 @@ class Function extends ValueEntity, @functionobject {
    */
   predicate mustPanic() { none() }
 
+  /**
+   * Holds if calling this function never returns normally (for example because it
+   * always panics, exits the process, or loops forever).
+   *
+   * Unlike `mayReturnNormally`, this predicate must be defined without reference to
+   * the control-flow graph, so that it can be used during CFG construction to
+   * suppress normal-flow successors of calls to this function.
+   */
+  predicate mustNotReturnNormally() { none() }
+
   /** Gets the number of parameters of this function. */
   int getNumParameter() { result = this.getType().(SignatureType).getNumParameter() }
 

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

@@ -5,66 +5,27 @@ overlay[local]
 module;
 
 import go
-private import ControlFlowGraphImpl
-private import codeql.controlflow.BasicBlock as BB
-private import codeql.controlflow.SuccessorType
+private import ControlFlowGraphShared
 
-private module Input implements BB::InputSig<Location> {
-  /** A delineated part of the AST with its own CFG. */
-  class CfgScope = ControlFlow::Root;
+/** A basic block in the control-flow graph. */
+class BasicBlock = GoCfg::Cfg::BasicBlock;
 
-  /** The class of control flow nodes. */
-  class Node = ControlFlowNode;
-
-  /** Gets the CFG scope in which this node occurs. */
-  CfgScope nodeGetCfgScope(Node node) { node.getRoot() = result }
-
-  /** Gets an immediate successor of this node. */
-  Node nodeGetASuccessor(Node node, SuccessorType t) {
-    result = node.getASuccessor() and
-    (
-      not result instanceof ControlFlow::ConditionGuardNode and t instanceof DirectSuccessor
-      or
-      t.(BooleanSuccessor).getValue() = result.(ControlFlow::ConditionGuardNode).getOutcome()
-    )
-  }
-
-  /**
-   * Holds if `node` represents an entry node to be used when calculating
-   * dominance.
-   */
-  predicate nodeIsDominanceEntry(Node node) { node instanceof EntryNode }
-
-  /**
-   * Holds if `node` represents an exit node to be used when calculating
-   * post dominance.
-   */
-  predicate nodeIsPostDominanceExit(Node node) { node instanceof ExitNode }
-}
-
-private module BbImpl = BB::Make<Location, Input>;
-
-class BasicBlock = BbImpl::BasicBlock;
-
-class EntryBasicBlock = BbImpl::EntryBasicBlock;
-
-cached
-private predicate reachableBB(BasicBlock bb) {
-  bb instanceof EntryBasicBlock
-  or
-  exists(BasicBlock predBB | predBB.getASuccessor(_) = bb | reachableBB(predBB))
-}
+/** An entry basic block. */
+class EntryBasicBlock = GoCfg::Cfg::EntryBasicBlock;
 
 /**
  * A basic block that is reachable from an entry basic block.
+ *
+ * Since the shared CFG library only creates nodes for reachable code,
+ * all basic blocks are reachable by construction.
  */
 class ReachableBasicBlock extends BasicBlock {
-  ReachableBasicBlock() { reachableBB(this) }
+  ReachableBasicBlock() { any() }
 }
 
 /**
  * A reachable basic block with more than one predecessor.
  */
 class ReachableJoinBlock extends ReachableBasicBlock {
-  ReachableJoinBlock() { this.getFirstNode().isJoin() }
+  ReachableJoinBlock() { this.getFirstNode().(ControlFlow::Node).isJoin() }
 }

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

@@ -5,13 +5,17 @@
 module;
 
 import go
-private import ControlFlowGraphImpl
+private import ControlFlowGraphShared
 
-/** Provides helper predicates for mapping btween CFG nodes and the AST. */
+/** Provides helper predicates for mapping between CFG nodes and the AST. */
 module ControlFlow {
   /** A file or function with which a CFG is associated. */
   class Root extends AstNode {
-    Root() { exists(this.(File).getADecl()) or exists(this.(FuncDef).getBody()) }
+    Root() {
+      exists(this.(FuncDef).getBody())
+      or
+      exists(this.(File).getADecl())
+    }
 
     /** Holds if `nd` belongs to this file or function. */
     predicate isRootOf(AstNode nd) {
@@ -29,45 +33,40 @@
   }
 
   /**
-   * A node in the intra-procedural control-flow graph of a Go function or file.
+   * A node in the intra-procedural control-flow graph of a Go function.
    *
    * Nodes correspond to expressions and statements that compute a value or perform
    * an operation (as opposed to providing syntactic structure or type information).
    *
-   * There are also synthetic entry and exit nodes for each Go function and file
+   * There are also synthetic entry and exit nodes for each Go function
    * that mark the beginning and the end, respectively, of the execution of the
-   * function and the loading of the file.
+   * function.
    */
-  class Node extends TControlFlowNode {
-    /** Gets a node that directly follows this one in the control-flow graph. */
-    Node getASuccessor() { result = CFG::succ(this) }
-
-    /** Gets a node that directly precedes this one in the control-flow graph. */
-    Node getAPredecessor() { this = result.getASuccessor() }
-
+  class Node extends GoCfg::ControlFlowNode {
     /** Holds if this is a node with more than one successor. */
     predicate isBranch() { strictcount(this.getASuccessor()) > 1 }
 
     /** Holds if this is a node with more than one predecessor. */
     predicate isJoin() { strictcount(this.getAPredecessor()) > 1 }
 
     /** Holds if this is the first control-flow node in `subtree`. */
-    predicate isFirstNodeOf(AstNode subtree) { CFG::firstNode(subtree, this) }
-
-    /** Holds if this node is the (unique) entry node of a function or file. */
-    predicate isEntryNode() { this instanceof MkEntryNode }
+    predicate isFirstNodeOf(AstNode subtree) {
+      this.isBefore(subtree)
+      or
+      this.injects(subtree)
+    }
 
-    /** Holds if this node is the (unique) exit node of a function or file. */
-    predicate isExitNode() { this instanceof MkExitNode }
+    /** Holds if this node is the (unique) entry node of a function. */
+    predicate isEntryNode() { this instanceof GoCfg::ControlFlow::EntryNode }
 
-    /** Gets the basic block to which this node belongs. */
-    BasicBlock getBasicBlock() { result.getANode() = this }
+    /** Holds if this node is the (unique) exit node of a function. */
+    predicate isExitNode() { this instanceof GoCfg::ControlFlow::ExitNode }
 
     /** Holds if this node dominates `dominee` in the control-flow graph. */
     overlay[caller?]
     pragma[inline]
     predicate dominatesNode(ControlFlow::Node dominee) {
-      exists(ReachableBasicBlock thisbb, ReachableBasicBlock dbb, int i, int j |
+      exists(GoCfg::Cfg::BasicBlock thisbb, GoCfg::Cfg::BasicBlock dbb, int i, int j |
         this = thisbb.getNode(i) and dominee = dbb.getNode(j)
       |
         thisbb.strictlyDominates(dbb)
@@ -76,20 +75,12 @@
       )
     }
 
-    /** Gets the innermost function or file to which this node belongs. */
-    Root getRoot() { none() }
+    /** Gets the innermost function to which this node belongs. */
+    Root getRoot() { result = this.getEnclosingCallable() }
 
     /** Gets the file to which this node belongs. */
     File getFile() { result = this.getLocation().getFile() }
 
-    /**
-     * Gets a textual representation of this control flow node.
-     */
-    string toString() { result = "control-flow node" }
-
-    /** Gets the source location for this element. */
-    Location getLocation() { none() }
-
     /**
      * DEPRECATED: Use `getLocation()` instead.
      *
@@ -113,6 +104,12 @@
     }
   }
 
+  /** A synthetic entry node for a function. */
+  class EntryNode extends Node instanceof GoCfg::ControlFlow::EntryNode { }
+
+  /** A synthetic exit node for a function. */
+  class ExitNode extends Node instanceof GoCfg::ControlFlow::ExitNode { }
+
   /**
    * A control-flow node that initializes or updates the value of a constant, a variable,
    * a field, or an (array, slice, or map) element.
@@ -172,7 +169,7 @@
       exists(IR::FieldTarget trg | trg = super.getLhs() |
         (
           trg.getBase() = base or
-          trg.getBase() = MkImplicitDeref(base.(IR::EvalInstruction).getExpr())
+          trg.getBase() = IR::implicitDerefInstruction(base.(IR::EvalInstruction).getExpr())
         ) and
         trg.getField() = f and
         super.getRhs() = rhs
@@ -220,7 +217,7 @@
       exists(IR::ElementTarget trg | trg = super.getLhs() |
         (
           trg.getBase() = base or
-          trg.getBase() = MkImplicitDeref(base.(IR::EvalInstruction).getExpr())
+          trg.getBase() = IR::implicitDerefInstruction(base.(IR::EvalInstruction).getExpr())
         ) and
         trg.getIndex() = index and
         super.getRhs() = rhs
@@ -250,11 +247,15 @@
    * 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, MkConditionGuardNode {
+  class ConditionGuardNode extends Node {
     Expr cond;
     boolean outcome;
 
-    ConditionGuardNode() { this = MkConditionGuardNode(cond, outcome) }
+    ConditionGuardNode() {
+      this.isAfterTrue(cond) and outcome = true
+      or
+      this.isAfterFalse(cond) and outcome = false
+    }
 
     private predicate ensuresAux(Expr expr, boolean b) {
       expr = cond and b = outcome
@@ -320,29 +321,30 @@
     boolean getOutcome() { result = outcome }
 
     override Root getRoot() { result.isRootOf(cond) }
-
-    override string toString() { result = cond + " is " + outcome }
-
-    override Location getLocation() { result = cond.getLocation() }
   }
 
   /**
-   * Gets the entry node of function or file `root`.
+   * Gets the entry node of function `root`.
    */
-  Node entryNode(Root root) { result = MkEntryNode(root) }
+  EntryNode entryNode(Root root) { result.getEnclosingCallable() = root }
 
   /**
-   * Gets the exit node of function or file `root`.
+   * Gets the exit node of function `root`.
    */
-  Node exitNode(Root root) { result = MkExitNode(root) }
+  ExitNode exitNode(Root root) { result.getEnclosingCallable() = root }
 
   /**
    * Holds if the function `f` may return without panicking, exiting the process, or looping forever.
    *
    * This is defined conservatively, and so may also hold of a function that in fact
    * cannot return normally, but never fails to hold of a function that can return normally.
    */
-  predicate mayReturnNormally(FuncDecl f) { CFG::mayReturnNormally(f.getBody()) }
+  predicate mayReturnNormally(FuncDecl f) {
+    exists(GoCfg::ControlFlow::NormalExitNode exit |
+      exit.getEnclosingCallable() = f and
+      exists(exit.getAPredecessor())
+    )
+  }
 
   /**
    * Holds if `pred` is the node for the case `testExpr` in an expression
@@ -352,10 +354,18 @@
   predicate isSwitchCaseTestPassingEdge(
     ControlFlow::Node pred, ControlFlow::Node succ, Expr switchExpr, Expr testExpr
   ) {
-    CFG::isSwitchCaseTestPassingEdge(pred, succ, switchExpr, testExpr)
+    exists(ExpressionSwitchStmt ess, CaseClause cc, int i |
+      ess.getExpr() = switchExpr and
+      cc = ess.getACase() and
+      testExpr = cc.getExpr(i) and
+      pred.isAfter(testExpr) and
+      succ.isFirstNodeOf(cc.getStmt(0))
+    )
   }
 }
 
 class ControlFlowNode = ControlFlow::Node;
 
+class CfgScope = GoCfg::CfgScope;
+
 class Write = ControlFlow::WriteNode;