[clang-tidy] Add misc-header-include-cycle check

[PiotrZSL]

Summary

Check detects cyclic #include dependencies between user-defined headers.

[PiotrZSL]

Typo fix.

[PiotrZSL]

Fixes

[PiotrZSL]

Findings on llvm:

clang-tools-extra/unittests/clang-doc/ClangDocTest.h:12:10: warning: direct self-inclusion of header file 'ClangDocTest.h' [misc-header-include-cycle]
libc/src/__support/FPUtil/x86_64/LongDoubleBits.h:21:10: warning: circular header file dependency detected while including 'FPBits.h', please check the include path: 'FPBits.h' -> 'LongDoubleBits.h' -> 'FPBits.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBAddress.h:13:10: warning: circular header file dependency detected while including 'SBModule.h', please check the include path: 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBBlock.h' -> 'SBTarget.h' -> 'SBAddress.h' -> 'SBModule.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBBlock.h:14:10: warning: circular header file dependency detected while including 'SBTarget.h', please check the include path: 'SBTarget.h' -> 'SBAddress.h' -> 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBBlock.h' -> 'SBTarget.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBFunction.h:12:10: warning: circular header file dependency detected while including 'SBAddress.h', please check the include path: 'SBAddress.h' -> 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBFunction.h' -> 'SBAddress.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBLineEntry.h:12:10: warning: circular header file dependency detected while including 'SBAddress.h', please check the include path: 'SBAddress.h' -> 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBLineEntry.h' -> 'SBAddress.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBModule.h:15:10: warning: circular header file dependency detected while including 'SBSymbolContext.h', please check the include path: 'SBSymbolContext.h' -> 'SBBlock.h' -> 'SBTarget.h' -> 'SBAddress.h' -> 'SBModule.h' -> 'SBSymbolContext.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBSymbol.h:12:10: warning: circular header file dependency detected while including 'SBAddress.h', please check the include path: 'SBAddress.h' -> 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBSymbol.h' -> 'SBAddress.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBSymbol.h:15:10: warning: circular header file dependency detected while including 'SBTarget.h', please check the include path: 'SBTarget.h' -> 'SBAddress.h' -> 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBSymbol.h' -> 'SBTarget.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBSymbolContext.h:12:10: warning: circular header file dependency detected while including 'SBBlock.h', please check the include path: 'SBBlock.h' -> 'SBTarget.h' -> 'SBAddress.h' -> 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBBlock.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBSymbolContext.h:15:10: warning: circular header file dependency detected while including 'SBFunction.h', please check the include path: 'SBFunction.h' -> 'SBAddress.h' -> 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBFunction.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBSymbolContext.h:16:10: warning: circular header file dependency detected while including 'SBLineEntry.h', please check the include path: 'SBLineEntry.h' -> 'SBAddress.h' -> 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBLineEntry.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBSymbolContext.h:17:10: warning: circular header file dependency detected while including 'SBModule.h', please check the include path: 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBModule.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBSymbolContext.h:18:10: warning: circular header file dependency detected while including 'SBSymbol.h', please check the include path: 'SBSymbol.h' -> 'SBAddress.h' -> 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBSymbol.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBSymbolContextList.h:13:10: warning: circular header file dependency detected while including 'SBSymbolContext.h', please check the include path: 'SBSymbolContext.h' -> 'SBBlock.h' -> 'SBTarget.h' -> 'SBSymbolContextList.h' -> 'SBSymbolContext.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBTarget.h:12:10: warning: circular header file dependency detected while including 'SBAddress.h', please check the include path: 'SBAddress.h' -> 'SBModule.h' -> 'SBSymbolContext.h' -> 'SBBlock.h' -> 'SBTarget.h' -> 'SBAddress.h' [misc-header-include-cycle]
lldb/include/lldb/API/SBTarget.h:20:10: warning: circular header file dependency detected while including 'SBSymbolContextList.h', please check the include path: 'SBSymbolContextList.h' -> 'SBSymbolContext.h' -> 'SBBlock.h' -> 'SBTarget.h' -> 'SBSymbolContextList.h' [misc-header-include-cycle]
lldb/include/lldb/lldb-private-types.h:14:10: warning: circular header file dependency detected while including 'lldb-private.h', please check the include path: 'lldb-private.h' -> 'lldb-private-types.h' -> 'lldb-private.h' [misc-header-include-cycle]
lldb/include/lldb/lldb-private.h:16:10: warning: circular header file dependency detected while including 'lldb-private-types.h', please check the include path: 'lldb-private-types.h' -> 'lldb-private.h' -> 'lldb-private-types.h' [misc-header-include-cycle]
lldb/source/Plugins/Process/scripted/ScriptedProcess.h:17:10: warning: circular header file dependency detected while including 'ScriptedThread.h', please check the include path: 'ScriptedThread.h' -> 'ScriptedProcess.h' -> 'ScriptedThread.h' [misc-header-include-cycle]
lldb/source/Plugins/Process/scripted/ScriptedThread.h:14:10: warning: circular header file dependency detected while including 'ScriptedProcess.h', please check the include path: 'ScriptedProcess.h' -> 'ScriptedThread.h' -> 'ScriptedProcess.h' [misc-header-include-cycle]
third-party/unittest/googletest/include/gtest/gtest_pred_impl.h:43:10: warning: circular header file dependency detected while including 'gtest.h', please check the include path: 'gtest.h' -> 'gtest_pred_impl.h' -> 'gtest.h' [misc-header-include-cycle]

