🛠️ [fix] Update caching logic and improve localization tests

 - 🔧 Modify the cache handling in `ColorScripts-Enhanced.GapFill1.Tests.ps1` to check for script content changes instead of just timestamps
 - 🔧 Ensure that metadata is updated correctly after script changes
 - 🔧 Add signature generation for cache entries in `ColorScripts-Enhanced.GapFill2.Tests.ps1`
 - 🧪 Introduce new tests in `ColorScripts-Enhanced.Localization.Tests.ps1` to validate localization initialization and resource loading
 - 🧪 Add tests in `ColorScripts-Enhanced.PrivateCoverage.Tests.ps1` to cover private utility functions for JSON and hashtable conversions
 - 🧪 Enhance existing tests in `ColorScripts-Enhanced.Tests.ps1` to ensure cache rebuild logic works as expected
 - 🔧 Update `Test-Coverage.ps1` to exclude specific scripts from coverage analysis and report exclusions

Signed-off-by: Nick2bad4u <20943337+Nick2bad4u@users.noreply.github.com>

Author: Nick2bad4u

ColorScripts-Enhanced/ColorScripts-Enhanced.psd1

@@ -3,15 +3,15 @@
 #
 # Generated by: Nick2bad4u
 #
-# Generated on: 12/7/2025
+# Generated on: 12/8/2025
 #
 
 @{
     # Script module or binary module file associated with this manifest.
     RootModule = 'ColorScripts-Enhanced.psm1'
 
     # Version number of this module.
-    ModuleVersion = '2025.12.07.1845'
+    ModuleVersion = '2025.12.08.1032'
 
     # Supported PSEditions
     CompatiblePSEditions = @('Desktop', 'Core')
@@ -211,7 +211,7 @@ PERFECT FOR
 
             # ReleaseNotes of this module
             ReleaseNotes = @'
-Version 2025.12.07.1845:
+Version 2025.12.08.1032:
 - Enhanced caching system with OS-wide cache in AppData
 - 6-19x performance improvement
 - Cache stored in centralized location

ColorScripts-Enhanced/Private/Build-ScriptCache.ps1

@@ -14,6 +14,7 @@ function Build-ScriptCache {
 
     $scriptName = [System.IO.Path]::GetFileNameWithoutExtension($ScriptPath)
     $cacheFile = Join-Path $script:CacheDir "$scriptName.cache"
+    Remove-CacheEntryMetadataFile -ScriptName $scriptName
 
     $result = [pscustomobject]@{
         ScriptName = $scriptName
@@ -46,10 +47,23 @@ function Build-ScriptCache {
                 $scriptLastWrite = Get-FileLastWriteTime -Path $ScriptPath
                 Set-FileLastWriteTime -Path $cacheFile -Timestamp $scriptLastWrite
             }
+
+            $signature = Get-FileContentSignature -Path $ScriptPath -IncludeHash
+            Write-CacheEntryMetadataFile -ScriptName $scriptName -Signature $signature -CacheFile $cacheFile
             $result.Success = $true
         }
         catch {
             $result.StdErr = $_.Exception.Message
+            try {
+                if (Test-Path -LiteralPath $cacheFile -PathType Leaf) {
+                    Remove-Item -LiteralPath $cacheFile -Force -ErrorAction Stop
+                }
+            }
+            catch {
+                Write-Verbose ("Failed to remove incomplete cache '{0}': {1}" -f $cacheFile, $_.Exception.Message)
+            }
+
+            Remove-CacheEntryMetadataFile -ScriptName $scriptName
         }
     }
     elseif (-not $result.StdErr) {

ColorScripts-Enhanced/Private/CacheEntryMetadata.ps1

@@ -0,0 +1,131 @@
+if (-not $script:CacheEntryMetadataExtension) {
+    $script:CacheEntryMetadataExtension = '.cacheinfo'
+}
+
+if (-not $script:CacheEntryMetadataVersion -or $script:CacheEntryMetadataVersion -lt 1) {
+    $script:CacheEntryMetadataVersion = 1
+}
+
+function Get-CacheEntryMetadataPath {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [object]$ScriptName,
+
+        [Parameter()]
+        [string]$CacheRoot
+    )
+
+    $root = if ($PSBoundParameters.ContainsKey('CacheRoot') -and $CacheRoot) { $CacheRoot } else { $script:CacheDir }
+    if (-not $root) {
+        return $null
+    }
+
+    $scriptNameValue = if ($null -ne $ScriptName) { [string]$ScriptName } else { $null }
+    $trimmed = if ($scriptNameValue) { $scriptNameValue.Trim() } else { $null }
+    if ([string]::IsNullOrWhiteSpace($trimmed)) {
+        return $null
+    }
+
+    return Join-Path -Path $root -ChildPath ("{0}{1}" -f $trimmed, $script:CacheEntryMetadataExtension)
+}
+
+function Remove-CacheEntryMetadataFile {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [object]$ScriptName,
+
+        [Parameter()]
+        [string]$CacheRoot
+    )
+
+    $metadataPath = Get-CacheEntryMetadataPath -ScriptName $ScriptName -CacheRoot $CacheRoot
+    if (-not $metadataPath) {
+        return
+    }
+
+    if (-not (Test-Path -LiteralPath $metadataPath -PathType Leaf)) {
+        return
+    }
+
+    try {
+        Remove-Item -LiteralPath $metadataPath -Force -ErrorAction Stop
+    }
+    catch {
+        Write-Verbose ("Failed to remove cache metadata '{0}': {1}" -f $metadataPath, $_.Exception.Message)
+    }
+}
+
+function Write-CacheEntryMetadataFile {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string]$ScriptName,
+
+        [Parameter(Mandatory)]
+        [ValidateNotNull()]
+        [pscustomobject]$Signature,
+
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string]$CacheFile,
+
+        [Parameter()]
+        [string]$CacheGeneratedUtc,
+
+        [Parameter()]
+        [string]$ModuleVersionOverride
+    )
+
+    if (-not $script:CacheDir) {
+        return
+    }
+
+    $metadataPath = Get-CacheEntryMetadataPath -ScriptName $ScriptName
+    if (-not $metadataPath) {
+        return
+    }
+
+    $nowUtc = (Get-Date).ToUniversalTime()
+    $generatedUtc = if ([string]::IsNullOrWhiteSpace($CacheGeneratedUtc)) { $nowUtc.ToString('o') } else { $CacheGeneratedUtc }
+
+    $moduleVersion = $ModuleVersionOverride
+    if (-not $moduleVersion) {
+        try {
+            if ($ExecutionContext -and $ExecutionContext.SessionState -and $ExecutionContext.SessionState.Module) {
+                $moduleVersion = $ExecutionContext.SessionState.Module.Version.ToString()
+            }
+        }
+        catch {
+            $moduleVersion = $null
+        }
+    }
+
+    $hashAlgorithm = if ($Signature.PSObject.Properties['HashAlgorithm'] -and $Signature.HashAlgorithm) {
+        [string]$Signature.HashAlgorithm
+    }
+    elseif ($script:CacheEntryHashAlgorithm) {
+        $script:CacheEntryHashAlgorithm
+    }
+    else {
+        'SHA256'
+    }
+
+    $metadataObject = [pscustomobject]@{
+        Version              = $script:CacheEntryMetadataVersion
+        CacheFile            = [System.IO.Path]::GetFileName($CacheFile)
+        ModuleVersion        = $moduleVersion
+        CacheGeneratedUtc    = $generatedUtc
+        LastValidatedUtc     = $nowUtc.ToString('o')
+        ScriptLength         = [long]$Signature.Length
+        ScriptHash           = if ($Signature.PSObject.Properties['Hash']) { $Signature.Hash } else { $null }
+        ScriptHashAlgorithm  = $hashAlgorithm
+        ScriptLastWriteTimeUtc = if ($Signature.PSObject.Properties['LastWriteTimeUtc'] -and $Signature.LastWriteTimeUtc) { $Signature.LastWriteTimeUtc.ToString('o') } else { $null }
+    }
+
+    $json = $metadataObject | ConvertTo-Json -Depth 5
+    Invoke-FileWriteAllText -Path $metadataPath -Content $json -Encoding $script:Utf8NoBomEncoding
+}

ColorScripts-Enhanced/Private/Ensure-CacheFormatVersion.ps1

@@ -70,6 +70,20 @@ function Update-CacheFormatVersion {
         Write-Verbose ("Cache purge enumeration failed: {0}" -f $_.Exception.Message)
     }
 
+    try {
+        Get-ChildItem -LiteralPath $CacheDirectory -Filter ('*{0}' -f $script:CacheEntryMetadataExtension) -File -ErrorAction Stop | ForEach-Object {
+            try {
+                Remove-Item -LiteralPath $_.FullName -Force -ErrorAction Stop
+            }
+            catch {
+                Write-Verbose ("Failed to remove cache metadata file '{0}': {1}" -f $_.FullName, $_.Exception.Message)
+            }
+        }
+    }
+    catch {
+        Write-Verbose ("Cache metadata purge enumeration failed: {0}" -f $_.Exception.Message)
+    }
+
     $moduleVersion = $null
     try {
         if ($ExecutionContext.SessionState -and $ExecutionContext.SessionState.Module) {