BugReporter.h source code [clang_source_code/include/clang/StaticAnalyzer/Core/BugReporter/BugReporter.h]

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
44	namespace clang {
45
46	class AnalyzerOptions;
47	class ASTContext;
48	class Decl;
49	class DiagnosticsEngine;
50	class LocationContext;
51	class SourceManager;
52	class Stmt;
53
54	namespace ento {
55
56	class BugType;
57	class CheckerBase;
58	class ExplodedGraph;
59	class ExplodedNode;
60	class ExprEngine;
61	class MemRegion;
62	class SValBuilder;
63
64	//===----------------------------------------------------------------------===//
65	// Interface for individual bug reports.
66	//===----------------------------------------------------------------------===//
67
68	/// A mapping from diagnostic consumers to the diagnostics they should
69	/// consume.
70	using 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.
75	class BugReport : public llvm::ilist_node<BugReport> {
76	public:
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
93	protected:
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
156	private:
157	// Used internally by BugReporter.
158	Symbols &getInterestingSymbols();
159	Regions &getInterestingRegions();
160
161	void lazyInitializeInterestingSets();
162	void pushInterestingSymbolsAndRegions();
163	void popInterestingSymbolsAndRegions();
164
165	public:
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	(0) . __assert_fail ("(R.isValid() \|\| Ranges.empty()) && \"Invalid range can only be used \" \"to specify that the report does not have a range.\"", "/home/seafit/code_projects/clang_source/clang/include/clang/StaticAnalyzer/Core/BugReporter/BugReporter.h", 329, __PRETTY_FUNCTION__))" file_link="../../../../../../include/assert.h.html#88" macro="true">assert((R.isValid() \|\| Ranges.empty()) && "Invalid range can only be used "
329	(0) . __assert_fail ("(R.isValid() \|\| Ranges.empty()) && \"Invalid range can only be used \" \"to specify that the report does not have a range.\"", "/home/seafit/code_projects/clang_source/clang/include/clang/StaticAnalyzer/Core/BugReporter/BugReporter.h", 329, __PRETTY_FUNCTION__))" file_link="../../../../../../include/assert.h.html#88" macro="true"> "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
362	class 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
372	public:
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
395	class BugReporterData {
396	public:
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
411	class BugReporter {
412	public:
413	enum Kind { BaseBRKind, GRBugReporterKind };
414
415	private:
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
439	protected:
440	BugReporter(BugReporterData& d, Kind k)
441	: BugTypes(F.getEmptySet()), kind(k), D(d) {}
442
443	public:
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
502	private:
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.
512	class GRBugReporter : public BugReporter {
513	ExprEngine& Eng;
514
515	public:
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
545	class NodeMapClosure : public BugReport::NodeResolver {
546	InterExplodedGraphMap &M;
547
548	public:
549	NodeMapClosure(InterExplodedGraphMap &m) : M(m) {}
550
551	const ExplodedNode getOriginalNode(const ExplodedNode N) override {
552	return M.lookup(N);
553	}
554	};
555
556	class BugReporterContext {
557	GRBugReporter &BR;
558	NodeMapClosure NMC;
559
560	virtual void anchor();
561
562	public:
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