sbom-tools 0.2.0

//! Diff result structures.

use crate::model::{CanonicalId, Component, ComponentRef, DependencyEdge, VulnerabilityRef};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// Map a severity string to a numeric rank for comparison.
///
/// Higher values indicate more severe vulnerabilities.
/// Returns 0 for unrecognized severity strings.
fn severity_rank(s: &str) -> u8 {
    match s.to_lowercase().as_str() {
        "critical" => 4,
        "high" => 3,
        "medium" => 2,
        "low" => 1,
        _ => 0,
    }
}

/// Complete result of an SBOM diff operation.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[must_use]
pub struct DiffResult {
    /// Summary statistics
    pub summary: DiffSummary,
    /// Component changes
    pub components: ChangeSet<ComponentChange>,
    /// Dependency changes
    pub dependencies: ChangeSet<DependencyChange>,
    /// License changes
    pub licenses: LicenseChanges,
    /// Vulnerability changes
    pub vulnerabilities: VulnerabilityChanges,
    /// Overall semantic similarity of the two documents, **0.0-100.0**
    /// (100 = identical). This is the single-diff scale used by every
    /// `diff` output; the multi-SBOM commands rescale it to a 0.0-1.0
    /// fraction (`MatrixResult::similarity_scores`, and `1 - similarity`
    /// for `MultiDiffSummary::deviation_scores`).
    pub semantic_score: f64,
    /// Document-level metadata changes (author, tool, timestamp, spec version,
    /// lifecycle phase, signature, document/primary-component version)
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub metadata_changes: Vec<MetadataChange>,
    /// Graph structural changes (only populated if graph diffing is enabled)
    #[serde(default)]
    pub graph_changes: Vec<DependencyGraphChange>,
    /// Summary of graph changes
    #[serde(default)]
    pub graph_summary: Option<GraphChangeSummary>,
    /// Number of custom matching rules applied
    #[serde(default)]
    pub rules_applied: usize,
    /// Quality impact of this diff (computed post-diff)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quality_delta: Option<QualityDelta>,
    /// Matching quality metrics (populated during diff)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub match_metrics: Option<MatchMetrics>,
    /// Supported numeric ML performance metrics that moved in the adverse direction.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub ml_regressions: Vec<MlRegression>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MlRegression {
    pub component: String,
    pub metric: String,
    pub previous_value: f64,
    pub new_value: f64,
}

/// Whether a higher value of the named ML metric is better (`Some(true)`),
/// worse (`Some(false)`), or unknown (`None`). Slice-qualified names
/// ("accuracy@validation") key on the base metric. Shared by the CLI
/// regression gate and the TUI so their notions of "regressed" cannot drift.
#[must_use]
pub fn ml_metric_higher_is_better(metric: &str) -> Option<bool> {
    let metric = metric.split('@').next().unwrap_or(metric);
    match metric {
        "accuracy" | "f1" | "f1_score" | "precision" | "recall" | "auc" | "roc_auc" | "bleu"
        | "rouge" => Some(true),
        "loss" | "error" | "error_rate" | "perplexity" | "latency" | "latency_ms" => Some(false),
        _ => None,
    }
}

impl DiffResult {
    /// Create a new empty diff result
    pub fn new() -> Self {
        Self {
            summary: DiffSummary::default(),
            components: ChangeSet::new(),
            dependencies: ChangeSet::new(),
            licenses: LicenseChanges::default(),
            vulnerabilities: VulnerabilityChanges::default(),
            semantic_score: 0.0,
            metadata_changes: Vec::new(),
            graph_changes: Vec::new(),
            graph_summary: None,
            rules_applied: 0,
            quality_delta: None,
            match_metrics: None,
            ml_regressions: Vec::new(),
        }
    }

    /// Calculate and update summary statistics
    pub fn calculate_summary(&mut self) {
        self.summary.components_added = self.components.added.len();
        self.summary.components_removed = self.components.removed.len();
        // Unchanged entries (produced under --include-unchanged) live in the
        // modified stream for rendering but are not modifications.
        self.summary.components_modified = self
            .components
            .modified
            .iter()
            .filter(|c| c.change_type != ChangeType::Unchanged)
            .count();

        self.summary.dependencies_added = self.dependencies.added.len();
        self.summary.dependencies_removed = self.dependencies.removed.len();
        self.summary.graph_changes_count = self.graph_changes.len();
        self.summary.metadata_changes_count = self.metadata_changes.len();

        self.summary.total_changes = self.summary.components_added
            + self.summary.components_removed
            + self.summary.components_modified
            + self.summary.dependencies_added
            + self.summary.dependencies_removed
            + self.summary.graph_changes_count
            + self.summary.metadata_changes_count;

        self.summary.vulnerabilities_introduced = self.vulnerabilities.introduced.len();
        self.summary.vulnerabilities_resolved = self.vulnerabilities.resolved.len();
        self.summary.vulnerabilities_persistent = self.vulnerabilities.persistent.len();

        self.summary.licenses_added = self.licenses.new_licenses.len();
        self.summary.licenses_removed = self.licenses.removed_licenses.len();
    }

    /// Check if there are any changes.
    ///
    /// Checks both the pre-computed summary and the source-of-truth fields to be
    /// safe regardless of whether `calculate_summary()` was called.
    ///
    /// Unchanged inventory entries (produced under `--include-unchanged`) are
    /// not changes: a zero-change diff reports `false` regardless of the flag.
    #[must_use]
    pub fn has_changes(&self) -> bool {
        self.summary.total_changes > 0
            || !self.components.added.is_empty()
            || !self.components.removed.is_empty()
            || self
                .components
                .modified
                .iter()
                .any(|c| c.change_type != ChangeType::Unchanged)
            || !self.dependencies.is_empty()
            || !self.graph_changes.is_empty()
            || !self.metadata_changes.is_empty()
            || !self.vulnerabilities.introduced.is_empty()
            || !self.vulnerabilities.resolved.is_empty()
    }

    /// Recompute date-derived vulnerability day counts for today.
    ///
    /// Cached results embed the day they were computed; the incremental
    /// engine calls this on cache hits so counts (and the SLA statuses
    /// derived from them) do not go stale across midnight. Returns true if
    /// anything changed.
    pub fn refresh_derived_day_counts(&mut self) -> bool {
        let today = chrono::Utc::now().date_naive();
        let mut changed = false;
        for detail in self
            .vulnerabilities
            .introduced
            .iter_mut()
            .chain(self.vulnerabilities.resolved.iter_mut())
            .chain(self.vulnerabilities.persistent.iter_mut())
        {
            changed |= detail.refresh_day_counts(today);
        }
        changed
    }

    /// Whether any vulnerability day-count field is stale for today.
    #[must_use]
    pub fn day_counts_stale(&self) -> bool {
        let today = chrono::Utc::now().date_naive();
        self.vulnerabilities
            .introduced
            .iter()
            .chain(self.vulnerabilities.resolved.iter())
            .chain(self.vulnerabilities.persistent.iter())
            .any(|detail| {
                let mut probe = detail.clone();
                probe.refresh_day_counts(today)
            })
    }

