sarif_rust 0.3.0

//! SARIF location-related types
//!
//! This module defines structures for representing locations within artifacts.

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

/// A location within a programming artifact
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Location {
    /// Value that distinguishes this location from all other locations within a single result object
    pub id: Option<i32>,

    /// Identifies the artifact and region
    pub physical_location: Option<PhysicalLocation>,

    /// The logical locations associated with the location
    pub logical_locations: Option<Vec<LogicalLocation>>,

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

    /// A set of regions relevant to the location
    pub annotations: Option<Vec<Region>>,

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

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

/// A physical location relevant to a result
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PhysicalLocation {
    /// The location of the artifact
    pub artifact_location: Option<ArtifactLocation>,

    /// Specifies a portion of the artifact
    pub region: Option<Region>,

    /// Specifies a portion of the artifact that encloses the region
    pub context_region: Option<Region>,

    /// The address of the location
    pub address: Option<Address>,

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

/// A region within an artifact where a result was detected
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Region {
    /// The line number of the first character in the region
    pub start_line: Option<i32>,

    /// The column number of the first character in the region
    pub start_column: Option<i32>,

    /// The line number of the last character in the region
    pub end_line: Option<i32>,

    /// The column number of the character following the end of the region
    pub end_column: Option<i32>,

    /// The zero-based offset from the beginning of the artifact of the first character in the region
    pub char_offset: Option<i32>,

    /// The length of the region in characters
    pub char_length: Option<i32>,

    /// The zero-based offset from the beginning of the artifact of the first byte in the region
    pub byte_offset: Option<i32>,

    /// The length of the region in bytes
    pub byte_length: Option<i32>,

    /// The portion of the artifact contents within the specified region
    pub snippet: Option<ArtifactContent>,

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

    /// Specifies the source language, if any, of the portion of the artifact specified by the region object
    pub source_language: Option<String>,

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

/// A logical location of a construct that produced a result
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LogicalLocation {
    /// Identifies the construct in which the result occurred
    pub name: Option<String>,

    /// The index within the logical locations array
    pub index: Option<i32>,

    /// The human-readable fully qualified name of the logical location
    pub fully_qualified_name: Option<String>,

    /// The machine-readable name for the logical location
    pub decorated_name: Option<String>,

    /// Identifies the index of the immediate parent of the construct
    pub parent_index: Option<i32>,

    /// The type of construct this logical location component refers to
    pub kind: Option<String>,

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

/// A physical or virtual address, or a range of addresses, in an 'addressable region'
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Address {
    /// The address expressed as a byte offset from the start of the addressable region
    pub absolute_address: Option<i64>,

    /// The address expressed as a byte offset from the absolute address of the segment
    pub relative_address: Option<i32>,

    /// The number of bytes in this range of addresses
    pub length: Option<i32>,

    /// An open-ended string that identifies the address kind
    pub kind: Option<String>,

    /// A name that is associated with the address
    pub name: Option<String>,

    /// A human-readable fully qualified name that is associated with the address
    pub fully_qualified_name: Option<String>,

    /// The byte offset of this address from the absolute or relative address of the parent object
    pub offset_from_parent: Option<i32>,

    /// The index within the 'addresses' array of the address object containing this address
    pub parent_index: Option<i32>,

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

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

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

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

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

/// Represents the contents of an artifact
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ArtifactContent {
    /// 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 about the artifact content
    #[serde(flatten)]
    pub properties: Option<HashMap<String, serde_json::Value>>,
}

impl Location {
    /// Create a new location
    pub fn new() -> Self {
        Self {
            id: None,
            physical_location: None,
            logical_locations: None,
            message: None,
            annotations: None,
            relationships: None,
            properties: None,
        }
    }

    /// Create a location with a physical location
    pub fn with_physical_location(physical_location: PhysicalLocation) -> Self {
        Self {
            id: None,
            physical_location: Some(physical_location),
            logical_locations: None,
            message: None,
            annotations: None,
            relationships: None,
            properties: None,
        }
    }

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

    /// Add a logical location
    pub fn add_logical_location(mut self, logical_location: LogicalLocation) -> Self {
        self.logical_locations
            .get_or_insert_with(Vec::new)
            .push(logical_location);
        self
    }
}

impl PhysicalLocation {
    /// Create a new physical location
    pub fn new() -> Self {
        Self {
            artifact_location: None,
            region: None,
            context_region: None,
            address: None,
            properties: None,
        }
    }

    /// Create a physical location with an artifact location
    pub fn with_artifact_location(artifact_location: ArtifactLocation) -> Self {
        Self {
            artifact_location: Some(artifact_location),
            region: None,
            context_region: None,
            address: None,
            properties: None,
        }
    }

    /// Set the region
    pub fn with_region(mut self, region: Region) -> Self {
        self.region = Some(region);
        self
    }

    /// Set the context region
    pub fn with_context_region(mut self, context_region: Region) -> Self {
        self.context_region = Some(context_region);
        self
    }
}

impl Region {
    /// Create a new region
    pub fn new() -> Self {
        Self {
            start_line: None,
            start_column: None,
            end_line: None,
            end_column: None,
            char_offset: None,
            char_length: None,
            byte_offset: None,
            byte_length: None,
            snippet: None,
            message: None,
            source_language: None,
            properties: None,
        }
    }

    /// Create a region from line and column coordinates
    pub fn from_coordinates(
        start_line: i32,
        start_column: i32,
        end_line: i32,
        end_column: i32,
    ) -> Self {
        Self {
            start_line: Some(start_line),
            start_column: Some(start_column),
            end_line: Some(end_line),
            end_column: Some(end_column),
            char_offset: None,
            char_length: None,
            byte_offset: None,
            byte_length: None,
            snippet: None,
            message: None,
            source_language: None,
            properties: None,
        }
    }

    /// Create a region from a single line
    pub fn from_line(line: i32) -> Self {
        Self {
            start_line: Some(line),
            start_column: None,
            end_line: Some(line),
            end_column: None,
            char_offset: None,
            char_length: None,
            byte_offset: None,
            byte_length: None,
            snippet: None,
            message: None,
            source_language: None,
            properties: None,
        }
    }

    /// Create a region from character offset and length
    pub fn from_char_offset(offset: i32, length: i32) -> Self {
        Self {
            start_line: None,
            start_column: None,
            end_line: None,
            end_column: None,
            char_offset: Some(offset),
            char_length: Some(length),
            byte_offset: None,
            byte_length: None,
            snippet: None,
            message: None,
            source_language: None,
            properties: None,
        }
    }

    /// Set the snippet
    pub fn with_snippet(mut self, text: impl Into<String>) -> Self {
        self.snippet = Some(ArtifactContent {
            text: Some(text.into()),
            binary: None,
            properties: None,
        });
        self
    }
}

impl LogicalLocation {
    /// Create a new logical location
    pub fn new() -> Self {
        Self {
            name: None,
            index: None,
            fully_qualified_name: None,
            decorated_name: None,
            parent_index: None,
            kind: None,
            properties: None,
        }
    }

    /// Create a logical location with a name
    pub fn with_name(name: impl Into<String>) -> Self {
        Self {
            name: Some(name.into()),
            index: None,
            fully_qualified_name: None,
            decorated_name: None,
            parent_index: None,
            kind: None,
            properties: None,
        }
    }

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

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

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

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

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

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