<?php
declare(strict_types=1);

namespace Ekesto\CacheWarmup;

use Ekesto\CacheAutopilot\Support\DebugLogger;

/**
 * Unified debug logging with dual-destination support.
 *
 * Authority hierarchy (any true → enabled):
 * 1. Shared option `ekesto_ca_debug` — option-driven support mode
 * 2. EKESTO_CA_DEBUG — product-level constant
 * 3. ECW_DEBUG — plugin-level developer constant
 *
 * Destinations:
 * - Developer path (error_log): active when ECW_DEBUG or EKESTO_CA_DEBUG is set
 * - Support path (shared log file): active when support mode or product constant is set
 */
final class Debug
{
    /** @var string Prefix shown in log lines. */
    private const PREFIX = '[ECW]';

    /** @var string Plugin-level developer constant name. */
    private const DEBUG_CONSTANT = 'ECW_DEBUG';

    /** @var string Plugin-level verbose constant name. */
    private const DEBUG_VERBOSE_CONSTANT = 'ECW_DEBUG_VERBOSE';

    /**
     * Whether any debug destination is active.
     *
     * @return bool
     */
    public static function enabled(): bool
    {
        return DebugLogger::enabled(self::DEBUG_CONSTANT);
    }

    /**
     * Whether verbose debug logging is enabled.
     *
     * Verbose is developer-only. Requires an active developer constant
     * plus a verbose constant.
     *
     * @return bool
     */
    public static function verboseEnabled(): bool
    {
        return DebugLogger::verboseEnabled(self::DEBUG_CONSTANT, self::DEBUG_VERBOSE_CONSTANT);
    }

    /**
     * Write a verbose debug log entry.
     *
     * Intended for high-noise diagnostic logging. Never writes to the support log.
     *
     * @param string               $message Log message.
     * @param array<string, mixed> $context Optional structured context.
     * @return void
     */
    public static function verbose(string $message, array $context = []): void
    {
        DebugLogger::verbose(
            self::PREFIX,
            self::DEBUG_CONSTANT,
            self::DEBUG_VERBOSE_CONSTANT,
            $message,
            $context
        );
    }

    /**
     * Debug log with optional structured context.
     *
     * @param string               $message Log message.
     * @param array<string, mixed> $context Optional structured context.
     * @return void
     */
    public static function log(string $message, array $context = []): void
    {
        DebugLogger::log(
            self::PREFIX,
            self::DEBUG_CONSTANT,
            self::DEBUG_VERBOSE_CONSTANT,
            $message,
            $context
        );
    }

    /**
     * Informational log entry — written to both destinations when active.
     *
     * @param string               $message Log message.
     * @param array<string, mixed> $context Optional structured context.
     * @return void
     */
    public static function info(string $message, array $context = []): void
    {
        DebugLogger::info(self::PREFIX, self::DEBUG_CONSTANT, $message, $context);
    }

    /**
     * Warning log entry — written to both destinations when active.
     *
     * @param string               $message Log message.
     * @param array<string, mixed> $context Optional structured context.
     * @return void
     */
    public static function warn(string $message, array $context = []): void
    {
        DebugLogger::warn(self::PREFIX, self::DEBUG_CONSTANT, $message, $context);
    }

    /**
     * Error log entry — written to both destinations when active.
     *
     * @param string               $message Log message.
     * @param array<string, mixed> $context Optional structured context.
     * @return void
     */
    public static function error(string $message, array $context = []): void
    {
        DebugLogger::error(self::PREFIX, self::DEBUG_CONSTANT, $message, $context);
    }
}