    /// Find a component change by canonical ID
    #[must_use]
    pub fn find_component_by_id(&self, id: &CanonicalId) -> Option<&ComponentChange> {
        let id_str = id.value();
        self.components
            .added
            .iter()
            .chain(self.components.removed.iter())
            .chain(self.components.modified.iter())
            .find(|c| c.id == id_str)
    }

    /// Find a component change by ID string
    #[must_use]
    pub fn find_component_by_id_str(&self, id_str: &str) -> Option<&ComponentChange> {
        self.components
            .added
            .iter()
            .chain(self.components.removed.iter())
            .chain(self.components.modified.iter())
            .find(|c| c.id == id_str)
    }

    /// Get all component changes as a flat list with their indices for navigation
    #[must_use]
    pub fn all_component_changes(&self) -> Vec<&ComponentChange> {
        self.components
            .added
            .iter()
            .chain(self.components.removed.iter())
            .chain(self.components.modified.iter())
            .collect()
    }

    /// Find vulnerabilities affecting a specific component by ID
    #[must_use]
    pub fn find_vulns_for_component(
        &self,
        component_id: &CanonicalId,
    ) -> Vec<&VulnerabilityDetail> {
        let id_str = component_id.value();
        self.vulnerabilities
            .introduced
            .iter()
            .chain(self.vulnerabilities.resolved.iter())
            .chain(self.vulnerabilities.persistent.iter())
            .filter(|v| v.component_id == id_str)
            .collect()
    }

    /// Build an index of component IDs to their changes for fast lookup
    #[must_use]
    pub fn build_component_id_index(&self) -> HashMap<String, &ComponentChange> {
        self.components
            .added
            .iter()
            .chain(&self.components.removed)
            .chain(&self.components.modified)
            .map(|c| (c.id.clone(), c))
            .collect()
    }

    /// Filter vulnerabilities by minimum severity level
    pub fn filter_by_severity(&mut self, min_severity: &str) {
        let min_sev = severity_rank(min_severity);

        self.vulnerabilities
            .introduced
            .retain(|v| severity_rank(&v.severity) >= min_sev);
        self.vulnerabilities
            .resolved
            .retain(|v| severity_rank(&v.severity) >= min_sev);
        self.vulnerabilities
            .persistent
            .retain(|v| severity_rank(&v.severity) >= min_sev);

        // Recalculate summary
        self.calculate_summary();
    }

    /// Filter out vulnerabilities where VEX status is `NotAffected` or `Fixed`.
    ///
    /// Keeps vulnerabilities that are `Affected`, `UnderInvestigation`, or have no VEX status.
    pub fn filter_by_vex(&mut self) {
        self.vulnerabilities
            .introduced
            .retain(VulnerabilityDetail::is_vex_actionable);
        self.vulnerabilities
            .resolved
            .retain(VulnerabilityDetail::is_vex_actionable);
        self.vulnerabilities
            .persistent
            .retain(VulnerabilityDetail::is_vex_actionable);

        self.calculate_summary();
    }
}

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

/// Quality and compliance impact of the diff.
///
/// Computed by comparing quality scores of old vs new SBOMs.
/// Enables tracking whether a change improves or degrades SBOM quality.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct QualityDelta {
    /// Overall score change (positive = improvement)
    pub overall_score_delta: f32,
    /// Old grade
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub old_grade: Option<crate::quality::QualityGrade>,
    /// New grade
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub new_grade: Option<crate::quality::QualityGrade>,
    /// Per-category score deltas
    pub category_deltas: Vec<CategoryDelta>,
    /// Categories that regressed (score decreased by >1 point)
    pub regressions: Vec<String>,
    /// Categories that improved (score increased by >1 point)
    pub improvements: Vec<String>,
    /// Compliance violation count change (positive = more violations)
    pub violation_count_delta: i32,
}

/// Score delta for a specific quality category.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CategoryDelta {
    /// Category name (e.g., "Completeness", "Identifiers")
    pub category: String,
    /// Score in old SBOM
    pub old_score: f32,
    /// Score in new SBOM
    pub new_score: f32,
    /// Change (new - old)
    pub delta: f32,
}

/// The per-slot scores the CBOM scorer actually used, or `None` when the
/// report was not scored by the CBOM substitution path.
///
/// Mirrors `quality::scorer`'s slot substitution exactly (crypto scores in
/// slots 1-6, standard provenance/licenses in slots 7-8), including its
/// gates: a CBOM-profile report with no crypto data falls back to standard
/// scoring (so its delta must keep the generic category names too), and PQC
/// readiness is `None` when no algorithms exist — the scorer reweights it
/// away, so the delta omits it the same way VulnDocs/Lifecycle are omitted.
/// Slot order matches [`crate::quality::CryptographyMetrics::cbom_category_names`].
fn cbom_slot_scores(report: &crate::quality::QualityReport) -> Option<[Option<f32>; 8]> {
    if report.profile != crate::quality::ScoringProfile::Cbom
        || !report.cryptography_metrics.has_data()
    {
        return None;
    }
    let cm = &report.cryptography_metrics;
    Some([
        Some(cm.crypto_completeness_score()),
        Some(cm.crypto_identifier_score()),
        Some(cm.algorithm_strength_score()),
        Some(cm.crypto_dependency_score()),
        Some(cm.crypto_lifecycle_score()),
        cm.pqc_readiness_score(),
        Some(report.provenance_score),
        Some(report.license_score),
    ])
}

impl QualityDelta {
    /// Compute quality delta by comparing two quality reports.
    ///
    /// Category names are profile-aware: when BOTH reports were scored by the
    /// CBOM substitution path, the deltas carry the crypto category names the
    /// scorer's arithmetic actually used
    /// ([`crate::quality::CryptographyMetrics::cbom_category_names`]) instead
    /// of the generic ones — a "Completeness" regression on a CBOM diff would
    /// describe a score that never contributed to either headline number.
    #[must_use]
    pub fn from_reports(
        old: &crate::quality::QualityReport,
        new: &crate::quality::QualityReport,
    ) -> Self {
        let category_deltas: Vec<CategoryDelta> =
            match (cbom_slot_scores(old), cbom_slot_scores(new)) {
                (Some(old_slots), Some(new_slots)) => {
                    crate::quality::CryptographyMetrics::cbom_category_names()
                        .iter()
                        .zip(old_slots.iter().zip(new_slots.iter()))
                        // A slot that is N/A on either side (PQC without
                        // algorithms) is omitted, like VulnDocs/Lifecycle.
                        .filter_map(|(name, (old_s, new_s))| match (old_s, new_s) {
                            (Some(o), Some(n)) => Some(CategoryDelta {
                                category: (*name).to_string(),
                                old_score: *o,
                                new_score: *n,
                                delta: n - o,
                            }),
                            _ => None,
                        })
                        .collect()
                }
                // Mixed pairs (CBOM vs plain SBOM) keep the generic categories:
                // per-category deltas need the same scale on both sides.
                _ => Self::standard_category_deltas(old, new),
            };

        let regressions: Vec<String> = category_deltas
            .iter()
            .filter(|d| d.delta < -1.0)
            .map(|d| d.category.clone())
            .collect();

        let improvements: Vec<String> = category_deltas
            .iter()
            .filter(|d| d.delta > 1.0)
            .map(|d| d.category.clone())
            .collect();

        // Compute compliance violation delta
        let old_violations = old.compliance.error_count + old.compliance.warning_count;
        let new_violations = new.compliance.error_count + new.compliance.warning_count;

        Self {
            overall_score_delta: new.overall_score - old.overall_score,
            old_grade: Some(old.grade),
            new_grade: Some(new.grade),
            category_deltas,
            regressions,
            improvements,
            violation_count_delta: new_violations as i32 - old_violations as i32,
        }
    }

