[clangd] Add Revision field to Symbol.

[sammccall]

Discussed offline a bit: it's not clear that this field is going to be generally useful - we don't have a plan to read this from open-source code.
(Google's internal index wants to be able to individually version symbols for distributed-system reasons, but we can add these version numbers when we convert to protobuf).

clangd/global-symbol-builder/GlobalSymbolBuilderMain.cpp

clang::FrontendAction *create() override {
     };
 
     index::IndexingOptions IndexOpts;
     IndexOpts.SystemSymbolFilter =
         index::IndexingOptions::SystemSymbolFilterKind::All;
     IndexOpts.IndexFunctionLocals = false;
     auto CollectorOpts = SymbolCollector::Options();
     CollectorOpts.FallbackDir = AssumedHeaderDir;
+    CollectorOpts.Revision = Ctx->getRevision();
     return new WrappedIndexAction(
         std::make_shared<SymbolCollector>(std::move(CollectorOpts)), IndexOpts,
         Ctx);
   }
 
   tooling::ExecutionContext *Ctx;
 };
 

clangd/index/Index.h

struct Symbol {
   //
   // A C++ symbol could have multiple declarations and one definition (e.g.
   // a function is declared in ".h" file, and is defined in ".cc" file).
   //   * For classes, the canonical declaration is usually definition.
   //   * For non-inline functions, the canonical declaration is a declaration
   //     (not a definition), which is usually declared in ".h" file.
   SymbolLocation CanonicalDeclaration;
 
+  // The source control symbol's revision number from which the symbol is
+  // indexed.
+  llvm::StringRef Revision;
+
   /// A brief description of the symbol that can be displayed in the completion
   /// candidate list. For example, "Foo(X x, Y y) const" is a labal for a
   /// function.
   llvm::StringRef CompletionLabel;
   /// The piece of text that the user is expected to type to match the
   /// code-completion string, typically a keyword or the name of a declarator or
   /// macro.
   llvm::StringRef CompletionFilterText;

clangd/index/Index.cpp

auto Intern = [&](StringRef &V) {
     }
     V = *R.first;
   };
 
   // We need to copy every StringRef field onto the arena.
   Intern(S.Name);
   Intern(S.Scope);
   Intern(S.CanonicalDeclaration.FilePath);