[PiotrZSL]

Ready for review

[njames93]

This is a great check that I've been meaning to work on for ages but never had time.
It mostly looks good but there are a few issues
I feel there is another issue that this can be very spammy with diagnostics(though clang-tidy is likely suppressing the duplicated ones).
But maybe when we emit a warning for a specified include, we could put it in a set to not warn on that include again

clang-tools-extra/clang-tidy/misc/HeaderIncludeCycleCheck.cpp

107–111

How does this handle this case where an include includes a file that self includes itself.

// Foo.hpp
#pragma once
#include "Foo.hpp"

// Bar.hpp
#pragma once
#include Foo.hpp

// Main.cpp
#include "Bar.hpp"

Where will the warning be emitted, it should appear in Foo.hpp but the logic here says it won't and would just be reported as a circular dependency below.
Can you make sure the warning is emitted in Foo.hpp and add test cases that test for this, The current tests just check include a file that self references itself with no intermediate files.

113–123

Rather than just printing out the include path, can you emit each include location as a note.
OtherInclude.h:5:1: note: 'ThisInclude.h' included here
You can pass DiagnosticLevel::Note as the 3rd parameter to Check::diag to emit a note. Just have to make sure you emit the note after you emit the warning.

Notes have better support for front end diagnostics parsing.

135

1024 entries is pushing the boat out for a small vector.

clang-tools-extra/docs/clang-tidy/checks/misc/header-include-cycle.rst

64

This tag line is just unnecessary

[PiotrZSL]

clang-tools-extra/clang-tidy/misc/HeaderIncludeCycleCheck.cpp

107–111

in theory it should raise an issue for self-include here..
and issue should be raised in Foo.hpp, can add check for this...

113–123

yes I wanted to do that, but at the point of FileChanged, where I fill up stack, i don't have an proper info where such file wre included.
It's possible, would need just to somehow connect info from InclusionDirective, assuming that when we got include, we go in such file, then probably keeping last processed include should be sufficient...

135

Thats just 4KB of memory pre-allocated to avoid re-allocations. Small is "muten" here.

clang-tools-extra/docs/clang-tidy/checks/misc/header-include-cycle.rst

64

maybe it is unnecessary, but I just wanted to put some advertisement slogan for a check ...
Doesn't need to be bold... But it's is catchy...

[PiotrZSL]

"But maybe when we emit a warning for a specified include, we could put it in a set to not warn on that include again"
I don't think so, in such case we hide include paths, and most of the time header guards should help here in reduction of cyclic dependences.

[PiotrZSL]

Added support for --include
Added support for self-include of source file
Added more tests
Reworked include stack.

[PiotrZSL]

TODO: Add option: ExcludeHeadersRegexp

[PiotrZSL]

Option need to be added

[PiotrZSL]

Ready for review, added new check option.