    /// The generic (non-CBOM) per-category deltas: the six always-scored
    /// categories plus VulnDocs/Lifecycle when both sides have them.
    fn standard_category_deltas(
        old: &crate::quality::QualityReport,
        new: &crate::quality::QualityReport,
    ) -> Vec<CategoryDelta> {
        let categories = [
            (
                "Completeness",
                old.completeness_score,
                new.completeness_score,
            ),
            ("Identifiers", old.identifier_score, new.identifier_score),
            ("Licenses", old.license_score, new.license_score),
            ("Dependencies", old.dependency_score, new.dependency_score),
            ("Integrity", old.integrity_score, new.integrity_score),
            ("Provenance", old.provenance_score, new.provenance_score),
        ];

        let mut category_deltas: Vec<CategoryDelta> = categories
            .iter()
            .map(|(name, old_s, new_s)| CategoryDelta {
                category: (*name).to_string(),
                old_score: *old_s,
                new_score: *new_s,
                delta: new_s - old_s,
            })
            .collect();

        // Handle optional categories (VulnDocs and Lifecycle)
        if let (Some(old_v), Some(new_v)) = (old.vulnerability_score, new.vulnerability_score) {
            category_deltas.push(CategoryDelta {
                category: "VulnDocs".to_string(),
                old_score: old_v,
                new_score: new_v,
                delta: new_v - old_v,
            });
        }
        if let (Some(old_l), Some(new_l)) = (old.lifecycle_score, new.lifecycle_score) {
            category_deltas.push(CategoryDelta {
                category: "Lifecycle".to_string(),
                old_score: old_l,
                new_score: new_l,
                delta: new_l - old_l,
            });
        }
        category_deltas
    }
}

/// Metrics about the component matching process.
///
/// Provides visibility into matching quality for debugging and tuning.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct MatchMetrics {
    /// Number of exact matches: identical identifiers or identical names
    /// (score ≥ 0.995, i.e. the 1.0 identity tiers)
    pub exact_matches: usize,
    /// Number of fuzzy matches (below exact threshold)
    pub fuzzy_matches: usize,
    /// Matched pairs declared equivalent by user matching rules
    pub rule_matches: usize,
    /// Components in old SBOM with no match
    pub unmatched_old: usize,
    /// Components in new SBOM with no match
    pub unmatched_new: usize,
    /// Average match confidence score
    pub avg_match_score: f64,
    /// Minimum match confidence score
    pub min_match_score: f64,
}

/// Summary statistics for the diff
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct DiffSummary {
    pub total_changes: usize,
    pub components_added: usize,
    pub components_removed: usize,
    pub components_modified: usize,
    pub dependencies_added: usize,
    pub dependencies_removed: usize,
    pub graph_changes_count: usize,
    pub metadata_changes_count: usize,
    pub vulnerabilities_introduced: usize,
    pub vulnerabilities_resolved: usize,
    pub vulnerabilities_persistent: usize,
    pub licenses_added: usize,
    pub licenses_removed: usize,
}

/// Generic change set for added/removed/modified items
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChangeSet<T> {
    pub added: Vec<T>,
    pub removed: Vec<T>,
    pub modified: Vec<T>,
}

impl<T> ChangeSet<T> {
    #[must_use]
    pub const fn new() -> Self {
        Self {
            added: Vec::new(),
            removed: Vec::new(),
            modified: Vec::new(),
        }
    }

    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.added.is_empty() && self.removed.is_empty() && self.modified.is_empty()
    }

    #[must_use]
    pub fn total(&self) -> usize {
        self.added.len() + self.removed.len() + self.modified.len()
    }
}

impl<T> Default for ChangeSet<T> {
    fn default() -> Self {
        Self::new()
    }
}

/// Information about how a component was matched.
///
/// Included in JSON output to explain why components were correlated.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MatchInfo {
    /// Match confidence score (0.0 - 1.0)
    pub score: f64,
    /// Matching method used (`ExactIdentifier`, Alias, Fuzzy, etc.)
    pub method: String,
    /// Human-readable explanation
    pub reason: String,
    /// Detailed score breakdown (optional)
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub score_breakdown: Vec<MatchScoreComponent>,
    /// Normalizations applied during matching
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub normalizations: Vec<String>,
    /// Confidence interval for the match score
    #[serde(skip_serializing_if = "Option::is_none")]
    pub confidence_interval: Option<ConfidenceInterval>,
}

/// Confidence interval for match score.
///
/// Provides uncertainty bounds around the match score, useful for
/// understanding match reliability.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConfidenceInterval {
    /// Lower bound of confidence (0.0 - 1.0)
    pub lower: f64,
    /// Upper bound of confidence (0.0 - 1.0)
    pub upper: f64,
    /// Confidence level (e.g., 0.95 for 95% CI)
    pub level: f64,
}

impl ConfidenceInterval {
    /// Create a new confidence interval.
    #[must_use]
    pub const fn new(lower: f64, upper: f64, level: f64) -> Self {
        Self {
            lower: lower.clamp(0.0, 1.0),
            upper: upper.clamp(0.0, 1.0),
            level,
        }
    }

    /// Create a 95% confidence interval from a score and standard error.
    ///
    /// Uses ±1.96 × SE for 95% CI.
    #[must_use]
    pub fn from_score_and_error(score: f64, std_error: f64) -> Self {
        let margin = 1.96 * std_error;
        Self::new(score - margin, score + margin, 0.95)
    }

    /// Create a simple confidence interval based on the matching tier.
    ///
    /// Exact matches have tight intervals, fuzzy matches have wider intervals.
    #[must_use]
    pub fn from_tier(score: f64, tier: &str) -> Self {
        let margin = match tier {
            "ExactIdentifier" => 0.0,
            // A user rule asserts identity outright
            "EquivalenceRule" => 0.02,
            "Alias" => 0.02,
            "EcosystemRule" | "NameIdentity" => 0.03,
            "CustomRule" => 0.05,
            "Fuzzy" => 0.08,
            // Curated equivalence, but across ecosystems: widest interval
            "CrossEcosystem" => 0.10,
            _ => 0.10,
        };
        Self::new(score - margin, score + margin, 0.95)
    }

    /// Get the width of the interval.
    #[must_use]
    pub fn width(&self) -> f64 {
        self.upper - self.lower
    }
}

/// A component of the match score for JSON output.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MatchScoreComponent {
    /// Name of this score component
    pub name: String,
    /// Weight applied
    pub weight: f64,
    /// Raw score
    pub raw_score: f64,
    /// Weighted contribution
    pub weighted_score: f64,
    /// Description
    pub description: String,
}

