clang-format: Add IncludeSortKey option

Sorting by stem gives nicer results when various header file names
are substrings of other header file names, for example, a CLI application
with a main header named analyze.h and a analyze-xxx.h header for each
subcommand currently will always put analyze.h last after all the
analyze-xxx.h headers, but putting analyze.h first instead of last is arguable
nicer to read.

TLDR; Instead of

"""
/#include "analyze-blame.h"
/#include "analyze.h"
"""

You'd get

"""
/#include "analyze.h"
/#include "analyze-blame.h"
"""

Let's allow sorting by stem instead of full path by introducing a new
option IncludeSortKey with two values "Path" and "Stem".

Author: DaanDeMeyer

clang/docs/ClangFormatStyleOptions.rst

@@ -4226,6 +4226,11 @@ the configuration (without a prefix: ``Auto``).
   ``ClassImpl.hpp`` would not have the main include file put on top
   before any other include.
 
+.. _IncludeSortIgnoreExtension:
+
+**IncludeSortIgnoreExtension** (``Boolean``) :versionbadge:`clang-format 21` :ref:`¶ <IncludeSortIgnoreExtension>`
+  When sorting includes in each block, ignore file extensions.
+
 .. _IndentAccessModifiers:
 
 **IndentAccessModifiers** (``Boolean``) :versionbadge:`clang-format 13` :ref:`¶ <IndentAccessModifiers>`

clang/include/clang/Format/Format.h

@@ -5368,6 +5368,8 @@ struct FormatStyle {
            IncludeStyle.IncludeIsMainSourceRegex ==
                R.IncludeStyle.IncludeIsMainSourceRegex &&
            IncludeStyle.MainIncludeChar == R.IncludeStyle.MainIncludeChar &&
+           IncludeStyle.IncludeSortIgnoreExtension ==
+               R.IncludeStyle.IncludeSortIgnoreExtension &&
            IndentAccessModifiers == R.IndentAccessModifiers &&
            IndentCaseBlocks == R.IndentCaseBlocks &&
            IndentCaseLabels == R.IndentCaseLabels &&

clang/include/clang/Tooling/Inclusions/IncludeStyle.h

@@ -152,6 +152,10 @@ struct IncludeStyle {
   /// \version 10
   std::string IncludeIsMainSourceRegex;
 
+  /// When sorting includes in each block, ignore file extensions.
+  /// \version 21
+  bool IncludeSortIgnoreExtension;
+
   /// Character to consider in the include directives for the main header.
   enum MainIncludeCharDiscriminator : int8_t {
     /// Main include uses quotes: ``#include "foo.hpp"`` (the default).

clang/lib/Format/Format.cpp

@@ -1062,6 +1062,8 @@ template <> struct MappingTraits<FormatStyle> {
     IO.mapOptional("IncludeIsMainRegex", Style.IncludeStyle.IncludeIsMainRegex);
     IO.mapOptional("IncludeIsMainSourceRegex",
                    Style.IncludeStyle.IncludeIsMainSourceRegex);
+    IO.mapOptional("IncludeSortIgnoreExtension",
+                   Style.IncludeStyle.IncludeSortIgnoreExtension);
     IO.mapOptional("IndentAccessModifiers", Style.IndentAccessModifiers);
     IO.mapOptional("IndentCaseBlocks", Style.IndentCaseBlocks);
     IO.mapOptional("IndentCaseLabels", Style.IndentCaseLabels);
@@ -1581,6 +1583,7 @@ FormatStyle getLLVMStyle(FormatStyle::LanguageKind Language) {
       {"^(<|\"(gtest|gmock|isl|json)/)", 3, 0, false},
       {".*", 1, 0, false}};
   LLVMStyle.IncludeStyle.IncludeIsMainRegex = "(Test)?$";
+  LLVMStyle.IncludeStyle.IncludeSortIgnoreExtension = false;
   LLVMStyle.IncludeStyle.MainIncludeChar = tooling::IncludeStyle::MICD_Quote;
   LLVMStyle.IndentAccessModifiers = false;
   LLVMStyle.IndentCaseBlocks = false;
@@ -3217,21 +3220,27 @@ static void sortCppIncludes(const FormatStyle &Style,
   SmallVector<unsigned, 16> Indices =
       llvm::to_vector<16>(llvm::seq<unsigned>(0, Includes.size()));
 
-  if (Style.SortIncludes == FormatStyle::SI_CaseInsensitive) {
-    stable_sort(Indices, [&](unsigned LHSI, unsigned RHSI) {
-      const auto LHSFilenameLower = Includes[LHSI].Filename.lower();
-      const auto RHSFilenameLower = Includes[RHSI].Filename.lower();
-      return std::tie(Includes[LHSI].Priority, LHSFilenameLower,
-                      Includes[LHSI].Filename) <
-             std::tie(Includes[RHSI].Priority, RHSFilenameLower,
-                      Includes[RHSI].Filename);
-    });
-  } else {
-    stable_sort(Indices, [&](unsigned LHSI, unsigned RHSI) {
-      return std::tie(Includes[LHSI].Priority, Includes[LHSI].Filename) <
-             std::tie(Includes[RHSI].Priority, Includes[RHSI].Filename);
-    });
-  }
+  stable_sort(Indices, [&](unsigned LHSI, unsigned RHSI) {
+    SmallString<128> LHSStem, RHSStem;
+    if (Style.IncludeStyle.IncludeSortIgnoreExtension) {
+      LHSStem = Includes[LHSI].Filename;
+      RHSStem = Includes[RHSI].Filename;
+      llvm::sys::path::replace_extension(LHSStem, "");
+      llvm::sys::path::replace_extension(RHSStem, "");
+    }
+    std::string LHSStemLower, RHSStemLower;
+    std::string LHSFilenameLower, RHSFilenameLower;
+    if (Style.SortIncludes == FormatStyle::SI_CaseInsensitive) {
+      LHSStemLower = LHSStem.str().lower();
+      RHSStemLower = RHSStem.str().lower();
+      LHSFilenameLower = Includes[LHSI].Filename.lower();
+      RHSFilenameLower = Includes[RHSI].Filename.lower();
+    }
+    return std::tie(Includes[LHSI].Priority, LHSStemLower, LHSStem,
+                    LHSFilenameLower, Includes[LHSI].Filename) <
+           std::tie(Includes[RHSI].Priority, RHSStemLower, RHSStem,
+                    RHSFilenameLower, Includes[RHSI].Filename);
+  });
 
   // The index of the include on which the cursor will be put after
   // sorting/deduplicating.

clang/unittests/Format/SortIncludesTest.cpp

@@ -1485,6 +1485,26 @@ TEST_F(SortIncludesTest, BlockCommentedOutIncludes) {
   verifyFormat(Code, sort(Code, "input.cpp", 0));
 }
 
+TEST_F(SortIncludesTest, IncludeSortIgnoreExtension) {
+  verifyFormat("#include <a-util.h>\n"
+               "#include <a.h>\n"
+               "#include <a.inc>",
+               sort("#include <a.inc>\n"
+                    "#include <a-util.h>\n"
+                    "#include <a.h>",
+                    "input.h", 1));
+
+  Style.IncludeSortIgnoreExtension = true;
+
+  verifyFormat("#include <a.h>\n"
+               "#include <a.inc>\n"
+               "#include <a-util.h>",
+               sort("#include <a.inc>\n"
+                    "#include <a-util.h>\n"
+                    "#include <a.h>",
+                    "input.h", 1));
+}
+
 } // end namespace
 } // end namespace format
 } // end namespace clang