using StellaOps.Scanner.WebService.Domain;

namespace StellaOps.Scanner.WebService.Services;

/// <summary>
/// Explanation reason with code and impact.
/// </summary>
public sealed record ExplanationReason(
    string Code,
    string Description,
    double? Impact = null);

/// <summary>
/// Static analysis evidence.
/// </summary>
public sealed record StaticAnalysisEvidence(
    string? CallgraphDigest = null,
    int? PathLength = null,
    IReadOnlyList<string>? EdgeTypes = null);

/// <summary>
/// Runtime evidence.
/// </summary>
public sealed record RuntimeEvidence(
    bool Observed,
    int HitCount = 0,
    DateTimeOffset? LastObserved = null);

/// <summary>
/// Policy evaluation result.
/// </summary>
public sealed record PolicyEvaluationEvidence(
    string? PolicyDigest = null,
    string? Verdict = null,
    string? VerdictReason = null);

/// <summary>
/// Evidence chain for explanation.
/// </summary>
public sealed record EvidenceChain(
    StaticAnalysisEvidence? StaticAnalysis = null,
    RuntimeEvidence? RuntimeEvidence = null,
    PolicyEvaluationEvidence? PolicyEvaluation = null);

/// <summary>
/// Full reachability explanation.
/// </summary>
public sealed record ReachabilityExplanation(
    string CveId,
    string Purl,
    string Status,
    double Confidence,
    string? LatticeState = null,
    IReadOnlyList<string>? PathWitness = null,
    IReadOnlyList<ExplanationReason>? Why = null,
    EvidenceChain? Evidence = null,
    string? SpineId = null);

/// <summary>
/// Service for explaining reachability decisions.
/// </summary>
public interface IReachabilityExplainService
{
    /// <summary>
    /// Explains why a CVE affects a component.
    /// </summary>
    Task<ReachabilityExplanation?> ExplainAsync(
        ScanId scanId,
        string cveId,
        string purl,
        CancellationToken cancellationToken = default);
}