+  Intern(S.Revision);
 
   Intern(S.CompletionLabel);
   Intern(S.CompletionFilterText);
   Intern(S.CompletionPlainInsertText);
   Intern(S.CompletionSnippetInsertText);
 
   if (S.Detail) {
     // Copy values of StringRefs into arena.

clangd/index/SymbolCollector.h

public:
   struct Options {
     /// Whether to collect symbols in main files (e.g. the source file
     /// corresponding to a TU).
     bool IndexMainFiles = false;
     // When symbol paths cannot be resolved to absolute paths (e.g. files in
     // VFS that does not have absolute path), combine the fallback directory
     // with symbols' paths to get absolute paths. This must be an absolute path.
     std::string FallbackDir;
+    // The source control symbol's revision number on which SymbolCollector
+    // runs.
+    std::string Revision;
   };
 
   SymbolCollector(Options Opts);
 
   void initialize(ASTContext &Ctx) override;
 
   void setPreprocessor(std::shared_ptr<Preprocessor> PP) override {
     this->PP = std::move(PP);

clangd/index/SymbolCollector.cpp

if (const NamedDecl *ND = llvm::dyn_cast<NamedDecl>(D)) {
 
     Symbol S;
     S.ID = std::move(ID);
     std::tie(S.Scope, S.Name) = splitQualifiedName(QName);
     S.SymInfo = index::getSymbolInfo(D);
     std::string FilePath;
     S.CanonicalDeclaration = GetSymbolLocation(ND, SM, Opts.FallbackDir, FilePath);
 
+    S.Revision = Opts.Revision;
+
     // Add completion info.
     assert(ASTCtx && PP.get() && "ASTContext and Preprocessor must be set.");
     CodeCompletionResult SymbolCompletion(ND, 0);
     const auto *CCS = SymbolCompletion.CreateCodeCompletionString(
         *ASTCtx, *PP, CodeCompletionContext::CCC_Name, *CompletionAllocator,
         *CompletionTUInfo,
         /*IncludeBriefComments*/ true);
     std::string Label;

clangd/index/SymbolYAML.cpp

template <> struct MappingTraits<Symbol> {
   static void mapping(IO &IO, Symbol &Sym) {
     MappingNormalization<NormalizedSymbolID, SymbolID> NSymbolID(IO, Sym.ID);
     MappingNormalization<ArenaPtr<Symbol::Details>, const Symbol::Details *>
         NDetail(IO, Sym.Detail);
     IO.mapRequired("ID", NSymbolID->HexString);
     IO.mapRequired("Name", Sym.Name);
     IO.mapRequired("Scope", Sym.Scope);
     IO.mapRequired("SymInfo", Sym.SymInfo);
+    IO.mapRequired("Revision", Sym.Revision);
     IO.mapRequired("CanonicalDeclaration", Sym.CanonicalDeclaration);
     IO.mapRequired("CompletionLabel", Sym.CompletionLabel);
     IO.mapRequired("CompletionFilterText", Sym.CompletionFilterText);
     IO.mapRequired("CompletionPlainInsertText", Sym.CompletionPlainInsertText);
 
     IO.mapOptional("CompletionSnippetInsertText",
                    Sym.CompletionSnippetInsertText);
     IO.mapOptional("Detail", NDetail->Opt);

unittests/clangd/SymbolCollectorTests.cpp

 }
 MATCHER_P(Doc, D, "") { return arg.Detail && arg.Detail->Documentation == D; }
 MATCHER_P(Plain, Text, "") { return arg.CompletionPlainInsertText == Text; }
 MATCHER_P(Snippet, S, "") {
   return arg.CompletionSnippetInsertText == S;
 }
 MATCHER_P(QName, Name, "") { return (arg.Scope + arg.Name).str() == Name; }
 MATCHER_P(CPath, P, "") { return arg.CanonicalDeclaration.FilePath == P; }
+MATCHER_P(Revision, R, "") { return arg.Revision == R; }
 MATCHER_P(LocationOffsets, Offsets, "") {
   // Offset range in SymbolLocation is [start, end] while in Clangd is [start,
   // end).
   return arg.CanonicalDeclaration.StartOffset == Offsets.first &&
       arg.CanonicalDeclaration.EndOffset == Offsets.second - 1;
 }
 
 namespace clang {
EXPECT_THAT(Symbols,
                   {QName("Foo"), QName("f1"), QName("f2"), QName("KInt"),
                    QName("kStr"), QName("foo"), QName("foo::bar"),
                    QName("foo::int32"), QName("foo::int32_t"), QName("foo::v1"),
                    QName("foo::bar::v2"), QName("foo::baz")}));
 }
 
 TEST_F(SymbolCollectorTest, SymbolRelativeNoFallback) {
   CollectorOpts.IndexMainFiles = false;
+  CollectorOpts.Revision = "1234";
   runSymbolCollector("class Foo {};", /*Main=*/"");
   EXPECT_THAT(Symbols,
-              UnorderedElementsAre(AllOf(QName("Foo"), CPath("symbols.h"))));
+              UnorderedElementsAre(AllOf(QName("Foo"), CPath("symbols.h"),
+                                         Revision(CollectorOpts.Revision))));
 }
 
 TEST_F(SymbolCollectorTest, SymbolRelativeWithFallback) {
   CollectorOpts.IndexMainFiles = false;
   CollectorOpts.FallbackDir = getVirtualTestRoot();
   runSymbolCollector("class Foo {};", /*Main=*/"");
   EXPECT_THAT(Symbols,
               UnorderedElementsAre(AllOf(

 Scope:   'clang::'
 SymInfo:
   Kind:            Function
   Lang:            Cpp
 CanonicalDeclaration:
   StartOffset:     0
   EndOffset:       1
   FilePath:        /path/foo.h
+Revision: 1234
 CompletionLabel:    'Foo1-label'
 CompletionFilterText:    'filter'
 CompletionPlainInsertText:    'plain'
 Detail:
   Documentation:    'Foo doc'
   CompletionDetail:    'int'
 ...
 )";
   const std::string YAML2 = R"(
 ---
 ID: 057557CEBF6E6B2DD437FBF60CC58F352D1DF858
 Name:   'Foo2'
 Scope:   'clang::'
 SymInfo:
   Kind:            Function
   Lang:            Cpp
 CanonicalDeclaration:
   StartOffset:     10
   EndOffset:       12
   FilePath:        /path/foo.h
+Revision: 1234
 CompletionLabel:    'Foo2-label'
 CompletionFilterText:    'filter'
 CompletionPlainInsertText:    'plain'
 CompletionSnippetInsertText:    'snippet'
 ...
 )";
 
   auto Symbols1 = SymbolFromYAML(YAML1);
-  EXPECT_THAT(Symbols1, UnorderedElementsAre(
-                            AllOf(QName("clang::Foo1"), Labeled("Foo1-label"),
-                                  Doc("Foo doc"), Detail("int"))));
+  EXPECT_THAT(Symbols1,
+              UnorderedElementsAre(AllOf(QName("clang::Foo1"), Revision("1234"),
+                                         Labeled("Foo1-label"), Doc("Foo doc"),
+                                         Detail("int"))));
   auto Symbols2 = SymbolFromYAML(YAML2);
   EXPECT_THAT(Symbols2, UnorderedElementsAre(AllOf(QName("clang::Foo2"),
+                                                   Revision("1234"),
                                                    Labeled("Foo2-label"),
                                                    Not(HasDetail()))));
 
   std::string ConcatenatedYAML =
       SymbolsToYAML(Symbols1) + SymbolsToYAML(Symbols2);
   auto ConcatenatedSymbols = SymbolFromYAML(ConcatenatedYAML);
   EXPECT_THAT(ConcatenatedSymbols,
               UnorderedElementsAre(QName("clang::Foo1"),
                                    QName("clang::Foo2")));
 }
 
 } // namespace
 } // namespace clangd
 } // namespace clang