sarif_rust 0.3.0

//! SARIF tool-related types
//!
//! This module defines structures for representing analysis tools and their components.

use crate::types::{Message, MultiformatMessage, NotificationLevel};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// The analysis tool that was run
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Tool {
    /// The tool driver that was run
    pub driver: ToolComponent,

    /// Tool extensions that contributed to or reconfigured the analysis tool
    pub extensions: Option<Vec<ToolComponent>>,

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

/// A component of the tool, such as a driver, extension, or plugin
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ToolComponent {
    /// A unique identifier for the tool component
    pub guid: Option<String>,

    /// The name of the tool component
    pub name: String,

    /// The organization or company that produced the tool component
    pub organization: Option<String>,

    /// A product suite to which the tool component belongs
    pub product: Option<String>,

    /// A brief description of the tool component
    pub product_suite: Option<String>,

    /// A comprehensive description of the tool component
    pub short_description: Option<MultiformatMessage>,

    /// A comprehensive description of the tool component  
    pub full_description: Option<MultiformatMessage>,

    /// The name of the tool component along with its version
    pub full_name: Option<String>,

    /// The tool component version
    pub version: Option<String>,

    /// The tool component version in the format major.minor.build.revision
    pub semantic_version: Option<String>,

    /// The binary version of the tool component
    pub dotted_quad_file_version: Option<String>,

    /// A string specifying the UTC date (and optionally, the time) of the component's release
    pub release_date_utc: Option<String>,

    /// The absolute URI from which the tool component can be downloaded
    pub download_uri: Option<String>,

    /// The absolute URI at which information about this version of the tool component can be found
    pub information_uri: Option<String>,

    /// A dictionary, each of whose keys is a resource identifier and each of whose values is a multiformatMessage
    pub global_message_strings: Option<HashMap<String, MultiformatMessage>>,

    /// An array of reportingDescriptor objects relevant to the notifications related to the configuration and runtime execution of the tool component
    pub notifications: Option<Vec<ReportingDescriptor>>,

    /// An array of reportingDescriptor objects relevant to the analysis performed by the tool component
    pub rules: Option<Vec<ReportingDescriptor>>,

    /// An array of reportingDescriptor objects relevant to the definitions of both standalone and tool-defined taxa
    pub taxa: Option<Vec<ReportingDescriptor>>,

    /// An array of the artifactLocation objects representing the locations of the tool component's associated files
    pub locations: Option<Vec<crate::types::ArtifactLocation>>,

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

    /// The contents of the tool component
    pub contents: Option<Vec<ToolComponentContents>>,

    /// Specifies whether this object contains a complete definition of the localizable and/or non-localizable data for this component
    pub is_comprehensive: Option<bool>,

    /// The semantic version of the localized strings defined in this component
    pub localized_data_semantic_version: Option<String>,

    /// The minimum value of localizedDataSemanticVersion required in translations consumed by this component
    pub minimum_required_localized_data_semantic_version: Option<String>,

    /// The component which is strongly associated with this component
    pub associated_component: Option<ToolComponentReference>,

    /// Translation metadata, required for a translation, not populated by other component types
    pub translation_metadata: Option<TranslationMetadata>,

    /// An array of toolComponentReference objects to declare the taxonomies supported by the tool component
    pub supported_taxonomies: Option<Vec<ToolComponentReference>>,

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

/// Metadata that describes a specific report produced by the tool
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ReportingDescriptor {
    /// A stable, opaque identifier for the report
    pub id: String,

    /// An array of stable, opaque identifiers by which this report was known in some previous version of the analysis tool
    pub deprecated_ids: Option<Vec<String>>,

    /// A unique identifier for the reporting descriptor
    pub guid: Option<String>,

    /// An array of unique identifies in the form of a GUID by which this report was known in some previous version of the analysis tool
    pub deprecated_guids: Option<Vec<String>>,

    /// A report identifier that is understandable to an end user
    pub name: Option<String>,

    /// An array of readable identifiers by which this report was known in some previous version of the analysis tool
    pub deprecated_names: Option<Vec<String>>,

    /// A concise description of the report
    pub short_description: Option<MultiformatMessage>,

    /// A description of the report
    pub full_description: Option<MultiformatMessage>,

    /// A set of name/value pairs with arbitrary names
    pub message_strings: Option<HashMap<String, MultiformatMessage>>,

    /// Default reporting configuration information
    pub default_configuration: Option<ReportingConfiguration>,

    /// A URI where the primary documentation for this reportingDescriptor resides
    pub help_uri: Option<String>,

    /// Provides the primary documentation for this reportingDescriptor
    pub help: Option<MultiformatMessage>,

    /// An array of objects that describe relationships between this reportingDescriptor and others
    pub relationships: Option<Vec<ReportingDescriptorRelationship>>,

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

/// Information about how to configure a reporting descriptor
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ReportingConfiguration {
    /// Specifies whether the report may be produced during the scan
    pub enabled: Option<bool>,

    /// Specifies the failure level for the report
    pub level: Option<NotificationLevel>,

    /// Contains configuration information specific to a report
    pub parameters: Option<HashMap<String, serde_json::Value>>,

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

/// Information about the relation of one reporting descriptor to another
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ReportingDescriptorRelationship {
    /// A reference to the related reporting descriptor
    pub target: ReportingDescriptorReference,

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

    /// A description of the reporting descriptor relationship
    pub description: Option<Message>,

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

/// Information that describes a reporting descriptor's relationship to a taxonomy
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ReportingDescriptorReference {
    /// The id of the descriptor
    pub id: Option<String>,

    /// The index into an array of descriptors
    pub index: Option<i32>,

    /// A guid that uniquely identifies the descriptor
    pub guid: Option<String>,

    /// A reference used to locate the toolComponent associated with the descriptor
    pub tool_component: Option<ToolComponentReference>,

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

/// Identifies a particular toolComponent object, either the driver or an extension
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ToolComponentReference {
    /// The name of the component
    pub name: Option<String>,

    /// The index within the 'extensions' array of the component
    pub index: Option<i32>,

    /// The toolComponent guid
    pub guid: Option<String>,

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

/// Describes the content type for files of a particular kind
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum ToolComponentContents {
    /// The tool component localizable strings
    LocalizedData,
    /// The tool component non-localizable strings
    NonLocalizedData,
}

/// Provides additional metadata related to translation
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TranslationMetadata {
    /// The name associated with the translation metadata
    pub name: String,

    /// The full name associated with the translation metadata
    pub full_name: Option<String>,

    /// A brief description of the translation metadata
    pub short_description: Option<MultiformatMessage>,

    /// A comprehensive description of the translation metadata
    pub full_description: Option<MultiformatMessage>,

    /// The absolute URI from which the translation metadata can be downloaded
    pub download_uri: Option<String>,

    /// The absolute URI from which information about this translation can be downloaded
    pub information_uri: Option<String>,

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

impl Tool {
    /// Create a new tool with a driver
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            driver: ToolComponent::new(name),
            extensions: None,
            properties: None,
        }
    }

    /// Add an extension to the tool
    pub fn add_extension(mut self, extension: ToolComponent) -> Self {
        self.extensions.get_or_insert_with(Vec::new).push(extension);
        self
    }
}

impl ToolComponent {
    /// Create a new tool component
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            guid: None,
            name: name.into(),
            organization: None,
            product: None,
            product_suite: None,
            short_description: None,
            full_description: None,
            full_name: None,
            version: None,
            semantic_version: None,
            dotted_quad_file_version: None,
            release_date_utc: None,
            download_uri: None,
            information_uri: None,
            global_message_strings: None,
            notifications: None,
            rules: None,
            taxa: None,
            locations: None,
            language: None,
            contents: None,
            is_comprehensive: None,
            localized_data_semantic_version: None,
            minimum_required_localized_data_semantic_version: None,
            associated_component: None,
            translation_metadata: None,
            supported_taxonomies: None,
            properties: None,
        }
    }

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

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

    /// Add a rule to the component
    pub fn add_rule(mut self, rule: ReportingDescriptor) -> Self {
        self.rules.get_or_insert_with(Vec::new).push(rule);
        self
    }

    /// Set the information URI
    pub fn with_information_uri(mut self, uri: impl Into<String>) -> Self {
        self.information_uri = Some(uri.into());
        self
    }
}

impl ReportingDescriptor {
    /// Create a new reporting descriptor
    pub fn new(id: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            deprecated_ids: None,
            guid: None,
            deprecated_guids: None,
            name: None,
            deprecated_names: None,
            short_description: None,
            full_description: None,
            message_strings: None,
            default_configuration: None,
            help_uri: None,
            help: None,
            relationships: None,
            properties: None,
        }
    }

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

    /// Set the short description
    pub fn with_short_description(mut self, description: impl Into<MultiformatMessage>) -> Self {
        self.short_description = Some(description.into());
        self
    }

    /// Set the help URI
    pub fn with_help_uri(mut self, uri: impl Into<String>) -> Self {
        self.help_uri = Some(uri.into());
        self
    }
}