<?php
/**
 * Wraps governance payloads with mandatory index coverage metadata.
 *
 * @package LolaCoreForBricks
 */

declare(strict_types=1);

namespace LolaCoreForBricks\Governance;

use LolaCoreForBricks\Support\CoveragePayload;

/**
 * Applies Law 3 to governance diagnostics.
 */
final class GovernanceResponse
{
    /**
     * @param array<string, mixed> $payload
     * @return array<string, mixed>
     */
    public static function withCoverage(array $payload): array
    {
        $coverage = CoveragePayload::forResponse();
        $response = ['coverage' => $coverage];

        if (!($coverage['complete'] ?? false)) {
            $indexed = (int) ($coverage['indexed'] ?? 0);
            $total   = (int) ($coverage['total'] ?? 0);
            $response['coverage_notice'] = 'Index coverage is partial (' . $indexed . '/' . $total
                . ' sources indexed). Treat unused or duplicate findings as provisional until rebuildDesignIndex finishes.';
        }

        return array_merge($response, $payload);
    }
}
