//== 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