/// Component change information
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ComponentChange {
    /// Component canonical ID (string for serialization)
    pub id: String,
    /// Typed canonical ID for navigation (skipped in JSON output for backward compat)
    #[serde(skip)]
    pub canonical_id: Option<CanonicalId>,
    /// Component reference with ID and name together
    #[serde(skip)]
    pub component_ref: Option<ComponentRef>,
    /// Old component ID (for modified components)
    #[serde(skip)]
    pub old_canonical_id: Option<CanonicalId>,
    /// Component name
    pub name: String,
    /// Old version (if existed)
    pub old_version: Option<String>,
    /// New version (if exists)
    pub new_version: Option<String>,
    /// Ecosystem
    pub ecosystem: Option<String>,
    /// Resolved component type ("library", "application",
    /// "machine-learning-model", ...). CBOM crypto assets are refined to
    /// their cryptoProperties assetType ("algorithm", "certificate",
    /// "protocol"), with related-crypto-material narrowed to its material
    /// type ("private-key", ...) — the uniform "cryptographic" component
    /// type carries no signal in a CBOM diff. Additive: omitted from JSON
    /// when unresolved so existing consumers are unaffected.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub component_type: Option<String>,
    /// Change type
    pub change_type: ChangeType,
    /// Detailed field changes
    pub field_changes: Vec<FieldChange>,
    /// Associated cost
    pub cost: u32,
    /// Match information (for modified components, explains how old/new were correlated)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub match_info: Option<MatchInfo>,
}

/// Resolve the serialized component type for a change entry.
///
/// CycloneDX component type, refined for CBOM crypto assets to the
/// cryptoProperties assetType (algorithm/certificate/protocol), with
/// related-crypto-material narrowed to its declared material type
/// (public-key, private-key, ...). ML models and datasets keep their
/// CycloneDX type strings ("machine-learning-model" / "data") — the TUI
/// applies its own display shorthand on top of the same resolution
/// (`tui::views::components::component_type_label`).
fn resolved_component_type(component: &Component) -> String {
    use crate::model::CryptoAssetType;
    if let Some(cp) = &component.crypto_properties {
        if cp.asset_type == CryptoAssetType::RelatedCryptoMaterial
            && let Some(mat) = &cp.related_crypto_material_properties
        {
            return mat.material_type.to_string();
        }
        return cp.asset_type.to_string();
    }
    component.component_type.to_string()
}

impl ComponentChange {
    /// Create a new component addition
    pub fn added(component: &Component, cost: u32) -> Self {
        Self {
            id: component.canonical_id.to_string(),
            canonical_id: Some(component.canonical_id.clone()),
            component_ref: Some(ComponentRef::from_component(component)),
            old_canonical_id: None,
            name: component.name.clone(),
            old_version: None,
            new_version: component.version.clone(),
            ecosystem: component
                .ecosystem
                .as_ref()
                .map(std::string::ToString::to_string),
            component_type: Some(resolved_component_type(component)),
            change_type: ChangeType::Added,
            field_changes: Vec::new(),
            cost,
            match_info: None,
        }
    }

    /// Create a new component removal
    pub fn removed(component: &Component, cost: u32) -> Self {
        Self {
            id: component.canonical_id.to_string(),
            canonical_id: Some(component.canonical_id.clone()),
            component_ref: Some(ComponentRef::from_component(component)),
            old_canonical_id: Some(component.canonical_id.clone()),
            name: component.name.clone(),
            old_version: component.version.clone(),
            new_version: None,
            ecosystem: component
                .ecosystem
                .as_ref()
                .map(std::string::ToString::to_string),
            component_type: Some(resolved_component_type(component)),
            change_type: ChangeType::Removed,
            field_changes: Vec::new(),
            cost,
            match_info: None,
        }
    }

    /// Create an unchanged-component entry (matched, content-equal pair).
    /// Produced only when `--include-unchanged` is enabled; carries zero cost
    /// and is excluded from modified counts and semantic scoring.
    pub fn unchanged(old: &Component, new: &Component) -> Self {
        Self {
            id: new.canonical_id.to_string(),
            canonical_id: Some(new.canonical_id.clone()),
            component_ref: Some(ComponentRef::from_component(new)),
            old_canonical_id: Some(old.canonical_id.clone()),
            name: new.name.clone(),
            old_version: old.version.clone(),
            new_version: new.version.clone(),
            ecosystem: new.ecosystem.as_ref().map(std::string::ToString::to_string),
            // New side: a matched pair's current type (mirrors the TUI's
            // new-side-first resolution for changed components).
            component_type: Some(resolved_component_type(new)),
            change_type: ChangeType::Unchanged,
            field_changes: Vec::new(),
            cost: 0,
            match_info: None,
        }
    }

    /// Create a component modification
    pub fn modified(
        old: &Component,
        new: &Component,
        field_changes: Vec<FieldChange>,
        cost: u32,
    ) -> Self {
        Self {
            id: new.canonical_id.to_string(),
            canonical_id: Some(new.canonical_id.clone()),
            component_ref: Some(ComponentRef::from_component(new)),
            old_canonical_id: Some(old.canonical_id.clone()),
            name: new.name.clone(),
            old_version: old.version.clone(),
            new_version: new.version.clone(),
            ecosystem: new.ecosystem.as_ref().map(std::string::ToString::to_string),
            component_type: Some(resolved_component_type(new)),
            change_type: ChangeType::Modified,
            field_changes,
            cost,
            match_info: None,
        }
    }

    /// Create a component modification with match explanation
    pub fn modified_with_match(
        old: &Component,
        new: &Component,
        field_changes: Vec<FieldChange>,
        cost: u32,
        match_info: MatchInfo,
    ) -> Self {
        Self {
            id: new.canonical_id.to_string(),
            canonical_id: Some(new.canonical_id.clone()),
            component_ref: Some(ComponentRef::from_component(new)),
            old_canonical_id: Some(old.canonical_id.clone()),
            name: new.name.clone(),
            old_version: old.version.clone(),
            new_version: new.version.clone(),
            ecosystem: new.ecosystem.as_ref().map(std::string::ToString::to_string),
            component_type: Some(resolved_component_type(new)),
            change_type: ChangeType::Modified,
            field_changes,
            cost,
            match_info: Some(match_info),
        }
    }

    /// Add match information to an existing change
    #[must_use]
    pub fn with_match_info(mut self, match_info: MatchInfo) -> Self {
        self.match_info = Some(match_info);
        self
    }

    /// Get the typed canonical ID, falling back to parsing from string if needed
    #[must_use]
    pub fn get_canonical_id(&self) -> CanonicalId {
        self.canonical_id.clone().unwrap_or_else(|| {
            CanonicalId::from_name_version(
                &self.name,
                self.new_version.as_deref().or(self.old_version.as_deref()),
            )
        })
    }

    /// Get a `ComponentRef` for this change
    #[must_use]
    pub fn get_component_ref(&self) -> ComponentRef {
        self.component_ref.clone().unwrap_or_else(|| {
            ComponentRef::with_version(
                self.get_canonical_id(),
                &self.name,
                self.new_version
                    .clone()
                    .or_else(|| self.old_version.clone()),
            )
        })
    }
}