[PiotrZSL]

Rebase due to failed clangd tests on windows

[PiotrZSL]

Rebase due to broken baseline

[PiotrZSL]

Ping + Rebase

[njames93]

clang-tools-extra/clang-tidy/misc/HeaderIncludeCycleCheck.cpp

135–136

Is this a case that can ever come up?
If it does come up, surely any notes emitted after that would be garbage, in which case wouldn't it make more sense to break rather than continue?

147

Again whats the rationale for using continue over break here?

149–151

Is this a case that is expected to come up, if so can there be a test added.
Likewise if we do have a file that was included from the command line, surely we should break after emitting that diagnostic, It's not like the command line can be included from another file.

155–162

Dont reinvent the wheel - llvm::sys::path::filename does the same thing

[PiotrZSL]

clang-tools-extra/clang-tidy/misc/HeaderIncludeCycleCheck.cpp

135–136

I will remove this...

147

Idea is to provide any information, even if it could be missing something.

149–151

I didn't found any case it could be, added this as an preclusion.

[PiotrZSL]

Small redesign (review comments)

[njames93]

LGTM: Just one small nit.

clang-tools-extra/clang-tidy/misc/HeaderIncludeCycleCheck.cpp

149–151

[PiotrZSL]

Fix one small nit.

[thakis]

This breaks tests: http://45.33.8.238/linux/104455/step_8.txt

Please take a look and revert for now if it takes a while to fix.

[PiotrZSL]

Small changes remove, file name

[PiotrZSL]

To be honest I have no idea why it failed, simply because there is CHECK-MESSAGES for that log. I will probably split this single test into few smaller tests.

[PiotrZSL]

TODO:
Split tests into multiple files (to isolate issue).
If possible remove usage of FileCheck.

[PiotrZSL]

Rebase

[PiotrZSL]

Reorder warnigns & copy .cpp file to Output

clang-tools-extra/clang-tidy/misc/CMakeLists.txt

