// -----------------------------------------------------------------------------
// IScanMetricsCollector.cs
// Sprint: SPRINT_20260106_003_002_SCANNER_vex_gate_service
// Task: T017
// Description: Interface for scan metrics collection.
// -----------------------------------------------------------------------------

namespace StellaOps.Scanner.Worker.Metrics;

/// <summary>
/// Interface for collecting scan metrics during execution.
/// </summary>
public interface IScanMetricsCollector
{
    /// <summary>
    /// Gets the metrics ID for this scan.
    /// </summary>
    Guid MetricsId { get; }

    /// <summary>
    /// Start tracking a phase.
    /// </summary>
    IDisposable StartPhase(string phaseName);

    /// <summary>
    /// Complete a phase with success.
    /// </summary>
    void CompletePhase(string phaseName, Dictionary<string, object>? metrics = null);

    /// <summary>
    /// Complete a phase with failure.
    /// </summary>
    void FailPhase(string phaseName, string errorCode, string? errorMessage = null);

    /// <summary>
    /// Set artifact counts.
    /// </summary>
    void SetCounts(int? packageCount = null, int? findingCount = null, int? vexDecisionCount = null);

    /// <summary>
    /// Records VEX gate metrics.
    /// </summary>
    void RecordVexGateMetrics(
        int totalFindings,
        int passedCount,
        int warnedCount,
        int blockedCount,
        TimeSpan elapsed);
}