1//===- BugReporter.h - Generate PathDiagnostics -----------------*- 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// This file defines BugReporter, a utility class for generating
10// PathDiagnostics for analyses based on ProgramState.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_CLANG_STATICANALYZER_CORE_BUGREPORTER_BUGREPORTER_H
15#define LLVM_CLANG_STATICANALYZER_CORE_BUGREPORTER_BUGREPORTER_H
16
17#include "clang/Basic/LLVM.h"
18#include "clang/Basic/SourceLocation.h"
19#include "clang/StaticAnalyzer/Core/BugReporter/BugReporterVisitors.h"
20#include "clang/StaticAnalyzer/Core/BugReporter/PathDiagnostic.h"
21#include "clang/StaticAnalyzer/Core/CheckerManager.h"
22#include "clang/StaticAnalyzer/Core/PathSensitive/ProgramState.h"
23#include "clang/StaticAnalyzer/Core/PathSensitive/SVals.h"
24#include "clang/StaticAnalyzer/Core/PathSensitive/SymExpr.h"
25#include "clang/StaticAnalyzer/Core/PathSensitive/ExplodedGraph.h"
26#include "llvm/ADT/ArrayRef.h"
27#include "llvm/ADT/DenseSet.h"
28#include "llvm/ADT/FoldingSet.h"
29#include "llvm/ADT/ImmutableSet.h"
30#include "llvm/ADT/None.h"
31#include "llvm/ADT/SmallSet.h"
32#include "llvm/ADT/SmallVector.h"
33#include "llvm/ADT/StringMap.h"
34#include "llvm/ADT/StringRef.h"
35#include "llvm/ADT/ilist.h"
36#include "llvm/ADT/ilist_node.h"
37#include "llvm/ADT/iterator_range.h"
38#include <cassert>
39#include <memory>
40#include <string>
41#include <utility>
42#include <vector>
43
44namespace clang {
45
46class AnalyzerOptions;
47class ASTContext;
48class Decl;
49class DiagnosticsEngine;
50class LocationContext;
51class SourceManager;
52class Stmt;
53
54namespace ento {
55
56class BugType;
57class CheckerBase;
58class ExplodedGraph;
59class ExplodedNode;
60class ExprEngine;
61class MemRegion;
62class SValBuilder;
63
64//===----------------------------------------------------------------------===//
65// Interface for individual bug reports.
66//===----------------------------------------------------------------------===//
67
68/// A mapping from diagnostic consumers to the diagnostics they should
69/// consume.
70using DiagnosticForConsumerMapTy =
71 llvm::DenseMap<PathDiagnosticConsumer *, std::unique_ptr<PathDiagnostic>>;
72
73/// This class provides an interface through which checkers can create
74/// individual bug reports.
75class BugReport : public llvm::ilist_node<BugReport> {
76public:
77 class NodeResolver {
78 virtual void anchor();
79
80 public:
81 virtual ~NodeResolver() = default;
82
83 virtual const ExplodedNode*
84 getOriginalNode(const ExplodedNode *N) = 0;
85 };
86
87 using ranges_iterator = const SourceRange *;
88 using VisitorList = SmallVector<std::unique_ptr<BugReporterVisitor>, 8>;
89 using visitor_iterator = VisitorList::iterator;
90 using ExtraTextList = SmallVector<StringRef, 2>;
91 using NoteList = SmallVector<std::shared_ptr<PathDiagnosticNotePiece>, 4>;
92
93protected:
94 friend class BugReportEquivClass;
95 friend class BugReporter;
96
97 const BugType& BT;
98 const Decl *DeclWithIssue = nullptr;
99 std::string ShortDescription;
100 std::string Description;
101 PathDiagnosticLocation Location;
102 PathDiagnosticLocation UniqueingLocation;
103 const Decl *UniqueingDecl;
104
105 const ExplodedNode *ErrorNode = nullptr;
106 SmallVector<SourceRange, 4> Ranges;
107 ExtraTextList ExtraText;
108 NoteList Notes;
109
110 using Symbols = llvm::DenseSet<SymbolRef>;
111 using Regions = llvm::DenseSet<const MemRegion *>;
112
113 /// A (stack of) a set of symbols that are registered with this
114 /// report as being "interesting", and thus used to help decide which
115 /// diagnostics to include when constructing the final path diagnostic.
116 /// The stack is largely used by BugReporter when generating PathDiagnostics
117 /// for multiple PathDiagnosticConsumers.
118 SmallVector<Symbols *, 2> interestingSymbols;
119
120 /// A (stack of) set of regions that are registered with this report as being
121 /// "interesting", and thus used to help decide which diagnostics
122 /// to include when constructing the final path diagnostic.
123 /// The stack is largely used by BugReporter when generating PathDiagnostics
124 /// for multiple PathDiagnosticConsumers.
125 SmallVector<Regions *, 2> interestingRegions;
126
127 /// A set of location contexts that correspoind to call sites which should be
128 /// considered "interesting".
129 llvm::SmallSet<const LocationContext *, 2> InterestingLocationContexts;
130
131 /// A set of custom visitors which generate "event" diagnostics at
132 /// interesting points in the path.
133 VisitorList Callbacks;
134
135 /// Used for ensuring the visitors are only added once.
136 llvm::FoldingSet<BugReporterVisitor> CallbacksSet;
137
138 /// When set, this flag disables all callstack pruning from a diagnostic
139 /// path. This is useful for some reports that want maximum fidelty
140 /// when reporting an issue.
141 bool DoNotPrunePath = false;
142
143 /// Used to track unique reasons why a bug report might be invalid.
144 ///
145 /// \sa markInvalid
146 /// \sa removeInvalidation
147 using InvalidationRecord = std::pair<const void *, const void *>;
148
149 /// If non-empty, this bug report is likely a false positive and should not be
150 /// shown to the user.
151 ///
152 /// \sa markInvalid
153 /// \sa removeInvalidation
154 llvm::SmallSet<InvalidationRecord, 4> Invalidations;
155
156private:
157 // Used internally by BugReporter.
158 Symbols &getInterestingSymbols();
159 Regions &getInterestingRegions();
160
161 void lazyInitializeInterestingSets();
162 void pushInterestingSymbolsAndRegions();
163 void popInterestingSymbolsAndRegions();
164
165public:
166 BugReport(const BugType& bt, StringRef desc, const ExplodedNode *errornode)
167 : BT(bt), Description(desc), ErrorNode(errornode) {}
168
169 BugReport(const BugType& bt, StringRef shortDesc, StringRef desc,
170 const ExplodedNode *errornode)
171 : BT(bt), ShortDescription(shortDesc), Description(desc),
172 ErrorNode(errornode) {}
173
174 BugReport(const BugType &bt, StringRef desc, PathDiagnosticLocation l)
175 : BT(bt), Description(desc), Location(l) {}
176
177 /// Create a BugReport with a custom uniqueing location.
178 ///
179 /// The reports that have the same report location, description, bug type, and
180 /// ranges are uniqued - only one of the equivalent reports will be presented
181 /// to the user. This method allows to rest the location which should be used
182 /// for uniquing reports. For example, memory leaks checker, could set this to
183 /// the allocation site, rather then the location where the bug is reported.
184 BugReport(BugType& bt, StringRef desc, const ExplodedNode *errornode,
185 PathDiagnosticLocation LocationToUnique, const Decl *DeclToUnique)
186 : BT(bt), Description(desc), UniqueingLocation(LocationToUnique),
187 UniqueingDecl(DeclToUnique), ErrorNode(errornode) {}
188
189 virtual ~BugReport();
190
191 const BugType& getBugType() const { return BT; }
192 //BugType& getBugType() { return BT; }
193
194 /// True when the report has an execution path associated with it.
195 ///
196 /// A report is said to be path-sensitive if it was thrown against a
197 /// particular exploded node in the path-sensitive analysis graph.
198 /// Path-sensitive reports have their intermediate path diagnostics
199 /// auto-generated, perhaps with the help of checker-defined visitors,
200 /// and may contain extra notes.
201 /// Path-insensitive reports consist only of a single warning message
202 /// in a specific location, and perhaps extra notes.
203 /// Path-sensitive checkers are allowed to throw path-insensitive reports.
204 bool isPathSensitive() const { return ErrorNode != nullptr; }
205
206 const ExplodedNode *getErrorNode() const { return ErrorNode; }
207
208 StringRef getDescription() const { return Description; }
209
210 StringRef getShortDescription(bool UseFallback = true) const {
211 if (ShortDescription.empty() && UseFallback)
212 return Description;
213 return ShortDescription;
214 }
215
216 /// Indicates whether or not any path pruning should take place
217 /// when generating a PathDiagnostic from this BugReport.
218 bool shouldPrunePath() const { return !DoNotPrunePath; }
219
220 /// Disable all path pruning when generating a PathDiagnostic.
221 void disablePathPruning() { DoNotPrunePath = true; }
222
223 void markInteresting(SymbolRef sym);
224 void markInteresting(const MemRegion *R);
225 void markInteresting(SVal V);
226 void markInteresting(const LocationContext *LC);
227
228 bool isInteresting(SymbolRef sym);
229 bool isInteresting(const MemRegion *R);
230 bool isInteresting(SVal V);
231 bool isInteresting(const LocationContext *LC);
232
233 /// Returns whether or not this report should be considered valid.
234 ///
235 /// Invalid reports are those that have been classified as likely false
236 /// positives after the fact.
237 bool isValid() const {
238 return Invalidations.empty();
239 }
240
241 /// Marks the current report as invalid, meaning that it is probably a false
242 /// positive and should not be reported to the user.
243 ///
244 /// The \p Tag and \p Data arguments are intended to be opaque identifiers for
245 /// this particular invalidation, where \p Tag represents the visitor
246 /// responsible for invalidation, and \p Data represents the reason this
247 /// visitor decided to invalidate the bug report.
248 ///
249 /// \sa removeInvalidation
250 void markInvalid(const void *Tag, const void *Data) {
251 Invalidations.insert(std::make_pair(Tag, Data));
252 }
253
254 /// Return the canonical declaration, be it a method or class, where
255 /// this issue semantically occurred.
256 const Decl *getDeclWithIssue() const;
257
258 /// Specifically set the Decl where an issue occurred. This isn't necessary
259 /// for BugReports that cover a path as it will be automatically inferred.
260 void setDeclWithIssue(const Decl *declWithIssue) {
261 DeclWithIssue = declWithIssue;
262 }
263
264 /// Add new item to the list of additional notes that need to be attached to
265 /// this path-insensitive report. If you want to add extra notes to a
266 /// path-sensitive report, you need to use a BugReporterVisitor because it
267 /// allows you to specify where exactly in the auto-generated path diagnostic
268 /// the extra note should appear.
269 void addNote(StringRef Msg, const PathDiagnosticLocation &Pos,
270 ArrayRef<SourceRange> Ranges) {
271 auto P = std::make_shared<PathDiagnosticNotePiece>(Pos, Msg);
272
273 for (const auto &R : Ranges)
274 P->addRange(R);
275
276 Notes.push_back(std::move(P));
277 }
278
279 // FIXME: Instead of making an override, we could have default-initialized
280 // Ranges with {}, however it crashes the MSVC 2013 compiler.
281 void addNote(StringRef Msg, const PathDiagnosticLocation &Pos) {
282 std::vector<SourceRange> Ranges;
283 addNote(Msg, Pos, Ranges);
284 }
285
286 virtual const NoteList &getNotes() {
287 return Notes;
288 }
289
290 /// This allows for addition of meta data to the diagnostic.
291 ///
292 /// Currently, only the HTMLDiagnosticClient knows how to display it.
293 void addExtraText(StringRef S) {
294 ExtraText.push_back(S);
295 }
296
297 virtual const ExtraTextList &getExtraText() {
298 return ExtraText;
299 }
300
301 /// Return the "definitive" location of the reported bug.
302 ///
303 /// While a bug can span an entire path, usually there is a specific
304 /// location that can be used to identify where the key issue occurred.
305 /// This location is used by clients rendering diagnostics.
306 virtual PathDiagnosticLocation getLocation(const SourceManager &SM) const;
307
308 /// Get the location on which the report should be uniqued.
309 PathDiagnosticLocation getUniqueingLocation() const {
310 return UniqueingLocation;
311 }
312
313 /// Get the declaration containing the uniqueing location.
314 const Decl *getUniqueingDecl() const {
315 return UniqueingDecl;
316 }
317
318 const Stmt *getStmt() const;
319
320 /// Add a range to a bug report.
321 ///
322 /// Ranges are used to highlight regions of interest in the source code.
323 /// They should be at the same source code line as the BugReport location.
324 /// By default, the source range of the statement corresponding to the error
325 /// node will be used; add a single invalid range to specify absence of
326 /// ranges.
327 void addRange(SourceRange R) {
328 assert((R.isValid() || Ranges.empty()) && "Invalid range can only be used "
329 "to specify that the report does not have a range.");
330 Ranges.push_back(R);
331 }
332
333 /// Get the SourceRanges associated with the report.
334 virtual llvm::iterator_range<ranges_iterator> getRanges();
335
336 /// Add custom or predefined bug report visitors to this report.
337 ///
338 /// The visitors should be used when the default trace is not sufficient.
339 /// For example, they allow constructing a more elaborate trace.
340 /// \sa registerConditionVisitor(), registerTrackNullOrUndefValue(),
341 /// registerFindLastStore(), registerNilReceiverVisitor(), and
342 /// registerVarDeclsLastStore().
343 void addVisitor(std::unique_ptr<BugReporterVisitor> visitor);
344
345 /// Remove all visitors attached to this bug report.
346 void clearVisitors();
347
348 /// Iterators through the custom diagnostic visitors.
349 visitor_iterator visitor_begin() { return Callbacks.begin(); }
350 visitor_iterator visitor_end() { return Callbacks.end(); }
351
352 /// Profile to identify equivalent bug reports for error report coalescing.
353 /// Reports are uniqued to ensure that we do not emit multiple diagnostics
354 /// for each bug.
355 virtual void Profile(llvm::FoldingSetNodeID& hash) const;
356};
357
358//===----------------------------------------------------------------------===//
359// BugTypes (collections of related reports).
360//===----------------------------------------------------------------------===//
361
362class BugReportEquivClass : public llvm::FoldingSetNode {
363 friend class BugReporter;
364
365 /// List of *owned* BugReport objects.
366 llvm::ilist<BugReport> Reports;
367
368 void AddReport(std::unique_ptr<BugReport> R) {
369 Reports.push_back(R.release());
370 }
371
372public:
373 BugReportEquivClass(std::unique_ptr<BugReport> R) { AddReport(std::move(R)); }
374 ~BugReportEquivClass();
375
376 void Profile(llvm::FoldingSetNodeID& ID) const {
377 assert(!Reports.empty());
378 Reports.front().Profile(ID);
379 }
380
381 using iterator = llvm::ilist<BugReport>::iterator;
382 using const_iterator = llvm::ilist<BugReport>::const_iterator;
383
384 iterator begin() { return Reports.begin(); }
385 iterator end() { return Reports.end(); }
386
387 const_iterator begin() const { return Reports.begin(); }
388 const_iterator end() const { return Reports.end(); }
389};
390
391//===----------------------------------------------------------------------===//
392// BugReporter and friends.
393//===----------------------------------------------------------------------===//
394
395class BugReporterData {
396public:
397 virtual ~BugReporterData();
398
399 virtual DiagnosticsEngine& getDiagnostic() = 0;
400 virtual ArrayRef<PathDiagnosticConsumer*> getPathDiagnosticConsumers() = 0;
401 virtual ASTContext &getASTContext() = 0;
402 virtual SourceManager &getSourceManager() = 0;
403 virtual AnalyzerOptions &getAnalyzerOptions() = 0;
404};
405
406/// BugReporter is a utility class for generating PathDiagnostics for analysis.
407/// It collects the BugReports and BugTypes and knows how to generate
408/// and flush the corresponding diagnostics.
409///
410/// The base class is used for generating path-insensitive
411class BugReporter {
412public:
413 enum Kind { BaseBRKind, GRBugReporterKind };
414
415private:
416 using BugTypesTy = llvm::ImmutableSet<BugType *>;
417
418 BugTypesTy::Factory F;
419 BugTypesTy BugTypes;
420
421 const Kind kind;
422 BugReporterData& D;
423
424 /// Generate and flush the diagnostics for the given bug report.
425 void FlushReport(BugReportEquivClass& EQ);
426
427 /// Generate the diagnostics for the given bug report.
428 std::unique_ptr<DiagnosticForConsumerMapTy>
429 generateDiagnosticForConsumerMap(BugReport *exampleReport,
430 ArrayRef<PathDiagnosticConsumer *> consumers,
431 ArrayRef<BugReport *> bugReports);
432
433 /// The set of bug reports tracked by the BugReporter.
434 llvm::FoldingSet<BugReportEquivClass> EQClasses;
435
436 /// A vector of BugReports for tracking the allocated pointers and cleanup.
437 std::vector<BugReportEquivClass *> EQClassesVector;
438
439protected:
440 BugReporter(BugReporterData& d, Kind k)
441 : BugTypes(F.getEmptySet()), kind(k), D(d) {}
442
443public:
444 BugReporter(BugReporterData& d)
445 : BugTypes(F.getEmptySet()), kind(BaseBRKind), D(d) {}
446 virtual ~BugReporter();
447
448 /// Generate and flush diagnostics for all bug reports.
449 void FlushReports();
450
451 Kind getKind() const { return kind; }
452
453 DiagnosticsEngine& getDiagnostic() {
454 return D.getDiagnostic();
455 }
456
457 ArrayRef<PathDiagnosticConsumer*> getPathDiagnosticConsumers() {
458 return D.getPathDiagnosticConsumers();
459 }
460
461 /// Iterator over the set of BugTypes tracked by the BugReporter.
462 using iterator = BugTypesTy::iterator;
463 iterator begin() { return BugTypes.begin(); }
464 iterator end() { return BugTypes.end(); }
465
466 /// Iterator over the set of BugReports tracked by the BugReporter.
467 using EQClasses_iterator = llvm::FoldingSet<BugReportEquivClass>::iterator;
468 EQClasses_iterator EQClasses_begin() { return EQClasses.begin(); }
469 EQClasses_iterator EQClasses_end() { return EQClasses.end(); }
470
471 ASTContext &getContext() { return D.getASTContext(); }
472
473 SourceManager &getSourceManager() { return D.getSourceManager(); }
474
475 AnalyzerOptions &getAnalyzerOptions() { return D.getAnalyzerOptions(); }
476
477 virtual std::unique_ptr<DiagnosticForConsumerMapTy>
478 generatePathDiagnostics(ArrayRef<PathDiagnosticConsumer *> consumers,
479 ArrayRef<BugReport *> &bugReports) {
480 return {};
481 }
482
483 void Register(const BugType *BT);
484
485 /// Add the given report to the set of reports tracked by BugReporter.
486 ///
487 /// The reports are usually generated by the checkers. Further, they are
488 /// folded based on the profile value, which is done to coalesce similar
489 /// reports.
490 void emitReport(std::unique_ptr<BugReport> R);
491
492 void EmitBasicReport(const Decl *DeclWithIssue, const CheckerBase *Checker,
493 StringRef BugName, StringRef BugCategory,
494 StringRef BugStr, PathDiagnosticLocation Loc,
495 ArrayRef<SourceRange> Ranges = None);
496
497 void EmitBasicReport(const Decl *DeclWithIssue, CheckName CheckName,
498 StringRef BugName, StringRef BugCategory,
499 StringRef BugStr, PathDiagnosticLocation Loc,
500 ArrayRef<SourceRange> Ranges = None);
501
502private:
503 llvm::StringMap<BugType *> StrBugTypes;
504
505 /// Returns a BugType that is associated with the given name and
506 /// category.
507 BugType *getBugTypeForName(CheckName CheckName, StringRef name,
508 StringRef category);
509};
510
511/// GRBugReporter is used for generating path-sensitive reports.
512class GRBugReporter : public BugReporter {
513 ExprEngine& Eng;
514
515public:
516 GRBugReporter(BugReporterData& d, ExprEngine& eng)
517 : BugReporter(d, GRBugReporterKind), Eng(eng) {}
518
519 ~GRBugReporter() override;
520
521 /// getGraph - Get the exploded graph created by the analysis engine
522 /// for the analyzed method or function.
523 ExplodedGraph &getGraph();
524
525 /// getStateManager - Return the state manager used by the analysis
526 /// engine.
527 ProgramStateManager &getStateManager();
528
529 /// \p bugReports A set of bug reports within a *single* equivalence class
530 ///
531 /// \return A mapping from consumers to the corresponding diagnostics.
532 /// Iterates through the bug reports within a single equivalence class,
533 /// stops at a first non-invalidated report.
534 std::unique_ptr<DiagnosticForConsumerMapTy>
535 generatePathDiagnostics(ArrayRef<PathDiagnosticConsumer *> consumers,
536 ArrayRef<BugReport *> &bugReports) override;
537
538 /// classof - Used by isa<>, cast<>, and dyn_cast<>.
539 static bool classof(const BugReporter* R) {
540 return R->getKind() == GRBugReporterKind;
541 }
542};
543
544
545class NodeMapClosure : public BugReport::NodeResolver {
546 InterExplodedGraphMap &M;
547
548public:
549 NodeMapClosure(InterExplodedGraphMap &m) : M(m) {}
550
551 const ExplodedNode *getOriginalNode(const ExplodedNode *N) override {
552 return M.lookup(N);
553 }
554};
555
556class BugReporterContext {
557 GRBugReporter &BR;
558 NodeMapClosure NMC;
559
560 virtual void anchor();
561
562public:
563 BugReporterContext(GRBugReporter &br, InterExplodedGraphMap &Backmap)
564 : BR(br), NMC(Backmap) {}
565
566 virtual ~BugReporterContext() = default;
567
568 GRBugReporter& getBugReporter() { return BR; }
569
570 ExplodedGraph &getGraph() { return BR.getGraph(); }
571
572 ProgramStateManager& getStateManager() {
573 return BR.getStateManager();
574 }
575
576 SValBuilder &getSValBuilder() {
577 return getStateManager().getSValBuilder();
578 }
579
580 ASTContext &getASTContext() {
581 return BR.getContext();
582 }
583
584 SourceManager& getSourceManager() {
585 return BR.getSourceManager();
586 }
587
588 AnalyzerOptions &getAnalyzerOptions() {
589 return BR.getAnalyzerOptions();
590 }
591
592 NodeMapClosure& getNodeResolver() { return NMC; }
593};
594
595} // namespace ento
596
597} // namespace clang
598
599#endif // LLVM_CLANG_STATICANALYZER_CORE_BUGREPORTER_BUGREPORTER_H
600