Exclude templates, improve performance

Author: MichaelRFairhurst

change_notes/2026-02-18-unused-type-improvements.md

@@ -3,4 +3,5 @@
      - Previous behavior considered anonymous types in variable declarations to be considered used by the variable definition itself. This has been improved to require that a field of the anonymous type is accessed for the type to be considered used.
      - Usages of a template type inside a specialization of that template are no longer considered usages of the template type.
      - Hidden friend declarations are no longer considered usages of the class they are declaring friendship for.
-     - Improved exclusions generally, for cases such as nested types and functions within functions. These previously were a source of incorrectly identified type uses.
+     - Improved exclusions generally, for cases such as nested types and functions within functions. These previously were a source of incorrectly identified type uses.
+     - Additional case added to detect `template <Enum = Enum::Value>` as a usage of `Enum`, without an explicit `tpl<Enum::Value>` usage.

cpp/common/src/codingstandards/cpp/ast/Class.qll

@@ -10,12 +10,19 @@ class LastClassDeclaration extends Declaration {
 
   pragma[nomagic]
   LastClassDeclaration() {
-    this =
-      max(Declaration decl, Location l |
-        decl = cls.getADeclaration() and
-        l = decl.getLocation()
-      |
-        decl order by l.getEndLine(), l.getEndColumn()
-      )
+    cls.getADeclaration() = this and
+    getLocation().getEndLine() = getLastLineOfClassDeclaration(cls)
   }
 }
+
+/**
+ * Gets the line number of the last line of the declaration of `cls`.
+ *
+ * This is often more performant to use than `LastClassDeclaration.getLocation().getEndLine()`.
+ */
+int getLastLineOfClassDeclaration(Class cls) {
+  result =
+    max(int endLine |
+      endLine = pragma[only_bind_out](cls).getADeclaration().getLocation().getEndLine()
+    )
+}

cpp/common/src/codingstandards/cpp/ast/HiddenFriend.qll

@@ -17,6 +17,13 @@
 import cpp
 import codingstandards.cpp.ast.Class
 