impl MatchInfo {
    /// Create from a `MatchExplanation`
    #[must_use]
    pub fn from_explanation(explanation: &crate::matching::MatchExplanation) -> Self {
        let method = format!("{:?}", explanation.tier);
        let ci = ConfidenceInterval::from_tier(explanation.score, &method);
        Self {
            score: explanation.score,
            method,
            reason: explanation.reason.clone(),
            score_breakdown: explanation
                .score_breakdown
                .iter()
                .map(|c| MatchScoreComponent {
                    name: c.name.clone(),
                    weight: c.weight,
                    raw_score: c.raw_score,
                    weighted_score: c.weighted_score,
                    description: c.description.clone(),
                })
                .collect(),
            normalizations: explanation.normalizations_applied.clone(),
            confidence_interval: Some(ci),
        }
    }

    /// Create a simple match info without detailed breakdown
    #[must_use]
    pub fn simple(score: f64, method: &str, reason: &str) -> Self {
        let ci = ConfidenceInterval::from_tier(score, method);
        Self {
            score,
            method: method.to_string(),
            reason: reason.to_string(),
            score_breakdown: Vec::new(),
            normalizations: Vec::new(),
            confidence_interval: Some(ci),
        }
    }

    /// Create a match info with a custom confidence interval
    #[must_use]
    pub const fn with_confidence_interval(mut self, ci: ConfidenceInterval) -> Self {
        self.confidence_interval = Some(ci);
        self
    }
}

/// Type of change
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum ChangeType {
    Added,
    Removed,
    Modified,
    Unchanged,
}

/// Individual field change
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FieldChange {
    pub field: String,
    pub old_value: Option<String>,
    pub new_value: Option<String>,
}

/// Whether a document-metadata field was added, removed, or modified.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum MetadataChangeKind {
    /// Field gained a value (old absent, new present).
    Added,
    /// Field lost a value (old present, new absent).
    Removed,
    /// Field's value changed (both present, different).
    Modified,
}

impl std::fmt::Display for MetadataChangeKind {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let s = match self {
            Self::Added => "added",
            Self::Removed => "removed",
            Self::Modified => "modified",
        };
        f.write_str(s)
    }
}

/// A document-level metadata change between two SBOMs.
///
/// Surfaces changes that are invisible in the component/dependency/vulnerability
/// passes: author or tool churn, timestamp updates, spec-version upgrades
/// (e.g. CycloneDX 1.5 -> 1.7), lifecycle-phase transitions, signature presence
/// or algorithm changes, and document- or primary-component version bumps. This
/// is the cross-cutting metadata signal the BSI gap analysis flagged as missing.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MetadataChange {
    /// Stable field key (e.g. `name`, `spec_version`, `created`, `creator.tool`,
    /// `lifecycle_phase`, `signature.algorithm`, `primary_component_version`).
    pub field: String,
    /// Value in the old SBOM (`None` when the field was absent / added).
    pub old_value: Option<String>,
    /// Value in the new SBOM (`None` when the field was removed).
    pub new_value: Option<String>,
    /// Whether the field was added, removed, or modified.
    pub kind: MetadataChangeKind,
}

impl MetadataChange {
    /// Build a metadata change from a field key and the two optional values,
    /// inferring the [`MetadataChangeKind`] from presence. Returns `None` when
    /// the values are equal (no change to report).
    #[must_use]
    pub fn from_values(
        field: impl Into<String>,
        old_value: Option<String>,
        new_value: Option<String>,
    ) -> Option<Self> {
        if old_value == new_value {
            return None;
        }
        let kind = match (&old_value, &new_value) {
            (None, Some(_)) => MetadataChangeKind::Added,
            (Some(_), None) => MetadataChangeKind::Removed,
            _ => MetadataChangeKind::Modified,
        };
        Some(Self {
            field: field.into(),
            old_value,
            new_value,
            kind,
        })
    }
}

/// Dependency change information
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DependencyChange {
    /// Source component
    pub from: String,
    /// Target component
    pub to: String,
    /// Relationship type
    pub relationship: String,
    /// Dependency scope
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scope: Option<String>,
    /// Change type
    pub change_type: ChangeType,
}

impl DependencyChange {
    #[must_use]
    pub fn added(edge: &DependencyEdge) -> Self {
        Self {
            from: edge.from.to_string(),
            to: edge.to.to_string(),
            relationship: edge.relationship.to_string(),
            scope: edge.scope.as_ref().map(std::string::ToString::to_string),
            change_type: ChangeType::Added,
        }
    }

    #[must_use]
    pub fn removed(edge: &DependencyEdge) -> Self {
        Self {
            from: edge.from.to_string(),
            to: edge.to.to_string(),
            relationship: edge.relationship.to_string(),
            scope: edge.scope.as_ref().map(std::string::ToString::to_string),
            change_type: ChangeType::Removed,
        }
    }
}

/// License change information
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct LicenseChanges {
    /// Newly introduced licenses
    pub new_licenses: Vec<LicenseChange>,
    /// Removed licenses
    pub removed_licenses: Vec<LicenseChange>,
    /// License conflicts
    pub conflicts: Vec<LicenseConflict>,
    /// Components with license changes
    pub component_changes: Vec<ComponentLicenseChange>,
}

/// Individual license change
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LicenseChange {
    /// License expression
    pub license: String,
    /// Components using this license
    pub components: Vec<String>,
    /// License family
    pub family: String,
}

/// License conflict information
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LicenseConflict {
    pub license_a: String,
    pub license_b: String,
    pub component: String,
    pub description: String,
}

/// Component-level license change
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ComponentLicenseChange {
    pub component_id: String,
    pub component_name: String,
    pub old_licenses: Vec<String>,
    pub new_licenses: Vec<String>,
}

/// A VEX state change for a vulnerability between old and new SBOMs.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct VexStatusChange {
    /// Vulnerability ID (e.g., "CVE-2023-1234")
    pub vuln_id: String,
    /// Affected component name
    pub component_name: String,
    /// Old VEX state (None = no VEX in old SBOM)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub old_state: Option<crate::model::VexState>,
    /// New VEX state (None = no VEX in new SBOM)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub new_state: Option<crate::model::VexState>,
}

/// Vulnerability change information
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct VulnerabilityChanges {
    /// Newly introduced vulnerabilities
    pub introduced: Vec<VulnerabilityDetail>,
    /// Resolved vulnerabilities
    pub resolved: Vec<VulnerabilityDetail>,
    /// Persistent vulnerabilities (present in both)
    pub persistent: Vec<VulnerabilityDetail>,
    /// VEX state transitions detected across persistent vulnerabilities
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub vex_changes: Vec<VexStatusChange>,
}

impl VulnerabilityChanges {
    /// Count vulnerabilities by severity
    #[must_use]
    pub fn introduced_by_severity(&self) -> HashMap<String, usize> {
        // Pre-allocate for typical severity levels (critical, high, medium, low, unknown)
        let mut counts = HashMap::with_capacity(5);
        for vuln in &self.introduced {
            *counts.entry(vuln.severity.clone()).or_insert(0) += 1;
        }
        counts
    }

    /// Get critical and high severity introduced vulnerabilities
    #[must_use]
    pub fn critical_and_high_introduced(&self) -> Vec<&VulnerabilityDetail> {
        self.introduced
            .iter()
            .filter(|v| v.severity == "Critical" || v.severity == "High")
            .collect()
    }

