[clang-tidy] Add infrastructure support for running on project-level information

[bahramib]

Summary

This patch adds the necessary infrastructure bindings and overloads that
allow checks to implement collecting and emitting per-TU data to a
directory from which the diagnosis mode can read it and decide whether
to diagnose.

What checks emit and how they transform the data is a per-check
implementation detail.

[martong]

Very good, this is a great initiative! Also, the quality of this patch is high, docs are great, even the release notes are updated. I would accept if I were that confident in Clang-tidy.

[aaron.ballman]

Thanks, I think this is a neat idea! I haven't had the chance to review thoroughly yet, but wanted to point out that precommit CI is showing a fair amount of failures that I believe are related to your patch.

[whisperity]

In D124447#3493446, @aaron.ballman wrote:

precommit CI is showing a fair amount of failures that I believe are related to your patch.

It was me who helped @bahramib to rebase and split a much larger and more convoluted development history into broken up patches for review, and I have no idea what is causing the CI issues, because all the CI issues are related to unit test libraries removing const from fixits and such(??) which this patch (or any in the current patch set) doesn't even touch, at all. I did run the test targets locally... it's likely that simply the rebase and the push happened against an unclean/breaking main branch...

We can investigate later, but I think the review can be done either way. If something is related, it has to be tangential, we strived to make the entire new infrastructure fully backwards compatible.

The only reason I can think of is that some LangOpts might not be forwarded correctly somewhere, will definitely look into this.

