[clangd] Add support for HeaderInsertion in .clangd config file

[qchateau]

Summary

Add ability to configure header insertion when accepting code
completion from the .clangd config file.
The command line option always take precedence.

[sammccall]

Thanks, this is a great idea.

It also opens the door to suppressing includes of particular files later (e.g. by regex) with another config option, though we need to be careful of performance there.

clang-tools-extra/clangd/Config.h

27

Config shouldn't depend on feature headers as it gets included everywhere :-(
This is a pain point, in general we'd need to define the same enum in two places, but often we find a workaround.

Here I think CodeCompleteOpts.IncludeInsertion is only actually referenced in two places (one production + one test), so it seems like it might be simplest just to remove that member from CodeCompleteOpts and read it from Config directly instead?

clang-tools-extra/clangd/ConfigFragment.h

292

I'm torn on the naming here.

I think InsertIncludes would be a much better name: Insert vs Insertion is simpler and more active, and Includes is more accurate and descriptive than Headers. On the other hand, using exactly the same naming as the command-line flag makes it clear that it's the same option.

I think *probably* we should do the rename - we'll eventually deprecate the command-line arg and it's better to have the good name in the long run.

[qchateau]

• clangd: rename HeaderInsertion and IncludeInsertion, read value from Config

clang-tools-extra/clangd/CodeComplete.h

 //===--- CodeComplete.h ------------------------------------------*- 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
 //
 //===----------------------------------------------------------------------===//
 //
struct CodeCompleteOptions {
 
   /// Limit the number of results returned (0 means no limit).
   /// If more results are available, we set CompletionList.isIncomplete.
   size_t Limit = 0;
 
   /// Whether to present doc comments as plain-text or markdown.
   MarkupKind DocumentationFormat = MarkupKind::PlainText;
 
-  enum IncludeInsertion {
-    IWYU,
-    NeverInsert,
-  } InsertIncludes = IncludeInsertion::IWYU;
-
   /// A visual indicator to prepend to the completion label to indicate whether
   /// completion result would trigger an #include insertion or not.
   struct IncludeInsertionIndicator {
     std::string Insert = "•";
     std::string NoInsert = " ";
   } IncludeIndicator;
 
   /// Expose origins of completion items in the label (for debugging).

clang-tools-extra/clangd/CodeComplete.cpp

 //===--- CodeComplete.cpp ----------------------------------------*- 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
 //
 //===----------------------------------------------------------------------===//
 //
 // Code completion has several moving parts:
 //  - AST-based completions are provided using the completion hooks in Sema.
 //  - external completions are retrieved from the index (using hints from Sema)
 //  - the two sources overlap, and must be merged and overloads bundled
 //  - results must be scored and ranked (see Quality.h) before rendering
 //
 // Signature help works in a similar way as code completion, but it is simpler:
 // it's purely AST-based, and there are few candidates.
 //
 //===----------------------------------------------------------------------===//
 