    /// Compute VEX coverage summary across all vulnerability categories.
    pub fn vex_summary(&self) -> VexCoverageSummary {
        let all_vulns: Vec<&VulnerabilityDetail> = self
            .introduced
            .iter()
            .chain(&self.resolved)
            .chain(&self.persistent)
            .collect();

        let total = all_vulns.len();
        let mut with_vex = 0;
        let mut by_state: HashMap<crate::model::VexState, usize> = HashMap::with_capacity(4);
        let mut actionable = 0;

        for vuln in &all_vulns {
            if let Some(ref state) = vuln.vex_state {
                with_vex += 1;
                *by_state.entry(state.clone()).or_insert(0) += 1;
            }
            if vuln.is_vex_actionable() {
                actionable += 1;
            }
        }

        // Vulns without VEX (gaps) — both introduced and persistent are flagged
        let introduced_without_vex = self
            .introduced
            .iter()
            .filter(|v| v.vex_state.is_none())
            .count();

        let persistent_without_vex = self
            .persistent
            .iter()
            .filter(|v| v.vex_state.is_none())
            .count();

        VexCoverageSummary {
            total_vulns: total,
            with_vex,
            without_vex: total - with_vex,
            actionable,
            coverage_pct: if total > 0 {
                (with_vex as f64 / total as f64) * 100.0
            } else {
                100.0
            },
            by_state,
            introduced_without_vex,
            persistent_without_vex,
        }
    }
}

/// VEX coverage summary for vulnerability changes.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[must_use]
pub struct VexCoverageSummary {
    /// Total vulnerabilities across all categories
    pub total_vulns: usize,
    /// Vulnerabilities with a VEX statement
    pub with_vex: usize,
    /// Vulnerabilities without a VEX statement
    pub without_vex: usize,
    /// Vulnerabilities that are VEX-actionable (no NotAffected/Fixed)
    pub actionable: usize,
    /// VEX coverage percentage (0.0-100.0)
    pub coverage_pct: f64,
    /// Breakdown by VEX state
    pub by_state: HashMap<crate::model::VexState, usize>,
    /// Introduced vulnerabilities without VEX (gaps requiring attention)
    pub introduced_without_vex: usize,
    /// Persistent vulnerabilities without VEX (ongoing gaps)
    pub persistent_without_vex: usize,
}

/// SLA status for vulnerability remediation tracking
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum SlaStatus {
    /// Past SLA deadline by N days
    Overdue(i64),
    /// Due within 3 days (N days remaining)
    DueSoon(i64),
    /// Within SLA window (N days remaining)
    OnTrack(i64),
    /// No SLA deadline applicable
    NoDueDate,
}

impl SlaStatus {
    /// Format for display (e.g., "3d late", "2d left", "45d old")
    #[must_use]
    pub fn display(&self, days_since_published: Option<i64>) -> String {
        match self {
            Self::Overdue(days) => format!("{days}d late"),
            Self::DueSoon(days) | Self::OnTrack(days) => format!("{days}d left"),
            Self::NoDueDate => {
                days_since_published.map_or_else(|| "-".to_string(), |age| format!("{age}d old"))
            }
        }
    }

    /// Check if this is an overdue status
    #[must_use]
    pub const fn is_overdue(&self) -> bool {
        matches!(self, Self::Overdue(_))
    }

    /// Check if this is due soon (approaching deadline)
    #[must_use]
    pub const fn is_due_soon(&self) -> bool {
        matches!(self, Self::DueSoon(_))
    }
}

/// Detailed vulnerability information
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VulnerabilityDetail {
    /// Vulnerability ID
    pub id: String,
    /// Source database
    pub source: String,
    /// Severity level
    pub severity: String,
    /// CVSS score
    pub cvss_score: Option<f32>,
    /// Affected component ID (string for serialization)
    pub component_id: String,
    /// Typed canonical ID for the component (skipped in JSON for backward compat)
    #[serde(skip)]
    pub component_canonical_id: Option<CanonicalId>,
    /// Component reference with ID and name together
    #[serde(skip)]
    pub component_ref: Option<ComponentRef>,
    /// Affected component name
    pub component_name: String,
    /// Affected version
    pub version: Option<String>,
    /// CWE identifiers
    pub cwes: Vec<String>,
    /// Description
    pub description: Option<String>,
    /// Remediation info
    pub remediation: Option<String>,
    /// Whether this vulnerability is in CISA's Known Exploited Vulnerabilities catalog
    #[serde(default)]
    pub is_kev: bool,
    /// Whether the KEV entry is known to be used in ransomware campaigns
    #[serde(default)]
    pub is_ransomware: bool,
    /// FIRST EPSS exploit-probability score (0.0 - 1.0), if enriched
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub epss_score: Option<f64>,
    /// Dependency depth (1 = direct, 2+ = transitive, None = unknown)
    #[serde(default)]
    pub component_depth: Option<u32>,
    /// Date vulnerability was published (ISO 8601)
    #[serde(default)]
    pub published_date: Option<String>,
    /// KEV due date (CISA mandated remediation deadline)
    #[serde(default)]
    pub kev_due_date: Option<String>,
    /// Days since published (positive = past)
    #[serde(default)]
    pub days_since_published: Option<i64>,
    /// Days until KEV due date (negative = overdue)
    #[serde(default)]
    pub days_until_due: Option<i64>,
    /// VEX state for this vulnerability's component (if available)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub vex_state: Option<crate::model::VexState>,
    /// VEX justification (from per-vuln or component-level VEX)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub vex_justification: Option<crate::model::VexJustification>,
    /// VEX impact statement (from per-vuln or component-level VEX)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub vex_impact_statement: Option<String>,
}

impl VulnerabilityDetail {
    /// Whether this vulnerability is VEX-actionable (not resolved by vendor analysis).
    ///
    /// Returns `true` if the VEX state is `Affected`, `UnderInvestigation`, or absent.
    /// Returns `false` if the VEX state is `NotAffected` or `Fixed`.
    #[must_use]
    pub const fn is_vex_actionable(&self) -> bool {
        !matches!(
            self.vex_state,
            Some(crate::model::VexState::NotAffected | crate::model::VexState::Fixed)
        )
    }

