namespace StellaOps.Scanner.ChangeTrace.Builder;

/// <summary>
/// Builder interface for constructing change traces.
/// </summary>
public interface IChangeTraceBuilder
{
    /// <summary>
    /// Build change trace from two scan comparisons.
    /// </summary>
    /// <param name="fromScanId">Scan ID of the "before" state.</param>
    /// <param name="toScanId">Scan ID of the "after" state.</param>
    /// <param name="options">Builder options for configuring the trace.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Constructed change trace.</returns>
    Task<Models.ChangeTrace> FromScanComparisonAsync(
        string fromScanId,
        string toScanId,
        ChangeTraceBuilderOptions? options = null,
        CancellationToken ct = default);

    /// <summary>
    /// Build change trace from two binary files.
    /// </summary>
    /// <param name="fromBinaryPath">Path to the "before" binary.</param>
    /// <param name="toBinaryPath">Path to the "after" binary.</param>
    /// <param name="options">Builder options for configuring the trace.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Constructed change trace.</returns>
    Task<Models.ChangeTrace> FromBinaryComparisonAsync(
        string fromBinaryPath,
        string toBinaryPath,
        ChangeTraceBuilderOptions? options = null,
        CancellationToken ct = default);
}