+/**
+ * A class that, by our best logic, appears to possibly be a hidden friend.
+ *
+ * Hidden friends are not directly represented in the database. Instances of this class have been
+ * found to have a location "within" the "body" of a class, and to satisfy other criteria that
+ * indicates it may be a hidden friend.
+ */
 class PossibleHiddenFriend extends HiddenFriendCandidate {
   ClassCandidate cls;
 
@@ -47,53 +54,76 @@ private class FileCandidate extends File {
 private class ClassCandidate extends Class {
   ClassCandidate() { getFile() instanceof FileCandidate }
 
+  /**
+   * Find the next declaration after this class that shares an enclosing element.
+   *
+   * This may be the next declaration after this class, or `getNextOrphanedDeclaration` may find the
+   * true next declaration after this class. These are split for performance reasons.
+   */
   Declaration getNextSiblingDeclaration() {
-    exists(LastClassDeclaration last |
-      last.getDeclaringType() = this and
-      result =
-        min(Declaration decl |
-          decl.getEnclosingElement() = this.getEnclosingElement() and
-          pragma[only_bind_out](decl.getFile()) = pragma[only_bind_out](this.getFile()) and
-          decl.getLocation().getStartLine() > last.getLocation().getEndLine()
-        |
-          decl order by decl.getLocation().getStartLine(), decl.getLocation().getStartColumn()
-        )
-    )
+    result =
+      min(Declaration decl |
+        decl.getEnclosingElement() = this.getEnclosingElement() and
+        pragma[only_bind_out](decl.getFile()) = pragma[only_bind_out](this.getFile()) and
+        decl.getLocation().getStartLine() > getLastLineOfClassDeclaration(this)
+      |
+        decl order by decl.getLocation().getStartLine(), decl.getLocation().getStartColumn()
+      )
   }
 
+  /**
+   * Get the next declaration after this class that does not have an enclosing element.
+   *
+   * This may be the next declaration after this class, or `getNextSiblingDeclaration` may find the
+   * true next declaration after this class. These are split for performance reasons.
+   *
+   * Note that `OrphanedDeclaration` excludes hidden friend candidates, so this will find the next
+   * orphan that is definitely not a hidden friend.
+   */
   Declaration getNextOrphanedDeclaration() {
-    exists(LastClassDeclaration last |
-      last.getDeclaringType() = this and
-      result =
-        min(OrphanedDeclaration decl, Location locLast, Location locDecl |
-          orphanHasFile(decl, this.getFile()) and
-          locDecl = decl.getLocation() and
-          locLast = last.getLocation() and
-          locLast.getStartLine() < locDecl.getEndLine()
-        |
-          decl order by locDecl.getStartLine(), locDecl.getStartColumn()
-        )
-    )
+    result =
+      min(OrphanedDeclaration decl, int startLine, int startColumn | // Location locDecl | // Location locLast, Location locDecl |
+        orphanHasLocation(decl, this.getFile(), startLine, startColumn) and
+        startLine > getLastLineOfClassDeclaration(this)
+      |
+        decl order by startLine, startColumn
+      )
   }
 
+  /**
+   * Get the first declaration definitely after this class, and not a hidden friend declaration, to
+   * determine the "end" location of this class.
+   */
   Declaration getFirstNonClassDeclaration() {
-    exists(LastClassDeclaration last |
-      last.getDeclaringType() = this and
-      result =
-        min(Declaration decl |
-          decl = getNextSiblingDeclaration() or decl = getNextOrphanedDeclaration()
-        |
-          decl order by decl.getLocation().getStartLine(), decl.getLocation().getStartColumn()
-        )
-    )
+    result =
+      min(Declaration decl |
+        decl = getNextSiblingDeclaration() or decl = getNextOrphanedDeclaration()
+      |
+        decl order by decl.getLocation().getStartLine(), decl.getLocation().getStartColumn()
+      )
   }
 }
 
+/**
+ * Helper predicate to improve join performance.
+ */
 pragma[nomagic]
-private predicate orphanHasFile(OrphanedDeclaration orphan, FileCandidate file) {
-  orphan.getFile() = file
+private predicate orphanHasLocation(
+  OrphanedDeclaration orphan, FileCandidate file, int endLine, int endColumn
+) {
+  orphan.getFile() = file and
+  orphan.getLocation().getEndLine() = endLine and
+  orphan.getLocation().getEndColumn() = endColumn
 }
 
+/**
+ * Orphaned declarations to be found by `getNextOrphanedDeclaration`.
+ *
+ * These are declarations with no enclosing element. Note that we exclude hidden friend candidates,
+ * as this class is used to find the declarations that are definitely not part of some class. This
+ * is done so we can detect if hidden friends may be within that class definition. Therefore we must
+ * exclude hidden friend candidates, even though those are also orphaned.
+ */
 private class OrphanedDeclaration extends Declaration {
   OrphanedDeclaration() {
     not exists(getEnclosingElement()) and
@@ -103,14 +133,25 @@ private class OrphanedDeclaration extends Declaration {
   }
 }
 
+/**
+ * Helper predicate to improve join performance.
+ */
 pragma[nomagic]
 private predicate classCandidateHasFile(ClassCandidate c, FileCandidate f) { c.getFile() = f }
 
+/**
+ * Helper predicate to improve join performance.
+ */
 pragma[nomagic]
 private predicate hiddenFriendCandidateHasFile(HiddenFriendCandidate h, FileCandidate f) {
   h.getFile() = f
 }
 
+/**
+ * Find the class locations that have declarations that could be hidden friend declarations, by
+ * comparing the locations of the candidate hidden friend functions to the location of the first
+ * declaration that clearly is outside that class.
+ */
 pragma[nomagic]
 private predicate hidesFriend(ClassCandidate c, HiddenFriendCandidate f) {
   exists(FileCandidate file, Location cloc, Location floc |

cpp/common/src/codingstandards/cpp/types/Uses.qll

@@ -89,15 +89,6 @@ predicate isWithinTypeDefinition(Locatable loc, Type type) {
     tpl = spec.getPrimaryTemplate() and
     isWithinTypeDefinition(loc, spec)
   )
-  //exists(TemplateClass tpl, ClassTemplateSpecialization spec |
-  //  tpl.getAnInstantiation() = type and
-  //  tpl = spec.getPrimaryTemplate() and
-  //  isWithinTypeDefinition(loc, spec)
-  //)
-  //exists(ClassTemplateSpecialization spec |
-  //  specializationSharesType(type, spec) and
-  //  isWithinTypeDefinition(loc, spec)
-  //)
 }
 
 private Locatable getATypeUse_i(Type type, string reason) {
@@ -181,6 +172,10 @@ private Locatable getATypeUse_i(Type type, string reason) {
     // Temporary object creation of type `type`
     exists(TemporaryObjectExpr toe | result = toe | type = toe.getType()) and
     reason = "used in temporary object expr"
+    or
+    // template<Type t> ...
+    exists(Declaration decl | result = decl | type = decl.getATemplateArgumentKind()) and
+    reason = "used as a non-type template parameter"
   )
   or
   // Recursive case - used by a used type

cpp/misra/src/rules/RULE-0-2-3/UnusedTypeWithLimitedVisibility.ql

@@ -18,9 +18,31 @@ import cpp
 import codingstandards.cpp.misra
 import codingstandards.cpp.types.Uses
 
+class UninstantiatedTemplate extends Element {
+  UninstantiatedTemplate() {
+    this instanceof TemplateClass and
+    not exists(this.(TemplateClass).getAnInstantiation())
+    or
+    this instanceof TemplateFunction and
+    not exists(this.(TemplateFunction).getAnInstantiation())
+  }
+
+  predicate canAccessNamespace(Namespace n) {
+    n = this.(Declaration).getNamespace().getParentNamespace*()
+  }
+}
+
+predicate isExcludedNamespaceDueToTemplate(Namespace n) {
+  exists(UninstantiatedTemplate t | t.canAccessNamespace(n))
+}
+
+predicate maybeUsedInUninstantiatedTemplate(UserType type) {
+  isExcludedNamespaceDueToTemplate(type.getNamespace())
+}
+
 predicate hasLimitedVisibility(UserType type) {
   type.isLocal() or
-  type.getNamespace().isAnonymous()
+  type.getNamespace().getParentNamespace*().isAnonymous()
 }
 
 predicate hasMaybeUnusedAttribute(UserType type) {
@@ -33,6 +55,7 @@ where
   hasLimitedVisibility(type) and
   not exists(getATypeUse(type)) and
   not hasMaybeUnusedAttribute(type) and
+  not maybeUsedInUninstantiatedTemplate(type) and
   not type instanceof TypeTemplateParameter and
   not type instanceof ClassTemplateSpecialization
 select type, "Type '" + type.getName() + "' with limited visibility is not used."

cpp/misra/test/rules/RULE-0-2-3/templates.cpp

@@ -0,0 +1,107 @@
+// Test types used in templates.
+//
+// The rule is clear that even a usage in an uninstantiated template should be
+// counted. However, we don't have enough information from the CodeQL extractor
+// to do this precisely, so we err on the side of false negatives.
+//
+// The only API to find these type references in uninstantiated templates
+// directly is `TypeMention`, which is too disassociated from the AST to easily
+// determine whether than mention occurs in or outside of the definition of
+// the type itself, inside a template, etc.
+namespace {
+
+// The following code is too hard to read without namespace indendation.
+// clang-format off
+
+/**
+ * Test case 1: A type is used inside an instantiated template
+ */
+namespace instantiated_use {
+    struct A1 {}; // COMPLIANT
+
+    template <typename T> // COMPLIANT
+    void foo(A1 l1) {}
+
+    void f1() { foo<int>(A1{}); }
+} // namespace instantiated_use
+
+/**
+ * Test case 2: A type is used inside an uninstantiated template
+ */
+namespace uninstantiated_use {
+    struct A1 {}; // COMPLIANT
+
+    template <typename T> // COMPLIANT
+    void foo(A1 l1) {}
+} // namespace uninstantiated_use
+
+/**
+ * Test case 3: A type is not used by a relevant template that is instantiated
+ */
+namespace instantiated_unused {
+    struct A1 {}; // NON_COMPLIANT
+
+    template <typename T> // COMPLIANT
+    void foo(int l1) {}
+
+    void f1() { foo<int>(42); }
+} // namespace instantiated_unused
+
+/**
+ * Test case 4: A type that is not used by a relevant template that is not
+ * instantiated
+ */
+namespace uninstantiated_unused {
+    struct A1 {}; // NON_COMPLIANT[False Negative]
+
+    template <typename T> // COMPLIANT
+    void foo(int l1) {}
+} // namespace uninstantiated_unused
+
+/**
+ * Test case 5: A type that is used to instantiate a template
+ */
+namespace use_by_instantiation {
+    struct A1 {}; // COMPLIANT
+
+    template <typename T> // COMPLIANT
+        void foo() {
+        T l1;
+    }
+
+    void f1() { foo<A1>(); }
+} // namespace use_by_instantiation
+
+/**
+ * Test case 6: A type that is used as the type of a template parameter
+ */
+namespace use_as_template_parameter_type {
+    enum A1 { a };
+
+    template <A1 a = A1::a> void foo() {} // COMPLIANT
+
+    // Instantiate the template -- if it isn't instantiated, the alert for A1 is
+    // suppressed regardless of template parameter type usage
+    void f1() { foo(); }
+} // namespace use_as_template_parameter_type
+
+/**
+ * Test case 6: A type that is used as the default value of a non-type template
+ * parameter
+ */
+namespace use_as_template_parameter_default_value {
+    class A1 { // COMPLIANT[False positive]
+        static const int a = 42;
+    };
+
+    // The only API to find this in the database is `TypeMention`, which is too
+    // disassociated from the AST to easily determine if it is used in or
+    // outside of the definition of `A1`.
+    template <int a = A1::a> void foo() {}
+
+    // Instantiate the template -- if it isn't instantiated, the alert for A1 is
+    // suppressed regardless of template parameter default value
+    void f1() { foo(); }
+} // namespace use_as_template_parameter_default_value
+
+} // namespace