 #include "CodeComplete.h"
 #include "AST.h"
 #include "CodeCompletionStrings.h"
 #include "Compiler.h"
+#include "Config.h"
 #include "ExpectedTypes.h"
 #include "FileDistance.h"
 #include "FuzzyMatch.h"
 #include "Headers.h"
 #include "Hover.h"
 #include "Preamble.h"
 #include "Protocol.h"
 #include "Quality.h"
#endif
     }
     assert(IdentifierResult);
     return 0;
   }
 
   // The best header to include if include insertion is allowed.
   llvm::Optional<llvm::StringRef>
   headerToInsertIfAllowed(const CodeCompleteOptions &Opts) const {
-    if (Opts.InsertIncludes == CodeCompleteOptions::NeverInsert ||
+    if (Config::current().Completion.InsertIncludes ==
+            Config::InsertIncludesPolicy::NeverInsert ||
         RankedIncludeHeaders.empty())
       return None;
     if (SemaResult && SemaResult->Declaration) {
       // Avoid inserting new #include if the declaration is found in the current
       // file e.g. the symbol is forward declared.
       auto &SM = SemaResult->Declaration->getASTContext().getSourceManager();
       for (const Decl *RD : SemaResult->Declaration->redecls())
         if (SM.isInMainFile(SM.getExpansionLoc(RD->getBeginLoc())))

clang-tools-extra/clangd/Config.h

 //===--- Config.h - User configuration of clangd behavior --------*- 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
 //
 //===----------------------------------------------------------------------===//
 //

 // of layering problems. Config should be expressed in terms of simple
 // vocabulary types where possible.
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_CONFIG_H
 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_CONFIG_H
 
 #include "support/Context.h"
 #include "llvm/ADT/FunctionExtras.h"
 #include "llvm/ADT/Optional.h"
 #include "llvm/ADT/StringMap.h"
 #include "llvm/ADT/StringSet.h"
 #include <functional>
 #include <string>
 #include <vector>
 
struct Config {
   /// Style of the codebase.
   struct {
     // Namespaces that should always be fully qualified, meaning no "using"
     // declarations, always spell out the whole name (with or without leading
     // ::). All nested namespaces are affected as well.
     std::vector<std::string> FullyQualifiedNamespaces;
   } Style;
 
+  enum class InsertIncludesPolicy {
+    IWYU,
+    NeverInsert,
+  };
   /// Configures code completion feature.
   struct {
     /// Whether code completion includes results that are not visible in current
     /// scopes.
     bool AllScopes = true;
+
+    /// Add #include directives when accepting code completions.
+    InsertIncludesPolicy InsertIncludes = InsertIncludesPolicy::IWYU;
   } Completion;
 
   /// Configures hover feature.
   struct {
     /// Whether hover show a.k.a type.
     bool ShowAKA = true;
   } Hover;
 

clang-tools-extra/clangd/ConfigCompile.cpp

 //===--- ConfigCompile.cpp - Translating Fragments into Config ------------===//
 //
 // 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
 //
 //===----------------------------------------------------------------------===//
 //
#endif
 
   void compile(Fragment::CompletionBlock &&F) {
     if (F.AllScopes) {
       Out.Apply.push_back(
           [AllScopes(**F.AllScopes)](const Params &, Config &C) {
             C.Completion.AllScopes = AllScopes;
           });
     }
+    if (F.InsertIncludes) {
+      if (auto Val =
+              compileEnum<Config::InsertIncludesPolicy>("InsertIncludes",
+                                                        **F.InsertIncludes)
+                  .map("Never", Config::InsertIncludesPolicy::NeverInsert)
+                  .map("IWYU", Config::InsertIncludesPolicy::IWYU)
+                  .value())
+        Out.Apply.push_back([Val](const Params &, Config &C) {
+          C.Completion.InsertIncludes = *Val;
+        });
+    }
   }
 
   void compile(Fragment::HoverBlock &&F) {
     if (F.ShowAKA) {
       Out.Apply.push_back([ShowAKA(**F.ShowAKA)](const Params &, Config &C) {
         C.Hover.ShowAKA = ShowAKA;
       });
     }

clang-tools-extra/clangd/ConfigFragment.h

 //===--- ConfigFragment.h - Unit of user-specified configuration -*- 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
 //
 //===----------------------------------------------------------------------===//
 //
struct Fragment {
   };
   StyleBlock Style;
 
   /// Describes code completion preferences.
   struct CompletionBlock {
     /// Whether code completion should include suggestions from scopes that are
     /// not visible. The required scope prefix will be inserted.
     llvm::Optional<Located<bool>> AllScopes;
+    /// Add #include directives when accepting code completions.
+    ///
+    /// Valid values are:
+    /// - Never
+    /// - IWYU
+    llvm::Optional<Located<std::string>> InsertIncludes;
   };
   CompletionBlock Completion;
 
   /// Describes hover preferences.
   struct HoverBlock {
     /// Whether hover show a.k.a type.
     llvm::Optional<Located<bool>> ShowAKA;
   };

clang-tools-extra/clangd/ConfigYAML.cpp

 //===--- ConfigYAML.cpp - Loading configuration fragments from YAML files -===//
 //
 // 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 "ConfigFragment.h"
private:
   }
 
   void parse(Fragment::CompletionBlock &F, Node &N) {
     DictParser Dict("Completion", this);
     Dict.handle("AllScopes", [&](Node &N) {
       if (auto AllScopes = boolValue(N, "AllScopes"))
         F.AllScopes = *AllScopes;
     });
+    Dict.handle("InsertIncludes", [&](Node &N) {
+      if (auto InsertIncludes = scalarValue(N, "InsertIncludes"))
+        F.InsertIncludes = *InsertIncludes;
+    });
     Dict.parse(N);
   }
 
   void parse(Fragment::HoverBlock &F, Node &N) {
     DictParser Dict("Hover", this);
     Dict.handle("ShowAKA", [&](Node &N) {
       if (auto ShowAKA = boolValue(N, "ShowAKA"))
         F.ShowAKA = *ShowAKA;

clang-tools-extra/clangd/tool/ClangdMain.cpp

 //===--- ClangdMain.cpp - clangd server loop ------------------------------===//
 //
 // 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
 //
 //===----------------------------------------------------------------------===//
 
opt<bool> EnableFunctionArgSnippets{
     "function-arg-placeholders",
     cat(Features),
     desc("When disabled, completions contain only parentheses for "
          "function calls. When enabled, completions also contain "
          "placeholders for method parameters"),
     init(CodeCompleteOptions().EnableFunctionArgSnippets),
 };
 
-opt<CodeCompleteOptions::IncludeInsertion> HeaderInsertion{
+opt<Config::InsertIncludesPolicy> HeaderInsertion{
     "header-insertion",
     cat(Features),
     desc("Add #include directives when accepting code completions"),
-    init(CodeCompleteOptions().InsertIncludes),
+    init(Config().Completion.InsertIncludes),
     values(
-        clEnumValN(CodeCompleteOptions::IWYU, "iwyu",
+        clEnumValN(Config::InsertIncludesPolicy::IWYU, "iwyu",
                    "Include what you use. "
                    "Insert the owning header for top-level symbols, unless the "
                    "header is already directly included or the symbol is "
                    "forward-declared"),
         clEnumValN(
-            CodeCompleteOptions::NeverInsert, "never",
+            Config::InsertIncludesPolicy::NeverInsert, "never",
             "Never insert #include directives as part of code completion")),
 };
 
 opt<bool> IncludeCleanerStdlib{
     "include-cleaner-stdlib",
     cat(Features),
     desc("Apply include-cleaner analysis to standard library headers "
          "(immature!)"),
Frag = [=](const config::Params &, Config &C) {
       if (CDBSearch)
         C.CompileFlags.CDBSearch = *CDBSearch;
       if (IndexSpec)
         C.Index.External = *IndexSpec;
       if (BGPolicy)
         C.Index.Background = *BGPolicy;
       if (AllScopesCompletion.getNumOccurrences())
         C.Completion.AllScopes = AllScopesCompletion;
+      if (HeaderInsertion.getNumOccurrences())
+        C.Completion.InsertIncludes = HeaderInsertion;
       return true;
     };
   }
 };
 } // namespace
 } // namespace clangd
 } // namespace clang
 
#endif
   Opts.AsyncThreadsCount = WorkerThreadsCount;
   Opts.MemoryCleanup = getMemoryCleanupFunction();
 
   Opts.CodeComplete.IncludeIneligibleResults = IncludeIneligibleResults;
   Opts.CodeComplete.Limit = LimitResults;
   if (CompletionStyle.getNumOccurrences())
     Opts.CodeComplete.BundleOverloads = CompletionStyle != Detailed;
   Opts.CodeComplete.ShowOrigins = ShowOrigins;
-  Opts.CodeComplete.InsertIncludes = HeaderInsertion;
   if (!HeaderInsertionDecorators) {
     Opts.CodeComplete.IncludeIndicator.Insert.clear();
     Opts.CodeComplete.IncludeIndicator.NoInsert.clear();
   }
   Opts.CodeComplete.EnableFunctionArgSnippets = EnableFunctionArgSnippets;
   Opts.CodeComplete.RunParser = CodeCompletionParse;
   Opts.CodeComplete.RankingModel = RankingModel;
 

clang-tools-extra/clangd/unittests/CodeCompleteTests.cpp

 //===-- CodeCompleteTests.cpp -----------------------------------*- 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
 //
 //===----------------------------------------------------------------------===//
 
 #include "ASTSignals.h"
 #include "Annotations.h"
 #include "ClangdServer.h"
 #include "CodeComplete.h"
 #include "Compiler.h"
+#include "Config.h"
 #include "Matchers.h"
 #include "Protocol.h"
 #include "Quality.h"
 #include "SourceCode.h"
 #include "SyncAPI.h"
 #include "TestFS.h"
 #include "TestIndex.h"
 #include "TestTU.h"
auto Results = completions(
           namespace ns { int local; void both(); }
           void f() { ::ns::^ }
       )cpp",
       {func("ns::both"), cls("ns::Index")}, Opts);
   EXPECT_EQ(Results.Completions.size(), Opts.Limit);
   EXPECT_TRUE(Results.HasMore);
 }
 
-TEST(CompletionTest, IncludeInsertionPreprocessorIntegrationTests) {
+TEST(CompletionTest, InsertIncludesPolicyPreprocessorIntegrationTests) {
   TestTU TU;
   TU.ExtraArgs.push_back("-I" + testPath("sub"));
   TU.AdditionalFiles["sub/bar.h"] = "";
   auto BarURI = URI::create(testPath("sub/bar.h")).toString();
 
   Symbol Sym = cls("ns::X");
   Sym.CanonicalDeclaration.FileURI = BarURI.c_str();
   Sym.IncludeHeaders.emplace_back(BarURI, 1);
   // Shorten include path based on search directory and insert.
   Annotations Test("int main() { ns::^ }");
   TU.Code = Test.code().str();
   auto Results = completions(TU, Test.point(), {Sym});
   EXPECT_THAT(Results.Completions,
               ElementsAre(AllOf(named("X"), insertInclude("\"bar.h\""))));
-  // Can be disabled via option.
-  CodeCompleteOptions NoInsertion;
-  NoInsertion.InsertIncludes = CodeCompleteOptions::NeverInsert;
-  Results = completions(TU, Test.point(), {Sym}, NoInsertion);
+  // Can be disabled via config.
+  {
+    Config Cfg;
+    Cfg.Completion.InsertIncludes = Config::InsertIncludesPolicy::NeverInsert;
+    WithContextValue WithCfg(Config::Key, std::move(Cfg));
+    Results = completions(TU, Test.point(), {Sym});
     EXPECT_THAT(Results.Completions,
                 ElementsAre(AllOf(named("X"), Not(insertInclude()))));
+  }
   // Duplicate based on inclusions in preamble.
   Test = Annotations(R"cpp(
           #include "sub/bar.h"  // not shortest, so should only match resolved.
           int main() { ns::^ }
       )cpp");
   TU.Code = Test.code().str();
   Results = completions(TU, Test.point(), {Sym});
   EXPECT_THAT(Results.Completions, ElementsAre(AllOf(named("X"), labeled("X"),

clang-tools-extra/clangd/unittests/ConfigCompileTests.cpp

 //===-- ConfigCompileTests.cpp --------------------------------------------===//
 //
 // 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 "CodeComplete.h"
 #include "Config.h"
 #include "ConfigFragment.h"
 #include "ConfigTesting.h"
 #include "Diagnostics.h"
 #include "Feature.h"
 #include "TestFS.h"
 #include "clang/Basic/DiagnosticSema.h"
 #include "llvm/ADT/None.h"
TEST_F(ConfigCompileTests, AllScopes) {
   EXPECT_FALSE(Conf.Completion.AllScopes);
 
   Frag = {};
   Frag.Completion.AllScopes = true;
   EXPECT_TRUE(compileAndApply());
   EXPECT_TRUE(Conf.Completion.AllScopes);
 }
 
+TEST_F(ConfigCompileTests, InsertIncludes) {
+  // Defaults to IWYU.
+  EXPECT_TRUE(compileAndApply());
+  EXPECT_EQ(Conf.Completion.InsertIncludes, Config::InsertIncludesPolicy::IWYU);
+
+  Frag = {};
+  Frag.Completion.InsertIncludes = std::string("IWYU");
+  EXPECT_TRUE(compileAndApply());
+  EXPECT_EQ(Conf.Completion.InsertIncludes, Config::InsertIncludesPolicy::IWYU);
+
+  Frag = {};
+  Frag.Completion.InsertIncludes = std::string("Never");
+  EXPECT_TRUE(compileAndApply());
+  EXPECT_EQ(Conf.Completion.InsertIncludes,
+            Config::InsertIncludesPolicy::NeverInsert);
+}
+
 TEST_F(ConfigCompileTests, Style) {
   Frag = {};
   Frag.Style.FullyQualifiedNamespaces.push_back(std::string("foo"));
   Frag.Style.FullyQualifiedNamespaces.push_back(std::string("bar"));
   EXPECT_TRUE(compileAndApply());
   EXPECT_THAT(Conf.Style.FullyQualifiedNamespaces, ElementsAre("foo", "bar"));
 }
 } // namespace
 } // namespace config
 } // namespace clangd
 } // namespace clang

clang-tools-extra/clangd/unittests/ConfigYAMLTests.cpp

 //===-- ConfigYAMLTests.cpp -----------------------------------------------===//
 //
 // 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
 //
 //===----------------------------------------------------------------------===//
 
EXPECT_THAT(Diags.Diagnostics,
               ElementsAre(AllOf(diagMessage("AllScopes should be a boolean"),
                                 diagKind(llvm::SourceMgr::DK_Warning),
                                 diagPos(YAML.range("diagrange").start),
                                 diagRange(YAML.range("diagrange")))));
   ASSERT_EQ(Results.size(), 1u);
   EXPECT_THAT(Results[0].Completion.AllScopes, testing::Eq(llvm::None));
 }
 
+TEST(ParseYAML, InsertIncludes) {
+  CapturedDiags Diags;
+  Annotations YAML(R"yaml(
+Completion:
+  InsertIncludes: Never
+  )yaml");
+  auto Results =
+      Fragment::parseYAML(YAML.code(), "config.yaml", Diags.callback());
+  ASSERT_THAT(Diags.Diagnostics, IsEmpty());
+  ASSERT_EQ(Results.size(), 1u);
+  EXPECT_THAT(Results[0].Completion.InsertIncludes,
+              llvm::ValueIs(val("Never")));
+}
+
 TEST(ParseYAML, ShowAKA) {
   CapturedDiags Diags;
   Annotations YAML(R"yaml(
 Hover:
   ShowAKA: True
   )yaml");
   auto Results =
       Fragment::parseYAML(YAML.code(), "config.yaml", Diags.callback());