<?php
declare(strict_types=1);

namespace ROITheme\Shared\Infrastructure\Validators;

/**
 * Contrato para validadores de fases
 *
 * Cada fase del flujo de trabajo tiene un validador específico
 * que verifica que la implementación cumple con los estándares
 */
interface PhaseValidatorInterface
{
    /**
     * Valida un componente para la fase específica
     *
     * @param string $componentName Nombre del componente en kebab-case (ej: 'top-notification-bar')
     * @param string $themePath Ruta absoluta al tema de WordPress
     * @return ValidationResult Resultado de la validación con errores, warnings e info
     */
    public function validate(string $componentName, string $themePath): ValidationResult;

    /**
     * Retorna el número de fase que valida
     *
     * @return int|string 1, 2, 3, 4, 5 o 'structure'
     */
    public function getPhaseNumber(): int|string;

    /**
     * Retorna descripción corta de qué valida esta fase
     *
     * @return string Descripción breve (ej: 'Schema JSON', 'JSON→DB Sync')
     */
    public function getPhaseDescription(): string;
}
