[clang-tools-extra] [clang-include-cleaner] Generalize analyze() to accept callbacks and deprecate the old overload and AnalysisResults (PR #241509)

via cfe-commits cfe-commits at lists.llvm.org
Wed Nov 11 17:52:41 PST 2026


https://github.com/higher-performance updated https://github.com/llvm/llvm-project/pull/241509

>From 17f7325769b3e03b3b8cafb73e1f8fb682f47a05 Mon Sep 17 00:00:00 2001
From: higher-performance <higher.performance.github at gmail.com>
Date: Wed, 11 Nov 2026 15:54:23 -0500
Subject: [PATCH] [clang-include-cleaner] Generalize analyze() to accept
 callbacks and provide more information to enable efficient
 cross-translation-unit analysis

---
 .../include/clang-include-cleaner/Analysis.h  | 19 +++-
 .../include-cleaner/lib/Analysis.cpp          | 92 ++++++++++++-------
 2 files changed, 78 insertions(+), 33 deletions(-)

diff --git a/clang-tools-extra/include-cleaner/include/clang-include-cleaner/Analysis.h b/clang-tools-extra/include-cleaner/include/clang-include-cleaner/Analysis.h
index c3241763237d14..b2edaec5c0581d 100644
--- a/clang-tools-extra/include-cleaner/include/clang-include-cleaner/Analysis.h
+++ b/clang-tools-extra/include-cleaner/include/clang-include-cleaner/Analysis.h
@@ -22,6 +22,7 @@
 #include "llvm/ADT/StringRef.h"
 #include <string>
 #include <utility>
+#include <vector>
 
 namespace clang {
 class SourceLocation;
@@ -71,8 +72,24 @@ struct AnalysisResults {
 /// This exposes conclusions but not reasons: use lower-level walkUsed for that.
 ///
 /// The HeaderFilter is a predicate that receives absolute path or spelling
-/// without quotes/brackets, when a phyiscal file doesn't exist.
+/// without quotes/brackets, when a physical file doesn't exist.
 /// No analysis will be performed for headers that satisfy the predicate.
+///
+/// The UnusedHeaderCallback is called for every header that is unused.
+///
+/// The Callback is called for every symbol reference. The Header pointer is
+/// NULL for every missing #include. Note that the Header pointer is temporary
+/// and might not survive the callback.
+void analyze(
+    llvm::ArrayRef<Decl *> ASTRoots, llvm::ArrayRef<SymbolReference> MacroRefs,
+    const Includes &Inc, const PragmaIncludes *PI, const Preprocessor &PP,
+    llvm::function_ref<bool(llvm::StringRef)> HeaderFilter,
+    llvm::function_ref<void(const Include *)> UnusedHeaderCallback,
+    llvm::function_ref<void(const Header *, const Include *,
+                            llvm::StringRef Spelling, const SymbolReference &,
+                            llvm::ArrayRef<Header> Providers)>
+        Callback);
+
 AnalysisResults
 analyze(llvm::ArrayRef<Decl *> ASTRoots,
         llvm::ArrayRef<SymbolReference> MacroRefs, const Includes &I,
diff --git a/clang-tools-extra/include-cleaner/lib/Analysis.cpp b/clang-tools-extra/include-cleaner/lib/Analysis.cpp
index 922a690dfc47cb..f22364ef6fa9f9 100644
--- a/clang-tools-extra/include-cleaner/lib/Analysis.cpp
+++ b/clang-tools-extra/include-cleaner/lib/Analysis.cpp
@@ -87,36 +87,41 @@ void walkUsed(llvm::ArrayRef<Decl *> ASTRoots,
   }
 }
 
-AnalysisResults
-analyze(llvm::ArrayRef<Decl *> ASTRoots,
-        llvm::ArrayRef<SymbolReference> MacroRefs, const Includes &Inc,
-        const PragmaIncludes *PI, const Preprocessor &PP,
-        llvm::function_ref<bool(llvm::StringRef)> HeaderFilter) {
+void analyze(
+    llvm::ArrayRef<Decl *> ASTRoots, llvm::ArrayRef<SymbolReference> MacroRefs,
+    const Includes &Inc, const PragmaIncludes *PI, const Preprocessor &PP,
+    llvm::function_ref<bool(llvm::StringRef)> HeaderFilter,
+    llvm::function_ref<void(const Include *)> UnusedHeaderCallback,
+    llvm::function_ref<void(const Header *, const Include *,
+                            llvm::StringRef Spelling, const SymbolReference &,
+                            llvm::ArrayRef<Header> Providers)>
+        Callback) {
   auto &SM = PP.getSourceManager();
   const auto MainFile = *SM.getFileEntryRefForID(SM.getMainFileID());
   llvm::DenseSet<const Include *> Used;
-  llvm::StringMap<Header> Missing;
   constexpr auto DefaultHeaderFilter = [](llvm::StringRef) { return false; };
   if (!HeaderFilter)
     HeaderFilter = DefaultHeaderFilter;
   OptionalDirectoryEntryRef ResourceDir =
       PP.getHeaderSearchInfo().getModuleMap().getBuiltinDir();
   walkUsed(ASTRoots, MacroRefs, PI, PP,
-           [&](const SymbolReference &Ref, llvm::ArrayRef<Header> Providers) {
-             bool Satisfied = false;
+           [=, &Used, &PP, &Inc](const SymbolReference &Ref,
+                                 llvm::ArrayRef<Header> Providers) {
+             std::pair<const Header *, const Include *> Satisfied;
              for (const Header &H : Providers) {
                if (H.kind() == Header::Physical &&
                    (H.physical() == MainFile ||
                     H.physical().getDir() == ResourceDir)) {
-                 Satisfied = true;
+                 Satisfied = {&H, nullptr};
                }
                for (const Include *I : Inc.match(H)) {
                  Used.insert(I);
-                 Satisfied = true;
+                 Satisfied = {&H, I};
                }
              }
              // Bail out if we can't (or need not) insert an include.
-             if (Satisfied || Providers.empty() || Ref.RT != RefType::Explicit)
+             if (Satisfied.first || Providers.empty() ||
+                 Ref.RT != RefType::Explicit)
                return;
              if (HeaderFilter(Providers.front().resolvedPath()))
                return;
@@ -126,36 +131,59 @@ analyze(llvm::ArrayRef<Decl *> ASTRoots,
              // refers to it.
              auto Spelling = spellHeader(
                  {Providers.front(), PP.getHeaderSearchInfo(), MainFile});
-             for (const Include *I : Inc.match(Header{Spelling})) {
+             Header similar_header(Spelling);
+             for (const Include *I : Inc.match(similar_header)) {
                Used.insert(I);
-               Satisfied = true;
+               Satisfied = {&similar_header, I};
+             }
+             if (Callback) {
+               Callback(Satisfied.first, Satisfied.second, Spelling, Ref,
+                        Providers);
              }
-             if (!Satisfied)
-               Missing.try_emplace(std::move(Spelling), Providers.front());
            });
 
-  AnalysisResults Results;
-  for (const Include &I : Inc.all()) {
-    if (Used.contains(&I) || !I.Resolved ||
-        HeaderFilter(I.Resolved->getName()) ||
-        I.Resolved->getDir() == ResourceDir)
-      continue;
-    if (PI) {
-      if (PI->shouldKeep(*I.Resolved))
+  if (UnusedHeaderCallback) {
+    for (const Include &I : Inc.all()) {
+      if (Used.contains(&I) || !I.Resolved ||
+          HeaderFilter(I.Resolved->getName()) ||
+          I.Resolved->getDir() == ResourceDir)
         continue;
-      // Check if main file is the public interface for a private header. If so
-      // we shouldn't diagnose it as unused.
-      if (auto PHeader = PI->getPublic(*I.Resolved); !PHeader.empty()) {
-        PHeader = PHeader.trim("<>\"");
-        // Since most private -> public mappings happen in a verbatim way, we
-        // check textually here. This might go wrong in presence of symlinks or
-        // header mappings. But that's not different than rest of the places.
-        if (MainFile.getName().ends_with(PHeader))
+      if (PI) {
+        if (PI->shouldKeep(*I.Resolved))
           continue;
+        // Check if main file is the public interface for a private header. If
+        // so we shouldn't diagnose it as unused.
+        if (auto PHeader = PI->getPublic(*I.Resolved); !PHeader.empty()) {
+          PHeader = PHeader.trim("<>\"");
+          // Since most private -> public mappings happen in a verbatim way, we
+          // check textually here. This might go wrong in presence of symlinks
+          // or header mappings. But that's not different than rest of the
+          // places.
+          if (MainFile.getName().ends_with(PHeader))
+            continue;
+        }
       }
+      UnusedHeaderCallback(&I);
     }
-    Results.Unused.push_back(&I);
   }
+}
+
+AnalysisResults
+analyze(llvm::ArrayRef<Decl *> ASTRoots,
+        llvm::ArrayRef<SymbolReference> MacroRefs, const Includes &Inc,
+        const PragmaIncludes *PI, const Preprocessor &PP,
+        llvm::function_ref<bool(llvm::StringRef)> HeaderFilter) {
+  llvm::StringMap<Header> Missing;
+  AnalysisResults Results;
+  analyze(
+      ASTRoots, MacroRefs, Inc, PI, PP, HeaderFilter,
+      [&Results](const Include *I) { Results.Unused.push_back(I); },
+      [&Results](const Header *H, const Include *, llvm::StringRef Spelling,
+                 const SymbolReference &, llvm::ArrayRef<Header> Providers) {
+        if (!H) {
+          Results.Missing.emplace_back(Spelling, Providers.front());
+        }
+      });
   for (auto &E : Missing)
     Results.Missing.emplace_back(E.first().str(), E.second);
   llvm::sort(Results.Missing);



More information about the cfe-commits mailing list