// -----------------------------------------------------------------------------
// IGatingReasonService.cs
// Sprint: SPRINT_9200_0001_0001_SCANNER_gated_triage_contracts
// Description: Service interface for computing why findings are gated.
// -----------------------------------------------------------------------------

using StellaOps.Scanner.WebService.Contracts;

namespace StellaOps.Scanner.WebService.Services;

/// <summary>
/// Computes gating reasons for findings in the quiet triage model.
/// </summary>
public interface IGatingReasonService
{
    /// <summary>
    /// Computes the gating status for a single finding.
    /// </summary>
    /// <param name="findingId">Finding identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Gating status or null if finding not found.</returns>
    Task<FindingGatingStatusDto?> GetGatingStatusAsync(
        string findingId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Computes gating status for multiple findings.
    /// </summary>
    /// <param name="findingIds">Finding identifiers.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Gating status for each finding.</returns>
    Task<IReadOnlyList<FindingGatingStatusDto>> GetBulkGatingStatusAsync(
        IReadOnlyList<string> findingIds,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Computes the gated buckets summary for a scan.
    /// </summary>
    /// <param name="scanId">Scan identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Summary of gated buckets or null if scan not found.</returns>
    Task<GatedBucketsSummaryDto?> GetGatedBucketsSummaryAsync(
        string scanId,
        CancellationToken cancellationToken = default);
}