Merge remote-tracking branch 'upstream/master' into Expr-location-workaround

Conflicts and semantic conflicts in `library-tests/dataflow/fields` and
`library-tests/ir/ir`.

Author: jbj

.devcontainer/devcontainer.json

@@ -0,0 +1,9 @@
+{
+  "extensions": [
+    "github.vscode-codeql",
+    "slevesque.vscode-zipexplorer"
+  ],
+  "settings": {
+    "codeQL.experimentalBqrsParsing": true
+  }
+}

cpp/ql/src/semmle/code/cpp/controlflow/BasicBlocks.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides a library for reasoning about control flow at the granularity of basic blocks.
+ * This is usually much more efficient than reasoning directly at the level of `ControlFlowNode`s.
+ */
+
 import cpp
 private import internal.PrimitiveBasicBlocks
 private import internal.ConstantExprs
@@ -148,22 +153,37 @@ predicate bb_successor = bb_successor_cached/2;
 class BasicBlock extends ControlFlowNodeBase {
   BasicBlock() { basic_block_entry_node(this) }
 
+  /** Holds if this basic block contains `node`. */
   predicate contains(ControlFlowNode node) { basic_block_member(node, this, _) }
 
+  /** Gets the `ControlFlowNode` at position `pos` in this basic block. */
   ControlFlowNode getNode(int pos) { basic_block_member(result, this, pos) }
 
+  /** Gets a `ControlFlowNode` in this basic block. */
   ControlFlowNode getANode() { basic_block_member(result, this, _) }
 
+  /** Gets a `BasicBlock` that is a direct successor of this basic block. */
   BasicBlock getASuccessor() { bb_successor(this, result) }
 
+  /** Gets a `BasicBlock` that is a direct predecessor of this basic block. */
   BasicBlock getAPredecessor() { bb_successor(result, this) }
 
+  /**
+   * Gets a `BasicBlock` such that the control-flow edge `(this, result)` may be taken
+   * when the outgoing edge of this basic block is an expression that is true.
+   */
   BasicBlock getATrueSuccessor() { result.getStart() = this.getEnd().getATrueSuccessor() }
 
+  /**
+   * Gets a `BasicBlock` such that the control-flow edge `(this, result)` may be taken
+   * when the outgoing edge of this basic block is an expression that is false.
+   */
   BasicBlock getAFalseSuccessor() { result.getStart() = this.getEnd().getAFalseSuccessor() }
 
+  /** Gets the final `ControlFlowNode` of this basic block. */
   ControlFlowNode getEnd() { basic_block_member(result, this, bb_length(this) - 1) }
 
+  /** Gets the first `ControlFlowNode` of this basic block. */
   ControlFlowNode getStart() { result = this }
 
   /** Gets the number of `ControlFlowNode`s in this basic block. */
@@ -192,6 +212,7 @@ class BasicBlock extends ControlFlowNodeBase {
     this.getEnd().getLocation().hasLocationInfo(endf, _, _, endl, endc)
   }
 
+  /** Gets the function containing this basic block. */
   Function getEnclosingFunction() { result = this.getStart().getControlFlowScope() }
 
   /**

cpp/ql/src/semmle/code/cpp/controlflow/ControlFlowGraph.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides a library for reasoning about control flow at the granularity of
+ * individual nodes in the control-flow graph.
+ */
+
 import cpp
 import BasicBlocks
 private import semmle.code.cpp.controlflow.internal.ConstantExprs
@@ -29,8 +34,10 @@ private import semmle.code.cpp.controlflow.internal.CFG
  * `Handler`. There are no edges from function calls to `Handler`s.
  */
 class ControlFlowNode extends Locatable, ControlFlowNodeBase {
+  /** Gets a direct successor of this control-flow node, if any. */
   ControlFlowNode getASuccessor() { successors_adapted(this, result) }
 
+  /** Gets a direct predecessor of this control-flow node, if any. */
   ControlFlowNode getAPredecessor() { this = result.getASuccessor() }
 
   /** Gets the function containing this control-flow node. */
@@ -71,6 +78,7 @@ class ControlFlowNode extends Locatable, ControlFlowNodeBase {
     result = getASuccessor()
   }
 
+  /** Gets the `BasicBlock` containing this control-flow node. */
   BasicBlock getBasicBlock() { result.getANode() = this }
 }
 
@@ -86,10 +94,18 @@ import ControlFlowGraphPublic
  */
 class ControlFlowNodeBase extends ElementBase, @cfgnode { }
 
+/**
+ * Holds when `n2` is a control-flow node such that the control-flow
+ * edge `(n1, n2)` may be taken when `n1` is an expression that is true.
+ */
 predicate truecond_base(ControlFlowNodeBase n1, ControlFlowNodeBase n2) {
   qlCFGTrueSuccessor(n1, n2)
 }
 
+/**
+ * Holds when `n2` is a control-flow node such that the control-flow
+ * edge `(n1, n2)` may be taken when `n1` is an expression that is false.
+ */
 predicate falsecond_base(ControlFlowNodeBase n1, ControlFlowNodeBase n2) {
   qlCFGFalseSuccessor(n1, n2)
 }

cpp/ql/src/semmle/code/cpp/controlflow/Dataflow.qll

@@ -15,14 +15,25 @@ import Dereferenced
 abstract class DataflowAnnotation extends string {
   DataflowAnnotation() { this = "pointer-null" or this = "pointer-valid" }
 
+  /** Holds if this annotation is the default annotation. */
   abstract predicate isDefault();
 
+  /** Holds if this annotation is generated when analyzing expression `e`. */
   abstract predicate generatedOn(Expr e);
 
+  /**
+   * Holds if this annotation is generated for the variable `v` when
+   * the control-flow edge `(src, dest)` is taken.
+   */
   abstract predicate generatedBy(LocalScopeVariable v, ControlFlowNode src, ControlFlowNode dest);
 
+  /**
+   * Holds if this annotation is removed for the variable `v` when
+   * the control-flow edge `(src, dest)` is taken.
+   */
   abstract predicate killedBy(LocalScopeVariable v, ControlFlowNode src, ControlFlowNode dest);
 
+  /** Holds if expression `e` is given this annotation. */
   predicate marks(Expr e) {
     this.generatedOn(e) and reachable(e)
     or
@@ -31,6 +42,7 @@ abstract class DataflowAnnotation extends string {
     exists(LocalScopeVariable v | this.marks(v, e) and e = v.getAnAccess())
   }
 
+  /** Holds if the variable `v` accessed in control-flow node `n` is given this annotation. */
   predicate marks(LocalScopeVariable v, ControlFlowNode n) {
     v.getAnAccess().getEnclosingFunction().getBlock() = n and
     this.isDefault()
@@ -57,13 +69,21 @@ abstract class DataflowAnnotation extends string {
     )
   }
 
+  /**
+   * Holds if the variable `v` preserves this annotation when the control-flow
+   * edge `(src, dest)` is taken.
+   */
   predicate preservedBy(LocalScopeVariable v, ControlFlowNode src, ControlFlowNode dest) {
     this.marks(v, src) and
     src.getASuccessor() = dest and
     not v.getInitializer() = dest and
     not v.getAnAssignment() = src
   }
 
+  /**
+   * Holds if the variable `v` is assigned this annotation when `src` is an assignment
+   * expression that assigns to `v` and the control-flow edge `(src, dest)` is taken.
+   */
   predicate assignedBy(LocalScopeVariable v, ControlFlowNode src, ControlFlowNode dest) {
     this.marks(src.(AssignExpr).getRValue()) and
     src = v.getAnAssignment() and

cpp/ql/src/semmle/code/cpp/controlflow/DefinitionsAndUses.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides classes and predicates for reasoning about definitions and uses of variables.
+ */
+
 import cpp
 private import semmle.code.cpp.controlflow.StackVariableReachability
 private import semmle.code.cpp.dataflow.EscapesTree
@@ -135,6 +139,7 @@ library class DefOrUse extends ControlFlowNodeBase {
   }
 }
 
+/** A definition of a stack variable. */
 library class Def extends DefOrUse {
   Def() { definition(_, this) }
 
@@ -149,6 +154,7 @@ private predicate parameterIsOverwritten(Function f, Parameter p) {
   definitionBarrier(p, _)
 }
 
+/** A definition of a parameter. */
 library class ParameterDef extends DefOrUse {
   ParameterDef() {
     // Optimization: parameters that are not overwritten do not require
@@ -162,6 +168,7 @@ library class ParameterDef extends DefOrUse {
   }
 }
 
+/** A use of a stack variable. */
 library class Use extends DefOrUse {
   Use() { useOfVar(_, this) }
 

cpp/ql/src/semmle/code/cpp/controlflow/Dereferenced.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides predicates for detecting whether an expression dereferences a pointer.
+ */
+
 import cpp
 import Nullness
 

cpp/ql/src/semmle/code/cpp/controlflow/Guards.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides classes and predicates for reasoning about guards and the control
+ * flow elements controlled by those guards.
+ */
+
 import cpp
 import semmle.code.cpp.controlflow.BasicBlocks
 import semmle.code.cpp.controlflow.SSA

cpp/ql/src/semmle/code/cpp/controlflow/IRGuards.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides classes and predicates for reasoning about guards and the control
+ * flow elements controlled by those guards.
+ */
+
 import cpp
 import semmle.code.cpp.ir.IR
 
@@ -32,7 +37,7 @@ class GuardCondition extends Expr {
   }
 
   /**
-   * Holds if this condition controls `block`, meaning that `block` is only
+   * Holds if this condition controls `controlled`, meaning that `controlled` is only
    * entered if the value of this condition is `testIsTrue`.
    *
    * Illustration:
@@ -253,7 +258,7 @@ class IRGuardCondition extends Instruction {
   IRGuardCondition() { branch = get_branch_for_condition(this) }
 
   /**
-   * Holds if this condition controls `block`, meaning that `block` is only
+   * Holds if this condition controls `controlled`, meaning that `controlled` is only
    * entered if the value of this condition is `testIsTrue`.
    *
    * Illustration:
@@ -290,6 +295,10 @@ class IRGuardCondition extends Instruction {
     )
   }
 
+  /**
+   * Holds if the control-flow edge `(pred, succ)` may be taken only if
+   * the value of this condition is `testIsTrue`.
+   */
   cached
   predicate controlsEdge(IRBlock pred, IRBlock succ, boolean testIsTrue) {
     pred.getASuccessor() = succ and

cpp/ql/src/semmle/code/cpp/controlflow/Nullness.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides classes and predicates for working with null values and checks for nullness.
+ */
+
 import cpp
 import DefinitionsAndUses
 

cpp/ql/src/semmle/code/cpp/controlflow/SSA.qll

@@ -1,7 +1,15 @@
+/**
+ * Provides classes and predicates for SSA representation (Static Single Assignment form).
+ */
+
 import cpp
 import semmle.code.cpp.controlflow.Dominance
 import SSAUtils
 
+/**
+ * The SSA logic comes in two versions: the standard SSA and range-analysis RangeSSA.
+ * This class provides the standard SSA logic.
+ */
 library class StandardSSA extends SSAHelper {
   StandardSSA() { this = 0 }
 }
@@ -50,11 +58,13 @@ class SsaDefinition extends ControlFlowNodeBase {
    */
   ControlFlowNode getDefinition() { result = this }
 
+  /** Gets the `BasicBlock` containing this definition. */
   BasicBlock getBasicBlock() { result.contains(getDefinition()) }
 
   /** Holds if this definition is a phi node for variable `v`. */
   predicate isPhiNode(StackVariable v) { exists(StandardSSA x | x.phi_node(v, this.(BasicBlock))) }
 
+  /** Gets the location of this definition. */
   Location getLocation() { result = this.(ControlFlowNode).getLocation() }
 
   /** Holds if the SSA variable `(this, p)` is defined by parameter `p`. */