// Copyright (c) StellaOps. All rights reserved.
// Licensed under BUSL-1.1. See LICENSE in the project root.

using StellaOps.BinaryIndex.Disassembly;
using StellaOps.BinaryIndex.Normalization;

namespace StellaOps.BinaryIndex.DeltaSig;

/// <summary>
/// Generates delta signatures from binaries for CVE detection.
/// </summary>
public interface IDeltaSignatureGenerator
{
    /// <summary>
    /// Generates signatures for specified symbols in a binary.
    /// </summary>
    /// <param name="binaryStream">Stream containing the binary data.</param>
    /// <param name="request">Signature generation request.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The generated delta signature.</returns>
    Task<DeltaSignature> GenerateSignaturesAsync(
        Stream binaryStream,
        DeltaSignatureRequest request,
        CancellationToken ct = default);

    /// <summary>
    /// Generates a signature for a single symbol given already-disassembled instructions.
    /// </summary>
    /// <param name="normalizedBytes">The normalized bytes of the symbol.</param>
    /// <param name="symbolName">Name of the symbol.</param>
    /// <param name="scope">Section containing the symbol.</param>
    /// <param name="options">Generation options.</param>
    /// <returns>The symbol signature.</returns>
    SymbolSignature GenerateSymbolSignature(
        ReadOnlySpan<byte> normalizedBytes,
        string symbolName,
        string scope,
        SignatureOptions? options = null);

    /// <summary>
    /// Generates a signature for a single symbol with full CFG analysis.
    /// </summary>
    /// <param name="normalized">The normalized function with instructions.</param>
    /// <param name="symbolName">Name of the symbol.</param>
    /// <param name="scope">Section containing the symbol.</param>
    /// <param name="options">Generation options.</param>
    /// <returns>The symbol signature with CFG metrics.</returns>
    SymbolSignature GenerateSymbolSignature(
        NormalizedFunction normalized,
        string symbolName,
        string scope,
        SignatureOptions? options = null);

    /// <summary>
    /// Generates a signature for a single symbol with optional semantic analysis.
    /// </summary>
    /// <param name="normalized">The normalized function with instructions.</param>
    /// <param name="symbolName">Name of the symbol.</param>
    /// <param name="scope">Section containing the symbol.</param>
    /// <param name="originalInstructions">Original disassembled instructions for semantic analysis.</param>
    /// <param name="architecture">CPU architecture for IR lifting.</param>
    /// <param name="options">Generation options.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The symbol signature with CFG metrics and optional semantic fingerprint.</returns>
    Task<SymbolSignature> GenerateSymbolSignatureAsync(
        NormalizedFunction normalized,
        string symbolName,
        string scope,
        IReadOnlyList<DisassembledInstruction> originalInstructions,
        CpuArchitecture architecture,
        SignatureOptions? options = null,
        CancellationToken ct = default);
}