clang-tools  8.0.0
CodeComplete.cpp
Go to the documentation of this file.
1 //===--- CodeComplete.cpp ----------------------------------------*- C++-*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // Code completion has several moving parts:
11 // - AST-based completions are provided using the completion hooks in Sema.
12 // - external completions are retrieved from the index (using hints from Sema)
13 // - the two sources overlap, and must be merged and overloads bundled
14 // - results must be scored and ranked (see Quality.h) before rendering
15 //
16 // Signature help works in a similar way as code completion, but it is simpler:
17 // it's purely AST-based, and there are few candidates.
18 //
19 //===----------------------------------------------------------------------===//
20 
21 #include "CodeComplete.h"
22 #include "AST.h"
23 #include "ClangdUnit.h"
24 #include "CodeCompletionStrings.h"
25 #include "Compiler.h"
26 #include "Diagnostics.h"
27 #include "ExpectedTypes.h"
28 #include "FileDistance.h"
29 #include "FuzzyMatch.h"
30 #include "Headers.h"
31 #include "Logger.h"
32 #include "Quality.h"
33 #include "SourceCode.h"
34 #include "TUScheduler.h"
35 #include "Trace.h"
36 #include "URI.h"
37 #include "index/Index.h"
38 #include "clang/AST/Decl.h"
39 #include "clang/AST/DeclBase.h"
40 #include "clang/Basic/LangOptions.h"
41 #include "clang/Basic/SourceLocation.h"
42 #include "clang/Format/Format.h"
43 #include "clang/Frontend/CompilerInstance.h"
44 #include "clang/Frontend/FrontendActions.h"
45 #include "clang/Lex/PreprocessorOptions.h"
46 #include "clang/Sema/CodeCompleteConsumer.h"
47 #include "clang/Sema/Sema.h"
48 #include "llvm/ADT/ArrayRef.h"
49 #include "llvm/ADT/None.h"
50 #include "llvm/ADT/Optional.h"
51 #include "llvm/ADT/SmallVector.h"
52 #include "llvm/Support/Error.h"
53 #include "llvm/Support/Format.h"
54 #include "llvm/Support/FormatVariadic.h"
55 #include "llvm/Support/ScopedPrinter.h"
56 #include <algorithm>
57 #include <iterator>
58 
59 // We log detailed candidate here if you run with -debug-only=codecomplete.
60 #define DEBUG_TYPE "CodeComplete"
61 
62 namespace clang {
63 namespace clangd {
64 namespace {
65 
66 CompletionItemKind toCompletionItemKind(index::SymbolKind Kind) {
67  using SK = index::SymbolKind;
68  switch (Kind) {
69  case SK::Unknown:
71  case SK::Module:
72  case SK::Namespace:
73  case SK::NamespaceAlias:
75  case SK::Macro:
77  case SK::Enum:
79  // FIXME(ioeric): use LSP struct instead of class when it is suppoted in the
80  // protocol.
81  case SK::Struct:
82  case SK::Class:
83  case SK::Protocol:
84  case SK::Extension:
85  case SK::Union:
87  // FIXME(ioeric): figure out whether reference is the right type for aliases.
88  case SK::TypeAlias:
89  case SK::Using:
91  case SK::Function:
92  // FIXME(ioeric): this should probably be an operator. This should be fixed
93  // when `Operator` is support type in the protocol.
94  case SK::ConversionFunction:
96  case SK::Variable:
97  case SK::Parameter:
99  case SK::Field:
101  // FIXME(ioeric): use LSP enum constant when it is supported in the protocol.
102  case SK::EnumConstant:
104  case SK::InstanceMethod:
105  case SK::ClassMethod:
106  case SK::StaticMethod:
107  case SK::Destructor:
109  case SK::InstanceProperty:
110  case SK::ClassProperty:
111  case SK::StaticProperty:
113  case SK::Constructor:
115  }
116  llvm_unreachable("Unhandled clang::index::SymbolKind.");
117 }
118 
120 toCompletionItemKind(CodeCompletionResult::ResultKind ResKind,
121  const NamedDecl *Decl,
122  CodeCompletionContext::Kind CtxKind) {
123  if (Decl)
124  return toCompletionItemKind(index::getSymbolInfo(Decl).Kind);
125  if (CtxKind == CodeCompletionContext::CCC_IncludedFile)
127  switch (ResKind) {
128  case CodeCompletionResult::RK_Declaration:
129  llvm_unreachable("RK_Declaration without Decl");
130  case CodeCompletionResult::RK_Keyword:
132  case CodeCompletionResult::RK_Macro:
133  return CompletionItemKind::Text; // unfortunately, there's no 'Macro'
134  // completion items in LSP.
135  case CodeCompletionResult::RK_Pattern:
137  }
138  llvm_unreachable("Unhandled CodeCompletionResult::ResultKind.");
139 }
140 
141 /// Get the optional chunk as a string. This function is possibly recursive.
142 ///
143 /// The parameter info for each parameter is appended to the Parameters.
144 std::string getOptionalParameters(const CodeCompletionString &CCS,
145  std::vector<ParameterInformation> &Parameters,
146  SignatureQualitySignals &Signal) {
147  std::string Result;
148  for (const auto &Chunk : CCS) {
149  switch (Chunk.Kind) {
150  case CodeCompletionString::CK_Optional:
151  assert(Chunk.Optional &&
152  "Expected the optional code completion string to be non-null.");
153  Result += getOptionalParameters(*Chunk.Optional, Parameters, Signal);
154  break;
155  case CodeCompletionString::CK_VerticalSpace:
156  break;
157  case CodeCompletionString::CK_Placeholder:
158  // A string that acts as a placeholder for, e.g., a function call
159  // argument.
160  // Intentional fallthrough here.
161  case CodeCompletionString::CK_CurrentParameter: {
162  // A piece of text that describes the parameter that corresponds to
163  // the code-completion location within a function call, message send,
164  // macro invocation, etc.
165  Result += Chunk.Text;
166  ParameterInformation Info;
167  Info.label = Chunk.Text;
168  Parameters.push_back(std::move(Info));
169  Signal.ContainsActiveParameter = true;
170  Signal.NumberOfOptionalParameters++;
171  break;
172  }
173  default:
174  Result += Chunk.Text;
175  break;
176  }
177  }
178  return Result;
179 }
180 
181 /// Creates a `HeaderFile` from \p Header which can be either a URI or a literal
182 /// include.
183 static llvm::Expected<HeaderFile> toHeaderFile(llvm::StringRef Header,
184  llvm::StringRef HintPath) {
185  if (isLiteralInclude(Header))
186  return HeaderFile{Header.str(), /*Verbatim=*/true};
187  auto U = URI::parse(Header);
188  if (!U)
189  return U.takeError();
190 
191  auto IncludePath = URI::includeSpelling(*U);
192  if (!IncludePath)
193  return IncludePath.takeError();
194  if (!IncludePath->empty())
195  return HeaderFile{std::move(*IncludePath), /*Verbatim=*/true};
196 
197  auto Resolved = URI::resolve(*U, HintPath);
198  if (!Resolved)
199  return Resolved.takeError();
200  return HeaderFile{std::move(*Resolved), /*Verbatim=*/false};
201 }
202 
203 /// A code completion result, in clang-native form.
204 /// It may be promoted to a CompletionItem if it's among the top-ranked results.
205 struct CompletionCandidate {
206  llvm::StringRef Name; // Used for filtering and sorting.
207  // We may have a result from Sema, from the index, or both.
208  const CodeCompletionResult *SemaResult = nullptr;
209  const Symbol *IndexResult = nullptr;
210  llvm::SmallVector<llvm::StringRef, 1> RankedIncludeHeaders;
211 
212  // Returns a token identifying the overload set this is part of.
213  // 0 indicates it's not part of any overload set.
214  size_t overloadSet() const {
215  llvm::SmallString<256> Scratch;
216  if (IndexResult) {
217  switch (IndexResult->SymInfo.Kind) {
218  case index::SymbolKind::ClassMethod:
219  case index::SymbolKind::InstanceMethod:
220  case index::SymbolKind::StaticMethod:
221 #ifndef NDEBUG
222  llvm_unreachable("Don't expect members from index in code completion");
223 #else
224  LLVM_FALLTHROUGH;
225 #endif
226  case index::SymbolKind::Function:
227  // We can't group overloads together that need different #includes.
228  // This could break #include insertion.
229  return llvm::hash_combine(
230  (IndexResult->Scope + IndexResult->Name).toStringRef(Scratch),
231  headerToInsertIfAllowed().getValueOr(""));
232  default:
233  return 0;
234  }
235  }
236  assert(SemaResult);
237  // We need to make sure we're consistent with the IndexResult case!
238  const NamedDecl *D = SemaResult->Declaration;
239  if (!D || !D->isFunctionOrFunctionTemplate())
240  return 0;
241  {
242  llvm::raw_svector_ostream OS(Scratch);
243  D->printQualifiedName(OS);
244  }
245  return llvm::hash_combine(Scratch,
246  headerToInsertIfAllowed().getValueOr(""));
247  }
248 
249  // The best header to include if include insertion is allowed.
250  llvm::Optional<llvm::StringRef> headerToInsertIfAllowed() const {
251  if (RankedIncludeHeaders.empty())
252  return None;
253  if (SemaResult && SemaResult->Declaration) {
254  // Avoid inserting new #include if the declaration is found in the current
255  // file e.g. the symbol is forward declared.
256  auto &SM = SemaResult->Declaration->getASTContext().getSourceManager();
257  for (const Decl *RD : SemaResult->Declaration->redecls())
258  if (SM.isInMainFile(SM.getExpansionLoc(RD->getBeginLoc())))
259  return None;
260  }
261  return RankedIncludeHeaders[0];
262  }
263 
264  using Bundle = llvm::SmallVector<CompletionCandidate, 4>;
265 };
266 using ScoredBundle =
267  std::pair<CompletionCandidate::Bundle, CodeCompletion::Scores>;
268 struct ScoredBundleGreater {
269  bool operator()(const ScoredBundle &L, const ScoredBundle &R) {
270  if (L.second.Total != R.second.Total)
271  return L.second.Total > R.second.Total;
272  return L.first.front().Name <
273  R.first.front().Name; // Earlier name is better.
274  }
275 };
276 
277 // Assembles a code completion out of a bundle of >=1 completion candidates.
278 // Many of the expensive strings are only computed at this point, once we know
279 // the candidate bundle is going to be returned.
280 //
281 // Many fields are the same for all candidates in a bundle (e.g. name), and are
282 // computed from the first candidate, in the constructor.
283 // Others vary per candidate, so add() must be called for remaining candidates.
284 struct CodeCompletionBuilder {
285  CodeCompletionBuilder(ASTContext &ASTCtx, const CompletionCandidate &C,
286  CodeCompletionString *SemaCCS,
287  llvm::ArrayRef<std::string> QueryScopes,
288  const IncludeInserter &Includes,
289  llvm::StringRef FileName,
290  CodeCompletionContext::Kind ContextKind,
291  const CodeCompleteOptions &Opts)
292  : ASTCtx(ASTCtx), ExtractDocumentation(Opts.IncludeComments),
293  EnableFunctionArgSnippets(Opts.EnableFunctionArgSnippets) {
294  add(C, SemaCCS);
295  if (C.SemaResult) {
296  Completion.Origin |= SymbolOrigin::AST;
297  Completion.Name = llvm::StringRef(SemaCCS->getTypedText());
298  if (Completion.Scope.empty()) {
299  if ((C.SemaResult->Kind == CodeCompletionResult::RK_Declaration) ||
300  (C.SemaResult->Kind == CodeCompletionResult::RK_Pattern))
301  if (const auto *D = C.SemaResult->getDeclaration())
302  if (const auto *ND = dyn_cast<NamedDecl>(D))
303  Completion.Scope =
305  }
306  Completion.Kind = toCompletionItemKind(
307  C.SemaResult->Kind, C.SemaResult->Declaration, ContextKind);
308  // Sema could provide more info on whether the completion was a file or
309  // folder.
310  if (Completion.Kind == CompletionItemKind::File &&
311  Completion.Name.back() == '/')
312  Completion.Kind = CompletionItemKind::Folder;
313  for (const auto &FixIt : C.SemaResult->FixIts) {
314  Completion.FixIts.push_back(
315  toTextEdit(FixIt, ASTCtx.getSourceManager(), ASTCtx.getLangOpts()));
316  }
317  llvm::sort(Completion.FixIts, [](const TextEdit &X, const TextEdit &Y) {
318  return std::tie(X.range.start.line, X.range.start.character) <
319  std::tie(Y.range.start.line, Y.range.start.character);
320  });
321  Completion.Deprecated |=
322  (C.SemaResult->Availability == CXAvailability_Deprecated);
323  }
324  if (C.IndexResult) {
325  Completion.Origin |= C.IndexResult->Origin;
326  if (Completion.Scope.empty())
327  Completion.Scope = C.IndexResult->Scope;
328  if (Completion.Kind == CompletionItemKind::Missing)
329  Completion.Kind = toCompletionItemKind(C.IndexResult->SymInfo.Kind);
330  if (Completion.Name.empty())
331  Completion.Name = C.IndexResult->Name;
332  // If the completion was visible to Sema, no qualifier is needed. This
333  // avoids unneeded qualifiers in cases like with `using ns::X`.
334  if (Completion.RequiredQualifier.empty() && !C.SemaResult) {
335  llvm::StringRef ShortestQualifier = C.IndexResult->Scope;
336  for (llvm::StringRef Scope : QueryScopes) {
337  llvm::StringRef Qualifier = C.IndexResult->Scope;
338  if (Qualifier.consume_front(Scope) &&
339  Qualifier.size() < ShortestQualifier.size())
340  ShortestQualifier = Qualifier;
341  }
342  Completion.RequiredQualifier = ShortestQualifier;
343  }
344  Completion.Deprecated |= (C.IndexResult->Flags & Symbol::Deprecated);
345  }
346 
347  // Turn absolute path into a literal string that can be #included.
348  auto Inserted = [&](llvm::StringRef Header)
349  -> llvm::Expected<std::pair<std::string, bool>> {
350  auto ResolvedDeclaring =
351  toHeaderFile(C.IndexResult->CanonicalDeclaration.FileURI, FileName);
352  if (!ResolvedDeclaring)
353  return ResolvedDeclaring.takeError();
354  auto ResolvedInserted = toHeaderFile(Header, FileName);
355  if (!ResolvedInserted)
356  return ResolvedInserted.takeError();
357  return std::make_pair(
358  Includes.calculateIncludePath(*ResolvedDeclaring, *ResolvedInserted),
359  Includes.shouldInsertInclude(*ResolvedDeclaring, *ResolvedInserted));
360  };
361  bool ShouldInsert = C.headerToInsertIfAllowed().hasValue();
362  // Calculate include paths and edits for all possible headers.
363  for (const auto &Inc : C.RankedIncludeHeaders) {
364  if (auto ToInclude = Inserted(Inc)) {
365  CodeCompletion::IncludeCandidate Include;
366  Include.Header = ToInclude->first;
367  if (ToInclude->second && ShouldInsert)
368  Include.Insertion = Includes.insert(ToInclude->first);
369  Completion.Includes.push_back(std::move(Include));
370  } else
371  log("Failed to generate include insertion edits for adding header "
372  "(FileURI='{0}', IncludeHeader='{1}') into {2}",
373  C.IndexResult->CanonicalDeclaration.FileURI, Inc, FileName);
374  }
375  // Prefer includes that do not need edits (i.e. already exist).
376  std::stable_partition(Completion.Includes.begin(),
377  Completion.Includes.end(),
378  [](const CodeCompletion::IncludeCandidate &I) {
379  return !I.Insertion.hasValue();
380  });
381  }
382 
383  void add(const CompletionCandidate &C, CodeCompletionString *SemaCCS) {
384  assert(bool(C.SemaResult) == bool(SemaCCS));
385  Bundled.emplace_back();
386  BundledEntry &S = Bundled.back();
387  if (C.SemaResult) {
388  getSignature(*SemaCCS, &S.Signature, &S.SnippetSuffix,
389  &Completion.RequiredQualifier);
390  S.ReturnType = getReturnType(*SemaCCS);
391  } else if (C.IndexResult) {
392  S.Signature = C.IndexResult->Signature;
393  S.SnippetSuffix = C.IndexResult->CompletionSnippetSuffix;
394  S.ReturnType = C.IndexResult->ReturnType;
395  }
396  if (ExtractDocumentation && Completion.Documentation.empty()) {
397  if (C.IndexResult)
398  Completion.Documentation = C.IndexResult->Documentation;
399  else if (C.SemaResult)
400  Completion.Documentation = getDocComment(ASTCtx, *C.SemaResult,
401  /*CommentsFromHeader=*/false);
402  }
403  }
404 
405  CodeCompletion build() {
406  Completion.ReturnType = summarizeReturnType();
407  Completion.Signature = summarizeSignature();
408  Completion.SnippetSuffix = summarizeSnippet();
409  Completion.BundleSize = Bundled.size();
410  return std::move(Completion);
411  }
412 
413 private:
414  struct BundledEntry {
415  std::string SnippetSuffix;
416  std::string Signature;
417  std::string ReturnType;
418  };
419 
420  // If all BundledEntrys have the same value for a property, return it.
421  template <std::string BundledEntry::*Member>
422  const std::string *onlyValue() const {
423  auto B = Bundled.begin(), E = Bundled.end();
424  for (auto I = B + 1; I != E; ++I)
425  if (I->*Member != B->*Member)
426  return nullptr;
427  return &(B->*Member);
428  }
429 
430  template <bool BundledEntry::*Member> const bool *onlyValue() const {
431  auto B = Bundled.begin(), E = Bundled.end();
432  for (auto I = B + 1; I != E; ++I)
433  if (I->*Member != B->*Member)
434  return nullptr;
435  return &(B->*Member);
436  }
437 
438  std::string summarizeReturnType() const {
439  if (auto *RT = onlyValue<&BundledEntry::ReturnType>())
440  return *RT;
441  return "";
442  }
443 
444  std::string summarizeSnippet() const {
445  auto *Snippet = onlyValue<&BundledEntry::SnippetSuffix>();
446  if (!Snippet)
447  // All bundles are function calls.
448  // FIXME(ibiryukov): sometimes add template arguments to a snippet, e.g.
449  // we need to complete 'forward<$1>($0)'.
450  return "($0)";
452  return *Snippet;
453 
454  // Replace argument snippets with a simplified pattern.
455  if (Snippet->empty())
456  return "";
457  if (Completion.Kind == CompletionItemKind::Function ||
458  Completion.Kind == CompletionItemKind::Method) {
459  // Functions snippets can be of 2 types:
460  // - containing only function arguments, e.g.
461  // foo(${1:int p1}, ${2:int p2});
462  // We transform this pattern to '($0)' or '()'.
463  // - template arguments and function arguments, e.g.
464  // foo<${1:class}>(${2:int p1}).
465  // We transform this pattern to '<$1>()$0' or '<$0>()'.
466 
467  bool EmptyArgs = llvm::StringRef(*Snippet).endswith("()");
468  if (Snippet->front() == '<')
469  return EmptyArgs ? "<$1>()$0" : "<$1>($0)";
470  if (Snippet->front() == '(')
471  return EmptyArgs ? "()" : "($0)";
472  return *Snippet; // Not an arg snippet?
473  }
474  if (Completion.Kind == CompletionItemKind::Reference ||
475  Completion.Kind == CompletionItemKind::Class) {
476  if (Snippet->front() != '<')
477  return *Snippet; // Not an arg snippet?
478 
479  // Classes and template using aliases can only have template arguments,
480  // e.g. Foo<${1:class}>.
481  if (llvm::StringRef(*Snippet).endswith("<>"))
482  return "<>"; // can happen with defaulted template arguments.
483  return "<$0>";
484  }
485  return *Snippet;
486  }
487 
488  std::string summarizeSignature() const {
489  if (auto *Signature = onlyValue<&BundledEntry::Signature>())
490  return *Signature;
491  // All bundles are function calls.
492  return "(…)";
493  }
494 
495  ASTContext &ASTCtx;
496  CodeCompletion Completion;
497  llvm::SmallVector<BundledEntry, 1> Bundled;
498  bool ExtractDocumentation;
500 };
501 
502 // Determine the symbol ID for a Sema code completion result, if possible.
503 llvm::Optional<SymbolID> getSymbolID(const CodeCompletionResult &R,
504  const SourceManager &SM) {
505  switch (R.Kind) {
506  case CodeCompletionResult::RK_Declaration:
507  case CodeCompletionResult::RK_Pattern: {
508  return clang::clangd::getSymbolID(R.Declaration);
509  }
510  case CodeCompletionResult::RK_Macro:
511  return clang::clangd::getSymbolID(*R.Macro, R.MacroDefInfo, SM);
512  case CodeCompletionResult::RK_Keyword:
513  return None;
514  }
515  llvm_unreachable("unknown CodeCompletionResult kind");
516 }
517 
518 // Scopes of the paritial identifier we're trying to complete.
519 // It is used when we query the index for more completion results.
520 struct SpecifiedScope {
521  // The scopes we should look in, determined by Sema.
522  //
523  // If the qualifier was fully resolved, we look for completions in these
524  // scopes; if there is an unresolved part of the qualifier, it should be
525  // resolved within these scopes.
526  //
527  // Examples of qualified completion:
528  //
529  // "::vec" => {""}
530  // "using namespace std; ::vec^" => {"", "std::"}
531  // "namespace ns {using namespace std;} ns::^" => {"ns::", "std::"}
532  // "std::vec^" => {""} // "std" unresolved
533  //
534  // Examples of unqualified completion:
535  //
536  // "vec^" => {""}
537  // "using namespace std; vec^" => {"", "std::"}
538  // "using namespace std; namespace ns { vec^ }" => {"ns::", "std::", ""}
539  //
540  // "" for global namespace, "ns::" for normal namespace.
541  std::vector<std::string> AccessibleScopes;
542  // The full scope qualifier as typed by the user (without the leading "::").
543  // Set if the qualifier is not fully resolved by Sema.
544  llvm::Optional<std::string> UnresolvedQualifier;
545 
546  // Construct scopes being queried in indexes. The results are deduplicated.
547  // This method format the scopes to match the index request representation.
548  std::vector<std::string> scopesForIndexQuery() {
549  std::set<std::string> Results;
550  for (llvm::StringRef AS : AccessibleScopes)
551  Results.insert(
552  ((UnresolvedQualifier ? *UnresolvedQualifier : "") + AS).str());
553  return {Results.begin(), Results.end()};
554  }
555 };
556 
557 // Get all scopes that will be queried in indexes and whether symbols from
558 // any scope is allowed. The first scope in the list is the preferred scope
559 // (e.g. enclosing namespace).
560 std::pair<std::vector<std::string>, bool>
561 getQueryScopes(CodeCompletionContext &CCContext, const Sema &CCSema,
562  const CodeCompleteOptions &Opts) {
563  auto GetAllAccessibleScopes = [](CodeCompletionContext &CCContext) {
564  SpecifiedScope Info;
565  for (auto *Context : CCContext.getVisitedContexts()) {
566  if (isa<TranslationUnitDecl>(Context))
567  Info.AccessibleScopes.push_back(""); // global namespace
568  else if (isa<NamespaceDecl>(Context))
569  Info.AccessibleScopes.push_back(printNamespaceScope(*Context));
570  }
571  return Info;
572  };
573 
574  auto SS = CCContext.getCXXScopeSpecifier();
575 
576  // Unqualified completion (e.g. "vec^").
577  if (!SS) {
578  std::vector<std::string> Scopes;
579  std::string EnclosingScope = printNamespaceScope(*CCSema.CurContext);
580  Scopes.push_back(EnclosingScope);
581  for (auto &S : GetAllAccessibleScopes(CCContext).scopesForIndexQuery()) {
582  if (EnclosingScope != S)
583  Scopes.push_back(std::move(S));
584  }
585  // Allow AllScopes completion only for there is no explicit scope qualifier.
586  return {Scopes, Opts.AllScopes};
587  }
588 
589  // Qualified completion ("std::vec^"), we have two cases depending on whether
590  // the qualifier can be resolved by Sema.
591  if ((*SS)->isValid()) { // Resolved qualifier.
592  return {GetAllAccessibleScopes(CCContext).scopesForIndexQuery(), false};
593  }
594 
595  // Unresolved qualifier.
596  // FIXME: When Sema can resolve part of a scope chain (e.g.
597  // "known::unknown::id"), we should expand the known part ("known::") rather
598  // than treating the whole thing as unknown.
599  SpecifiedScope Info;
600  Info.AccessibleScopes.push_back(""); // global namespace
601 
602  Info.UnresolvedQualifier =
603  Lexer::getSourceText(CharSourceRange::getCharRange((*SS)->getRange()),
604  CCSema.SourceMgr, clang::LangOptions())
605  .ltrim("::");
606  // Sema excludes the trailing "::".
607  if (!Info.UnresolvedQualifier->empty())
608  *Info.UnresolvedQualifier += "::";
609 
610  return {Info.scopesForIndexQuery(), false};
611 }
612 
613 // Should we perform index-based completion in a context of the specified kind?
614 // FIXME: consider allowing completion, but restricting the result types.
615 bool contextAllowsIndex(enum CodeCompletionContext::Kind K) {
616  switch (K) {
617  case CodeCompletionContext::CCC_TopLevel:
618  case CodeCompletionContext::CCC_ObjCInterface:
619  case CodeCompletionContext::CCC_ObjCImplementation:
620  case CodeCompletionContext::CCC_ObjCIvarList:
621  case CodeCompletionContext::CCC_ClassStructUnion:
622  case CodeCompletionContext::CCC_Statement:
623  case CodeCompletionContext::CCC_Expression:
624  case CodeCompletionContext::CCC_ObjCMessageReceiver:
625  case CodeCompletionContext::CCC_EnumTag:
626  case CodeCompletionContext::CCC_UnionTag:
627  case CodeCompletionContext::CCC_ClassOrStructTag:
628  case CodeCompletionContext::CCC_ObjCProtocolName:
629  case CodeCompletionContext::CCC_Namespace:
630  case CodeCompletionContext::CCC_Type:
631  case CodeCompletionContext::CCC_ParenthesizedExpression:
632  case CodeCompletionContext::CCC_ObjCInterfaceName:
633  case CodeCompletionContext::CCC_ObjCCategoryName:
634  case CodeCompletionContext::CCC_Symbol:
635  case CodeCompletionContext::CCC_SymbolOrNewName:
636  return true;
637  case CodeCompletionContext::CCC_OtherWithMacros:
638  case CodeCompletionContext::CCC_DotMemberAccess:
639  case CodeCompletionContext::CCC_ArrowMemberAccess:
640  case CodeCompletionContext::CCC_ObjCPropertyAccess:
641  case CodeCompletionContext::CCC_MacroName:
642  case CodeCompletionContext::CCC_MacroNameUse:
643  case CodeCompletionContext::CCC_PreprocessorExpression:
644  case CodeCompletionContext::CCC_PreprocessorDirective:
645  case CodeCompletionContext::CCC_SelectorName:
646  case CodeCompletionContext::CCC_TypeQualifiers:
647  case CodeCompletionContext::CCC_ObjCInstanceMessage:
648  case CodeCompletionContext::CCC_ObjCClassMessage:
649  case CodeCompletionContext::CCC_IncludedFile:
650  // FIXME: Provide identifier based completions for the following contexts:
651  case CodeCompletionContext::CCC_Other: // Be conservative.
652  case CodeCompletionContext::CCC_NaturalLanguage:
653  case CodeCompletionContext::CCC_Recovery:
654  case CodeCompletionContext::CCC_NewName:
655  return false;
656  }
657  llvm_unreachable("unknown code completion context");
658 }
659 
660 static bool isInjectedClass(const NamedDecl &D) {
661  if (auto *R = dyn_cast_or_null<RecordDecl>(&D))
662  if (R->isInjectedClassName())
663  return true;
664  return false;
665 }
666 
667 // Some member calls are blacklisted because they're so rarely useful.
668 static bool isBlacklistedMember(const NamedDecl &D) {
669  // Destructor completion is rarely useful, and works inconsistently.
670  // (s.^ completes ~string, but s.~st^ is an error).
671  if (D.getKind() == Decl::CXXDestructor)
672  return true;
673  // Injected name may be useful for A::foo(), but who writes A::A::foo()?
674  if (isInjectedClass(D))
675  return true;
676  // Explicit calls to operators are also rare.
677  auto NameKind = D.getDeclName().getNameKind();
678  if (NameKind == DeclarationName::CXXOperatorName ||
679  NameKind == DeclarationName::CXXLiteralOperatorName ||
680  NameKind == DeclarationName::CXXConversionFunctionName)
681  return true;
682  return false;
683 }
684 
685 // The CompletionRecorder captures Sema code-complete output, including context.
686 // It filters out ignored results (but doesn't apply fuzzy-filtering yet).
687 // It doesn't do scoring or conversion to CompletionItem yet, as we want to
688 // merge with index results first.
689 // Generally the fields and methods of this object should only be used from
690 // within the callback.
691 struct CompletionRecorder : public CodeCompleteConsumer {
692  CompletionRecorder(const CodeCompleteOptions &Opts,
693  llvm::unique_function<void()> ResultsCallback)
694  : CodeCompleteConsumer(Opts.getClangCompleteOpts(),
695  /*OutputIsBinary=*/false),
696  CCContext(CodeCompletionContext::CCC_Other), Opts(Opts),
697  CCAllocator(std::make_shared<GlobalCodeCompletionAllocator>()),
698  CCTUInfo(CCAllocator), ResultsCallback(std::move(ResultsCallback)) {
699  assert(this->ResultsCallback);
700  }
701 
702  std::vector<CodeCompletionResult> Results;
703  CodeCompletionContext CCContext;
704  Sema *CCSema = nullptr; // Sema that created the results.
705  // FIXME: Sema is scary. Can we store ASTContext and Preprocessor, instead?
706 
707  void ProcessCodeCompleteResults(class Sema &S, CodeCompletionContext Context,
708  CodeCompletionResult *InResults,
709  unsigned NumResults) override final {
710  // Results from recovery mode are generally useless, and the callback after
711  // recovery (if any) is usually more interesting. To make sure we handle the
712  // future callback from sema, we just ignore all callbacks in recovery mode,
713  // as taking only results from recovery mode results in poor completion
714  // results.
715  // FIXME: in case there is no future sema completion callback after the
716  // recovery mode, we might still want to provide some results (e.g. trivial
717  // identifier-based completion).
718  if (Context.getKind() == CodeCompletionContext::CCC_Recovery) {
719  log("Code complete: Ignoring sema code complete callback with Recovery "
720  "context.");
721  return;
722  }
723  // If a callback is called without any sema result and the context does not
724  // support index-based completion, we simply skip it to give way to
725  // potential future callbacks with results.
726  if (NumResults == 0 && !contextAllowsIndex(Context.getKind()))
727  return;
728  if (CCSema) {
729  log("Multiple code complete callbacks (parser backtracked?). "
730  "Dropping results from context {0}, keeping results from {1}.",
731  getCompletionKindString(Context.getKind()),
732  getCompletionKindString(this->CCContext.getKind()));
733  return;
734  }
735  // Record the completion context.
736  CCSema = &S;
737  CCContext = Context;
738 
739  // Retain the results we might want.
740  for (unsigned I = 0; I < NumResults; ++I) {
741  auto &Result = InResults[I];
742  // Class members that are shadowed by subclasses are usually noise.
743  if (Result.Hidden && Result.Declaration &&
744  Result.Declaration->isCXXClassMember())
745  continue;
746  if (!Opts.IncludeIneligibleResults &&
747  (Result.Availability == CXAvailability_NotAvailable ||
748  Result.Availability == CXAvailability_NotAccessible))
749  continue;
750  if (Result.Declaration &&
751  !Context.getBaseType().isNull() // is this a member-access context?
752  && isBlacklistedMember(*Result.Declaration))
753  continue;
754  // Skip injected class name when no class scope is not explicitly set.
755  // E.g. show injected A::A in `using A::A^` but not in "A^".
756  if (Result.Declaration && !Context.getCXXScopeSpecifier().hasValue() &&
757  isInjectedClass(*Result.Declaration))
758  continue;
759  // We choose to never append '::' to completion results in clangd.
760  Result.StartsNestedNameSpecifier = false;
761  Results.push_back(Result);
762  }
763  ResultsCallback();
764  }
765 
766  CodeCompletionAllocator &getAllocator() override { return *CCAllocator; }
767  CodeCompletionTUInfo &getCodeCompletionTUInfo() override { return CCTUInfo; }
768 
769  // Returns the filtering/sorting name for Result, which must be from Results.
770  // Returned string is owned by this recorder (or the AST).
771  llvm::StringRef getName(const CodeCompletionResult &Result) {
772  switch (Result.Kind) {
773  case CodeCompletionResult::RK_Declaration:
774  if (auto *ID = Result.Declaration->getIdentifier())
775  return ID->getName();
776  break;
777  case CodeCompletionResult::RK_Keyword:
778  return Result.Keyword;
779  case CodeCompletionResult::RK_Macro:
780  return Result.Macro->getName();
781  case CodeCompletionResult::RK_Pattern:
782  return Result.Pattern->getTypedText();
783  }
784  auto *CCS = codeCompletionString(Result);
785  return CCS->getTypedText();
786  }
787 
788  // Build a CodeCompletion string for R, which must be from Results.
789  // The CCS will be owned by this recorder.
790  CodeCompletionString *codeCompletionString(const CodeCompletionResult &R) {
791  // CodeCompletionResult doesn't seem to be const-correct. We own it, anyway.
792  return const_cast<CodeCompletionResult &>(R).CreateCodeCompletionString(
793  *CCSema, CCContext, *CCAllocator, CCTUInfo,
794  /*IncludeBriefComments=*/false);
795  }
796 
797 private:
798  CodeCompleteOptions Opts;
799  std::shared_ptr<GlobalCodeCompletionAllocator> CCAllocator;
800  CodeCompletionTUInfo CCTUInfo;
801  llvm::unique_function<void()> ResultsCallback;
802 };
803 
804 struct ScoredSignature {
805  // When set, requires documentation to be requested from the index with this
806  // ID.
807  llvm::Optional<SymbolID> IDForDoc;
808  SignatureInformation Signature;
809  SignatureQualitySignals Quality;
810 };
811 
812 class SignatureHelpCollector final : public CodeCompleteConsumer {
813 public:
814  SignatureHelpCollector(const clang::CodeCompleteOptions &CodeCompleteOpts,
815  const SymbolIndex *Index, SignatureHelp &SigHelp)
816  : CodeCompleteConsumer(CodeCompleteOpts,
817  /*OutputIsBinary=*/false),
818  SigHelp(SigHelp),
819  Allocator(std::make_shared<clang::GlobalCodeCompletionAllocator>()),
820  CCTUInfo(Allocator), Index(Index) {}
821 
822  void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
823  OverloadCandidate *Candidates,
824  unsigned NumCandidates,
825  SourceLocation OpenParLoc) override {
826  assert(!OpenParLoc.isInvalid());
827  SourceManager &SrcMgr = S.getSourceManager();
828  OpenParLoc = SrcMgr.getFileLoc(OpenParLoc);
829  if (SrcMgr.isInMainFile(OpenParLoc))
830  SigHelp.argListStart = sourceLocToPosition(SrcMgr, OpenParLoc);
831  else
832  elog("Location oustide main file in signature help: {0}",
833  OpenParLoc.printToString(SrcMgr));
834 
835  std::vector<ScoredSignature> ScoredSignatures;
836  SigHelp.signatures.reserve(NumCandidates);
837  ScoredSignatures.reserve(NumCandidates);
838  // FIXME(rwols): How can we determine the "active overload candidate"?
839  // Right now the overloaded candidates seem to be provided in a "best fit"
840  // order, so I'm not too worried about this.
841  SigHelp.activeSignature = 0;
842  assert(CurrentArg <= (unsigned)std::numeric_limits<int>::max() &&
843  "too many arguments");
844  SigHelp.activeParameter = static_cast<int>(CurrentArg);
845  for (unsigned I = 0; I < NumCandidates; ++I) {
846  OverloadCandidate Candidate = Candidates[I];
847  // We want to avoid showing instantiated signatures, because they may be
848  // long in some cases (e.g. when 'T' is substituted with 'std::string', we
849  // would get 'std::basic_string<char>').
850  if (auto *Func = Candidate.getFunction()) {
851  if (auto *Pattern = Func->getTemplateInstantiationPattern())
852  Candidate = OverloadCandidate(Pattern);
853  }
854 
855  const auto *CCS = Candidate.CreateSignatureString(
856  CurrentArg, S, *Allocator, CCTUInfo, true);
857  assert(CCS && "Expected the CodeCompletionString to be non-null");
858  ScoredSignatures.push_back(processOverloadCandidate(
859  Candidate, *CCS,
860  Candidate.getFunction()
861  ? getDeclComment(S.getASTContext(), *Candidate.getFunction())
862  : ""));
863  }
864 
865  // Sema does not load the docs from the preamble, so we need to fetch extra
866  // docs from the index instead.
867  llvm::DenseMap<SymbolID, std::string> FetchedDocs;
868  if (Index) {
869  LookupRequest IndexRequest;
870  for (const auto &S : ScoredSignatures) {
871  if (!S.IDForDoc)
872  continue;
873  IndexRequest.IDs.insert(*S.IDForDoc);
874  }
875  Index->lookup(IndexRequest, [&](const Symbol &S) {
876  if (!S.Documentation.empty())
877  FetchedDocs[S.ID] = S.Documentation;
878  });
879  log("SigHelp: requested docs for {0} symbols from the index, got {1} "
880  "symbols with non-empty docs in the response",
881  IndexRequest.IDs.size(), FetchedDocs.size());
882  }
883 
884  llvm::sort(ScoredSignatures, [](const ScoredSignature &L,
885  const ScoredSignature &R) {
886  // Ordering follows:
887  // - Less number of parameters is better.
888  // - Function is better than FunctionType which is better than
889  // Function Template.
890  // - High score is better.
891  // - Shorter signature is better.
892  // - Alphebatically smaller is better.
893  if (L.Quality.NumberOfParameters != R.Quality.NumberOfParameters)
894  return L.Quality.NumberOfParameters < R.Quality.NumberOfParameters;
895  if (L.Quality.NumberOfOptionalParameters !=
896  R.Quality.NumberOfOptionalParameters)
897  return L.Quality.NumberOfOptionalParameters <
898  R.Quality.NumberOfOptionalParameters;
899  if (L.Quality.Kind != R.Quality.Kind) {
900  using OC = CodeCompleteConsumer::OverloadCandidate;
901  switch (L.Quality.Kind) {
902  case OC::CK_Function:
903  return true;
904  case OC::CK_FunctionType:
905  return R.Quality.Kind != OC::CK_Function;
906  case OC::CK_FunctionTemplate:
907  return false;
908  }
909  llvm_unreachable("Unknown overload candidate type.");
910  }
911  if (L.Signature.label.size() != R.Signature.label.size())
912  return L.Signature.label.size() < R.Signature.label.size();
913  return L.Signature.label < R.Signature.label;
914  });
915 
916  for (auto &SS : ScoredSignatures) {
917  auto IndexDocIt =
918  SS.IDForDoc ? FetchedDocs.find(*SS.IDForDoc) : FetchedDocs.end();
919  if (IndexDocIt != FetchedDocs.end())
920  SS.Signature.documentation = IndexDocIt->second;
921 
922  SigHelp.signatures.push_back(std::move(SS.Signature));
923  }
924  }
925 
926  GlobalCodeCompletionAllocator &getAllocator() override { return *Allocator; }
927 
928  CodeCompletionTUInfo &getCodeCompletionTUInfo() override { return CCTUInfo; }
929 
930 private:
931  // FIXME(ioeric): consider moving CodeCompletionString logic here to
932  // CompletionString.h.
933  ScoredSignature processOverloadCandidate(const OverloadCandidate &Candidate,
934  const CodeCompletionString &CCS,
935  llvm::StringRef DocComment) const {
936  SignatureInformation Signature;
937  SignatureQualitySignals Signal;
938  const char *ReturnType = nullptr;
939 
940  Signature.documentation = formatDocumentation(CCS, DocComment);
941  Signal.Kind = Candidate.getKind();
942 
943  for (const auto &Chunk : CCS) {
944  switch (Chunk.Kind) {
945  case CodeCompletionString::CK_ResultType:
946  // A piece of text that describes the type of an entity or,
947  // for functions and methods, the return type.
948  assert(!ReturnType && "Unexpected CK_ResultType");
949  ReturnType = Chunk.Text;
950  break;
951  case CodeCompletionString::CK_Placeholder:
952  // A string that acts as a placeholder for, e.g., a function call
953  // argument.
954  // Intentional fallthrough here.
955  case CodeCompletionString::CK_CurrentParameter: {
956  // A piece of text that describes the parameter that corresponds to
957  // the code-completion location within a function call, message send,
958  // macro invocation, etc.
959  Signature.label += Chunk.Text;
960  ParameterInformation Info;
961  Info.label = Chunk.Text;
962  Signature.parameters.push_back(std::move(Info));
963  Signal.NumberOfParameters++;
964  Signal.ContainsActiveParameter = true;
965  break;
966  }
967  case CodeCompletionString::CK_Optional: {
968  // The rest of the parameters are defaulted/optional.
969  assert(Chunk.Optional &&
970  "Expected the optional code completion string to be non-null.");
971  Signature.label += getOptionalParameters(*Chunk.Optional,
972  Signature.parameters, Signal);
973  break;
974  }
975  case CodeCompletionString::CK_VerticalSpace:
976  break;
977  default:
978  Signature.label += Chunk.Text;
979  break;
980  }
981  }
982  if (ReturnType) {
983  Signature.label += " -> ";
984  Signature.label += ReturnType;
985  }
986  dlog("Signal for {0}: {1}", Signature, Signal);
987  ScoredSignature Result;
988  Result.Signature = std::move(Signature);
989  Result.Quality = Signal;
990  Result.IDForDoc =
991  Result.Signature.documentation.empty() && Candidate.getFunction()
992  ? clangd::getSymbolID(Candidate.getFunction())
993  : None;
994  return Result;
995  }
996 
997  SignatureHelp &SigHelp;
998  std::shared_ptr<clang::GlobalCodeCompletionAllocator> Allocator;
999  CodeCompletionTUInfo CCTUInfo;
1000  const SymbolIndex *Index;
1001 }; // SignatureHelpCollector
1002 
1003 struct SemaCompleteInput {
1005  const tooling::CompileCommand &Command;
1006  const PreambleData *Preamble;
1007  llvm::StringRef Contents;
1008  Position Pos;
1009  llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS;
1010  std::shared_ptr<PCHContainerOperations> PCHs;
1011 };
1012 
1013 // Invokes Sema code completion on a file.
1014 // If \p Includes is set, it will be updated based on the compiler invocation.
1015 bool semaCodeComplete(std::unique_ptr<CodeCompleteConsumer> Consumer,
1016  const clang::CodeCompleteOptions &Options,
1017  const SemaCompleteInput &Input,
1018  IncludeStructure *Includes = nullptr) {
1019  trace::Span Tracer("Sema completion");
1020  std::vector<const char *> ArgStrs;
1021  for (const auto &S : Input.Command.CommandLine)
1022  ArgStrs.push_back(S.c_str());
1023 
1024  if (Input.VFS->setCurrentWorkingDirectory(Input.Command.Directory)) {
1025  log("Couldn't set working directory");
1026  // We run parsing anyway, our lit-tests rely on results for non-existing
1027  // working dirs.
1028  }
1029 
1030  llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS = Input.VFS;
1031  if (Input.Preamble && Input.Preamble->StatCache)
1032  VFS = Input.Preamble->StatCache->getConsumingFS(std::move(VFS));
1033  IgnoreDiagnostics DummyDiagsConsumer;
1034  auto CI = createInvocationFromCommandLine(
1035  ArgStrs,
1036  CompilerInstance::createDiagnostics(new DiagnosticOptions,
1037  &DummyDiagsConsumer, false),
1038  VFS);
1039  if (!CI) {
1040  elog("Couldn't create CompilerInvocation");
1041  return false;
1042  }
1043  auto &FrontendOpts = CI->getFrontendOpts();
1044  FrontendOpts.DisableFree = false;
1045  FrontendOpts.SkipFunctionBodies = true;
1046  CI->getLangOpts()->CommentOpts.ParseAllComments = true;
1047  // Disable typo correction in Sema.
1048  CI->getLangOpts()->SpellChecking = false;
1049  // Setup code completion.
1050  FrontendOpts.CodeCompleteOpts = Options;
1051  FrontendOpts.CodeCompletionAt.FileName = Input.FileName;
1052  auto Offset = positionToOffset(Input.Contents, Input.Pos);
1053  if (!Offset) {
1054  elog("Code completion position was invalid {0}", Offset.takeError());
1055  return false;
1056  }
1057  std::tie(FrontendOpts.CodeCompletionAt.Line,
1058  FrontendOpts.CodeCompletionAt.Column) =
1059  offsetToClangLineColumn(Input.Contents, *Offset);
1060 
1061  std::unique_ptr<llvm::MemoryBuffer> ContentsBuffer =
1062  llvm::MemoryBuffer::getMemBufferCopy(Input.Contents, Input.FileName);
1063  // The diagnostic options must be set before creating a CompilerInstance.
1064  CI->getDiagnosticOpts().IgnoreWarnings = true;
1065  // We reuse the preamble whether it's valid or not. This is a
1066  // correctness/performance tradeoff: building without a preamble is slow, and
1067  // completion is latency-sensitive.
1068  // However, if we're completing *inside* the preamble section of the draft,
1069  // overriding the preamble will break sema completion. Fortunately we can just
1070  // skip all includes in this case; these completions are really simple.
1071  bool CompletingInPreamble =
1072  ComputePreambleBounds(*CI->getLangOpts(), ContentsBuffer.get(), 0).Size >
1073  *Offset;
1074  // NOTE: we must call BeginSourceFile after prepareCompilerInstance. Otherwise
1075  // the remapped buffers do not get freed.
1076  auto Clang = prepareCompilerInstance(
1077  std::move(CI),
1078  (Input.Preamble && !CompletingInPreamble) ? &Input.Preamble->Preamble
1079  : nullptr,
1080  std::move(ContentsBuffer), std::move(Input.PCHs), std::move(VFS),
1081  DummyDiagsConsumer);
1082  Clang->getPreprocessorOpts().SingleFileParseMode = CompletingInPreamble;
1083  Clang->setCodeCompletionConsumer(Consumer.release());
1084 
1086  if (!Action.BeginSourceFile(*Clang, Clang->getFrontendOpts().Inputs[0])) {
1087  log("BeginSourceFile() failed when running codeComplete for {0}",
1088  Input.FileName);
1089  return false;
1090  }
1091  if (Includes)
1092  Clang->getPreprocessor().addPPCallbacks(
1093  collectIncludeStructureCallback(Clang->getSourceManager(), Includes));
1094  if (!Action.Execute()) {
1095  log("Execute() failed when running codeComplete for {0}", Input.FileName);
1096  return false;
1097  }
1098  Action.EndSourceFile();
1099 
1100  return true;
1101 }
1102 
1103 // Should we allow index completions in the specified context?
1104 bool allowIndex(CodeCompletionContext &CC) {
1105  if (!contextAllowsIndex(CC.getKind()))
1106  return false;
1107  // We also avoid ClassName::bar (but allow namespace::bar).
1108  auto Scope = CC.getCXXScopeSpecifier();
1109  if (!Scope)
1110  return true;
1111  NestedNameSpecifier *NameSpec = (*Scope)->getScopeRep();
1112  if (!NameSpec)
1113  return true;
1114  // We only query the index when qualifier is a namespace.
1115  // If it's a class, we rely solely on sema completions.
1116  switch (NameSpec->getKind()) {
1117  case NestedNameSpecifier::Global:
1119  case NestedNameSpecifier::NamespaceAlias:
1120  return true;
1121  case NestedNameSpecifier::Super:
1122  case NestedNameSpecifier::TypeSpec:
1123  case NestedNameSpecifier::TypeSpecWithTemplate:
1124  // Unresolved inside a template.
1125  case NestedNameSpecifier::Identifier:
1126  return false;
1127  }
1128  llvm_unreachable("invalid NestedNameSpecifier kind");
1129 }
1130 
1131 std::future<SymbolSlab> startAsyncFuzzyFind(const SymbolIndex &Index,
1132  const FuzzyFindRequest &Req) {
1133  return runAsync<SymbolSlab>([&Index, Req]() {
1134  trace::Span Tracer("Async fuzzyFind");
1135  SymbolSlab::Builder Syms;
1136  Index.fuzzyFind(Req, [&Syms](const Symbol &Sym) { Syms.insert(Sym); });
1137  return std::move(Syms).build();
1138  });
1139 }
1140 
1141 // Creates a `FuzzyFindRequest` based on the cached index request from the
1142 // last completion, if any, and the speculated completion filter text in the
1143 // source code.
1144 llvm::Optional<FuzzyFindRequest>
1145 speculativeFuzzyFindRequestForCompletion(FuzzyFindRequest CachedReq,
1146  PathRef File, llvm::StringRef Content,
1147  Position Pos) {
1148  auto Filter = speculateCompletionFilter(Content, Pos);
1149  if (!Filter) {
1150  elog("Failed to speculate filter text for code completion at Pos "
1151  "{0}:{1}: {2}",
1152  Pos.line, Pos.character, Filter.takeError());
1153  return None;
1154  }
1155  CachedReq.Query = *Filter;
1156  return CachedReq;
1157 }
1158 
1159 // Returns the most popular include header for \p Sym. If two headers are
1160 // equally popular, prefer the shorter one. Returns empty string if \p Sym has
1161 // no include header.
1162 llvm::SmallVector<llvm::StringRef, 1> getRankedIncludes(const Symbol &Sym) {
1163  auto Includes = Sym.IncludeHeaders;
1164  // Sort in descending order by reference count and header length.
1165  llvm::sort(Includes, [](const Symbol::IncludeHeaderWithReferences &LHS,
1166  const Symbol::IncludeHeaderWithReferences &RHS) {
1167  if (LHS.References == RHS.References)
1168  return LHS.IncludeHeader.size() < RHS.IncludeHeader.size();
1169  return LHS.References > RHS.References;
1170  });
1171  llvm::SmallVector<llvm::StringRef, 1> Headers;
1172  for (const auto &Include : Includes)
1173  Headers.push_back(Include.IncludeHeader);
1174  return Headers;
1175 }
1176 
1177 // Runs Sema-based (AST) and Index-based completion, returns merged results.
1178 //
1179 // There are a few tricky considerations:
1180 // - the AST provides information needed for the index query (e.g. which
1181 // namespaces to search in). So Sema must start first.
1182 // - we only want to return the top results (Opts.Limit).
1183 // Building CompletionItems for everything else is wasteful, so we want to
1184 // preserve the "native" format until we're done with scoring.
1185 // - the data underlying Sema completion items is owned by the AST and various
1186 // other arenas, which must stay alive for us to build CompletionItems.
1187 // - we may get duplicate results from Sema and the Index, we need to merge.
1188 //
1189 // So we start Sema completion first, and do all our work in its callback.
1190 // We use the Sema context information to query the index.
1191 // Then we merge the two result sets, producing items that are Sema/Index/Both.
1192 // These items are scored, and the top N are synthesized into the LSP response.
1193 // Finally, we can clean up the data structures created by Sema completion.
1194 //
1195 // Main collaborators are:
1196 // - semaCodeComplete sets up the compiler machinery to run code completion.
1197 // - CompletionRecorder captures Sema completion results, including context.
1198 // - SymbolIndex (Opts.Index) provides index completion results as Symbols
1199 // - CompletionCandidates are the result of merging Sema and Index results.
1200 // Each candidate points to an underlying CodeCompletionResult (Sema), a
1201 // Symbol (Index), or both. It computes the result quality score.
1202 // CompletionCandidate also does conversion to CompletionItem (at the end).
1203 // - FuzzyMatcher scores how the candidate matches the partial identifier.
1204 // This score is combined with the result quality score for the final score.
1205 // - TopN determines the results with the best score.
1206 class CodeCompleteFlow {
1207  PathRef FileName;
1208  IncludeStructure Includes; // Complete once the compiler runs.
1209  SpeculativeFuzzyFind *SpecFuzzyFind; // Can be nullptr.
1210  const CodeCompleteOptions &Opts;
1211 
1212  // Sema takes ownership of Recorder. Recorder is valid until Sema cleanup.
1213  CompletionRecorder *Recorder = nullptr;
1214  int NSema = 0, NIndex = 0, NBoth = 0; // Counters for logging.
1215  bool Incomplete = false; // Would more be available with a higher limit?
1216  llvm::Optional<FuzzyMatcher> Filter; // Initialized once Sema runs.
1217  std::vector<std::string> QueryScopes; // Initialized once Sema runs.
1218  // Initialized once QueryScopes is initialized, if there are scopes.
1219  llvm::Optional<ScopeDistance> ScopeProximity;
1220  llvm::Optional<OpaqueType> PreferredType; // Initialized once Sema runs.
1221  // Whether to query symbols from any scope. Initialized once Sema runs.
1222  bool AllScopes = false;
1223  // Include-insertion and proximity scoring rely on the include structure.
1224  // This is available after Sema has run.
1225  llvm::Optional<IncludeInserter> Inserter; // Available during runWithSema.
1226  llvm::Optional<URIDistance> FileProximity; // Initialized once Sema runs.
1227  /// Speculative request based on the cached request and the filter text before
1228  /// the cursor.
1229  /// Initialized right before sema run. This is only set if `SpecFuzzyFind` is
1230  /// set and contains a cached request.
1231  llvm::Optional<FuzzyFindRequest> SpecReq;
1232 
1233 public:
1234  // A CodeCompleteFlow object is only useful for calling run() exactly once.
1235  CodeCompleteFlow(PathRef FileName, const IncludeStructure &Includes,
1236  SpeculativeFuzzyFind *SpecFuzzyFind,
1237  const CodeCompleteOptions &Opts)
1238  : FileName(FileName), Includes(Includes), SpecFuzzyFind(SpecFuzzyFind),
1239  Opts(Opts) {}
1240 
1241  CodeCompleteResult run(const SemaCompleteInput &SemaCCInput) && {
1242  trace::Span Tracer("CodeCompleteFlow");
1243  if (Opts.Index && SpecFuzzyFind && SpecFuzzyFind->CachedReq.hasValue()) {
1244  assert(!SpecFuzzyFind->Result.valid());
1245  if ((SpecReq = speculativeFuzzyFindRequestForCompletion(
1246  *SpecFuzzyFind->CachedReq, SemaCCInput.FileName,
1247  SemaCCInput.Contents, SemaCCInput.Pos)))
1248  SpecFuzzyFind->Result = startAsyncFuzzyFind(*Opts.Index, *SpecReq);
1249  }
1250 
1251  // We run Sema code completion first. It builds an AST and calculates:
1252  // - completion results based on the AST.
1253  // - partial identifier and context. We need these for the index query.
1254  CodeCompleteResult Output;
1255  auto RecorderOwner = llvm::make_unique<CompletionRecorder>(Opts, [&]() {
1256  assert(Recorder && "Recorder is not set");
1257  auto Style =
1258  format::getStyle(format::DefaultFormatStyle, SemaCCInput.FileName,
1259  format::DefaultFallbackStyle, SemaCCInput.Contents,
1260  SemaCCInput.VFS.get());
1261  if (!Style) {
1262  log("getStyle() failed for file {0}: {1}. Fallback is LLVM style.",
1263  SemaCCInput.FileName, Style.takeError());
1264  Style = format::getLLVMStyle();
1265  }
1266  // If preprocessor was run, inclusions from preprocessor callback should
1267  // already be added to Includes.
1268  Inserter.emplace(
1269  SemaCCInput.FileName, SemaCCInput.Contents, *Style,
1270  SemaCCInput.Command.Directory,
1271  Recorder->CCSema->getPreprocessor().getHeaderSearchInfo());
1272  for (const auto &Inc : Includes.MainFileIncludes)
1273  Inserter->addExisting(Inc);
1274 
1275  // Most of the cost of file proximity is in initializing the FileDistance
1276  // structures based on the observed includes, once per query. Conceptually
1277  // that happens here (though the per-URI-scheme initialization is lazy).
1278  // The per-result proximity scoring is (amortized) very cheap.
1279  FileDistanceOptions ProxOpts{}; // Use defaults.
1280  const auto &SM = Recorder->CCSema->getSourceManager();
1281  llvm::StringMap<SourceParams> ProxSources;
1282  for (auto &Entry : Includes.includeDepth(
1283  SM.getFileEntryForID(SM.getMainFileID())->getName())) {
1284  auto &Source = ProxSources[Entry.getKey()];
1285  Source.Cost = Entry.getValue() * ProxOpts.IncludeCost;
1286  // Symbols near our transitive includes are good, but only consider
1287  // things in the same directory or below it. Otherwise there can be
1288  // many false positives.
1289  if (Entry.getValue() > 0)
1290  Source.MaxUpTraversals = 1;
1291  }
1292  FileProximity.emplace(ProxSources, ProxOpts);
1293 
1294  Output = runWithSema();
1295  Inserter.reset(); // Make sure this doesn't out-live Clang.
1296  SPAN_ATTACH(Tracer, "sema_completion_kind",
1297  getCompletionKindString(Recorder->CCContext.getKind()));
1298  log("Code complete: sema context {0}, query scopes [{1}] (AnyScope={2}), "
1299  "expected type {3}",
1300  getCompletionKindString(Recorder->CCContext.getKind()),
1301  llvm::join(QueryScopes.begin(), QueryScopes.end(), ","), AllScopes,
1302  PreferredType ? Recorder->CCContext.getPreferredType().getAsString()
1303  : "<none>");
1304  });
1305 
1306  Recorder = RecorderOwner.get();
1307 
1308  semaCodeComplete(std::move(RecorderOwner), Opts.getClangCompleteOpts(),
1309  SemaCCInput, &Includes);
1310 
1311  SPAN_ATTACH(Tracer, "sema_results", NSema);
1312  SPAN_ATTACH(Tracer, "index_results", NIndex);
1313  SPAN_ATTACH(Tracer, "merged_results", NBoth);
1314  SPAN_ATTACH(Tracer, "returned_results", int64_t(Output.Completions.size()));
1315  SPAN_ATTACH(Tracer, "incomplete", Output.HasMore);
1316  log("Code complete: {0} results from Sema, {1} from Index, "
1317  "{2} matched, {3} returned{4}.",
1318  NSema, NIndex, NBoth, Output.Completions.size(),
1319  Output.HasMore ? " (incomplete)" : "");
1320  assert(!Opts.Limit || Output.Completions.size() <= Opts.Limit);
1321  // We don't assert that isIncomplete means we hit a limit.
1322  // Indexes may choose to impose their own limits even if we don't have one.
1323  return Output;
1324  }
1325 
1326 private:
1327  // This is called by run() once Sema code completion is done, but before the
1328  // Sema data structures are torn down. It does all the real work.
1329  CodeCompleteResult runWithSema() {
1330  const auto &CodeCompletionRange = CharSourceRange::getCharRange(
1331  Recorder->CCSema->getPreprocessor().getCodeCompletionTokenRange());
1332  Range TextEditRange;
1333  // When we are getting completions with an empty identifier, for example
1334  // std::vector<int> asdf;
1335  // asdf.^;
1336  // Then the range will be invalid and we will be doing insertion, use
1337  // current cursor position in such cases as range.
1338  if (CodeCompletionRange.isValid()) {
1339  TextEditRange = halfOpenToRange(Recorder->CCSema->getSourceManager(),
1340  CodeCompletionRange);
1341  } else {
1342  const auto &Pos = sourceLocToPosition(
1343  Recorder->CCSema->getSourceManager(),
1344  Recorder->CCSema->getPreprocessor().getCodeCompletionLoc());
1345  TextEditRange.start = TextEditRange.end = Pos;
1346  }
1347  Filter = FuzzyMatcher(
1348  Recorder->CCSema->getPreprocessor().getCodeCompletionFilter());
1349  std::tie(QueryScopes, AllScopes) =
1350  getQueryScopes(Recorder->CCContext, *Recorder->CCSema, Opts);
1351  if (!QueryScopes.empty())
1352  ScopeProximity.emplace(QueryScopes);
1353  PreferredType =
1354  OpaqueType::fromType(Recorder->CCSema->getASTContext(),
1355  Recorder->CCContext.getPreferredType());
1356  // Sema provides the needed context to query the index.
1357  // FIXME: in addition to querying for extra/overlapping symbols, we should
1358  // explicitly request symbols corresponding to Sema results.
1359  // We can use their signals even if the index can't suggest them.
1360  // We must copy index results to preserve them, but there are at most Limit.
1361  auto IndexResults = (Opts.Index && allowIndex(Recorder->CCContext))
1362  ? queryIndex()
1363  : SymbolSlab();
1364  trace::Span Tracer("Populate CodeCompleteResult");
1365  // Merge Sema and Index results, score them, and pick the winners.
1366  auto Top = mergeResults(Recorder->Results, IndexResults);
1367  CodeCompleteResult Output;
1368 
1369  // Convert the results to final form, assembling the expensive strings.
1370  for (auto &C : Top) {
1371  Output.Completions.push_back(toCodeCompletion(C.first));
1372  Output.Completions.back().Score = C.second;
1373  Output.Completions.back().CompletionTokenRange = TextEditRange;
1374  }
1375  Output.HasMore = Incomplete;
1376  Output.Context = Recorder->CCContext.getKind();
1377 
1378  return Output;
1379  }
1380 
1381  SymbolSlab queryIndex() {
1382  trace::Span Tracer("Query index");
1383  SPAN_ATTACH(Tracer, "limit", int64_t(Opts.Limit));
1384 
1385  // Build the query.
1386  FuzzyFindRequest Req;
1387  if (Opts.Limit)
1388  Req.Limit = Opts.Limit;
1389  Req.Query = Filter->pattern();
1390  Req.RestrictForCodeCompletion = true;
1391  Req.Scopes = QueryScopes;
1392  Req.AnyScope = AllScopes;
1393  // FIXME: we should send multiple weighted paths here.
1394  Req.ProximityPaths.push_back(FileName);
1395  vlog("Code complete: fuzzyFind({0:2})", toJSON(Req));
1396 
1397  if (SpecFuzzyFind)
1398  SpecFuzzyFind->NewReq = Req;
1399  if (SpecFuzzyFind && SpecFuzzyFind->Result.valid() && (*SpecReq == Req)) {
1400  vlog("Code complete: speculative fuzzy request matches the actual index "
1401  "request. Waiting for the speculative index results.");
1402  SPAN_ATTACH(Tracer, "Speculative results", true);
1403 
1404  trace::Span WaitSpec("Wait speculative results");
1405  return SpecFuzzyFind->Result.get();
1406  }
1407 
1408  SPAN_ATTACH(Tracer, "Speculative results", false);
1409 
1410  // Run the query against the index.
1411  SymbolSlab::Builder ResultsBuilder;
1412  if (Opts.Index->fuzzyFind(
1413  Req, [&](const Symbol &Sym) { ResultsBuilder.insert(Sym); }))
1414  Incomplete = true;
1415  return std::move(ResultsBuilder).build();
1416  }
1417 
1418  // Merges Sema and Index results where possible, to form CompletionCandidates.
1419  // Groups overloads if desired, to form CompletionCandidate::Bundles. The
1420  // bundles are scored and top results are returned, best to worst.
1421  std::vector<ScoredBundle>
1422  mergeResults(const std::vector<CodeCompletionResult> &SemaResults,
1423  const SymbolSlab &IndexResults) {
1424  trace::Span Tracer("Merge and score results");
1425  std::vector<CompletionCandidate::Bundle> Bundles;
1426  llvm::DenseMap<size_t, size_t> BundleLookup;
1427  auto AddToBundles = [&](const CodeCompletionResult *SemaResult,
1428  const Symbol *IndexResult) {
1429  CompletionCandidate C;
1430  C.SemaResult = SemaResult;
1431  C.IndexResult = IndexResult;
1432  if (C.IndexResult)
1433  C.RankedIncludeHeaders = getRankedIncludes(*C.IndexResult);
1434  C.Name = IndexResult ? IndexResult->Name : Recorder->getName(*SemaResult);
1435  if (auto OverloadSet = Opts.BundleOverloads ? C.overloadSet() : 0) {
1436  auto Ret = BundleLookup.try_emplace(OverloadSet, Bundles.size());
1437  if (Ret.second)
1438  Bundles.emplace_back();
1439  Bundles[Ret.first->second].push_back(std::move(C));
1440  } else {
1441  Bundles.emplace_back();
1442  Bundles.back().push_back(std::move(C));
1443  }
1444  };
1445  llvm::DenseSet<const Symbol *> UsedIndexResults;
1446  auto CorrespondingIndexResult =
1447  [&](const CodeCompletionResult &SemaResult) -> const Symbol * {
1448  if (auto SymID =
1449  getSymbolID(SemaResult, Recorder->CCSema->getSourceManager())) {
1450  auto I = IndexResults.find(*SymID);
1451  if (I != IndexResults.end()) {
1452  UsedIndexResults.insert(&*I);
1453  return &*I;
1454  }
1455  }
1456  return nullptr;
1457  };
1458  // Emit all Sema results, merging them with Index results if possible.
1459  for (auto &SemaResult : Recorder->Results)
1460  AddToBundles(&SemaResult, CorrespondingIndexResult(SemaResult));
1461  // Now emit any Index-only results.
1462  for (const auto &IndexResult : IndexResults) {
1463  if (UsedIndexResults.count(&IndexResult))
1464  continue;
1465  AddToBundles(/*SemaResult=*/nullptr, &IndexResult);
1466  }
1467  // We only keep the best N results at any time, in "native" format.
1468  TopN<ScoredBundle, ScoredBundleGreater> Top(
1469  Opts.Limit == 0 ? std::numeric_limits<size_t>::max() : Opts.Limit);
1470  for (auto &Bundle : Bundles)
1471  addCandidate(Top, std::move(Bundle));
1472  return std::move(Top).items();
1473  }
1474 
1475  llvm::Optional<float> fuzzyScore(const CompletionCandidate &C) {
1476  // Macros can be very spammy, so we only support prefix completion.
1477  // We won't end up with underfull index results, as macros are sema-only.
1478  if (C.SemaResult && C.SemaResult->Kind == CodeCompletionResult::RK_Macro &&
1479  !C.Name.startswith_lower(Filter->pattern()))
1480  return None;
1481  return Filter->match(C.Name);
1482  }
1483 
1484  // Scores a candidate and adds it to the TopN structure.
1485  void addCandidate(TopN<ScoredBundle, ScoredBundleGreater> &Candidates,
1486  CompletionCandidate::Bundle Bundle) {
1487  SymbolQualitySignals Quality;
1488  SymbolRelevanceSignals Relevance;
1489  Relevance.Context = Recorder->CCContext.getKind();
1490  Relevance.Query = SymbolRelevanceSignals::CodeComplete;
1491  Relevance.FileProximityMatch = FileProximity.getPointer();
1492  if (ScopeProximity)
1493  Relevance.ScopeProximityMatch = ScopeProximity.getPointer();
1494  if (PreferredType)
1495  Relevance.HadContextType = true;
1496 
1497  auto &First = Bundle.front();
1498  if (auto FuzzyScore = fuzzyScore(First))
1499  Relevance.NameMatch = *FuzzyScore;
1500  else
1501  return;
1503  bool FromIndex = false;
1504  for (const auto &Candidate : Bundle) {
1505  if (Candidate.IndexResult) {
1506  Quality.merge(*Candidate.IndexResult);
1507  Relevance.merge(*Candidate.IndexResult);
1508  Origin |= Candidate.IndexResult->Origin;
1509  FromIndex = true;
1510  if (!Candidate.IndexResult->Type.empty())
1511  Relevance.HadSymbolType |= true;
1512  if (PreferredType &&
1513  PreferredType->raw() == Candidate.IndexResult->Type) {
1514  Relevance.TypeMatchesPreferred = true;
1515  }
1516  }
1517  if (Candidate.SemaResult) {
1518  Quality.merge(*Candidate.SemaResult);
1519  Relevance.merge(*Candidate.SemaResult);
1520  if (PreferredType) {
1521  if (auto CompletionType = OpaqueType::fromCompletionResult(
1522  Recorder->CCSema->getASTContext(), *Candidate.SemaResult)) {
1523  Relevance.HadSymbolType |= true;
1524  if (PreferredType == CompletionType)
1525  Relevance.TypeMatchesPreferred = true;
1526  }
1527  }
1528  Origin |= SymbolOrigin::AST;
1529  }
1530  }
1531 
1532  CodeCompletion::Scores Scores;
1533  Scores.Quality = Quality.evaluate();
1534  Scores.Relevance = Relevance.evaluate();
1535  Scores.Total = evaluateSymbolAndRelevance(Scores.Quality, Scores.Relevance);
1536  // NameMatch is in fact a multiplier on total score, so rescoring is sound.
1537  Scores.ExcludingName = Relevance.NameMatch
1538  ? Scores.Total / Relevance.NameMatch
1539  : Scores.Quality;
1540 
1541  dlog("CodeComplete: {0} ({1}) = {2}\n{3}{4}\n", First.Name,
1542  llvm::to_string(Origin), Scores.Total, llvm::to_string(Quality),
1543  llvm::to_string(Relevance));
1544 
1545  NSema += bool(Origin & SymbolOrigin::AST);
1546  NIndex += FromIndex;
1547  NBoth += bool(Origin & SymbolOrigin::AST) && FromIndex;
1548  if (Candidates.push({std::move(Bundle), Scores}))
1549  Incomplete = true;
1550  }
1551 
1552  CodeCompletion toCodeCompletion(const CompletionCandidate::Bundle &Bundle) {
1553  llvm::Optional<CodeCompletionBuilder> Builder;
1554  for (const auto &Item : Bundle) {
1555  CodeCompletionString *SemaCCS =
1556  Item.SemaResult ? Recorder->codeCompletionString(*Item.SemaResult)
1557  : nullptr;
1558  if (!Builder)
1559  Builder.emplace(Recorder->CCSema->getASTContext(), Item, SemaCCS,
1560  QueryScopes, *Inserter, FileName,
1561  Recorder->CCContext.getKind(), Opts);
1562  else
1563  Builder->add(Item, SemaCCS);
1564  }
1565  return Builder->build();
1566  }
1567 };
1568 
1569 } // namespace
1570 
1571 clang::CodeCompleteOptions CodeCompleteOptions::getClangCompleteOpts() const {
1572  clang::CodeCompleteOptions Result;
1573  Result.IncludeCodePatterns = EnableSnippets && IncludeCodePatterns;
1574  Result.IncludeMacros = IncludeMacros;
1575  Result.IncludeGlobals = true;
1576  // We choose to include full comments and not do doxygen parsing in
1577  // completion.
1578  // FIXME: ideally, we should support doxygen in some form, e.g. do markdown
1579  // formatting of the comments.
1580  Result.IncludeBriefComments = false;
1581 
1582  // When an is used, Sema is responsible for completing the main file,
1583  // the index can provide results from the preamble.
1584  // Tell Sema not to deserialize the preamble to look for results.
1585  Result.LoadExternal = !Index;
1586  Result.IncludeFixIts = IncludeFixIts;
1587 
1588  return Result;
1589 }
1590 
1591 llvm::Expected<llvm::StringRef>
1592 speculateCompletionFilter(llvm::StringRef Content, Position Pos) {
1593  auto Offset = positionToOffset(Content, Pos);
1594  if (!Offset)
1595  return llvm::make_error<llvm::StringError>(
1596  "Failed to convert position to offset in content.",
1597  llvm::inconvertibleErrorCode());
1598  if (*Offset == 0)
1599  return "";
1600 
1601  // Start from the character before the cursor.
1602  int St = *Offset - 1;
1603  // FIXME(ioeric): consider UTF characters?
1604  auto IsValidIdentifierChar = [](char c) {
1605  return ((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') ||
1606  (c >= '0' && c <= '9') || (c == '_'));
1607  };
1608  size_t Len = 0;
1609  for (; (St >= 0) && IsValidIdentifierChar(Content[St]); --St, ++Len) {
1610  }
1611  if (Len > 0)
1612  St++; // Shift to the first valid character.
1613  return Content.substr(St, Len);
1614 }
1615 
1617 codeComplete(PathRef FileName, const tooling::CompileCommand &Command,
1618  const PreambleData *Preamble, llvm::StringRef Contents,
1619  Position Pos, llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS,
1620  std::shared_ptr<PCHContainerOperations> PCHs,
1621  CodeCompleteOptions Opts, SpeculativeFuzzyFind *SpecFuzzyFind) {
1622  return CodeCompleteFlow(FileName,
1623  Preamble ? Preamble->Includes : IncludeStructure(),
1624  SpecFuzzyFind, Opts)
1625  .run({FileName, Command, Preamble, Contents, Pos, VFS, PCHs});
1626 }
1627 
1629  const tooling::CompileCommand &Command,
1630  const PreambleData *Preamble,
1631  llvm::StringRef Contents, Position Pos,
1632  llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS,
1633  std::shared_ptr<PCHContainerOperations> PCHs,
1634  const SymbolIndex *Index) {
1636  clang::CodeCompleteOptions Options;
1637  Options.IncludeGlobals = false;
1638  Options.IncludeMacros = false;
1639  Options.IncludeCodePatterns = false;
1640  Options.IncludeBriefComments = false;
1641  IncludeStructure PreambleInclusions; // Unused for signatureHelp
1642  semaCodeComplete(
1643  llvm::make_unique<SignatureHelpCollector>(Options, Index, Result),
1644  Options,
1645  {FileName, Command, Preamble, Contents, Pos, std::move(VFS),
1646  std::move(PCHs)});
1647  return Result;
1648 }
1649 
1650 bool isIndexedForCodeCompletion(const NamedDecl &ND, ASTContext &ASTCtx) {
1651  auto InTopLevelScope = [](const NamedDecl &ND) {
1652  switch (ND.getDeclContext()->getDeclKind()) {
1653  case Decl::TranslationUnit:
1654  case Decl::Namespace:
1655  case Decl::LinkageSpec:
1656  return true;
1657  default:
1658  break;
1659  };
1660  return false;
1661  };
1662  if (InTopLevelScope(ND))
1663  return true;
1664 
1665  if (const auto *EnumDecl = dyn_cast<clang::EnumDecl>(ND.getDeclContext()))
1666  return InTopLevelScope(*EnumDecl) && !EnumDecl->isScoped();
1667 
1668  return false;
1669 }
1670 
1672  CompletionItem LSP;
1673  const auto *InsertInclude = Includes.empty() ? nullptr : &Includes[0];
1674  LSP.label = ((InsertInclude && InsertInclude->Insertion)
1675  ? Opts.IncludeIndicator.Insert
1676  : Opts.IncludeIndicator.NoInsert) +
1677  (Opts.ShowOrigins ? "[" + llvm::to_string(Origin) + "]" : "") +
1678  RequiredQualifier + Name + Signature;
1679 
1680  LSP.kind = Kind;
1681  LSP.detail = BundleSize > 1 ? llvm::formatv("[{0} overloads]", BundleSize)
1682  : ReturnType;
1683  LSP.deprecated = Deprecated;
1684  if (InsertInclude)
1685  LSP.detail += "\n" + InsertInclude->Header;
1686  LSP.documentation = Documentation;
1687  LSP.sortText = sortText(Score.Total, Name);
1688  LSP.filterText = Name;
1689  LSP.textEdit = {CompletionTokenRange, RequiredQualifier + Name};
1690  // Merge continuous additionalTextEdits into main edit. The main motivation
1691  // behind this is to help LSP clients, it seems most of them are confused when
1692  // they are provided with additionalTextEdits that are consecutive to main
1693  // edit.
1694  // Note that we store additional text edits from back to front in a line. That
1695  // is mainly to help LSP clients again, so that changes do not effect each
1696  // other.
1697  for (const auto &FixIt : FixIts) {
1698  if (IsRangeConsecutive(FixIt.range, LSP.textEdit->range)) {
1699  LSP.textEdit->newText = FixIt.newText + LSP.textEdit->newText;
1700  LSP.textEdit->range.start = FixIt.range.start;
1701  } else {
1702  LSP.additionalTextEdits.push_back(FixIt);
1703  }
1704  }
1705  if (Opts.EnableSnippets)
1706  LSP.textEdit->newText += SnippetSuffix;
1707 
1708  // FIXME(kadircet): Do not even fill insertText after making sure textEdit is
1709  // compatible with most of the editors.
1710  LSP.insertText = LSP.textEdit->newText;
1713  if (InsertInclude && InsertInclude->Insertion)
1714  LSP.additionalTextEdits.push_back(*InsertInclude->Insertion);
1715 
1716  return LSP;
1717 }
1718 
1719 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, const CodeCompletion &C) {
1720  // For now just lean on CompletionItem.
1721  return OS << C.render(CodeCompleteOptions());
1722 }
1723 
1724 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS,
1725  const CodeCompleteResult &R) {
1726  OS << "CodeCompleteResult: " << R.Completions.size() << (R.HasMore ? "+" : "")
1727  << " (" << getCompletionKindString(R.Context) << ")"
1728  << " items:\n";
1729  for (const auto &C : R.Completions)
1730  OS << C << "\n";
1731  return OS;
1732 }
1733 
1734 } // namespace clangd
1735 } // namespace clang
std::string insertText
A string that should be inserted to a document when selecting this completion.
Definition: Protocol.h:868
std::vector< std::string > AccessibleScopes
Sema * CCSema
llvm::StringRef Name
bool ShowOrigins
Expose origins of completion items in the label (for debugging).
Definition: CodeComplete.h:79
SignatureHelp signatureHelp(PathRef FileName, const tooling::CompileCommand &Command, const PreambleData *Preamble, llvm::StringRef Contents, Position Pos, llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS, std::shared_ptr< PCHContainerOperations > PCHs, const SymbolIndex *Index)
const tooling::CompileCommand & Command
CodeCompleteResult codeComplete(PathRef FileName, const tooling::CompileCommand &Command, const PreambleData *Preamble, llvm::StringRef Contents, Position Pos, llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS, std::shared_ptr< PCHContainerOperations > PCHs, CodeCompleteOptions Opts, SpeculativeFuzzyFind *SpecFuzzyFind)
SignatureQualitySignals Quality
llvm::json::Value toJSON(const FuzzyFindRequest &Request)
Definition: Index.cpp:189
CodeCompletionContext::Kind Context
Definition: CodeComplete.h:198
std::string printQualifiedName(const NamedDecl &ND)
Returns the qualified name of ND.
Definition: AST.cpp:54
llvm::Optional< TextEdit > textEdit
An edit which is applied to a document when selecting this completion.
Definition: Protocol.h:879
llvm::StringRef Contents
llvm::Optional< SymbolID > getSymbolID(const Decl *D)
Gets the symbol ID for a declaration, if possible.
Definition: AST.cpp:117
static llvm::Optional< OpaqueType > fromType(ASTContext &Ctx, QualType Type)
Construct an instance from a clang::QualType.
llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS
CompletionItemKind kind
The kind of this completion item.
Definition: Protocol.h:849
bool EnableSnippets
When true, completion items will contain expandable code snippets in completion (e.g.
Definition: CodeComplete.h:47
clang::find_all_symbols::SymbolInfo::SymbolKind SymbolKind
Definition: SymbolInfo.cpp:22
std::string printNamespaceScope(const DeclContext &DC)
Returns the first enclosing namespace scope starting from DC.
Definition: AST.cpp:109
std::vector< CodeCompletion > Completions
Definition: CodeComplete.h:196
Interface for symbol indexes that can be used for searching or matching symbols among a set of symbol...
Definition: Index.h:487
bool IsRangeConsecutive(const Range &Left, const Range &Right)
Definition: SourceCode.cpp:235
std::string sortText(float Score, llvm::StringRef Name)
Returns a string that sorts in the same order as (-Score, Tiebreak), for LSP.
Definition: Quality.cpp:452
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:24
llvm::Optional< std::string > UnresolvedQualifier
std::vector< CodeCompletionResult > Results
std::string sortText
A string that should be used when comparing this item with other items.
Definition: Protocol.h:860
std::string getDocComment(const ASTContext &Ctx, const CodeCompletionResult &Result, bool CommentsFromHeaders)
Gets a minimally formatted documentation comment of Result, with comment markers stripped.
Documents should not be synced at all.
llvm::Expected< llvm::StringRef > speculateCompletionFilter(llvm::StringRef Content, Position Pos)
Retrives a speculative code completion filter text before the cursor.
std::string documentation
A human-readable string that represents a doc-comment.
Definition: Protocol.h:856
void vlog(const char *Fmt, Ts &&... Vals)
Definition: Logger.h:68
std::vector< TextEdit > additionalTextEdits
An optional array of additional text edits that are applied when selecting this completion.
Definition: Protocol.h:884
void elog(const char *Fmt, Ts &&... Vals)
Definition: Logger.h:57
static ClangTidyModuleRegistry::Add< AbseilModule > X("abseil-module", "Add Abseil checks.")
CompletionItemKind
The kind of a completion entry.
Definition: Protocol.h:259
std::string getReturnType(const CodeCompletionString &CCS)
Gets detail to be used as the detail field in an LSP completion item.
BindArgumentKind Kind
std::string detail
A human-readable string with additional information about this item, like type or symbol information...
Definition: Protocol.h:853
std::pair< size_t, size_t > offsetToClangLineColumn(llvm::StringRef Code, size_t Offset)
Definition: SourceCode.cpp:153
std::vector< SymbolDetails > getSymbolInfo(ParsedAST &AST, Position Pos)
Get info about symbols at Pos.
Definition: XRefs.cpp:765
TextEdit toTextEdit(const FixItHint &FixIt, const SourceManager &M, const LangOptions &L)
Definition: SourceCode.cpp:226
bool isIndexedForCodeCompletion(const NamedDecl &ND, ASTContext &ASTCtx)
std::string filterText
A string that should be used when filtering a set of completion items.
Definition: Protocol.h:864
llvm::Expected< size_t > positionToOffset(llvm::StringRef Code, Position P, bool AllowColumnsBeyondLineLength)
Turn a [line, column] pair into an offset in Code.
Definition: SourceCode.cpp:81
A speculative and asynchronous fuzzy find index request (based on cached request) that can be sent be...
Definition: CodeComplete.h:205
bool deprecated
Indicates if this item is deprecated.
Definition: Protocol.h:887
llvm::unique_function< void()> Action
std::string Signature
void log(const char *Fmt, Ts &&... Vals)
Definition: Logger.h:63
#define dlog(...)
Definition: Logger.h:73
const Decl * D
Definition: XRefs.cpp:79
llvm::Optional< llvm::Expected< tooling::AtomicChanges > > Result
const Symbol * IndexResult
PathRef FileName
std::string formatDocumentation(const CodeCompletionString &CCS, llvm::StringRef DocComment)
Assembles formatted documentation for a completion result.
std::string ReturnType
clang::CodeCompleteOptions getClangCompleteOpts() const
Returns options that can be passed to clang&#39;s completion engine.
std::string SnippetSuffix
Position sourceLocToPosition(const SourceManager &SM, SourceLocation Loc)
Turn a SourceLocation into a [line, column] pair.
Definition: SourceCode.cpp:128
Position Pos
float evaluateSymbolAndRelevance(float SymbolQuality, float SymbolRelevance)
Combine symbol quality and relevance into a single score.
Definition: Quality.cpp:434
FunctionInfo Info
std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &Decl)
Similar to getDocComment, but returns the comment for a NamedDecl.
Represents the signature of a callable.
Definition: Protocol.h:939
void getSignature(const CodeCompletionString &CCS, std::string *Signature, std::string *Snippet, std::string *RequiredQualifiers)
Formats the signature for an item, as a display string and snippet.
const PreambleData * Preamble
std::unique_ptr< PPCallbacks > collectIncludeStructureCallback(const SourceManager &SM, IncludeStructure *Out)
Returns a PPCallback that visits all inclusions in the main file.
Definition: Headers.cpp:78
llvm::SmallVector< llvm::StringRef, 1 > RankedIncludeHeaders
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
std::string label
The label of this completion item.
Definition: Protocol.h:845
CompletionItem render(const CodeCompleteOptions &) const
std::shared_ptr< PCHContainerOperations > PCHs
struct clang::clangd::CodeCompleteOptions::IncludeInsertionIndicator IncludeIndicator
CharSourceRange Range
SourceRange for the file name.
std::pair< llvm::StringRef, llvm::StringRef > splitQualifiedName(llvm::StringRef QName)
From "a::b::c", return {"a::b::", "c"}.
Definition: SourceCode.cpp:164
const CodeCompletionResult * SemaResult
static llvm::Expected< std::string > resolve(const URI &U, llvm::StringRef HintPath="")
Resolves the absolute path of U.
Definition: URI.cpp:224
static llvm::cl::opt< bool > EnableFunctionArgSnippets("function-arg-placeholders", llvm::cl::desc("When disabled, completions contain only parentheses for " "function calls. When enabled, completions also contain " "placeholders for method parameters."), llvm::cl::init(CodeCompleteOptions().EnableFunctionArgSnippets))
llvm::Optional< FixItHint > FixIt
Indicates if the symbol is deprecated.
Definition: Index.h:241
static llvm::Expected< std::string > includeSpelling(const URI &U)
Gets the preferred spelling of this file for #include, if there is one, e.g.
Definition: URI.cpp:252
static llvm::Expected< URI > parse(llvm::StringRef Uri)
Parse a URI string "<scheme>:[//<authority>/]<path>".
Definition: URI.cpp:166
static std::string join(ArrayRef< SpecialMemberFunctionsCheck::SpecialMemberFunctionKind > SMFS, llvm::StringRef AndOr)
IncludeStructure Includes
Definition: ClangdUnit.h:57
llvm::raw_ostream & operator<<(llvm::raw_ostream &OS, const CodeCompletion &C)
std::unique_ptr< CompilerInstance > prepareCompilerInstance(std::unique_ptr< clang::CompilerInvocation > CI, const PrecompiledPreamble *Preamble, std::unique_ptr< llvm::MemoryBuffer > Buffer, std::shared_ptr< PCHContainerOperations > PCHs, llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS, DiagnosticConsumer &DiagsClient)
Definition: Compiler.cpp:44
InsertTextFormat insertTextFormat
The format of the insert text.
Definition: Protocol.h:872
bool isLiteralInclude(llvm::StringRef Include)
Returns true if Include is literal include like "path" or <path>.
Definition: Headers.cpp:68
CodeCompletionContext CCContext
#define SPAN_ATTACH(S, Name, Expr)
Attach a key-value pair to a Span event.
Definition: Trace.h:99
llvm::Optional< SymbolID > IDForDoc
static llvm::Optional< OpaqueType > fromCompletionResult(ASTContext &Ctx, const CodeCompletionResult &R)
Create a type from a code completion result.
Range halfOpenToRange(const SourceManager &SM, CharSourceRange R)
Definition: SourceCode.cpp:145
const SymbolIndex * Index
Definition: Dexp.cpp:85