clang-tools  15.0.0git
Diagnostics.h
Go to the documentation of this file.
1 //===--- Diagnostics.h -------------------------------------------*- C++-*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_DIAGNOSTICS_H
10 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_DIAGNOSTICS_H
11 
12 #include "Protocol.h"
13 #include "clang/Basic/Diagnostic.h"
14 #include "clang/Basic/LangOptions.h"
15 #include "clang/Basic/SourceLocation.h"
16 #include "llvm/ADT/ArrayRef.h"
17 #include "llvm/ADT/DenseSet.h"
18 #include "llvm/ADT/Optional.h"
19 #include "llvm/ADT/SmallVector.h"
20 #include "llvm/ADT/StringSet.h"
21 #include "llvm/Support/JSON.h"
22 #include "llvm/Support/SourceMgr.h"
23 #include <cassert>
24 #include <functional>
25 #include <memory>
26 #include <string>
27 #include <utility>
28 #include <vector>
29 
30 namespace clang {
31 namespace tidy {
32 class ClangTidyContext;
33 } // namespace tidy
34 namespace clangd {
35 
37  /// If true, Clangd uses an LSP extension to embed the fixes with the
38  /// diagnostics that are sent to the client.
40 
41  /// If true, Clangd uses the relatedInformation field to include other
42  /// locations (in particular attached notes).
43  /// Otherwise, these are flattened into the diagnostic message.
44  bool EmitRelatedLocations = false;
45 
46  /// If true, Clangd uses an LSP extension to send the diagnostic's
47  /// category to the client. The category typically describes the compilation
48  /// stage during which the issue was produced, e.g. "Semantic Issue" or "Parse
49  /// Issue".
50  bool SendDiagnosticCategory = false;
51 
52  /// If true, Clangd will add a number of available fixes to the diagnostic's
53  /// message.
54  bool DisplayFixesCount = true;
55 };
56 
57 /// Contains basic information about a diagnostic.
58 struct DiagBase {
59  std::string Message;
60  // Intended to be used only in error messages.
61  // May be relative, absolute or even artificially constructed.
62  std::string File;
63  // Absolute path to containing file, if available.
64  llvm::Optional<std::string> AbsFile;
65 
67  DiagnosticsEngine::Level Severity = DiagnosticsEngine::Note;
68  std::string Category;
69  // Since File is only descriptive, we store a separate flag to distinguish
70  // diags from the main file.
71  bool InsideMainFile = false;
72  unsigned ID = 0; // e.g. member of clang::diag, or clang-tidy assigned ID.
73  // Feature modules can make use of this field to propagate data from a
74  // diagnostic to a CodeAction request. Each module should only append to the
75  // list.
76  llvm::json::Object OpaqueData;
77 };
78 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, const DiagBase &D);
79 
80 /// Represents a single fix-it that editor can apply to fix the error.
81 struct Fix {
82  /// Message for the fix-it.
83  std::string Message;
84  /// TextEdits from clang's fix-its. Must be non-empty.
85  llvm::SmallVector<TextEdit, 1> Edits;
86 };
87 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, const Fix &F);
88 
89 /// Represents a note for the diagnostic. Severity of notes can only be 'note'
90 /// or 'remark'.
91 struct Note : DiagBase {};
92 
93 /// A top-level diagnostic that may have Notes and Fixes.
94 struct Diag : DiagBase {
95  std::string Name; // if ID was recognized.
96  // The source of this diagnostic.
97  enum DiagSource {
103  } Source = Unknown;
104  /// Elaborate on the problem, usually pointing to a related piece of code.
105  std::vector<Note> Notes;
106  /// *Alternative* fixes for this diagnostic, one should be chosen.
107  std::vector<Fix> Fixes;
108  llvm::SmallVector<DiagnosticTag, 1> Tags;
109 };
110 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, const Diag &D);
111 
112 Diag toDiag(const llvm::SMDiagnostic &, Diag::DiagSource Source);
113 
114 /// Conversion to LSP diagnostics. Formats the error message of each diagnostic
115 /// to include all its notes. Notes inside main file are also provided as
116 /// separate diagnostics with their corresponding fixits. Notes outside main
117 /// file do not have a corresponding LSP diagnostic, but can still be included
118 /// as part of their main diagnostic's message.
119 void toLSPDiags(
120  const Diag &D, const URIForFile &File, const ClangdDiagnosticOptions &Opts,
121  llvm::function_ref<void(clangd::Diagnostic, llvm::ArrayRef<Fix>)> OutFn);
122 
123 /// Convert from Fix to LSP CodeAction.
124 CodeAction toCodeAction(const Fix &D, const URIForFile &File);
125 
126 /// Convert from clang diagnostic level to LSP severity.
127 int getSeverity(DiagnosticsEngine::Level L);
128 
129 /// Returns a URI providing more information about a particular diagnostic.
130 llvm::Optional<std::string> getDiagnosticDocURI(Diag::DiagSource, unsigned ID,
131  llvm::StringRef Name);
132 
133 /// StoreDiags collects the diagnostics that can later be reported by
134 /// clangd. It groups all notes for a diagnostic into a single Diag
135 /// and filters out diagnostics that don't mention the main file (i.e. neither
136 /// the diag itself nor its notes are in the main file).
138 public:
139  // The ClangTidyContext populates Source and Name for clang-tidy diagnostics.
140  std::vector<Diag> take(const clang::tidy::ClangTidyContext *Tidy = nullptr);
141 
142  void BeginSourceFile(const LangOptions &Opts,
143  const Preprocessor *PP) override;
144  void EndSourceFile() override;
145  void HandleDiagnostic(DiagnosticsEngine::Level DiagLevel,
146  const clang::Diagnostic &Info) override;
147 
148  /// When passed a main diagnostic, returns fixes to add to it.
149  /// When passed a note diagnostic, returns fixes to replace it with.
150  using DiagFixer = std::function<std::vector<Fix>(DiagnosticsEngine::Level,
151  const clang::Diagnostic &)>;
152  using LevelAdjuster = std::function<DiagnosticsEngine::Level(
153  DiagnosticsEngine::Level, const clang::Diagnostic &)>;
154  using DiagCallback =
155  std::function<void(const clang::Diagnostic &, clangd::Diag &)>;
156  /// If set, possibly adds fixes for diagnostics using \p Fixer.
157  void contributeFixes(DiagFixer Fixer) { this->Fixer = Fixer; }
158  /// If set, this allows the client of this class to adjust the level of
159  /// diagnostics, such as promoting warnings to errors, or ignoring
160  /// diagnostics.
161  void setLevelAdjuster(LevelAdjuster Adjuster) { this->Adjuster = Adjuster; }
162  /// Invokes a callback every time a diagnostics is completely formed. Handler
163  /// of the callback can also mutate the diagnostic.
164  void setDiagCallback(DiagCallback CB) { DiagCB = std::move(CB); }
165 
166 private:
167  void flushLastDiag();
168 
169  DiagFixer Fixer = nullptr;
170  LevelAdjuster Adjuster = nullptr;
171  DiagCallback DiagCB = nullptr;
172  std::vector<Diag> Output;
173  llvm::Optional<LangOptions> LangOpts;
174  llvm::Optional<Diag> LastDiag;
175  llvm::Optional<FullSourceLoc> LastDiagLoc; // Valid only when LastDiag is set.
176  bool LastDiagOriginallyError = false; // Valid only when LastDiag is set.
177  SourceManager *OrigSrcMgr = nullptr;
178 
179  llvm::DenseSet<std::pair<unsigned, unsigned>> IncludedErrorLocations;
180 };
181 
182 /// Determine whether a (non-clang-tidy) diagnostic is suppressed by config.
183 bool isBuiltinDiagnosticSuppressed(unsigned ID,
184  const llvm::StringSet<> &Suppressed,
185  const LangOptions &);
186 /// Take a user-specified diagnostic code, and convert it to a normalized form
187 /// stored in the config and consumed by isBuiltinDiagnosticsSuppressed.
188 ///
189 /// (This strips err_ and -W prefix so we can match with or without them.)
190 llvm::StringRef normalizeSuppressedCode(llvm::StringRef);
191 
192 } // namespace clangd
193 } // namespace clang
194 
195 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_DIAGNOSTICS_H
clang::clangd::DiagBase::Severity
DiagnosticsEngine::Level Severity
Definition: Diagnostics.h:67
clang::clangd::Diag::Tags
llvm::SmallVector< DiagnosticTag, 1 > Tags
Definition: Diagnostics.h:108
clang::clangd::Diag::ClangTidy
@ ClangTidy
Definition: Diagnostics.h:100
clang::clangd::Fix
Represents a single fix-it that editor can apply to fix the error.
Definition: Diagnostics.h:81
clang::clangd::CodeAction
A code action represents a change that can be performed in code, e.g.
Definition: Protocol.h:992
DiagnosticConsumer
clang::clangd::Diag::Name
std::string Name
Definition: Diagnostics.h:95
clang::clangd::DiagBase::InsideMainFile
bool InsideMainFile
Definition: Diagnostics.h:71
clang::clangd::ClangdDiagnosticOptions
Definition: Diagnostics.h:36
clang::clangd::getSeverity
int getSeverity(DiagnosticsEngine::Level L)
Convert from clang diagnostic level to LSP severity.
Definition: Diagnostics.cpp:547
clang::clangd::StoreDiags::DiagFixer
std::function< std::vector< Fix >(DiagnosticsEngine::Level, const clang::Diagnostic &)> DiagFixer
When passed a main diagnostic, returns fixes to add to it.
Definition: Diagnostics.h:151
clang::clangd::Diag::Source
enum clang::clangd::Diag::DiagSource Source
clang::clangd::StoreDiags::HandleDiagnostic
void HandleDiagnostic(DiagnosticsEngine::Level DiagLevel, const clang::Diagnostic &Info) override
Definition: Diagnostics.cpp:666
clang::clangd::StoreDiags::DiagCallback
std::function< void(const clang::Diagnostic &, clangd::Diag &)> DiagCallback
Definition: Diagnostics.h:155
clang::clangd::StoreDiags::LevelAdjuster
std::function< DiagnosticsEngine::Level(DiagnosticsEngine::Level, const clang::Diagnostic &)> LevelAdjuster
Definition: Diagnostics.h:153
Protocol.h
clang::clangd::ClangdDiagnosticOptions::DisplayFixesCount
bool DisplayFixesCount
If true, Clangd will add a number of available fixes to the diagnostic's message.
Definition: Diagnostics.h:54
clang::clangd::Fix::Edits
llvm::SmallVector< TextEdit, 1 > Edits
TextEdits from clang's fix-its. Must be non-empty.
Definition: Diagnostics.h:85
clang::clangd::Diagnostic
Definition: Protocol.h:846
ns1::ns2::D
@ D
Definition: CategoricalFeature.h:3
Diagnostic
DiagnosticCallback Diagnostic
Definition: ConfigCompile.cpp:100
clang::clangd::DiagBase::Message
std::string Message
Definition: Diagnostics.h:59
clang::clangd::Fix::Message
std::string Message
Message for the fix-it.
Definition: Diagnostics.h:83
clang::clangd::StoreDiags::EndSourceFile
void EndSourceFile() override
Definition: Diagnostics.cpp:626
clang::clangd::Diag
A top-level diagnostic that may have Notes and Fixes.
Definition: Diagnostics.h:94
clang::tidy::ClangTidyContext
Every ClangTidyCheck reports errors through a DiagnosticsEngine provided by this context.
Definition: ClangTidyDiagnosticConsumer.h:67
clang::clangd::Diag::Notes
std::vector< Note > Notes
Elaborate on the problem, usually pointing to a related piece of code.
Definition: Diagnostics.h:105
clang::clangd::toDiag
Diag toDiag(const llvm::SMDiagnostic &D, Diag::DiagSource Source)
Definition: Diagnostics.cpp:433
clang::clangd::Diag::Unknown
@ Unknown
Definition: Diagnostics.h:98
clang::clangd::Diag::Fixes
std::vector< Fix > Fixes
Alternative fixes for this diagnostic, one should be chosen.
Definition: Diagnostics.h:107
Name
Token Name
Definition: MacroToEnumCheck.cpp:89
clang::clangd::URIForFile
Definition: Protocol.h:81
clang::clangd::Diag::Clang
@ Clang
Definition: Diagnostics.h:99
clang::clangd::operator<<
llvm::raw_ostream & operator<<(llvm::raw_ostream &OS, const CodeCompletion &C)
Definition: CodeComplete.cpp:2182
clang::tidy::bugprone::PP
static Preprocessor * PP
Definition: BadSignalToKillThreadCheck.cpp:29
clang::clangd::DiagBase::AbsFile
llvm::Optional< std::string > AbsFile
Definition: Diagnostics.h:64
clang::clangd::toCodeAction
CodeAction toCodeAction(const Fix &F, const URIForFile &File)
Convert from Fix to LSP CodeAction.
Definition: Diagnostics.cpp:424
clang::clangd::StoreDiags::contributeFixes
void contributeFixes(DiagFixer Fixer)
If set, possibly adds fixes for diagnostics using Fixer.
Definition: Diagnostics.h:157
clang::clangd::ClangdDiagnosticOptions::EmitRelatedLocations
bool EmitRelatedLocations
If true, Clangd uses the relatedInformation field to include other locations (in particular attached ...
Definition: Diagnostics.h:44
clang::clangd::ClangdDiagnosticOptions::SendDiagnosticCategory
bool SendDiagnosticCategory
If true, Clangd uses an LSP extension to send the diagnostic's category to the client.
Definition: Diagnostics.h:50
Info
FunctionInfo Info
Definition: FunctionSizeCheck.cpp:121
clang::clangd::DiagBase::OpaqueData
llvm::json::Object OpaqueData
Definition: Diagnostics.h:76
ID
static char ID
Definition: Logger.cpp:74
clang::clangd::ClangdDiagnosticOptions::EmbedFixesInDiagnostics
bool EmbedFixesInDiagnostics
If true, Clangd uses an LSP extension to embed the fixes with the diagnostics that are sent to the cl...
Definition: Diagnostics.h:39
clang::clangd::Range
Definition: Protocol.h:182
clang::clangd::DiagBase::Category
std::string Category
Definition: Diagnostics.h:68
clang::clangd::Diag::Clangd
@ Clangd
Definition: Diagnostics.h:101
clang::clangd::toLSPDiags
void toLSPDiags(const Diag &D, const URIForFile &File, const ClangdDiagnosticOptions &Opts, llvm::function_ref< void(clangd::Diagnostic, llvm::ArrayRef< Fix >)> OutFn)
Conversion to LSP diagnostics.
Definition: Diagnostics.cpp:459
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
OS
llvm::raw_string_ostream OS
Definition: TraceTests.cpp:160
clang::clangd::StoreDiags::setDiagCallback
void setDiagCallback(DiagCallback CB)
Invokes a callback every time a diagnostics is completely formed.
Definition: Diagnostics.h:164
clang::clangd::StoreDiags
StoreDiags collects the diagnostics that can later be reported by clangd.
Definition: Diagnostics.h:137
clang::clangd::Diag::ClangdConfig
@ ClangdConfig
Definition: Diagnostics.h:102
clang::clangd::DiagBase::ID
unsigned ID
Definition: Diagnostics.h:72
clang::clangd::normalizeSuppressedCode
llvm::StringRef normalizeSuppressedCode(llvm::StringRef Code)
Take a user-specified diagnostic code, and convert it to a normalized form stored in the config and c...
Definition: Diagnostics.cpp:904
clang::clangd::Note
Represents a note for the diagnostic.
Definition: Diagnostics.h:91
clang::clangd::Diag::DiagSource
DiagSource
Definition: Diagnostics.h:97
clang::clangd::getDiagnosticDocURI
llvm::Optional< std::string > getDiagnosticDocURI(Diag::DiagSource Source, unsigned ID, llvm::StringRef Name)
Returns a URI providing more information about a particular diagnostic.
Definition: Diagnostics.cpp:910
clang::clangd::StoreDiags::setLevelAdjuster
void setLevelAdjuster(LevelAdjuster Adjuster)
If set, this allows the client of this class to adjust the level of diagnostics, such as promoting wa...
Definition: Diagnostics.h:161
clang::clangd::DiagBase
Contains basic information about a diagnostic.
Definition: Diagnostics.h:58
clang::clangd::StoreDiags::BeginSourceFile
void BeginSourceFile(const LangOptions &Opts, const Preprocessor *PP) override
Definition: Diagnostics.cpp:618
clang::clangd::isBuiltinDiagnosticSuppressed
bool isBuiltinDiagnosticSuppressed(unsigned ID, const llvm::StringSet<> &Suppress, const LangOptions &LangOpts)
Determine whether a (non-clang-tidy) diagnostic is suppressed by config.
Definition: Diagnostics.cpp:885
clang::clangd::StoreDiags::take
std::vector< Diag > take(const clang::tidy::ClangTidyContext *Tidy=nullptr)
Definition: Diagnostics.cpp:564
clang::clangd::DiagBase::File
std::string File
Definition: Diagnostics.h:62
clang::clangd::DiagBase::Range
clangd::Range Range
Definition: Diagnostics.h:66