(Also, full disclosure, I am the B.Sc. thesis supervisor of @bahramib so I'm only here to keep an eye on (and fix up the "very LLVM-y" parts) of the check, I cannot impartially review and accept this as I was involved in the full creation process. 😇)

[whisperity]

In D124447#3493996, @whisperity wrote:

In D124447#3493446, @aaron.ballman wrote:

precommit CI is showing a fair amount of failures that I believe are related to your patch.

I have no idea what is causing the CI issues, because all the CI issues are related to unit test libraries removing const from fixits and such(??) which this patch (or any in the current patch set) doesn't even touch, at all. I did run the test targets locally... it's likely that simply the rebase and the push happened against an unclean/breaking main branch...

Rebase & rerun against a current main branch produces the issues locally for me, too. So far I have no idea what might be causing this, but I'll keep on digging. However, let's continue with discussing the general approach meanwhile. 🙂

[whisperity]

In D124447#3506536, @whisperity wrote:

In D124447#3493996, @whisperity wrote:

In D124447#3493446, @aaron.ballman wrote:

precommit CI is showing a fair amount of failures that I believe are related to your patch.

I have no idea what is causing the CI issues, because all the CI issues are related to unit test libraries removing const from fixits and such(??) which this patch (or any in the current patch set) doesn't even touch, at all. I did run the test targets locally... it's likely that simply the rebase and the push happened against an unclean/breaking main branch...

Rebase & rerun against a current main branch produces the issues locally for me, too. So far I have no idea what might be causing this, but I'll keep on digging. However, let's continue with discussing the general approach meanwhile. 🙂

Actually, it turned out to be easy after all! The implementation is backwards compatible on the command-line but was not for the "machine-driven" tests that are implemented as C++ code and execution scaffold. Adding the below commented change to the diff completely solved the failing tests for me locally (turns out none of the checks were actually running the check() callback!), but I cannot update a "Revision" that I do not own.

clang-tools-extra/clang-tidy/ClangTidyOptions.h

60

⚠ The crucial fix against the unit-test failures!

[aaron.ballman]

In general, I think this is looking pretty close to good. Whether clang-tidy should get this functionality in this form or not is a bit less clear to me. *I* think it's helpful functionality and the current approach is reasonable, but I think it might be worthwhile to have a community RFC to see if others agree. CC @alexfh in case he wants to make a code owner decision instead.

clang-tools-extra/clang-tidy/ClangTidy.cpp

321–324

I'd add the braces for readability despite them not being strictly required.

347–348

clang-tools-extra/clang-tidy/ClangTidyCheck.cpp

54

I'm on the fence about whether this should be an unreachable or an assert. This seems like it's an assertion situation (if you reach that case, the programmer made a mistake; it's not that you can never reach this case).

clang-tools-extra/clang-tidy/ClangTidyCheck.h

118–119

122

I'm not certain what "to the right" means in this context, so some extra clarification here would be reasonable. I think it's saying that it's a post order traversal?

clang-tools-extra/clang-tidy/ClangTidyDiagnosticConsumer.cpp

242–243

I think this would be expressed better via an assert.

246

Why is this a reference?

clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp

552–553

This looks like a TOCTOU issue; create_directory() takes an argument for whether you should ignore existing or not, that should suffice here, right?

[kadircet]

The idea looks great in general, I didn't get a chance to look at all the details but this also creates some concerns for integrations of clang-tidy checks in other environments (like clangd or tidy running in distributed systems) as the workflow actually needs to be run twice and be able to write to disk.

So I'd actually ask for changing the way the outputting is performed. It'd be better to have an interface where checks can perform this finding reporting operation, that way clangd and other means of running clang-tidy can implement that interface as they see fit (put everything into a database, collect in memory, etc.) and clang-tidy binary by default can implement writing to disk (through VFS rather than physical FS operations if possible).
In addition to that it'd be nice to have a flag on checks to indicate whether they can work in a certain phase, and make sure instantiation only happens for checks that can run at a certain phase. This ensures checks can have assumptions about the phase they're being run at and also drivers can assume checks won't perform invalid operations. That way we should get to reduce complexity on both sides. We can by default say that checks work in diagnose phase and doesn't work in other phases, then relevant checks can override these bits.

As a more general comment to the overall approach, the "compact" phase probably doesn't require any tidy specific infrastructure. Only pieces that can benefit re-use is outputting edits, but this is already common infra across all clang-tools. So another direction overall here could be to actually change the way clang-tidy outputs findings into two forms:

• a machine readable format, that can later on be used by other tools to perform more analysis
• a human readable format, the usual thing today.

Have we considered this? Any reason for not going down this path?

clang-tools-extra/clang-tidy/ClangTidyCheck.cpp

98

filename and contents might not be enough here. as clang-tidy is usually run over a compilation database and there might be multiple entries for the same file with different compile flags. i think we also want to include a hash of the flags in the filename.

[sammccall]

In D124447#3608747, @aaron.ballman wrote:

In general, I think this is looking pretty close to good. Whether clang-tidy should get this functionality in this form or not is a bit less clear to me. *I* think it's helpful functionality and the current approach is reasonable, but I think it might be worthwhile to have a community RFC to see if others agree. CC @alexfh in case he wants to make a code owner decision instead.

+1 to a need for the RFC here, there are ecosystem questions that I think should be addressed first but aren't in scope of this patch.
Changing the "plugin signature" of checks in a widely-used plugin system like clang-tidy shouldn't be taken lightly.

In particular:

• what is a motivating example of the problem you're solving? (sorry if I missed this)
• which checks do you plan to contribute/modify that will make use of this functionality?
• for existing users of clang-tidy that don't adopt the new workflow (clang-tidy without --multipass-phase, code review systems, clangd and other IDEs), how do they interact with such checks?
• will you be maintaining/extending the framework functionality & design long-term, or for a particular time span?
• do you have plans for how to deploy this to users? (e.g. running the CLI commands by hand, or integration into a code review tool)
• what are the expectations on check owners for understanding/supporting this mode?
• is this extensible to distributed execution like clang-tidy currently is? (this patch appears to assume coordination through a shared local filesystem, and "compact" appears to be a large monolithic step)
• what alternative designs were considered?

I really would like to see these addressed in an RFC rather than here - I think it will attract wider discussion.
(I'm sure I'll have an opinion, but mostly hoping to flesh out the plan to evolve clang-tidy so others can react)

[whisperity]

In D124447#3645197, @sammccall wrote:

In D124447#3608747, @aaron.ballman wrote:

In general, I think this is looking pretty close to good. Whether clang-tidy should get this functionality in this form or not is a bit less clear to me. *I* think it's helpful functionality and the current approach is reasonable, but I think it might be worthwhile to have a community RFC to see if others agree. CC @alexfh in case he wants to make a code owner decision instead.

+1 to a need for the RFC here, there are ecosystem questions that I think should be addressed first but aren't in scope of this patch.

I will attempt to write a concise response to this today (and tomorrow)! Sorry, I was away travelling to and doing post-action bureaucracy of conferences the past few weeks.

[whisperity]

In D124447#3651074, @whisperity wrote:

I will attempt to write a concise response to this today (and tomorrow)! Sorry, I was away travelling to and doing post-action bureaucracy of conferences the past few weeks.

@aaron.ballman @kadircet @sammccall, FYI, I have posted it here: http://discourse.llvm.org/t/rfc-enhancing-clang-tidy-with-project-level-knowledge/63960

clang-tools-extra/clang-tidy/ClangTidy.h

 std::vector<ClangTidyError>
 runClangTidy(clang::tidy::ClangTidyContext &Context,
              const tooling::CompilationDatabase &Compilations,
              ArrayRef<std::string> InputFiles,
              llvm::IntrusiveRefCntPtr<llvm::vfs::OverlayFileSystem> BaseFS,
              bool ApplyAnyFix, bool EnableCheckProfile = false,
              llvm::StringRef StoreCheckProfile = StringRef());
 
+/// Run the multi-pass project-level "compact" routine of checks that support
+/// such on the data available in the Context.
+void runClangTidyCompactPhase(clang::tidy::ClangTidyContext &Context);
+
 /// Controls what kind of fixes clang-tidy is allowed to apply.
 enum FixBehaviour {
   /// Don't try to apply any fix.
   FB_NoFix,
   /// Only apply fixes added to warnings.
   FB_Fix,
   /// Apply fixes found in notes.
   FB_FixNotes

clang-tools-extra/clang-tidy/ClangTidy.cpp

private:
   llvm::StringMap<Replacements> FileReplacements;
   ClangTidyContext &Context;
   FixBehaviour ApplyFixes;
   unsigned TotalFixes;
   unsigned AppliedFixes;
   unsigned WarningsAsErrors;
 };
 
+using CheckVec = std::vector<std::unique_ptr<ClangTidyCheck>>;
+
 class ClangTidyASTConsumer : public MultiplexConsumer {
 public:
   ClangTidyASTConsumer(std::vector<std::unique_ptr<ASTConsumer>> Consumers,
                        std::unique_ptr<ClangTidyProfiling> Profiling,
                        std::unique_ptr<ast_matchers::MatchFinder> Finder,
-                       std::vector<std::unique_ptr<ClangTidyCheck>> Checks)
+                       CheckVec Checks, MultipassProjectPhase MultipassPhase)
       : MultiplexConsumer(std::move(Consumers)),
         Profiling(std::move(Profiling)), Finder(std::move(Finder)),
-        Checks(std::move(Checks)) {}
+        Checks(std::move(Checks)), MultipassPhase(MultipassPhase) {}
+
+  ~ClangTidyASTConsumer() {
+    if (MultipassPhase == MultipassProjectPhase::Collect)
+      // Allow the checks to write their data at the end of execution.
+      for (auto &Check : Checks)
+        Check->runPostCollect();
+  }
 
 private:
   // Destructor order matters! Profiling must be destructed last.
   // Or at least after Finder.
   std::unique_ptr<ClangTidyProfiling> Profiling;
   std::unique_ptr<ast_matchers::MatchFinder> Finder;
-  std::vector<std::unique_ptr<ClangTidyCheck>> Checks;
+  CheckVec Checks;
+  MultipassProjectPhase MultipassPhase;
 };
 
 } // namespace
 
