Add library for reporting if all instances hold

Add a utility library for determing whether a condition holds for
all copies of a statement in a program.

Author: lcartey

cpp/common/src/codingstandards/cpp/alertreporting/HoldsForAllInstances.qll

@@ -0,0 +1,106 @@
+/**
+ * A module for considering whether a result occurs in all instances (e.g. copies) of the code at a
+ * given location.
+ *
+ * Multiple instances of a statement at the same location can occur for two main reasons:
+ *  1. Instantiations of a template
+ *  2. Re-compilation of a file under a different context
+ * This module helps ensure that a particular condition holds for all copies of a particular logical
+ * statement. For example, this can be used to determine whether a line of code is dead in all copies
+ * of a piece of code.
+ *
+ * This module is parameterized by a set of _candidate_ statements in the program. For each candidate
+ * statement, we determine whether all other statements that occur at the same location in the
+ * program are also part of the same set, ignoring any results generated by macros.
+ *
+ * We do so by reporting a new type of result, `LogicalResultStmt`, which represents a logical result
+ * where all instances of a statement at a given location are considered to be part of the same set.
+ */
+
+import cpp
+
+/**
+ * Holds if the `Stmt` `s` is not within a macro expansion, i.e. generated by a macro, but not the
+ * outermost `Stmt` generated by the macro.
+ */
+predicate isNotWithinMacroExpansion(Stmt s) {
+  not s.isInMacroExpansion()
+  or
+  exists(MacroInvocation mi |
+    mi.getStmt() = s and
+    not exists(mi.getParentInvocation())
+  )
+}
+
+/** A candidate set of types. */
+signature class CandidateStmtSig extends Stmt;
+
+/**
+ * A module for considering whether a result occurs in all instances (e.g. copies) of the code at a
+ * given location.
+ */
+module HoldsForAllInstances<CandidateStmtSig CandidateStmt> {
+  private predicate hasLocation(
+    Stmt s, string filepath, int startline, int startcolumn, int endline, int endcolumn
+  ) {
+    s.getLocation().hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
+  }
+
+  final private class MyStmt = Stmt;
+
+  /**
+   * A `Stmt` that appears at the same location as a candidate statement.
+   */
+  private class RelevantStmt extends MyStmt {
+    CandidateStmt s;
+
+    RelevantStmt() {
+      exists(string filepath, int startline, int startcolumn, int endline, int endcolumn |
+        hasLocation(this, filepath, startline, startcolumn, endline, endcolumn) and
+        hasLocation(s, filepath, startline, startcolumn, endline, endcolumn)
+      ) and
+      // Not within a macro expansion, as we cannot match up instances by location in that
+      // case
+      isNotWithinMacroExpansion(this) and
+      // Ignore catch handlers, as they occur at the same location as the catch block
+      not this instanceof Handler
+    }
+
+    CandidateStmt getCandidateStmt() { result = s }
+  }
+
+  newtype TResultStmts =
+    TLogicalResultStmt(string filepath, int startline, int startcolumn, int endline, int endcolumn) {
+      exists(CandidateStmt s |
+        // Only consider candidates where we can match up the location
+        isNotWithinMacroExpansion(s) and
+        hasLocation(s, filepath, startline, startcolumn, endline, endcolumn) and
+        // All relevant statements that occur at the same location are candidates
+        forex(RelevantStmt relevantStmt | s = relevantStmt.getCandidateStmt() |
+          relevantStmt instanceof CandidateStmt
+        )
+      )
+    }
+
+  /**
+   * A logical result statement, representing all instances of a statement that occur at the same
+   * location.
+   */
+  class LogicalResultStmt extends TLogicalResultStmt {
+    predicate hasLocationInfo(
+      string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {
+      this = TLogicalResultStmt(filepath, startline, startcolumn, endline, endcolumn)
+    }
+
+    /** Gets an instance of this logical result statement. */
+    CandidateStmt getAStmtInstance() {
+      exists(string filepath, int startline, int startcolumn, int endline, int endcolumn |
+        this = TLogicalResultStmt(filepath, startline, startcolumn, endline, endcolumn) and
+        hasLocation(result, filepath, startline, startcolumn, endline, endcolumn)
+      )
+    }
+
+    string toString() { result = getAStmtInstance().toString() }
+  }
+}