[Diagnostics][SourceKit] Expose diagnostic educational notes through SourceKit requests

Author: owenv

test/SourceKit/CompileNotifications/Inputs/descriptive-error.swift

@@ -0,0 +1 @@
+extension (Int, Int) {}

test/SourceKit/CompileNotifications/Inputs/test-docs/nominal-types.md

@@ -0,0 +1,3 @@
+Nominal Types
+-------------
+Nominal types documentation content

test/SourceKit/CompileNotifications/diagnostics.swift

@@ -87,3 +87,42 @@
 // RUN: %sourcekitd-test -req=track-compiles == -req=syntax-map %s | %FileCheck %s -check-prefix=SYNTACTIC
 // SYNTACTIC: key.syntaxmap:
 // SYNTACTIC_NOT: key.notification: source.notification.compile-did-finish
+
+// RUN: %sourcekitd-test -req=track-compiles == -req=sema %S/Inputs/descriptive-error.swift -- -Xfrontend -enable-descriptive-diagnostics -Xfrontend -diagnostic-documentation-path -Xfrontend %S/Inputs/test-docs %S/Inputs/descriptive-error.swift | %FileCheck %s -check-prefix=DESCRIPTIVE
+// DESCRIPTIVE: key.notification: source.notification.compile-did-finish
+// DESCRIPTIVE-NEXT: key.diagnostics: [
+// DESCRIPTIVE-NEXT:   {
+// DESCRIPTIVE-NEXT:     key.line: 1
+// DESCRIPTIVE-NEXT:     key.column: 1
+// DESCRIPTIVE-NEXT:     key.filepath: "{{.*}}descriptive-error.swift"
+// DESCRIPTIVE-NEXT:     key.severity: source.diagnostic.severity.error
+// DESCRIPTIVE-NEXT:     key.description: "non-nominal type
+// DESCRIPTIVE-NEXT:     key.ranges: [
+// DESCRIPTIVE-NEXT:       {
+// DESCRIPTIVE-NEXT:         key.offset: 10,
+// DESCRIPTIVE-NEXT:         key.length: 10
+// DESCRIPTIVE-NEXT:       }
+// DESCRIPTIVE-NEXT:     ],
+// DESCRIPTIVE-NEXT:     key.educational_notes: [
+// DESCRIPTIVE-NEXT:       "Nominal Types\n-------------\nNominal types documentation content\n"
+// DESCRIPTIVE-NEXT:     ]
+// DESCRIPTIVE-NEXT:   }
+// DESCRIPTIVE-NEXT: ],
+
+// RUN: %sourcekitd-test -req=track-compiles == -req=sema %S/Inputs/descriptive-error.swift -- %S/Inputs/descriptive-error.swift | %FileCheck %s -check-prefix=DESCRIPTIVE-DISABLED
+// DESCRIPTIVE-DISABLED: key.notification: source.notification.compile-did-finish
+// DESCRIPTIVE-DISABLED-NEXT: key.diagnostics: [
+// DESCRIPTIVE-DISABLED-NEXT:   {
+// DESCRIPTIVE-DISABLED-NEXT:     key.line: 1
+// DESCRIPTIVE-DISABLED-NEXT:     key.column: 1
+// DESCRIPTIVE-DISABLED-NEXT:     key.filepath: "{{.*}}descriptive-error.swift"
+// DESCRIPTIVE-DISABLED-NEXT:     key.severity: source.diagnostic.severity.error
+// DESCRIPTIVE-DISABLED-NEXT:     key.description: "non-nominal type
+// DESCRIPTIVE-DISABLED-NEXT:     key.ranges: [
+// DESCRIPTIVE-DISABLED-NEXT:       {
+// DESCRIPTIVE-DISABLED-NEXT:         key.offset: 10,
+// DESCRIPTIVE-DISABLED-NEXT:         key.length: 10
+// DESCRIPTIVE-DISABLED-NEXT:       }
+// DESCRIPTIVE-DISABLED-NEXT:     ]
+// DESCRIPTIVE-DISABLED-NEXT:   }
+// DESCRIPTIVE-DISABLED-NEXT: ],

tools/SourceKit/docs/Protocol.md

@@ -418,6 +418,7 @@ of diagnostic entries. A diagnostic entry has this format:
     [opts] <key.fixits>:    (array) [fixit+] // one or more entries for fixits
     [opts] <key.ranges>:    (array) [range+] // one or more entries for ranges
     [opts] <key.diagnostics>: (array) [diagnostic+] // one or more sub-diagnostic entries
+    [opts] <key.educational_notes>: (array) [string+] // one or more educational notes, fomatted as Markdown
 }
 ```
 

tools/SourceKit/include/SourceKit/Core/LangSupport.h

@@ -202,6 +202,7 @@ struct DiagnosticEntryInfoBase {
   std::string Filename;
   SmallVector<std::pair<unsigned, unsigned>, 2> Ranges;
   SmallVector<Fixit, 2> Fixits;
+  SmallVector<std::string, 1> EducationalNotes;
 };
 
 struct DiagnosticEntryInfo : DiagnosticEntryInfoBase {

tools/SourceKit/lib/SwiftLang/SwiftEditor.cpp

@@ -110,6 +110,11 @@ void EditorDiagConsumer::handleDiagnostic(SourceManager &SM,
   }
   SKInfo.Description = Text.str();
 
+  for (auto notePath : Info.EducationalNotePaths) {
+    if (auto buffer = SM.getFileSystem()->getBufferForFile(notePath))
+      SKInfo.EducationalNotes.push_back(buffer->get()->getBuffer());
+  }
+
   Optional<unsigned> BufferIDOpt;
   if (Info.Loc.isValid()) {
     BufferIDOpt = SM.findBufferContainingLoc(Info.Loc);

tools/SourceKit/tools/sourcekitd/lib/API/Requests.cpp

@@ -2651,6 +2651,10 @@ static void fillDictionaryForDiagnosticInfoBase(
   if (!Info.Filename.empty())
     Elem.set(KeyFilePath, Info.Filename);
 
+  if (!Info.EducationalNotes.empty()) {
+    Elem.set(KeyEducationalNotes, Info.EducationalNotes);
+  }
+
   if (!Info.Ranges.empty()) {
     auto RangesArr = Elem.setArray(KeyRanges);
     for (auto R : Info.Ranges) {

utils/gyb_sourcekit_support/UIDs.py

@@ -95,6 +95,7 @@ def __init__(self, internal_name, external_name):
     KEY('Ranges', 'key.ranges'),
     KEY('Fixits', 'key.fixits'),
     KEY('Diagnostics', 'key.diagnostics'),
+    KEY('EducationalNotes', 'key.educational_notes'),
     KEY('FormatOptions', 'key.editor.format.options'),
     KEY('CodeCompleteOptions', 'key.codecomplete.options'),
     KEY('FilterRules', 'key.codecomplete.filterrules'),