#Requires -Version 7.4

# Module-scoped cache for requirements context
$script:RequirementsContext = $null

function Get-vSEALRequirementsContext {
    <#
    .SYNOPSIS
        Builds and caches static environment context for requirements evaluation.

    .DESCRIPTION
        Creates a hashtable containing the current environment context used to evaluate
        plugin requirements. The context includes vSEAL version, Windows build number,
        OS type, hypervisor platform, and architecture.

        Context is cached after the first call for performance. Use -Force to rebuild.

    .PARAMETER Force
        Rebuilds the context even if cached. Use when testing or if environment
        detection needs to be refreshed.

    .OUTPUTS
        [hashtable] containing:
        - vSEALVersion: Current module version (e.g., '0.1.11')
        - Build: Windows build number as integer (e.g., 22631)
        - OsType: 'workstation', 'server', or 'multisession'
        - Platform: 'vmware', 'hyperv', 'nutanix', 'citrix', 'azure', or 'physical'
        - Architecture: 'x64', 'arm64', etc. (lowercase)

    .EXAMPLE
        $ctx = Get-vSEALRequirementsContext
        if ($ctx.Platform -eq 'vmware') {
            Write-Host "Running on VMware"
        }

    .EXAMPLE
        # Force rebuild of cached context
        $ctx = Get-vSEALRequirementsContext -Force

    .NOTES
        All values are lowercase for case-insensitive comparison during requirements
        evaluation. The context is static (doesn't change during module lifetime)
        so caching is safe.

    .LINK
        Test-vSEALPluginRequirements
        Get-vSEALOperatingSystemInfo
        Get-HypervisorPlatformData
    #>
    [CmdletBinding()]
    [OutputType([hashtable])]
    param(
        [Parameter()]
        [switch]$Force
    )

    # Return cached context if available (unless -Force specified)
    if ($script:RequirementsContext -and -not $Force) {
        Write-vSEALLog "Returning cached requirements context" -Level 'DEBUG'
        return $script:RequirementsContext
    }

    Write-vSEALLog "Building requirements context..." -Level 'DEBUG'

    # Get module version from manifest
    $manifestPath = Join-Path -Path $PSScriptRoot -ChildPath '..\vSEAL.psd1'
    try {
        $manifest = Import-PowerShellDataFile -Path $manifestPath -ErrorAction Stop
        $moduleVersion = $manifest.ModuleVersion
    }
    catch {
        Write-vSEALLog "Failed to read module manifest: $($_.Exception.Message)" -Level 'WARNING'
        $moduleVersion = '0.0.0'
    }

    # Get OS info (uses existing public function)
    $osInfo = Get-vSEALOperatingSystemInfo

    # Determine OsType per Get-vSEALGlobals pattern
    $osType = if ($osInfo.IsServer) {
        'server'
    }
    elseif ($osInfo.IsWorkstationEnterpriseMultiSessionOS) {
        'multisession'
    }
    else {
        'workstation'
    }

    # Get hypervisor and Azure platform data
    $azureData = Get-vSEALAzurePlatformData
    $hypervisorData = Get-HypervisorPlatformData

    # Determine Platform per Get-vSEALGlobals pattern
    # Azure check first (higher priority than hypervisor)
    $platform = if ($null -ne $azureData) {
        'azure'
    }
    elseif ($hypervisorData.IsVMware) {
        'vmware'
    }
    elseif ($hypervisorData.IsHyperV) {
        'hyperv'
    }
    elseif ($hypervisorData.IsNutanixAHV) {
        'nutanix'
    }
    elseif ($hypervisorData.IsXenServer) {
        'citrix'
    }
    else {
        'physical'
    }

    # Build context hashtable (all lowercase values for comparison)
    $context = @{
        vSEALVersion = $moduleVersion
        Build        = [int]$osInfo.BuildNumber
        OsType       = $osType
        Platform     = $platform
        Architecture = $osInfo.Architecture.ToString().ToLower()
    }

    Write-vSEALLog "Requirements context: vSEAL=$($context.vSEALVersion), Build=$($context.Build), OS=$($context.OsType), Platform=$($context.Platform), Arch=$($context.Architecture)" -Level 'VERBOSE'

    # Cache and return
    $script:RequirementsContext = $context
    return $context
}
