package de.gecheckt.pdf.umbenenner.application.port.in;

/**
 * Aggregated outcome counts of a complete batch run, reported once at the end of the run
 * to {@link BatchRunProgressObserver#onRunEnded(RunSummary)}.
 * <p>
 * The three counts are independent, non-negative and sum up to the total number of
 * candidates that were processed in the run (possibly fewer than the originally detected
 * candidate count if the run was cancelled mid-way).
 *
 * @param successCount   number of candidates that completed with
 *                       {@link DocumentCompletionStatus#SUCCESS}; must be &ge; 0
 * @param failedCount    number of candidates that completed with either
 *                       {@link DocumentCompletionStatus#FAILED_RETRYABLE} or
 *                       {@link DocumentCompletionStatus#FAILED_PERMANENT}; must be &ge; 0
 * @param skippedCount   number of candidates that completed with either
 *                       {@link DocumentCompletionStatus#SKIPPED_ALREADY_PROCESSED} or
 *                       {@link DocumentCompletionStatus#SKIPPED_FINAL_FAILURE}; must be &ge; 0
 */
public record RunSummary(int successCount, int failedCount, int skippedCount) {

    /**
     * Compact constructor enforcing non-negative counts.
     *
     * @throws IllegalArgumentException if any count is negative
     */
    public RunSummary {
        if (successCount < 0 || failedCount < 0 || skippedCount < 0) {
            throw new IllegalArgumentException(
                    "RunSummary counts must not be negative; was: "
                            + successCount + "/" + failedCount + "/" + skippedCount);
        }
    }

    /**
     * Returns the total number of candidates reflected in this summary.
     *
     * @return {@code successCount + failedCount + skippedCount}; never negative
     */
    public int totalProcessed() {
        return successCount + failedCount + skippedCount;
    }
}