    /// Create from a vulnerability reference and component
    pub fn from_ref(vuln: &VulnerabilityRef, component: &Component) -> Self {
        // Calculate days since published (published is DateTime<Utc>)
        let days_since_published = vuln.published.map(|dt| {
            let today = chrono::Utc::now().date_naive();
            (today - dt.date_naive()).num_days()
        });

        // Format published date as string for serialization
        let published_date = vuln.published.map(|dt| dt.format("%Y-%m-%d").to_string());

        // Get KEV info if present. days_until_due is DATE-granular
        // (matching days_since_published above and refresh_day_counts):
        // KevInfo::days_until_due() truncates a DateTime delta, which is one
        // day lower for midnight-UTC due dates at any time past 00:00 — a
        // fresh value the refresher would immediately "correct", defeating
        // the cache's no-clone fast path and making hit/miss disagree.
        let (kev_due_date, days_until_due) = vuln.kev_info.as_ref().map_or((None, None), |kev| {
            let today = chrono::Utc::now().date_naive();
            (
                Some(kev.due_date.format("%Y-%m-%d").to_string()),
                Some((kev.due_date.date_naive() - today).num_days()),
            )
        });

        Self {
            id: vuln.id.clone(),
            source: vuln.source.to_string(),
            severity: vuln
                .severity
                .as_ref()
                .map_or_else(|| "Unknown".to_string(), std::string::ToString::to_string),
            cvss_score: vuln.max_cvss_score(),
            component_id: component.canonical_id.to_string(),
            component_canonical_id: Some(component.canonical_id.clone()),
            component_ref: Some(ComponentRef::from_component(component)),
            component_name: component.name.clone(),
            version: component.version.clone(),
            cwes: vuln.cwes.clone(),
            description: vuln.description.clone(),
            remediation: vuln.remediation.as_ref().map(|r| {
                format!(
                    "{}: {}",
                    r.remediation_type,
                    r.description.as_deref().unwrap_or("")
                )
            }),
            is_kev: vuln.is_kev,
            is_ransomware: vuln.is_ransomware_related(),
            epss_score: vuln.epss_score,
            component_depth: None,
            published_date,
            kev_due_date,
            days_since_published,
            days_until_due,
            vex_state: {
                let vex_source = vuln.vex_status.as_ref().or(component.vex_status.as_ref());
                vex_source.map(|v| v.status.clone())
            },
            vex_justification: {
                let vex_source = vuln.vex_status.as_ref().or(component.vex_status.as_ref());
                vex_source.and_then(|v| v.justification.clone())
            },
            vex_impact_statement: {
                let vex_source = vuln.vex_status.as_ref().or(component.vex_status.as_ref());
                vex_source.and_then(|v| v.impact_statement.clone())
            },
        }
    }

    /// Recompute the day-count fields from the stored dates.
    ///
    /// `days_since_published` and `days_until_due` embed the date they were
    /// computed on; a cached result served across midnight carries stale
    /// counts. Returns true if anything changed. `days_until_due` follows
    /// `KevInfo::days_until_due` semantics (whole days, date-granular here
    /// since only the date string is stored).
    pub(crate) fn refresh_day_counts(&mut self, today: chrono::NaiveDate) -> bool {
        let mut changed = false;
        if let Some(published) = self.published_date.as_deref()
            && let Ok(date) = chrono::NaiveDate::parse_from_str(published, "%Y-%m-%d")
        {
            let days = (today - date).num_days();
            if self.days_since_published != Some(days) {
                self.days_since_published = Some(days);
                changed = true;
            }
        }
        if let Some(due) = self.kev_due_date.as_deref()
            && let Ok(date) = chrono::NaiveDate::parse_from_str(due, "%Y-%m-%d")
        {
            let days = (date - today).num_days();
            if self.days_until_due != Some(days) {
                self.days_until_due = Some(days);
                changed = true;
            }
        }
        changed
    }

    /// Create from a vulnerability reference and component with known depth
    #[must_use]
    pub fn from_ref_with_depth(
        vuln: &VulnerabilityRef,
        component: &Component,
        depth: Option<u32>,
    ) -> Self {
        let mut detail = Self::from_ref(vuln, component);
        detail.component_depth = depth;
        detail
    }

    /// Calculate SLA status based on KEV due date or severity-based policy
    ///
    /// Priority order:
    /// 1. KEV due date (CISA mandated deadline)
    /// 2. Severity-based SLA (Critical=1d, High=7d, Medium=30d, Low=90d)
    #[must_use]
    pub fn sla_status(&self) -> SlaStatus {
        // KEV due date takes priority
        if let Some(days) = self.days_until_due {
            if days < 0 {
                return SlaStatus::Overdue(-days);
            } else if days <= 3 {
                return SlaStatus::DueSoon(days);
            }
            return SlaStatus::OnTrack(days);
        }

        // Fall back to severity-based SLA
        if let Some(age_days) = self.days_since_published {
            let sla_days = match self.severity.to_lowercase().as_str() {
                "critical" => 1,
                "high" => 7,
                "medium" => 30,
                "low" => 90,
                _ => return SlaStatus::NoDueDate,
            };
            let remaining = sla_days - age_days;
            if remaining < 0 {
                return SlaStatus::Overdue(-remaining);
            } else if remaining <= 3 {
                return SlaStatus::DueSoon(remaining);
            }
            return SlaStatus::OnTrack(remaining);
        }

        SlaStatus::NoDueDate
    }

    /// Get the typed component canonical ID
    #[must_use]
    pub fn get_component_id(&self) -> CanonicalId {
        self.component_canonical_id.clone().unwrap_or_else(|| {
            CanonicalId::from_name_version(&self.component_name, self.version.as_deref())
        })
    }

    /// Get a `ComponentRef` for the affected component
    #[must_use]
    pub fn get_component_ref(&self) -> ComponentRef {
        self.component_ref.clone().unwrap_or_else(|| {
            ComponentRef::with_version(
                self.get_component_id(),
                &self.component_name,
                self.version.clone(),
            )
        })
    }
}

// ============================================================================
// Graph-Aware Diffing Types
// ============================================================================

/// Represents a structural change in the dependency graph
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DependencyGraphChange {
    /// The component involved in the change
    pub component_id: CanonicalId,
    /// Human-readable component name
    pub component_name: String,
    /// The type of structural change
    pub change: DependencyChangeType,
    /// Assessed impact of this change
    pub impact: GraphChangeImpact,
}

/// Types of dependency graph structural changes
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub enum DependencyChangeType {
    /// A new dependency link was added
    DependencyAdded {
        dependency_id: CanonicalId,
        dependency_name: String,
    },

    /// A dependency link was removed
    DependencyRemoved {
        dependency_id: CanonicalId,
        dependency_name: String,
    },

    /// Dependency relationship or scope changed (same endpoints, different attributes)
    RelationshipChanged {
        dependency_id: CanonicalId,
        dependency_name: String,
        old_relationship: String,
        new_relationship: String,
        old_scope: Option<String>,
        new_scope: Option<String>,
    },

    /// A dependency was reparented (had exactly one parent in both, but different)
    Reparented {
        dependency_id: CanonicalId,
        dependency_name: String,
        old_parent_id: CanonicalId,
        old_parent_name: String,
        new_parent_id: CanonicalId,
        new_parent_name: String,
    },

    /// Dependency depth changed (e.g., transitive became direct)
    DepthChanged {
        old_depth: u32, // 1 = root, 2 = direct, 3+ = transitive
        new_depth: u32,
    },
}

impl DependencyChangeType {
    /// Get a short description of the change type
    #[must_use]
    pub const fn kind(&self) -> &'static str {
        match self {
            Self::DependencyAdded { .. } => "added",
            Self::DependencyRemoved { .. } => "removed",
            Self::RelationshipChanged { .. } => "relationship_changed",
            Self::Reparented { .. } => "reparented",
            Self::DepthChanged { .. } => "depth_changed",
        }
    }
}

/// Impact level of a graph change
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum GraphChangeImpact {
    /// Internal reorganization, no functional change
    Low,
    /// Depth or type change, may affect build/runtime
    Medium,
    /// Security-relevant component relationship changed
    High,
    /// Vulnerable component promoted to direct dependency
    Critical,
}

impl GraphChangeImpact {
    #[must_use]
    pub const fn as_str(&self) -> &'static str {
        match self {
            Self::Low => "low",
            Self::Medium => "medium",
            Self::High => "high",
            Self::Critical => "critical",
        }
    }

    /// Parse from a string label. Returns Low for unrecognized values.
    #[must_use]
    pub fn from_label(s: &str) -> Self {
        match s.to_lowercase().as_str() {
            "critical" => Self::Critical,
            "high" => Self::High,
            "medium" => Self::Medium,
            _ => Self::Low,
        }
    }
}

