EIC code displayed by LXR master/​include/​clang/​Basic/​Sarif.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2026-05-10 08:36:50

 //== clang/Basic/Sarif.h - SARIF Diagnostics Object Model -------*- C++ -*--==//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 /// \file
 /// Defines clang::SarifDocumentWriter, clang::SarifRule, clang::SarifResult.
 ///
 /// The document built can be accessed as a JSON Object.
 /// Several value semantic types are also introduced which represent properties
 /// of the SARIF standard, such as 'artifact', 'result', 'rule'.
 ///
 /// A SARIF (Static Analysis Results Interchange Format) document is JSON
 /// document that describes in detail the results of running static analysis
 /// tools on a project. Each (non-trivial) document consists of at least one
 /// "run", which are themselves composed of details such as:
 /// * Tool: The tool that was run
 /// * Rules: The rules applied during the tool run, represented by
 ///   \c reportingDescriptor objects in SARIF
 /// * Results: The matches for the rules applied against the project(s) being
 ///   evaluated, represented by \c result objects in SARIF
 ///
 /// Reference:
 /// 1. <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html">The SARIF standard</a>
 /// 2. <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317836">SARIF<pre>reportingDescriptor</pre></a>
 /// 3. <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317638">SARIF<pre>result</pre></a>
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_BASIC_SARIF_H
 #define LLVM_CLANG_BASIC_SARIF_H
 
 #include "clang/Basic/SourceLocation.h"
 #include "clang/Basic/Version.h"
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/SmallVector.h"
 #include "llvm/ADT/StringMap.h"
 #include "llvm/ADT/StringRef.h"
 #include "llvm/Support/JSON.h"
 #include <cassert>
 #include <cstddef>
 #include <cstdint>
 #include <initializer_list>
 #include <optional>
 #include <string>
 
 namespace clang {
 
 class SarifDocumentWriter;
 class SourceManager;
 
 namespace detail {
 
 /// \internal
 /// An artifact location is SARIF's way of describing the complete location
 /// of an artifact encountered during analysis. The \c artifactLocation object
 /// typically consists of a URI, and/or an index to reference the artifact it
 /// locates.
 ///
 /// This builder makes an additional assumption: that every artifact encountered
 /// by \c clang will be a physical, top-level artifact. Which is why the static
 /// creation method \ref SarifArtifactLocation::create takes a mandatory URI
 /// parameter. The official standard states that either a \c URI or \c Index
 /// must be available in the object, \c clang picks the \c URI as a reasonable
 /// default, because it intends to deal in physical artifacts for now.
 ///
 /// Reference:
 /// 1. <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317427">artifactLocation object</a>
 /// 2. \ref SarifArtifact
 class SarifArtifactLocation {
 private:
   friend class clang::SarifDocumentWriter;
 
   std::optional<uint32_t> Index;
   std::string URI;
 
   SarifArtifactLocation() = delete;
   explicit SarifArtifactLocation(const std::string &URI) : URI(URI) {}
 
 public:
   static SarifArtifactLocation create(llvm::StringRef URI) {
     return SarifArtifactLocation{URI.str()};
   }
 
   SarifArtifactLocation setIndex(uint32_t Idx) {
     Index = Idx;
     return *this;
   }
 };
 
 /// \internal
 /// An artifact in SARIF is any object (a sequence of bytes) addressable by
 /// a URI (RFC 3986). The most common type of artifact for clang's use-case
 /// would be source files. SARIF's artifact object is described in detail in
 /// section 3.24.
 //
 /// Since every clang artifact MUST have a location (there being no nested
 /// artifacts), the creation method \ref SarifArtifact::create requires a
 /// \ref SarifArtifactLocation object.
 ///
 /// Reference:
 /// 1. <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317611">artifact object</a>
 class SarifArtifact {
 private:
   friend class clang::SarifDocumentWriter;
 
   std::optional<uint32_t> Offset;
   std::optional<size_t> Length;
   std::string MimeType;
   SarifArtifactLocation Location;
   llvm::SmallVector<std::string, 4> Roles;
 
   SarifArtifact() = delete;
 
   explicit SarifArtifact(const SarifArtifactLocation &Loc) : Location(Loc) {}
 
 public:
   static SarifArtifact create(const SarifArtifactLocation &Loc) {
     return SarifArtifact{Loc};
   }
 
   SarifArtifact setOffset(uint32_t ArtifactOffset) {
     Offset = ArtifactOffset;
     return *this;
   }
 
   SarifArtifact setLength(size_t NumBytes) {
     Length = NumBytes;
     return *this;
   }
 
   SarifArtifact setRoles(std::initializer_list<llvm::StringRef> ArtifactRoles) {
     Roles.assign(ArtifactRoles.begin(), ArtifactRoles.end());
     return *this;
   }
 
   SarifArtifact setMimeType(llvm::StringRef ArtifactMimeType) {
     MimeType = ArtifactMimeType.str();
     return *this;
   }
 };
 
 } // namespace detail
 
 enum class ThreadFlowImportance { Important, Essential, Unimportant };
 
 /// The level of severity associated with a \ref SarifResult.
 ///
 /// Of all the levels, \c None is the only one that is not associated with
 /// a failure.
 ///
 /// A typical mapping for clang's DiagnosticKind to SarifResultLevel would look
 /// like:
 /// * \c None: \ref clang::DiagnosticsEngine::Level::Remark, \ref clang::DiagnosticsEngine::Level::Ignored
 /// * \c Note: \ref clang::DiagnosticsEngine::Level::Note
 /// * \c Warning: \ref clang::DiagnosticsEngine::Level::Warning
 /// * \c Error could be generated from one of:
 ///   - \ref clang::DiagnosticsEngine::Level::Warning with \c -Werror
 ///   - \ref clang::DiagnosticsEngine::Level::Error
 ///   - \ref clang::DiagnosticsEngine::Level::Fatal when \ref clang::DiagnosticsEngine::ErrorsAsFatal is set.
 ///
 /// Reference:
 /// 1. <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317648">level property</a>
 enum class SarifResultLevel { None, Note, Warning, Error };
 
 /// A thread flow is a sequence of code locations that specify a possible path
 /// through a single thread of execution.
 /// A thread flow in SARIF is related to a code flow which describes
 /// the progress of one or more programs through one or more thread flows.
 ///
 /// Reference:
 /// 1. <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317744">threadFlow object</a>
 /// 2. <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317740">codeFlow object</a>
 class ThreadFlow {
   friend class SarifDocumentWriter;
 
   CharSourceRange Range;
   ThreadFlowImportance Importance;
   std::string Message;
 
   ThreadFlow() = default;
 
 public:
   static ThreadFlow create() { return {}; }
 
   ThreadFlow setRange(const CharSourceRange &ItemRange) {
     assert(ItemRange.isCharRange() &&
            "ThreadFlows require a character granular source range!");
     Range = ItemRange;
     return *this;
   }
 
   ThreadFlow setImportance(const ThreadFlowImportance &ItemImportance) {
     Importance = ItemImportance;
     return *this;
   }
 
   ThreadFlow setMessage(llvm::StringRef ItemMessage) {
     Message = ItemMessage.str();
     return *this;
   }
 };
 
 /// A SARIF Reporting Configuration (\c reportingConfiguration) object contains
 /// properties for a \ref SarifRule that can be configured at runtime before
 /// analysis begins.
 ///
 /// Reference:
 /// 1. <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317852">reportingConfiguration object</a>
 class SarifReportingConfiguration {
   friend class clang::SarifDocumentWriter;
 
   bool Enabled = true;
   SarifResultLevel Level = SarifResultLevel::Warning;
   float Rank = -1.0f;
 
   SarifReportingConfiguration() = default;
 
 public:
   static SarifReportingConfiguration create() { return {}; };
 
   SarifReportingConfiguration disable() {
     Enabled = false;
     return *this;
   }
 
   SarifReportingConfiguration enable() {
     Enabled = true;
     return *this;
   }
 
   SarifReportingConfiguration setLevel(SarifResultLevel TheLevel) {
     Level = TheLevel;
     return *this;
   }
 
   SarifReportingConfiguration setRank(float TheRank) {
     assert(TheRank >= 0.0f && "Rule rank cannot be smaller than 0.0");
     assert(TheRank <= 100.0f && "Rule rank cannot be larger than 100.0");
     Rank = TheRank;
     return *this;
   }
 };
 
 /// A SARIF rule (\c reportingDescriptor object) contains information that
 /// describes a reporting item generated by a tool. A reporting item is
 /// either a result of analysis or notification of a condition encountered by
 /// the tool. Rules are arbitrary but are identifiable by a hierarchical
 /// rule-id.
 ///
 /// This builder provides an interface to create SARIF \c reportingDescriptor
 /// objects via the \ref SarifRule::create static method.
 ///
 /// Reference:
 /// 1. <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317836">reportingDescriptor object</a>
 class SarifRule {
   friend class clang::SarifDocumentWriter;
 
   std::string Name;
   std::string Id;
   std::string Description;
   std::string HelpURI;
   SarifReportingConfiguration DefaultConfiguration;
 
   SarifRule() : DefaultConfiguration(SarifReportingConfiguration::create()) {}
 
 public:
   static SarifRule create() { return {}; }
 
   SarifRule setName(llvm::StringRef RuleName) {
     Name = RuleName.str();
     return *this;
   }
 
   SarifRule setRuleId(llvm::StringRef RuleId) {
     Id = RuleId.str();
     return *this;
   }
 
   SarifRule setDescription(llvm::StringRef RuleDesc) {
     Description = RuleDesc.str();
     return *this;
   }
 
   SarifRule setHelpURI(llvm::StringRef RuleHelpURI) {
     HelpURI = RuleHelpURI.str();
     return *this;
   }
 
   SarifRule
   setDefaultConfiguration(const SarifReportingConfiguration &Configuration) {
     DefaultConfiguration = Configuration;
     return *this;
   }
 };
 
 /// A SARIF result (also called a "reporting item") is a unit of output
 /// produced when one of the tool's \c reportingDescriptor encounters a match
 /// on the file being analysed by the tool.
 ///
 /// This builder provides a \ref SarifResult::create static method that can be
 /// used to create an empty shell onto which attributes can be added using the
 /// \c setX(...) methods.
 ///
 /// For example:
 /// \code{.cpp}
 /// SarifResult result = SarifResult::create(...)
 ///                         .setRuleId(...)
 ///                         .setDiagnosticMessage(...);
 /// \endcode
 ///
 /// Reference:
 /// 1. <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317638">SARIF<pre>result</pre></a>
 class SarifResult {
   friend class clang::SarifDocumentWriter;
 
   // NOTE:
   // This type cannot fit all possible indexes representable by JSON, but is
   // chosen because it is the largest unsigned type that can be safely
   // converted to an \c int64_t.
   uint32_t RuleIdx;
   std::string RuleId;
   std::string DiagnosticMessage;
   llvm::SmallVector<CharSourceRange, 8> Locations;
   llvm::SmallVector<ThreadFlow, 8> ThreadFlows;
   std::optional<SarifResultLevel> LevelOverride;
 
   SarifResult() = delete;
   explicit SarifResult(uint32_t RuleIdx) : RuleIdx(RuleIdx) {}
 
 public:
   static SarifResult create(uint32_t RuleIdx) { return SarifResult{RuleIdx}; }
 
   SarifResult setIndex(uint32_t Idx) {
     RuleIdx = Idx;
     return *this;
   }
 
   SarifResult setRuleId(llvm::StringRef Id) {
     RuleId = Id.str();
     return *this;
   }
 
   SarifResult setDiagnosticMessage(llvm::StringRef Message) {
     DiagnosticMessage = Message.str();
     return *this;
   }
 
   SarifResult setLocations(llvm::ArrayRef<CharSourceRange> DiagLocs) {
 #ifndef NDEBUG
     for (const auto &Loc : DiagLocs) {
       assert(Loc.isCharRange() &&
              "SARIF Results require character granular source ranges!");
     }
 #endif
     Locations.assign(DiagLocs.begin(), DiagLocs.end());
     return *this;
   }
   SarifResult setThreadFlows(llvm::ArrayRef<ThreadFlow> ThreadFlowResults) {
     ThreadFlows.assign(ThreadFlowResults.begin(), ThreadFlowResults.end());
     return *this;
   }
 
   SarifResult setDiagnosticLevel(const SarifResultLevel &TheLevel) {
     LevelOverride = TheLevel;
     return *this;
   }
 };
 
 /// This class handles creating a valid SARIF document given various input
 /// attributes. However, it requires an ordering among certain method calls:
 ///
 /// 1. Because every SARIF document must contain at least 1 \c run, callers
 ///    must ensure that \ref SarifDocumentWriter::createRun is called before
 ///    any other methods.
 /// 2. If SarifDocumentWriter::endRun is called, callers MUST call
 ///    SarifDocumentWriter::createRun, before invoking any of the result
 ///    aggregation methods such as SarifDocumentWriter::appendResult etc.
 class SarifDocumentWriter {
 private:
   const llvm::StringRef SchemaURI{
       "https://docs.oasis-open.org/sarif/sarif/v2.1.0/cos02/schemas/"
       "sarif-schema-2.1.0.json"};
   const llvm::StringRef SchemaVersion{"2.1.0"};
 
   /// \internal
   /// Return a pointer to the current tool. Asserts that a run exists.
   llvm::json::Object &getCurrentTool();
 
   /// \internal
   /// Checks if there is a run associated with this document.
   ///
   /// \return true on success
   bool hasRun() const;
 
   /// \internal
   /// Reset portions of the internal state so that the document is ready to
   /// receive data for a new run.
   void reset();
 
   /// \internal
   /// Return a mutable reference to the current run, after asserting it exists.
   ///
   /// \note It is undefined behavior to call this if a run does not exist in
   /// the SARIF document.
   llvm::json::Object &getCurrentRun();
 
   /// Create a code flow object for the given threadflows.
   /// See \ref ThreadFlow.
   ///
   /// \note It is undefined behavior to call this if a run does not exist in
   /// the SARIF document.
   llvm::json::Object
   createCodeFlow(const llvm::ArrayRef<ThreadFlow> ThreadFlows);
 
   /// Add the given threadflows to the ones this SARIF document knows about.
   llvm::json::Array
   createThreadFlows(const llvm::ArrayRef<ThreadFlow> ThreadFlows);
 
   /// Add the given \ref CharSourceRange to the SARIF document as a physical
   /// location, with its corresponding artifact.
   llvm::json::Object createPhysicalLocation(const CharSourceRange &R);
 
 public:
   SarifDocumentWriter() = delete;
 
   /// Create a new empty SARIF document with the given source manager.
   SarifDocumentWriter(const SourceManager &SourceMgr) : SourceMgr(SourceMgr) {}
 
   /// Release resources held by this SARIF document.
   ~SarifDocumentWriter() = default;
 
   /// Create a new run with which any upcoming analysis will be associated.
   /// Each run requires specifying the tool that is generating reporting items.
   void createRun(const llvm::StringRef ShortToolName,
                  const llvm::StringRef LongToolName,
                  const llvm::StringRef ToolVersion = CLANG_VERSION_STRING);
 
   /// If there is a current run, end it.
   ///
   /// This method collects various book-keeping required to clear and close
   /// resources associated with the current run, but may also allocate some
   /// for the next run.
   ///
   /// Calling \ref endRun before associating a run through \ref createRun leads
   /// to undefined behaviour.
   void endRun();
 
   /// Associate the given rule with the current run.
   ///
   /// Returns an integer rule index for the created rule that is unique within
   /// the current run, which can then be used to create a \ref SarifResult
   /// to add to the current run. Note that a rule must exist before being
   /// referenced by a result.
   ///
   /// \pre
   /// There must be a run associated with the document, failing to do so will
   /// cause undefined behaviour.
   size_t createRule(const SarifRule &Rule);
 
   /// Append a new result to the currently in-flight run.
   ///
   /// \pre
   /// There must be a run associated with the document, failing to do so will
   /// cause undefined behaviour.
   /// \pre
   /// \c RuleIdx used to create the result must correspond to a rule known by
   /// the SARIF document. It must be the value returned by a previous call
   /// to \ref createRule.
   void appendResult(const SarifResult &SarifResult);
 
   /// Return the SARIF document in its current state.
   /// Calling this will trigger a copy of the internal state including all
   /// reported diagnostics, resulting in an expensive call.
   llvm::json::Object createDocument();
 
 private:
   /// Source Manager to use for the current SARIF document.
   const SourceManager &SourceMgr;
 
   /// Flag to track the state of this document:
   /// A closed document is one on which a new runs must be created.
   /// This could be a document that is freshly created, or has recently
   /// finished writing to a previous run.
   bool Closed = true;
 
   /// A sequence of SARIF runs.
   /// Each run object describes a single run of an analysis tool and contains
   /// the output of that run.
   ///
   /// Reference: <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317484">run object</a>
   llvm::json::Array Runs;
 
   /// The list of rules associated with the most recent active run. These are
   /// defined using the diagnostics passed to the SarifDocument. Each rule
   /// need not be unique through the result set. E.g. there may be several
   /// 'syntax' errors throughout code under analysis, each of which has its
   /// own specific diagnostic message (and consequently, RuleId). Rules are
   /// also known as "reportingDescriptor" objects in SARIF.
   ///
   /// Reference: <a href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317556">rules property</a>
   llvm::SmallVector<SarifRule, 32> CurrentRules;
 
   /// The list of artifacts that have been encountered on the most recent active
   /// run. An artifact is defined in SARIF as a sequence of bytes addressable
   /// by a URI. A common example for clang's case would be files named by
   /// filesystem paths.
   llvm::StringMap<detail::SarifArtifact> CurrentArtifacts;
 };
 } // namespace clang
 
 #endif // LLVM_CLANG_BASIC_SARIF_H

This page was automatically generated by the 2.3.7 LXR engine. The LXR team