+static void instantiateTidyModules(ClangTidyCheckFactories &CheckFactories) {
+  for (ClangTidyModuleRegistry::entry E : ClangTidyModuleRegistry::entries()) {
+    std::unique_ptr<ClangTidyModule> M = E.instantiate();
+    M->addCheckFactories(CheckFactories);
+  }
+}
+
+static CheckVec instantiateChecks(ClangTidyContext &Context,
+                                  ClangTidyCheckFactories &CheckFactories) {
+  CheckVec Checks = CheckFactories.createChecks(&Context);
+  return Checks;
+}
+
 ClangTidyASTConsumerFactory::ClangTidyASTConsumerFactory(
     ClangTidyContext &Context,
     IntrusiveRefCntPtr<llvm::vfs::OverlayFileSystem> OverlayFS)
     : Context(Context), OverlayFS(std::move(OverlayFS)),
       CheckFactories(new ClangTidyCheckFactories) {
-  for (ClangTidyModuleRegistry::entry E : ClangTidyModuleRegistry::entries()) {
-    std::unique_ptr<ClangTidyModule> Module = E.instantiate();
-    Module->addCheckFactories(*CheckFactories);
-  }
+  instantiateTidyModules(*CheckFactories);
 }
 
 #if CLANG_TIDY_ENABLE_STATIC_ANALYZER
 static void
 setStaticAnalyzerCheckerOpts(const ClangTidyOptions &Opts,
                              clang::AnalyzerOptions &AnalyzerOptions) {
   StringRef AnalyzerPrefix(AnalyzerCheckNamePrefix);
   for (const auto &Opt : Opts.CheckOptions) {
ClangTidyASTConsumerFactory::createASTConsumer(
 
   auto WorkingDir = Compiler.getSourceManager()
                         .getFileManager()
                         .getVirtualFileSystem()
                         .getCurrentWorkingDirectory();
   if (WorkingDir)
     Context.setCurrentBuildDirectory(WorkingDir.get());
 
-  std::vector<std::unique_ptr<ClangTidyCheck>> Checks =
-      CheckFactories->createChecks(&Context);
+  CheckVec Checks = instantiateChecks(Context, *CheckFactories);
 
   llvm::erase_if(Checks, [&](std::unique_ptr<ClangTidyCheck> &Check) {
     return !Check->isLanguageVersionSupported(Context.getLangOpts());
   });
 
   ast_matchers::MatchFinder::MatchFinderOptions FinderOptions;
 
   std::unique_ptr<ClangTidyProfiling> Profiling;
std::unique_ptr<ento::AnalysisASTConsumer> AnalysisConsumer =
         ento::CreateAnalysisConsumer(Compiler);
     AnalysisConsumer->AddDiagnosticConsumer(
         new AnalyzerDiagnosticConsumer(Context));
     Consumers.push_back(std::move(AnalysisConsumer));
   }
 #endif // CLANG_TIDY_ENABLE_STATIC_ANALYZER
   return std::make_unique<ClangTidyASTConsumer>(
       std::move(Consumers), std::move(Profiling), std::move(Finder),
-      std::move(Checks));
+      std::move(Checks), Context.getGlobalOptions().MultipassPhase);
 }
 
 std::vector<std::string> ClangTidyASTConsumerFactory::getCheckNames() {
   std::vector<std::string> CheckNames;
   for (const auto &CheckFactory : *CheckFactories) {
     if (Context.isCheckEnabled(CheckFactory.getKey()))
       CheckNames.emplace_back(CheckFactory.getKey());
   }
 
 #if CLANG_TIDY_ENABLE_STATIC_ANALYZER
   for (const auto &AnalyzerCheck : getAnalyzerCheckersAndPackages(
            Context, Context.canEnableAnalyzerAlphaCheckers()))
     CheckNames.push_back(AnalyzerCheckNamePrefix + AnalyzerCheck.first);
 #endif // CLANG_TIDY_ENABLE_STATIC_ANALYZER
 
   llvm::sort(CheckNames);
   return CheckNames;
 }
 
 ClangTidyOptions::OptionMap ClangTidyASTConsumerFactory::getCheckOptions() {
   ClangTidyOptions::OptionMap Options;
-  std::vector<std::unique_ptr<ClangTidyCheck>> Checks =
-      CheckFactories->createChecks(&Context);
+  CheckVec Checks = instantiateChecks(Context, *CheckFactories);
   for (const auto &Check : Checks)
     Check->storeOptions(Options);
   return Options;
 }
 
 std::vector<std::string>
 getCheckNames(const ClangTidyOptions &Options,
               bool AllowEnablingAnalyzerAlphaCheckers) {
getCheckOptions(const ClangTidyOptions &Options,
   clang::tidy::ClangTidyContext Context(
       std::make_unique<DefaultOptionsProvider>(ClangTidyGlobalOptions(),
                                                 Options),
       AllowEnablingAnalyzerAlphaCheckers);
   ClangTidyASTConsumerFactory Factory(Context);
   return Factory.getCheckOptions();
 }
 
+void runClangTidyCompactPhase(clang::tidy::ClangTidyContext &Context) {
+  std::unique_ptr<ClangTidyCheckFactories> CheckFactories(
+      new ClangTidyCheckFactories());
+  instantiateTidyModules(*CheckFactories);
+  CheckVec Checks = instantiateChecks(Context, *CheckFactories);
+  for (auto &Check : Checks)
+    Check->runCompact();
+}
+
 std::vector<ClangTidyError>
 runClangTidy(clang::tidy::ClangTidyContext &Context,
              const CompilationDatabase &Compilations,
              ArrayRef<std::string> InputFiles,
              llvm::IntrusiveRefCntPtr<llvm::vfs::OverlayFileSystem> BaseFS,
              bool ApplyAnyFix, bool EnableCheckProfile,
              llvm::StringRef StoreCheckProfile) {
   ClangTool Tool(Compilations, InputFiles,

clang-tools-extra/clang-tidy/ClangTidyCheck.h

public:
   /// store these as members of the derived class. However, note that all
   /// matches occur in the order of the AST traversal.
   virtual void registerMatchers(ast_matchers::MatchFinder *Finder) {}
 
   /// ``ClangTidyChecks`` that register ASTMatchers should do the actual
   /// work in here.
   virtual void check(const ast_matchers::MatchFinder::MatchResult &Result) {}
 
+  /// ``ClangTidyChecks`` that register ASTMatchers should do the actual work
+  /// for registering per-TU data to the project-level collection in here.
+  virtual void collect(const ast_matchers::MatchFinder::MatchResult &Result) {}
+
+  /// Checks that performed ``collect`` should write their data to the output to
+  /// the file in here.
+  virtual void postCollect(StringRef OutFile) {}
+
+  /// Execute the ``postCollect()`` function to the right, automatically
+  /// generated filename.
+  void runPostCollect();
+
+  /// In the ``compact`` phase, checks that are supporting such should reduce
+  /// the data received from all the TUs into a single file.
+  virtual void compact(const std::vector<std::string> &PerTUCollectedDataFiles,
+                       StringRef OutFile) {}
+
+  /// Gather the list of per-TU files from the context, and execute ``compact``.
+  void runCompact();
+
   /// Add a diagnostic with the check's name.
   DiagnosticBuilder diag(SourceLocation Loc, StringRef Description,
                          DiagnosticIDs::Level Level = DiagnosticIDs::Warning);
 
   /// Add a diagnostic with the check's name.
   DiagnosticBuilder diag(StringRef Description,
                          DiagnosticIDs::Level Level = DiagnosticIDs::Warning);
 
protected:
   StringRef getCurrentMainFile() const { return Context->getCurrentFile(); }
   /// Returns the language options from the context.
   const LangOptions &getLangOpts() const { return Context->getLangOpts(); }
   /// Returns true when the check is run in a use case when only 1 fix will be
   /// applied at a time.
   bool areDiagsSelfContained() const {
     return Context->areDiagsSelfContained();
   }
+  /// Returns the path where the current check should write collected data to.
+  std::string getCollectPath();
+  /// Returns the file where the current check should write or read compacted
+  /// data to/from.
+  StringRef getCompactedDataPath() const {
+    return Context->getCompactedDataPath(CheckName);
+  }
+  /// Returns the current phase of execution in a multi-pass project-level
+  /// system.
+  MultipassProjectPhase getPhase() const {
+    return Context->getGlobalOptions().MultipassPhase;
+  }
 };
 
 /// Read a named option from the ``Context`` and parse it as a bool.
 ///
 /// Reads the option with the check-local name \p LocalName from the
 /// ``CheckOptions``. If the corresponding key is not present, return
 /// ``None``.
 ///

clang-tools-extra/clang-tidy/ClangTidyCheck.cpp

ClangTidyCheck::configurationDiag(StringRef Description,
                                   DiagnosticIDs::Level Level) const {
   return Context->configurationDiag(Description, Level);
 }
 
 void ClangTidyCheck::run(const ast_matchers::MatchFinder::MatchResult &Result) {
   // For historical reasons, checks don't implement the MatchFinder run()
   // callback directly. We keep the run()/check() distinction to avoid interface
   // churn, and to allow us to add cross-cutting logic in the future.
+
+  switch (getPhase()) {
+  case MultipassProjectPhase::Diagnose:
     check(Result);
+    break;
+  case MultipassProjectPhase::Collect:
+    collect(Result);
+    break;
+  case MultipassProjectPhase::Compact:
+    llvm_unreachable("AST Matchers should not have run in compact mode.");
+  }
+}
+
+void ClangTidyCheck::runCompact() {
+  using namespace llvm::sys::fs;
+  using namespace llvm::sys::path;
+
+  std::vector<std::string> Inputs;
+  StringRef OutputPath = getCompactedDataPath();
+  StringRef OutputFilename = filename(OutputPath);
+
+  std::error_code EC;
+  for (auto It = directory_iterator(
+           Context->getGlobalOptions().MultipassDirectory, EC);
+       It != directory_iterator(); It.increment(EC)) {
+    if (EC)
+      continue;
+
+    StringRef Filename = filename(It->path());
+    if (Filename.startswith(this->CheckName) && Filename != OutputFilename)
+      Inputs.push_back(It->path());
+  }
+
+  compact(Inputs, OutputPath);
+}
+
+void ClangTidyCheck::runPostCollect() {
+  // FIXME: Hash does not respect multiple compilations of the same file with
+  // different compile flags.
+  assert(getPhase() == MultipassProjectPhase::Collect &&
+         "postCollect() in wrong phase.");
+  postCollect(getCollectPath());
+}
+
+std::string ClangTidyCheck::getCollectPath() {
+  using namespace llvm::sys::path;
+  assert(getPhase() == MultipassProjectPhase::Collect &&
+         "getCollectPath() in wrong phase.");
+
+  SmallString<256> Filename;
+  llvm::raw_svector_ostream OS{Filename};
+  StringRef CurrentFile = Context->getCurrentFile();
+  OS << Context->getGlobalOptions().MultipassDirectory << get_separator()
+     << CheckName << '.' << filename(CurrentFile) << '.'
+     << hash_value(CurrentFile) << ".yaml";
+
+  return Filename.str().str();
 }
 
 ClangTidyCheck::OptionsView::OptionsView(
     StringRef CheckName, const ClangTidyOptions::OptionMap &CheckOptions,
     ClangTidyContext *Context)
     : NamePrefix(CheckName.str() + "."), CheckOptions(CheckOptions),
       Context(Context) {}
 

clang-tools-extra/clang-tidy/ClangTidyDiagnosticConsumer.h

DiagLevelAndFormatString getDiagLevelAndFormatString(unsigned DiagnosticID,
                                                        SourceLocation Loc) {
     return DiagLevelAndFormatString(
         static_cast<DiagnosticIDs::Level>(
             DiagEngine->getDiagnosticLevel(DiagnosticID, Loc)),
         std::string(
             DiagEngine->getDiagnosticIDs()->getDescription(DiagnosticID)));
   }
 
+  /// Returns the file where a check should write or read compacted data
+  /// to/from.
+  StringRef getCompactedDataPath(StringRef CheckName);
+
 private:
   // Writes to Stats.
   friend class ClangTidyDiagnosticConsumer;
 
   DiagnosticsEngine *DiagEngine;
   std::unique_ptr<ClangTidyOptionsProvider> OptionsProvider;
 
   std::string CurrentFile;
private:
   bool Profile;
   std::string ProfilePrefix;
 
   bool AllowEnablingAnalyzerAlphaCheckers;
 
   bool SelfContainedDiags;
 
   NoLintDirectiveHandler NoLintHandler;
+
+  llvm::DenseMap<StringRef, std::string> CompactedDataPaths;
 };
 
 /// Gets the Fix attached to \p Diagnostic.
 /// If there isn't a Fix attached to the diagnostic and \p AnyFix is true, Check
 /// to see if exactly one note has a Fix and return it. Otherwise return
 /// nullptr.
 const llvm::StringMap<tooling::Replacements> *
 getFixIt(const tooling::Diagnostic &Diagnostic, bool AnyFix);

clang-tools-extra/clang-tidy/ClangTidyDiagnosticConsumer.cpp

WarningAsErrorFilter =
       std::make_unique<CachedGlobList>(*getOptions().WarningsAsErrors);
 }
 
 void ClangTidyContext::setASTContext(ASTContext *Context) {
   DiagEngine->SetArgToStringFn(&FormatASTNodeDiagnosticArgument, Context);
   LangOpts = Context->getLangOpts();
 }
 
