lib/Basic/Sarif.cpp - llvm-project/clang - Git at Google

 //===-- clang/Basic/Sarif.cpp - SarifDocumentWriter class definition ------===//
 //
 // 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
 /// This file contains the declaration of the SARIFDocumentWriter class, and
 /// associated builders such as:
 /// - \ref SarifArtifact
 /// - \ref SarifArtifactLocation
 /// - \ref SarifRule
 /// - \ref SarifResult
 //===----------------------------------------------------------------------===//
 #include "clang/Basic/Sarif.h"
 #include "clang/Basic/SourceLocation.h"
 #include "clang/Basic/SourceManager.h"
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/STLExtras.h"
 #include "llvm/ADT/StringExtras.h"
 #include "llvm/ADT/StringRef.h"
 #include "llvm/Support/ConvertUTF.h"
 #include "llvm/Support/JSON.h"
 #include "llvm/Support/Path.h"

 #include <optional>
 #include <string>
 #include <utility>

 using namespace clang;
 using namespace llvm;

 using clang::detail::SarifArtifact;
 using clang::detail::SarifArtifactLocation;

 static StringRef getFileName(FileEntryRef FE) {
   StringRef Filename = FE.getFileEntry().tryGetRealPathName();
   if (Filename.empty())
     Filename = FE.getName();
   return Filename;
 }
 /// \name URI
 /// @{

 /// \internal
 /// \brief
 /// Return the RFC3986 encoding of the input character.
 ///
 /// \param C Character to encode to RFC3986.
 ///
 /// \return The RFC3986 representation of \c C.
 static std::string percentEncodeURICharacter(char C) {
   // RFC 3986 claims alpha, numeric, and this handful of
   // characters are not reserved for the path component and
   // should be written out directly. Otherwise, percent
   // encode the character and write that out instead of the
   // reserved character.
   if (llvm::isAlnum(C) || StringRef("-._~:@!$&'()*+,;=").contains(C))
     return std::string(&C, 1);
   return "%" + llvm::toHex(StringRef(&C, 1));
 }

 /// \internal
 /// \brief Return a URI representing the given file name.
 ///
 /// \param Filename The filename to be represented as URI.
 ///
 /// \return RFC3986 URI representing the input file name.
 static std::string fileNameToURI(StringRef Filename) {
   SmallString<32> Ret = StringRef("file://");

   // Get the root name to see if it has a URI authority.
   StringRef Root = sys::path::root_name(Filename);
   if (Root.starts_with("//")) {
     // There is an authority, so add it to the URI.
     Ret += Root.drop_front(2).str();
   } else if (!Root.empty()) {
     // There is no authority, so end the component and add the root to the URI.
     Ret += Twine("/" + Root).str();
   }

   auto Iter = sys::path::begin(Filename), End = sys::path::end(Filename);
   assert(Iter != End && "Expected there to be a non-root path component.");
   // Add the rest of the path components, encoding any reserved characters;
   // we skip past the first path component, as it was handled it above.
   for (StringRef Component : llvm::make_range(++Iter, End)) {
     // For reasons unknown to me, we may get a backslash with Windows native
     // paths for the initial backslash following the drive component, which
     // we need to ignore as a URI path part.
     if (Component == "\\")
       continue;

     // Add the separator between the previous path part and the one being
     // currently processed.
     Ret += "/";

     // URI encode the part.
     for (char C : Component) {
       Ret += percentEncodeURICharacter(C);
     }
   }

   return std::string(Ret);
 }
 ///  @}

 /// \brief Calculate the column position expressed in the number of UTF-8 code
 /// points from column start to the source location
 ///
 /// \param Loc The source location whose column needs to be calculated.
 /// \param TokenLen Optional hint for when the token is multiple bytes long.
 ///
 /// \return The column number as a UTF-8 aware byte offset from column start to
 /// the effective source location.
 static unsigned int adjustColumnPos(FullSourceLoc Loc,
                                     unsigned int TokenLen = 0) {
   assert(!Loc.isInvalid() && "invalid Loc when adjusting column position");

   std::pair<FileID, unsigned> LocInfo = Loc.getDecomposedExpansionLoc();
   std::optional<MemoryBufferRef> Buf =
       Loc.getManager().getBufferOrNone(LocInfo.first);
   assert(Buf && "got an invalid buffer for the location's file");
   assert(Buf->getBufferSize() >= (LocInfo.second + TokenLen) &&
          "token extends past end of buffer?");

   // Adjust the offset to be the start of the line, since we'll be counting
   // Unicode characters from there until our column offset.
   unsigned int Off = LocInfo.second - (Loc.getExpansionColumnNumber() - 1);
   unsigned int Ret = 1;
   while (Off < (LocInfo.second + TokenLen)) {
     Off += getNumBytesForUTF8(Buf->getBuffer()[Off]);
     Ret++;
   }

   return Ret;
 }

 /// \name SARIF Utilities
 /// @{

 /// \internal
 json::Object createMessage(StringRef Text) {
   return json::Object{{"text", Text.str()}};
 }

 /// \internal
 /// \pre CharSourceRange must be a token range
 static json::Object createTextRegion(const SourceManager &SM,
                                      const CharSourceRange &R) {
   FullSourceLoc BeginCharLoc{R.getBegin(), SM};
   FullSourceLoc EndCharLoc{R.getEnd(), SM};
   json::Object Region{{"startLine", BeginCharLoc.getExpansionLineNumber()},
                       {"startColumn", adjustColumnPos(BeginCharLoc)}};

   if (BeginCharLoc == EndCharLoc) {
     Region["endColumn"] = adjustColumnPos(BeginCharLoc);
   } else {
     Region["endLine"] = EndCharLoc.getExpansionLineNumber();
     Region["endColumn"] = adjustColumnPos(EndCharLoc);
   }
   return Region;
 }

 static json::Object createLocation(json::Object &&PhysicalLocation,
                                    StringRef Message = "") {
   json::Object Ret{{"physicalLocation", std::move(PhysicalLocation)}};
   if (!Message.empty())
     Ret.insert({"message", createMessage(Message)});
   return Ret;
 }

 static StringRef importanceToStr(ThreadFlowImportance I) {
   switch (I) {
   case ThreadFlowImportance::Important:
     return "important";
   case ThreadFlowImportance::Essential:
     return "essential";
   case ThreadFlowImportance::Unimportant:
     return "unimportant";
   }
   llvm_unreachable("Fully covered switch is not so fully covered");
 }

 static StringRef resultLevelToStr(SarifResultLevel R) {
   switch (R) {
   case SarifResultLevel::None:
     return "none";
   case SarifResultLevel::Note:
     return "note";
   case SarifResultLevel::Warning:
     return "warning";
   case SarifResultLevel::Error:
     return "error";
   }
   llvm_unreachable("Potentially un-handled SarifResultLevel. "
                    "Is the switch not fully covered?");
 }

 static json::Object
 createThreadFlowLocation(json::Object &&Location,
                          const ThreadFlowImportance &Importance) {
   return json::Object{{"location", std::move(Location)},
                       {"importance", importanceToStr(Importance)}};
 }
 ///  @}

 json::Object
 SarifDocumentWriter::createPhysicalLocation(const CharSourceRange &R) {
   assert(R.isValid() &&
          "Cannot create a physicalLocation from invalid SourceRange!");
   assert(R.isCharRange() &&
          "Cannot create a physicalLocation from a token range!");
   FullSourceLoc Start{R.getBegin(), SourceMgr};
   OptionalFileEntryRef FE = Start.getExpansionLoc().getFileEntryRef();
   assert(FE && "Diagnostic does not exist within a valid file!");

   const std::string &FileURI = fileNameToURI(getFileName(*FE));
   auto I = CurrentArtifacts.find(FileURI);

   if (I == CurrentArtifacts.end()) {
     uint32_t Idx = static_cast<uint32_t>(CurrentArtifacts.size());
     const SarifArtifactLocation &Location =
         SarifArtifactLocation::create(FileURI).setIndex(Idx);
     const SarifArtifact &Artifact = SarifArtifact::create(Location)
                                         .setRoles({"resultFile"})
                                         .setLength(FE->getSize())
                                         .setMimeType("text/plain");
     auto StatusIter = CurrentArtifacts.insert({FileURI, Artifact});
     // If inserted, ensure the original iterator points to the newly inserted
     // element, so it can be used downstream.
     if (StatusIter.second)
       I = StatusIter.first;
   }
   assert(I != CurrentArtifacts.end() && "Failed to insert new artifact");
   const SarifArtifactLocation &Location = I->second.Location;
   json::Object ArtifactLocationObject{{"uri", Location.URI}};
   if (Location.Index.has_value())
     ArtifactLocationObject["index"] = *Location.Index;
   return json::Object{{{"artifactLocation", std::move(ArtifactLocationObject)},
                        {"region", createTextRegion(SourceMgr, R)}}};
 }

 json::Object &SarifDocumentWriter::getCurrentTool() {
   assert(!Closed && "SARIF Document is closed. "
                     "Need to call createRun() before using getcurrentTool!");

   // Since Closed = false here, expect there to be at least 1 Run, anything
   // else is an invalid state.
   assert(!Runs.empty() && "There are no runs associated with the document!");

   return *Runs.back().getAsObject()->get("tool")->getAsObject();
 }

 void SarifDocumentWriter::reset() {
   CurrentRules.clear();
   CurrentArtifacts.clear();
 }

 void SarifDocumentWriter::endRun() {
   // Exit early if trying to close a closed Document.
   if (Closed) {
     reset();
     return;
   }

   // Since Closed = false here, expect there to be at least 1 Run, anything
   // else is an invalid state.
   assert(!Runs.empty() && "There are no runs associated with the document!");

   // Flush all the rules.
   json::Object &Tool = getCurrentTool();
   json::Array Rules;
   for (const SarifRule &R : CurrentRules) {
     json::Object Config{
         {"enabled", R.DefaultConfiguration.Enabled},
         {"level", resultLevelToStr(R.DefaultConfiguration.Level)},
         {"rank", R.DefaultConfiguration.Rank}};
     json::Object Rule{
         {"name", R.Name},
         {"id", R.Id},
         {"fullDescription", json::Object{{"text", R.Description}}},
         {"defaultConfiguration", std::move(Config)}};
     if (!R.HelpURI.empty())
       Rule["helpUri"] = R.HelpURI;
     Rules.emplace_back(std::move(Rule));
   }
   json::Object &Driver = *Tool.getObject("driver");
   Driver["rules"] = std::move(Rules);

   // Flush all the artifacts.
   json::Object &Run = getCurrentRun();
   json::Array *Artifacts = Run.getArray("artifacts");
   SmallVector<std::pair<StringRef, SarifArtifact>, 0> Vec;
   for (const auto &[K, V] : CurrentArtifacts)
     Vec.emplace_back(K, V);
   llvm::sort(Vec, llvm::less_first());
   for (const auto &[_, A] : Vec) {
     json::Object Loc{{"uri", A.Location.URI}};
     if (A.Location.Index.has_value()) {
       Loc["index"] = static_cast<int64_t>(*A.Location.Index);
     }
     json::Object Artifact;
     Artifact["location"] = std::move(Loc);
     if (A.Length.has_value())
       Artifact["length"] = static_cast<int64_t>(*A.Length);
     if (!A.Roles.empty())
       Artifact["roles"] = json::Array(A.Roles);
     if (!A.MimeType.empty())
       Artifact["mimeType"] = A.MimeType;
     if (A.Offset.has_value())
       Artifact["offset"] = *A.Offset;
     Artifacts->push_back(json::Value(std::move(Artifact)));
   }

   // Clear, reset temporaries before next run.
   reset();

   // Mark the document as closed.
   Closed = true;
 }

 json::Array
 SarifDocumentWriter::createThreadFlows(ArrayRef<ThreadFlow> ThreadFlows) {
   json::Object Ret{{"locations", json::Array{}}};
   json::Array Locs;
   for (const auto &ThreadFlow : ThreadFlows) {
     json::Object PLoc = createPhysicalLocation(ThreadFlow.Range);
     json::Object Loc = createLocation(std::move(PLoc), ThreadFlow.Message);
     Locs.emplace_back(
         createThreadFlowLocation(std::move(Loc), ThreadFlow.Importance));
   }
   Ret["locations"] = std::move(Locs);
   return json::Array{std::move(Ret)};
 }

 json::Object
 SarifDocumentWriter::createCodeFlow(ArrayRef<ThreadFlow> ThreadFlows) {
   return json::Object{{"threadFlows", createThreadFlows(ThreadFlows)}};
 }

 void SarifDocumentWriter::createRun(StringRef ShortToolName,
                                     StringRef LongToolName,
                                     StringRef ToolVersion) {
   // Clear resources associated with a previous run.
   endRun();

   // Signify a new run has begun.
   Closed = false;

   json::Object Tool{
       {"driver",
        json::Object{{"name", ShortToolName},
                     {"fullName", LongToolName},
                     {"language", "en-US"},
                     {"version", ToolVersion},
                     {"informationUri",
                      "https://clang.llvm.org/docs/UsersManual.html"}}}};
   json::Object TheRun{{"tool", std::move(Tool)},
                       {"results", {}},
                       {"artifacts", {}},
                       {"columnKind", "unicodeCodePoints"}};
   Runs.emplace_back(std::move(TheRun));
 }

 json::Object &SarifDocumentWriter::getCurrentRun() {
   assert(!Closed &&
          "SARIF Document is closed. "
          "Can only getCurrentRun() if document is opened via createRun(), "
          "create a run first");

   // Since Closed = false here, expect there to be at least 1 Run, anything
   // else is an invalid state.
   assert(!Runs.empty() && "There are no runs associated with the document!");
   return *Runs.back().getAsObject();
 }

 size_t SarifDocumentWriter::createRule(const SarifRule &Rule) {
   size_t Ret = CurrentRules.size();
   CurrentRules.emplace_back(Rule);
   return Ret;
 }

 void SarifDocumentWriter::appendResult(const SarifResult &Result) {
   size_t RuleIdx = Result.RuleIdx;
   assert(RuleIdx < CurrentRules.size() &&
          "Trying to reference a rule that doesn't exist");
   const SarifRule &Rule = CurrentRules[RuleIdx];
   assert(Rule.DefaultConfiguration.Enabled &&
          "Cannot add a result referencing a disabled Rule");
   json::Object Ret{{"message", createMessage(Result.DiagnosticMessage)},
                    {"ruleIndex", static_cast<int64_t>(RuleIdx)},
                    {"ruleId", Rule.Id}};
   if (!Result.Locations.empty()) {
     json::Array Locs;
     for (auto &Range : Result.Locations) {
       Locs.emplace_back(createLocation(createPhysicalLocation(Range)));
     }
     Ret["locations"] = std::move(Locs);
   }
   if (!Result.ThreadFlows.empty())
     Ret["codeFlows"] = json::Array{createCodeFlow(Result.ThreadFlows)};

   Ret["level"] = resultLevelToStr(
       Result.LevelOverride.value_or(Rule.DefaultConfiguration.Level));

   json::Object &Run = getCurrentRun();
   json::Array *Results = Run.getArray("results");
   Results->emplace_back(std::move(Ret));
 }

 json::Object SarifDocumentWriter::createDocument() {
   // Flush all temporaries to their destinations if needed.
   endRun();

   json::Object Doc{
       {"$schema", SchemaURI},
       {"version", SchemaVersion},
   };
   if (!Runs.empty())
     Doc["runs"] = json::Array(Runs);
   return Doc;
 }
	//===-- clang/Basic/Sarif.cpp - SarifDocumentWriter class definition ------===//
	//
	// 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
	/// This file contains the declaration of the SARIFDocumentWriter class, and
	/// associated builders such as:
	/// - \ref SarifArtifact
	/// - \ref SarifArtifactLocation
	/// - \ref SarifRule
	/// - \ref SarifResult
	//===----------------------------------------------------------------------===//
	#include "clang/Basic/Sarif.h"
	#include "clang/Basic/SourceLocation.h"
	#include "clang/Basic/SourceManager.h"
	#include "llvm/ADT/ArrayRef.h"
	#include "llvm/ADT/STLExtras.h"
	#include "llvm/ADT/StringExtras.h"
	#include "llvm/ADT/StringRef.h"
	#include "llvm/Support/ConvertUTF.h"
	#include "llvm/Support/JSON.h"
	#include "llvm/Support/Path.h"

	#include <optional>
	#include <string>
	#include <utility>

	using namespace clang;
	using namespace llvm;

	using clang::detail::SarifArtifact;
	using clang::detail::SarifArtifactLocation;

	static StringRef getFileName(FileEntryRef FE) {
	StringRef Filename = FE.getFileEntry().tryGetRealPathName();
	if (Filename.empty())
	Filename = FE.getName();
	return Filename;
	}
	/// \name URI
	/// @{

	/// \internal
	/// \brief
	/// Return the RFC3986 encoding of the input character.
	///
	/// \param C Character to encode to RFC3986.
	///
	/// \return The RFC3986 representation of \c C.
	static std::string percentEncodeURICharacter(char C) {
	// RFC 3986 claims alpha, numeric, and this handful of
	// characters are not reserved for the path component and
	// should be written out directly. Otherwise, percent
	// encode the character and write that out instead of the
	// reserved character.
	if (llvm::isAlnum(C) \|\| StringRef("-._~:@!$&'()*+,;=").contains(C))
	return std::string(&C, 1);
	return "%" + llvm::toHex(StringRef(&C, 1));
	}

	/// \internal
	/// \brief Return a URI representing the given file name.
	///
	/// \param Filename The filename to be represented as URI.
	///
	/// \return RFC3986 URI representing the input file name.
	static std::string fileNameToURI(StringRef Filename) {
	SmallString<32> Ret = StringRef("file://");

	// Get the root name to see if it has a URI authority.
	StringRef Root = sys::path::root_name(Filename);
	if (Root.starts_with("//")) {
	// There is an authority, so add it to the URI.
	Ret += Root.drop_front(2).str();
	} else if (!Root.empty()) {
	// There is no authority, so end the component and add the root to the URI.
	Ret += Twine("/" + Root).str();
	}

	auto Iter = sys::path::begin(Filename), End = sys::path::end(Filename);
	assert(Iter != End && "Expected there to be a non-root path component.");
	// Add the rest of the path components, encoding any reserved characters;
	// we skip past the first path component, as it was handled it above.
	for (StringRef Component : llvm::make_range(++Iter, End)) {
	// For reasons unknown to me, we may get a backslash with Windows native
	// paths for the initial backslash following the drive component, which
	// we need to ignore as a URI path part.
	if (Component == "\\")
	continue;

	// Add the separator between the previous path part and the one being
	// currently processed.
	Ret += "/";

	// URI encode the part.
	for (char C : Component) {
	Ret += percentEncodeURICharacter(C);
	}
	}

	return std::string(Ret);
	}
	/// @}

	/// \brief Calculate the column position expressed in the number of UTF-8 code
	/// points from column start to the source location
	///
	/// \param Loc The source location whose column needs to be calculated.
	/// \param TokenLen Optional hint for when the token is multiple bytes long.
	///
	/// \return The column number as a UTF-8 aware byte offset from column start to
	/// the effective source location.
	static unsigned int adjustColumnPos(FullSourceLoc Loc,
	unsigned int TokenLen = 0) {
	assert(!Loc.isInvalid() && "invalid Loc when adjusting column position");

	std::pair<FileID, unsigned> LocInfo = Loc.getDecomposedExpansionLoc();
	std::optional<MemoryBufferRef> Buf =
	Loc.getManager().getBufferOrNone(LocInfo.first);
	assert(Buf && "got an invalid buffer for the location's file");
	assert(Buf->getBufferSize() >= (LocInfo.second + TokenLen) &&
	"token extends past end of buffer?");

	// Adjust the offset to be the start of the line, since we'll be counting
	// Unicode characters from there until our column offset.
	unsigned int Off = LocInfo.second - (Loc.getExpansionColumnNumber() - 1);
	unsigned int Ret = 1;
	while (Off < (LocInfo.second + TokenLen)) {
	Off += getNumBytesForUTF8(Buf->getBuffer()[Off]);
	Ret++;
	}

	return Ret;
	}

	/// \name SARIF Utilities
	/// @{

	/// \internal
	json::Object createMessage(StringRef Text) {
	return json::Object{{"text", Text.str()}};
	}

	/// \internal
	/// \pre CharSourceRange must be a token range
	static json::Object createTextRegion(const SourceManager &SM,
	const CharSourceRange &R) {
	FullSourceLoc BeginCharLoc{R.getBegin(), SM};
	FullSourceLoc EndCharLoc{R.getEnd(), SM};
	json::Object Region{{"startLine", BeginCharLoc.getExpansionLineNumber()},
	{"startColumn", adjustColumnPos(BeginCharLoc)}};

	if (BeginCharLoc == EndCharLoc) {
	Region["endColumn"] = adjustColumnPos(BeginCharLoc);
	} else {
	Region["endLine"] = EndCharLoc.getExpansionLineNumber();
	Region["endColumn"] = adjustColumnPos(EndCharLoc);
	}
	return Region;
	}

	static json::Object createLocation(json::Object &&PhysicalLocation,
	StringRef Message = "") {
	json::Object Ret{{"physicalLocation", std::move(PhysicalLocation)}};
	if (!Message.empty())
	Ret.insert({"message", createMessage(Message)});
	return Ret;
	}

	static StringRef importanceToStr(ThreadFlowImportance I) {
	switch (I) {
	case ThreadFlowImportance::Important:
	return "important";
	case ThreadFlowImportance::Essential:
	return "essential";
	case ThreadFlowImportance::Unimportant:
	return "unimportant";
	}
	llvm_unreachable("Fully covered switch is not so fully covered");
	}

	static StringRef resultLevelToStr(SarifResultLevel R) {
	switch (R) {
	case SarifResultLevel::None:
	return "none";
	case SarifResultLevel::Note:
	return "note";
	case SarifResultLevel::Warning:
	return "warning";
	case SarifResultLevel::Error:
	return "error";
	}
	llvm_unreachable("Potentially un-handled SarifResultLevel. "
	"Is the switch not fully covered?");
	}

	static json::Object
	createThreadFlowLocation(json::Object &&Location,
	const ThreadFlowImportance &Importance) {
	return json::Object{{"location", std::move(Location)},
	{"importance", importanceToStr(Importance)}};
	}
	/// @}

	json::Object
	SarifDocumentWriter::createPhysicalLocation(const CharSourceRange &R) {
	assert(R.isValid() &&
	"Cannot create a physicalLocation from invalid SourceRange!");
	assert(R.isCharRange() &&
	"Cannot create a physicalLocation from a token range!");
	FullSourceLoc Start{R.getBegin(), SourceMgr};
	OptionalFileEntryRef FE = Start.getExpansionLoc().getFileEntryRef();
	assert(FE && "Diagnostic does not exist within a valid file!");

	const std::string &FileURI = fileNameToURI(getFileName(*FE));
	auto I = CurrentArtifacts.find(FileURI);

	if (I == CurrentArtifacts.end()) {
	uint32_t Idx = static_cast<uint32_t>(CurrentArtifacts.size());
	const SarifArtifactLocation &Location =
	SarifArtifactLocation::create(FileURI).setIndex(Idx);
	const SarifArtifact &Artifact = SarifArtifact::create(Location)
	.setRoles({"resultFile"})
	.setLength(FE->getSize())
	.setMimeType("text/plain");
	auto StatusIter = CurrentArtifacts.insert({FileURI, Artifact});
	// If inserted, ensure the original iterator points to the newly inserted
	// element, so it can be used downstream.
	if (StatusIter.second)
	I = StatusIter.first;
	}
	assert(I != CurrentArtifacts.end() && "Failed to insert new artifact");
	const SarifArtifactLocation &Location = I->second.Location;
	json::Object ArtifactLocationObject{{"uri", Location.URI}};
	if (Location.Index.has_value())
	ArtifactLocationObject["index"] = *Location.Index;
	return json::Object{{{"artifactLocation", std::move(ArtifactLocationObject)},
	{"region", createTextRegion(SourceMgr, R)}}};
	}

	json::Object &SarifDocumentWriter::getCurrentTool() {
	assert(!Closed && "SARIF Document is closed. "
	"Need to call createRun() before using getcurrentTool!");

	// Since Closed = false here, expect there to be at least 1 Run, anything
	// else is an invalid state.
	assert(!Runs.empty() && "There are no runs associated with the document!");

	return *Runs.back().getAsObject()->get("tool")->getAsObject();
	}

	void SarifDocumentWriter::reset() {
	CurrentRules.clear();
	CurrentArtifacts.clear();
	}

	void SarifDocumentWriter::endRun() {
	// Exit early if trying to close a closed Document.
	if (Closed) {
	reset();
	return;
	}

	// Since Closed = false here, expect there to be at least 1 Run, anything
	// else is an invalid state.
	assert(!Runs.empty() && "There are no runs associated with the document!");

	// Flush all the rules.
	json::Object &Tool = getCurrentTool();
	json::Array Rules;
	for (const SarifRule &R : CurrentRules) {
	json::Object Config{
	{"enabled", R.DefaultConfiguration.Enabled},
	{"level", resultLevelToStr(R.DefaultConfiguration.Level)},
	{"rank", R.DefaultConfiguration.Rank}};
	json::Object Rule{
	{"name", R.Name},
	{"id", R.Id},
	{"fullDescription", json::Object{{"text", R.Description}}},
	{"defaultConfiguration", std::move(Config)}};
	if (!R.HelpURI.empty())
	Rule["helpUri"] = R.HelpURI;
	Rules.emplace_back(std::move(Rule));
	}
	json::Object &Driver = *Tool.getObject("driver");
	Driver["rules"] = std::move(Rules);

	// Flush all the artifacts.
	json::Object &Run = getCurrentRun();
	json::Array *Artifacts = Run.getArray("artifacts");
	SmallVector<std::pair<StringRef, SarifArtifact>, 0> Vec;
	for (const auto &[K, V] : CurrentArtifacts)
	Vec.emplace_back(K, V);
	llvm::sort(Vec, llvm::less_first());
	for (const auto &[_, A] : Vec) {
	json::Object Loc{{"uri", A.Location.URI}};
	if (A.Location.Index.has_value()) {
	Loc["index"] = static_cast<int64_t>(*A.Location.Index);
	}
	json::Object Artifact;
	Artifact["location"] = std::move(Loc);
	if (A.Length.has_value())
	Artifact["length"] = static_cast<int64_t>(*A.Length);
	if (!A.Roles.empty())
	Artifact["roles"] = json::Array(A.Roles);
	if (!A.MimeType.empty())
	Artifact["mimeType"] = A.MimeType;
	if (A.Offset.has_value())
	Artifact["offset"] = *A.Offset;
	Artifacts->push_back(json::Value(std::move(Artifact)));
	}

	// Clear, reset temporaries before next run.
	reset();

	// Mark the document as closed.
	Closed = true;
	}

	json::Array
	SarifDocumentWriter::createThreadFlows(ArrayRef<ThreadFlow> ThreadFlows) {
	json::Object Ret{{"locations", json::Array{}}};
	json::Array Locs;
	for (const auto &ThreadFlow : ThreadFlows) {
	json::Object PLoc = createPhysicalLocation(ThreadFlow.Range);
	json::Object Loc = createLocation(std::move(PLoc), ThreadFlow.Message);
	Locs.emplace_back(
	createThreadFlowLocation(std::move(Loc), ThreadFlow.Importance));
	}
	Ret["locations"] = std::move(Locs);
	return json::Array{std::move(Ret)};
	}

	json::Object
	SarifDocumentWriter::createCodeFlow(ArrayRef<ThreadFlow> ThreadFlows) {
	return json::Object{{"threadFlows", createThreadFlows(ThreadFlows)}};
	}

	void SarifDocumentWriter::createRun(StringRef ShortToolName,
	StringRef LongToolName,
	StringRef ToolVersion) {
	// Clear resources associated with a previous run.
	endRun();

	// Signify a new run has begun.
	Closed = false;

	json::Object Tool{
	{"driver",
	json::Object{{"name", ShortToolName},
	{"fullName", LongToolName},
	{"language", "en-US"},
	{"version", ToolVersion},
	{"informationUri",
	"https://clang.llvm.org/docs/UsersManual.html"}}}};
	json::Object TheRun{{"tool", std::move(Tool)},
	{"results", {}},
	{"artifacts", {}},
	{"columnKind", "unicodeCodePoints"}};
	Runs.emplace_back(std::move(TheRun));
	}

	json::Object &SarifDocumentWriter::getCurrentRun() {
	assert(!Closed &&
	"SARIF Document is closed. "
	"Can only getCurrentRun() if document is opened via createRun(), "
	"create a run first");

	// Since Closed = false here, expect there to be at least 1 Run, anything
	// else is an invalid state.
	assert(!Runs.empty() && "There are no runs associated with the document!");
	return *Runs.back().getAsObject();
	}

	size_t SarifDocumentWriter::createRule(const SarifRule &Rule) {
	size_t Ret = CurrentRules.size();
	CurrentRules.emplace_back(Rule);
	return Ret;
	}

	void SarifDocumentWriter::appendResult(const SarifResult &Result) {
	size_t RuleIdx = Result.RuleIdx;
	assert(RuleIdx < CurrentRules.size() &&
	"Trying to reference a rule that doesn't exist");
	const SarifRule &Rule = CurrentRules[RuleIdx];
	assert(Rule.DefaultConfiguration.Enabled &&
	"Cannot add a result referencing a disabled Rule");
	json::Object Ret{{"message", createMessage(Result.DiagnosticMessage)},
	{"ruleIndex", static_cast<int64_t>(RuleIdx)},
	{"ruleId", Rule.Id}};
	if (!Result.Locations.empty()) {
	json::Array Locs;
	for (auto &Range : Result.Locations) {
	Locs.emplace_back(createLocation(createPhysicalLocation(Range)));
	}
	Ret["locations"] = std::move(Locs);
	}
	if (!Result.ThreadFlows.empty())
	Ret["codeFlows"] = json::Array{createCodeFlow(Result.ThreadFlows)};

	Ret["level"] = resultLevelToStr(
	Result.LevelOverride.value_or(Rule.DefaultConfiguration.Level));

	json::Object &Run = getCurrentRun();
	json::Array *Results = Run.getArray("results");
	Results->emplace_back(std::move(Ret));
	}

	json::Object SarifDocumentWriter::createDocument() {
	// Flush all temporaries to their destinations if needed.
	endRun();

	json::Object Doc{
	{"$schema", SchemaURI},
	{"version", SchemaVersion},
	};
	if (!Runs.empty())
	Doc["runs"] = json::Array(Runs);
	return Doc;
	}