[Includecleaner] Introduce RefType to ast walking

RefTypes are distinct categories for each reference to a symbol. They
are signals indicating strength of a reference, that'll enable different
decision making based on the finding being provided.

There are 3 kinds of ref types:
- Explicit, the reference is spelled in the code.
- Implicit, the reference is not directly visible in the code.
- Ambigious, the reference exists but can't be proven as used (e.g.
  overloads brought in by a using decl but not used by the code).

Differential Revision: https://reviews.llvm.org/D135859

Author: kadircet

clang-tools-extra/include-cleaner/include/clang-include-cleaner/Analysis.h

@@ -26,10 +26,10 @@ namespace include_cleaner {
 ///
 /// References occur at a particular location, refer to a single symbol, and
 /// that symbol may be provided by several headers.
-/// FIXME: Provide signals about the reference type and providing headers so the
-/// caller can filter and rank the results.
-using UsedSymbolCB = llvm::function_ref<void(
-    SourceLocation RefLoc, Symbol Target, llvm::ArrayRef<Header> Providers)>;
+/// FIXME: Provide signals about the providing headers so the caller can filter
+/// and rank the results.
+using UsedSymbolCB = llvm::function_ref<void(SymbolReference SymRef,
+                                             llvm::ArrayRef<Header> Providers)>;
 
 /// Find and report all references to symbols in a region of code.
 ///

clang-tools-extra/include-cleaner/include/clang-include-cleaner/Types.h

@@ -42,9 +42,7 @@ struct Macro {
   /// The location of the Name where the macro is defined.
   SourceLocation Definition;
 
-  bool operator==(const Macro &S) const {
-    return Definition == S.Definition;
-  }
+  bool operator==(const Macro &S) const { return Definition == S.Definition; }
 };
 
 /// An entity that can be referenced in the code.
@@ -78,12 +76,24 @@ struct Symbol {
 };
 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const Symbol &);
 
+/// Indicates the relation between the reference and the target.
+enum class RefType {
+  /// Target is named by the reference, e.g. function call.
+  Explicit,
+  /// Target isn't spelled, e.g. default constructor call in `Foo f;`
+  Implicit,
+  /// Target's use can't be proven, e.g. a candidate for an unresolved overload.
+  Ambiguous,
+};
+
 /// Indicates that a piece of code refers to a symbol.
 struct SymbolReference {
-  /// The symbol referred to.
-  Symbol Symbol;
   /// The point in the code that refers to the symbol.
   SourceLocation RefLocation;
+  /// The symbol referred to.
+  Symbol Target;
+  /// Relation type between the reference location and the target.
+  RefType RT;
 };
 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const SymbolReference &);
 

clang-tools-extra/include-cleaner/lib/Analysis.cpp

@@ -7,8 +7,8 @@
 //===----------------------------------------------------------------------===//
 
 #include "clang-include-cleaner/Analysis.h"
-#include "clang-include-cleaner/Types.h"
 #include "AnalysisInternal.h"
+#include "clang-include-cleaner/Types.h"
 #include "clang/AST/ASTContext.h"
 #include "clang/Basic/SourceManager.h"
 #include "clang/Tooling/Inclusions/StandardLibrary.h"
