// -----------------------------------------------------------------------------
// ISbomRegistryRepository.cs
// Sprint: SPRINT_8200_0013_0003_SCAN_sbom_intersection_scoring
// Task: SBOM-8200-001
// Description: Repository interface for SBOM registry persistence
// -----------------------------------------------------------------------------

using StellaOps.Concelier.SbomIntegration.Models;

namespace StellaOps.Concelier.SbomIntegration;

/// <summary>
/// Repository for SBOM registration persistence.
/// </summary>
public interface ISbomRegistryRepository
{
    #region Registration CRUD

    /// <summary>
    /// Saves or updates an SBOM registration.
    /// </summary>
    Task SaveAsync(SbomRegistration registration, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets an SBOM registration by digest.
    /// </summary>
    Task<SbomRegistration?> GetByDigestAsync(string digest, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets an SBOM registration by ID.
    /// </summary>
    Task<SbomRegistration?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);

    /// <summary>
    /// Lists registrations with pagination.
    /// </summary>
    Task<IReadOnlyList<SbomRegistration>> ListAsync(
        int offset,
        int limit,
        string? tenantId = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Deletes an SBOM registration by digest.
    /// </summary>
    Task DeleteAsync(string digest, CancellationToken cancellationToken = default);

    /// <summary>
    /// Counts total registrations.
    /// </summary>
    Task<long> CountAsync(string? tenantId = null, CancellationToken cancellationToken = default);

    #endregion

    #region Match CRUD

    /// <summary>
    /// Saves SBOM matches (replaces existing).
    /// </summary>
    Task SaveMatchesAsync(
        Guid sbomId,
        IEnumerable<SbomAdvisoryMatch> matches,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets matches for an SBOM.
    /// </summary>
    Task<IReadOnlyList<SbomAdvisoryMatch>> GetMatchesAsync(
        string digest,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets matches for a canonical advisory.
    /// </summary>
    Task<IReadOnlyList<SbomAdvisoryMatch>> GetMatchesByCanonicalAsync(
        Guid canonicalId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Deletes all matches for an SBOM.
    /// </summary>
    Task DeleteMatchesAsync(Guid sbomId, CancellationToken cancellationToken = default);

    #endregion

    #region Statistics

    /// <summary>
    /// Gets registry statistics.
    /// </summary>
    Task<SbomRegistryStats> GetStatsAsync(
        string? tenantId = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Updates affected count for an SBOM.
    /// </summary>
    Task UpdateAffectedCountAsync(
        string digest,
        int affectedCount,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Updates last matched timestamp.
    /// </summary>
    Task UpdateLastMatchedAsync(
        string digest,
        DateTimeOffset lastMatched,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Updates the PURL list for an SBOM.
    /// </summary>
    Task UpdatePurlsAsync(
        string digest,
        IReadOnlyList<string> purls,
        CancellationToken cancellationToken = default);

    #endregion
}