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/PathSensitive/ProgramState.h"
20 #include "llvm/ADT/FoldingSet.h"
21 #include "llvm/ADT/ImmutableList.h"
22 #include "llvm/ADT/ImmutableSet.h"
23 #include "llvm/ADT/SmallSet.h"
36 class PathDiagnosticPiece;
37 class PathDiagnosticClient;
41 class BugReporterContext;
46 //===----------------------------------------------------------------------===//
47 // Interface for individual bug reports.
48 //===----------------------------------------------------------------------===//
50 class BugReporterVisitor : public llvm::FoldingSetNode {
52 virtual ~BugReporterVisitor();
53 virtual PathDiagnosticPiece *VisitNode(const ExplodedNode *N,
54 const ExplodedNode *PrevN,
55 BugReporterContext &BRC) = 0;
57 virtual bool isOwnedByReporterContext() { return true; }
58 virtual void Profile(llvm::FoldingSetNodeID &ID) const = 0;
61 class BugReport : public BugReporterVisitor {
65 virtual ~NodeResolver() {}
66 virtual const ExplodedNode*
67 getOriginalNode(const ExplodedNode *N) = 0;
70 typedef void (*VisitorCreator)(BugReporterContext &BRcC, const void *data,
71 const ExplodedNode *N);
72 typedef const SourceRange *ranges_iterator;
75 friend class BugReporter;
76 friend class BugReportEquivClass;
77 typedef SmallVector<std::pair<VisitorCreator, const void*>, 2> Creators;
80 std::string ShortDescription;
81 std::string Description;
82 FullSourceLoc Location;
83 const ExplodedNode *ErrorNode;
84 SmallVector<SourceRange, 4> Ranges;
87 /// Profile to identify equivalent bug reports for error report coalescing.
88 virtual void Profile(llvm::FoldingSetNodeID& hash) const;
90 const Stmt *getStmt() const;
93 BugReport(BugType& bt, StringRef desc, const ExplodedNode *errornode)
94 : BT(bt), Description(desc), ErrorNode(errornode) {}
96 BugReport(BugType& bt, StringRef shortDesc, StringRef desc,
97 const ExplodedNode *errornode)
98 : BT(bt), ShortDescription(shortDesc), Description(desc),
99 ErrorNode(errornode) {}
101 BugReport(BugType& bt, StringRef desc, FullSourceLoc l)
102 : BT(bt), Description(desc), Location(l), ErrorNode(0) {}
104 virtual ~BugReport();
106 bool isOwnedByReporterContext() { return false; }
108 const BugType& getBugType() const { return BT; }
109 BugType& getBugType() { return BT; }
111 const ExplodedNode *getErrorNode() const { return ErrorNode; }
113 const StringRef getDescription() const { return Description; }
115 const StringRef getShortDescription() const {
116 return ShortDescription.empty() ? Description : ShortDescription;
119 /// \brief This allows for addition of meta data to the diagnostic.
121 /// Currently, only the HTMLDiagnosticClient knows how to display it.
122 virtual std::pair<const char**,const char**> getExtraDescriptiveText() {
123 return std::make_pair((const char**)0,(const char**)0);
126 /// Provide custom definition for the last diagnostic piece on the path.
127 virtual PathDiagnosticPiece *getEndPath(BugReporterContext &BRC,
128 const ExplodedNode *N);
130 /// \brief Return the "definitive" location of the reported bug.
132 /// While a bug can span an entire path, usually there is a specific
133 /// location that can be used to identify where the key issue occurred.
134 /// This location is used by clients rendering diagnostics.
135 virtual SourceLocation getLocation() const;
137 /// \brief Add a range to a bug report.
139 /// Ranges are used to highlight regions of interest in the source code.
140 /// They should be at the same source code line as the BugReport location.
141 void addRange(SourceRange R) {
146 /// \brief Get the SourceRanges associated with the report.
147 virtual std::pair<ranges_iterator, ranges_iterator> getRanges();
149 /// \brief Add custom or predefined bug report visitors to this report.
151 /// The visitors should be used when the default trace is not sufficient.
152 /// For example, they allow constructing a more elaborate trace.
153 /// \sa registerConditionVisitor(), registerTrackNullOrUndefValue(),
154 /// registerFindLastStore(), registerNilReceiverVisitor(), and
155 /// registerVarDeclsLastStore().
156 void addVisitorCreator(VisitorCreator creator, const void *data) {
157 creators.push_back(std::make_pair(creator, data));
160 virtual PathDiagnosticPiece *VisitNode(const ExplodedNode *N,
161 const ExplodedNode *PrevN,
162 BugReporterContext &BR);
164 virtual void registerInitialVisitors(BugReporterContext &BRC,
165 const ExplodedNode *N) {}
168 //===----------------------------------------------------------------------===//
169 // BugTypes (collections of related reports).
170 //===----------------------------------------------------------------------===//
172 class BugReportEquivClass : public llvm::FoldingSetNode {
173 /// List of *owned* BugReport objects.
174 std::list<BugReport*> Reports;
176 friend class BugReporter;
177 void AddReport(BugReport* R) { Reports.push_back(R); }
179 BugReportEquivClass(BugReport* R) { Reports.push_back(R); }
180 ~BugReportEquivClass();
182 void Profile(llvm::FoldingSetNodeID& ID) const {
183 assert(!Reports.empty());
184 (*Reports.begin())->Profile(ID);
188 std::list<BugReport*>::iterator impl;
190 iterator(std::list<BugReport*>::iterator i) : impl(i) {}
191 iterator &operator++() { ++impl; return *this; }
192 bool operator==(const iterator &I) const { return I.impl == impl; }
193 bool operator!=(const iterator &I) const { return I.impl != impl; }
194 BugReport* operator*() const { return *impl; }
195 BugReport* operator->() const { return *impl; }
198 class const_iterator {
199 std::list<BugReport*>::const_iterator impl;
201 const_iterator(std::list<BugReport*>::const_iterator i) : impl(i) {}
202 const_iterator &operator++() { ++impl; return *this; }
203 bool operator==(const const_iterator &I) const { return I.impl == impl; }
204 bool operator!=(const const_iterator &I) const { return I.impl != impl; }
205 const BugReport* operator*() const { return *impl; }
206 const BugReport* operator->() const { return *impl; }
209 iterator begin() { return iterator(Reports.begin()); }
210 iterator end() { return iterator(Reports.end()); }
212 const_iterator begin() const { return const_iterator(Reports.begin()); }
213 const_iterator end() const { return const_iterator(Reports.end()); }
216 //===----------------------------------------------------------------------===//
217 // BugReporter and friends.
218 //===----------------------------------------------------------------------===//
220 class BugReporterData {
222 virtual ~BugReporterData();
223 virtual Diagnostic& getDiagnostic() = 0;
224 virtual PathDiagnosticClient* getPathDiagnosticClient() = 0;
225 virtual ASTContext &getASTContext() = 0;
226 virtual SourceManager& getSourceManager() = 0;
229 /// BugReporter is a utility class for generating PathDiagnostics for analysis.
230 /// It collects the BugReports and BugTypes and knows how to generate
231 /// and flush the corresponding diagnostics.
234 enum Kind { BaseBRKind, GRBugReporterKind };
237 typedef llvm::ImmutableSet<BugType*> BugTypesTy;
238 BugTypesTy::Factory F;
244 /// Generate and flush the diagnostics for the given bug report.
245 void FlushReport(BugReportEquivClass& EQ);
247 /// The set of bug reports tracked by the BugReporter.
248 llvm::FoldingSet<BugReportEquivClass> EQClasses;
251 BugReporter(BugReporterData& d, Kind k) : BugTypes(F.getEmptySet()), kind(k),
255 BugReporter(BugReporterData& d) : BugTypes(F.getEmptySet()), kind(BaseBRKind),
257 virtual ~BugReporter();
259 /// \brief Generate and flush diagnostics for all bug reports.
262 Kind getKind() const { return kind; }
264 Diagnostic& getDiagnostic() {
265 return D.getDiagnostic();
268 PathDiagnosticClient* getPathDiagnosticClient() {
269 return D.getPathDiagnosticClient();
272 /// \brief Iterator over the set of BugTypes tracked by the BugReporter.
273 typedef BugTypesTy::iterator iterator;
274 iterator begin() { return BugTypes.begin(); }
275 iterator end() { return BugTypes.end(); }
277 /// \brief Iterator over the set of BugReports tracked by the BugReporter.
278 typedef llvm::FoldingSet<BugReportEquivClass>::iterator EQClasses_iterator;
279 EQClasses_iterator EQClasses_begin() { return EQClasses.begin(); }
280 EQClasses_iterator EQClasses_end() { return EQClasses.end(); }
282 ASTContext &getContext() { return D.getASTContext(); }
284 SourceManager& getSourceManager() { return D.getSourceManager(); }
286 virtual void GeneratePathDiagnostic(PathDiagnostic& pathDiagnostic,
287 SmallVectorImpl<BugReport *> &bugReports) {}
289 void Register(BugType *BT);
291 /// \brief Add the given report to the set of reports tracked by BugReporter.
293 /// The reports are usually generated by the checkers. Further, they are
294 /// folded based on the profile value, which is done to coalesce similar
296 void EmitReport(BugReport *R);
298 void EmitBasicReport(StringRef BugName, StringRef BugStr,
300 SourceRange* RangeBeg, unsigned NumRanges);
302 void EmitBasicReport(StringRef BugName, StringRef BugCategory,
303 StringRef BugStr, SourceLocation Loc,
304 SourceRange* RangeBeg, unsigned NumRanges);
307 void EmitBasicReport(StringRef BugName, StringRef BugStr,
308 SourceLocation Loc) {
309 EmitBasicReport(BugName, BugStr, Loc, 0, 0);
312 void EmitBasicReport(StringRef BugName, StringRef BugCategory,
313 StringRef BugStr, SourceLocation Loc) {
314 EmitBasicReport(BugName, BugCategory, BugStr, Loc, 0, 0);
317 void EmitBasicReport(StringRef BugName, StringRef BugStr,
318 SourceLocation Loc, SourceRange R) {
319 EmitBasicReport(BugName, BugStr, Loc, &R, 1);
322 void EmitBasicReport(StringRef BugName, StringRef Category,
323 StringRef BugStr, SourceLocation Loc,
325 EmitBasicReport(BugName, Category, BugStr, Loc, &R, 1);
328 static bool classof(const BugReporter* R) { return true; }
331 llvm::StringMap<BugType *> StrBugTypes;
333 /// \brief Returns a BugType that is associated with the given name and
335 BugType *getBugTypeForName(StringRef name, StringRef category);
338 // FIXME: Get rid of GRBugReporter. It's the wrong abstraction.
339 class GRBugReporter : public BugReporter {
341 llvm::SmallSet<SymbolRef, 10> NotableSymbols;
343 GRBugReporter(BugReporterData& d, ExprEngine& eng)
344 : BugReporter(d, GRBugReporterKind), Eng(eng) {}
346 virtual ~GRBugReporter();
348 /// getEngine - Return the analysis engine used to analyze a given
349 /// function or method.
350 ExprEngine &getEngine() { return Eng; }
352 /// getGraph - Get the exploded graph created by the analysis engine
353 /// for the analyzed method or function.
354 ExplodedGraph &getGraph();
356 /// getStateManager - Return the state manager used by the analysis
358 ProgramStateManager &getStateManager();
360 virtual void GeneratePathDiagnostic(PathDiagnostic &pathDiagnostic,
361 SmallVectorImpl<BugReport*> &bugReports);
363 void addNotableSymbol(SymbolRef Sym) {
364 NotableSymbols.insert(Sym);
367 bool isNotable(SymbolRef Sym) const {
368 return (bool) NotableSymbols.count(Sym);
371 /// classof - Used by isa<>, cast<>, and dyn_cast<>.
372 static bool classof(const BugReporter* R) {
373 return R->getKind() == GRBugReporterKind;
377 class BugReporterContext {
379 // Not the most efficient data structure, but we use an ImmutableList for the
380 // Callbacks because it is safe to make additions to list during iteration.
381 llvm::ImmutableList<BugReporterVisitor*>::Factory F;
382 llvm::ImmutableList<BugReporterVisitor*> Callbacks;
383 llvm::FoldingSet<BugReporterVisitor> CallbacksSet;
385 BugReporterContext(GRBugReporter& br) : BR(br), Callbacks(F.getEmptyList()) {}
386 virtual ~BugReporterContext();
388 void addVisitor(BugReporterVisitor* visitor);
390 typedef llvm::ImmutableList<BugReporterVisitor*>::iterator visitor_iterator;
391 visitor_iterator visitor_begin() { return Callbacks.begin(); }
392 visitor_iterator visitor_end() { return Callbacks.end(); }
394 GRBugReporter& getBugReporter() { return BR; }
396 ExplodedGraph &getGraph() { return BR.getGraph(); }
398 void addNotableSymbol(SymbolRef Sym) {
399 // FIXME: For now forward to GRBugReporter.
400 BR.addNotableSymbol(Sym);
403 bool isNotable(SymbolRef Sym) const {
404 // FIXME: For now forward to GRBugReporter.
405 return BR.isNotable(Sym);
408 ProgramStateManager& getStateManager() {
409 return BR.getStateManager();
412 SValBuilder& getSValBuilder() {
413 return getStateManager().getSValBuilder();
416 ASTContext &getASTContext() {
417 return BR.getContext();
420 SourceManager& getSourceManager() {
421 return BR.getSourceManager();
424 virtual BugReport::NodeResolver& getNodeResolver() = 0;
427 //===----------------------------------------------------------------------===//
428 //===----------------------------------------------------------------------===//
430 namespace bugreporter {
432 const Stmt *GetDerefExpr(const ExplodedNode *N);
433 const Stmt *GetDenomExpr(const ExplodedNode *N);
434 const Stmt *GetCalleeExpr(const ExplodedNode *N);
435 const Stmt *GetRetValExpr(const ExplodedNode *N);
437 void registerConditionVisitor(BugReporterContext &BRC);
439 void registerTrackNullOrUndefValue(BugReporterContext &BRC, const void *stmt,
440 const ExplodedNode *N);
442 void registerFindLastStore(BugReporterContext &BRC, const void *memregion,
443 const ExplodedNode *N);
445 void registerNilReceiverVisitor(BugReporterContext &BRC);
447 void registerVarDeclsLastStore(BugReporterContext &BRC, const void *stmt,
448 const ExplodedNode *N);
450 } // end namespace clang::bugreporter
452 //===----------------------------------------------------------------------===//
454 } // end GR namespace
456 } // end clang namespace