sarif_rust 0.3.0

//! SARIF result-related types
//!
//! This module defines structures for representing analysis results and findings.

use crate::types::{
    ArtifactLocation, BaselineState, Kind, Level, Location, Message, MultiformatMessage,
    ReportingDescriptorReference,
};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// A result produced by an analysis tool
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Result {
    /// The stable, unique identifier of the rule
    pub rule_id: Option<String>,

    /// The index within the tool component rules array
    pub rule_index: Option<i32>,

    /// A reference used to locate the rule descriptor relevant to this result
    pub rule: Option<ReportingDescriptorReference>,

    /// The kind of result
    pub kind: Option<Kind>,

    /// A value that categorizes results by evaluation state
    pub level: Option<Level>,

    /// A message that describes the result
    pub message: Message,

    /// Identifies the artifact that the analysis tool was instructed to scan
    pub analysis_target: Option<ArtifactLocation>,

    /// The set of locations where the result was detected
    pub locations: Option<Vec<Location>>,

    /// A stable, unique identifier for the result
    pub guid: Option<String>,

    /// A stable, unique identifier for the equivalence class of logically identical results
    pub correlation_guid: Option<String>,

    /// A positive integer specifying the number of times this logically unique result was observed in this run
    pub occurrence_count: Option<i32>,

    /// A set of strings that contribute to the stable, unique identity of the result
    pub partial_fingerprints: Option<HashMap<String, String>>,

    /// A set of strings each of which individually defines a stable, unique identity for the result
    pub fingerprints: Option<HashMap<String, String>>,

    /// An array of 'stack' objects relevant to the result
    pub stacks: Option<Vec<Stack>>,

    /// An array of 'codeFlow' objects relevant to the result
    pub code_flows: Option<Vec<CodeFlow>>,

    /// An array of zero or more unique graph objects associated with the result
    pub graphs: Option<Vec<Graph>>,

    /// An array of one or more unique 'graphTraversal' objects
    pub graph_traversals: Option<Vec<GraphTraversal>>,

    /// A set of locations relevant to this result
    pub related_locations: Option<Vec<Location>>,

    /// A set of suppressions relevant to this result
    pub suppressions: Option<Vec<Suppression>>,

    /// The state of a result relative to a baseline of a previous run
    pub baseline_state: Option<BaselineState>,

    /// A number representing the priority or importance of the result
    pub rank: Option<f64>,

    /// A set of artifacts relevant to the result
    pub attachments: Option<Vec<Attachment>>,

    /// An absolute URI at which the result can be viewed
    pub hosted_viewer_uri: Option<String>,

    /// The URIs of the work items associated with this result
    pub work_item_uris: Option<Vec<String>>,

    /// Information about how and when the result was detected
    pub provenance: Option<ResultProvenance>,

    /// An array of 'fix' objects, each of which represents a proposed fix to the problem indicated by the result
    pub fixes: Option<Vec<Fix>>,

    /// An array of reportingDescriptorReference objects relevant to the taxonomies associated with the result
    pub taxa: Option<Vec<ReportingDescriptorReference>>,

    /// A web request associated with this result
    pub web_request: Option<WebRequest>,

    /// A web response associated with this result
    pub web_response: Option<WebResponse>,

    /// Key/value pairs that provide additional information about the result
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

// ReportingDescriptorReference and ToolComponentReference are defined in tool.rs

/// A call stack that is relevant to a result
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Stack {
    /// A message relevant to this call stack
    pub message: Option<Message>,

    /// An array of stack frames that represents a sequence of calls
    pub frames: Vec<StackFrame>,

    /// Key/value pairs that provide additional information about the stack
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// A function call within a stack trace
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct StackFrame {
    /// The location to which this stack frame refers
    pub location: Option<Location>,

    /// The name of the module that contains the code of this stack frame
    pub module: Option<String>,

    /// The thread identifier of the stack frame
    pub thread_id: Option<i32>,

    /// The parameters of the call that is executing
    pub parameters: Option<Vec<String>>,

    /// Key/value pairs that provide additional information about the stack frame
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// A set of threadFlow objects which together describe a pattern of code execution
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CodeFlow {
    /// A message relevant to the code flow
    pub message: Option<Message>,

    /// An array of one or more unique threadFlow objects
    pub thread_flows: Vec<ThreadFlow>,

    /// Key/value pairs that provide additional information about the code flow
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// A sequence of code locations that specify a path through a single thread of execution
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ThreadFlow {
    /// An string that uniquely identifies the threadFlow within the codeFlow
    pub id: Option<String>,

    /// A message relevant to the thread flow
    pub message: Option<Message>,

    /// Values of relevant expressions at the start of the thread flow
    pub initial_state: Option<HashMap<String, MultiformatMessage>>,

    /// Values of relevant expressions after the last location of the thread flow
    pub immutable_state: Option<HashMap<String, MultiformatMessage>>,

    /// A temporally ordered array of 'threadFlowLocation' objects
    pub locations: Vec<ThreadFlowLocation>,

    /// Key/value pairs that provide additional information about the thread flow
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// A location visited by an analysis tool while simulating or monitoring the execution of a program
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ThreadFlowLocation {
    /// The index within the run threadFlowLocations array
    pub index: Option<i32>,

    /// The code location
    pub location: Option<Location>,

    /// The call stack leading to this location
    pub stack: Option<Stack>,

    /// A set of distinct strings that categorize the thread flow location
    pub kinds: Option<Vec<String>>,

    /// An array of references to rule or taxonomy reporting descriptors
    pub taxa: Option<Vec<ReportingDescriptorReference>>,

    /// The name of the module that contains the code that is executing
    pub module: Option<String>,

    /// A dictionary, each of whose keys specifies a variable or expression
    pub state: Option<HashMap<String, MultiformatMessage>>,

    /// An integer representing the temporal order in which execution reached this location
    pub execution_order: Option<i32>,

    /// The Coordinated Universal Time (UTC) date and time at which this location was executed
    pub execution_time_utc: Option<String>,

    /// Specifies the importance of this location in understanding the code flow
    pub importance: Option<ThreadFlowLocationImportance>,

    /// A web request associated with this thread flow location
    pub web_request: Option<WebRequest>,

    /// A web response associated with this thread flow location
    pub web_response: Option<WebResponse>,

    /// Key/value pairs that provide additional information about the thread flow location
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

// MultiformatMessage is defined in message.rs

/// Specifies the importance of this location in understanding the code flow
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum ThreadFlowLocationImportance {
    /// The location is important
    Important,
    /// The location is essential
    Essential,
    /// The location is unimportant
    Unimportant,
}

/// A network request/response pair associated with this result
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct WebRequest {
    /// The index within the run webRequests array
    pub index: Option<i32>,

    /// The request protocol
    pub protocol: Option<String>,

    /// The request version
    pub version: Option<String>,

    /// The target of the request
    pub target: Option<String>,

    /// The HTTP method
    pub method: Option<String>,

    /// The request headers
    pub headers: Option<HashMap<String, String>>,

    /// The request parameters
    pub parameters: Option<HashMap<String, String>>,

    /// The body of the request
    pub body: Option<ResultArtifactContent>,

    /// Key/value pairs that provide additional information about the web request
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// A web response associated with this result
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct WebResponse {
    /// The index within the run webResponses array
    pub index: Option<i32>,

    /// The response protocol
    pub protocol: Option<String>,

    /// The response version
    pub version: Option<String>,

    /// The response status code
    pub status_code: Option<i32>,

    /// The response reason phrase
    pub reason_phrase: Option<String>,

    /// The response headers
    pub headers: Option<HashMap<String, String>>,

    /// The body of the response
    pub body: Option<ResultArtifactContent>,

    /// Specifies whether a response was received from the server
    pub no_response_received: Option<bool>,

    /// Key/value pairs that provide additional information about the web response
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// Represents the contents of an artifact in result context
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ResultArtifactContent {
    /// UTF-8-encoded content from a text artifact
    pub text: Option<String>,

    /// MIME Base64-encoded content from a binary artifact
    pub binary: Option<String>,

    /// Key/value pairs that provide additional information
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// A graph object represents a network of nodes and edges
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Graph {
    /// A description of the graph
    pub description: Option<Message>,

    /// An array of node objects representing the nodes of the graph
    pub nodes: Option<Vec<Node>>,

    /// An array of edge objects representing the edges of the graph
    pub edges: Option<Vec<Edge>>,

    /// Key/value pairs that provide additional information about the graph
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// Represents a node in a graph
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Node {
    /// A string that uniquely identifies the node within its graph
    pub id: String,

    /// A short description of the node
    pub label: Option<Message>,

    /// A code location associated with the node
    pub location: Option<Location>,

    /// Array of child node ids
    pub children: Option<Vec<NodeReference>>,

    /// Key/value pairs that provide additional information about the node
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// Represents a directed edge in a graph
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Edge {
    /// A string that uniquely identifies the edge within its graph
    pub id: String,

    /// A short description of the edge
    pub label: Option<Message>,

    /// Identifies the source node (the node at which the edge starts)
    pub source_node_id: String,

    /// Identifies the target node (the node at which the edge ends)
    pub target_node_id: String,

    /// Key/value pairs that provide additional information about the edge
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// Information about a graph traversal
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct GraphTraversal {
    /// The index within the run.graphs to be associated with this traversal
    pub run_graph_index: Option<i32>,

    /// The index within the result.graphs to be associated with this traversal
    pub result_graph_index: Option<i32>,

    /// A description of this graph traversal
    pub description: Option<Message>,

    /// Values of relevant expressions at the start of the graph traversal
    pub initial_state: Option<HashMap<String, MultiformatMessage>>,

    /// Values of relevant expressions at the end of the graph traversal
    pub immutable_state: Option<HashMap<String, MultiformatMessage>>,

    /// The sequences of edges traversed by this graph traversal
    pub edge_traversals: Option<Vec<EdgeTraversal>>,

    /// Key/value pairs that provide additional information about the graph traversal
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// Represents the traversal of a single edge during a graph traversal
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct EdgeTraversal {
    /// Identifies the edge being traversed
    pub edge_id: String,

    /// A message to display to the user as the edge is traversed
    pub message: Option<Message>,

    /// The values of relevant expressions after the edge has been traversed
    pub final_state: Option<HashMap<String, MultiformatMessage>>,

    /// The number of edge traversals necessary to return from a nested graph
    pub step_over_edge_count: Option<i32>,

    /// Key/value pairs that provide additional information about the edge traversal
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// A node reference within a graph
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct NodeReference {
    /// The id of the node
    pub id: String,

    /// Key/value pairs that provide additional information about the node reference
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// A suppression that is relevant to a result
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Suppression {
    /// A string that indicates where the suppression is persisted
    pub kind: String,

    /// A string that indicates the review status of the suppression
    pub status: Option<SuppressionStatus>,

    /// A string representing the justification for the suppression
    pub justification: Option<String>,

    /// Identifies the location associated with the suppression
    pub location: Option<Location>,

    /// A stable, unique identifier for the suppression
    pub guid: Option<String>,

    /// Key/value pairs that provide additional information about the suppression
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// The review status of the suppression
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum SuppressionStatus {
    /// The suppression has been accepted
    Accepted,
    /// The suppression is under review
    UnderReview,
    /// The suppression has been rejected
    Rejected,
}

/// An artifact relevant to a result
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Attachment {
    /// A message describing the role played by the attachment
    pub description: Option<Message>,

    /// The location of the attachment
    pub artifact_location: ArtifactLocation,

    /// An array of regions of interest within the attachment
    pub regions: Option<Vec<crate::types::Region>>,

    /// An array of rectangles specifying areas of interest within the image
    pub rectangles: Option<Vec<Rectangle>>,

    /// Key/value pairs that provide additional information about the attachment
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// An area within an image
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Rectangle {
    /// The Y coordinate of the top edge of the rectangle
    pub top: Option<f64>,

    /// The X coordinate of the left edge of the rectangle
    pub left: Option<f64>,

    /// The Y coordinate of the bottom edge of the rectangle
    pub bottom: Option<f64>,

    /// The X coordinate of the right edge of the rectangle
    pub right: Option<f64>,

    /// A message relevant to the rectangle
    pub message: Option<Message>,

    /// Key/value pairs that provide additional information about the rectangle
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// Information about how and when a result was detected
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ResultProvenance {
    /// The Coordinated Universal Time (UTC) date and time at which the result was first detected
    pub first_detection_time_utc: Option<String>,

    /// The Coordinated Universal Time (UTC) date and time at which the result was most recently detected
    pub last_detection_time_utc: Option<String>,

    /// A GUID-valued string equal to the automationDetails.guid property
    pub first_detection_run_guid: Option<String>,

    /// A GUID-valued string equal to the automationDetails.guid property
    pub last_detection_run_guid: Option<String>,

    /// The index within the run.invocations array
    pub invocation_index: Option<i32>,

    /// An array of physicalLocation objects
    pub conversion_sources: Option<Vec<PhysicalLocation>>,

    /// Key/value pairs that provide additional information about the result provenance
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// A proposed fix for the problem represented by a result object
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Fix {
    /// A message that describes the proposed fix
    pub description: Option<Message>,

    /// One or more artifact changes that comprise a fix for a result
    pub artifact_changes: Vec<ArtifactChange>,

    /// Key/value pairs that provide additional information about the fix
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// A change to a single artifact
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ArtifactChange {
    /// The location of the artifact to change
    pub artifact_location: ArtifactLocation,

    /// An array of replacement objects
    pub replacements: Vec<Replacement>,

    /// Key/value pairs that provide additional information about the artifact change
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// The replacement of a single region of an artifact
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Replacement {
    /// The region of the artifact to delete
    pub deleted_region: crate::types::Region,

    /// The content to insert at the location specified by the 'deletedRegion' property
    pub inserted_content: Option<ResultArtifactContent>,

    /// Key/value pairs that provide additional information about the replacement
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

/// A physical location relevant to a result
pub use crate::types::PhysicalLocation;

impl Result {
    /// Create a new result with a message
    pub fn new(message: impl Into<Message>) -> Self {
        Self {
            rule_id: None,
            rule_index: None,
            rule: None,
            kind: None,
            level: None,
            message: message.into(),
            analysis_target: None,
            locations: None,
            guid: None,
            correlation_guid: None,
            occurrence_count: None,
            partial_fingerprints: None,
            fingerprints: None,
            stacks: None,
            code_flows: None,
            graphs: None,
            graph_traversals: None,
            related_locations: None,
            suppressions: None,
            baseline_state: None,
            rank: None,
            attachments: None,
            hosted_viewer_uri: None,
            work_item_uris: None,
            provenance: None,
            fixes: None,
            taxa: None,
            web_request: None,
            web_response: None,
            properties: None,
        }
    }

    /// Set the rule ID
    pub fn with_rule_id(mut self, rule_id: impl Into<String>) -> Self {
        self.rule_id = Some(rule_id.into());
        self
    }

    /// Set the level
    pub fn with_level(mut self, level: Level) -> Self {
        self.level = Some(level);
        self
    }

    /// Set the kind
    pub fn with_kind(mut self, kind: Kind) -> Self {
        self.kind = Some(kind);
        self
    }

    /// Add a location
    pub fn add_location(mut self, location: Location) -> Self {
        self.locations.get_or_insert_with(Vec::new).push(location);
        self
    }

    /// Set the analysis target
    pub fn with_analysis_target(mut self, target: ArtifactLocation) -> Self {
        self.analysis_target = Some(target);
        self
    }

    /// Add a code flow
    pub fn add_code_flow(mut self, code_flow: CodeFlow) -> Self {
        self.code_flows.get_or_insert_with(Vec::new).push(code_flow);
        self
    }
}

// MultiformatMessage implementations are in message.rs