add_custom_command(
     DEPENDS ${clang_tidy_confusable_chars_gen_target} ConfusableTable/confusables.txt)
 
 add_custom_target(genconfusable DEPENDS Confusables.inc)
 
 add_clang_library(clangTidyMiscModule
   ConstCorrectnessCheck.cpp
   DefinitionsInHeadersCheck.cpp
   ConfusableIdentifierCheck.cpp
+  HeaderIncludeCycleCheck.cpp
   MiscTidyModule.cpp
   MisleadingBidirectional.cpp
   MisleadingIdentifier.cpp
   MisplacedConstCheck.cpp
   NewDeleteOverloadsCheck.cpp
   NoRecursionCheck.cpp
   NonCopyableObjects.cpp
   NonPrivateMemberVariablesInClassesCheck.cpp

clang-tools-extra/clang-tidy/misc/HeaderIncludeCycleCheck.h

+//===--- HeaderIncludeCycleCheck.h - clang-tidy -----------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MISC_HEADERINCLUDECYCLECHECK_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MISC_HEADERINCLUDECYCLECHECK_H
+
+#include "../ClangTidyCheck.h"
+#include <vector>
+
+namespace clang::tidy::misc {
+
+/// Check detects cyclic #include dependencies between user-defined headers.
+///
+/// For the user-facing documentation see:
+/// http://clang.llvm.org/extra/clang-tidy/checks/misc/header-include-cycle.html
+class HeaderIncludeCycleCheck : public ClangTidyCheck {
+public:
+  HeaderIncludeCycleCheck(StringRef Name, ClangTidyContext *Context);
+  void registerPPCallbacks(const SourceManager &SM, Preprocessor *PP,
+                           Preprocessor *ModuleExpanderPP) override;
+  void storeOptions(ClangTidyOptions::OptionMap &Opts) override;
+
+private:
+  const std::vector<StringRef> IgnoredFilesList;
+};
+
+} // namespace clang::tidy::misc
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MISC_HEADERINCLUDECYCLECHECK_H

clang-tools-extra/clang-tidy/misc/HeaderIncludeCycleCheck.cpp

+//===--- HeaderIncludeCycleCheck.cpp - clang-tidy -------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "HeaderIncludeCycleCheck.h"
+#include "../utils/OptionsUtils.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+#include "clang/Lex/PPCallbacks.h"
+#include "clang/Lex/Preprocessor.h"
+#include "llvm/ADT/SmallVector.h"
+#include "llvm/Support/Regex.h"
+#include <algorithm>
+#include <deque>
+#include <optional>
+#include <string>
+
+using namespace clang::ast_matchers;
+
+namespace clang::tidy::misc {
+
+namespace {
+
+struct Include {
+  FileID Id;
+  llvm::StringRef Name;
+  SourceLocation Loc;
+};
+
+class CyclicDependencyCallbacks : public PPCallbacks {
+public:
+  CyclicDependencyCallbacks(HeaderIncludeCycleCheck &Check,
+                            const SourceManager &SM,
+                            const std::vector<StringRef> &IgnoredFilesList)
+      : Check(Check), SM(SM) {
+    IgnoredFilesRegexes.reserve(IgnoredFilesList.size());
+    for (const StringRef &It : IgnoredFilesList) {
+      if (!It.empty())
+        IgnoredFilesRegexes.emplace_back(It);
+    }
+  }
+
+  void FileChanged(SourceLocation Loc, FileChangeReason Reason,
+                   SrcMgr::CharacteristicKind FileType,
+                   FileID PrevFID) override {
+    if (FileType != clang::SrcMgr::C_User)
+      return;
+
+    if (Reason != EnterFile && Reason != ExitFile)
+      return;
+
+    FileID Id = SM.getFileID(Loc);
+    if (Id.isInvalid())
+      return;
+
+    if (Reason == ExitFile) {
+      if ((Files.size() > 1U) && (Files.back().Id == PrevFID) &&
+          (Files[Files.size() - 2U].Id == Id))
+        Files.pop_back();
+      return;
+    }
+
+    if (!Files.empty() && Files.back().Id == Id)
+      return;
+
+    std::optional<llvm::StringRef> FilePath = SM.getNonBuiltinFilenameForID(Id);
+    llvm::StringRef FileName =
+        FilePath ? getFileName(*FilePath) : llvm::StringRef();
+
+    if (!NextToEnter)
+      NextToEnter = Include{Id, FileName, SourceLocation()};
+
+    assert(NextToEnter->Name == FileName);
+    NextToEnter->Id = Id;
+    Files.emplace_back(*NextToEnter);
+    NextToEnter.reset();
+  }
+
+  void InclusionDirective(SourceLocation, const Token &, StringRef FilePath,
+                          bool, CharSourceRange Range,
+                          OptionalFileEntryRef File, StringRef, StringRef,
+                          const Module *,
+                          SrcMgr::CharacteristicKind FileType) override {
+    if (FileType != clang::SrcMgr::C_User)
+      return;
+
+    llvm::StringRef FileName = getFileName(FilePath);
+    NextToEnter = {FileID(), FileName, Range.getBegin()};
+
+    if (!File)
+      return;
+
+    FileID Id = SM.translateFile(*File);
+    if (Id.isInvalid())
+      return;
+
+    checkForDoubleInclude(Id, FileName, Range.getBegin());
+  }
+
+  void EndOfMainFile() override {
+    if (!Files.empty() && Files.back().Id == SM.getMainFileID())
+      Files.pop_back();
+
+    assert(Files.empty());
+  }
+
+  void checkForDoubleInclude(FileID Id, llvm::StringRef FileName,
+                             SourceLocation Loc) {
+    auto It =
+        std::find_if(Files.rbegin(), Files.rend(),
+                     [&](const Include &Entry) { return Entry.Id == Id; });
+    if (It == Files.rend())
+      return;
+
+    const std::optional<StringRef> FilePath = SM.getNonBuiltinFilenameForID(Id);
+    if (!FilePath || isFileIgnored(*FilePath))
+      return;
+
+    if (It == Files.rbegin()) {
+      Check.diag(Loc, "direct self-inclusion of header file '%0'") << FileName;
+      return;
+    }
+
+    Check.diag(Loc, "circular header file dependency detected while including "
+                    "'%0', please check the include path")
+        << FileName;
+
+    auto CurrentIt = Files.rbegin();
+    do {
+      if (CurrentIt->Name.empty())
+        continue;
+
+      if (CurrentIt->Loc.isValid()) {
+        Check.diag(CurrentIt->Loc, "'%0' included from here",
+                   DiagnosticIDs::Note)
+            << CurrentIt->Name;
+        continue;
+      }
+
+      SourceLocation Location = SM.getLocForStartOfFile(CurrentIt->Id);
+      if (Location.isInvalid())
+        continue;
+
+      Check.diag(Location, "'%0' included from command line",
+                 DiagnosticIDs::Note)
+          << CurrentIt->Name;
+    } while (CurrentIt++ != It);
+  }
+
+  static llvm::StringRef getFileName(llvm::StringRef FilePath) {
+    llvm::StringRef FileName = FilePath;
+    if (FileName.contains('/'))
+      FileName = FileName.rsplit('/').second;
+    if (FileName.contains('\\'))
+      FileName = FileName.rsplit('\\').second;
+    return FileName;
+  }
+
+  bool isFileIgnored(StringRef FileName) const {
+    return std::any_of(
+        IgnoredFilesRegexes.begin(), IgnoredFilesRegexes.end(),
+        [&](const llvm::Regex &It) { return It.match(FileName); });
+  }
+
+private:
+  std::deque<Include> Files;
+  std::optional<Include> NextToEnter;
+  HeaderIncludeCycleCheck &Check;
+  const SourceManager &SM;
+  std::vector<llvm::Regex> IgnoredFilesRegexes;
+};
+
+} // namespace
+
+HeaderIncludeCycleCheck::HeaderIncludeCycleCheck(StringRef Name,
+                                                 ClangTidyContext *Context)
+    : ClangTidyCheck(Name, Context),
+      IgnoredFilesList(utils::options::parseStringList(
+          Options.get("IgnoredFilesList", ""))) {}
+
+void HeaderIncludeCycleCheck::registerPPCallbacks(
+    const SourceManager &SM, Preprocessor *PP, Preprocessor *ModuleExpanderPP) {
+  PP->addPPCallbacks(
+      std::make_unique<CyclicDependencyCallbacks>(*this, SM, IgnoredFilesList));
+}
+
+void HeaderIncludeCycleCheck::storeOptions(ClangTidyOptions::OptionMap &Opts) {
+  Options.store(Opts, "IgnoredFilesList",
+                utils::options::serializeStringList(IgnoredFilesList));
+}
+
+} // namespace clang::tidy::misc

clang-tools-extra/clang-tidy/misc/MiscTidyModule.cpp

 //===--- MiscTidyModule.cpp - clang-tidy ----------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "../ClangTidy.h"
 #include "../ClangTidyModule.h"
 #include "../ClangTidyModuleRegistry.h"
 #include "ConfusableIdentifierCheck.h"
 #include "ConstCorrectnessCheck.h"
 #include "DefinitionsInHeadersCheck.h"
+#include "HeaderIncludeCycleCheck.h"
 #include "MisleadingBidirectional.h"
 #include "MisleadingIdentifier.h"
 #include "MisplacedConstCheck.h"
 #include "NewDeleteOverloadsCheck.h"
 #include "NoRecursionCheck.h"
 #include "NonCopyableObjects.h"
 #include "NonPrivateMemberVariablesInClassesCheck.h"
 #include "RedundantExpressionCheck.h"

 public:
   void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
     CheckFactories.registerCheck<ConfusableIdentifierCheck>(
         "misc-confusable-identifiers");
     CheckFactories.registerCheck<ConstCorrectnessCheck>(
         "misc-const-correctness");
     CheckFactories.registerCheck<DefinitionsInHeadersCheck>(
         "misc-definitions-in-headers");
+    CheckFactories.registerCheck<HeaderIncludeCycleCheck>(
+        "misc-header-include-cycle");
     CheckFactories.registerCheck<MisleadingBidirectionalCheck>(
         "misc-misleading-bidirectional");
     CheckFactories.registerCheck<MisleadingIdentifierCheck>(
         "misc-misleading-identifier");
     CheckFactories.registerCheck<MisplacedConstCheck>("misc-misplaced-const");
     CheckFactories.registerCheck<NewDeleteOverloadsCheck>(
         "misc-new-delete-overloads");
     CheckFactories.registerCheck<NoRecursionCheck>("misc-no-recursion");

clang-tools-extra/docs/ReleaseNotes.rst

- New :doc:`cppcoreguidelines-avoid-capture-default-when-capturing-this
   Warns when lambda specify a capture default and capture ``this``.
 
 - New :doc:`llvmlibc-inline-function-decl
   <clang-tidy/checks/llvmlibc/inline-function-decl>` check.
 
   Checks that all implicit and explicit inline functions in header files are
   tagged with the ``LIBC_INLINE`` macro.
 
+- New :doc:`misc-header-include-cycle
+  <clang-tidy/checks/misc/header-include-cycle>` check.
+
+  Check detects cyclic ``#include`` dependencies between user-defined headers.
+
 New check aliases
 ^^^^^^^^^^^^^^^^^
 
 - New alias :doc:`cert-msc24-c
   <clang-tidy/checks/cert/msc24-c>` to :doc:`bugprone-unsafe-functions
   <clang-tidy/checks/bugprone/unsafe-functions>` was added.
 
 - New alias :doc:`cert-msc33-c

clang-tools-extra/docs/clang-tidy/checks/list.rst

.. csv-table::
    `llvm-twine-local <llvm/twine-local.html>`_, "Yes"
    `llvmlibc-callee-namespace <llvmlibc/callee-namespace.html>`_,
    `llvmlibc-implementation-in-namespace <llvmlibc/implementation-in-namespace.html>`_,
    `llvmlibc-inline-function-decl <llvmlibc/inline-function-decl.html>`_,
    `llvmlibc-restrict-system-libc-headers <llvmlibc/restrict-system-libc-headers.html>`_, "Yes"
    `misc-confusable-identifiers <misc/confusable-identifiers.html>`_,
    `misc-const-correctness <misc/const-correctness.html>`_, "Yes"
    `misc-definitions-in-headers <misc/definitions-in-headers.html>`_, "Yes"
+   `misc-header-include-cycle <misc/header-include-cycle.html>`_,
    `misc-misleading-bidirectional <misc/misleading-bidirectional.html>`_,
    `misc-misleading-identifier <misc/misleading-identifier.html>`_,
    `misc-misplaced-const <misc/misplaced-const.html>`_,
    `misc-new-delete-overloads <misc/new-delete-overloads.html>`_,
    `misc-no-recursion <misc/no-recursion.html>`_,
    `misc-non-copyable-objects <misc/non-copyable-objects.html>`_,
    `misc-non-private-member-variables-in-classes <misc/non-private-member-variables-in-classes.html>`_,
    `misc-redundant-expression <misc/redundant-expression.html>`_, "Yes"

clang-tools-extra/docs/clang-tidy/checks/misc/header-include-cycle.rst

+.. title:: clang-tidy - misc-header-include-cycle
+
+misc-header-include-cycle
+=========================
+
+Check detects cyclic ``#include`` dependencies between user-defined headers.
+
+.. code-block:: c++
+
+    // Header A.hpp
+    #pragma once
+    #include "B.hpp"
+
+    // Header B.hpp
+    #pragma once
+    #include "C.hpp"
+
+    // Header C.hpp
+    #pragma once
+    #include "A.hpp"
+
+    // Include chain: A->B->C->A
+
+Header files are a crucial part of many C++ programs, as they provide a way to
+organize declarations and definitions that are shared across multiple source
+files. However, header files can also create problems when they become entangled
+in complex dependency cycles. Such cycles can cause issues with compilation
+times, unnecessary rebuilds, and make it harder to understand the overall
+structure of the code.
+
+To address these issues, this check has been developed. This check is designed
+to detect cyclic dependencies between header files, also known as
+"include cycles". An include cycle occurs when a header file `A` includes a
+header file `B`, and header file `B` (or any later included header file in the
+chain) includes back header file `A`, leading to a circular dependency cycle.
+
+This check operates at the preprocessor level and analyzes user-defined headers
+and their dependencies. It focuses specifically on detecting include cycles,
+and ignores other types or function dependencies. This allows it to provide a
+specialized analysis that is focused on identifying and preventing issues
+related to header file organization.
+
+The benefits of using this check are numerous. By detecting include cycles early
+in the development process, developers can identify and resolve these issues
+before they become more difficult and time-consuming to fix. This can lead to
+faster compile times, improved code quality, and a more maintainable codebase
+overall. Additionally, by ensuring that header files are organized in a way that
+avoids cyclic dependencies, developers can make their code easier to understand
+and modify over time.
+
+It's worth noting that this tool only analyzes user-defined headers and their
+dependencies, excluding system includes such as standard library headers and
+third-party library headers. System includes are usually well-designed and free
+of include cycles, and ignoring them helps to focus on potential issues within
+the project's own codebase. This limitation doesn't diminish the tool's ability
+to detect ``#include`` cycles within the analyzed code. As with any tool,
+developers should use their judgment when evaluating the warnings produced by
+the check and be prepared to make exceptions or modifications to their code as
+needed.
+
+Options
+-------
+
+.. option:: IgnoredFilesList
+
+    Provides a way to exclude specific files/headers from the warnings raised by
+    a check. This can be achieved by specifying a semicolon-separated list of
+    regular expressions or filenames. This option can be used as an alternative
+    to ``//NOLINT`` when using it is not possible.
+    The default value of this option is an empty string, indicating that no
+    files are ignored by default.

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.first-d.hpp

+#ifndef FIRST
+#define FIRST
+#include "header-include-cycle.second-d.hpp"
+#endif

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.first.hpp

+#pragma once
+#include "header-include-cycle.second.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.fourth-d.hpp

+#ifndef FOURTH
+#define FOURTH
+#include "header-include-cycle.first-d.hpp"
+#endif

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.fourth.hpp

+#pragma once
+#include "header-include-cycle.first.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.second-d.hpp

+#ifndef SECOND
+#define SECOND
+#include "header-include-cycle.third-d.hpp"
+#endif

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.second.hpp

+#pragma once
+#include "header-include-cycle.third.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.self-d.hpp

+#ifndef SELF
+#define SELF
+#include "header-include-cycle.self-d.hpp"
+#endif

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.self-e.hpp

+#pragma once
+#include "header-include-cycle.self-e.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.self-i.hpp

+#pragma once
+#include "header-include-cycle.self-i.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.self-n.hpp

+#pragma once
+#include "header-include-cycle.self-n.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.self-o.hpp

+#pragma once
+#include "header-include-cycle.self-n.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.self.hpp

+#pragma once
+#include "header-include-cycle.self.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.third-d.hpp

+#ifndef THIRD
+#define THIRD
+#include "header-include-cycle.fourth-d.hpp"
+#endif

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/header-include-cycle.third.hpp

+#pragma once
+#include "header-include-cycle.fourth.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/system/header-include-cycle.first-s.hpp

+#pragma once
+#include "header-include-cycle.second-s.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/system/header-include-cycle.fourth-s.hpp

+#pragma once
+#include "header-include-cycle.first-s.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/system/header-include-cycle.second-s.hpp

+#pragma once
+#include "header-include-cycle.third-s.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/system/header-include-cycle.self-s.hpp

+#pragma once
+#include "header-include-cycle.self-s.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/Inputs/system/header-include-cycle.third-s.hpp

+#pragma once
+#include "header-include-cycle.fourth-s.hpp"

clang-tools-extra/test/clang-tidy/checkers/misc/header-include-cycle.cpp

+// RUN: rm -rf %T/misc-header-include-cycle-headers
+// RUN: mkdir %T/misc-header-include-cycle-headers
+// RUN: cp -r %S/Inputs/header-include-cycle* %T/misc-header-include-cycle-headers/
+// RUN: mkdir %T/misc-header-include-cycle-headers/system
+// RUN: cp -r %S/Inputs/system/header-include-cycle* %T/misc-header-include-cycle-headers/system
+// RUN: clang-tidy %s -checks='-*,misc-header-include-cycle' -header-filter=.* \
+// RUN: -config="{CheckOptions: [{key: misc-header-include-cycle.IgnoredFilesList, value: 'header-include-cycle.self-e.hpp'}]}" \
+// RUN: -- -I%T/misc-header-include-cycle-headers -isystem %T/misc-header-include-cycle-headers/system \
+// RUN: --include %T/misc-header-include-cycle-headers/header-include-cycle.self-i.hpp | FileCheck %s \
+// RUN: -check-prefix=CHECK-MESSAGES -implicit-check-not="{{warning|error|note}}:"
+// RUN: rm -rf %T/misc-header-include-cycle-headers
+
+#ifndef MAIN_GUARD
+#define MAIN_GUARD
+
+#include <header-include-cycle.first-d.hpp>
+// CHECK-MESSAGES: header-include-cycle.fourth-d.hpp:3:10: warning: circular header file dependency detected while including 'header-include-cycle.first-d.hpp', please check the include path [misc-header-include-cycle]
+// CHECK-MESSAGES: header-include-cycle.third-d.hpp:3:10: note: 'header-include-cycle.fourth-d.hpp' included from here
+// CHECK-MESSAGES: header-include-cycle.second-d.hpp:3:10: note: 'header-include-cycle.third-d.hpp' included from here
+// CHECK-MESSAGES: header-include-cycle.first-d.hpp:3:10: note: 'header-include-cycle.second-d.hpp' included from here
+// CHECK-MESSAGES: header-include-cycle.cpp:[[@LINE-5]]:10: note: 'header-include-cycle.first-d.hpp' included from here
+
+#include <header-include-cycle.first.hpp>
+// CHECK-MESSAGES: header-include-cycle.fourth.hpp:2:10: warning: circular header file dependency detected while including 'header-include-cycle.first.hpp', please check the include path [misc-header-include-cycle]
+// CHECK-MESSAGES: header-include-cycle.third.hpp:2:10: note: 'header-include-cycle.fourth.hpp' included from here
+// CHECK-MESSAGES: header-include-cycle.second.hpp:2:10: note: 'header-include-cycle.third.hpp' included from here
+// CHECK-MESSAGES: header-include-cycle.first.hpp:2:10: note: 'header-include-cycle.second.hpp' included from here
+// CHECK-MESSAGES: header-include-cycle.cpp:[[@LINE-5]]:10: note: 'header-include-cycle.first.hpp' included from here
+
+#include <header-include-cycle.self-d.hpp>
+// CHECK-MESSAGES: header-include-cycle.self-d.hpp:3:10: warning: direct self-inclusion of header file 'header-include-cycle.self-d.hpp' [misc-header-include-cycle]
+
+// CHECK-MESSAGES: header-include-cycle.self-i.hpp:2:10: warning: direct self-inclusion of header file 'header-include-cycle.self-i.hpp' [misc-header-include-cycle]
+
+#include <header-include-cycle.self-o.hpp>
+// CHECK-MESSAGES: header-include-cycle.self-n.hpp:2:10: warning: direct self-inclusion of header file 'header-include-cycle.self-n.hpp' [misc-header-include-cycle]
+
+#include <header-include-cycle.self.hpp>
+// CHECK-MESSAGES: header-include-cycle.self.hpp:2:10: warning: direct self-inclusion of header file 'header-include-cycle.self.hpp' [misc-header-include-cycle]
+
+// Should not warn about second include of guarded headers:
+#include <header-include-cycle.first.hpp>
+#include <header-include-cycle.first-d.hpp>
+#include <header-include-cycle.self.hpp>
+#include <header-include-cycle.self-d.hpp>
+#include <header-include-cycle.self-o.hpp>
+#include <header-include-cycle.self-n.hpp>
+
+// Should not warn about system includes
+#include <header-include-cycle.first-s.hpp>
+#include <header-include-cycle.self-s.hpp>
+
+// Should not warn about this excluded header
+#include <header-include-cycle.self-e.hpp>
+
+#include "header-include-cycle.cpp"
+// CHECK-MESSAGES: header-include-cycle.cpp:[[@LINE-1]]:10: warning: direct self-inclusion of header file 'header-include-cycle.cpp' [misc-header-include-cycle]
+#endif