// SPDX-License-Identifier: BUSL-1.1
// Sprint: SPRINT_4000_0002_0001
// Task: T1 - Extend Findings API Response with version comparison metadata

using System.Collections.Immutable;
using System.Text.Json.Serialization;

namespace StellaOps.Scanner.Evidence.Models;

/// <summary>
/// Evidence of version comparison used to determine vulnerability status.
/// Provides explainability for backport detection logic.
/// </summary>
public sealed record VersionComparisonEvidence
{
    /// <summary>
    /// Comparator algorithm used (rpm-evr, dpkg, apk, semver).
    /// </summary>
    [JsonPropertyName("comparator")]
    public required string Comparator { get; init; }

    /// <summary>
    /// Installed version in native format.
    /// </summary>
    [JsonPropertyName("installedVersion")]
    public required string InstalledVersion { get; init; }

    /// <summary>
    /// Fixed version threshold from advisory.
    /// </summary>
    [JsonPropertyName("fixedVersion")]
    public required string FixedVersion { get; init; }

    /// <summary>
    /// Whether the installed version is >= fixed.
    /// </summary>
    [JsonPropertyName("isFixed")]
    public required bool IsFixed { get; init; }

    /// <summary>
    /// Human-readable proof lines showing comparison steps.
    /// </summary>
    [JsonPropertyName("proofLines")]
    public ImmutableArray<string> ProofLines { get; init; } = [];

    /// <summary>
    /// Advisory source (DSA-1234, RHSA-2025:1234, USN-1234-1).
    /// </summary>
    [JsonPropertyName("advisorySource")]
    public string? AdvisorySource { get; init; }

    /// <summary>
    /// Creates VersionComparisonEvidence from a version comparison result.
    /// </summary>
    /// <param name="comparator">The comparator type identifier.</param>
    /// <param name="installedVersion">The installed version string.</param>
    /// <param name="fixedVersion">The fixed version threshold.</param>
    /// <param name="comparisonResult">The comparison result (negative if installed < fixed).</param>
    /// <param name="proofLines">Human-readable comparison steps.</param>
    /// <param name="advisorySource">Optional advisory identifier.</param>
    public static VersionComparisonEvidence Create(
        string comparator,
        string installedVersion,
        string fixedVersion,
        int comparisonResult,
        ImmutableArray<string> proofLines,
        string? advisorySource = null)
    {
        return new VersionComparisonEvidence
        {
            Comparator = comparator,
            InstalledVersion = installedVersion,
            FixedVersion = fixedVersion,
            IsFixed = comparisonResult >= 0, // installed >= fixed means fixed
            ProofLines = proofLines,
            AdvisorySource = advisorySource
        };
    }
}