1 //===-- clang-tools-extra/clang-tidy/NoLintDirectiveHandler.cpp -----------===//
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 /// \file This file implements the NoLintDirectiveHandler class, which is used
10 /// to locate NOLINT comments in the file being analyzed, to decide whether a
11 /// diagnostic should be suppressed.
12 ///
13 //===----------------------------------------------------------------------===//
14
15 #include "NoLintDirectiveHandler.h"
16 #include "GlobList.h"
17 #include "clang/Basic/LLVM.h"
18 #include "clang/Basic/SourceLocation.h"
19 #include "clang/Basic/SourceManager.h"
20 #include "clang/Tooling/Core/Diagnostic.h"
21 #include "llvm/ADT/ArrayRef.h"
22 #include "llvm/ADT/None.h"
23 #include "llvm/ADT/Optional.h"
24 #include "llvm/ADT/STLExtras.h"
25 #include "llvm/ADT/SmallVector.h"
26 #include "llvm/ADT/StringExtras.h"
27 #include "llvm/ADT/StringMap.h"
28 #include "llvm/ADT/StringSwitch.h"
29 #include <cassert>
30 #include <cstddef>
31 #include <iterator>
32 #include <string>
33 #include <tuple>
34 #include <type_traits>
35 #include <utility>
36
37 namespace clang {
38 namespace tidy {
39
40 //===----------------------------------------------------------------------===//
41 // NoLintType
42 //===----------------------------------------------------------------------===//
43
44 // The type - one of NOLINT[NEXTLINE/BEGIN/END].
45 enum class NoLintType { NoLint, NoLintNextLine, NoLintBegin, NoLintEnd };
46
47 // Convert a string like "NOLINTNEXTLINE" to its enum `Type::NoLintNextLine`.
48 // Return `None` if the string is unrecognized.
strToNoLintType(StringRef Str)49 static Optional<NoLintType> strToNoLintType(StringRef Str) {
50 auto Type = llvm::StringSwitch<Optional<NoLintType>>(Str)
51 .Case("NOLINT", NoLintType::NoLint)
52 .Case("NOLINTNEXTLINE", NoLintType::NoLintNextLine)
53 .Case("NOLINTBEGIN", NoLintType::NoLintBegin)
54 .Case("NOLINTEND", NoLintType::NoLintEnd)
55 .Default(None);
56 return Type;
57 }
58
59 //===----------------------------------------------------------------------===//
60 // NoLintToken
61 //===----------------------------------------------------------------------===//
62
63 // Whitespace within a NOLINT's check list shall be ignored.
64 // "NOLINT( check1, check2 )" is equivalent to "NOLINT(check1,check2)".
65 // Return the check list with all extraneous whitespace removed.
trimWhitespace(StringRef Checks)66 static std::string trimWhitespace(StringRef Checks) {
67 SmallVector<StringRef> Split;
68 Checks.split(Split, ',');
69 for (StringRef &Check : Split)
70 Check = Check.trim();
71 return llvm::join(Split, ",");
72 }
73
74 namespace {
75
76 // Record the presence of a NOLINT comment - its type, location, checks -
77 // as parsed from the file's character contents.
78 class NoLintToken {
79 public:
80 // \param Checks:
81 // - If unspecified (i.e. `None`) then ALL checks are suppressed - equivalent
82 // to NOLINT(*).
83 // - An empty string means nothing is suppressed - equivalent to NOLINT().
84 // - Negative globs ignored (which would effectively disable the suppression).
NoLintToken(NoLintType Type,size_t Pos,const Optional<std::string> & Checks)85 NoLintToken(NoLintType Type, size_t Pos, const Optional<std::string> &Checks)
86 : Type(Type), Pos(Pos), ChecksGlob(std::make_unique<CachedGlobList>(
87 Checks.value_or("*"),
88 /*KeepNegativeGlobs=*/false)) {
89 if (Checks)
90 this->Checks = trimWhitespace(*Checks);
91 }
92
93 // The type - one of NOLINT[NEXTLINE/BEGIN/END].
94 NoLintType Type;
95
96 // The location of the first character, "N", in "NOLINT".
97 size_t Pos;
98
99 // If this NOLINT specifies checks, return the checks.
checks() const100 Optional<std::string> checks() const { return Checks; }
101
102 // Whether this NOLINT applies to the provided check.
suppresses(StringRef Check) const103 bool suppresses(StringRef Check) const { return ChecksGlob->contains(Check); }
104
105 private:
106 Optional<std::string> Checks;
107 std::unique_ptr<CachedGlobList> ChecksGlob;
108 };
109
110 } // namespace
111
112 // Consume the entire buffer and return all `NoLintToken`s that were found.
getNoLints(StringRef Buffer)113 static SmallVector<NoLintToken> getNoLints(StringRef Buffer) {
114 static constexpr llvm::StringLiteral NOLINT = "NOLINT";
115 SmallVector<NoLintToken> NoLints;
116
117 size_t Pos = 0;
118 while (Pos < Buffer.size()) {
119 // Find NOLINT:
120 const size_t NoLintPos = Buffer.find(NOLINT, Pos);
121 if (NoLintPos == StringRef::npos)
122 break; // Buffer exhausted
123
124 // Read [A-Z] characters immediately after "NOLINT", e.g. the "NEXTLINE" in
125 // "NOLINTNEXTLINE".
126 Pos = NoLintPos + NOLINT.size();
127 while (Pos < Buffer.size() && llvm::isAlpha(Buffer[Pos]))
128 ++Pos;
129
130 // Is this a recognized NOLINT type?
131 const Optional<NoLintType> NoLintType =
132 strToNoLintType(Buffer.slice(NoLintPos, Pos));
133 if (!NoLintType)
134 continue;
135
136 // Get checks, if specified.
137 Optional<std::string> Checks;
138 if (Pos < Buffer.size() && Buffer[Pos] == '(') {
139 size_t ClosingBracket = Buffer.find_first_of("\n)", ++Pos);
140 if (ClosingBracket != StringRef::npos && Buffer[ClosingBracket] == ')') {
141 Checks = Buffer.slice(Pos, ClosingBracket).str();
142 Pos = ClosingBracket + 1;
143 }
144 }
145
146 NoLints.emplace_back(*NoLintType, NoLintPos, Checks);
147 }
148
149 return NoLints;
150 }
151
152 //===----------------------------------------------------------------------===//
153 // NoLintBlockToken
154 //===----------------------------------------------------------------------===//
155
156 namespace {
157
158 // Represents a source range within a pair of NOLINT(BEGIN/END) comments.
159 class NoLintBlockToken {
160 public:
NoLintBlockToken(NoLintToken Begin,const NoLintToken & End)161 NoLintBlockToken(NoLintToken Begin, const NoLintToken &End)
162 : Begin(std::move(Begin)), EndPos(End.Pos) {
163 assert(this->Begin.Type == NoLintType::NoLintBegin);
164 assert(End.Type == NoLintType::NoLintEnd);
165 assert(this->Begin.Pos < End.Pos);
166 assert(this->Begin.checks() == End.checks());
167 }
168
169 // Whether the provided diagnostic is within and is suppressible by this block
170 // of NOLINT(BEGIN/END) comments.
suppresses(size_t DiagPos,StringRef DiagName) const171 bool suppresses(size_t DiagPos, StringRef DiagName) const {
172 return (Begin.Pos < DiagPos) && (DiagPos < EndPos) &&
173 Begin.suppresses(DiagName);
174 }
175
176 private:
177 NoLintToken Begin;
178 size_t EndPos;
179 };
180
181 } // namespace
182
183 // Match NOLINTBEGINs with their corresponding NOLINTENDs and move them into
184 // `NoLintBlockToken`s. If any BEGINs or ENDs are left over, they are moved to
185 // `UnmatchedTokens`.
186 static SmallVector<NoLintBlockToken>
formNoLintBlocks(SmallVector<NoLintToken> NoLints,SmallVectorImpl<NoLintToken> & UnmatchedTokens)187 formNoLintBlocks(SmallVector<NoLintToken> NoLints,
188 SmallVectorImpl<NoLintToken> &UnmatchedTokens) {
189 SmallVector<NoLintBlockToken> CompletedBlocks;
190 SmallVector<NoLintToken> Stack;
191
192 // Nested blocks must be fully contained within their parent block. What this
193 // means is that when you have a series of nested BEGIN tokens, the END tokens
194 // shall appear in the reverse order, starting with the closing of the
195 // inner-most block first, then the next level up, and so on. This is
196 // essentially a last-in-first-out/stack system.
197 for (NoLintToken &NoLint : NoLints) {
198 if (NoLint.Type == NoLintType::NoLintBegin)
199 // A new block is being started. Add it to the stack.
200 Stack.emplace_back(std::move(NoLint));
201 else if (NoLint.Type == NoLintType::NoLintEnd) {
202 if (!Stack.empty() && Stack.back().checks() == NoLint.checks())
203 // The previous block is being closed. Pop one element off the stack.
204 CompletedBlocks.emplace_back(Stack.pop_back_val(), NoLint);
205 else
206 // Trying to close the wrong block.
207 UnmatchedTokens.emplace_back(std::move(NoLint));
208 }
209 }
210
211 llvm::move(Stack, std::back_inserter(UnmatchedTokens));
212 return CompletedBlocks;
213 }
214
215 //===----------------------------------------------------------------------===//
216 // NoLintDirectiveHandler::Impl
217 //===----------------------------------------------------------------------===//
218
219 class NoLintDirectiveHandler::Impl {
220 public:
221 bool shouldSuppress(DiagnosticsEngine::Level DiagLevel,
222 const Diagnostic &Diag, StringRef DiagName,
223 SmallVectorImpl<tooling::Diagnostic> &NoLintErrors,
224 bool AllowIO, bool EnableNoLintBlocks);
225
226 private:
227 bool diagHasNoLintInMacro(const Diagnostic &Diag, StringRef DiagName,
228 SmallVectorImpl<tooling::Diagnostic> &NoLintErrors,
229 bool AllowIO, bool EnableNoLintBlocks);
230
231 bool diagHasNoLint(StringRef DiagName, SourceLocation DiagLoc,
232 const SourceManager &SrcMgr,
233 SmallVectorImpl<tooling::Diagnostic> &NoLintErrors,
234 bool AllowIO, bool EnableNoLintBlocks);
235
236 void generateCache(const SourceManager &SrcMgr, StringRef FileName,
237 FileID File, StringRef Buffer,
238 SmallVectorImpl<tooling::Diagnostic> &NoLintErrors);
239
240 llvm::StringMap<SmallVector<NoLintBlockToken>> Cache;
241 };
242
shouldSuppress(DiagnosticsEngine::Level DiagLevel,const Diagnostic & Diag,StringRef DiagName,SmallVectorImpl<tooling::Diagnostic> & NoLintErrors,bool AllowIO,bool EnableNoLintBlocks)243 bool NoLintDirectiveHandler::Impl::shouldSuppress(
244 DiagnosticsEngine::Level DiagLevel, const Diagnostic &Diag,
245 StringRef DiagName, SmallVectorImpl<tooling::Diagnostic> &NoLintErrors,
246 bool AllowIO, bool EnableNoLintBlocks) {
247 if (DiagLevel >= DiagnosticsEngine::Error)
248 return false;
249 return diagHasNoLintInMacro(Diag, DiagName, NoLintErrors, AllowIO,
250 EnableNoLintBlocks);
251 }
252
253 // Look at the macro's spelling location for a NOLINT. If none is found, keep
254 // looking up the call stack.
diagHasNoLintInMacro(const Diagnostic & Diag,StringRef DiagName,SmallVectorImpl<tooling::Diagnostic> & NoLintErrors,bool AllowIO,bool EnableNoLintBlocks)255 bool NoLintDirectiveHandler::Impl::diagHasNoLintInMacro(
256 const Diagnostic &Diag, StringRef DiagName,
257 SmallVectorImpl<tooling::Diagnostic> &NoLintErrors, bool AllowIO,
258 bool EnableNoLintBlocks) {
259 SourceLocation DiagLoc = Diag.getLocation();
260 if (DiagLoc.isInvalid())
261 return false;
262 const SourceManager &SrcMgr = Diag.getSourceManager();
263 while (true) {
264 if (diagHasNoLint(DiagName, DiagLoc, SrcMgr, NoLintErrors, AllowIO,
265 EnableNoLintBlocks))
266 return true;
267 if (!DiagLoc.isMacroID())
268 return false;
269 DiagLoc = SrcMgr.getImmediateExpansionRange(DiagLoc).getBegin();
270 }
271 return false;
272 }
273
274 // Look behind and ahead for '\n' characters. These mark the start and end of
275 // this line.
getLineStartAndEnd(StringRef Buffer,size_t From)276 static std::pair<size_t, size_t> getLineStartAndEnd(StringRef Buffer,
277 size_t From) {
278 size_t StartPos = Buffer.find_last_of('\n', From) + 1;
279 size_t EndPos = std::min(Buffer.find('\n', From), Buffer.size());
280 return std::make_pair(StartPos, EndPos);
281 }
282
283 // Whether the line has a NOLINT of type = `Type` that can suppress the
284 // diagnostic `DiagName`.
lineHasNoLint(StringRef Buffer,std::pair<size_t,size_t> LineStartAndEnd,NoLintType Type,StringRef DiagName)285 static bool lineHasNoLint(StringRef Buffer,
286 std::pair<size_t, size_t> LineStartAndEnd,
287 NoLintType Type, StringRef DiagName) {
288 // Get all NOLINTs on the line.
289 Buffer = Buffer.slice(LineStartAndEnd.first, LineStartAndEnd.second);
290 SmallVector<NoLintToken> NoLints = getNoLints(Buffer);
291
292 // Do any of these NOLINTs match the desired type and diag name?
293 return llvm::any_of(NoLints, [&](const NoLintToken &NoLint) {
294 return NoLint.Type == Type && NoLint.suppresses(DiagName);
295 });
296 }
297
298 // Whether the provided diagnostic is located within and is suppressible by a
299 // block of NOLINT(BEGIN/END) comments.
withinNoLintBlock(ArrayRef<NoLintBlockToken> NoLintBlocks,size_t DiagPos,StringRef DiagName)300 static bool withinNoLintBlock(ArrayRef<NoLintBlockToken> NoLintBlocks,
301 size_t DiagPos, StringRef DiagName) {
302 return llvm::any_of(NoLintBlocks, [&](const NoLintBlockToken &NoLintBlock) {
303 return NoLintBlock.suppresses(DiagPos, DiagName);
304 });
305 }
306
307 // Get the file contents as a string.
getBuffer(const SourceManager & SrcMgr,FileID File,bool AllowIO)308 static Optional<StringRef> getBuffer(const SourceManager &SrcMgr, FileID File,
309 bool AllowIO) {
310 return AllowIO ? SrcMgr.getBufferDataOrNone(File)
311 : SrcMgr.getBufferDataIfLoaded(File);
312 }
313
314 // We will check for NOLINTs and NOLINTNEXTLINEs first. Checking for these is
315 // not so expensive (just need to parse the current and previous lines). Only if
316 // that fails do we look for NOLINT(BEGIN/END) blocks (which requires reading
317 // the entire file).
diagHasNoLint(StringRef DiagName,SourceLocation DiagLoc,const SourceManager & SrcMgr,SmallVectorImpl<tooling::Diagnostic> & NoLintErrors,bool AllowIO,bool EnableNoLintBlocks)318 bool NoLintDirectiveHandler::Impl::diagHasNoLint(
319 StringRef DiagName, SourceLocation DiagLoc, const SourceManager &SrcMgr,
320 SmallVectorImpl<tooling::Diagnostic> &NoLintErrors, bool AllowIO,
321 bool EnableNoLintBlocks) {
322 // Translate the diagnostic's SourceLocation to a raw file + offset pair.
323 FileID File;
324 unsigned int Pos = 0;
325 std::tie(File, Pos) = SrcMgr.getDecomposedSpellingLoc(DiagLoc);
326
327 // We will only see NOLINTs in user-authored sources. No point reading the
328 // file if it is a <built-in>.
329 Optional<StringRef> FileName = SrcMgr.getNonBuiltinFilenameForID(File);
330 if (!FileName)
331 return false;
332
333 // Get file contents.
334 Optional<StringRef> Buffer = getBuffer(SrcMgr, File, AllowIO);
335 if (!Buffer)
336 return false;
337
338 // Check if there's a NOLINT on this line.
339 auto ThisLine = getLineStartAndEnd(*Buffer, Pos);
340 if (lineHasNoLint(*Buffer, ThisLine, NoLintType::NoLint, DiagName))
341 return true;
342
343 // Check if there's a NOLINTNEXTLINE on the previous line.
344 if (ThisLine.first > 0) {
345 auto PrevLine = getLineStartAndEnd(*Buffer, ThisLine.first - 1);
346 if (lineHasNoLint(*Buffer, PrevLine, NoLintType::NoLintNextLine, DiagName))
347 return true;
348 }
349
350 // Check if this line is within a NOLINT(BEGIN/END) block.
351 if (!EnableNoLintBlocks)
352 return false;
353
354 // Do we have cached NOLINT block locations for this file?
355 if (Cache.count(*FileName) == 0)
356 // Warning: heavy operation - need to read entire file.
357 generateCache(SrcMgr, *FileName, File, *Buffer, NoLintErrors);
358
359 return withinNoLintBlock(Cache[*FileName], Pos, DiagName);
360 }
361
362 // Construct a [clang-tidy-nolint] diagnostic to do with the unmatched
363 // NOLINT(BEGIN/END) pair.
makeNoLintError(const SourceManager & SrcMgr,FileID File,const NoLintToken & NoLint)364 static tooling::Diagnostic makeNoLintError(const SourceManager &SrcMgr,
365 FileID File,
366 const NoLintToken &NoLint) {
367 tooling::Diagnostic Error;
368 Error.DiagLevel = tooling::Diagnostic::Error;
369 Error.DiagnosticName = "clang-tidy-nolint";
370 StringRef Message =
371 (NoLint.Type == NoLintType::NoLintBegin)
372 ? ("unmatched 'NOLINTBEGIN' comment without a subsequent 'NOLINT"
373 "END' comment")
374 : ("unmatched 'NOLINTEND' comment without a previous 'NOLINT"
375 "BEGIN' comment");
376 SourceLocation Loc = SrcMgr.getComposedLoc(File, NoLint.Pos);
377 Error.Message = tooling::DiagnosticMessage(Message, SrcMgr, Loc);
378 return Error;
379 }
380
381 // Find all NOLINT(BEGIN/END) blocks in a file and store in the cache.
generateCache(const SourceManager & SrcMgr,StringRef FileName,FileID File,StringRef Buffer,SmallVectorImpl<tooling::Diagnostic> & NoLintErrors)382 void NoLintDirectiveHandler::Impl::generateCache(
383 const SourceManager &SrcMgr, StringRef FileName, FileID File,
384 StringRef Buffer, SmallVectorImpl<tooling::Diagnostic> &NoLintErrors) {
385 // Read entire file to get all NOLINTs.
386 SmallVector<NoLintToken> NoLints = getNoLints(Buffer);
387
388 // Match each BEGIN with its corresponding END.
389 SmallVector<NoLintToken> UnmatchedTokens;
390 Cache[FileName] = formNoLintBlocks(std::move(NoLints), UnmatchedTokens);
391
392 // Raise error for any BEGIN/END left over.
393 for (const NoLintToken &NoLint : UnmatchedTokens)
394 NoLintErrors.emplace_back(makeNoLintError(SrcMgr, File, NoLint));
395 }
396
397 //===----------------------------------------------------------------------===//
398 // NoLintDirectiveHandler
399 //===----------------------------------------------------------------------===//
400
NoLintDirectiveHandler()401 NoLintDirectiveHandler::NoLintDirectiveHandler()
402 : PImpl(std::make_unique<Impl>()) {}
403
404 NoLintDirectiveHandler::~NoLintDirectiveHandler() = default;
405
shouldSuppress(DiagnosticsEngine::Level DiagLevel,const Diagnostic & Diag,StringRef DiagName,SmallVectorImpl<tooling::Diagnostic> & NoLintErrors,bool AllowIO,bool EnableNoLintBlocks)406 bool NoLintDirectiveHandler::shouldSuppress(
407 DiagnosticsEngine::Level DiagLevel, const Diagnostic &Diag,
408 StringRef DiagName, SmallVectorImpl<tooling::Diagnostic> &NoLintErrors,
409 bool AllowIO, bool EnableNoLintBlocks) {
410 return PImpl->shouldSuppress(DiagLevel, Diag, DiagName, NoLintErrors, AllowIO,
411 EnableNoLintBlocks);
412 }
413
414 } // namespace tidy
415 } // namespace clang
416