sarif_rust 0.3.0

//! SARIF run-related types
//!
//! This module defines structures for representing analysis tool runs.

use crate::types::{
    Address, Artifact, ArtifactLocation, Graph, LogicalLocation, Result, ThreadFlowLocation, Tool,
    ToolComponent, WebRequest, WebResponse,
};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// Describes a single run of an analysis tool
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Run {
    /// Information about the tool or tool pipeline that generated the results in this run
    pub tool: Tool,

    /// Describes the invocation of the analysis tool
    pub invocations: Option<Vec<crate::types::Invocation>>,

    /// A conversion object that describes how a converter transformed an analysis tool's native reporting format
    pub conversion: Option<crate::types::Conversion>,

    /// The language of the messages emitted into the log file during this run
    pub language: Option<String>,

    /// Specifies the revision in version control of the artifacts that were scanned
    pub version_control_provenance: Option<Vec<VersionControlDetails>>,

    /// The artifact location specified by each uriBaseId symbol on the machine where the tool originally ran
    pub original_uri_base_ids: Option<HashMap<String, ArtifactLocation>>,

    /// An array of artifact objects relevant to the run
    pub artifacts: Option<Vec<Artifact>>,

    /// An array of logical location objects relevant to the run
    pub logical_locations: Option<Vec<LogicalLocation>>,

    /// An array of graph objects relevant to the run
    pub graphs: Option<Vec<Graph>>,

    /// The set of results contained in an SARIF log
    pub results: Option<Vec<Result>>,

    /// Automation details that describe this run
    pub automation_details: Option<RunAutomationDetails>,

    /// Automation details that describe the aggregate of runs to which this run belongs
    pub run_aggregates: Option<Vec<RunAutomationDetails>>,

    /// The 'guid' property of a previous SARIF 'run' that comprises the baseline that was used to compute result 'baselineState' properties
    pub baseline_guid: Option<String>,

    /// An array of strings used to replace sensitive information in a redaction-aware property
    pub redaction_tokens: Option<Vec<String>>,

    /// Specifies the default encoding for any artifact that refers to a text file
    pub default_encoding: Option<String>,

    /// Specifies the default source language for any artifact that refers to a text file that contains source code
    pub default_source_language: Option<String>,

    /// An ordered list of character sequences that were treated as line breaks when computing region information for the run
    pub newline_sequences: Option<Vec<String>>,

    /// Specifies the unit in which the tool measures columns
    pub column_kind: Option<ColumnKind>,

    /// References to external property files that should be inlined with the content of this run object
    pub external_property_file_references: Option<ExternalPropertyFileReferences>,

    /// An array of threadFlowLocation objects cached at run level
    pub thread_flow_locations: Option<Vec<ThreadFlowLocation>>,

    /// An array of toolComponent objects relevant to a taxonomy in which results are categorized
    pub taxonomies: Option<Vec<ToolComponent>>,

    /// Addresses associated with this run instance, if any
    pub addresses: Option<Vec<Address>>,

    /// The set of available translations of the localized data provided by the tool
    pub translations: Option<Vec<ToolComponent>>,

    /// Contains configurations that may potentially override both
    pub policies: Option<Vec<ToolComponent>>,

    /// An array of request objects cached at run level
    pub web_requests: Option<Vec<WebRequest>>,

    /// An array of response objects cached at run level
    pub web_responses: Option<Vec<WebResponse>>,

    /// A specialLocations object that defines locations of special significance to SARIF consumers
    pub special_locations: Option<SpecialLocations>,

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

/// Information that describes a run's identity and role within an engineering system process
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RunAutomationDetails {
    /// A description of the identity and role played within the engineering system by this object's containing run object
    pub description: Option<crate::types::Message>,

    /// A hierarchical string that uniquely identifies this object's containing run object
    pub id: Option<String>,

    /// A stable, unique identifier for this object's containing run object
    pub guid: Option<String>,

    /// A stable, unique identifier for the equivalence class of runs to which this object's containing run object belongs
    pub correlation_guid: Option<String>,

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

/// Contains information that enables a SARIF consumer to locate external property files
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ExternalPropertyFileReferences {
    /// The URI of an external property file containing a run.conversion object to be merged with this run
    pub conversion: Option<ExternalPropertyFileReference>,

    /// An array of external property file references containing a run.graphs array to be merged with this run
    pub graphs: Option<Vec<ExternalPropertyFileReference>>,

    /// References to external property files containing information about external property files
    pub externalized_properties: Option<ExternalPropertyFileReference>,

    /// References to external property files containing a run.artifacts array to be merged with this run
    pub artifacts: Option<Vec<ExternalPropertyFileReference>>,

    /// References to external property files containing a run.invocations array to be merged with this run
    pub invocations: Option<Vec<ExternalPropertyFileReference>>,

    /// References to external property files containing a run.logicalLocations array to be merged with this run
    pub logical_locations: Option<Vec<ExternalPropertyFileReference>>,

    /// References to external property files containing a run.threadFlowLocations array to be merged with this run
    pub thread_flow_locations: Option<Vec<ExternalPropertyFileReference>>,

    /// References to external property files containing a run.results array to be merged with this run
    pub results: Option<Vec<ExternalPropertyFileReference>>,

    /// References to external property files containing a run.taxonomies array to be merged with this run
    pub taxonomies: Option<Vec<ExternalPropertyFileReference>>,

    /// References to external property files containing a run.addresses array to be merged with this run
    pub addresses: Option<Vec<ExternalPropertyFileReference>>,

    /// A reference to an external property file containing a run.driver object to be merged with this run
    pub driver: Option<ExternalPropertyFileReference>,

    /// References to external property files containing a run.extensions array to be merged with this run
    pub extensions: Option<Vec<ExternalPropertyFileReference>>,

    /// References to external property files containing a run.policies array to be merged with this run
    pub policies: Option<Vec<ExternalPropertyFileReference>>,

    /// References to external property files containing a run.translations array to be merged with this run
    pub translations: Option<Vec<ExternalPropertyFileReference>>,

    /// References to external property files containing a run.webRequests array to be merged with this run
    pub web_requests: Option<Vec<ExternalPropertyFileReference>>,

    /// References to external property files containing a run.webResponses array to be merged with this run
    pub web_responses: Option<Vec<ExternalPropertyFileReference>>,

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

/// Contains information that enables a SARIF consumer to locate a single external property file
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ExternalPropertyFileReference {
    /// The location of the external property file
    pub location: crate::types::ArtifactLocation,

    /// A stable, unique identifier for the external property file
    pub guid: Option<String>,

    /// A non-negative integer specifying the number of items contained in the external property file
    pub item_count: Option<i32>,

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

/// Defines locations of special significance to SARIF consumers
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SpecialLocations {
    /// Provides a suggestion to SARIF consumers to display file paths relative to the specified location
    pub display_base: Option<crate::types::ArtifactLocation>,

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

/// Specifies the information necessary to retrieve a desired revision from a version control system
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct VersionControlDetails {
    /// The absolute URI of the repository
    pub repository_uri: String,

    /// A string that uniquely and permanently identifies an arbitrary revision within the repository
    pub revision_id: Option<String>,

    /// The name of a branch containing the revision
    pub branch: Option<String>,

    /// A tag that has been applied to the revision
    pub revision_tag: Option<String>,

    /// A Coordinated Universal Time (UTC) date and time that can be used to synchronize an enlistment to the state of the repository at that time
    pub as_of_time_utc: Option<String>,

    /// The location in the local file system to which the root of the repository was mapped at the time of the analysis
    pub mapped_to: Option<crate::types::ArtifactLocation>,

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

/// Specifies the unit in which the tool measures columns
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum ColumnKind {
    /// Columns are measured in UTF-16 code units
    Utf16CodeUnits,
    /// Columns are measured in Unicode code points
    UnicodeCodePoints,
}

// Re-export types (removed to avoid conflicts)

impl Run {
    /// Create a new run with the specified tool
    pub fn new(tool: Tool) -> Self {
        Self {
            tool,
            invocations: None,
            conversion: None,
            language: None,
            version_control_provenance: None,
            original_uri_base_ids: None,
            artifacts: None,
            logical_locations: None,
            graphs: None,
            results: None,
            automation_details: None,
            run_aggregates: None,
            baseline_guid: None,
            redaction_tokens: None,
            default_encoding: None,
            default_source_language: None,
            newline_sequences: None,
            column_kind: None,
            external_property_file_references: None,
            thread_flow_locations: None,
            taxonomies: None,
            addresses: None,
            translations: None,
            policies: None,
            web_requests: None,
            web_responses: None,
            special_locations: None,
            properties: None,
        }
    }

    /// Add a result to the run
    pub fn add_result(mut self, result: Result) -> Self {
        self.results.get_or_insert_with(Vec::new).push(result);
        self
    }

    /// Add multiple results to the run
    pub fn add_results(mut self, results: Vec<Result>) -> Self {
        self.results.get_or_insert_with(Vec::new).extend(results);
        self
    }

    /// Add an artifact to the run
    pub fn add_artifact(mut self, artifact: Artifact) -> Self {
        self.artifacts.get_or_insert_with(Vec::new).push(artifact);
        self
    }

    /// Add an invocation to the run
    pub fn add_invocation(mut self, invocation: crate::types::Invocation) -> Self {
        self.invocations
            .get_or_insert_with(Vec::new)
            .push(invocation);
        self
    }

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

    /// Set the default encoding
    pub fn with_default_encoding(mut self, encoding: impl Into<String>) -> Self {
        self.default_encoding = Some(encoding.into());
        self
    }

    /// Set the default source language
    pub fn with_default_source_language(mut self, language: impl Into<String>) -> Self {
        self.default_source_language = Some(language.into());
        self
    }

    /// Set the column kind
    pub fn with_column_kind(mut self, column_kind: ColumnKind) -> Self {
        self.column_kind = Some(column_kind);
        self
    }

    /// Set automation details
    pub fn with_automation_details(mut self, details: RunAutomationDetails) -> Self {
        self.automation_details = Some(details);
        self
    }
}

impl RunAutomationDetails {
    /// Create new automation details
    pub fn new() -> Self {
        Self {
            description: None,
            id: None,
            guid: None,
            correlation_guid: None,
            properties: None,
        }
    }

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

    /// Set the GUID
    pub fn with_guid(mut self, guid: impl Into<String>) -> Self {
        self.guid = Some(guid.into());
        self
    }

    /// Set the correlation GUID
    pub fn with_correlation_guid(mut self, guid: impl Into<String>) -> Self {
        self.correlation_guid = Some(guid.into());
        self
    }

    /// Set the description
    pub fn with_description(mut self, description: impl Into<crate::types::Message>) -> Self {
        self.description = Some(description.into());
        self
    }
}

impl VersionControlDetails {
    /// Create new version control details
    pub fn new(repository_uri: impl Into<String>) -> Self {
        Self {
            repository_uri: repository_uri.into(),
            revision_id: None,
            branch: None,
            revision_tag: None,
            as_of_time_utc: None,
            mapped_to: None,
            properties: None,
        }
    }

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

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

    /// Set the revision tag
    pub fn with_revision_tag(mut self, tag: impl Into<String>) -> Self {
        self.revision_tag = Some(tag.into());
        self
    }

    /// Set the mapped location
    pub fn with_mapped_to(mut self, location: crate::types::ArtifactLocation) -> Self {
        self.mapped_to = Some(location);
        self
    }
}

impl Default for RunAutomationDetails {
    fn default() -> Self {
        Self::new()
    }
}