<?php

declare(strict_types=1);

namespace App\Framework\Performance\Contracts;

use App\Framework\Filesystem\ValueObjects\FilePath;
use RuntimeException;

interface PerformanceReporterInterface
{
    /**
     * Generate a performance report in the specified format
     *
     * @param string $format Supported formats: 'array', 'json', 'html', 'text'
     * @return string|array Returns array for 'array' format, string for others
     * @throws \InvalidArgumentException If format is not supported
     */
    public function generateReport(string $format = 'array'): string|array;

    /**
     * Get performance summary data
     *
     * @return array{
     *     total_request_time_ms: float,
     *     total_request_memory_bytes: int,
     *     peak_memory_bytes: int,
     *     metrics_count: int
     * }
     */
    public function getSummary(): array;

    /**
     * Get top metrics by execution time
     *
     * @param int $limit Maximum number of metrics to return
     * @return array Array of metric data sorted by total duration descending
     */
    public function getTopMetricsByTime(int $limit = 10): array;

    /**
     * Get top metrics by memory usage
     *
     * @param int $limit Maximum number of metrics to return
     * @return array Array of metric data sorted by total memory descending
     */
    public function getTopMetricsByMemory(int $limit = 10): array;

    /**
     * Get metrics grouped by category with aggregated statistics
     *
     * @return array<string, array{
     *     metrics_count: int,
     *     total_time_ms: float,
     *     total_calls: int,
     *     avg_time_ms: float,
     *     metrics: array
     * }>
     */
    public function getMetricsByCategory(): array;

    /**
     * Export report to file
     *
     * @param FilePath $filepath Path to export file
     * @param string $format Export format
     * @throws RuntimeException If file cannot be written
     */
    public function exportToFile(FilePath $filepath, string $format = 'json'): void;
}
