1 //===--- BugReporter.h - Generate PathDiagnostics --------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file defines BugReporter, a utility class for generating
11 // PathDiagnostics for analyses based on ProgramState.
13 //===----------------------------------------------------------------------===//
15 #ifndef LLVM_CLANG_GR_BUGREPORTER
16 #define LLVM_CLANG_GR_BUGREPORTER
18 #include "clang/Basic/SourceLocation.h"
19 #include "clang/StaticAnalyzer/Core/BugReporter/BugReporterVisitor.h"
20 #include "clang/StaticAnalyzer/Core/BugReporter/PathDiagnostic.h"
21 #include "clang/StaticAnalyzer/Core/PathSensitive/ProgramState.h"
22 #include "llvm/ADT/DenseSet.h"
23 #include "llvm/ADT/FoldingSet.h"
24 #include "llvm/ADT/ImmutableSet.h"
25 #include "llvm/ADT/SmallSet.h"
26 #include "llvm/ADT/ilist.h"
27 #include "llvm/ADT/ilist_node.h"
32 class DiagnosticsEngine;
43 class BugReporterContext;
47 //===----------------------------------------------------------------------===//
48 // Interface for individual bug reports.
49 //===----------------------------------------------------------------------===//
51 /// This class provides an interface through which checkers can create
52 /// individual bug reports.
53 class BugReport : public llvm::ilist_node<BugReport> {
56 virtual void anchor();
58 virtual ~NodeResolver() {}
59 virtual const ExplodedNode*
60 getOriginalNode(const ExplodedNode *N) = 0;
63 typedef const SourceRange *ranges_iterator;
64 typedef SmallVector<BugReporterVisitor *, 8> VisitorList;
65 typedef VisitorList::iterator visitor_iterator;
66 typedef SmallVector<StringRef, 2> ExtraTextList;
69 friend class BugReporter;
70 friend class BugReportEquivClass;
73 const Decl *DeclWithIssue;
74 std::string ShortDescription;
75 std::string Description;
76 PathDiagnosticLocation Location;
77 PathDiagnosticLocation UniqueingLocation;
78 const Decl *UniqueingDecl;
80 const ExplodedNode *ErrorNode;
81 SmallVector<SourceRange, 4> Ranges;
82 ExtraTextList ExtraText;
84 typedef llvm::DenseSet<SymbolRef> Symbols;
85 typedef llvm::DenseSet<const MemRegion *> Regions;
87 /// A (stack of) a set of symbols that are registered with this
88 /// report as being "interesting", and thus used to help decide which
89 /// diagnostics to include when constructing the final path diagnostic.
90 /// The stack is largely used by BugReporter when generating PathDiagnostics
91 /// for multiple PathDiagnosticConsumers.
92 SmallVector<Symbols *, 2> interestingSymbols;
94 /// A (stack of) set of regions that are registered with this report as being
95 /// "interesting", and thus used to help decide which diagnostics
96 /// to include when constructing the final path diagnostic.
97 /// The stack is largely used by BugReporter when generating PathDiagnostics
98 /// for multiple PathDiagnosticConsumers.
99 SmallVector<Regions *, 2> interestingRegions;
101 /// A set of location contexts that correspoind to call sites which should be
102 /// considered "interesting".
103 llvm::SmallSet<const LocationContext *, 2> InterestingLocationContexts;
105 /// A set of custom visitors which generate "event" diagnostics at
106 /// interesting points in the path.
107 VisitorList Callbacks;
109 /// Used for ensuring the visitors are only added once.
110 llvm::FoldingSet<BugReporterVisitor> CallbacksSet;
112 /// Used for clients to tell if the report's configuration has changed
113 /// since the last time they checked.
114 unsigned ConfigurationChangeToken;
116 /// When set, this flag disables all callstack pruning from a diagnostic
117 /// path. This is useful for some reports that want maximum fidelty
118 /// when reporting an issue.
121 /// Used to track unique reasons why a bug report might be invalid.
124 /// \sa removeInvalidation
125 typedef std::pair<const void *, const void *> InvalidationRecord;
127 /// If non-empty, this bug report is likely a false positive and should not be
128 /// shown to the user.
131 /// \sa removeInvalidation
132 llvm::SmallSet<InvalidationRecord, 4> Invalidations;
135 // Used internally by BugReporter.
136 Symbols &getInterestingSymbols();
137 Regions &getInterestingRegions();
139 void lazyInitializeInterestingSets();
140 void pushInterestingSymbolsAndRegions();
141 void popInterestingSymbolsAndRegions();
144 BugReport(BugType& bt, StringRef desc, const ExplodedNode *errornode)
145 : BT(bt), DeclWithIssue(0), Description(desc), ErrorNode(errornode),
146 ConfigurationChangeToken(0), DoNotPrunePath(false) {}
148 BugReport(BugType& bt, StringRef shortDesc, StringRef desc,
149 const ExplodedNode *errornode)
150 : BT(bt), DeclWithIssue(0), ShortDescription(shortDesc), Description(desc),
151 ErrorNode(errornode), ConfigurationChangeToken(0),
152 DoNotPrunePath(false) {}
154 BugReport(BugType& bt, StringRef desc, PathDiagnosticLocation l)
155 : BT(bt), DeclWithIssue(0), Description(desc), Location(l), ErrorNode(0),
156 ConfigurationChangeToken(0),
157 DoNotPrunePath(false) {}
159 /// \brief Create a BugReport with a custom uniqueing location.
161 /// The reports that have the same report location, description, bug type, and
162 /// ranges are uniqued - only one of the equivalent reports will be presented
163 /// to the user. This method allows to rest the location which should be used
164 /// for uniquing reports. For example, memory leaks checker, could set this to
165 /// the allocation site, rather then the location where the bug is reported.
166 BugReport(BugType& bt, StringRef desc, const ExplodedNode *errornode,
167 PathDiagnosticLocation LocationToUnique, const Decl *DeclToUnique)
168 : BT(bt), DeclWithIssue(0), Description(desc),
169 UniqueingLocation(LocationToUnique),
170 UniqueingDecl(DeclToUnique),
171 ErrorNode(errornode), ConfigurationChangeToken(0),
172 DoNotPrunePath(false) {}
174 virtual ~BugReport();
176 const BugType& getBugType() const { return BT; }
177 BugType& getBugType() { return BT; }
179 const ExplodedNode *getErrorNode() const { return ErrorNode; }
181 const StringRef getDescription() const { return Description; }
183 const StringRef getShortDescription(bool UseFallback = true) const {
184 if (ShortDescription.empty() && UseFallback)
186 return ShortDescription;
189 /// Indicates whether or not any path pruning should take place
190 /// when generating a PathDiagnostic from this BugReport.
191 bool shouldPrunePath() const { return !DoNotPrunePath; }
193 /// Disable all path pruning when generating a PathDiagnostic.
194 void disablePathPruning() { DoNotPrunePath = true; }
196 void markInteresting(SymbolRef sym);
197 void markInteresting(const MemRegion *R);
198 void markInteresting(SVal V);
199 void markInteresting(const LocationContext *LC);
201 bool isInteresting(SymbolRef sym);
202 bool isInteresting(const MemRegion *R);
203 bool isInteresting(SVal V);
204 bool isInteresting(const LocationContext *LC);
206 unsigned getConfigurationChangeToken() const {
207 return ConfigurationChangeToken;
210 /// Returns whether or not this report should be considered valid.
212 /// Invalid reports are those that have been classified as likely false
213 /// positives after the fact.
214 bool isValid() const {
215 return Invalidations.empty();
218 /// Marks the current report as invalid, meaning that it is probably a false
219 /// positive and should not be reported to the user.
221 /// The \p Tag and \p Data arguments are intended to be opaque identifiers for
222 /// this particular invalidation, where \p Tag represents the visitor
223 /// responsible for invalidation, and \p Data represents the reason this
224 /// visitor decided to invalidate the bug report.
226 /// \sa removeInvalidation
227 void markInvalid(const void *Tag, const void *Data) {
228 Invalidations.insert(std::make_pair(Tag, Data));
231 /// Reverses the effects of a previous invalidation.
234 void removeInvalidation(const void *Tag, const void *Data) {
235 Invalidations.erase(std::make_pair(Tag, Data));
238 /// Return the canonical declaration, be it a method or class, where
239 /// this issue semantically occurred.
240 const Decl *getDeclWithIssue() const;
242 /// Specifically set the Decl where an issue occurred. This isn't necessary
243 /// for BugReports that cover a path as it will be automatically inferred.
244 void setDeclWithIssue(const Decl *declWithIssue) {
245 DeclWithIssue = declWithIssue;
248 /// \brief This allows for addition of meta data to the diagnostic.
250 /// Currently, only the HTMLDiagnosticClient knows how to display it.
251 void addExtraText(StringRef S) {
252 ExtraText.push_back(S);
255 virtual const ExtraTextList &getExtraText() {
259 /// \brief Return the "definitive" location of the reported bug.
261 /// While a bug can span an entire path, usually there is a specific
262 /// location that can be used to identify where the key issue occurred.
263 /// This location is used by clients rendering diagnostics.
264 virtual PathDiagnosticLocation getLocation(const SourceManager &SM) const;
266 /// \brief Get the location on which the report should be uniqued.
267 PathDiagnosticLocation getUniqueingLocation() const {
268 return UniqueingLocation;
271 /// \brief Get the declaration containing the uniqueing location.
272 const Decl *getUniqueingDecl() const {
273 return UniqueingDecl;
276 const Stmt *getStmt() const;
278 /// \brief Add a range to a bug report.
280 /// Ranges are used to highlight regions of interest in the source code.
281 /// They should be at the same source code line as the BugReport location.
282 /// By default, the source range of the statement corresponding to the error
283 /// node will be used; add a single invalid range to specify absence of
285 void addRange(SourceRange R) {
286 assert((R.isValid() || Ranges.empty()) && "Invalid range can only be used "
287 "to specify that the report does not have a range.");
291 /// \brief Get the SourceRanges associated with the report.
292 virtual std::pair<ranges_iterator, ranges_iterator> getRanges();
294 /// \brief Add custom or predefined bug report visitors to this report.
296 /// The visitors should be used when the default trace is not sufficient.
297 /// For example, they allow constructing a more elaborate trace.
298 /// \sa registerConditionVisitor(), registerTrackNullOrUndefValue(),
299 /// registerFindLastStore(), registerNilReceiverVisitor(), and
300 /// registerVarDeclsLastStore().
301 void addVisitor(BugReporterVisitor *visitor);
303 /// Iterators through the custom diagnostic visitors.
304 visitor_iterator visitor_begin() { return Callbacks.begin(); }
305 visitor_iterator visitor_end() { return Callbacks.end(); }
307 /// Profile to identify equivalent bug reports for error report coalescing.
308 /// Reports are uniqued to ensure that we do not emit multiple diagnostics
310 virtual void Profile(llvm::FoldingSetNodeID& hash) const;
313 } // end ento namespace
314 } // end clang namespace
317 template<> struct ilist_traits<clang::ento::BugReport>
318 : public ilist_default_traits<clang::ento::BugReport> {
319 clang::ento::BugReport *createSentinel() const {
320 return static_cast<clang::ento::BugReport *>(&Sentinel);
322 void destroySentinel(clang::ento::BugReport *) const {}
324 clang::ento::BugReport *provideInitialHead() const {
325 return createSentinel();
327 clang::ento::BugReport *ensureHead(clang::ento::BugReport *) const {
328 return createSentinel();
331 mutable ilist_half_node<clang::ento::BugReport> Sentinel;
338 //===----------------------------------------------------------------------===//
339 // BugTypes (collections of related reports).
340 //===----------------------------------------------------------------------===//
342 class BugReportEquivClass : public llvm::FoldingSetNode {
343 /// List of *owned* BugReport objects.
344 llvm::ilist<BugReport> Reports;
346 friend class BugReporter;
347 void AddReport(BugReport* R) { Reports.push_back(R); }
349 BugReportEquivClass(BugReport* R) { Reports.push_back(R); }
350 ~BugReportEquivClass();
352 void Profile(llvm::FoldingSetNodeID& ID) const {
353 assert(!Reports.empty());
354 Reports.front().Profile(ID);
357 typedef llvm::ilist<BugReport>::iterator iterator;
358 typedef llvm::ilist<BugReport>::const_iterator const_iterator;
360 iterator begin() { return Reports.begin(); }
361 iterator end() { return Reports.end(); }
363 const_iterator begin() const { return Reports.begin(); }
364 const_iterator end() const { return Reports.end(); }
367 //===----------------------------------------------------------------------===//
368 // BugReporter and friends.
369 //===----------------------------------------------------------------------===//
371 class BugReporterData {
373 virtual ~BugReporterData();
374 virtual DiagnosticsEngine& getDiagnostic() = 0;
375 virtual ArrayRef<PathDiagnosticConsumer*> getPathDiagnosticConsumers() = 0;
376 virtual ASTContext &getASTContext() = 0;
377 virtual SourceManager& getSourceManager() = 0;
380 /// BugReporter is a utility class for generating PathDiagnostics for analysis.
381 /// It collects the BugReports and BugTypes and knows how to generate
382 /// and flush the corresponding diagnostics.
385 enum Kind { BaseBRKind, GRBugReporterKind };
388 typedef llvm::ImmutableSet<BugType*> BugTypesTy;
389 BugTypesTy::Factory F;
395 /// Generate and flush the diagnostics for the given bug report.
396 void FlushReport(BugReportEquivClass& EQ);
398 /// Generate and flush the diagnostics for the given bug report
399 /// and PathDiagnosticConsumer.
400 void FlushReport(BugReport *exampleReport,
401 PathDiagnosticConsumer &PD,
402 ArrayRef<BugReport*> BugReports);
404 /// The set of bug reports tracked by the BugReporter.
405 llvm::FoldingSet<BugReportEquivClass> EQClasses;
406 /// A vector of BugReports for tracking the allocated pointers and cleanup.
407 std::vector<BugReportEquivClass *> EQClassesVector;
410 BugReporter(BugReporterData& d, Kind k) : BugTypes(F.getEmptySet()), kind(k),
414 BugReporter(BugReporterData& d) : BugTypes(F.getEmptySet()), kind(BaseBRKind),
416 virtual ~BugReporter();
418 /// \brief Generate and flush diagnostics for all bug reports.
421 Kind getKind() const { return kind; }
423 DiagnosticsEngine& getDiagnostic() {
424 return D.getDiagnostic();
427 ArrayRef<PathDiagnosticConsumer*> getPathDiagnosticConsumers() {
428 return D.getPathDiagnosticConsumers();
431 /// \brief Iterator over the set of BugTypes tracked by the BugReporter.
432 typedef BugTypesTy::iterator iterator;
433 iterator begin() { return BugTypes.begin(); }
434 iterator end() { return BugTypes.end(); }
436 /// \brief Iterator over the set of BugReports tracked by the BugReporter.
437 typedef llvm::FoldingSet<BugReportEquivClass>::iterator EQClasses_iterator;
438 EQClasses_iterator EQClasses_begin() { return EQClasses.begin(); }
439 EQClasses_iterator EQClasses_end() { return EQClasses.end(); }
441 ASTContext &getContext() { return D.getASTContext(); }
443 SourceManager& getSourceManager() { return D.getSourceManager(); }
445 virtual bool generatePathDiagnostic(PathDiagnostic& pathDiagnostic,
446 PathDiagnosticConsumer &PC,
447 ArrayRef<BugReport *> &bugReports) {
451 bool RemoveUnneededCalls(PathPieces &pieces, BugReport *R);
453 void Register(BugType *BT);
455 /// \brief Add the given report to the set of reports tracked by BugReporter.
457 /// The reports are usually generated by the checkers. Further, they are
458 /// folded based on the profile value, which is done to coalesce similar
460 void emitReport(BugReport *R);
462 void EmitBasicReport(const Decl *DeclWithIssue,
463 StringRef BugName, StringRef BugCategory,
464 StringRef BugStr, PathDiagnosticLocation Loc,
465 SourceRange* RangeBeg, unsigned NumRanges);
467 void EmitBasicReport(const Decl *DeclWithIssue,
468 StringRef BugName, StringRef BugCategory,
469 StringRef BugStr, PathDiagnosticLocation Loc) {
470 EmitBasicReport(DeclWithIssue, BugName, BugCategory, BugStr, Loc, 0, 0);
473 void EmitBasicReport(const Decl *DeclWithIssue,
474 StringRef BugName, StringRef Category,
475 StringRef BugStr, PathDiagnosticLocation Loc,
477 EmitBasicReport(DeclWithIssue, BugName, Category, BugStr, Loc, &R, 1);
481 llvm::StringMap<BugType *> StrBugTypes;
483 /// \brief Returns a BugType that is associated with the given name and
485 BugType *getBugTypeForName(StringRef name, StringRef category);
488 // FIXME: Get rid of GRBugReporter. It's the wrong abstraction.
489 class GRBugReporter : public BugReporter {
492 GRBugReporter(BugReporterData& d, ExprEngine& eng)
493 : BugReporter(d, GRBugReporterKind), Eng(eng) {}
495 virtual ~GRBugReporter();
497 /// getEngine - Return the analysis engine used to analyze a given
498 /// function or method.
499 ExprEngine &getEngine() { return Eng; }
501 /// getGraph - Get the exploded graph created by the analysis engine
502 /// for the analyzed method or function.
503 ExplodedGraph &getGraph();
505 /// getStateManager - Return the state manager used by the analysis
507 ProgramStateManager &getStateManager();
509 /// Generates a path corresponding to one of the given bug reports.
511 /// Which report is used for path generation is not specified. The
512 /// bug reporter will try to pick the shortest path, but this is not
515 /// \return True if the report was valid and a path was generated,
516 /// false if the reports should be considered invalid.
517 virtual bool generatePathDiagnostic(PathDiagnostic &PD,
518 PathDiagnosticConsumer &PC,
519 ArrayRef<BugReport*> &bugReports);
521 /// classof - Used by isa<>, cast<>, and dyn_cast<>.
522 static bool classof(const BugReporter* R) {
523 return R->getKind() == GRBugReporterKind;
527 class BugReporterContext {
528 virtual void anchor();
531 BugReporterContext(GRBugReporter& br) : BR(br) {}
533 virtual ~BugReporterContext() {}
535 GRBugReporter& getBugReporter() { return BR; }
537 ExplodedGraph &getGraph() { return BR.getGraph(); }
539 ProgramStateManager& getStateManager() {
540 return BR.getStateManager();
543 SValBuilder& getSValBuilder() {
544 return getStateManager().getSValBuilder();
547 ASTContext &getASTContext() {
548 return BR.getContext();
551 SourceManager& getSourceManager() {
552 return BR.getSourceManager();
555 virtual BugReport::NodeResolver& getNodeResolver() = 0;
558 } // end GR namespace
560 } // end clang namespace