namespace StellaOps.Feedser.BinaryAnalysis;

using StellaOps.Feedser.BinaryAnalysis.Models;

/// <summary>
/// Interface for extracting binary fingerprints from compiled artifacts.
/// </summary>
public interface IBinaryFingerprinter
{
    /// <summary>
    /// Fingerprinting method this implementation provides.
    /// </summary>
    FingerprintMethod Method { get; }

    /// <summary>
    /// Extract fingerprint from binary file.
    /// </summary>
    /// <param name="binaryPath">Path to binary file.</param>
    /// <param name="cveId">Associated CVE ID.</param>
    /// <param name="targetFunction">Optional function name to fingerprint.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Binary fingerprint.</returns>
    Task<BinaryFingerprint> ExtractAsync(
        string binaryPath,
        string? cveId,
        string? targetFunction = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Extract fingerprint from binary bytes.
    /// </summary>
    /// <param name="binaryData">Binary data.</param>
    /// <param name="binaryName">Binary name for identification.</param>
    /// <param name="cveId">Associated CVE ID.</param>
    /// <param name="targetFunction">Optional function name to fingerprint.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Binary fingerprint.</returns>
    Task<BinaryFingerprint> ExtractAsync(
        ReadOnlyMemory<byte> binaryData,
        string binaryName,
        string? cveId,
        string? targetFunction = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Match candidate binary against known fingerprint.
    /// </summary>
    /// <param name="candidatePath">Path to candidate binary.</param>
    /// <param name="knownFingerprint">Known fingerprint to match against.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Match result.</returns>
    Task<FingerprintMatchResult> MatchAsync(
        string candidatePath,
        BinaryFingerprint knownFingerprint,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Match candidate binary bytes against known fingerprint.
    /// </summary>
    /// <param name="candidateData">Candidate binary data.</param>
    /// <param name="knownFingerprint">Known fingerprint to match against.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Match result.</returns>
    Task<FingerprintMatchResult> MatchAsync(
        ReadOnlyMemory<byte> candidateData,
        BinaryFingerprint knownFingerprint,
        CancellationToken cancellationToken = default);
}