@@ -32,17 +32,17 @@ void walkUsed(llvm::ArrayRef<Decl *> ASTRoots, UsedSymbolCB CB) {
   tooling::stdlib::Recognizer Recognizer;
   for (auto *Root : ASTRoots) {
     auto &SM = Root->getASTContext().getSourceManager();
-    walkAST(*Root, [&](SourceLocation Loc, NamedDecl &ND) {
+    walkAST(*Root, [&](SourceLocation Loc, NamedDecl &ND, RefType RT) {
       if (auto SS = Recognizer(&ND)) {
         // FIXME: Also report forward decls from main-file, so that the caller
         // can decide to insert/ignore a header.
-        return CB(Loc, Symbol(*SS), toHeader(SS->headers()));
+        return CB({Loc, Symbol(*SS), RT}, toHeader(SS->headers()));
       }
       // FIXME: Extract locations from redecls.
       // FIXME: Handle IWYU pragmas, non self-contained files.
       // FIXME: Handle macro locations.
       if (auto *FE = SM.getFileEntryForID(SM.getFileID(ND.getLocation())))
-        return CB(Loc, Symbol(ND), {Header(FE)});
+        return CB({Loc, Symbol(ND), RT}, {Header(FE)});
     });
   }
   // FIXME: Handle references of macros.

clang-tools-extra/include-cleaner/lib/AnalysisInternal.h

@@ -21,6 +21,7 @@
 #ifndef CLANG_INCLUDE_CLEANER_ANALYSISINTERNAL_H
 #define CLANG_INCLUDE_CLEANER_ANALYSISINTERNAL_H
 
+#include "clang-include-cleaner/Types.h"
 #include "clang/Basic/SourceLocation.h"
 #include "llvm/ADT/STLFunctionalExtras.h"
 
@@ -37,10 +38,13 @@ namespace include_cleaner {
 ///   the primary location of the AST node found under Root.
 /// - the NamedDecl is the symbol referenced. It is canonical, rather than e.g.
 ///   the redecl actually found by lookup.
+/// - the RefType describes the relation between the SourceLocation and the
+///   NamedDecl.
 ///
 /// walkAST is typically called once per top-level declaration in the file
 /// being analyzed, in order to find all references within it.
-void walkAST(Decl &Root, llvm::function_ref<void(SourceLocation, NamedDecl &)>);
+void walkAST(Decl &Root,
+             llvm::function_ref<void(SourceLocation, NamedDecl &, RefType)>);
 
 /// Write an HTML summary of the analysis to the given stream.
 /// FIXME: Once analysis has a public API, this should be public too.

clang-tools-extra/include-cleaner/lib/HTMLReport.cpp

@@ -14,6 +14,7 @@
 //===----------------------------------------------------------------------===//
 
 #include "AnalysisInternal.h"
+#include "clang-include-cleaner/Analysis.h"
 #include "clang/AST/ASTContext.h"
 #include "clang/AST/Decl.h"
 #include "clang/AST/PrettyPrinter.h"
@@ -212,8 +213,9 @@ void writeHTMLReport(FileID File, llvm::ArrayRef<Decl *> Roots, ASTContext &Ctx,
                      llvm::raw_ostream &OS) {
   Reporter R(OS, Ctx, File);
   for (Decl *Root : Roots)
-    walkAST(*Root,
-            [&](SourceLocation Loc, const NamedDecl &D) { R.addRef(Loc, D); });
+    walkAST(*Root, [&](SourceLocation Loc, const NamedDecl &D, RefType) {
+      R.addRef(Loc, D);
+    });
   R.write();
 }
 

clang-tools-extra/include-cleaner/lib/Record.cpp

@@ -7,6 +7,7 @@
 //===----------------------------------------------------------------------===//
 
 #include "clang-include-cleaner/Record.h"
+#include "clang-include-cleaner/Types.h"
 #include "clang/AST/ASTConsumer.h"
 #include "clang/AST/ASTContext.h"
 #include "clang/AST/DeclGroup.h"
@@ -86,8 +87,9 @@ class PPRecorder : public PPCallbacks {
     if (MI.isBuiltinMacro())
       return; // __FILE__ is not a reference.
     Recorded.MacroReferences.push_back(
-        SymbolReference{Macro{Tok.getIdentifierInfo(), MI.getDefinitionLoc()},
-                        Tok.getLocation()});
+        SymbolReference{Tok.getLocation(),
+                        Macro{Tok.getIdentifierInfo(), MI.getDefinitionLoc()},
+                        RefType::Explicit});
   }
 
   bool Active = false;
@@ -254,5 +256,4 @@ std::unique_ptr<PPCallbacks> RecordedPP::record(const Preprocessor &PP) {
   return std::make_unique<PPRecorder>(*this, PP);
 }
 
-
 } // namespace clang::include_cleaner

clang-tools-extra/include-cleaner/lib/Types.cpp

@@ -46,7 +46,7 @@ llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, const Include &I) {
 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, const SymbolReference &R) {
   // We can't decode the Location without SourceManager. Its raw representation
   // isn't completely useless (and distinguishes SymbolReference from Symbol).
-  return OS << R.Symbol << "@0x"
+  return OS << R.Target << "@0x"
             << llvm::utohexstr(R.RefLocation.getRawEncoding(),
                                /*Width=*/CHAR_BIT *
                                    sizeof(SourceLocation::UIntTy));

clang-tools-extra/include-cleaner/lib/WalkAST.cpp

@@ -7,6 +7,7 @@
 //===----------------------------------------------------------------------===//
 
 #include "AnalysisInternal.h"
+#include "clang-include-cleaner/Analysis.h"
 #include "clang/AST/Decl.h"
 #include "clang/AST/DeclCXX.h"
 #include "clang/AST/Expr.h"
@@ -16,15 +17,21 @@
 #include "clang/AST/Type.h"
 #include "clang/AST/TypeLoc.h"
 #include "clang/Basic/SourceLocation.h"
+#include "clang/Basic/SourceManager.h"
 #include "llvm/ADT/STLExtras.h"
 #include "llvm/Support/Casting.h"
 
 namespace clang::include_cleaner {
 namespace {
-using DeclCallback = llvm::function_ref<void(SourceLocation, NamedDecl &)>;
+using DeclCallback =
+    llvm::function_ref<void(SourceLocation, NamedDecl &, RefType)>;
 
 class ASTWalker : public RecursiveASTVisitor<ASTWalker> {
   DeclCallback Callback;
+  // Whether we're traversing declarations coming from a header file.
+  // This helps figure out whether certain symbols can be assumed as unused
+  // (e.g. overloads brought into an implementation file, but not used).
+  bool IsHeader = false;
 
   bool handleTemplateName(SourceLocation Loc, TemplateName TN) {
     // For using-templates, only mark the alias.
@@ -36,14 +43,16 @@ class ASTWalker : public RecursiveASTVisitor<ASTWalker> {
     return true;
   }
 
-  void report(SourceLocation Loc, NamedDecl *ND) {
+  void report(SourceLocation Loc, NamedDecl *ND,
+              RefType RT = RefType::Explicit) {
     if (!ND || Loc.isInvalid())
       return;
-    Callback(Loc, *cast<NamedDecl>(ND->getCanonicalDecl()));
+    Callback(Loc, *cast<NamedDecl>(ND->getCanonicalDecl()), RT);
   }
 
 public:
-  ASTWalker(DeclCallback Callback) : Callback(Callback) {}
+  ASTWalker(DeclCallback Callback, bool IsHeader)
+      : Callback(Callback), IsHeader(IsHeader) {}
 
   bool VisitDeclRefExpr(DeclRefExpr *DRE) {
     report(DRE->getLocation(), DRE->getFoundDecl());
@@ -56,23 +65,31 @@ class ASTWalker : public RecursiveASTVisitor<ASTWalker> {
   }
 
   bool VisitCXXConstructExpr(CXXConstructExpr *E) {
-    report(E->getLocation(), E->getConstructor());
+    report(E->getLocation(), E->getConstructor(),
+           E->getParenOrBraceRange().isValid() ? RefType::Explicit
+                                               : RefType::Implicit);
     return true;
   }
 
   bool VisitOverloadExpr(OverloadExpr *E) {
     // Since we can't prove which overloads are used, report all of them.
-    // FIXME: Provide caller with the ability to make a decision for such uses.
-    llvm::for_each(E->decls(),
-                   [this, E](NamedDecl *D) { report(E->getNameLoc(), D); });
+    llvm::for_each(E->decls(), [this, E](NamedDecl *D) {
+      report(E->getNameLoc(), D, RefType::Ambiguous);
+    });
     return true;
   }
 
   bool VisitUsingDecl(UsingDecl *UD) {
-    // FIXME: Provide caller with the ability to tell apart used/non-used
-    // targets.
-    for (const auto *Shadow : UD->shadows())
-      report(UD->getLocation(), Shadow->getTargetDecl());
+    for (const auto *Shadow : UD->shadows()) {
+      auto *TD = Shadow->getTargetDecl();
+      auto IsUsed = TD->isUsed() || TD->isReferenced();
+      // We ignore unused overloads inside implementation files, as the ones in
+      // headers might still be used by the dependents of the header.
+      if (!IsUsed && !IsHeader)
+        continue;
+      report(UD->getLocation(), TD,
+             IsUsed ? RefType::Explicit : RefType::Ambiguous);
+    }
     return true;
   }
 
@@ -135,7 +152,14 @@ class ASTWalker : public RecursiveASTVisitor<ASTWalker> {
 } // namespace
 
 void walkAST(Decl &Root, DeclCallback Callback) {
-  ASTWalker(Callback).TraverseDecl(&Root);
+  auto &AST = Root.getASTContext();
+  auto &SM = AST.getSourceManager();
+  // If decl isn't written in main file, assume it's coming from an include,
+  // hence written in a header.
+  bool IsRootedAtHeader =
+      AST.getLangOpts().IsHeaderFile ||
+      !SM.isWrittenInMainFile(SM.getSpellingLoc(Root.getLocation()));
+  ASTWalker(Callback, IsRootedAtHeader).TraverseDecl(&Root);
 }
 
 } // namespace clang::include_cleaner

clang-tools-extra/include-cleaner/unittests/AnalysisTest.cpp

@@ -50,12 +50,12 @@ TEST(WalkUsed, Basic) {
 
   auto &SM = AST.sourceManager();
   llvm::DenseMap<size_t, std::vector<Header>> OffsetToProviders;
-  walkUsed(TopLevelDecls, [&](SourceLocation RefLoc, Symbol S,
-                              llvm::ArrayRef<Header> Providers) {
-    auto [FID, Offset] = SM.getDecomposedLoc(RefLoc);
-    EXPECT_EQ(FID, SM.getMainFileID());
-    OffsetToProviders.try_emplace(Offset, Providers.vec());
-  });
+  walkUsed(TopLevelDecls,
+           [&](SymbolReference SymRef, llvm::ArrayRef<Header> Providers) {
+             auto [FID, Offset] = SM.getDecomposedLoc(SymRef.RefLocation);
+             EXPECT_EQ(FID, SM.getMainFileID());
+             OffsetToProviders.try_emplace(Offset, Providers.vec());
+           });
   auto HeaderFile = Header(AST.fileManager().getFile("header.h").get());
   auto MainFile = Header(SM.getFileEntryForID(SM.getMainFileID()));
   auto VectorSTL = Header(tooling::stdlib::Header::named("<vector>").value());

clang-tools-extra/include-cleaner/unittests/RecordTest.cpp

@@ -185,15 +185,15 @@ TEST_F(RecordPPTest, CapturesMacroRefs) {
       SM.translateFile(AST.fileManager().getFile("header.h").get()),
       Header.point("def"));
   ASSERT_THAT(Recorded.MacroReferences, Not(IsEmpty()));
-  Symbol OrigX = Recorded.MacroReferences.front().Symbol;
+  Symbol OrigX = Recorded.MacroReferences.front().Target;
   EXPECT_EQ("X", OrigX.macro().Name->getName());
   EXPECT_EQ(Def, OrigX.macro().Definition);
 
   std::vector<unsigned> RefOffsets;
   std::vector<unsigned> ExpOffsets; // Expansion locs of refs in macro locs.
   std::vector<SourceLocation> RefMacroLocs;
   for (const auto &Ref : Recorded.MacroReferences) {
-    if (Ref.Symbol == OrigX) {
+    if (Ref.Target == OrigX) {
       auto [FID, Off] = SM.getDecomposedLoc(Ref.RefLocation);
       if (FID == SM.getMainFileID()) {
         RefOffsets.push_back(Off);