C++: Ensure only one Variable exists for every global variable

Depending on the extraction order, before this change there might be multiple
`GlobalVariable`s per declared global variable. See the tests in
`cpp/ql/test/library-tests/variables/global`. This change ensures that only one
of those `GlobalVariable`s is visible to the user if we can locate a unique
definition. If not, the old situation persists.

Note that an exception needs to be made for templated variables. Here, the
definition refers to the non-instantiated template, while a declaration that
is not a definition refers to an instantiation. In case the instantiation refers
to a template parameter, the mangled names of the template and the instantiation
will be identical. This happens for example in the following case:
```
template <typename T>
T x = T(42);           // Uninstantiated templated variable

template <typename T>
class C {
  T y = x<T>;          // Instantiation using a template parameter
};
```
Since the uninstantiated template and the instantiation are two different
entities, we do not unify them as described above.

cpp/ql/lib/semmle/code/cpp/Element.qll

@@ -6,6 +6,7 @@
 import semmle.code.cpp.Location
 private import semmle.code.cpp.Enclosing
 private import semmle.code.cpp.internal.ResolveClass
+private import semmle.code.cpp.internal.ResolveGlobalVariable
 
 /**
  * Get the `Element` that represents this `@element`.
@@ -28,9 +29,12 @@ Element mkElement(@element e) { unresolveElement(result) = e }
 pragma[inline]
 @element unresolveElement(Element e) {
   not result instanceof @usertype and
+  not result instanceof @variable and
   result = e
   or
   e = resolveClass(result)
+  or
+  e = resolveGlobalVariable(result)
 }
 
 /**

cpp/ql/lib/semmle/code/cpp/Variable.qll

@@ -6,6 +6,7 @@ import semmle.code.cpp.Element
 import semmle.code.cpp.exprs.Access
 import semmle.code.cpp.Initializer
 private import semmle.code.cpp.internal.ResolveClass
+private import semmle.code.cpp.internal.ResolveGlobalVariable
 
 /**
  * A C/C++ variable. For example, in the following code there are four
@@ -32,6 +33,8 @@ private import semmle.code.cpp.internal.ResolveClass
  * can have multiple declarations.
  */
 class Variable extends Declaration, @variable {
+  Variable() { isVariable(underlyingElement(this)) }
+
   override string getAPrimaryQlClass() { result = "Variable" }
 
   /** Gets the initializer of this variable, if any. */

cpp/ql/lib/semmle/code/cpp/internal/ResolveGlobalVariable.qll

@@ -0,0 +1,60 @@
+private predicate hasDefinition(@globalvariable g) {
+  exists(@var_decl vd | var_decls(vd, g, _, _, _) | var_def(vd))
+}
+
+pragma[noinline]
+private predicate onlyOneCompleteGlobalVariableExistsWithMangledName(@mangledname name) {
+  strictcount(@globalvariable g | hasDefinition(g) and mangled_name(g, name)) = 1
+}
+
+/** Holds if `g` is a unique global variable with a definition named `name`. */
+pragma[noinline]
+private predicate isGlobalWithMangledNameAndWithDefinition(@mangledname name, @globalvariable g) {
+  hasDefinition(g) and
+  mangled_name(g, name) and
+  onlyOneCompleteGlobalVariableExistsWithMangledName(name)
+}
+
+/** Holds if `g` is a global variable without a definition named `name`. */
+pragma[noinline]
+private predicate isGlobalWithMangledNameAndWithoutDefinition(@mangledname name, @globalvariable g) {
+  not hasDefinition(g) and
+  mangled_name(g, name)
+}
+
+/**
+ * Holds if `incomplete` is a global variable without a definition, and there exists
+ * a unique global variable `complete` with the same name that does have a definition.
+ */
+private predicate hasTwinWithDefinition(@globalvariable incomplete, @globalvariable complete) {
+  exists(@mangledname name |
+    not variable_instantiation(incomplete, complete) and
+    isGlobalWithMangledNameAndWithoutDefinition(name, incomplete) and
+    isGlobalWithMangledNameAndWithDefinition(name, complete)
+  )
+}
+
+import Cached
+
+cached
+private module Cached {
+  /**
+   * If `v` is a global variable without a definition, and there exists a unique
+   * global variable with the same name that does have a definition, then the
+   * result is that unique global variable. Otherwise, the result is `v`.
+   */
+  cached
+  @variable resolveGlobalVariable(@variable v) {
+    hasTwinWithDefinition(v, result)
+    or
+    not hasTwinWithDefinition(v, _) and
+    result = v
+  }
+
+  cached
+  predicate isVariable(@variable v) {
+    not v instanceof @globalvariable
+    or
+    v = resolveGlobalVariable(_)
+  }
+}

cpp/ql/test/library-tests/variables/global/variables.expected

@@ -4,11 +4,7 @@
 | c.c:6:5:6:6 | ls | array of 4 {int} | 1 |
 | c.c:8:5:8:7 | iss | array of 4 {array of 2 {int}} | 1 |
 | c.c:12:11:12:11 | i | typedef {int} as "int_alias" | 1 |
-| c.h:4:12:4:13 | ks | array of {int} | 1 |
-| c.h:8:12:8:14 | iss | array of {array of 2 {int}} | 1 |
-| c.h:10:12:10:12 | i | int | 1 |
 | d.cpp:3:7:3:8 | xs | array of {int} | 1 |
-| d.h:3:14:3:15 | xs | array of 2 {int} | 1 |
 | file://:0:0:0:0 | (unnamed parameter 0) | reference to {const {struct __va_list_tag}} | 1 |
 | file://:0:0:0:0 | (unnamed parameter 0) | rvalue reference to {struct __va_list_tag} | 1 |
 | file://:0:0:0:0 | fp_offset | unsigned int | 1 |