impl std::fmt::Display for GraphChangeImpact {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.as_str())
    }
}

/// Summary statistics for graph changes
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct GraphChangeSummary {
    pub total_changes: usize,
    pub dependencies_added: usize,
    pub dependencies_removed: usize,
    pub relationship_changed: usize,
    pub reparented: usize,
    pub depth_changed: usize,
    pub by_impact: GraphChangesByImpact,
}

impl GraphChangeSummary {
    /// Build summary from a list of changes
    #[must_use]
    pub fn from_changes(changes: &[DependencyGraphChange]) -> Self {
        let mut summary = Self {
            total_changes: changes.len(),
            ..Default::default()
        };

        for change in changes {
            match &change.change {
                DependencyChangeType::DependencyAdded { .. } => summary.dependencies_added += 1,
                DependencyChangeType::DependencyRemoved { .. } => summary.dependencies_removed += 1,
                DependencyChangeType::RelationshipChanged { .. } => {
                    summary.relationship_changed += 1;
                }
                DependencyChangeType::Reparented { .. } => summary.reparented += 1,
                DependencyChangeType::DepthChanged { .. } => summary.depth_changed += 1,
            }

            match change.impact {
                GraphChangeImpact::Low => summary.by_impact.low += 1,
                GraphChangeImpact::Medium => summary.by_impact.medium += 1,
                GraphChangeImpact::High => summary.by_impact.high += 1,
                GraphChangeImpact::Critical => summary.by_impact.critical += 1,
            }
        }

        summary
    }
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct GraphChangesByImpact {
    pub low: usize,
    pub medium: usize,
    pub high: usize,
    pub critical: usize,
}

#[cfg(test)]
mod quality_delta_tests {
    use super::QualityDelta;
    use crate::model::{
        AlgorithmProperties, Component, ComponentType, CryptoAssetType, CryptoPrimitive,
        CryptoProperties, NormalizedSbom,
    };
    use crate::quality::{CryptographyMetrics, QualityScorer, ScoringProfile};

    /// A small CBOM: one crypto algorithm asset with the given family and
    /// NIST quantum security level.
    fn cbom_sbom(family: &str, quantum_level: u8) -> NormalizedSbom {
        let mut sbom = NormalizedSbom::default();
        let mut comp = Component::new(family.to_string(), format!("crypto/{family}"));
        comp.component_type = ComponentType::Cryptographic;
        comp.crypto_properties = Some(
            CryptoProperties::new(CryptoAssetType::Algorithm).with_algorithm_properties(
                AlgorithmProperties::new(CryptoPrimitive::Hash)
                    .with_algorithm_family(family.to_string())
                    .with_nist_quantum_security_level(quantum_level),
            ),
        );
        comp.calculate_content_hash();
        sbom.add_component(comp);
        sbom
    }

    /// A plain SBOM with one library component.
    fn plain_sbom(version: &str) -> NormalizedSbom {
        let mut sbom = NormalizedSbom::default();
        let mut comp = Component::new("lodash".to_string(), format!("pkg:npm/lodash@{version}"));
        comp.version = Some(version.to_string());
        comp.calculate_content_hash();
        sbom.add_component(comp);
        sbom
    }

    /// CBOM-scored pairs must carry the crypto category names the CBOM
    /// scorer's arithmetic actually used — not the generic 8 (whose scores
    /// never contributed to either headline number).
    #[test]
    fn cbom_pair_uses_crypto_category_names() {
        let scorer = QualityScorer::new(ScoringProfile::Cbom);
        let old_report = scorer.score(&cbom_sbom("SHA-2", 1));
        let new_report = scorer.score(&cbom_sbom("MD5", 0));

        let delta = QualityDelta::from_reports(&old_report, &new_report);

        let names: Vec<&str> = delta
            .category_deltas
            .iter()
            .map(|d| d.category.as_str())
            .collect();
        assert_eq!(
            names,
            CryptographyMetrics::cbom_category_names().to_vec(),
            "CBOM delta must use the scorer's crypto category names"
        );
        // Regressions/improvements derive from the same rows, so they can
        // only ever name CBOM categories here.
        for name in delta.regressions.iter().chain(delta.improvements.iter()) {
            assert!(
                CryptographyMetrics::cbom_category_names().contains(&name.as_str()),
                "unexpected non-CBOM category `{name}` in a CBOM delta"
            );
        }
        // The strong->weak hash family swap must actually surface as an
        // Algo Strength regression, not hide under a generic name.
        assert!(
            delta.regressions.iter().any(|r| r == "Algo Strength"),
            "expected an Algo Strength regression, got {:?}",
            delta.regressions
        );
    }

    /// Standard-profile pairs keep the generic category names (backward
    /// compatible: this is the only shape existing JSON consumers have seen).
    #[test]
    fn standard_pair_keeps_generic_category_names() {
        let scorer = QualityScorer::new(ScoringProfile::Standard);
        let old_report = scorer.score(&plain_sbom("1.0.0"));
        let new_report = scorer.score(&plain_sbom("2.0.0"));

        let delta = QualityDelta::from_reports(&old_report, &new_report);

        let names: Vec<&str> = delta
            .category_deltas
            .iter()
            .map(|d| d.category.as_str())
            .collect();
        for expected in [
            "Completeness",
            "Identifiers",
            "Licenses",
            "Dependencies",
            "Integrity",
            "Provenance",
        ] {
            assert!(
                names.contains(&expected),
                "missing `{expected}` in {names:?}"
            );
        }
        assert!(
            !names.iter().any(|n| n.starts_with("Crypto")),
            "generic delta must not carry CBOM names: {names:?}"
        );
    }

    /// A mixed pair (only one side scored by the CBOM substitution) falls
    /// back to the generic categories: per-category deltas need the same
    /// scale on both sides.
    #[test]
    fn mixed_profile_pair_falls_back_to_generic_names() {
        let old_report = QualityScorer::new(ScoringProfile::Standard).score(&plain_sbom("1.0.0"));
        let new_report = QualityScorer::new(ScoringProfile::Cbom).score(&cbom_sbom("SHA-2", 1));

        let delta = QualityDelta::from_reports(&old_report, &new_report);

        assert!(
            delta
                .category_deltas
                .iter()
                .any(|d| d.category == "Completeness"),
            "mixed pair must keep generic categories"
        );
    }
}

#[cfg(test)]
mod ml_metric_direction_tests {
    use super::ml_metric_higher_is_better;

    /// Locks the '@slice' strip and the table now shared by engine and TUI.
    #[test]
    fn ml_metric_direction_table() {
        assert_eq!(ml_metric_higher_is_better("accuracy"), Some(true));
        assert_eq!(
            ml_metric_higher_is_better("accuracy@validation"),
            Some(true)
        );
        assert_eq!(ml_metric_higher_is_better("loss"), Some(false));
        assert_eq!(ml_metric_higher_is_better("latency_ms"), Some(false));
        assert_eq!(ml_metric_higher_is_better("custom_metric"), None);
    }
}