+StringRef ClangTidyContext::getCompactedDataPath(StringRef CheckName) {
+  using namespace llvm::sys::fs;
+  using namespace llvm::sys::path;
+
+  MultipassProjectPhase Phase = getGlobalOptions().MultipassPhase;
+  if (Phase == MultipassProjectPhase::Collect)
+    llvm_unreachable("Invalid phase 'Collect' for accessing compacted data");
+
+  auto InsertResult = CompactedDataPaths.try_emplace(CheckName, "");
+  std::string &FilePath = InsertResult.first->second;
+  if (!InsertResult.second)
+    return FilePath;
+
+  SmallString<128> OutputFile;
+  llvm::raw_svector_ostream OS{OutputFile};
+  OS << getGlobalOptions().MultipassDirectory << get_separator() << CheckName
+     << ".yaml";
+
+  if (Phase == MultipassProjectPhase::Compact)
+    // The file will be written, and thus, created.
+    FilePath = OutputFile.str().str();
+  else if (Phase == MultipassProjectPhase::Diagnose)
+    if (llvm::sys::fs::exists(OutputFile))
+      // If the file doesn't exist, leave it as empty string.
+      FilePath = OutputFile.str().str();
+
+  return FilePath;
+}
+
 const ClangTidyGlobalOptions &ClangTidyContext::getGlobalOptions() const {
   return OptionsProvider->getGlobalOptions();
 }
 
 const ClangTidyOptions &ClangTidyContext::getOptions() const {
   return CurrentOptions;
 }
 

