// Copyright (c) StellaOps. All rights reserved.
// Licensed under AGPL-3.0-or-later. See LICENSE in the project root.

namespace StellaOps.BinaryIndex.Semantic;

/// <summary>
/// Service for generating semantic fingerprints from key-semantics graphs.
/// </summary>
public interface ISemanticFingerprintGenerator
{
    /// <summary>
    /// Generate a semantic fingerprint from a key-semantics graph.
    /// </summary>
    /// <param name="graph">The key-semantics graph.</param>
    /// <param name="address">Function start address.</param>
    /// <param name="options">Fingerprint generation options.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The generated semantic fingerprint.</returns>
    Task<SemanticFingerprint> GenerateAsync(
        KeySemanticsGraph graph,
        ulong address,
        SemanticFingerprintOptions? options = null,
        CancellationToken ct = default);

    /// <summary>
    /// Generate a semantic fingerprint from a lifted function (convenience method).
    /// </summary>
    /// <param name="function">The lifted function.</param>
    /// <param name="graphExtractor">Graph extractor to use.</param>
    /// <param name="options">Fingerprint generation options.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The generated semantic fingerprint.</returns>
    Task<SemanticFingerprint> GenerateFromFunctionAsync(
        LiftedFunction function,
        ISemanticGraphExtractor graphExtractor,
        SemanticFingerprintOptions? options = null,
        CancellationToken ct = default);

    /// <summary>
    /// Gets the algorithm used by this generator.
    /// </summary>
    SemanticFingerprintAlgorithm Algorithm { get; }
}