namespace StellaOps.AdvisoryAI.Remediation;

/// <summary>
/// Version resolution result.
/// </summary>
public sealed record VersionResolutionResult
{
    /// <summary>
    /// Current version.
    /// </summary>
    public required string CurrentVersion { get; init; }

    /// <summary>
    /// Recommended upgrade version.
    /// </summary>
    public required string RecommendedVersion { get; init; }

    /// <summary>
    /// Latest available version.
    /// </summary>
    public required string LatestVersion { get; init; }

    /// <summary>
    /// Whether upgrade path is safe.
    /// </summary>
    public required bool IsSafe { get; init; }

    /// <summary>
    /// Breaking changes detected.
    /// </summary>
    public required IReadOnlyList<string> BreakingChanges { get; init; }

    /// <summary>
    /// Vulnerabilities fixed by upgrade.
    /// </summary>
    public required IReadOnlyList<string> VulnerabilitiesFixed { get; init; }

    /// <summary>
    /// New vulnerabilities introduced (rare but possible).
    /// </summary>
    public required IReadOnlyList<string> NewVulnerabilities { get; init; }

    /// <summary>
    /// Upgrade type (patch, minor, major).
    /// </summary>
    public required string UpgradeType { get; init; }

    /// <summary>
    /// Confidence in the resolution (0.0-1.0).
    /// </summary>
    public required double Confidence { get; init; }
}

/// <summary>
/// Service for resolving package versions and validating upgrade paths.
/// Sprint: SPRINT_20251226_016_AI_remedy_autopilot
/// Task: REMEDY-04
/// </summary>
public interface IPackageVersionResolver
{
    /// <summary>
    /// Resolve upgrade path for a package.
    /// </summary>
    /// <param name="purl">Package URL.</param>
    /// <param name="targetVulnerability">Vulnerability to fix.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Version resolution result.</returns>
    Task<VersionResolutionResult> ResolveUpgradePathAsync(
        string purl,
        string targetVulnerability,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Check if a specific version is available.
    /// </summary>
    /// <param name="purl">Package URL with version.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if version exists.</returns>
    Task<bool> IsVersionAvailableAsync(string purl, CancellationToken cancellationToken = default);

    /// <summary>
    /// Get all available versions for a package.
    /// </summary>
    /// <param name="purl">Package URL (without version).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of available versions.</returns>
    Task<IReadOnlyList<string>> GetAvailableVersionsAsync(string purl, CancellationToken cancellationToken = default);
}