<?php
/**
 * Introspectable Module Interface
 *
 * Extends ModuleInterface with full introspection capabilities for
 * dependency management, configuration schemas, and hook documentation.
 *
 * @package     WPUltimateSecurity\UltimateSecurity\Contracts
 * @since       2.0.0
 */

declare(strict_types=1);

namespace WPUltimateSecurity\UltimateSecurity\Contracts;

/**
 * Extended interface for modules with full introspection support.
 *
 * New modules should extend AbstractModule which implements this interface.
 * This enables:
 * - Dependency-aware initialization via ModuleRegistry
 * - Configuration schema for settings UI
 * - Hook documentation for developers
 * - System requirement checking
 *
 * @since 2.0.0
 */
interface IntrospectableModuleInterface extends ModuleInterface
{
    /**
     * Boot the module after all modules are registered.
     *
     * Called by ModuleRegistry after dependency resolution.
     * Use this for hook registration instead of register().
     *
     * @return void
     */
    public static function boot(): void;

    /**
     * Clean up when module is deactivated.
     *
     * Remove scheduled hooks, clean up options, etc.
     *
     * @return void
     */
    public static function deactivate(): void;

    /**
     * Get unique module identifier (e.g., 'auth.2fa', 'protection.url_guard').
     *
     * Format: domain.feature or domain.feature.subfeature
     *
     * @return string
     */
    public static function getId(): string;

    /**
     * Get human-readable module name.
     *
     * @return string Translatable module name.
     */
    public static function getName(): string;

    /**
     * Get module domain.
     *
     * @return string One of: authentication, protection, monitoring, maintenance
     */
    public static function getDomain(): string;

    /**
     * Get module version.
     *
     * @return string Semantic version (e.g., '1.0.0').
     */
    public static function getVersion(): string;

    /**
     * Get IDs of modules this module depends on.
     *
     * ModuleRegistry uses this for initialization ordering.
     *
     * @return string[] Array of module IDs this module requires.
     */
    public static function getDependencies(): array;

    /**
     * Get system requirements.
     *
     * @return array<string, string> Map of requirement name to minimum version.
     *                               E.g., ['php' => '8.1', 'wp' => '6.0']
     */
    public static function getRequirements(): array;

    /**
     * Get configuration schema with defaults, types, and validation.
     *
     * Used by settings UI and ConfigService for type-safe access.
     *
     * @return array<string, array{type: string, default: mixed, label?: string, description?: string}>
     */
    public static function getConfigSchema(): array;

    /**
     * Get current resolved settings based on config schema.
     *
     * @return array<string, mixed> Map of setting key to current value.
     */
    public static function getSettings(): array;

    /**
     * Get hooks this module fires.
     *
     * Documents actions and filters for developers.
     *
     * @return array<string, array{type: string, params: string[], description?: string}>
     */
    public static function getHooks(): array;
}
