[WIP][clang] adds a way to provide user-oriented reasons

[cjdb]

Summary

Part of the [revised diagnostic model][1] is to provide users with
diagnostics that explain what's going wrong from their perspective,
as opposed to from the compiler's perspective. This may be achieved
through a rewording of the reason, or by provididng more info, or both.

This commit also changes the diagnostic for an explicit template
parameter gone wrong to demonstrate how it works.

NOTE: this is a work-in-progress. Most of the work has been fleshed out, but the note needs to be provided with the kind of template argument it is given. I'm looking into doing this, but it seems to require a lot of tedious manual changes, and I'd prefer to get input on the changes that are currently in the diff before making those extra changes (which will distract from the current stuff, and may ultimately be unnecessary if the current direction is undesirable).

[1]: https://discourse.llvm.org/t/rfc-improving-clang-s-diagnostics/62584

[erichkeane]

A few comments. I don't mind the approach, though I find myself wondering if the "FormatDiagnostic" call should stay the same, and choose the legacy-reason only when a sarif reason doesn't exist? Or for some level of command line control?

The clang-side interface to this seems a touch clunky, and I fear it'll make continuing its use/generalizing its use less likely.

clang/include/clang/Basic/DiagnosticIDs.h

165

"Reason" is a part of the diagnostic itself, pre-rendered, right? Since these strings are literals, can this be an llvm::StringLiteral instead? (the constexpr-stringref type)?

Else, generating these is going to cost us at startup time.

clang/include/clang/Basic/DiagnosticSemaKinds.td

4520

Already kidna hate this format here. Is there any way we could make this be something more like:

DiagReason<Legacy<"whatever">, SARIF<"whatever">> ?

clang/lib/Format/TokenAnalyzer.cpp

47

This pair of calls has happened ~20 times by the time I've scrolled here. Can we do a single call here of some sort instead?

clang/test/Frontend/sarif-reason.cpp

16

This is definitely a case where I'd love the diagnostics formatted/arranged differently here. If you can use the #BOOKMARK style to make sure errors and notes are together, it would better illustrate what you're trying to do here.

[cjdb]

I don't understand why test_demangle.pass.cpp was considered too big to upload. Here's the diff:

diff --git a/libcxxabi/test/test_demangle.pass.cpp b/libcxxabi/test/test_demangle.pass.cpp
index bbbbdce8e6c3..9da6fb7d2ad9 100644
--- a/libcxxabi/test/test_demangle.pass.cpp
+++ b/libcxxabi/test/test_demangle.pass.cpp
@@ -11451,7 +11451,9 @@ const char* cases[][2] =
     {"_ZN5clang16DiagnosticClientD1Ev", "clang::DiagnosticClient::~DiagnosticClient()"},
     {"_ZN5clang16DiagnosticClientD2Ev", "clang::DiagnosticClient::~DiagnosticClient()"},
     {"_ZN5clang16DiagnosticClient16HandleDiagnosticENS_10Diagnostic5LevelERKNS_14DiagnosticInfoE", "clang::DiagnosticClient::HandleDiagnostic(clang::Diagnostic::Level, clang::DiagnosticInfo const&)"},
-    {"_ZNK5clang14DiagnosticInfo16FormatDiagnosticERN4llvm15SmallVectorImplIcEE", "clang::DiagnosticInfo::FormatDiagnostic(llvm::SmallVectorImpl<char>&) const"},
+    {"_ZNK5clang14DiagnosticInfo13FormatSummaryERN4llvm15SmallVectorImplIcEE", "clang::DiagnosticInfo::FormatSummary(llvm::SmallVectorImpl<char>&) const"},
+    {"_ZNK5clang14DiagnosticInfo18FormatLegacyReasonERN4llvm15SmallVectorImplIcEE", "clang::DiagnosticInfo::FormatLegacyReason(llvm::SmallVectorImpl<char>&) const"},
+    {"_ZNK5clang14DiagnosticInfo17FormatSARIFReasonERN4llvm15SmallVectorImplIcEE", "clang::DiagnosticInfo::FormatSARIFReason(llvm::SmallVectorImpl<char>&) const"},
     {"_ZNK5clang14DiagnosticInfo16FormatDiagnosticEPKcS2_RN4llvm15SmallVectorImplIcEE", "clang::DiagnosticInfo::FormatDiagnostic(char const*, char const*, llvm::SmallVectorImpl<char>&) const"},
     {"_Z10ScanFormatPKcS0_c", "ScanFormat(char const*, char const*, char)"},
     {"_Z20HandlePluralModifierRKN5clang14DiagnosticInfoEjPKcjRN4llvm15SmallVectorImplIcEE", "HandlePluralModifier(clang::DiagnosticInfo const&, unsigned int, char const*, unsigned int, llvm::SmallVectorImpl<char>&)"},

[cjdb]

The clang-side interface to this seems a touch clunky, and I fear it'll make continuing its use/generalizing its use less likely.

Is this w.r.t. the FormatDiagnostic being split up, or is it something else? If it's the former: I'll be changing that to FormatLegacyDiagnostic, which almost gets us back to where we started.

clang/include/clang/Basic/DiagnosticSemaKinds.td

4520

I like this suggestion.

[cjdb]

though I find myself wondering if the "FormatDiagnostic" call should stay the same, and choose the legacy-reason only when a sarif reason doesn't exist? Or for some level of command line control?

Hmm... isn't this the point of the diagnostic consumers?

[rymiel]

clang/include/clang/Frontend/DiagnosticRenderer.h

130 ↗

