contrib/llvm/tools/clang/include/clang/StaticAnalyzer/Core/BugReporter/BugReporter.h

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