clang-tools-extra/clang-tidy/ClangTidyOptions.h

 #include <string>
 #include <system_error>
 #include <utility>
 #include <vector>
 
 namespace clang {
 namespace tidy {
 
+/// When executing multi-pass project-level analysis, identifies the phase the
+/// current process is configured for.
+enum class MultipassProjectPhase {
+  /// In the collection phase, checks capable for project-level analysis emit
+  /// analysis data.
+  Collect,
+  /// Create a full project-level data file that diagnosis can use.
+  Compact,
+  /// Emit diagnostics from the checks. (This is the default value in
+  /// single-phase mode.)
+  Diagnose
+};
+
 /// Contains a list of line ranges in a single file.
 struct FileFilter {
   /// File name.
   std::string Name;
 
   /// LineRange is a pair<start, end> (inclusive).
   typedef std::pair<unsigned, unsigned> LineRange;
 
   /// A list of line ranges in this file, for which we show warnings.
   std::vector<LineRange> LineRanges;
 };
 
 /// Global options. These options are neither stored nor read from
 /// configuration files.
 struct ClangTidyGlobalOptions {
   /// Output warnings from certain line ranges of certain files only.
   /// If empty, no warnings will be filtered.
   std::vector<FileFilter> LineFilter;
+
+  MultipassProjectPhase MultipassPhase;
+  /// The directory where multi-pass project-level analysis stores its data to.
+  std::string MultipassDirectory;
 };
 
 /// Contains options for clang-tidy. These options may be read from
 /// configuration files, and may be different for different translation units.
 struct ClangTidyOptions {
   /// These options are used for all settings that haven't been
   /// overridden by the \c OptionsProvider.
   ///

clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp

 Apply suggested fixes even if compilation
 errors were found. If compiler errors have
 attached fix-its, clang-tidy will apply them as
 well.
 )"),
                                cl::init(false), cl::cat(ClangTidyCategory));
 
 static cl::opt<bool> FixNotes("fix-notes", cl::desc(R"(
-If a warning has no fix, but a single fix can 
-be found through an associated diagnostic note, 
-apply the fix. 
-Specifying this flag will implicitly enable the 
+If a warning has no fix, but a single fix can
+be found through an associated diagnostic note,
+apply the fix.
+Specifying this flag will implicitly enable the
 '--fix' flag.
 )"),
                               cl::init(false), cl::cat(ClangTidyCategory));
 
 static cl::opt<std::string> FormatStyle("format-style", cl::desc(R"(
 Style for formatting code around applied fixes:
   - 'none' (default) turns off formatting
   - 'file' (literally 'file', not a placeholder)

 Use colors in diagnostics. If not set, colors
 will be used if the terminal connected to
 standard output supports colors.
 This option overrides the 'UseColor' option in
 .clang-tidy file, if any.
 )"),
                               cl::init(false), cl::cat(ClangTidyCategory));
 
+static cl::opt<clang::tidy::MultipassProjectPhase> MultipassPhase(
+    "multipass-phase", cl::desc(R"(
+When executing project-level analysis, specify
+which phase of the analysis to run. Multi-pass
+project-level analysis requires the execution
+of 3 passes in sequence. Not all checks support
+this feature.
+)"),
+    cl::values(
+        clEnumValN(clang::tidy::MultipassProjectPhase::Collect, "collect", R"(
+Collect per-TU analysis data from checks that are
+capable of multi-pass analysis.
+This pass can be executed in parallel.
+)"),
+        clEnumValN(clang::tidy::MultipassProjectPhase::Compact, "compact", R"(
+Transform the per-TU data into a single project-level
+data to be consumed for diagnostics.
+This pass CAN NOT be executed in parallel!
+)"),
+        clEnumValN(clang::tidy::MultipassProjectPhase::Diagnose, "diagnose", R"(
+Emit diagnostics of the code, using the previously
+collected and compacted data, or with per-TU data
+only for single-pass analysis analysis.
+This pass can be executed in parallel.
+)")),
+    cl::init(clang::tidy::MultipassProjectPhase::Diagnose),
+    cl::cat(ClangTidyCategory));
+
+static cl::opt<std::string> MultipassDirectory("multipass-dir", cl::desc(R"(
+When executing project-level analysis, specify
+a directory where data can be stored inbetween
+phases.
+)"),
+                                               cl::cat(ClangTidyCategory));
+
 namespace clang {
 namespace tidy {
 
+static SmallString<256> makeAbsolute(const std::string &Input) {
+  if (Input.empty())
+    return {};
+  SmallString<256> AbsolutePath(Input);
+  if (std::error_code EC = llvm::sys::fs::make_absolute(AbsolutePath)) {
+    llvm::errs() << "Can't make absolute path from " << Input << ": "
+                 << EC.message() << "\n";
+  }
+  return AbsolutePath;
+}
+
 static void printStats(const ClangTidyStats &Stats) {
   if (Stats.errorsIgnored()) {
     llvm::errs() << "Suppressed " << Stats.errorsIgnored() << " warnings (";
     StringRef Separator = "";
     if (Stats.ErrorsIgnoredNonUserCode) {
       llvm::errs() << Stats.ErrorsIgnoredNonUserCode << " in non-user code";
       Separator = ", ";
     }
static std::unique_ptr<ClangTidyOptionsProvider> createOptionsProvider(
    llvm::IntrusiveRefCntPtr<vfs::FileSystem> FS) {
   ClangTidyGlobalOptions GlobalOptions;
   if (std::error_code Err = parseLineFilter(LineFilter, GlobalOptions)) {
     llvm::errs() << "Invalid LineFilter: " << Err.message() << "\n\nUsage:\n";
     llvm::cl::PrintHelpMessage(/*Hidden=*/false, /*Categorized=*/true);
     return nullptr;
   }
 
+  GlobalOptions.MultipassPhase = MultipassPhase;
+
+  SmallString<256> MultipassDirAbsolute = makeAbsolute(MultipassDirectory);
+  GlobalOptions.MultipassDirectory =
+      makeAbsolute(MultipassDirectory).str().str();
+
   ClangTidyOptions DefaultOptions;
   DefaultOptions.Checks = DefaultChecks;
   DefaultOptions.WarningsAsErrors = "";
   DefaultOptions.HeaderFilterRegex = HeaderFilter;
   DefaultOptions.SystemHeaders = SystemHeaders;
   DefaultOptions.FormatStyle = FormatStyle;
   DefaultOptions.User = llvm::sys::Process::GetEnv("USER");
   // USERNAME is used on Windows.
if (!VfsOverlay.empty()) {
     BaseFS->pushOverlay(std::move(VfsFromFile));
   }
 
   auto OwningOptionsProvider = createOptionsProvider(BaseFS);
   auto *OptionsProvider = OwningOptionsProvider.get();
   if (!OptionsProvider)
     return 1;
 
-  auto MakeAbsolute = [](const std::string &Input) -> SmallString<256> {
-    if (Input.empty())
-      return {};
-    SmallString<256> AbsolutePath(Input);
-    if (std::error_code EC = llvm::sys::fs::make_absolute(AbsolutePath)) {
-      llvm::errs() << "Can't make absolute path from " << Input << ": "
-                   << EC.message() << "\n";
-    }
-    return AbsolutePath;
-  };
-
-  SmallString<256> ProfilePrefix = MakeAbsolute(StoreCheckProfile);
+  SmallString<256> ProfilePrefix = makeAbsolute(StoreCheckProfile);
 
   StringRef FileName("dummy");
   auto PathList = OptionsParser->getSourcePathList();
   if (!PathList.empty()) {
     FileName = PathList.front();
   }
 
-  SmallString<256> FilePath = MakeAbsolute(std::string(FileName));
+  SmallString<256> FilePath = makeAbsolute(std::string(FileName));
 
   ClangTidyOptions EffectiveOptions = OptionsProvider->getOptions(FilePath);
   std::vector<std::string> EnabledChecks =
       getCheckNames(EffectiveOptions, AllowEnablingAnalyzerAlphaCheckers);
 
   if (ExplainConfig) {
     // FIXME: Show other ClangTidyOptions' fields, like ExtraArg.
     std::vector<clang::tidy::ClangTidyOptionsProvider::OptionsSource>
int clangTidyMain(int argc, const char **argv) {
   }
 
   if (EnabledChecks.empty()) {
     llvm::errs() << "Error: no checks enabled.\n";
     llvm::cl::PrintHelpMessage(/*Hidden=*/false, /*Categorized=*/true);
     return 1;
   }
 
+  MultipassProjectPhase Phase =
+      OptionsProvider->getGlobalOptions().MultipassPhase;
+  if (Phase == MultipassProjectPhase::Compact) {
+    ClangTidyContext Context(std::move(OwningOptionsProvider),
+                             AllowEnablingAnalyzerAlphaCheckers);
+    runClangTidyCompactPhase(Context);
+    return 0;
+  }
+
   if (PathList.empty()) {
     llvm::errs() << "Error: no input files specified.\n";
     llvm::cl::PrintHelpMessage(/*Hidden=*/false, /*Categorized=*/true);
     return 1;
   }
 
+  const std::string &MultipassDir =
+      OptionsProvider->getGlobalOptions().MultipassDirectory;
+  if (Phase == MultipassProjectPhase::Collect ||
+      Phase == MultipassProjectPhase::Compact) {
+    if (MultipassDir.empty()) {
+      llvm::errs() << "Error: --multipass-phase 'collect' or 'compact' given, "
+                      "but no '--multipass-dir' set.\n";
+      return 1;
+    }
+    if (!llvm::sys::fs::is_directory(MultipassDir))
+      llvm::sys::fs::create_directory(MultipassDir);
+  }
+
   llvm::InitializeAllTargetInfos();
   llvm::InitializeAllTargetMCs();
   llvm::InitializeAllAsmParsers();
 
   ClangTidyContext Context(std::move(OwningOptionsProvider),
                            AllowEnablingAnalyzerAlphaCheckers);
   std::vector<ClangTidyError> Errors =
       runClangTidy(Context, OptionsParser->getCompilations(), PathList, BaseFS,

clang-tools-extra/docs/ReleaseNotes.rst

- Added trace code to help narrow down any checks and the relevant source code
   that result in crashes.
 
 - Clang-tidy now consideres newlines as separators of single elements in the `Checks` section in
   `.clang-tidy` configuration files. Where previously a comma had to be used to distinguish elements in
   this list from each other, newline characters now also work as separators in the parsed YAML. That
   means it is advised to use YAML's block style initiated by the pipe character `|` for the `Checks`
   section in order to benefit from the easier syntax that works without commas.
 
+- Added the infrastructure support for checks to be executed in multiple phases
+  to facilitate analysis with project-level information. Such analysis is not
+  the default, and not all checks support it.
+
 New checks
 ^^^^^^^^^^
 
 - New :doc:`bugprone-shared-ptr-array-mismatch <clang-tidy/checks/bugprone-shared-ptr-array-mismatch>` check.
 
   Finds initializations of C++ shared pointers to non-array type that are initialized with an array.
 
 - New :doc:`modernize-macro-to-enum

clang-tools-extra/docs/clang-tidy/index.rst

-load=<plugin>                 -
                                      Load the dynamic object ``plugin``. This
                                      object should register new static analyzer
                                      or clang-tidy passes. Once loaded, the
                                      object will add new command line options
                                      to run various analyses. To see the new
                                      complete list of passes, use the
                                      :option:`--list-checks` and
                                      :option:`-load` options together.
+  --multipass-dir=<string>       -
+                                   When executing project-level analysis, specify
+                                   a directory where data can be stored inbetween
+                                   phases.
+  --multipass-phase=<value>      -
+                                   When executing project-level analysis, specify
+                                   which phase of the analysis to run. Multi-pass
+                                   project-level analysis requires the execution
+                                   of 3 passes in sequence. Not all checks support
+                                   this feature.
+    =collect                     -
+                                     Collect per-TU analysis data from checks that are
+                                     capable of multi-pass analysis.
+
+                                     This pass can be executed in parallel.
+    =compact                     -
+                                     Transform the per-TU data into a single project-level
+                                     data to be consumed for diagnostics.
+
+                                     This pass CAN NOT be executed in parallel!
+    =diagnose                    -
+                                     Emit diagnostics of the code, using the previously
+                                     collected and compacted data, or with per-TU data
+                                     only for single-pass analysis analysis.
+
+                                     This pass can be executed in parallel.
     -p=<string>                    - Build path
     --quiet                        -
                                      Run clang-tidy in quiet mode. This suppresses
                                      printing statistics about ignored warnings and
                                      warnings treated as errors if the respective
                                      options are specified.
     --store-check-profile=<prefix> -
                                      By default reports are printed in tabulated

 
 All ``NOLINTBEGIN`` comments must be paired by an equal number of ``NOLINTEND``
 comments. Moreover, a pair of comments must have matching arguments -- for
 example, ``NOLINTBEGIN(check-name)`` can be paired with
 ``NOLINTEND(check-name)`` but not with ``NOLINTEND`` `(zero arguments)`.
 :program:`clang-tidy` will generate a ``clang-tidy-nolint`` error diagnostic if
 any ``NOLINTBEGIN``/``NOLINTEND`` comment violates these requirements.
 
+Project-level analysis
+======================
+
+By default, Clang-Tidy runs checks on every translation unit of the project
+separately.
+Some checks, however, might benefit from and give better or more meaningful
+results, or only work, when executed not for a single file, but for the entire
+project.
+The **multi-pass** analysis can be used in this case, with which checks can first
+`collect` information into a temporary data location (``--multipass-dir``) on the
+disk, `compact` per-TU data into project-level data, and `diagnose` with the
+project-level data in mind.
+The phase is selected by passing the appropriate value to the
+``--multipass-phase`` command-line parameter.
+
+Whether a check supports project-level analysis, and how project-level data is
+stored and transformed from per-TU to "global" values is specific to each
+individual check.
+
+.. code-block:: bash
+    $ clang-tidy --checks=... file1.cpp file2.cpp
+
+    $ clang-tidy --checks=... --multipass-phase=collect --multipass-dir="TidyData" file1.cpp file2.cpp
+    # No output to the terminal.
+    $ ls ./TidyData
+    blah.file1.cpp.01234567.yaml
+    blah.file2.cpp.89abcdef.yaml
+
+    $ clang-tidy --checks=... --multipass-phase=compact --multipass-dir="TidyData"
+    # No file list required to be specified.
+    # No output to the terminal.
+    $ ls ./TidyData
+    blah.file1.cpp.01234567.yaml
+    blah.file2.cpp.89abcdef.yaml
+    blah.yaml
+
+    $ clang-tidy --checks=... --multipass-phase=compact --multipass-dir="TidyData" file1.cpp file2.cpp
+    # Diagnostics that use project-level data.
+
 .. _LibTooling: https://clang.llvm.org/docs/LibTooling.html
 .. _How To Setup Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html