(On Diff #478675)

Which parameter is this doxygen comment referring to?

clang/tools/clang-format/ClangFormat.cpp

397

I don't think this indent change was intended?

[erichkeane]

In D138939#3958185, @cjdb wrote:

The clang-side interface to this seems a touch clunky, and I fear it'll make continuing its use/generalizing its use less likely.

Is this w.r.t. the FormatDiagnostic being split up, or is it something else? If it's the former: I'll be changing that to FormatLegacyDiagnostic, which almost gets us back to where we started.

Urgh, I was a bit afraid you'd ask that :D It is more of a feeling I guess, which is perhaps biased by this patch being particularly in the diagnostics-handling code. However, I suspect that over time, you're going to want to start switching all these uses of FormatLegacyReason over to FormatSarifReason, and I would want the 'easy way' to be the 'right' way in either case. Having it be a 2-liner, or over-specifying what is otherwise the 'default' behavior is a bit disconcerting.

In D138939#3958231, @cjdb wrote:

though I find myself wondering if the "FormatDiagnostic" call should stay the same, and choose the legacy-reason only when a sarif reason doesn't exist? Or for some level of command line control?

Hmm... isn't this the point of the diagnostic consumers?

I don't have a great feeling of that? I haven't done much thinking into the diagnostics architecture over the years. That said, the use of when we'd choose one vs the other isn't completely clear to me yet.

clang/lib/Basic/Diagnostic.cpp

790–791

Comment no longer matches.

[tschuett]

Maybe void FormatDiagnostic(SmallVectorImpl<char> &OutStr, DiagnosticMode mode)instead of void FormatDiagnostic(SmallVectorImpl<char> &OutStr)?
To make the transition easer and future proof.

[erichkeane]

In D138939#3963473, @tschuett wrote:

Maybe void FormatDiagnostic(SmallVectorImpl<char> &OutStr, DiagnosticMode mode)instead of void FormatDiagnostic(SmallVectorImpl<char> &OutStr)?
To make the transition easer and future proof.

I like this idea. Perhaps with DiagnosticMode being a 3-way enum:

enum struct DiagnosticMode {
  Legacy,
  Sarif,  
  Default = Legacy
}

I like the idea in particular, since it makes a command line flag to modify "Default" to be whichever the user prefers pretty trivial.

[cjdb]

In D138939#3963496, @erichkeane wrote:

In D138939#3963473, @tschuett wrote:

Maybe void FormatDiagnostic(SmallVectorImpl<char> &OutStr, DiagnosticMode mode)instead of void FormatDiagnostic(SmallVectorImpl<char> &OutStr)?
To make the transition easer and future proof.

I like this idea. Perhaps with DiagnosticMode being a 3-way enum:

enum struct DiagnosticMode {
  Legacy,
  Sarif,  
  Default = Legacy
}

I like the idea in particular, since it makes a command line flag to modify "Default" to be whichever the user prefers pretty trivial.

There's already a flag for this: -fdiagnostics-format=sarif. Why do we need a second diagnostic mode flag?

clang/tools/clang-format/ClangFormat.cpp

397

I find it ironic that clang-format misformatted ClangFormat.cpp.

[erichkeane]

In D138939#3964404, @cjdb wrote:

In D138939#3963496, @erichkeane wrote:

In D138939#3963473, @tschuett wrote:

Maybe void FormatDiagnostic(SmallVectorImpl<char> &OutStr, DiagnosticMode mode)instead of void FormatDiagnostic(SmallVectorImpl<char> &OutStr)?
To make the transition easer and future proof.

I like this idea. Perhaps with DiagnosticMode being a 3-way enum:

enum struct DiagnosticMode {
  Legacy,
  Sarif,  
  Default = Legacy
}

I like the idea in particular, since it makes a command line flag to modify "Default" to be whichever the user prefers pretty trivial.

There's already a flag for this: -fdiagnostics-format=sarif. Why do we need a second diagnostic mode flag?

Ah, oh... is the Sarif formatting being done with a new formatter? That seems unfortunate, since folks using the other formatters won't be able to use the user friendly formats.

[erichkeane]

In D138939#3964439, @erichkeane wrote:

In D138939#3964404, @cjdb wrote:

In D138939#3963496, @erichkeane wrote:

In D138939#3963473, @tschuett wrote:

Maybe void FormatDiagnostic(SmallVectorImpl<char> &OutStr, DiagnosticMode mode)instead of void FormatDiagnostic(SmallVectorImpl<char> &OutStr)?
To make the transition easer and future proof.

I like this idea. Perhaps with DiagnosticMode being a 3-way enum:

enum struct DiagnosticMode {
  Legacy,
  Sarif,  
  Default = Legacy
}

I like the idea in particular, since it makes a command line flag to modify "Default" to be whichever the user prefers pretty trivial.

There's already a flag for this: -fdiagnostics-format=sarif. Why do we need a second diagnostic mode flag?

Ah, oh... is the Sarif formatting being done with a new formatter? That seems unfortunate, since folks using the other formatters won't be able to use the user friendly formats.

I've been alerted offline that I am misunderstanding the Sarif proposal, and where this is going. I'll note that I wasn't present/invited at the calls where all of this was discussed, so I am admittedly not completely up to date. The above concern shouldn't stop others from reviewing this, particularly if you better understand the intent here.

[cjdb]

responds to feedback

[cjdb]

In D138939#3964677, @erichkeane wrote:

In D138939#3964439, @erichkeane wrote:

In D138939#3964404, @cjdb wrote:

In D138939#3963496, @erichkeane wrote:

In D138939#3963473, @tschuett wrote:

Maybe void FormatDiagnostic(SmallVectorImpl<char> &OutStr, DiagnosticMode mode)instead of void FormatDiagnostic(SmallVectorImpl<char> &OutStr)?
To make the transition easer and future proof.

I like this idea. Perhaps with DiagnosticMode being a 3-way enum:

enum struct DiagnosticMode {
  Legacy,
  Sarif,  
  Default = Legacy
}

I like the idea in particular, since it makes a command line flag to modify "Default" to be whichever the user prefers pretty trivial.

There's already a flag for this: -fdiagnostics-format=sarif. Why do we need a second diagnostic mode flag?

Ah, oh... is the Sarif formatting being done with a new formatter? That seems unfortunate, since folks using the other formatters won't be able to use the user friendly formats.

I've been alerted offline that I am misunderstanding the Sarif proposal, and where this is going. I'll note that I wasn't present/invited at the calls where all of this was discussed, so I am admittedly not completely up to date. The above concern shouldn't stop others from reviewing this, particularly if you better understand the intent here.

I don't necessarily think you're the one misunderstanding here. We're definitely talking past one another, but I think it's equally likely that you're asking for something reasonable, and I'm mixing it up with something else.

clang/include/clang/Frontend/DiagnosticRenderer.h

130 ↗

(On Diff #478675)

Thanks, that was from an old iteration of the CL.

clang/lib/Basic/Diagnostic.cpp

790–791

I've deleted the comment because it's already in the header, and risks going stale over and over.

clang/test/Frontend/sarif-reason.cpp

16

This is maybe done? I'm not sure if this is the #BOOKMARK style you're referring to, but it should capture the same intent. Lemme know if you had something else in mind and I'll happily change it 🙂

[tschuett]

Then Sarif was a distraction. Still to reduce boilerplate and for A/B testing:

enum class DiagnosticMode {
  Legacy,
  UserOriented,
  Default = Legacy
}

[cjdb]

In D138939#3965985, @tschuett wrote:

Then Sarif was a distraction. Still to reduce boilerplate and for A/B testing:

enum class DiagnosticMode {
  Legacy,
  UserOriented,
  Default = Legacy
}

It took a fair bit of squinting and coffee, but I think I get it now. Having SARIF will be good for option 2: I hadn't realised this was at the Clang API level and not an enum for users to toggle on the command line! Thanks for your patience, I'll implement this now.

[tschuett]

Maybe the kind/amount of information printed ( DiagnosticMode ) and the output device (console/sarif) are orthogonal issues.

Still it would nice to be able to toggle the diagnostic mode for users/testing / A/B.

[cjdb]

In D138939#3966938, @tschuett wrote:

Maybe the kind/amount of information printed ( DiagnosticMode ) and the output device (console/sarif) are orthogonal issues.

Still it would nice to be able to toggle the diagnostic mode for users/testing / A/B.

Hmm, are you asking for it to be possible for there to be legacy diagnostics with -fdiagnostics-format=sarif as well as user-oriented diagnostics? That should be doable, at least for now (I don't want to commit to this long-term in case it isn't viable at some point down the road, but it's hardly effort for what we currently support).

[tschuett]

I do not ask you to do anything! I just noticed that you add a lot of FormatXXXDiagnostic functions. An alternativ design is to have one FormatDiagnostic function with a mode parameter. Then you can decide whether to print legacy or user-oriented reasons.

If next year you invent another diagnostic, you can extend the enum and the FormatDiagnostic function.

[dblaikie]

Sorry if this is derailing, but I wonder/worry about a few things here:

1. Compounding structured output with phraseology - it seems like it might be worthwhile for these to be separate issues (doesn't mean the terminal output has to say exactly the same thing - as you've mentioned, we could have some fields that aren't rendered in some modes (eg: maybe a terminal only gets the summary, and not the reason - or perhaps you can ask for reasons to be provided if you don't mind the verbosity)). In the example case include here - describing the template parameter kind mismatch seems OK for Clang's current textual diagnostic experience & I don't think that would need to be limited to only the SARIF output?
2. Could the new phraseology be included in a separate/parallel diagnostic file, essentially akin to a translation? Clang never did get support for multiple languages in its diagnostics, but maybe this is the time to do that work? And then have this new phrasing as the first "translation" of sorts?
3. I'm not sure I'd commit to calling the current diagnostic experience "legacy" just yet & maybe this is my broadest feedback: It'd be great to avoid a two-system situation with the intent to merge things back in later.

I think what I'd like to see (though I'm far from the decider in any of this) would be that the existing underlying structured diagnostics system could have a new emission system, that produces SARIF instead of text on a terminal - same underlying structured representation, but providing that more directly (in SARIF/JSON/etc) so that it's not lossy in the conversion to an output format - essentially a machine-readable mode for clang's diagnostic output. (to a file, to the terminal, beside the existing terminal output or instead of it, whatever folks prefer) - this would, ideally, initially require no changes to diagnostic API usage across clang.
Diagnostic quality improvements, like the template parameter kind mismatch can be committed independently as desired.
Diagnostic infrastructure could be improved/expanded - adding the "reason" field, and a way to emit that (perhaps only in SARIF output, but maybe there's room for a flag to emit it in terminal diagnostics too).
Multiple diagnostic text files supported, and the ability to choose which diagnostic text - initially with the intent to support this newly proposed phrasing approach, but equally could be used for whole language translation.

Pretty much all of these features could be implemented somewhat in parallel, each feature would be of value independently to varying degrees, and we wouldn't end up with a deprecated/legacy/not ready yet situation (the only "not ready yet" part might be adding the new diagnostic phrasings - perhaps initially there'd be some way to fallback to the traditional diagnostics, so that the whole database didn't need to be translated wholesale - and once it's all translated and there's a lot of user feedback on the direction, we could consider changing the diagnostic database default, perhaps eventually deprecating the old database, and eventually removing it - without major API upheaval/renaming/addition/removal)

clang/lib/Basic/DiagnosticIDs.cpp

524

I don't think LLVM generally uses (xxx) in FIXMEs, or if we do it's probably only for bug numbers and maybe developer user names (though the latter's not ideal - people come and go, bug numbers are forever (kinda)) - not sure what the "spaceship" in there is meant to communicate (I'm aware of the C++20 spaceship operator, but I'd expect the thing in the () to be some list of known entities that we keep track of somewhere?)

Maybe // FIXME: Use spaceship operator in C++20?

812–825

Unrelated/accidental reformatting? (please commit separately if it's being committed)

[cjdb]

In D138939#3967397, @tschuett wrote:

I do not ask you to do anything! I just noticed that you add a lot of FormatXXXDiagnostic functions. An alternativ design is to have one FormatDiagnostic function with a mode parameter. Then you can decide whether to print legacy or user-oriented reasons.

If next year you invent another diagnostic, you can extend the enum and the FormatDiagnostic function.

Makes sense to me! Thank you for clarifying.

In D138939#3967715, @dblaikie wrote:

Sorry if this is derailing, but I wonder/worry about a few things here:

1. Compounding structured output with phraseology - it seems like it might be worthwhile for these to be separate issues

I agree with you. The reason I've compounded the two is to demonstrate how this is supposed to be used (otherwise it really feels like a nothing burger where I've made change for the sake of change).

(doesn't mean the terminal output has to say exactly the same thing - as you've mentioned, we could have some fields that aren't rendered in some modes (eg: maybe a terminal only gets the summary, and not the reason - or perhaps you can ask for reasons to be provided if you don't mind the verbosity)). In the example case include here - describing the template parameter kind mismatch seems OK for Clang's current textual diagnostic experience & I don't think that would need to be limited to only the SARIF output?

@rsmith and I spent a fair amount of time chatting about giving Clang a verbose diagnostic mode, and we agreed that would have issues:

1. If you wanted to use unstructured text in brief mode 90% of the time and then change when you need to clarify something, build systems are going to need to rebuild everything.
2. Because scripts almost certainly exist that consume the current diagnostics, I'm reluctant to alter those in any meaningful way. I even note this in the RFC, where I explicitly state that there are no current plans to bin the existing model.

2. Could the new phraseology be included in a separate/parallel diagnostic file, essentially akin to a translation? Clang never did get support for multiple languages in its diagnostics, but maybe this is the time to do that work? And then have this new phrasing as the first "translation" of sorts?

Yes and no. For strict a rephrasing, this would be possible, but reasons aren't necessarily going to be just a rephrasing (the one in this patch is not). I intend for the reason section to be a far richer field that contains information that we've never previously provided before: a translation file can't help there. However, using parallel diagnostic files might not be such a bad idea. How do we ensure the two don't get out of sync?

3. I'm not sure I'd commit to calling the current diagnostic experience "legacy" just yet &

You mentioned "terminal diagnostics" below. I like that a lot more than the original "unstructured reason" and "traditional reason", so let's go with that for now.

maybe this is my broadest feedback: It'd be great to avoid a two-system situation with the intent to merge things back in later.

I don't know how we can without breaking the promise of backwards compatibility.

I think what I'd like to see (though I'm far from the decider in any of this) would be that the existing underlying structured diagnostics system could have a new emission system, that produces SARIF instead of text on a terminal - same underlying structured representation, but providing that more directly (in SARIF/JSON/etc) so that it's not lossy in the conversion to an output format - essentially a machine-readable mode for clang's diagnostic output. (to a file, to the terminal, beside the existing terminal output or instead of it, whatever folks prefer) - this would, ideally, initially require no changes to diagnostic API usage across clang.

I think you may be asking for what I mentioned here? That's doable and probably wise: I just need to add -fdiagnostics-format=sarif-compatibility (flag spelling to be bikeshed). (@tschuett it seems that this flag may happen regardless of whether you intended for it!)

Diagnostic quality improvements, like the template parameter kind mismatch can be committed independently as desired.

I'll coordinate with you next week to address my concerns here, but if we can achieve this, I'll be really happy. I'll be happier again if we can make it so both formats can have the change too :)

Pretty much all of these features could be implemented somewhat in parallel, each feature would be of value independently to varying degrees, and we wouldn't end up with a deprecated/legacy/not ready yet situation (the only "not ready yet" part might be adding the new diagnostic phrasings - perhaps initially there'd be some way to fallback to the traditional diagnostics, so that the whole database didn't need to be translated wholesale - and once it's all translated and there's a lot of user feedback on the direction, we could consider changing the diagnostic database default, perhaps eventually deprecating the old database, and eventually removing it - without major API upheaval/renaming/addition/removal)

Mostly agreement with the above wherever possible.

clang/lib/Basic/DiagnosticIDs.cpp

524

FIXME(spaceship) is really just to make it very easy to find. I can make a bug for it.

812–825

I do what git clang-format HEAD~ asks me to do.

[erichkeane]

clang/test/Frontend/sarif-reason.cpp

16

It isn't exactly (in that it is using line-numbers instead of bookmarks), but the ordering is fine for me.

The bookmarking is something like:

LineThatHasNote; // #NoteLine
...
LineThatCausesError;
// expected-error@-1 {{Some Error}}
// expected-note@#NoteLine {{The Note}}

However, what I REALLY care about is that the notes and errors are 'next' to eachother, since they are easier to read that way

[cjdb]

Abandoning since we're heading down a different design path now.

clang-tools-extra/clang-tidy/ClangTidyDiagnosticConsumer.cpp

if (ExternalDiagEngine) {
     // If there is an external diagnostics engine, like in the
     // ClangTidyPluginAction case, forward the diagnostics to it.
     forwardDiagnostic(Info);
   } else {
     ClangTidyDiagnosticRenderer Converter(
         Context.getLangOpts(), &Context.DiagEngine->getDiagnosticOptions(),
         Errors.back());
     SmallString<100> Message;
-    Info.FormatDiagnostic(Message);
+    Info.FormatLegacyDiagnostic(Message);
     FullSourceLoc Loc;
     if (Info.getLocation().isValid() && Info.hasSourceManager())
       Loc = FullSourceLoc(Info.getLocation(), Info.getSourceManager());
     Converter.emitDiagnostic(Loc, DiagLevel, Message, Info.getRanges(),
                              Info.getFixItHints());
   }
 
   if (Info.hasSourceManager())

clang-tools-extra/clangd/Compiler.cpp

 
 namespace clang {
 namespace clangd {
 
 void IgnoreDiagnostics::log(DiagnosticsEngine::Level DiagLevel,
                             const clang::Diagnostic &Info) {
   // FIXME: format lazily, in case vlog is off.
   llvm::SmallString<64> Message;
-  Info.FormatDiagnostic(Message);
+  Info.FormatLegacyDiagnostic(Message);
 
   llvm::SmallString<64> Location;
   if (Info.hasSourceManager() && Info.getLocation().isValid()) {
     auto &SourceMgr = Info.getSourceManager();
     auto Loc = SourceMgr.getFileLoc(Info.getLocation());
     llvm::raw_svector_ostream OS(Location);
     Loc.print(OS, SourceMgr);
     OS << ":";

clang-tools-extra/clangd/Diagnostics.cpp

 
 namespace clang {
 namespace clangd {
 namespace {
 
 const char *getDiagnosticCode(unsigned ID) {
   switch (ID) {
 #define DIAG(ENUM, CLASS, DEFAULT_MAPPING, DESC, GROPU, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   case clang::diag::ENUM:                                                      \
     return #ENUM;
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"

 
 /// Fills \p D with all information, except the location-related bits.
 /// Also note that ID and Name are not part of clangd::DiagBase and should be
 /// set elsewhere.
 static void fillNonLocationData(DiagnosticsEngine::Level DiagLevel,
                                 const clang::Diagnostic &Info,
                                 clangd::DiagBase &D) {
   llvm::SmallString<64> Message;
-  Info.FormatDiagnostic(Message);
+  Info.FormatLegacyDiagnostic(Message);
 
   D.Message = std::string(Message.str());
   D.Severity = DiagLevel;
   D.Category = DiagnosticIDs::getCategoryNameFromID(
                    DiagnosticIDs::getCategoryNumberForDiag(Info.getID()))
                    .str();
 }
 
if (SyntheticMessage && FixIts.size() == 1) {
           writeCodeToFixMessage(M, Insert);
           M << "'";
         }
         // Don't allow source code to inject newlines into diagnostics.
         std::replace(Message.begin(), Message.end(), '\n', ' ');
       }
     }
     if (Message.empty()) // either !SyntheticMessage, or we failed to make one.
-      Info.FormatDiagnostic(Message);
+      Info.FormatSummary(Message);
+    Info.FormatLegacyDiagnostic(Message);
     LastDiag->Fixes.push_back(
         Fix{std::string(Message.str()), std::move(Edits)});
     return true;
   };
 
   if (!isNote(DiagLevel)) {
     // Handle the new main diagnostic.
     flushLastDiag();

clang/include/clang/Basic/Diagnostic.h

const FixItHint &getFixItHint(unsigned Idx) const {
     assert(Idx < getNumFixItHints() && "Invalid index!");
     return DiagObj->DiagStorage.FixItHints[Idx];
   }
 
   ArrayRef<FixItHint> getFixItHints() const {
     return DiagObj->DiagStorage.FixItHints;
   }
 
-  /// Format this diagnostic into a string, substituting the
+  /// Format the summary into a string, substituting the
   /// formal arguments into the %0 slots.
   ///
   /// The result is appended onto the \p OutStr array.
-  void FormatDiagnostic(SmallVectorImpl<char> &OutStr) const;
+  void FormatSummary(SmallVectorImpl<char> &OutStr) const;
+
+  /// Format the legacy reason into a string, substituting the formal arguments
+  /// into the %0 slots.
+  ///
+  /// The result is appended onto the \p OutStr array.
+  void FormatLegacyReason(SmallVectorImpl<char> &OutStr) const;
+
+  /// Format the SARIF-based reason into a string, substituting the formal
+  /// arguments into the %0 slots.
+  ///
+  /// The result is appended onto the \p OutStr array.
+  void FormatSARIFReason(SmallVectorImpl<char> &OutStr) const;
+
+  /// Format the legacy diagnostic into a string, substituting the
+  /// formal arguments into the %0 slots.
+  ///
+  /// The result is appended onto the \p OutStr array.
+  void FormatLegacyDiagnostic(SmallVectorImpl<char> &OutStr) const;
 
   /// Format the given format-string into the output buffer using the
   /// arguments stored in this diagnostic.
   void FormatDiagnostic(const char *DiagStr, const char *DiagEnd,
                         SmallVectorImpl<char> &OutStr) const;
 };
 
 /**
  * Represents a diagnostic in a form that can be retained until its
  * corresponding source manager is destroyed.
  */
 class StoredDiagnostic {
   unsigned ID;
   DiagnosticsEngine::Level Level;
   FullSourceLoc Loc;
   std::string Message;
+  DiagnosticReason Reason;
+
   std::vector<CharSourceRange> Ranges;
   std::vector<FixItHint> FixIts;
 
 public:
   StoredDiagnostic() = default;
   StoredDiagnostic(DiagnosticsEngine::Level Level, const Diagnostic &Info);
   StoredDiagnostic(DiagnosticsEngine::Level Level, unsigned ID,
-                   StringRef Message);
+                   StringRef Message, DiagnosticReason Reason);
   StoredDiagnostic(DiagnosticsEngine::Level Level, unsigned ID,
-                   StringRef Message, FullSourceLoc Loc,
-                   ArrayRef<CharSourceRange> Ranges,
+                   StringRef Message, DiagnosticReason Reason,
+                   FullSourceLoc Loc, ArrayRef<CharSourceRange> Ranges,
                    ArrayRef<FixItHint> Fixits);
 
   /// Evaluates true when this object stores a diagnostic.
   explicit operator bool() const { return !Message.empty(); }
 
   unsigned getID() const { return ID; }
   DiagnosticsEngine::Level getLevel() const { return Level; }
   const FullSourceLoc &getLocation() const { return Loc; }
   StringRef getMessage() const { return Message; }
+  const DiagnosticReason &getReason() const { return Reason; }
 
   void setLocation(FullSourceLoc Loc) { this->Loc = Loc; }
 
   using range_iterator = std::vector<CharSourceRange>::const_iterator;
 
   range_iterator range_begin() const { return Ranges.begin(); }
   range_iterator range_end() const { return Ranges.end(); }
   unsigned range_size() const { return Ranges.size(); }

clang/include/clang/Basic/Diagnostic.td

 include "DiagnosticDocs.td"
 
 // This defines all of the named diagnostic categories.
 include "DiagnosticCategories.td"
 
 // This defines all of the named diagnostic groups.
 include "DiagnosticGroups.td"
 
+class Legacy<string value> {
+  string Value = value;
+}
+
+class SARIF<string value> {
+  string Value = value;
+}
+
+class DiagReason<Legacy legacy, SARIF structured = SARIF<legacy.Value>> {
+  // A legacy reason is a reason that is part of Clang's legacy diagnostic model,
+  // but needed to be split from the summary in order to facilitate the existence
+  // of the structured diagnostic (which will have very different text). One may
+  // observe that older versions of Clang's diagnostics are the same as
+  // `Diagnostic.Summary + Diagnostic.Reason.Legacy`. This is intentional, so as
+  // to preserve the legacy diagnostic model for the time being.
+  Legacy Legacy = legacy;
+
+  // The SARIF reason will appear when Clang is asked to emit SARIF diagnostics,
+  // in place of Legacy. Unlike Legacy, which is a fragment of the original
+  // diagnostic from past-Clang, SARIF reasons may have completely different text
+  // to explain the problem, often from the perspective of a user.
+  SARIF SARIF = structured;
+}
+def NO_REASON_YET : DiagReason<Legacy<"">, SARIF<"">>;
 
 // All diagnostics emitted by the compiler are an indirect subclass of this.
-class Diagnostic<string summary, DiagClass DC, Severity defaultmapping> {
+class Diagnostic<string summary, DiagClass DC, Severity defaultmapping, DiagReason reason> {
   /// Component is specified by the file with a big let directive.
   string         Component = ?;
   string         Summary = summary;
   DiagClass      Class = DC;
   SFINAEResponse SFINAE = SFINAE_Suppress;
   bit            AccessControl = 0;
   bit            WarningNoWerror = 0;
   bit            ShowInSystemHeader = 0;
   bit            ShowInSystemMacro = 1;
   bit            Deferrable = 0;
   Severity       DefaultSeverity = defaultmapping;
   DiagGroup      Group;
   string         CategoryName = "";
+  DiagReason     Reason = reason;
 }
 
 class SFINAEFailure {
   SFINAEResponse SFINAE = SFINAE_SubstitutionFailure;
 }
 class NoSFINAE {
   SFINAEResponse SFINAE = SFINAE_Report;
 }
class Deferrable {
   bit Deferrable = 1;
 }
 
 class NonDeferrable {
   bit Deferrable = 0;
 }
 
 // FIXME: ExtWarn and Extension should also be SFINAEFailure by default.
-class Error<string str>     : Diagnostic<str, CLASS_ERROR, SEV_Error>, SFINAEFailure {
+class Error<string str, DiagReason reason = NO_REASON_YET>     : Diagnostic<str, CLASS_ERROR, SEV_Error, reason>, SFINAEFailure {
   bit ShowInSystemHeader = 1;
 }
 // Warnings default to on (but can be default-off'd with DefaultIgnore).
 // This is used for warnings about questionable code; warnings about
 // accepted language extensions should use Extension or ExtWarn below instead.
-class Warning<string str>   : Diagnostic<str, CLASS_WARNING, SEV_Warning>;
+class Warning<string str, DiagReason reason = NO_REASON_YET>   : Diagnostic<str, CLASS_WARNING, SEV_Warning, reason>;
 // Remarks can be turned on with -R flags and provide commentary, e.g. on
 // optimizer decisions.
-class Remark<string str>    : Diagnostic<str, CLASS_REMARK, SEV_Ignored>;
+class Remark<string str, DiagReason reason = NO_REASON_YET>    : Diagnostic<str, CLASS_REMARK, SEV_Ignored, reason>;
 // Extensions are warnings about accepted language extensions.
 // Extension warnings are default-off but enabled by -pedantic.
-class Extension<string str> : Diagnostic<str, CLASS_EXTENSION, SEV_Ignored>;
+class Extension<string str, DiagReason reason = NO_REASON_YET> : Diagnostic<str, CLASS_EXTENSION, SEV_Ignored, reason>;
 // ExtWarns are warnings about accepted language extensions.
 // ExtWarn warnings are default-on.
-class ExtWarn<string str>   : Diagnostic<str, CLASS_EXTENSION, SEV_Warning>;
+class ExtWarn<string str, DiagReason reason = NO_REASON_YET>   : Diagnostic<str, CLASS_EXTENSION, SEV_Warning, reason>;
 // Notes can provide supplementary information on errors, warnings, and remarks.
-class Note<string str>      : Diagnostic<str, CLASS_NOTE, SEV_Fatal/*ignored*/>;
+class Note<string str, DiagReason reason = NO_REASON_YET>      : Diagnostic<str, CLASS_NOTE, SEV_Fatal/*ignored*/, reason>;
 
 
 class DefaultIgnore { Severity DefaultSeverity = SEV_Ignored; }
 class DefaultWarn   { Severity DefaultSeverity = SEV_Warning; }
 class DefaultError  { Severity DefaultSeverity = SEV_Error; }
 class DefaultFatal  { Severity DefaultSeverity = SEV_Fatal; }
 class DefaultWarnNoWerror {
   bit WarningNoWerror = 1;

clang/include/clang/Basic/DiagnosticAST.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICAST_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   ENUM,
 #define ASTSTART
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #undef DIAG
   NUM_BUILTIN_AST_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICAST_H

clang/include/clang/Basic/DiagnosticAnalysis.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICANALYSIS_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   ENUM,
 #define ANALYSISSTART
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
 #undef DIAG
   NUM_BUILTIN_ANALYSIS_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICANALYSIS_H

clang/include/clang/Basic/DiagnosticComment.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICCOMMENT_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   ENUM,
 #define COMMENTSTART
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #undef DIAG
   NUM_BUILTIN_COMMENT_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICCOMMENT_H

clang/include/clang/Basic/DiagnosticCrossTU.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICCROSSTU_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   ENUM,
 #define CROSSTUSTART
 #include "clang/Basic/DiagnosticCrossTUKinds.inc"
 #undef DIAG
   NUM_BUILTIN_CROSSTU_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICCROSSTU_H

clang/include/clang/Basic/DiagnosticDriver.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICDRIVER_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   ENUM,
 #define DRIVERSTART
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #undef DIAG
   NUM_BUILTIN_DRIVER_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICDRIVER_H

clang/include/clang/Basic/DiagnosticFrontend.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICFRONTEND_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   ENUM,
 #define FRONTENDSTART
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #undef DIAG
   NUM_BUILTIN_FRONTEND_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICFRONTEND_H

clang/include/clang/Basic/DiagnosticIDs.h

namespace diag {
 
     class CustomDiagInfo;
 
     /// All of the diagnostics that can be emitted by the frontend.
     typedef unsigned kind;
 
     // Get typedefs for common diagnostics.
     enum {
-#define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, CATEGORY,      \
-             NOWERROR, SHOWINSYSHEADER, SHOWINSYSMACRO, DEFFERABLE)            \
+#define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, CATEGORY,  \
+                 NOWERROR, SHOWINSYSHEADER, SHOWINSYSMACRO, DEFFERABLE,        \
+                 LEGACY_REASON, SARIF_REASON)                                  \
       ENUM,
 #define COMMONSTART
 #include "clang/Basic/DiagnosticCommonKinds.inc"
       NUM_BUILTIN_COMMON_DIAGNOSTICS
 #undef DIAG
     };
 
     /// Enum values that allow the client to map NOTEs, WARNINGs, and EXTENSIONs
     /// to either Ignore (nothing), Remark (emit a remark), Warning
static DiagnosticMapping deserialize(unsigned Bits) {
     Result.HasNoWarningAsError = (Bits >> 5) & 1;
     Result.HasNoErrorAsFatal = (Bits >> 4) & 1;
     Result.WasUpgradedFromWarning = (Bits >> 3) & 1;
     Result.Severity = Bits & 0x7;
     return Result;
   }
 };
 
+struct LegacyR {
+  llvm::StringLiteral Value = "";
+
+  // FIXME(spaceship): default when C++20 becomes the default
+  bool operator==(const LegacyR &Other) const { return Value == Other.Value; }
+  bool operator!=(const LegacyR &Other) const { return !(*this == Other); }
+  bool operator<(const LegacyR &Other) const { return Value < Other.Value; }
+  bool operator>(const LegacyR &Other) const { return Other < *this; }
+  bool operator<=(const LegacyR &Other) const { return !(Other < *this); }
+  bool operator>=(const LegacyR &Other) const { return !(*this < Other); }
+};
+
+struct DiagnosticReason {
+  LegacyR Legacy;
+  llvm::StringLiteral SARIF = "";
+
+  // FIXME(spaceship): default when C++20 becomes the default
+  bool operator==(const DiagnosticReason &Other) const {
+    return Legacy == Other.Legacy && SARIF == Other.SARIF;
+  }
+
+  bool operator!=(const DiagnosticReason &Other) const {
+    return !(*this == Other);
+  }
+
+  bool operator<(const DiagnosticReason &Other) const {
+    return Legacy < Other.Legacy && SARIF < Other.SARIF;
+  }
+
+  bool operator>(const DiagnosticReason &Other) const { return Other < *this; }
+
+  bool operator<=(const DiagnosticReason &Other) const {
+    return !(Other < *this);
+  }
+
+  bool operator>=(const DiagnosticReason &Other) const {
+    return !(*this < Other);
+  }
+};
+
 /// Used for handling and querying diagnostic IDs.
 ///
 /// Can be used and shared by multiple Diagnostics for multiple translation units.
 class DiagnosticIDs : public RefCountedBase<DiagnosticIDs> {
 public:
   /// The level of the diagnostic, after it has been through mapping.
   enum Level {
     Ignored, Note, Remark, Warning, Error, Fatal
public:
   /// level.
   ///
   /// If this is the first request for this diagnostic, it is registered and
   /// created, otherwise the existing ID is returned.
 
   // FIXME: Replace this function with a create-only facilty like
   // createCustomDiagIDFromFormatString() to enforce safe usage. At the time of
   // writing, nearly all callers of this function were invalid.
-  unsigned getCustomDiagID(Level L, StringRef FormatString);
+  unsigned getCustomDiagID(Level L, StringRef FormatString,
+                           const DiagnosticReason &Reason = {});
 
   //===--------------------------------------------------------------------===//
   // Diagnostic classification and reporting interfaces.
   //
 
   /// Given a diagnostic ID, return a description of the issue.
   StringRef getDescription(unsigned DiagID) const;
 
+  /// Given a diagnostic ID, return the issue's legacy reason.
+  StringRef getLegacyReason(unsigned DiagID) const;
+
+  /// Given a diagnostic ID, return the issue's SARIF reason.
+  StringRef getSARIFReason(unsigned DiagID) const;
+
   /// Return true if the unmapped diagnostic levelof the specified
   /// diagnostic ID is a Warning or Extension.
   ///
   /// This only works on builtin diagnostics, not custom ones, and is not
   /// legal to call on NOTEs.
   static bool isBuiltinWarningOrExtension(unsigned DiagID);
 
   /// Return true if the specified diagnostic is mapped to errors by

clang/include/clang/Basic/DiagnosticLex.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICLEX_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   ENUM,
 #define LEXSTART
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #undef DIAG
   NUM_BUILTIN_LEX_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICLEX_H

clang/include/clang/Basic/DiagnosticParse.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICPARSE_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   ENUM,
 #define PARSESTART
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #undef DIAG
   NUM_BUILTIN_PARSE_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICPARSE_H

clang/include/clang/Basic/DiagnosticRefactoring.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICREFACTORING_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   ENUM,
 #define REFACTORINGSTART
 #include "clang/Basic/DiagnosticRefactoringKinds.inc"
 #undef DIAG
   NUM_BUILTIN_REFACTORING_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICREFACTORING_H

clang/include/clang/Basic/DiagnosticSema.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICSEMA_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   ENUM,
 #define SEMASTART
 #include "clang/Basic/DiagnosticSemaKinds.inc"
 #undef DIAG
   NUM_BUILTIN_SEMA_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICSEMA_H

clang/include/clang/Basic/DiagnosticSemaKinds.td

def note_ovl_candidate_inconsistent_deduction : Note<
     "candidate template ignored: deduced %select{conflicting types|"
     "conflicting values|conflicting templates|packs of different lengths}0 "
     "for parameter %1%diff{ ($ vs. $)|}2,3">;
 def note_ovl_candidate_inconsistent_deduction_types : Note<
     "candidate template ignored: deduced values %diff{"
     "of conflicting types for parameter %0 (%1 of type $ vs. %3 of type $)|"
     "%1 and %3 of conflicting types for parameter %0}2,4">;
 def note_ovl_candidate_explicit_arg_mismatch_named : Note<
-    "candidate template ignored: invalid explicitly-specified argument "
-    "for template parameter %0">;
+  "candidate template ignored: ",
+  DiagReason<
+    Legacy<"invalid explicitly-specified argument for template parameter %0">,
+    SARIF<"we passed a %select{type|value|class template}1 as our %ordinal2 "
+    "explicit template parameter, but this candidate expects a "
+    "%select{type|value|class template}3 for template parameter %0">>>;
 def note_ovl_candidate_unsatisfied_constraints : Note<
     "candidate template ignored: constraints not satisfied%0">;
 def note_ovl_candidate_explicit_arg_mismatch_unnamed : Note<
     "candidate template ignored: invalid explicitly-specified argument "
     "for %ordinal0 template parameter">;
 def note_ovl_candidate_instantiation_depth : Note<
     "candidate template ignored: substitution exceeded maximum template "
     "instantiation depth">;

clang/include/clang/Basic/DiagnosticSerialization.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICSERIALIZATION_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   ENUM,
 #define SERIALIZATIONSTART
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #undef DIAG
   NUM_BUILTIN_SERIALIZATION_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICSERIALIZATION_H

clang/include/clang/Basic/PartialDiagnostic.h

public:
   }
 
   void EmitToString(DiagnosticsEngine &Diags,
                     SmallVectorImpl<char> &Buf) const {
     // FIXME: It should be possible to render a diagnostic to a string without
     //        messing with the state of the diagnostics engine.
     DiagnosticBuilder DB(Diags.Report(getDiagID()));
     Emit(DB);
-    Diagnostic(&Diags).FormatDiagnostic(Buf);
+    Diagnostic Info(&Diags);
+    Info.FormatLegacyDiagnostic(Buf);
     DB.Clear();
     Diags.Clear();
   }
 
   /// Clear out this partial diagnostic, giving it a new diagnostic ID
   /// and removing all of its arguments, ranges, and fix-it hints.
   void Reset(unsigned DiagID = 0) {
     this->DiagID = DiagID;

clang/include/clang/Frontend/ASTUnit.h

struct StandaloneFixIt {
     std::string CodeToInsert;
     bool BeforePreviousInsertions;
   };
 
   struct StandaloneDiagnostic {
     unsigned ID;
     DiagnosticsEngine::Level Level;
     std::string Message;
+    DiagnosticReason Reason;
     std::string Filename;
     unsigned LocOffset;
     std::vector<std::pair<unsigned, unsigned>> Ranges;
     std::vector<StandaloneFixIt> FixIts;
   };
 
 private:
   std::shared_ptr<LangOptions>            LangOpts;

clang/lib/Basic/Diagnostic.cpp

 static const char *getTokenDescForDiagnostic(tok::TokenKind Kind) {
   switch (Kind) {
   case tok::identifier:
     return "identifier";
   default:
     return nullptr;
   }
 }
 
-/// FormatDiagnostic - Format this diagnostic into a string, substituting the
-/// formal arguments into the %0 slots.  The result is appended onto the Str
-/// array.
-void Diagnostic::
-FormatDiagnostic(SmallVectorImpl<char> &OutStr) const {
+void Diagnostic::FormatSummary(SmallVectorImpl<char> &OutStr) const {
   if (!StoredDiagMessage.empty()) {
     OutStr.append(StoredDiagMessage.begin(), StoredDiagMessage.end());
     return;
   }
 
   StringRef Diag =
     getDiags()->getDiagnosticIDs()->getDescription(getID());
 
   FormatDiagnostic(Diag.begin(), Diag.end(), OutStr);
 }
 
+void Diagnostic::FormatLegacyReason(SmallVectorImpl<char> &OutStr) const {
+  StringRef Diag = getDiags()->getDiagnosticIDs()->getLegacyReason(getID());
+  FormatDiagnostic(Diag.begin(), Diag.end(), OutStr);
+}
+
+void Diagnostic::FormatSARIFReason(SmallVectorImpl<char> &OutStr) const {
+  StringRef Diag = getDiags()->getDiagnosticIDs()->getSARIFReason(getID());
+  FormatDiagnostic(Diag.begin(), Diag.end(), OutStr);
+}
+
+void Diagnostic::FormatLegacyDiagnostic(SmallVectorImpl<char> &OutStr) const {
+  FormatSummary(OutStr);
+  FormatLegacyReason(OutStr);
+}
+
 /// pushEscapedString - Append Str to the diagnostic buffer,
 /// escaping non-printable characters and ill-formed code unit sequences.
 static void pushEscapedString(StringRef Str, SmallVectorImpl<char> &OutStr) {
   OutStr.reserve(OutStr.size() + Str.size());
   auto *Begin = reinterpret_cast<const unsigned char *>(Str.data());
   llvm::raw_svector_ostream OutStream(OutStr);
   const unsigned char *End = Begin + Str.size();
   while (Begin != End) {
else
                                         (intptr_t)getArgStdStr(ArgNo).c_str()));
   }
 
   // Append the type tree to the end of the diagnostics.
   OutStr.append(Tree.begin(), Tree.end());
 }
 
 StoredDiagnostic::StoredDiagnostic(DiagnosticsEngine::Level Level, unsigned ID,
-                                   StringRef Message)
-    : ID(ID), Level(Level), Message(Message) {}
+                                   StringRef Message, DiagnosticReason Reason)
+    : ID(ID), Level(Level), Message(Message), Reason(std::move(Reason)) {}
 
 StoredDiagnostic::StoredDiagnostic(DiagnosticsEngine::Level Level,
                                    const Diagnostic &Info)
     : ID(Info.getID()), Level(Level) {
   assert((Info.getLocation().isInvalid() || Info.hasSourceManager()) &&
        "Valid source location without setting a source manager for diagnostic");
   if (Info.getLocation().isValid())
     Loc = FullSourceLoc(Info.getLocation(), Info.getSourceManager());
   SmallString<64> Message;
-  Info.FormatDiagnostic(Message);
+  Info.FormatSummary(Message);
   this->Message.assign(Message.begin(), Message.end());
   this->Ranges.assign(Info.getRanges().begin(), Info.getRanges().end());
   this->FixIts.assign(Info.getFixItHints().begin(), Info.getFixItHints().end());
 }
 
 StoredDiagnostic::StoredDiagnostic(DiagnosticsEngine::Level Level, unsigned ID,
-                                   StringRef Message, FullSourceLoc Loc,
+                                   StringRef Message, DiagnosticReason Reason,
+                                   FullSourceLoc Loc,
                                    ArrayRef<CharSourceRange> Ranges,
                                    ArrayRef<FixItHint> FixIts)
-    : ID(ID), Level(Level), Loc(Loc), Message(Message),
-      Ranges(Ranges.begin(), Ranges.end()), FixIts(FixIts.begin(), FixIts.end())
-{
-}
+    : ID(ID), Level(Level), Loc(Loc), Message(Message), Reason(Reason),
+      Ranges(Ranges.begin(), Ranges.end()),
+      FixIts(FixIts.begin(), FixIts.end()) {}
 
 llvm::raw_ostream &clang::operator<<(llvm::raw_ostream &OS,
                                      const StoredDiagnostic &SD) {
   if (SD.getLocation().hasManager())
     OS << SD.getLocation().printToString(SD.getLocation().getManager()) << ": ";
   OS << SD.getMessage();
   return OS;
 }

clang/lib/Basic/DiagnosticIDs.cpp

 
 struct StaticDiagInfoRec;
 
 // Store the descriptions in a separate table to avoid pointers that need to
 // be relocated, and also decrease the amount of data needed on 64-bit
 // platforms. See "How To Write Shared Libraries" by Ulrich Drepper.
 struct StaticDiagInfoDescriptionStringTable {
 #define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   char ENUM##_desc[sizeof(DESC)];
   // clang-format off
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #include "clang/Basic/DiagnosticCrossTUKinds.inc"
 #include "clang/Basic/DiagnosticSemaKinds.inc"
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
 #include "clang/Basic/DiagnosticRefactoringKinds.inc"
   // clang-format on
 #undef DIAG
 };
 
 const StaticDiagInfoDescriptionStringTable StaticDiagInfoDescriptions = {
 #define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   DESC,
 // clang-format off
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #include "clang/Basic/DiagnosticCrossTUKinds.inc"
 #include "clang/Basic/DiagnosticSemaKinds.inc"
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
 #include "clang/Basic/DiagnosticRefactoringKinds.inc"
-  // clang-format on
 #undef DIAG
 };
 
 extern const StaticDiagInfoRec StaticDiagInfo[];
 
 // Stored separately from StaticDiagInfoRec to pack better.  Otherwise,
 // StaticDiagInfoRec would have extra padding on 64-bit platforms.
 const uint32_t StaticDiagInfoDescriptionOffsets[] = {
 #define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
   offsetof(StaticDiagInfoDescriptionStringTable, ENUM##_desc),
 // clang-format off
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #include "clang/Basic/DiagnosticCrossTUKinds.inc"
 #include "clang/Basic/DiagnosticSemaKinds.inc"
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
 #include "clang/Basic/DiagnosticRefactoringKinds.inc"
-  // clang-format on
 #undef DIAG
 };
 
+// Reason.Legacy
+struct StaticDiagInfoUnstructuredReasonStringTable {
+#define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
+  char ENUM##_legacy_reason[sizeof(LEGACY_REASON)];
+  // clang-format off
+#include "clang/Basic/DiagnosticCommonKinds.inc"
+#include "clang/Basic/DiagnosticDriverKinds.inc"
+#include "clang/Basic/DiagnosticFrontendKinds.inc"
+#include "clang/Basic/DiagnosticSerializationKinds.inc"
+#include "clang/Basic/DiagnosticLexKinds.inc"
+#include "clang/Basic/DiagnosticParseKinds.inc"
+#include "clang/Basic/DiagnosticASTKinds.inc"
+#include "clang/Basic/DiagnosticCommentKinds.inc"
+#include "clang/Basic/DiagnosticCrossTUKinds.inc"
+#include "clang/Basic/DiagnosticSemaKinds.inc"
+#include "clang/Basic/DiagnosticAnalysisKinds.inc"
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
+  // clang-format on
+#undef DIAG
+};
+
+const StaticDiagInfoUnstructuredReasonStringTable
+    StaticDiagInfoUnstructuredReasons = {
+#define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
+  LEGACY_REASON,
+// clang-format off
+#include "clang/Basic/DiagnosticCommonKinds.inc"
+#include "clang/Basic/DiagnosticDriverKinds.inc"
+#include "clang/Basic/DiagnosticFrontendKinds.inc"
+#include "clang/Basic/DiagnosticSerializationKinds.inc"
+#include "clang/Basic/DiagnosticLexKinds.inc"
+#include "clang/Basic/DiagnosticParseKinds.inc"
+#include "clang/Basic/DiagnosticASTKinds.inc"
+#include "clang/Basic/DiagnosticCommentKinds.inc"
+#include "clang/Basic/DiagnosticCrossTUKinds.inc"
+#include "clang/Basic/DiagnosticSemaKinds.inc"
+#include "clang/Basic/DiagnosticAnalysisKinds.inc"
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
+// clang-format on
+#undef DIAG
+};
+
+// Stored separately from StaticDiagInfoRec to pack better.  Otherwise,
+// StaticDiagInfoRec would have extra padding on 64-bit platforms.
+const uint32_t StaticDiagInfoUnstructuredReasonOffsets[] = {
+#define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
+  offsetof(StaticDiagInfoUnstructuredReasonStringTable, ENUM##_legacy_reason),
+// clang-format off
+#include "clang/Basic/DiagnosticCommonKinds.inc"
+#include "clang/Basic/DiagnosticDriverKinds.inc"
+#include "clang/Basic/DiagnosticFrontendKinds.inc"
+#include "clang/Basic/DiagnosticSerializationKinds.inc"
+#include "clang/Basic/DiagnosticLexKinds.inc"
+#include "clang/Basic/DiagnosticParseKinds.inc"
+#include "clang/Basic/DiagnosticASTKinds.inc"
+#include "clang/Basic/DiagnosticCommentKinds.inc"
+#include "clang/Basic/DiagnosticCrossTUKinds.inc"
+#include "clang/Basic/DiagnosticSemaKinds.inc"
+#include "clang/Basic/DiagnosticAnalysisKinds.inc"
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
+// clang-format on
+#undef DIAG
+};
+
+// Reason.SARIF
+struct StaticDiagInfoStructuredReasonStringTable {
+#define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
+  char ENUM##_sarif_reason[sizeof(SARIF_REASON)];
+  // clang-format off
+#include "clang/Basic/DiagnosticCommonKinds.inc"
+#include "clang/Basic/DiagnosticDriverKinds.inc"
+#include "clang/Basic/DiagnosticFrontendKinds.inc"
+#include "clang/Basic/DiagnosticSerializationKinds.inc"
+#include "clang/Basic/DiagnosticLexKinds.inc"
+#include "clang/Basic/DiagnosticParseKinds.inc"
+#include "clang/Basic/DiagnosticASTKinds.inc"
+#include "clang/Basic/DiagnosticCommentKinds.inc"
+#include "clang/Basic/DiagnosticCrossTUKinds.inc"
+#include "clang/Basic/DiagnosticSemaKinds.inc"
+#include "clang/Basic/DiagnosticAnalysisKinds.inc"
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
+  // clang-format on
+#undef DIAG
+};
+
+const StaticDiagInfoStructuredReasonStringTable
+    StaticDiagInfoStructuredReasons = {
+#define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
+  SARIF_REASON,
+// clang-format off
+#include "clang/Basic/DiagnosticCommonKinds.inc"
+#include "clang/Basic/DiagnosticDriverKinds.inc"
+#include "clang/Basic/DiagnosticFrontendKinds.inc"
+#include "clang/Basic/DiagnosticSerializationKinds.inc"
+#include "clang/Basic/DiagnosticLexKinds.inc"
+#include "clang/Basic/DiagnosticParseKinds.inc"
+#include "clang/Basic/DiagnosticASTKinds.inc"
+#include "clang/Basic/DiagnosticCommentKinds.inc"
+#include "clang/Basic/DiagnosticCrossTUKinds.inc"
+#include "clang/Basic/DiagnosticSemaKinds.inc"
+#include "clang/Basic/DiagnosticAnalysisKinds.inc"
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
+// clang-format on
+#undef DIAG
+};
+
+// Stored separately from StaticDiagInfoRec to pack better.  Otherwise,
+// StaticDiagInfoRec would have extra padding on 64-bit platforms.
+const uint32_t StaticDiagInfoStructuredReasonOffsets[] = {
+#define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             LEGACY_REASON, SARIF_REASON)                                      \
+  offsetof(StaticDiagInfoStructuredReasonStringTable, ENUM##_sarif_reason),
+// clang-format off
+#include "clang/Basic/DiagnosticCommonKinds.inc"
+#include "clang/Basic/DiagnosticDriverKinds.inc"
+#include "clang/Basic/DiagnosticFrontendKinds.inc"
+#include "clang/Basic/DiagnosticSerializationKinds.inc"
+#include "clang/Basic/DiagnosticLexKinds.inc"
+#include "clang/Basic/DiagnosticParseKinds.inc"
+#include "clang/Basic/DiagnosticASTKinds.inc"
+#include "clang/Basic/DiagnosticCommentKinds.inc"
+#include "clang/Basic/DiagnosticCrossTUKinds.inc"
+#include "clang/Basic/DiagnosticSemaKinds.inc"
+#include "clang/Basic/DiagnosticAnalysisKinds.inc"
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
+// clang-format on
+#undef DIAG
+};
+
 // Diagnostic classes.
 enum {
-  CLASS_NOTE       = 0x01,
-  CLASS_REMARK     = 0x02,
-  CLASS_WARNING    = 0x03,
-  CLASS_EXTENSION  = 0x04,
-  CLASS_ERROR      = 0x05
+  CLASS_NOTE = 0x01,
+  CLASS_REMARK = 0x02,
+  CLASS_WARNING = 0x03,
+  CLASS_EXTENSION = 0x04,
+  CLASS_ERROR = 0x05
 };
 
 struct StaticDiagInfoRec {
   uint16_t DiagID;
   uint8_t DefaultSeverity : 3;
   uint8_t Class : 3;
   uint8_t SFINAE : 2;
   uint8_t Category : 6;
   uint8_t WarnNoWerror : 1;
   uint8_t WarnShowInSystemHeader : 1;
   uint8_t WarnShowInSystemMacro : 1;
 
   uint16_t OptionGroupIndex : 15;
   uint16_t Deferrable : 1;
 
   uint16_t DescriptionLen;
+  uint16_t UnstructuredReasonLen;
+  uint16_t StructuredReasonLen;
 
-  unsigned getOptionGroupIndex() const {
-    return OptionGroupIndex;
-  }
+  unsigned getOptionGroupIndex() const { return OptionGroupIndex; }
 
   StringRef getDescription() const {
     size_t MyIndex = this - &StaticDiagInfo[0];
     uint32_t StringOffset = StaticDiagInfoDescriptionOffsets[MyIndex];
-    const char* Table = reinterpret_cast<const char*>(&StaticDiagInfoDescriptions);
+    const char *Table =
+        reinterpret_cast<const char *>(&StaticDiagInfoDescriptions);
     return StringRef(&Table[StringOffset], DescriptionLen);
   }
 
+  StringRef getUnstructuredReason() const {
+    size_t MyIndex = this - &StaticDiagInfo[0];
+    uint32_t StringOffset = StaticDiagInfoUnstructuredReasonOffsets[MyIndex];
+    const char *Table =
+        reinterpret_cast<const char *>(&StaticDiagInfoUnstructuredReasons);
+    return StringRef(&Table[StringOffset], UnstructuredReasonLen);
+  }
+
+  StringRef getStructuredReason() const {
+    size_t MyIndex = this - &StaticDiagInfo[0];
+    uint32_t StringOffset = StaticDiagInfoStructuredReasonOffsets[MyIndex];
+    const char *Table =
+        reinterpret_cast<const char *>(&StaticDiagInfoStructuredReasons);
+    return StringRef(&Table[StringOffset], StructuredReasonLen);
+  }
+
   diag::Flavor getFlavor() const {
     return Class == CLASS_REMARK ? diag::Flavor::Remark
                                  : diag::Flavor::WarningOrError;
   }
 
   bool operator<(const StaticDiagInfoRec &RHS) const {
     return DiagID < RHS.DiagID;
   }

 VALIDATE_DIAG_SIZE(ANALYSIS)
 VALIDATE_DIAG_SIZE(REFACTORING)
 #undef VALIDATE_DIAG_SIZE
 #undef STRINGIFY_NAME
 
 const StaticDiagInfoRec StaticDiagInfo[] = {
 // clang-format off
 #define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, LEGACY_REASON, SARIF_REASON)            \
   {                                                                            \
       diag::ENUM,                                                              \
       DEFAULT_SEVERITY,                                                        \
       CLASS,                                                                   \
       DiagnosticIDs::SFINAE,                                                   \
       CATEGORY,                                                                \
       NOWERROR,                                                                \
       SHOWINSYSHEADER,                                                         \
       SHOWINSYSMACRO,                                                          \
       GROUP,                                                                   \
       DEFERRABLE,                                                              \
-      STR_SIZE(DESC, uint16_t)},
+      STR_SIZE(DESC, uint16_t), \
+      STR_SIZE(LEGACY_REASON, uint16_t), \
+      STR_SIZE(SARIF_REASON, uint16_t)},
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
static const StaticDiagInfoRec *GetDiagInfo(unsigned DiagID) {
   //    diagnostic and of the category the diagnostic is in. This gives us
   //    the offset of the category in the table.
   // 2. Subtract the number of IDs in each category from our ID. This gives us
   //    the offset of the diagnostic in the category.
   // This is cheaper than a binary search on the table as it doesn't touch
   // memory at all.
   unsigned Offset = 0;
   unsigned ID = DiagID - DIAG_START_COMMON - 1;
-#define CATEGORY(NAME, PREV) \
-  if (DiagID > DIAG_START_##NAME) { \
-    Offset += NUM_BUILTIN_##PREV##_DIAGNOSTICS - DIAG_START_##PREV - 1; \
-    ID -= DIAG_START_##NAME - DIAG_START_##PREV; \
+#define CATEGORY(NAME, PREV)                                                   \
+  if (DiagID > DIAG_START_##NAME) {                                            \
+    Offset += NUM_BUILTIN_##PREV##_DIAGNOSTICS - DIAG_START_##PREV - 1;        \
+    ID -= DIAG_START_##NAME - DIAG_START_##PREV;                               \
   }
   CATEGORY(DRIVER, COMMON)
   CATEGORY(FRONTEND, DRIVER)
   CATEGORY(SERIALIZATION, FRONTEND)
   CATEGORY(LEX, SERIALIZATION)
   CATEGORY(PARSE, LEX)
   CATEGORY(AST, PARSE)
   CATEGORY(COMMENT, AST)
   CATEGORY(CROSSTU, COMMENT)
   CATEGORY(SEMA, CROSSTU)
   CATEGORY(ANALYSIS, SEMA)
   CATEGORY(REFACTORING, ANALYSIS)
 #undef CATEGORY
 
   // Avoid out of bounds reads.
   if (ID + Offset >= StaticDiagInfoSize)
     return nullptr;
 
   assert(ID < StaticDiagInfoSize && Offset < StaticDiagInfoSize);
 

 /// DiagID belongs to, or 0 if no category.
 unsigned DiagnosticIDs::getCategoryNumberForDiag(unsigned DiagID) {
   if (const StaticDiagInfoRec *Info = GetDiagInfo(DiagID))
     return Info->Category;
   return 0;
 }
 
 namespace {
-  // The diagnostic category names.
-  struct StaticDiagCategoryRec {
-    const char *NameStr;
-    uint8_t NameLen;
 
-    StringRef getName() const {
-      return StringRef(NameStr, NameLen);
-    }
-  };
-}
+  StringRef getName() const { return StringRef(NameStr, NameLen); }
+} // namespace
 
 // Unfortunately, the split between DiagnosticIDs and Diagnostic is not
 // particularly clean, but for now we just implement this method here so we can
 // access GetDefaultDiagMapping.
 DiagnosticMapping &
 DiagnosticsEngine::DiagState::getOrAddMapping(diag::kind Diag) {
   std::pair<iterator, bool> Result =
       DiagMap.insert(std::make_pair(Diag, DiagnosticMapping()));
 
   // Initialize the entry if we added it.
   if (Result.second)
     Result.first->second = GetDefaultDiagMapping(Diag);
 
   return Result.first->second;
 }
 
 static const StaticDiagCategoryRec CategoryNameTable[] = {
 #define GET_CATEGORY_TABLE
-#define CATEGORY(X, ENUM) { X, STR_SIZE(X, uint8_t) },
+#define CATEGORY(X, ENUM) {X, STR_SIZE(X, uint8_t)},
 #include "clang/Basic/DiagnosticGroups.inc"
 #undef GET_CATEGORY_TABLE
-  { nullptr, 0 }
-};
+    {nullptr, 0}};
 
 /// getNumberOfCategories - Return the number of categories
 unsigned DiagnosticIDs::getNumberOfCategories() {
   return std::size(CategoryNameTable) - 1;
 }
 
 /// getCategoryNameFromID - Given a category ID, return the name of the
 /// category, an empty string if CategoryID is zero, or null if CategoryID is
 /// invalid.
 StringRef DiagnosticIDs::getCategoryNameFromID(unsigned CategoryID) {
   if (CategoryID >= getNumberOfCategories())
     return StringRef();
   return CategoryNameTable[CategoryID].getName();
 }
 
-
-
 DiagnosticIDs::SFINAEResponse
 DiagnosticIDs::getDiagnosticSFINAEResponse(unsigned DiagID) {
   if (const StaticDiagInfoRec *Info = GetDiagInfo(DiagID))
     return static_cast<DiagnosticIDs::SFINAEResponse>(Info->SFINAE);
   return SFINAE_Report;
 }
 
 bool DiagnosticIDs::isDeferrable(unsigned DiagID) {
static unsigned getBuiltinDiagClass(unsigned DiagID) {
   return ~0U;
 }
 
 //===----------------------------------------------------------------------===//
 // Custom Diagnostic information
 //===----------------------------------------------------------------------===//
 
 namespace clang {
-  namespace diag {
-    class CustomDiagInfo {
-      typedef std::pair<DiagnosticIDs::Level, std::string> DiagDesc;
-      std::vector<DiagDesc> DiagInfo;
-      std::map<DiagDesc, unsigned> DiagIDs;
-    public:
+  struct DiagDesc {
+    DiagnosticIDs::Level Level;
+    std::string Message;
+    DiagnosticReason Reason;
+
+    // FIXME(spaceship): default when C++20 becomes the default
+    bool operator==(const DiagDesc &Other) const {
+      return std::tie(Level, Message, Reason) ==
+             std::tie(Other.Level, Other.Message, Other.Reason);
+    }
+
+    bool operator!=(const DiagDesc &Other) const { return !(*this == Other); }
+
+    bool operator<(const DiagDesc &Other) const {
+      return std::tie(Level, Message, Reason) <
+             std::tie(Other.Level, Other.Message, Other.Reason);
+    }
+
+    bool operator>(const DiagDesc &Other) const { return Other < *this; }
+
+    bool operator<=(const DiagDesc &Other) const { return !(Other < *this); }
+
+    bool operator>=(const DiagDesc &Other) const { return !(*this < Other); }
+  };
 
-      /// getDescription - Return the description of the specified custom
-      /// diagnostic.
-      StringRef getDescription(unsigned DiagID) const {
-        assert(DiagID - DIAG_UPPER_LIMIT < DiagInfo.size() &&
-               "Invalid diagnostic ID");
-        return DiagInfo[DiagID-DIAG_UPPER_LIMIT].second;
-      }
+  bool IsValidDiagnosticID(unsigned DiagID) const {
+    return DiagID - DIAG_UPPER_LIMIT < DiagInfo.size();
+  }
+
+public:
+    assert(IsValidDiagnosticID(DiagID) && "Invalid diagnostic ID");
+    return DiagInfo[DiagID - DIAG_UPPER_LIMIT].Message;
+  }
+
+  StringRef getLegacyReason(unsigned DiagID) const {
+    assert(IsValidDiagnosticID(DiagID) && "Invalid diagnostic ID");
+    return DiagInfo[DiagID - DIAG_UPPER_LIMIT].Reason.Legacy.Value;
+  }
+
+  StringRef getSARIFReason(unsigned DiagID) const {
+    assert(IsValidDiagnosticID(DiagID) && "Invalid diagnostic ID");
+    return DiagInfo[DiagID - DIAG_UPPER_LIMIT].Reason.SARIF;
 
-      /// getLevel - Return the level of the specified custom diagnostic.
-      DiagnosticIDs::Level getLevel(unsigned DiagID) const {
-        assert(DiagID - DIAG_UPPER_LIMIT < DiagInfo.size() &&
-               "Invalid diagnostic ID");
-        return DiagInfo[DiagID-DIAG_UPPER_LIMIT].first;
-      }
+    assert(IsValidDiagnosticID(DiagID) && "Invalid diagnostic ID");
+    return DiagInfo[DiagID - DIAG_UPPER_LIMIT].Level;
 
-      unsigned getOrCreateDiagID(DiagnosticIDs::Level L, StringRef Message,
-                                 DiagnosticIDs &Diags) {
-        DiagDesc D(L, std::string(Message));
-        // Check to see if it already exists.
-        std::map<DiagDesc, unsigned>::iterator I = DiagIDs.lower_bound(D);
-        if (I != DiagIDs.end() && I->first == D)
-          return I->second;
+                             const DiagnosticReason &Reason,
+    DiagDesc D{L, std::string(Message), Reason};
 
-        // If not, assign a new ID.
-        unsigned ID = DiagInfo.size()+DIAG_UPPER_LIMIT;
-        DiagIDs.insert(std::make_pair(D, ID));
-        DiagInfo.push_back(D);
-        return ID;
-      }
-    };
+    unsigned ID = DiagInfo.size() + DIAG_UPPER_LIMIT;
 
-  } // end diag namespace
-} // end clang namespace
-
+} // namespace diag
+} // namespace clang
 
 //===----------------------------------------------------------------------===//
 // Common Diagnostic implementation
 //===----------------------------------------------------------------------===//
 
 DiagnosticIDs::DiagnosticIDs() {}
 
 DiagnosticIDs::~DiagnosticIDs() {}
 
 /// getCustomDiagID - Return an ID for a diagnostic with the specified message
 /// and level.  If this is the first request for this diagnostic, it is
 /// registered and created, otherwise the existing ID is returned.
 ///
 /// \param FormatString A fixed diagnostic format string that will be hashed and
 /// mapped to a unique DiagID.
-unsigned DiagnosticIDs::getCustomDiagID(Level L, StringRef FormatString) {
+unsigned DiagnosticIDs::getCustomDiagID(Level L, StringRef FormatString,
+                                        const DiagnosticReason &Reason) {
   if (!CustomDiagInfo)
     CustomDiagInfo.reset(new diag::CustomDiagInfo());
-  return CustomDiagInfo->getOrCreateDiagID(L, FormatString, *this);
+  return CustomDiagInfo->getOrCreateDiagID(L, FormatString, Reason, *this);
 }
 
-
 /// isBuiltinWarningOrExtension - Return true if the unmapped diagnostic
 /// level of the specified diagnostic ID is a Warning or Extension.
 /// This only works on builtin diagnostics, not custom ones, and is not legal to
 /// call on NOTEs.
 bool DiagnosticIDs::isBuiltinWarningOrExtension(unsigned DiagID) {
   return DiagID < diag::DIAG_UPPER_LIMIT &&
          getBuiltinDiagClass(DiagID) != CLASS_ERROR;
 }
 
 /// Determine whether the given built-in diagnostic ID is a
 /// Note.
 bool DiagnosticIDs::isBuiltinNote(unsigned DiagID) {
   return DiagID < diag::DIAG_UPPER_LIMIT &&
          getBuiltinDiagClass(DiagID) == CLASS_NOTE;
 }
 
 /// isBuiltinExtensionDiag - Determine whether the given built-in diagnostic
 /// ID is for an extension of some sort.  This also returns EnabledByDefault,
 /// which is set to indicate whether the diagnostic is ignored by default (in
 /// which case -pedantic enables it) or treated as a warning/error by default.
 ///
 bool DiagnosticIDs::isBuiltinExtensionDiag(unsigned DiagID,
                                            bool &EnabledByDefault) {
   if (DiagID >= diag::DIAG_UPPER_LIMIT ||
       getBuiltinDiagClass(DiagID) != CLASS_EXTENSION)
     return false;
 
   EnabledByDefault =
       GetDefaultDiagMapping(DiagID).getSeverity() != diag::Severity::Ignored;
   return true;
 }

 /// issue.
 StringRef DiagnosticIDs::getDescription(unsigned DiagID) const {
   if (const StaticDiagInfoRec *Info = GetDiagInfo(DiagID))
     return Info->getDescription();
   assert(CustomDiagInfo && "Invalid CustomDiagInfo");
   return CustomDiagInfo->getDescription(DiagID);
 }
 
+StringRef DiagnosticIDs::getLegacyReason(unsigned DiagID) const {
+  if (const StaticDiagInfoRec *Info = GetDiagInfo(DiagID))
+    return Info->getUnstructuredReason();
+  assert(CustomDiagInfo && "Invalid CustomDiagInfo");
+  return CustomDiagInfo->getLegacyReason(DiagID);
+}
+
+StringRef DiagnosticIDs::getSARIFReason(unsigned DiagID) const {
+  if (const StaticDiagInfoRec *Info = GetDiagInfo(DiagID))
+    return Info->getStructuredReason();
+  assert(CustomDiagInfo && "Invalid CustomDiagInfo");
+  return CustomDiagInfo->getSARIFReason(DiagID);
+}
+
 static DiagnosticIDs::Level toLevel(diag::Severity SV) {
   switch (SV) {
   case diag::Severity::Ignored:
     return DiagnosticIDs::Ignored;
   case diag::Severity::Remark:
     return DiagnosticIDs::Remark;
   case diag::Severity::Warning:
     return DiagnosticIDs::Warning;
DiagnosticIDs::getDiagnosticLevel(unsigned DiagID, SourceLocation Loc,
                                   const DiagnosticsEngine &Diag) const {
   // Handle custom diagnostics, which cannot be mapped.
   if (DiagID >= diag::DIAG_UPPER_LIMIT) {
     assert(CustomDiagInfo && "Invalid CustomDiagInfo");
     return CustomDiagInfo->getLevel(DiagID);
   }
 
   unsigned DiagClass = getBuiltinDiagClass(DiagID);
-  if (DiagClass == CLASS_NOTE) return DiagnosticIDs::Note;
+  if (DiagClass == CLASS_NOTE)
+    return DiagnosticIDs::Note;
   return toLevel(getDiagnosticSeverity(DiagID, Loc, Diag));
 }
 
 /// Based on the way the client configured the Diagnostic
 /// object, classify the specified diagnostic ID into a Level, consumable by
 /// the DiagnosticClient.
 ///
 /// \param Loc The source location we are interested in finding out the
DiagnosticIDs::getDiagnosticSeverity(unsigned DiagID, SourceLocation Loc,
 
   return Result;
 }
 
 #define GET_DIAG_ARRAYS
 #include "clang/Basic/DiagnosticGroups.inc"
 #undef GET_DIAG_ARRAYS
 
 namespace {
-  struct WarningOption {
-    uint16_t NameOffset;
-    uint16_t Members;
-    uint16_t SubGroups;
-    StringRef Documentation;
 
-    // String is stored with a pascal-style length byte.
-    StringRef getName() const {
-      return StringRef(DiagGroupNames + NameOffset + 1,
-                       DiagGroupNames[NameOffset]);
-    }
-  };
-}
+} // namespace
 
 // Second the table of options, sorted by name for fast binary lookup.
 static const WarningOption OptionTable[] = {
 #define DIAG_ENTRY(GroupName, FlagNameOffset, Members, SubGroups, Docs)        \
   {FlagNameOffset, Members, SubGroups, Docs},
 #include "clang/Basic/DiagnosticGroups.inc"
 #undef DIAG_ENTRY
 };
if (GetDiagInfo(*Member)->getFlavor() == Flavor) {
       NotFound = false;
       Diags.push_back(*Member);
     }
   }
 
   // Add the members of the subgroups.
   const int16_t *SubGroups = DiagSubGroups + Group->SubGroups;
   for (; *SubGroups != (int16_t)-1; ++SubGroups)
-    NotFound &= getDiagnosticsInGroup(Flavor, &OptionTable[(short)*SubGroups],
-                                      Diags);
+    NotFound &=
+        getDiagnosticsInGroup(Flavor, &OptionTable[(short)*SubGroups], Diags);
 
   return NotFound;
 }
 
-bool
-DiagnosticIDs::getDiagnosticsInGroup(diag::Flavor Flavor, StringRef Group,
-                                     SmallVectorImpl<diag::kind> &Diags) const {
+bool DiagnosticIDs::getDiagnosticsInGroup(
+    diag::Flavor Flavor, StringRef Group,
   if (llvm::Optional<diag::Group> G = getGroupForWarningOption(Group))
     return ::getDiagnosticsInGroup(
         Flavor, &OptionTable[static_cast<unsigned>(*G)], Diags);
   return true;
 }
 
 void DiagnosticIDs::getAllDiagnostics(diag::Flavor Flavor,
                                       std::vector<diag::kind> &Diags) {

 /// finally fully formed.
 bool DiagnosticIDs::ProcessDiag(DiagnosticsEngine &Diag) const {
   Diagnostic Info(&Diag);
 
   assert(Diag.getClient() && "DiagnosticClient not set!");
 
   // Figure out the diagnostic level of this message.
   unsigned DiagID = Info.getID();
-  DiagnosticIDs::Level DiagLevel
-    = getDiagnosticLevel(DiagID, Info.getLocation(), Diag);
+  DiagnosticIDs::Level DiagLevel =
+      getDiagnosticLevel(DiagID, Info.getLocation(), Diag);
 
   // Update counts for DiagnosticErrorTrap even if a fatal error occurred
   // or diagnostics are suppressed.
   if (DiagLevel >= DiagnosticIDs::Error) {
     ++Diag.TrapNumErrorsOccurred;
     if (isUnrecoverable(DiagID))
       ++Diag.TrapNumUnrecoverableErrorsOccurred;
   }
if (Diag.CurDiagID == diag::fatal_too_many_errors)
     Diag.FatalErrorOccurred = true;
   // Finally, report it.
   EmitDiag(Diag, DiagLevel);
   return true;
 }
 
 void DiagnosticIDs::EmitDiag(DiagnosticsEngine &Diag, Level DiagLevel) const {
   Diagnostic Info(&Diag);
-  assert(DiagLevel != DiagnosticIDs::Ignored && "Cannot emit ignored diagnostics!");
+  assert(DiagLevel != DiagnosticIDs::Ignored &&
+         "Cannot emit ignored diagnostics!");
 
   Diag.Client->HandleDiagnostic((DiagnosticsEngine::Level)DiagLevel, Info);
   if (Diag.Client->IncludeInDiagnosticCounts()) {
     if (DiagLevel == DiagnosticIDs::Warning)
       ++Diag.NumWarnings;
   }
 
   Diag.CurDiagID = ~0U;

clang/lib/Format/TokenAnalyzer.cpp

 // better way to return errors through the format APIs.
 class FatalDiagnosticConsumer : public DiagnosticConsumer {
 public:
   void HandleDiagnostic(DiagnosticsEngine::Level DiagLevel,
                         const Diagnostic &Info) override {
     if (DiagLevel == DiagnosticsEngine::Fatal) {
       Fatal = true;
       llvm::SmallVector<char, 128> Message;
-      Info.FormatDiagnostic(Message);
+      Info.FormatLegacyDiagnostic(Message);
       llvm::errs() << Message << "\n";
     }
   }
 
   bool fatalError() const { return Fatal; }
 
 private:
   bool Fatal = false;

clang/lib/Frontend/ASTUnit.cpp

for (const auto &FixIt : SD.FixIts) {
       FixIts.push_back(FixItHint());
       FixItHint &FH = FixIts.back();
       FH.CodeToInsert = FixIt.CodeToInsert;
       SourceLocation BL = FileLoc.getLocWithOffset(FixIt.RemoveRange.first);
       SourceLocation EL = FileLoc.getLocWithOffset(FixIt.RemoveRange.second);
       FH.RemoveRange = CharSourceRange::getCharRange(BL, EL);
     }
 
-    Result.push_back(StoredDiagnostic(SD.Level, SD.ID,
-                                      SD.Message, Loc, Ranges, FixIts));
+    Result.push_back(StoredDiagnostic(SD.Level, SD.ID, SD.Message, SD.Reason,
+                                      Loc, Ranges, FixIts));
   }
   Result.swap(Out);
 }
 
 void ASTUnit::addFileLevelDecl(Decl *D) {
   assert(D);
 
   // We only care about local declarations.

clang/lib/Frontend/LogDiagnosticPrinter.cpp

void LogDiagnosticPrinter::HandleDiagnostic(DiagnosticsEngine::Level Level,
   DE.DiagnosticID = Info.getID();
   DE.DiagnosticLevel = Level;
 
   DE.WarningOption =
       std::string(DiagnosticIDs::getWarningOptionForDiag(DE.DiagnosticID));
 
   // Format the message.
   SmallString<100> MessageStr;
-  Info.FormatDiagnostic(MessageStr);
+  Info.FormatLegacyDiagnostic(MessageStr);
   DE.Message = std::string(MessageStr.str());
 
   // Set the location information.
   DE.Filename = "";
   DE.Line = DE.Column = 0;
   if (Info.getLocation().isValid() && Info.hasSourceManager()) {
     const SourceManager &SM = Info.getSourceManager();
     PresumedLoc PLoc = SM.getPresumedLoc(Info.getLocation());
if (PLoc.isInvalid()) {
       DE.Line = PLoc.getLine();
       DE.Column = PLoc.getColumn();
     }
   }
 
   // Record the diagnostic entry.
   Entries.push_back(DE);
 }
-

clang/lib/Frontend/SARIFDiagnosticPrinter.cpp

void SARIFDiagnosticPrinter::HandleDiagnostic(DiagnosticsEngine::Level Level,
   assert(SARIFDiag && "SARIFDiagnostic has not been set.");
   // Default implementation (Warnings/errors count). Keeps track of the
   // number of errors.
   DiagnosticConsumer::HandleDiagnostic(Level, Info);
 
   // Render the diagnostic message into a temporary buffer eagerly. We'll use
   // this later as we add the diagnostic to the SARIF object.
   SmallString<100> OutStr;
-  Info.FormatDiagnostic(OutStr);
+  Info.FormatSummary(OutStr);
+  Info.FormatSARIFReason(OutStr);
 
   llvm::raw_svector_ostream DiagMessageStream(OutStr);
 
   // Use a dedicated, simpler path for diagnostics without a valid location.
   // This is important as if the location is missing, we may be emitting
   // diagnostics in a context that lacks language options, a source manager, or
   // other infrastructure necessary when emitting more rich diagnostics.
   if (Info.getLocation().isInvalid()) {

clang/lib/Frontend/SerializedDiagnosticPrinter.cpp

 }
 
 void SDiagsWriter::HandleDiagnostic(DiagnosticsEngine::Level DiagLevel,
                                     const Diagnostic &Info) {
   assert(!IsFinishing &&
          "Received a diagnostic after we've already started teardown.");
   if (IsFinishing) {
     SmallString<256> diagnostic;
-    Info.FormatDiagnostic(diagnostic);
+    Info.FormatLegacyDiagnostic(diagnostic);
     getMetaDiags()->Report(
         diag::warn_fe_serialized_diag_failure_during_finalisation)
         << diagnostic;
     return;
   }
 
   // Enter the block for a non-note diagnostic immediately, rather than waiting
   // for beginDiagnostic, in case associated notes are emitted before we get
   // there.
   if (DiagLevel != DiagnosticsEngine::Note) {
     if (State->EmittedAnyDiagBlocks)
       ExitDiagBlock();
 
     EnterDiagBlock();
     State->EmittedAnyDiagBlocks = true;
   }
 
   // Compute the diagnostic text.
   State->diagBuf.clear();
-  Info.FormatDiagnostic(State->diagBuf);
+  Info.FormatLegacyDiagnostic(State->diagBuf);
 
   if (Info.getLocation().isInvalid()) {
     // Special-case diagnostics with no location. We may not have entered a
     // source file in this case, so we can't use the normal DiagnosticsRenderer
     // machinery.
 
     // Make sure we bracket all notes as "sub-diagnostics".  This matches
     // the behavior in SDiagsRenderer::emitDiagnostic().

clang/lib/Frontend/TextDiagnosticBuffer.cpp

 /// HandleDiagnostic - Store the errors, warnings, and notes that are
 /// reported.
 void TextDiagnosticBuffer::HandleDiagnostic(DiagnosticsEngine::Level Level,
                                             const Diagnostic &Info) {
   // Default implementation (Warnings/errors count).
   DiagnosticConsumer::HandleDiagnostic(Level, Info);
 
   SmallString<100> Buf;
-  Info.FormatDiagnostic(Buf);
+  Info.FormatLegacyDiagnostic(Buf);
   switch (Level) {
   default: llvm_unreachable(
                          "Diagnostic not handled during diagnostic buffering!");
   case DiagnosticsEngine::Note:
     All.emplace_back(Level, Notes.size());
     Notes.emplace_back(Info.getLocation(), std::string(Buf.str()));
     break;
   case DiagnosticsEngine::Warning:

clang/lib/Frontend/TextDiagnosticPrinter.cpp

 void TextDiagnosticPrinter::HandleDiagnostic(DiagnosticsEngine::Level Level,
                                              const Diagnostic &Info) {
   // Default implementation (Warnings/errors count).
   DiagnosticConsumer::HandleDiagnostic(Level, Info);
 
   // Render the diagnostic message into a temporary buffer eagerly. We'll use
   // this later as we print out the diagnostic to the terminal.
   SmallString<100> OutStr;
-  Info.FormatDiagnostic(OutStr);
+  Info.FormatLegacyDiagnostic(OutStr);
 
   llvm::raw_svector_ostream DiagMessageStream(OutStr);
   printDiagnosticOptions(DiagMessageStream, Level, Info, *DiagOpts);
 
   // Keeps track of the starting position of the location
   // information (e.g., "foo.c:10:4:") that precedes the error
   // message. We use this information to determine how long the
   // file+line+column number prefix is.

clang/lib/Sema/SemaOverload.cpp

if (getLangOpts().CPlusPlusModules && !MF->isModuleMapModule() &&
       /// FIXME: Currently, the semantics of linkage in clang is slightly
       /// different from the semantics in C++ spec. In C++ spec, only names
       /// have linkage. So that all entities of the same should share one
       /// linkage. But in clang, different entities of the same could have
       /// different linkage.
       NamedDecl *ND = Function;
       if (auto *SpecInfo = Function->getTemplateSpecializationInfo())
         ND = SpecInfo->getTemplate();
-      
       if (ND->getFormalLinkage() == Linkage::InternalLinkage) {
         Candidate.Viable = false;
         Candidate.FailureKind = ovl_fail_module_mismatched;
         return;
       }
     }
   }
 
case Sema::TDK_Inconsistent: {
     S.Diag(Templated->getLocation(),
            diag::note_ovl_candidate_inconsistent_deduction)
         << which << ParamD->getDeclName() << *DeductionFailure.getFirstArg()
         << *DeductionFailure.getSecondArg();
     MaybeEmitInheritedConstructorNote(S, Found);
     return;
   }
 
-  case Sema::TDK_InvalidExplicitArguments:
+  case Sema::TDK_InvalidExplicitArguments: {
     assert(ParamD && "no parameter found for invalid explicit arguments");
+
+    unsigned index = 1;
+    int parameter_kind = 0;
+    if (auto *TTP = dyn_cast<TemplateTypeParmDecl>(ParamD)) {
+      index += TTP->getIndex();
+      parameter_kind = 0;
+    } else if (auto *NTTP = dyn_cast<NonTypeTemplateParmDecl>(ParamD)) {
+      index += NTTP->getIndex();
+      parameter_kind = 1;
+    } else {
+      index += cast<TemplateTemplateParmDecl>(ParamD)->getIndex();
+      parameter_kind = 2;
+    }
+
+    // QualType CallType = dyn_cast<CallExpr>(Fn)->getType();
+    // auto *FT = dyn_cast<FunctionTemplateDecl>(CallType);
+    // TemplateParameterList *Args = FT->getTemplateParameters();
+    // assert(Args && "We should have a full list of template arguments at this
+    // point"); assert(Args->size() >= index && "The argument list should at
+    // least be as long as the parameter we're indexing");
+
+    int arg_kind = 0;
+    // if (auto *TTP = dyn_cast<TemplateTypeParmDecl>(Args->getParam(index -
+    // 1)))
+    //   arg_kind = 0;
+    // else if (auto *NTTP =
+    // dyn_cast<NonTypeTemplateParmDecl>(Args->getParam(index - 1)))
+    //   arg_kind = 1;
+    // else
+    //   arg_kind = 2;
+
     if (ParamD->getDeclName())
       S.Diag(Templated->getLocation(),
              diag::note_ovl_candidate_explicit_arg_mismatch_named)
-          << ParamD->getDeclName();
-    else {
-      int index = 0;
-      if (TemplateTypeParmDecl *TTP = dyn_cast<TemplateTypeParmDecl>(ParamD))
-        index = TTP->getIndex();
-      else if (NonTypeTemplateParmDecl *NTTP
-                                  = dyn_cast<NonTypeTemplateParmDecl>(ParamD))
-        index = NTTP->getIndex();
-      else
-        index = cast<TemplateTemplateParmDecl>(ParamD)->getIndex();
+          << ParamD->getDeclName() << arg_kind << index << parameter_kind;
       S.Diag(Templated->getLocation(),
              diag::note_ovl_candidate_explicit_arg_mismatch_unnamed)
-          << (index + 1);
-    }
+          << index;
+
     MaybeEmitInheritedConstructorNote(S, Found);
     return;
-
+  }
   case Sema::TDK_ConstraintsNotSatisfied: {
     // Format the template argument list into the argument string.
     SmallString<128> TemplateArgString;
     TemplateArgumentList *Args = DeductionFailure.getTemplateArgumentList();
     TemplateArgString = " ";
     TemplateArgString += S.getTemplateArgumentBindingsText(
         getDescribedTemplate(Templated)->getTemplateParameters(), *Args);
     if (TemplateArgString.size() == 1)
case OR_Success: {
             Diag(OpLoc, diag::ext_ovl_ambiguous_oper_binary_reversed)
                 << BinaryOperator::getOpcodeStr(Opc)
                 << Args[0]->getType() << Args[1]->getType() << AmbiguousWithSelf
                 << Args[0]->getSourceRange() << Args[1]->getSourceRange();
             if (AmbiguousWithSelf) {
               Diag(FnDecl->getLocation(),
                    diag::note_ovl_ambiguous_oper_binary_reversed_self);
               // Mark member== const or provide matching != to disallow reversed
-              // args. Eg. 
-              // struct S { bool operator==(const S&); }; 
+              // args. Eg.
+              // struct S { bool operator==(const S&); };
               // S()==S();
               if (auto *MD = dyn_cast<CXXMethodDecl>(FnDecl))
                 if (Op == OverloadedOperatorKind::OO_EqualEqual &&
                     !MD->isConst() &&
                     Context.hasSameUnqualifiedType(
                         MD->getThisObjectType(),
                         MD->getParamDecl(0)->getType().getNonReferenceType()) &&
                     Context.hasSameUnqualifiedType(MD->getThisObjectType(),

clang/test/Frontend/sarif-reason.cpp

+// RUN: %clang_cc1 %s -verify -fsyntax-only
+// RUN: %clang -fsyntax-only -fdiagnostics-format=sarif %s > %t 2>&1
+// RUN: FileCheck -dump-input=always %s --input-file=%t --check-prefix=EXPECTED-ERROR --check-prefix=EXPECTED-NOTE
+
+template<class T>
+void f1();
+template<int T>
+void f2();
+template<template<class> class T>
+void f3();
+
+template<class> struct S;
+
+void g() {
+  f1<0>(); // expected-error{{no matching function for call to 'f1'}}
+           // expected-note@6{{candidate template ignored: invalid explicitly-specified argument for template parameter 'T'}}
+  f1<S>(); // expected-error{{no matching function for call to 'f1'}}
+           // expected-note@6{{candidate template ignored: invalid explicitly-specified argument for template parameter 'T'}}
+
+  f2<int>(); // expected-error{{no matching function for call to 'f2'}}
+             // expected-note@8{{candidate template ignored: invalid explicitly-specified argument for template parameter 'T'}}
+  f2<S>();   // expected-error{{no matching function for call to 'f2'}}
+             // expected-note@8{{candidate template ignored: invalid explicitly-specified argument for template parameter 'T'}}
+
+  f3<int>(); // expected-error{{no matching function for call to 'f3'}}
+             // expected-note@10{{candidate template ignored: invalid explicitly-specified argument for template parameter 'T'}}
+  f3<0>();   // expected-error{{no matching function for call to 'f3'}}
+             // expected-note@10{{candidate template ignored: invalid explicitly-specified argument for template parameter 'T'}}
+}
+
+// EXPECTED-ERROR: no matching function for call to 'f1'
+// EXPECTED-NOTE: candidate template ignored: we passed a value as our first explicit template parameter, but this candidate expects a type for 'T'
+
+// EXPECTED-ERROR: no matching function for call to 'f1'
+// EXPECTED-NOTE: candidate template ignored: we passed a class template as our first explicit template parameter, but this candidate expects a type for 'T'
+
+// EXPECTED-ERROR: no matching function for call to 'f2'
+// EXPECTED-NOTE: candidate template ignored: we passed a type as our first explicit template parameter, but this candidate expects a value for 'T'
+
+// EXPECTED-ERROR: no matching function for call to 'f2'
+// EXPECTED-NOTE: candidate template ignored: we passed a class template as our first explicit template parameter, but this candidate expects a value for 'T'
+
+// EXPECTED-ERROR: no matching function for call to 'f3'
+// EXPECTED-NOTE: candidate template ignored: we passed a type as our first explicit template parameter, but this candidate expects a class template for 'T'
+
+// EXPECTED-ERROR: no matching function for call to 'f3'
+// EXPECTED-NOTE: candidate template ignored: we passed a value as our first explicit template parameter, but this candidate expects a class template for 'T'

clang/test/TableGen/DiagnosticBase.inc

class DiagGroup<string Name, list<DiagGroup> subgroups = []> {
   string GroupName = Name;
   list<DiagGroup> SubGroups = subgroups;
   string CategoryName = "";
   code Documentation = [{}];
 }
 class InGroup<DiagGroup G> { DiagGroup Group = G; }
 //class IsGroup<string Name> { DiagGroup Group = DiagGroup<Name>; }
 
+class LegacyR<string value> {
+  string Value = value;
+}
+
+class SARIF<string value> {
+  string Value = value;
+}
+
+class DiagReason<LegacyR legacy, SARIF sarif = SARIF<legacy.Value>> {
+  // A legacy reason is a reason that is part of Clang's legacy diagnostic model,
+  // but needed to be split from the summary in order to facilitate the existence
+  // of the structured diagnostic (which will have very different text). One may
+  // observe that older versions of Clang's diagnostics are the same as
+  // `Diagnostic.Summary + Diagnostic.Reason.Legacy`. This is intentional, so as
+  // to preserve the legacy diagnostic model for the time being.
+  LegacyR Legacy = legacy;
+
+  // The SARIF reason will appear when Clang is asked to emit SARIF diagnostics,
+  // in place of Legacy. Unlike Legacy, which is a fragment of the original
+  // diagnostic from past-Clang, SARIF reasons may have completely different text
+  // to explain the problem, often from the perspective of a user.
+  SARIF SS = structured;
+}
+def NO_REASON_YET : DiagReason<LegacyR<"">>;
 include "DiagnosticDocs.inc"
 
 // All diagnostics emitted by the compiler are an indirect subclass of this.
-class Diagnostic<string summary, DiagClass DC, Severity defaultmapping> {
+class Diagnostic<string summary, DiagClass DC, Severity defaultmapping, DiagReason reason> {
   /// Component is specified by the file with a big let directive.
   string         Component = ?;
   string         Summary = summary;
   DiagClass      Class = DC;
   SFINAEResponse SFINAE = SFINAE_Suppress;
   bit            AccessControl = 0;
   bit            WarningNoWerror = 0;
   bit            ShowInSystemHeader = 0;
   bit            ShowInSystemMacro = 1;
   bit            Deferrable = 0;
   Severity       DefaultSeverity = defaultmapping;
   DiagGroup      Group;
   string         CategoryName = "";
+  DiagReason     Reason = reason;
 }
 
 class SFINAEFailure {
   SFINAEResponse SFINAE = SFINAE_SubstitutionFailure;
 }
 class NoSFINAE {
   SFINAEResponse SFINAE = SFINAE_Report;
 }
class Deferrable {
   bit Deferrable = 1;
 }
 
 class NonDeferrable {
   bit Deferrable = 0;
 }
 
 // FIXME: ExtWarn and Extension should also be SFINAEFailure by default.
-class Error<string str>     : Diagnostic<str, CLASS_ERROR, SEV_Error>, SFINAEFailure {
+class Error<string str, DiagReason reason = NO_REASON_YET>     : Diagnostic<str, CLASS_ERROR, SEV_Error, reason>, SFINAEFailure {
   bit ShowInSystemHeader = 1;
 }
 // Warnings default to on (but can be default-off'd with DefaultIgnore).
 // This is used for warnings about questionable code; warnings about
 // accepted language extensions should use Extension or ExtWarn below instead.
-class Warning<string str>   : Diagnostic<str, CLASS_WARNING, SEV_Warning>;
+class Warning<string str, DiagReason reason = NO_REASON_YET>   : Diagnostic<str, CLASS_WARNING, SEV_Warning, reason>;
 // Remarks can be turned on with -R flags and provide commentary, e.g. on
 // optimizer decisions.
-class Remark<string str>    : Diagnostic<str, CLASS_REMARK, SEV_Ignored>;
+class Remark<string str, DiagReason reason = NO_REASON_YET>    : Diagnostic<str, CLASS_REMARK, SEV_Ignored, reason>;
 // Extensions are warnings about accepted language extensions.
 // Extension warnings are default-off but enabled by -pedantic.
-class Extension<string str> : Diagnostic<str, CLASS_EXTENSION, SEV_Ignored>;
+class Extension<string str, DiagReason reason = NO_REASON_YET> : Diagnostic<str, CLASS_EXTENSION, SEV_Ignored, reason>;
 // ExtWarns are warnings about accepted language extensions.
 // ExtWarn warnings are default-on.
-class ExtWarn<string str>   : Diagnostic<str, CLASS_EXTENSION, SEV_Warning>;
+class ExtWarn<string str, DiagReason reason = NO_REASON_YET>   : Diagnostic<str, CLASS_EXTENSION, SEV_Warning, reason>;
 // Notes can provide supplementary information on errors, warnings, and remarks.
-class Note<string str>      : Diagnostic<str, CLASS_NOTE, SEV_Fatal/*ignored*/>;
+class Note<string str, DiagReason reason = NO_REASON_YET>      : Diagnostic<str, CLASS_NOTE, SEV_Fatal/*ignored*/, reason>;
 
 
 class DefaultIgnore { Severity DefaultSeverity = SEV_Ignored; }
 class DefaultWarn   { Severity DefaultSeverity = SEV_Warning; }
 class DefaultError  { Severity DefaultSeverity = SEV_Error; }
 class DefaultFatal  { Severity DefaultSeverity = SEV_Fatal; }
 class DefaultWarnNoWerror {
   bit WarningNoWerror = 1;
 }
 class DefaultRemark { Severity DefaultSeverity = SEV_Remark; }

clang/test/TableGen/deferred-diag.td

 // RUN: clang-tblgen -gen-clang-diags-defs -I%S %s -o - 2>&1 | \
 // RUN:    FileCheck --strict-whitespace %s
 include "DiagnosticBase.inc"
 
 // Test usage of Deferrable and NonDeferrable in diagnostics.
 
 def test_default : Error<"This error is non-deferrable by default">;
-// CHECK-DAG: DIAG(test_default, {{.*}}SFINAE_SubstitutionFailure, false, true, true, false, 0)
+// CHECK-DAG: DIAG(test_default, {{.*}}SFINAE_SubstitutionFailure, false, true, true, false, 0, /*Reason.Legacy=*/"", /*Reason.SARIF=*/"")
 
 def test_deferrable : Error<"This error is deferrable">, Deferrable;
-// CHECK-DAG: DIAG(test_deferrable, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0)
+// CHECK-DAG: DIAG(test_deferrable, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0, /*Reason.Legacy=*/"", /*Reason.SARIF=*/"")
 
 def test_non_deferrable : Error<"This error is non-deferrable">, NonDeferrable;
-// CHECK-DAG: DIAG(test_non_deferrable, {{.*}} SFINAE_SubstitutionFailure, false, true, true, false, 0)
+// CHECK-DAG: DIAG(test_non_deferrable, {{.*}} SFINAE_SubstitutionFailure, false, true, true, false, 0, /*Reason.Legacy=*/"", /*Reason.SARIF=*/"")
 
 let Deferrable = 1 in {
 
 def test_let : Error<"This error is deferrable by let">;
-// CHECK-DAG: DIAG(test_let, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0)
+// CHECK-DAG: DIAG(test_let, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0, /*Reason.Legacy=*/"", /*Reason.SARIF=*/"")
 
 // Make sure TextSubstitution is allowed in the let Deferrable block.
 def textsub : TextSubstitution<"%select{text1|text2}0">;
 
 def test_let2 : Error<"This error is deferrable by let %sub{textsub}0">;
-// CHECK-DAG: DIAG(test_let2, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0)
+// CHECK-DAG: DIAG(test_let2, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0, /*Reason.Legacy=*/"", /*Reason.SARIF=*/"")
 
 }

clang/tools/clang-format/ClangFormat.cpp

 
 class ClangFormatDiagConsumer : public DiagnosticConsumer {
   virtual void anchor() {}
 
   void HandleDiagnostic(DiagnosticsEngine::Level DiagLevel,
                         const Diagnostic &Info) override {
 
     SmallVector<char, 16> vec;
-    Info.FormatDiagnostic(vec);
+    Info.FormatLegacyDiagnostic(vec);
     errs() << "clang-format error:" << vec << "\n";
   }
 };
 
 // Returns true on error.
 static bool format(StringRef FileName) {
   if (!OutputXML && Inplace && FileName == "-") {
     errs() << "error: cannot use -i when reading from stdin.\n";
     return false;

clang/tools/clang-import-test/clang-import-test.cpp

if (Info.hasSourceManager() && LangOpts) {
       SourceManager &SM = Info.getSourceManager();
 
       if (Info.getLocation().isValid()) {
         Info.getLocation().print(llvm::errs(), SM);
         llvm::errs() << ": ";
       }
 
       SmallString<16> DiagText;
-      Info.FormatDiagnostic(DiagText);
+      Info.FormatLegacyDiagnostic(DiagText);
       llvm::errs() << DiagText << '\n';
 
       if (Info.getLocation().isValid()) {
         PrintSourceForLocation(Info.getLocation(), SM);
       }
 
       for (const CharSourceRange &Range : Info.getRanges()) {
         bool Invalid = true;

clang/tools/diagtool/DiagnosticNames.cpp

llvm::ArrayRef<DiagnosticRecord> diagtool::getBuiltinDiagnosticsByName() {
   return llvm::makeArrayRef(BuiltinDiagnosticsByName);
 }
 
 
 // FIXME: Is it worth having two tables, especially when this one can get
 // out of sync easily?
 static const DiagnosticRecord BuiltinDiagnosticsByID[] = {
 #define DIAG(ENUM, CLASS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFER, CATEGORY)                 \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFER, CATEGORY, LEGACY_REASON,  \
+             SARIF_REASON)                                                     \
   {#ENUM, diag::ENUM, STR_SIZE(#ENUM, uint8_t)},
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticCrossTUKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"

clang/unittests/Driver/SimpleDiagnosticConsumer.h

 #include "clang/Basic/Diagnostic.h"
 #include "llvm/ADT/SmallString.h"
 
 struct SimpleDiagnosticConsumer : public clang::DiagnosticConsumer {
   void HandleDiagnostic(clang::DiagnosticsEngine::Level DiagLevel,
                         const clang::Diagnostic &Info) override {
     if (DiagLevel == clang::DiagnosticsEngine::Level::Error) {
       Errors.emplace_back();
-      Info.FormatDiagnostic(Errors.back());
+      Info.FormatLegacyDiagnostic(Errors.back());
     } else {
       Msgs.emplace_back();
-      Info.FormatDiagnostic(Msgs.back());
+      Info.FormatLegacyDiagnostic(Msgs.back());
     }
   }
   void clear() override {
     Msgs.clear();
     Errors.clear();
     DiagnosticConsumer::clear();
   }
   std::vector<llvm::SmallString<32>> Msgs;
   std::vector<llvm::SmallString<32>> Errors;
 };
 
 #endif // CLANG_UNITTESTS_SIMPLEDIAGNOSTICCONSUMER_H

clang/unittests/Driver/ToolChainTest.cpp

TEST(GetDriverMode, PrefersLastDriverMode) {
   EXPECT_EQ(getDriverMode(Args[0], llvm::makeArrayRef(Args).slice(1)), "bar");
 }
 
 struct SimpleDiagnosticConsumer : public DiagnosticConsumer {
   void HandleDiagnostic(DiagnosticsEngine::Level DiagLevel,
                         const Diagnostic &Info) override {
     if (DiagLevel == DiagnosticsEngine::Level::Error) {
       Errors.emplace_back();
-      Info.FormatDiagnostic(Errors.back());
+      Info.FormatLegacyDiagnostic(Errors.back());
     } else {
       Msgs.emplace_back();
-      Info.FormatDiagnostic(Msgs.back());
+      Info.FormatLegacyDiagnostic(Msgs.back());
     }
   }
   void clear() override {
     Msgs.clear();
     Errors.clear();
     DiagnosticConsumer::clear();
   }
   std::vector<SmallString<32>> Msgs;

clang/unittests/Frontend/FrontendActionTest.cpp

 };
 
 struct TypoDiagnosticConsumer : public DiagnosticConsumer {
   void HandleDiagnostic(DiagnosticsEngine::Level DiagLevel,
                         const Diagnostic &Info) override {
     // Capture errors and notes. There should be one of each.
     if (DiagLevel == DiagnosticsEngine::Error) {
       assert(Error.empty());
-      Info.FormatDiagnostic(Error);
+      Info.FormatLegacyDiagnostic(Error);
     } else {
       assert(Note.empty());
-      Info.FormatDiagnostic(Note);
+      Info.FormatLegacyDiagnostic(Note);
     }
   }
   SmallString<32> Error;
   SmallString<32> Note;
 };
 
 TEST(ASTFrontendAction, ExternalSemaSource) {
   auto Invocation = std::make_shared<CompilerInvocation>();

clang/unittests/Tooling/RewriterTestContext.h

 ///
 /// This avoids a dependency on clangFrontend for FormatTests.
 struct RewriterDiagnosticConsumer : public DiagnosticConsumer {
   RewriterDiagnosticConsumer() : NumDiagnosticsSeen(0) {}
   void HandleDiagnostic(DiagnosticsEngine::Level DiagLevel,
                         const Diagnostic &Info) override {
     ++NumDiagnosticsSeen;
     SmallString<100> OutStr;
-    Info.FormatDiagnostic(OutStr);
+    Info.FormatLegacyDiagnostic(OutStr);
     llvm::errs() << OutStr;
   }
   unsigned NumDiagnosticsSeen;
 };
 
 /// \brief A class that sets up a ready to use Rewriter.
 ///
 /// Useful in unit tests that need a Rewriter. Creates all dependencies

clang/utils/TableGen/ClangDiagnosticsEmitter.cpp

for (Record *Diag : Records.getAllDerivedDefinitions("Diagnostic")) {
             Diag->getLoc(),
             "Diagnostic '" + Name +
                 "' has same name as TextSubstitution definition");
     }
   }
 
   std::vector<std::string> buildForDocumentation(StringRef Role,
                                                  const Record *R);
-  std::string buildForDefinition(const Record *R);
+  std::string buildForDefinition(const Record *R, StringRef Field);
 
   Piece *getSubstitution(SubstitutionPiece *S) const {
     auto It = Substitutions.find(S->Name);
     if (It == Substitutions.end())
       PrintFatalError("Failed to find substitution with name: " + S->Name);
     return It->second.Root;
   }
 
if (!MP) {
     D.Root = MP;
   }
   MP->Pieces.insert(MP->Pieces.begin(), Prefix);
   std::vector<std::string> Result;
   DiagTextDocPrinter{*this, Result}.Visit(D.Root);
   return Result;
 }
 
-std::string DiagnosticTextBuilder::buildForDefinition(const Record *R) {
+std::string DiagnosticTextBuilder::buildForDefinition(const Record *R,
+                                                      StringRef Field) {
   EvaluatingRecordGuard Guard(&EvaluatingRecord, R);
-  StringRef Text = R->getValueAsString("Summary");
+  StringRef Text = R->getValueAsString(Field);
   DiagText D(*this, Text);
   std::string Result;
   DiagTextPrinter{*this, Result}.Visit(D.Root);
   return Result;
 }
 
 } // namespace
 
for (unsigned i = 0, e = Diags.size(); i != e; ++i) {
 
     OS << "DIAG(" << R.getName() << ", ";
     OS << R.getValueAsDef("Class")->getName();
     OS << ", (unsigned)diag::Severity::"
        << R.getValueAsDef("DefaultSeverity")->getValueAsString("Name");
 
     // Description string.
     OS << ", \"";
-    OS.write_escaped(DiagTextBuilder.buildForDefinition(&R)) << '"';
+    OS.write_escaped(DiagTextBuilder.buildForDefinition(&R, "Summary")) << '"';
 
     // Warning group associated with the diagnostic. This is stored as an index
     // into the alphabetically sorted warning group table.
     if (DefInit *DI = dyn_cast<DefInit>(R.getValueInit("Group"))) {
       std::map<std::string, GroupInfo>::iterator I = DiagsInGroup.find(
           std::string(DI->getDef()->getValueAsString("GroupName")));
       assert(I != DiagsInGroup.end());
       OS << ", " << I->second.IDNo;
for (unsigned i = 0, e = Diags.size(); i != e; ++i) {
 
     if (R.getValueAsBit("Deferrable"))
       OS << ", true";
     else
       OS << ", false";
 
     // Category number.
     OS << ", " << CategoryIDs.getID(getDiagnosticCategory(&R, DGParentMap));
+
+    // Reasons
+    OS << ", /*LegacyReason=*/\"";
+    OS.write_escaped(DiagTextBuilder.buildForDefinition(
+        R.getValueAsDef("Reason")->getValueAsDef("Legacy"), "Value"))
+        << '"';
+
+    OS << ", /*SARIFReason=*/\"";
+    OS.write_escaped(DiagTextBuilder.buildForDefinition(
+        R.getValueAsDef("Reason")->getValueAsDef("SARIF"), "Value"))
+        << '"';
     OS << ")\n";
   }
 }
 
 //===----------------------------------------------------------------------===//
 // Warning Group Tables generation
 //===----------------------------------------------------------------------===//
 

flang/lib/Frontend/TextDiagnosticBuffer.cpp

 /// HandleDiagnostic - Store the errors, warnings, and notes that are
 /// reported.
 void TextDiagnosticBuffer::HandleDiagnostic(
     clang::DiagnosticsEngine::Level level, const clang::Diagnostic &info) {
   // Default implementation (warnings_/errors count).
   DiagnosticConsumer::HandleDiagnostic(level, info);
 
   llvm::SmallString<100> buf;
-  info.FormatDiagnostic(buf);
+  info.FormatSummary(buf);
+  info.FormatLegacyDiagnostic(buf);
   switch (level) {
   default:
     llvm_unreachable("Diagnostic not handled during diagnostic buffering!");
   case clang::DiagnosticsEngine::Note:
     all.emplace_back(level, notes.size());
     notes.emplace_back(info.getLocation(), std::string(buf.str()));
     break;
   case clang::DiagnosticsEngine::Warning:

flang/lib/Frontend/TextDiagnosticPrinter.cpp

 void TextDiagnosticPrinter::HandleDiagnostic(
     clang::DiagnosticsEngine::Level level, const clang::Diagnostic &info) {
   // Default implementation (Warnings/errors count).
   DiagnosticConsumer::HandleDiagnostic(level, info);
 
   // Render the diagnostic message into a temporary buffer eagerly. We'll use
   // this later as we print out the diagnostic to the terminal.
   llvm::SmallString<100> outStr;
-  info.FormatDiagnostic(outStr);
+  info.FormatSummary(outStr);
+  info.FormatLegacyDiagnostic(outStr);
 
   llvm::raw_svector_ostream diagMessageStream(outStr);
 
   if (!prefix.empty())
     os << prefix << ": ";
 
   // We only emit diagnostics in contexts that lack valid source locations.
   assert(!info.getLocation().isValid() &&

lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionParser.cpp

if (!m_manager) {
       // We have no DiagnosticManager before/after parsing but we still could
       // receive diagnostics (e.g., by the ASTImporter failing to copy decls
       // when we move the expression result ot the ScratchASTContext). Let's at
       // least log these diagnostics until we find a way to properly render
       // them and display them to the user.
       Log *log = GetLog(LLDBLog::Expressions);
       if (log) {
         llvm::SmallVector<char, 32> diag_str;
-        Info.FormatDiagnostic(diag_str);
+        Info.FormatLegacyDiagnostic(diag_str);
         diag_str.push_back('\0');
         const char *plain_diag = diag_str.data();
         LLDB_LOG(log, "Received diagnostic outside parsing: {0}", plain_diag);
       }
       return;
     }
 
     // Update error/warning counters.

lldb/source/Plugins/TypeSystem/Clang/TypeSystemClang.cpp

 class NullDiagnosticConsumer : public DiagnosticConsumer {
 public:
   NullDiagnosticConsumer() { m_log = GetLog(LLDBLog::Expressions); }
 
   void HandleDiagnostic(DiagnosticsEngine::Level DiagLevel,
                         const clang::Diagnostic &info) override {
     if (m_log) {
       llvm::SmallVector<char, 32> diag_str(10);
-      info.FormatDiagnostic(diag_str);
+      info.FormatLegacyDiagnostic(diag_str);
       diag_str.push_back('\0');
       LLDB_LOGF(m_log, "Compiler diagnostic: %s\n", diag_str.data());
     }
   }
 
   DiagnosticConsumer *clone(DiagnosticsEngine &Diags) const {
     return new NullDiagnosticConsumer();
   }