Update-Modules.ps1

#Requires -Version 7.0
#Requires -modules Microsoft.PowerShell.ThreadJob
#Requires -RunAsAdministrator
<#
Author:  Harze2k
Date:    2026-07-18
Version: 4.8
    - Added an -OnlyCleanUpOldModules parameter set to Update-Modules that skips the update check and cleans old versions from the Get-ModuleInfo inventory ($script:moduleInfo), keeping the highest version per path.
    - Added -CleanupBackupPath to back up each old version as <Module>\<Module>_<version>.zip before removal; a failed backup keeps that folder.
    - Extended -ReplaceLockedModuleOnReboot to cleanup: locked or access-denied version folders are scheduled for deletion on the next restart via PendingFileRenameOperations.
    - Added automatic ACL repair (takeown + icacls with the S-1-5-32-544 SID) and a removal retry for access-denied folders such as the built-in Pester 3.4.0.
    - Remove-OutdatedVersions now returns a structured result; failed cleanups report CleanStatus Failed, PartiallySucceeded, or PendingReboot instead of a false NoOldVersions.
    - Added FailedCleanPaths, CleanPendingRebootPaths, and BackupPaths to all result objects and extended the cleanup summaries with failed and pending-reboot counts plus a -ReplaceLockedModuleOnReboot hint.
#>
#region Check-PSResourceRepository
function Check-PSResourceRepository {
	<#
	.SYNOPSIS
	Ensures that PSResourceGet and the required repositories are configured.
	.DESCRIPTION
	Imports Microsoft.PowerShell.PSResourceGet, installing it for all users when
	necessary, and idempotently configures only the selected repositories.
	The function is intended for PowerShell 7 running as administrator. It emits
	exactly one success-stream value: $true when the final configuration is valid,
	or $false when setup or verification fails.
	.PARAMETER ImportDependencies
	Requests an explicit module import. If PSResourceGet is already loaded, the
	current session-safe instance is retained because binary modules can't be
	hot-reloaded after another version is installed. ForceImport is an alias for
	this parameter.
	.PARAMETER ForceInstall
	Forces Microsoft.PowerShell.PSResourceGet to be installed again before import.
	.PARAMETER Repositories
	Repository names to configure and verify. Valid values are PSGallery, NuGet,
	and NuGetGallery. When omitted, all three repositories are checked.
	.OUTPUTS
	System.Boolean
	.EXAMPLE
	$repositoryReady = Check-PSResourceRepository
	.EXAMPLE
	$repositoryReady = Check-PSResourceRepository -ForceImport
	.EXAMPLE
	$repos = @('PSGallery', 'NuGet')
	$repositoryReady = Check-PSResourceRepository -Repositories $repos
	.NOTES
	Requires PowerShell 7, administrator rights, and network access when the module
	must be installed.
	#>
	[CmdletBinding()]
	[OutputType([bool])]
	param (
		[Alias('ForceImport')][switch]$ImportDependencies,
		[switch]$ForceInstall,
		[ValidateNotNullOrEmpty()]
		[ValidateSet('PSGallery', 'NuGet', 'NuGetGallery')]
		[string[]]$Repositories = @('PSGallery', 'NuGet', 'NuGetGallery')
	)
	function Test-RepositoryConfiguration {
		[OutputType([bool])]
		param (
			[AllowNull()][psobject]$Repository,
			[Parameter(Mandatory)][hashtable]$Definition
		)
		if ($null -eq $Repository) {
			return $false
		}
		if (-not [bool]$Repository.Trusted -or
			[int]$Repository.Priority -ne [int]$Definition.Priority) {
			return $false
		}
		if ($Definition.ContainsKey('Uri')) {
			try {
				$actualUri = ([uri]$Repository.Uri).AbsoluteUri.TrimEnd('/')
				$expectedUri = ([uri]$Definition.Uri).AbsoluteUri.TrimEnd('/')
			}
			catch {
				return $false
			}
			if ($actualUri -ine $expectedUri) {
				return $false
			}
		}
		if ($Definition.ContainsKey('ApiVersion') -and
			[string]$Repository.ApiVersion -ine [string]$Definition.ApiVersion) {
			return $false
		}
		return $true
	}
	$moduleName = 'Microsoft.PowerShell.PSResourceGet'
	try {
		# Command discovery auto-imports PSResourceGet, which would load its binary assembly before a requested reinstall and make the new assembly impossible to load in-process.
		$loadedModule = Get-Module -Name $moduleName | Select-Object -First 1
		$resourceCommand = if ($null -ne $loadedModule) {
			Get-Command -Name 'Get-PSResourceRepository' -ErrorAction SilentlyContinue
		}
		else {
			$null
		}
		if (-not $ForceInstall -and $null -eq $resourceCommand) {
			try {
				$importParams = @{
					Name          = $moduleName
					ErrorAction   = 'Stop'
					Verbose       = $false
					WarningAction = 'SilentlyContinue'
				}
				Import-Module @importParams
				$loadedModule = Get-Module -Name $moduleName | Select-Object -First 1
				$resourceCommand = Get-Command -Name 'Get-PSResourceRepository' -ErrorAction SilentlyContinue
			}
			catch {
				New-Log "PSResourceGet could not be imported; installation will be attempted." -Level ERROR
				$resourceCommand = $null
			}
		}
		elseif (-not $ForceInstall -and $ImportDependencies -and $null -ne $loadedModule) {
			New-Log "PSResourceGet $($loadedModule.Version) is already loaded; retaining the current binary module instance."
		}
		if ($ForceInstall -or $null -eq $resourceCommand) {
			if ($null -eq (Get-Command -Name 'Install-Module' -ErrorAction SilentlyContinue)) {
				New-Log 'Install-Module is unavailable, so PSResourceGet cannot be installed.' -Level WARNING
				return $false
			}
			# Install-Module uses the legacy PowerShellGet repository store. Make its PSGallery entry usable for an unattended bootstrap when those commands exist.
			if ($null -ne (Get-Command -Name 'Get-PSRepository' -ErrorAction SilentlyContinue)) {
				$legacyGallery = Get-PSRepository -Name 'PSGallery' -ErrorAction SilentlyContinue
				if ($null -eq $legacyGallery) {
					Register-PSRepository -Default -ErrorAction Stop
					$legacyGallery = Get-PSRepository -Name 'PSGallery' -ErrorAction Stop
				}
				if ($legacyGallery.InstallationPolicy -ne 'Trusted') {
					Set-PSRepository -Name 'PSGallery' -InstallationPolicy Trusted -ErrorAction Stop
				}
			}
			New-Log "Installing $moduleName for all users..."
			$installParams = @{
				Name          = $moduleName
				Repository    = 'PSGallery'
				Scope         = 'AllUsers'
				Force         = $true
				AllowClobber  = $true
				AcceptLicense = $true
				Confirm       = $false
				ErrorAction   = 'Stop'
				PassThru      = $true
				Verbose       = $false
			}
			$installedResource = Install-Module @installParams
			$sessionModule = Get-Module -Name $moduleName | Select-Object -First 1
			if ($null -ne $sessionModule) {
				# A .NET assembly can't be replaced inside a running pwsh process. Keep
				# using the functional version that is already loaded; the installed
				# version will be selected automatically by the next pwsh process.
				$resourceCommand = Get-Command -Name 'Get-PSResourceRepository' -ErrorAction SilentlyContinue
				$installedVersion = if ($null -ne $installedResource.Version) { $installedResource.Version } else { 'unknown' }
				New-Log "Installation completed. Continuing with loaded PSResourceGet $($sessionModule.Version); installed version $installedVersion will be used in new PowerShell sessions."
			}
			else {
				Import-Module -Name $moduleName -ErrorAction Stop -Verbose:$false -WarningAction SilentlyContinue
				$resourceCommand = Get-Command -Name 'Get-PSResourceRepository' -ErrorAction SilentlyContinue
			}
		}
		if ($null -eq $resourceCommand) {
			New-Log 'PSResourceGet was imported, but Get-PSResourceRepository is unavailable.' -Level WARNING
			return $false
		}
		$requiredCommands = @(
			'Get-PSResourceRepository'
			'Register-PSResourceRepository'
			'Set-PSResourceRepository'
		)
		foreach ($commandName in $requiredCommands) {
			if ($null -eq (Get-Command -Name $commandName -ErrorAction SilentlyContinue)) {
				New-Log "Required PSResourceGet command '$commandName' is unavailable." -Level WARNING
				return $false
			}
		}
		$repositoryDefinitions = @(
			@{
				Name      = 'PSGallery'
				Priority  = 30
				PSGallery = $true
			}
			@{
				Name       = 'NuGetGallery'
				Uri        = 'https://api.nuget.org/v3/index.json'
				Priority   = 40
				ApiVersion = 'V3'
			}
			@{
				Name       = 'NuGet'
				Uri        = 'https://www.nuget.org/api/v2'
				Priority   = 50
				ApiVersion = 'V2'
			}
		)
		$requestedRepositories = @($Repositories | Select-Object -Unique)
		$repositoriesToCheck = @($repositoryDefinitions | Where-Object { $_.Name -in $requestedRepositories })
		New-Log "PSResourceGet is available. Checking repositories: $($repositoriesToCheck.Name -join ', ')..."
		foreach ($definition in $repositoriesToCheck) {
			$repository = Get-PSResourceRepository -Name $definition.Name -ErrorAction SilentlyContinue
			if ($null -eq $repository) {
				if ($definition.PSGallery) {
					Register-PSResourceRepository -PSGallery -Trusted -Priority $definition.Priority -Confirm:$false -ErrorAction Stop
				}
				else {
					$registerParams = @{
						Name        = $definition.Name
						Uri         = $definition.Uri
						Priority    = $definition.Priority
						ApiVersion  = $definition.ApiVersion
						Trusted     = $true
						Confirm     = $false
						ErrorAction = 'Stop'
					}
					Register-PSResourceRepository @registerParams
				}
				New-Log "Registered repository '$($definition.Name)'." -Level SUCCESS
			}
			elseif (-not (Test-RepositoryConfiguration -Repository $repository -Definition $definition)) {
				$setParams = @{
					Name        = $definition.Name
					Priority    = $definition.Priority
					Trusted     = $true
					Confirm     = $false
					ErrorAction = 'Stop'
				}
				if (-not $definition.PSGallery) {
					$setParams.Uri = $definition.Uri
					$setParams.ApiVersion = $definition.ApiVersion
				}
				Set-PSResourceRepository @setParams
				New-Log "Updated repository '$($definition.Name)'." -Level SUCCESS
			}
			else {
				New-Log "Repository '$($definition.Name)' is already configured correctly."
			}
			$verifiedRepository = Get-PSResourceRepository -Name $definition.Name -ErrorAction SilentlyContinue
			if (-not (Test-RepositoryConfiguration -Repository $verifiedRepository -Definition $definition)) {
				New-Log "Repository '$($definition.Name)' failed final verification." -Level WARNING
				return $false
			}
		}
		New-Log 'All selected repositories are configured and verified.' -Level SUCCESS
		return $true
	}
	catch {
		New-Log "PSResource repository setup failed." -Level ERROR
		return $false
	}
}
#endregion Check-PSResourceRepository
#region Get-ModuleInfo
function Get-ModuleInfo {
	<#
    .SYNOPSIS
    Builds an inventory of installed PowerShell modules.
    .DESCRIPTION
    Scans the supplied directories for module manifests and PSGetModuleInfo.xml/nuspec files,
    parses their metadata in parallel, normalizes installation paths, and groups the
    results by module name.
    .PARAMETER Paths
    Directories to scan recursively. Paths from PSModulePath are typically supplied.
    .PARAMETER IgnoredModules
    Module names to exclude from the returned inventory.
    .PARAMETER ThrottleLimit
    Maximum number of files processed concurrently.
    .INPUTS
    None.
    .OUTPUTS
    System.Collections.Specialized.OrderedDictionary. Keys are module names and values
    are arrays of installation records containing version, path, prerelease, and author data.
    .EXAMPLE
    $paths = $env:PSModulePath -split [IO.Path]::PathSeparator
    $inventory = Get-ModuleInfo -Paths $paths -IgnoredModules 'BurntToast'
    Scans standard module paths and excludes BurntToast.
    .NOTES
    Requires PowerShell 7 or later for ForEach-Object -Parallel.
    .LINK
    Get-ModuleUpdateStatus
    #>
	[CmdletBinding()]
	param(
		[Parameter(Mandatory)][string[]]$Paths,
		[string[]]$IgnoredModules = @(),
		[int]$ThrottleLimit = ([System.Environment]::ProcessorCount * 2)
	)
	$helperFunctionDefinitions = @{
		"New-Log"                 = ${function:New-Log}.ToString()
		"Parse-ModuleVersion"     = ${function:Parse-ModuleVersion}.ToString()
		"Get-ManifestVersionInfo" = ${function:Get-ManifestVersionInfo}.ToString()
		"Resolve-ModuleVersion"   = ${function:Resolve-ModuleVersion}.ToString()
		"Get-ModuleformPath"      = ${function:Get-ModuleformPath}.ToString()
		"Get-ModuleInfoFromXml"   = ${function:Get-ModuleInfoFromXml}.ToString()
		"Test-IsResourceFile"     = ${function:Test-IsResourceFile}.ToString()
	}
	foreach ($funcName in $helperFunctionDefinitions.Keys) {
		if ([string]::IsNullOrWhiteSpace($helperFunctionDefinitions[$funcName])) {
			Write-Error "Helper function '$funcName' could not be found. It must be loaded."
			return
		}
	}
	$scanPaths = @($Paths | Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | Sort-Object -Unique)
	New-Log "Scanning $($scanPaths.Count) module path(s) for manifests and PSGetModuleInfo.xml/nuspec files..."
	$fileDiscoveryStartTime = Get-Date
	$allPotentialFiles = [System.Collections.Generic.List[System.IO.FileInfo]]::new()
	foreach ($dir in $scanPaths) {
		try {
			if (-not (Test-Path -LiteralPath $dir -PathType Container)) {
				New-Log "Skipping missing module path '$dir'." -Level WARNING
				continue
			}
			$psd1Files = @(Get-ChildItem -LiteralPath $dir -Recurse -File -Filter "*.psd1" -ErrorAction Stop)
			$xmlFiles = @(Get-ChildItem -LiteralPath $dir -Recurse -File -ErrorAction Stop) | Where-Object { $_.Name -match '^(PSGetModuleInfo\.xml|.*\.nuspec)$' }
			foreach ($file in $psd1Files) { $allPotentialFiles.Add($file) }
			foreach ($file in $xmlFiles) { $allPotentialFiles.Add($file) }
		}
		catch {
			New-Log "Could not scan module path '$dir'" -Level ERROR
		}
	}
	$allPotentialFiles = @($allPotentialFiles | Sort-Object FullName -Unique)
	$fileDiscoveryDuration = (Get-Date) - $fileDiscoveryStartTime
	if ($allPotentialFiles.Count -eq 0) {
		New-Log "No potential module files found to process." -Level WARNING
		return [ordered]@{}
	}
	New-Log "Found $($allPotentialFiles.Count) candidate file(s) in $([math]::Round($fileDiscoveryDuration.TotalSeconds, 2)) seconds; parsing with throttle $ThrottleLimit." -Level VERBOSE
	$allFoundModulesFromParallel = [System.Collections.Concurrent.ConcurrentBag[object]]::new()
	$skippedFiles = [System.Collections.Concurrent.ConcurrentBag[string]]::new()
	$fallbackFiles = [System.Collections.Concurrent.ConcurrentBag[string]]::new()
	$failedFiles = [System.Collections.Concurrent.ConcurrentBag[string]]::new()
	$null = $allPotentialFiles | ForEach-Object -ThrottleLimit $ThrottleLimit -Parallel {
		$fileInfo = $_
		$filePath = $fileInfo.FullName
		$fileExtension = $fileInfo.Extension
		$VerbosePreference = $using:VerbosePreference
		$allFoundModulesFromParallel = $using:allFoundModulesFromParallel
		$skippedFiles = $using:skippedFiles
		$fallbackFiles = $using:fallbackFiles
		$failedFiles = $using:failedFiles
		$localHelperFunctionDefinitions = $using:helperFunctionDefinitions
		foreach ($funcName in $localHelperFunctionDefinitions.Keys) {
			$funcDefinition = $localHelperFunctionDefinitions[$funcName]
			if (-not [string]::IsNullOrWhiteSpace($funcDefinition)) {
				Set-Item -Path "function:global:$funcName" -Value ([scriptblock]::Create($funcDefinition))
			}
		}
		if (Test-IsResourceFile -Path $filePath) {
			New-Log "Skipping resource file '$filePath'." -Level VERBOSE
			$skippedFiles.Add($filePath)
			return
		}
		if ($fileExtension -eq '.psd1') {
			$manifestInfoObj = $null
			$testManifestOutput = $null
			$usedFallback = $false
			try {
				$testManifestOutput = Test-ModuleManifest -Path $filePath -ErrorAction Stop -WarningAction SilentlyContinue -Verbose:$false
			}
			catch {
				$testManifestOutput = $null
				$usedFallback = $true
			}
			if ($testManifestOutput) {
				try {
					$manifestInfoObj = Get-ManifestVersionInfo -ResData $testManifestOutput -Quick -ErrorAction Stop -WarningAction SilentlyContinue
				}
				catch {
					New-Log "Get-ManifestVersionInfo failed for '$filePath': $($_.Exception.Message)" -Level VERBOSE
					$manifestInfoObj = $null
					$usedFallback = $true
				}
			}
			if (-not $manifestInfoObj) {
				$usedFallback = $true
				try {
					$manifestInfoObj = Get-ManifestVersionInfo -ModuleFilePath $filePath -ErrorAction Stop -WarningAction SilentlyContinue
				}
				catch {
					New-Log "Fallback Get-ManifestVersionInfo failed for '$filePath': $($_.Exception.Message)" -Level VERBOSE
					$manifestInfoObj = $null
				}
			}
			if ($usedFallback -and $manifestInfoObj) {
				$fallbackFiles.Add($filePath)
			}
			$manifestInfosToProcess = @()
			if ($manifestInfoObj) {
				if ($manifestInfoObj -is [array] -or $manifestInfoObj -is [System.Collections.IList]) {
					$manifestInfosToProcess = $manifestInfoObj
				}
				else {
					$manifestInfosToProcess = @($manifestInfoObj)
				}
			}
			foreach ($mInfo in $manifestInfosToProcess) {
				if ($mInfo -and $mInfo.ModuleVersion -and $mInfo.ModuleName) {
					New-Log "Found module '$($mInfo.ModuleName)' version '$($mInfo.ModuleVersionString)' at '$($mInfo.BasePath)'." -Level VERBOSE
					$allFoundModulesFromParallel.Add([PSCustomObject]@{
							ModuleName          = $mInfo.ModuleName
							ModuleVersion       = $mInfo.ModuleVersion
							ModuleVersionString = $mInfo.ModuleVersionString
							BasePath            = $mInfo.BasePath
							isPreRelease        = $mInfo.isPreRelease
							PreReleaseLabel     = $mInfo.PreReleaseLabel
							Author              = $mInfo.Author
						})
				}
			}
			if ($manifestInfosToProcess.Count -eq 0) {
				New-Log "No valid module data could be extracted from manifest '$filePath'." -Level VERBOSE
				$failedFiles.Add($filePath)
			}
		}
		elseif ($fileExtension -in @('.xml', '.nuspec')) {
			$xmlInfo = Get-ModuleInfoFromXml -XmlFilePath $filePath -ErrorAction SilentlyContinue -WarningAction SilentlyContinue
			if ($xmlInfo -and $xmlInfo.ModuleName -and $xmlInfo.ModuleVersion) {
				New-Log "Found module '$($xmlInfo.ModuleName)' version '$($xmlInfo.ModuleVersionString)' at '$($xmlInfo.BasePath)'." -Level VERBOSE
				$allFoundModulesFromParallel.Add([PSCustomObject]@{
						ModuleName          = $xmlInfo.ModuleName
						ModuleVersion       = $xmlInfo.ModuleVersion
						ModuleVersionString = $xmlInfo.ModuleVersionString
						BasePath            = $xmlInfo.BasePath
						isPreRelease        = $xmlInfo.isPreRelease
						PreReleaseLabel     = $xmlInfo.PreReleaseLabel
						Author              = $xmlInfo.Author
					})
			}
			else {
				New-Log "No valid module data could be extracted from XML file '$filePath'." -Level VERBOSE
				$failedFiles.Add($filePath)
			}
		}
	}
	$allFoundModulesArray = $allFoundModulesFromParallel.ToArray()
	if ($allFoundModulesArray.Count -eq 0) {
		New-Log "No valid module data collected after parallel processing." -Level WARNING
		return [ordered]@{}
	}
	$uniqueModules = $allFoundModulesArray | Group-Object -Property ModuleName, BasePath, ModuleVersionString | ForEach-Object { $_.Group[0] }
	$resultModules = [ordered]@{}
	$modulesGroupedByName = $uniqueModules | Where-Object { $null -ne $_.ModuleName -and $_.ModuleName -notmatch '^\d+(\.\d+)+$' } | Group-Object ModuleName
	foreach ($nameGroup in $modulesGroupedByName) {
		$moduleName = $nameGroup.Name
		$groupWithNormalizedPaths = $nameGroup.Group | Where-Object { $null -ne $_ } | ForEach-Object {
			$newObject = $_ | Select-Object *
			if ($null -ne $newObject.BasePath -and -not ([string]::IsNullOrWhiteSpace($moduleName))) {
				$currentBasePath = $newObject.BasePath
				$normalizedCurrentPath = $currentBasePath.TrimEnd('\', '/') -replace '/', '\'
				$expectedEnding = "\$moduleName"
				if (-not $normalizedCurrentPath.EndsWith($expectedEnding, [System.StringComparison]::OrdinalIgnoreCase)) {
					$leafName = Split-Path $normalizedCurrentPath -Leaf
					$parentOfCurrent = Split-Path $normalizedCurrentPath -Parent -ErrorAction SilentlyContinue
					$parentLeafName = if ($parentOfCurrent) { Split-Path $parentOfCurrent -Leaf -ErrorAction SilentlyContinue } else { $null }
					if ($parentLeafName -eq $moduleName -and $leafName -match '^\d+(\.\d+){1,3}(-.+)?$') {
						$newObject.BasePath = $parentOfCurrent
					}
					elseif ($leafName -eq 'Modules' -or $leafName -eq 'Documents') {
						$newObject.BasePath = Join-Path -Path $normalizedCurrentPath -ChildPath $moduleName -ErrorAction SilentlyContinue
					}
					else {
						$newObject.BasePath = $normalizedCurrentPath
					}
				}
				else {
					$newObject.BasePath = $normalizedCurrentPath
				}
			}
			$newObject
		}
		$modulesGroupedByBasePath = $groupWithNormalizedPaths | Where-Object { $null -ne $_.BasePath } | Group-Object -Property BasePath
		$finalModuleLocations = [System.Collections.Generic.List[object]]::new()
		foreach ($basePathGroup in $modulesGroupedByBasePath) {
			$currentBasePath = $basePathGroup.Name
			$versionsInPathGroup = $basePathGroup.Group | Group-Object -Property @{ Expression = { if ($_.ModuleVersion -is [version]) { $_.ModuleVersion } else { $_.ModuleVersionString } } }
			foreach ($versionGroup in $versionsInPathGroup) {
				$representativeEntry = $versionGroup.Group | Sort-Object -Property @{Expression = { $_.ModuleVersion -is [version] }; Descending = $true }, ModuleVersionString | Select-Object -First 1
				if ($representativeEntry) {
					$outputObject = [PSCustomObject]@{
						ModuleName          = $moduleName
						ModuleVersion       = $representativeEntry.ModuleVersion
						ModuleVersionString = $representativeEntry.ModuleVersionString
						BasePath            = $currentBasePath
						IsPreRelease        = $representativeEntry.IsPreRelease
						PreReleaseLabel     = $representativeEntry.PreReleaseLabel
						Author              = $representativeEntry.Author
					}
					$finalModuleLocations.Add($outputObject)
				}
			}
		}
		if ($finalModuleLocations.Count -gt 0) {
			$sortedLocations = $finalModuleLocations | Sort-Object BasePath, @{Expression = { $_.ModuleVersion }; Ascending = $true }
			$resultModules[$moduleName] = $sortedLocations
		}
	}
	$finalSortedModules = [ordered]@{}
	foreach ($key in ($resultModules.Keys | Sort-Object)) {
		if ($IgnoredModules -notcontains $key) {
			$finalSortedModules[$key] = $resultModules[$key]
		}
		else {
			New-Log "Skipping module '$key' as it is in the IgnoredModules list (final filter)." -Level VERBOSE
		}
	}
	$totalFunctionDuration = (Get-Date) - $fileDiscoveryStartTime
	$installationCount = @($finalSortedModules.Values | ForEach-Object { $_ }).Count
	$inventoryLevel = if ($failedFiles.Count -gt 0) { 'WARNING' } else { 'SUCCESS' }
	New-Log "Inventory complete: $($allPotentialFiles.Count) candidates produced $installationCount installation record(s) for $($finalSortedModules.Keys.Count) module(s) in $([math]::Round($totalFunctionDuration.TotalSeconds, 2)) seconds; skipped $($skippedFiles.Count) support file(s), used fallback metadata for $($fallbackFiles.Count), and could not parse $($failedFiles.Count)." -Level $inventoryLevel
	return $finalSortedModules
}
#endregion Get-ModuleInfo
#region Get-ModuleUpdateStatus
function Get-ModuleUpdateStatus {
	<#
    .SYNOPSIS
    Finds newer module versions in registered PSResource repositories.
    .DESCRIPTION
    Fetches stable and prerelease metadata in parallel, applying repository exclusions
    separately for each module. It compares the online versions with the local inventory
    and returns one record for each module that has an update.
    .PARAMETER ModuleInventory
    Module inventory returned by Get-ModuleInfo.
    .PARAMETER Repositories
    Registered PSResource repositories to query, in priority order.
    .PARAMETER ThrottleLimit
    Maximum number of concurrent repository lookups and comparisons.
    .PARAMETER TimeoutSeconds
    Hard time limit, in seconds, for the complete online lookup operation.
    .PARAMETER FindModuleTimeoutSeconds
    Soft time budget, in seconds, for repository queries for one module.
    .PARAMETER OnlineCacheMinutes
    Lifetime of successful online lookup metadata in minutes. The default is 30;
    specify 0 to disable the persistent cache.
    .PARAMETER OnlineCachePath
    JSON file used for the persistent online lookup cache.
    .PARAMETER LookupRetryCount
    Number of targeted retries for modules that did not finish within the main stage.
    .PARAMETER RetryTimeoutSeconds
    Hard time limit, in seconds, for each targeted retry stage.
    .PARAMETER ForceOnlineRefresh
    Ignores existing persistent cache entries for this run.
    .PARAMETER BlackList
    Maps module names to excluded repositories. Use '*' to exclude all repositories for a module. The default is an empty hashtable.
    .PARAMETER MatchAuthor
    Reports an update only when normalized local and repository author names match.
    .INPUTS
    None.
    .OUTPUTS
    System.Management.Automation.PSCustomObject. Each record contains the module name,
    repository, local and online versions, prerelease data, and outdated installations.
    .EXAMPLE
    $updates = Get-ModuleUpdateStatus -ModuleInventory $inventory -Repositories 'PSGallery' -MatchAuthor
    Checks PSGallery and requires matching author names.
    .NOTES
    Requires Microsoft.PowerShell.PSResourceGet and network access to the repositories.
    .LINK
    Find-PSResource
    #>
	[CmdletBinding()]
	param (
		[Parameter(Mandatory)][hashtable]$ModuleInventory,
		[string[]]$Repositories = @('PSGallery', 'NuGet', 'NuGetGallery'),
		[int]$ThrottleLimit = ([Environment]::ProcessorCount * 2),
		[ValidateRange(1, 3600)][int]$TimeoutSeconds = 60,
		[ValidateRange(1, 60)][int]$FindModuleTimeoutSeconds = 15,
		[ValidateRange(0, 1440)][int]$OnlineCacheMinutes = 30,
		[ValidateNotNullOrEmpty()][string]$OnlineCachePath = (Join-Path ([Environment]::GetFolderPath('LocalApplicationData')) 'Temp\Update-Modules\OnlineVersionCache.json'),
		[ValidateRange(0, 3)][int]$LookupRetryCount = 1,
		[ValidateRange(1, 300)][int]$RetryTimeoutSeconds = 10,
		[switch]$ForceOnlineRefresh,
		[hashtable]$BlackList = @{},
		[switch]$MatchAuthor
	)
	function ConvertTo-OnlineCacheResource {
		param ([AllowNull()][psobject]$Resource)
		if ($null -eq $Resource) { return $null }
		return [pscustomobject]@{
			Version      = [string]$Resource.Version
			Repository   = [string]$Resource.Repository
			Author       = [string]$Resource.Author
			PreRelease   = if ($Resource.PSObject.Properties['PreRelease']) { [string]$Resource.PreRelease } else { $null }
			IsPrerelease = if ($Resource.PSObject.Properties['IsPrerelease']) { [bool]$Resource.IsPrerelease } else { $false }
		}
	}
	$allModuleNames = $ModuleInventory.Keys | Where-Object { $_ -and $_.Trim() } | Sort-Object -Unique
	if ($allModuleNames.Count -eq 0) {
		New-Log "Module inventory is empty. Nothing to check."
		return @()
	}
	$moduleDataArray = @()
	foreach ($moduleNameInLoop in $allModuleNames) {
		$localModulesInput = $ModuleInventory[$moduleNameInLoop]
		if ($localModulesInput -is [PSCustomObject]) {
			$localModulesInput = @($localModulesInput)
		}
		$parsedVersions = $localModulesInput | Where-Object { $_ -and ($_.PSObject.Properties.Name -contains 'ModuleVersion' -or $_.PSObject.Properties.Name -contains 'ModuleVersionString') -and $_.PSObject.Properties.Name -contains 'BasePath' } | ForEach-Object {
			[PSCustomObject]@{
				ModuleVersion       = $_.ModuleVersion
				ModuleVersionString = $_.ModuleVersionString
				PreReleaseLabel     = $_.PreReleaseLabel
				BasePath            = $_.BasePath
				IsPreRelease        = $_.IsPrerelease
				Author              = $_.Author
			}
		}
		if ($parsedVersions.Count -gt 0) {
			$highestLocalVersionInstall = $parsedVersions | Sort-Object -Property @{E = { $_.ModuleVersion }; Descending = $true }, @{E = { $_.IsPreRelease }; Ascending = $true } | Select-Object -First 1
			New-Log "Module '$moduleNameInLoop' has $($parsedVersions.Count) local installation(s); highest version is '$($highestLocalVersionInstall.ModuleVersionString)'." -Level VERBOSE
			$moduleDataArray += [PSCustomObject]@{
				ModuleName          = $moduleNameInLoop
				HighestLocalInstall = $highestLocalVersionInstall
				AllParsedVersions   = $parsedVersions
			}
		}
		else {
			New-Log "Module '$moduleNameInLoop' has no valid version data and will be skipped." -Level WARNING
		}
	}
	$validModuleCountForProcessing = $moduleDataArray.Count
	if ($validModuleCountForProcessing -eq 0) {
		New-Log "No valid modules remaining after pre-processing local inventory." -Level WARNING
		return @()
	}
	New-Log "Prepared $validModuleCountForProcessing modules from local inventory." -Level VERBOSE
	$overallOperationStartTime = Get-Date
	$onlineModuleVersionsCache = [System.Collections.Concurrent.ConcurrentDictionary[string, object]]::new([System.StringComparer]::OrdinalIgnoreCase)
	$normalizedRepositories = @($Repositories | ForEach-Object { ([string]$_).ToLowerInvariant() })
	$normalizedBlackList = @($BlackList.GetEnumerator() | Sort-Object { [string]$_.Key } | ForEach-Object {
			$normalizedValues = @($_.Value | ForEach-Object { ([string]$_).ToLowerInvariant() } | Sort-Object)
			"$(([string]$_.Key).ToLowerInvariant())=$($normalizedValues -join ',')"
		})
	$onlineCacheConfigurationKey = "$($normalizedRepositories -join '|')::$($normalizedBlackList -join ';')"
	$moduleNamesToCheck = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
	foreach ($moduleData in $moduleDataArray) { [void]$moduleNamesToCheck.Add($moduleData.ModuleName) }
	$cacheHits = 0
	if ($OnlineCacheMinutes -gt 0 -and -not $ForceOnlineRefresh.IsPresent -and (Test-Path -LiteralPath $OnlineCachePath -PathType Leaf)) {
		try {
			$cacheDocument = Get-Content -LiteralPath $OnlineCachePath -Raw -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop
			if ([int]$cacheDocument.SchemaVersion -eq 2 -and [string]$cacheDocument.ConfigurationKey -ceq $onlineCacheConfigurationKey) {
				$cacheCutoffUtc = [DateTime]::UtcNow.AddMinutes(-$OnlineCacheMinutes)
				foreach ($cacheEntry in @($cacheDocument.Entries)) {
					if ($null -eq $cacheEntry -or -not $moduleNamesToCheck.Contains([string]$cacheEntry.ModuleName)) { continue }
					try { $cachedAtUtc = [DateTime]::new([long]$cacheEntry.CachedAtUtcTicks, [DateTimeKind]::Utc) }
					catch { continue }
					if ($cachedAtUtc -lt $cacheCutoffUtc) { continue }
					New-Log "Online lookup cache hit for module '$($cacheEntry.ModuleName)' (cached at $($cachedAtUtc.ToString('u')))." -Level VERBOSE
					$onlineModuleVersionsCache[[string]$cacheEntry.ModuleName] = [pscustomobject]@{
						ModuleName    = [string]$cacheEntry.ModuleName
						Stable        = $cacheEntry.Stable
						PreRelease    = $cacheEntry.PreRelease
						ErrorFetching = $null
						Skipped       = $false
						CachedAtUtc   = $cachedAtUtc
					}
					$cacheHits++
				}
			}
			else {
				New-Log "Online lookup cache configuration changed; ignoring existing entries." -Level VERBOSE
			}
		}
		catch {
			New-Log "Online lookup cache could not be read and will be rebuilt." -Level ERROR
		}
	}
	elseif ($ForceOnlineRefresh.IsPresent) {
		New-Log "Forcing a fresh online lookup; existing cache entries are being ignored." -Level VERBOSE
	}
	$modulesPendingLookup = @($moduleDataArray | Where-Object { -not $onlineModuleVersionsCache.ContainsKey($_.ModuleName) })
	New-Log "Online lookup cache: $cacheHits hit(s), $($modulesPendingLookup.Count) lookup(s) required (TTL: $OnlineCacheMinutes minute(s))." -Level VERBOSE
	$NewLogDef = ${function:New-Log}.ToString()
	# Run lookup stages as background parallel jobs so timed-out pipelines can be stopped and drained quietly.
	for ($lookupAttempt = 0; $lookupAttempt -le $LookupRetryCount -and $modulesPendingLookup.Count -gt 0; $lookupAttempt++) {
		$stageTimeoutSeconds = if ($lookupAttempt -eq 0) { $TimeoutSeconds } else { $RetryTimeoutSeconds }
		if ($lookupAttempt -eq 0) {
			New-Log "Starting online version pre-fetching for $($modulesPendingLookup.Count) module(s) (Throttle: $ThrottleLimit, max ${stageTimeoutSeconds}s)..."
		}
		else {
			New-Log "Retrying $($modulesPendingLookup.Count) unfinished module lookup(s), attempt $lookupAttempt of $LookupRetryCount (max ${stageTimeoutSeconds}s)..." -Level VERBOSE
		}
		$lookupJob = $null
		$stageTimedOut = $false
		try {
			$lookupJob = $modulesPendingLookup | ForEach-Object -ThrottleLimit $ThrottleLimit -Parallel {
				$moduleNameToFetch = $_.ModuleName
				${function:New-Log} = $using:NewLogDef
				$VerbosePreference = $using:VerbosePreference
				$allRepositories = @($using:Repositories)
				$blackList = $using:BlackList
				$perModuleBudget = $using:FindModuleTimeoutSeconds
				$cache = $using:onlineModuleVersionsCache
				$currentRepositories = $allRepositories
				if ($blackList -and $blackList.ContainsKey($moduleNameToFetch)) {
					$setting = $blackList[$moduleNameToFetch]
					if ($setting -eq '*') {
						$cache[$moduleNameToFetch] = [pscustomobject]@{
							ModuleName    = $moduleNameToFetch
							Stable        = $null
							PreRelease    = $null
							ErrorFetching = $null
							Skipped       = $true
							CachedAtUtc   = [DateTime]::UtcNow
						}
						New-Log "[$moduleNameToFetch] Pre-fetch: Blacklisted ('*'). Skipping online check." -Level VERBOSE
						return
					}
					elseif ($setting -is [array]) { $currentRepositories = @($allRepositories | Where-Object { $setting -notcontains $_ }) }
					elseif ($setting -is [string]) { $currentRepositories = @($allRepositories | Where-Object { $_ -ne $setting }) }
				}
				if (@($currentRepositories).Count -eq 0) {
					$cache[$moduleNameToFetch] = [pscustomobject]@{
						ModuleName    = $moduleNameToFetch
						Stable        = $null
						PreRelease    = $null
						ErrorFetching = $null
						Skipped       = $true
						CachedAtUtc   = [DateTime]::UtcNow
					}
					New-Log "[$moduleNameToFetch] Pre-fetch: No repositories left to check after blacklist exclusion. Skipping." -Level VERBOSE
					return
				}
				$stableResult = $null
				$prereleaseResult = $null
				$fetchError = $null
				$swModule = [System.Diagnostics.Stopwatch]::StartNew()
				foreach ($repo in $currentRepositories) {
					if ($swModule.Elapsed.TotalSeconds -gt $perModuleBudget) {
						$fetchError = "Per-module time budget (${perModuleBudget}s) exceeded during stable search."
						break
					}
					try {
						$found = Find-PSResource -Name $moduleNameToFetch -Repository $repo -ErrorAction SilentlyContinue -Verbose:$false | Sort-Object -Property Version -Descending | Select-Object -First 1
						if ($found) {
							New-Log "[$moduleNameToFetch] Pre-fetch: Found stable version '$($found.Version)' in repository '$repo'." -Level VERBOSE
							$stableResult = $found
							break
						}
					}
					catch { $fetchError = "Stable search error in '$repo': $($_.Exception.Message)" }
				}
				$prereleaseRepos = if ($stableResult) { @($stableResult.Repository) } else { $currentRepositories }
				foreach ($repo in $prereleaseRepos) {
					if ($swModule.Elapsed.TotalSeconds -gt $perModuleBudget) { $fetchError = (@($fetchError, "Per-module time budget exceeded during prerelease search.") -join '; ').Trim('; ', ' '); break }
					try {
						$found = Find-PSResource -Name $moduleNameToFetch -Prerelease -Repository $repo -ErrorAction SilentlyContinue -Verbose:$false
						| Where-Object { $_.IsPrerelease } | Sort-Object -Property Version -Descending | Select-Object -First 1
						if ($found) {
							New-Log "[$moduleNameToFetch] Pre-fetch: Found prerelease version '$($found.Version)' in repository '$repo'." -Level VERBOSE
							$prereleaseResult = $found
							break
						}
					}
					catch { $fetchError = (@($fetchError, "Prerelease search error in '$repo': $($_.Exception.Message)") -join '; ').Trim('; ', ' ') }
				}
				$cache[$moduleNameToFetch] = [pscustomobject]@{
					ModuleName    = $moduleNameToFetch
					Stable        = $stableResult
					PreRelease    = $prereleaseResult
					ErrorFetching = $fetchError
					Skipped       = $false
					CachedAtUtc   = [DateTime]::UtcNow
				}
			} -AsJob
			$null = Wait-Job -Job $lookupJob -Timeout $stageTimeoutSeconds -ErrorAction SilentlyContinue
			if ($lookupJob.State -in @('Running', 'NotStarted')) {
				$stageTimedOut = $true
				Stop-Job -Job $lookupJob -ErrorAction SilentlyContinue 2>$null
			}
			elseif ($lookupJob.State -ne 'Completed') {
				New-Log "Online lookup job ended in state '$($lookupJob.State)'. Unfinished modules will be retried or reported." -Level WARNING
			}
		}
		catch {
			New-Log "Online lookup job failed." -Level ERROR
			if ($null -ne $lookupJob -and $lookupJob.State -in @('Running', 'NotStarted')) {
				Stop-Job -Job $lookupJob -ErrorAction SilentlyContinue 2>$null
			}
		}
		finally {
			if ($null -ne $lookupJob) {
				Receive-Job -Job $lookupJob -ErrorAction SilentlyContinue -WarningAction SilentlyContinue 2>$null | Out-Null
				Remove-Job -Job $lookupJob -Force -ErrorAction SilentlyContinue 2>$null
			}
		}
		$modulesPendingLookup = @($moduleDataArray | Where-Object { -not $onlineModuleVersionsCache.ContainsKey($_.ModuleName) })
		if ($stageTimedOut -and $modulesPendingLookup.Count -gt 0) {
			New-Log "Online lookup stage reached its ${stageTimeoutSeconds}s cap; $($modulesPendingLookup.Count) unfinished module(s) remain." -Level WARNING
		}
	}
	$preFetchTimeouts = 0
	foreach ($moduleEntry in $moduleDataArray) {
		if (-not $onlineModuleVersionsCache.ContainsKey($moduleEntry.ModuleName)) {
			New-Log "[$($moduleEntry.ModuleName)] No pre-fetched data found after all lookup attempts. Marking as error." -Level WARNING
			$onlineModuleVersionsCache[$moduleEntry.ModuleName] = [pscustomobject]@{
				ModuleName    = $moduleEntry.ModuleName
				Stable        = $null
				PreRelease    = $null
				ErrorFetching = "Data not found after online lookup timeout and retry."
				Skipped       = $false
				CachedAtUtc   = [DateTime]::UtcNow
			}
			$preFetchTimeouts++
		}
	}
	if ($OnlineCacheMinutes -gt 0) {
		$tempCachePath = "$OnlineCachePath.$PID.tmp"
		try {
			$cacheEntries = foreach ($moduleEntry in $moduleDataArray) {
				$lookupData = $null
				if (-not $onlineModuleVersionsCache.TryGetValue($moduleEntry.ModuleName, [ref]$lookupData)) { continue }
				if ($lookupData.Skipped -or -not [string]::IsNullOrWhiteSpace([string]$lookupData.ErrorFetching)) { continue }
				$cachedAtUtc = if ($lookupData.PSObject.Properties['CachedAtUtc']) { ([DateTime]$lookupData.CachedAtUtc).ToUniversalTime() } else { [DateTime]::UtcNow }
				[pscustomobject]@{
					ModuleName       = $moduleEntry.ModuleName
					CachedAtUtc      = $cachedAtUtc.ToString('o')
					CachedAtUtcTicks = $cachedAtUtc.Ticks
					Stable           = ConvertTo-OnlineCacheResource -Resource $lookupData.Stable
					PreRelease       = ConvertTo-OnlineCacheResource -Resource $lookupData.PreRelease
				}
			}
			$cacheDirectory = Split-Path -Path $OnlineCachePath -Parent
			if (-not [string]::IsNullOrWhiteSpace($cacheDirectory) -and -not (Test-Path -LiteralPath $cacheDirectory -PathType Container)) {
				$null = New-Item -ItemType Directory -Path $cacheDirectory -Force -ErrorAction Stop
			}
			$cacheDocumentToSave = [pscustomobject]@{
				SchemaVersion    = 2
				ConfigurationKey = $onlineCacheConfigurationKey
				WrittenAtUtc     = [DateTime]::UtcNow.ToString('o')
				Entries          = @($cacheEntries)
			}
			$cacheDocumentToSave | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $tempCachePath -Encoding utf8 -ErrorAction Stop
			Move-Item -LiteralPath $tempCachePath -Destination $OnlineCachePath -Force -ErrorAction Stop
			New-Log "Online lookup cache saved with $(@($cacheEntries).Count) successful entry/entries." -Level VERBOSE
		}
		catch {
			New-Log "Online lookup cache could not be saved." -Level ERROR
		}
		finally {
			if (Test-Path -LiteralPath $tempCachePath -PathType Leaf) {
				Remove-Item -LiteralPath $tempCachePath -Force -ErrorAction SilentlyContinue
			}
		}
	}
	$prefetchSync = @{ timeouts = $preFetchTimeouts; completed = ($onlineModuleVersionsCache.Count - $preFetchTimeouts); total = $moduleDataArray.Count }
	$preFetchDuration = (Get-Date) - $overallOperationStartTime
	$results = [System.Collections.Concurrent.ConcurrentBag[object]]::new()
	$comparisonErrors = [System.Collections.Concurrent.ConcurrentBag[string]]::new()
	$NewLogDef = ${function:New-Log}.ToString()
	$CompareModuleVersionDef = ${function:Compare-ModuleVersion}.ToString()
	$moduleDataArray | ForEach-Object -ThrottleLimit $ThrottleLimit -Parallel {
		$script:ErrorActionPreference = 'Continue'
		$moduleData = $_
		$moduleName = $moduleData.ModuleName
		$comparisonErrors = $using:comparisonErrors
		$VerbosePreference = $using:VerbosePreference
		${function:New-Log} = $using:NewLogDef
		${function:Compare-ModuleVersion} = $using:CompareModuleVersionDef
		$results = $using:results
		$matchAuthor = $using:MatchAuthor.IsPresent
		$onlineCache = $using:onlineModuleVersionsCache
		try {
			$highestLocalInstall = $moduleData.HighestLocalInstall
			if (-not $highestLocalInstall) {
				New-Log "[$moduleName] Pre-processed HighestLocalInstall object missing. Skipping." -Level WARNING
				$comparisonErrors.Add("$moduleName`: missing local version data")
				return
			}
			$onlineModuleData = $null
			if (-not $onlineCache.TryGetValue($moduleName, [ref]$onlineModuleData)) {
				New-Log "[$moduleName] Could not retrieve pre-fetched data from cache. Skipping." -Level WARNING
				$comparisonErrors.Add("$moduleName`: lookup cache entry missing")
				return
			}
			if ($onlineModuleData.Skipped -or (-not $onlineModuleData.Stable -and -not $onlineModuleData.PreRelease -and $onlineModuleData.ErrorFetching)) {
				if ($onlineModuleData.Skipped) {
					New-Log "[$moduleName] Skipped by repository exclusion." -Level VERBOSE
				}
				else {
					$comparisonErrors.Add("$moduleName`: $($onlineModuleData.ErrorFetching)")
					New-Log "[$moduleName] Repository lookup failed: $($onlineModuleData.ErrorFetching)" -Level WARNING
				}
				return
			}
			$stableModule = $onlineModuleData.Stable
			$preReleaseModule = $onlineModuleData.PreRelease
			$galleryModule = $null
			if ($stableModule -and $preReleaseModule) {
				$stableVerStr = $stableModule.Version.ToString()
				$prereleaseVerStr = $preReleaseModule.Version.ToString()
				$prereleaseLbl = $preReleaseModule.PSObject.Properties['PreRelease'].Value
				$fullPrereleaseVerStr = if (-not [string]::IsNullOrEmpty($prereleaseLbl)) { "$prereleaseVerStr-$prereleaseLbl" } else { $prereleaseVerStr }
				try {
					$isPreReleaseNewer = Compare-ModuleVersion -VersionA $stableVerStr -VersionB $fullPrereleaseVerStr -ReturnBoolean
					$galleryModule = if ($isPreReleaseNewer) { $preReleaseModule } else { $stableModule }
				}
				catch {
					$galleryModule = $stableModule
					$comparisonErrors.Add("$moduleName`: could not compare stable and prerelease versions")
					New-Log "[$moduleName] Could not compare stable '$stableVerStr' with prerelease '$fullPrereleaseVerStr'; using stable" -Level ERROR
				}
			}
			elseif ($preReleaseModule) {
				$galleryModule = $preReleaseModule
			}
			elseif ($stableModule) {
				$galleryModule = $stableModule
			}
			if (-not $galleryModule) {
				New-Log "[$moduleName] No valid online version found. Skipping." -Level WARNING
				return
			}
			[string]$latestOnlineStr = if ($galleryModule.PSObject.Properties['PreRelease'].Value) {
				"$($galleryModule.Version)-$($galleryModule.PSObject.Properties['PreRelease'].Value)".Trim()
			}
			else {
				"$($galleryModule.Version)".Trim()
			}
			[string]$highestLocalStr = if ($highestLocalInstall.IsPrerelease -and $highestLocalInstall.PreReleaseLabel) {
				"$($highestLocalInstall.ModuleVersion)-$($highestLocalInstall.PreReleaseLabel)"
			}
			else {
				"$($highestLocalInstall.ModuleVersion)"
			}
			if ([string]::IsNullOrWhiteSpace($latestOnlineStr) -or [string]::IsNullOrWhiteSpace($highestLocalStr)) {
				New-Log "[$moduleName] Invalid online ('$latestOnlineStr') or local ('$highestLocalStr') version string. Skipping." -Level WARNING
				$comparisonErrors.Add("$moduleName`: invalid version data")
				return
			}
			$needsOverallUpdate = $false
			try {
				if (Compare-ModuleVersion -VersionA $highestLocalStr -VersionB $latestOnlineStr -ReturnBoolean) {
					$needsOverallUpdate = $true
				}
			}
			catch {
				New-Log "[$moduleName] Error comparing versions $highestLocalStr and $latestOnlineStr." -Level ERROR
				$comparisonErrors.Add("$moduleName`: version comparison failed")
				return
			}
			if ($needsOverallUpdate -and $matchAuthor) {
				$localAuthor = $highestLocalInstall.Author
				$galleryAuthor = $galleryModule.Author
				$authorsMatch = $false
				$normalizedLocalAuthor = [Regex]::Replace([string]$localAuthor, '[^a-zA-Z0-9]', '')
				$normalizedGalleryAuthor = [Regex]::Replace([string]$galleryAuthor, '[^a-zA-Z0-9]', '')
				if ($normalizedLocalAuthor -and $normalizedGalleryAuthor -and $normalizedGalleryAuthor -eq $normalizedLocalAuthor) {
					$authorsMatch = $true
				}
				if (-not $authorsMatch) {
					New-Log "[$moduleName] Skipping update: -MatchAuthor specified and authors do not match (Local: '$localAuthor', Online: '$galleryAuthor')." -Level VERBOSE
					$needsOverallUpdate = $false
				}
			}
			if ($needsOverallUpdate) {
				$outdatedInstallationsDetailed = @()
				$allLocalInstalls = $moduleData.AllParsedVersions
				$installsByPath = $allLocalInstalls | Group-Object -Property BasePath
				foreach ($pathGroup in $installsByPath) {
					$versionsInThisPath = $pathGroup.Group
					$latestOnlineVersionFoundInThisPath = $false
					foreach ($installedVersionEntry in $versionsInThisPath) {
						if ($installedVersionEntry.ModuleVersionString -eq $latestOnlineStr) {
							$latestOnlineVersionFoundInThisPath = $true; break
						}
					}
					if (-not $latestOnlineVersionFoundInThisPath) {
						foreach ($outdatedInstall in $versionsInThisPath) {
							$outdatedInstallationsDetailed += [PSCustomObject]@{
								Path             = $outdatedInstall.BasePath
								InstalledVersion = $outdatedInstall.ModuleVersionString
							}
						}
					}
				}
				if ($outdatedInstallationsDetailed.Count -gt 0) {
					$uniqueOutdatedModules = $outdatedInstallationsDetailed | Sort-Object Path, InstalledVersion -Unique
					$resultObject = [PSCustomObject]@{
						ModuleName          = $moduleName
						Repository          = $galleryModule.Repository
						IsPreview           = if ($galleryModule.PSObject.Properties['PreRelease'].Value) { $true } else { $false }
						PreReleaseVersion   = $galleryModule.PSObject.Properties['PreRelease'].Value
						HighestLocalVersion = $highestLocalInstall.ModuleVersion
						LatestVersion       = [version]($galleryModule.Version.ToString() -replace '-.*$', '')
						LatestVersionString = $latestOnlineStr
						OutdatedModules     = $uniqueOutdatedModules
						Author              = $highestLocalInstall.Author
						GalleryAuthor       = $galleryModule.Author
					}
					$results.Add($resultObject)
					New-Log "[$moduleName] Update found: Local '$highestLocalStr' -> Online '$latestOnlineStr'. $($uniqueOutdatedModules.Count) outdated paths." -Level SUCCESS
				}
				else {
					New-Log "[$moduleName] Version '$latestOnlineStr' is newer, but no installation path requiring it was found." -Level WARNING
				}
			}
		}
		catch {
			$comparisonErrors.Add("$moduleName`: $($_.Exception.Message)")
			New-Log "[$moduleName] Unhandled comparison error." -Level ERROR
		}
	}
	$moduleObjects = @($results)
	$finalOverallTime = (Get-Date) - $overallOperationStartTime
	$comparisonDuration = $finalOverallTime - $preFetchDuration
	$updateCheckLevel = if ($preFetchTimeouts -gt 0 -or $comparisonErrors.Count -gt 0) { 'WARNING' } else { 'SUCCESS' }
	New-Log "Update check complete: $validModuleCountForProcessing module(s) checked in $([math]::Round($finalOverallTime.TotalSeconds, 2)) seconds (lookup $([math]::Round($preFetchDuration.TotalSeconds, 2))s, comparison $([math]::Round($comparisonDuration.TotalSeconds, 2))s); found $($moduleObjects.Count) update(s), $preFetchTimeouts timeout(s), and $($comparisonErrors.Count) comparison error(s)." -Level $updateCheckLevel
	if ($prefetchSync.timeouts -gt 0) {
		New-Log "$($prefetchSync.timeouts) module pre-fetch checks timed out." -Level WARNING
	}
	if ($comparisonErrors.Count -gt 0) {
		New-Log "Comparison errors: $(@($comparisonErrors) -join '; ')" -Level WARNING
	}
	return $moduleObjects | Sort-Object ModuleName
}
#endregion Get-ModuleUpdateStatus
#region Update-Modules
function Update-Modules {
	<#
    .SYNOPSIS
    Installs available module updates.
    .DESCRIPTION
    Validates update records and ShouldProcess decisions on the caller thread, installs
    approved modules concurrently, and optionally removes older versions sequentially.
    Flat module layouts are preserved unless a locked module policy is selected.
    .PARAMETER OutdatedModules
    Update records returned by Get-ModuleUpdateStatus. Accepts pipeline input.
    .PARAMETER MaxUpdateNumber
    Maximum number of module update records to process. The minimum is 1. When
    omitted, all supplied update records are processed.
    .PARAMETER Clean
    Removes older versions after the new version is installed successfully.
    .PARAMETER UseProgressBar
    Displays the script's post-processing progress bar. Progress emitted internally by
    PSResourceGet remains suppressed so this switch is the only progress display.
    .PARAMETER PreRelease
    Allows prerelease targets supplied by the input records.
    .PARAMETER ReplaceLockedModuleOnReboot
    For a locked flat module, stages replacement files and schedules the in-place update
    for the next Windows restart. During cleanup, old version folders that cannot be
    removed (locked files or access denied) are scheduled for deletion on the next restart.
    .PARAMETER AllowVersionedSubfolder
    For a locked flat module, installs the update in a versioned subfolder instead of
    preserving the flat layout.
    .PARAMETER OnlyCleanUpOldModules
    Cleanup-only mode: skips the update check and install steps entirely, scans the
    module inventory, and removes older version folders while keeping the highest
    version found in each path. Never removes folders newer than the retained version.
    .PARAMETER ModuleInventory
    Inventory from Get-ModuleInfo used by -OnlyCleanUpOldModules. Defaults to the
    $script:moduleInfo inventory collected earlier in the session. Cleanup-only mode
    does not scan the filesystem for additional module versions.
    .PARAMETER CleanupBackupPath
    Root folder that receives a <ModuleName>\<ModuleName>_<version>.zip backup of every
    version folder before it is removed. When a backup fails that folder is not removed.
    .INPUTS
    System.Management.Automation.PSCustomObject.
    .OUTPUTS
    System.Management.Automation.PSCustomObject. Each result reports updated, failed,
    cleaned, failed-clean, clean-pending-reboot, backup, and pending-reboot paths.
    .EXAMPLE
    Get-ModuleUpdateStatus -ModuleInventory $inventory |
        Update-Modules -Clean -ReplaceLockedModuleOnReboot
    Installs updates, cleans older versions, and schedules locked flat modules for restart.
    .EXAMPLE
    Get-ModuleUpdateStatus -ModuleInventory $inventory |
        Update-Modules -Clean -MaxUpdateNumber 5 -WhatIf
    Reports the first five updates, including versions, repositories, paths, and
    cleanup actions, without changing any modules.
    .EXAMPLE
    Update-Modules -OnlyCleanUpOldModules -CleanupBackupPath 'D:\ModuleBackups'
    Removes old module versions only (no update check), zipping each one to the backup
    path first and keeping the highest version per path.
    .NOTES
    ReplaceLockedModuleOnReboot and AllowVersionedSubfolder are mutually exclusive.
    Administrative rights may be required for system module paths and reboot scheduling.
    .LINK
    Get-ModuleUpdateStatus
    #>
	[CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'Update')]
	param (
		[Parameter(ParameterSetName = 'Update', ValueFromPipeline, Mandatory)][Object[]]$OutdatedModules,
		[Parameter(ParameterSetName = 'Update')][ValidateRange(1, [int]::MaxValue)][int]$MaxUpdateNumber,
		[Parameter(ParameterSetName = 'Update')][switch]$Clean,
		[switch]$UseProgressBar,
		[Parameter(ParameterSetName = 'Update')][switch]$PreRelease,
		[switch]$ReplaceLockedModuleOnReboot,
		[Parameter(ParameterSetName = 'Update')][switch]$AllowVersionedSubfolder,
		[Parameter(ParameterSetName = 'CleanupOnly', Mandatory)][switch]$OnlyCleanUpOldModules,
		[Parameter(ParameterSetName = 'CleanupOnly')][System.Collections.IDictionary]$ModuleInventory,
		[string]$CleanupBackupPath
	)
	begin {
		if ($ReplaceLockedModuleOnReboot -and $AllowVersionedSubfolder) {
			throw "Parameters -ReplaceLockedModuleOnReboot and -AllowVersionedSubfolder are mutually exclusive. Specify at most one (or neither)."
		}
		if ($CleanupBackupPath -and -not $WhatIfPreference) {
			try {
				if (-not (Test-Path -LiteralPath $CleanupBackupPath -PathType Container)) {
					$null = New-Item -ItemType Directory -Path $CleanupBackupPath -Force -ErrorAction Stop
				}
			}
			catch {
				throw "The -CleanupBackupPath '$CleanupBackupPath' does not exist and could not be created: $($_.Exception.Message)"
			}
		}
		$aggregateResults = [System.Collections.Generic.List[object]]::new()
		$batchModules = @()
		$updateStartTime = Get-Date
		$whatIfMode = [bool]$WhatIfPreference
	}
	process {
		foreach ($module in $OutdatedModules) {
			$batchModules += $module
		}
	}
	end {
		if ($PSCmdlet.ParameterSetName -eq 'CleanupOnly') {
			$cleanupInventory = $ModuleInventory
			if (-not $cleanupInventory -or $cleanupInventory.Count -eq 0) {
				$cleanupInventory = $script:moduleInfo # Reuses the inventory that Get-ModuleInfo already collected in this session.
			}
			if (-not $cleanupInventory -or $cleanupInventory.Count -eq 0) {
				New-Log "Cleanup-only mode requires -ModuleInventory or an existing `$script:moduleInfo inventory. Nothing to do." -Level WARNING
				return
			}
			$cleanupModuleNames = @($cleanupInventory.Keys)
			New-Log "Cleanup-only mode: checking $($cleanupModuleNames.Count) module(s) for old versions (keeping the highest version per path)..."
			$cleanupIndex = 0
			foreach ($cleanupModuleName in $cleanupModuleNames) {
				$cleanupIndex++
				if ($UseProgressBar.IsPresent) {
					$progressParams = @{
						Activity        = "Cleaning up old module versions"
						Status          = "Checking: $cleanupModuleName"
						PercentComplete = [math]::Round(($cleanupIndex / $cleanupModuleNames.Count) * 100)
					}
					Write-Progress @progressParams
				}
				$moduleRecords = @($cleanupInventory[$cleanupModuleName]) | Where-Object { $null -ne $_ -and -not [string]::IsNullOrWhiteSpace($_.BasePath) }
				$recordsByPath = $moduleRecords | Group-Object -Property BasePath
				foreach ($pathGroup in $recordsByPath) {
					$cleanupBasePath = $pathGroup.Name
					$versionRecords = @($pathGroup.Group | Group-Object -Property @{ Expression = {
								if ("$($_.ModuleVersionString)" -match '-') { $_.ModuleVersionString } elseif ($_.IsPreRelease -and $_.PreReleaseLabel) { "$($_.ModuleVersionString)-$($_.PreReleaseLabel)" } else { $_.ModuleVersionString }
							}
						} | ForEach-Object { $_.Group[0] })
					if ($versionRecords.Count -le 1) {
						continue
					}
					$knownAuthors = @($versionRecords | ForEach-Object {
							$normalizedAuthor = [Regex]::Replace([string]$_.Author, '[^a-zA-Z0-9]', '').ToLowerInvariant()
							if ($normalizedAuthor) { $normalizedAuthor }
						} | Select-Object -Unique)
					$authorsCompatible = $true
					for ($authorIndex = 0; $authorIndex -lt $knownAuthors.Count -and $authorsCompatible; $authorIndex++) {
						for ($compareIndex = $authorIndex + 1; $compareIndex -lt $knownAuthors.Count; $compareIndex++) {
							$authorA = $knownAuthors[$authorIndex]
							$authorB = $knownAuthors[$compareIndex]
							if (-not ($authorA.Contains($authorB) -or $authorB.Contains($authorA))) {
								$authorsCompatible = $false
								break
							}
						}
					}
					if (-not $authorsCompatible) {
						$authorDetails = @($versionRecords | ForEach-Object { "$($_.ModuleVersionString)='$($_.Author)'" }) -join ', '
						New-Log "[$cleanupModuleName] Skipping cleanup at '$cleanupBasePath': installed versions have incompatible authors ($authorDetails). This may be a repository name collision." -Level WARNING
						continue
					}
					$keepRecord = $versionRecords | Sort-Object -Property @{E = { $_.ModuleVersion }; Descending = $true }, @{E = { $_.IsPreRelease }; Ascending = $true } | Select-Object -First 1
					$keepVersionFullString = if ("$($keepRecord.ModuleVersionString)" -match '-') { $keepRecord.ModuleVersionString } elseif ($keepRecord.IsPreRelease -and $keepRecord.PreReleaseLabel) { "$($keepRecord.ModuleVersionString)-$($keepRecord.PreReleaseLabel)" } else { $keepRecord.ModuleVersionString }
					$parsedKeep = Parse-ModuleVersion -VersionString $keepVersionFullString -ErrorAction SilentlyContinue
					if (-not $parsedKeep -or -not $parsedKeep.ModuleVersion) {
						New-Log "[$cleanupModuleName] Skipping cleanup at '$cleanupBasePath': could not parse the version to keep from '$keepVersionFullString'." -Level WARNING
						continue
					}
					$keepPreReleaseVersion = if ($parsedKeep.IsPrerelease) { $keepVersionFullString } else { $null }
					$oldVersionPaths = [System.Collections.Generic.List[string]]::new()
					foreach ($oldRecord in @($versionRecords | Where-Object { $_ -ne $keepRecord })) {
						$recordVersionString = if ("$($oldRecord.ModuleVersionString)" -match '-') { $oldRecord.ModuleVersionString } elseif ($oldRecord.IsPreRelease -and $oldRecord.PreReleaseLabel) { "$($oldRecord.ModuleVersionString)-$($oldRecord.PreReleaseLabel)" } else { $oldRecord.ModuleVersionString }
						$versionFolderPath = Join-Path -Path $cleanupBasePath -ChildPath $recordVersionString
						if (Test-Path -LiteralPath $versionFolderPath -PathType Container) {
							$oldVersionPaths.Add($versionFolderPath)
							continue
						}
						$flatManifestPath = Join-Path -Path $cleanupBasePath -ChildPath "$cleanupModuleName.psd1"
						if (Test-Path -LiteralPath $flatManifestPath -PathType Leaf) {
							try {
								$flatManifestData = Import-PowerShellDataFile -LiteralPath $flatManifestPath -ErrorAction Stop
								$flatVersionString = [string]$flatManifestData.ModuleVersion
								$flatPreRelease = if ($flatManifestData.PrivateData -and $flatManifestData.PrivateData.PSData) { [string]$flatManifestData.PrivateData.PSData.Prerelease } else { $null }
								if ($flatPreRelease) { $flatVersionString = "$flatVersionString-$flatPreRelease" }
								if ($flatVersionString -eq $recordVersionString) {
									$oldVersionPaths.Add($cleanupBasePath)
									continue
								}
							}
							catch {
								New-Log "[$cleanupModuleName] Could not inspect flat manifest '$flatManifestPath': $($_.Exception.Message)" -Level WARNING
							}
						}
						New-Log "[$cleanupModuleName] Inventory version '$recordVersionString' has no matching installed path below '$cleanupBasePath'. Skipping that record." -Level WARNING
					}
					if ($oldVersionPaths.Count -eq 0) { continue }
					$cleanResult = Remove-OutdatedVersions -ModuleName $cleanupModuleName -ModuleBasePaths @($cleanupBasePath) -LatestVersion $parsedKeep.ModuleVersion -PreReleaseVersion $keepPreReleaseVersion -CleanupBackupPath $CleanupBackupPath -ReplaceLockedModuleOnReboot:$ReplaceLockedModuleOnReboot -OnlyRemoveOlderThanLatest -CandidateVersionPaths @($oldVersionPaths) -WhatIf:$whatIfMode -ErrorAction SilentlyContinue
					if ($cleanResult -and $cleanResult.OldVersionCount -gt 0) {
						$cleanupStatus = if ($whatIfMode) { 'WhatIf' } else { Get-CleanStatusFromResult -CleanResult $cleanResult }
						$aggregateResults.Add([PSCustomObject]@{
								ModuleName              = $cleanupModuleName
								BasePath                = $cleanupBasePath
								KeptVersion             = $keepVersionFullString
								OldVersionCount         = $cleanResult.OldVersionCount
								CleanedPaths            = @($cleanResult.CleanedPaths)
								FailedCleanPaths        = @($cleanResult.FailedPaths)
								CleanPendingRebootPaths = @($cleanResult.PendingRebootPaths)
								BackupPaths             = @($cleanResult.BackupPaths)
								CleanStatus             = $cleanupStatus
							})
					}
				}
			}
			if ($UseProgressBar.IsPresent) {
				Write-Progress -Activity "Cleaning up old module versions" -Completed
			}
			$cleanupDuration = (Get-Date) - $updateStartTime
			$totalCleanedCount = @($aggregateResults | ForEach-Object { $_.CleanedPaths }).Count
			$totalFailedCount = @($aggregateResults | ForEach-Object { $_.FailedCleanPaths }).Count
			$totalPendingCount = @($aggregateResults | ForEach-Object { $_.CleanPendingRebootPaths }).Count
			$totalBackupCount = @($aggregateResults | ForEach-Object { $_.BackupPaths }).Count
			if ($whatIfMode) {
				New-Log "WhatIf cleanup preview complete: $($aggregateResults.Count) module path(s) hold old versions; no changes were made." -Level SUCCESS
			}
			else {
				$cleanupSummaryLevel = if ($totalFailedCount -gt 0) { 'WARNING' } else { 'SUCCESS' }
				New-Log "Cleanup-only complete: $($cleanupModuleNames.Count) module(s) checked in $([math]::Round($cleanupDuration.TotalSeconds, 2)) seconds; $totalCleanedCount old folder(s) removed, $totalFailedCount failed, $totalPendingCount pending reboot, $totalBackupCount backed up." -Level $cleanupSummaryLevel
			}
			if ($totalFailedCount -gt 0 -and -not $ReplaceLockedModuleOnReboot.IsPresent) {
				New-Log "Some old versions could not be removed (locked files or access denied). Re-run with -ReplaceLockedModuleOnReboot to schedule them for deletion on the next restart." -Level WARNING
			}
			return $aggregateResults
		}
		if ($batchModules.Count -eq 0) {
			New-Log "No modules provided for update. Exiting."
			return
		}
		$availableTotal = $batchModules.Count
		if ($PSBoundParameters.ContainsKey('MaxUpdateNumber') -and $availableTotal -gt $MaxUpdateNumber) {
			$batchModules = @($batchModules | Select-Object -First $MaxUpdateNumber)
			New-Log "Limiting this run to $MaxUpdateNumber of $availableTotal available module update(s); $($availableTotal - $MaxUpdateNumber) deferred."
		}
		$total = $batchModules.Count
		New-Log "Preparing $total module update(s)..."
		$modulesToInstall = [System.Collections.Generic.List[object]]::new()
		$current = 0
		foreach ($module in $batchModules) {
			$moduleName = $module.ModuleName
			$current++
			[string]$targetVersionString = $($module.LatestVersion)
			[version]$latestVer = $null
			if ($module.isPreView) {
				$parsedTargetVersion = Parse-ModuleVersion -VersionString "$($targetVersionString)-$($module.PreReleaseVersion)" -ErrorAction SilentlyContinue
				[string]$preReleaseVersion = $parsedTargetVersion.PreReleaseVersion
			}
			else {
				$parsedTargetVersion = Parse-ModuleVersion -VersionString $targetVersionString -ErrorAction SilentlyContinue
				[string]$preReleaseVersion = $null
			}
			if (-not $parsedTargetVersion -or -not $parsedTargetVersion.ModuleVersion) {
				New-Log "[$current/$total] Skipping module [$moduleName]: Could not parse Target Version String '$targetVersionString' using Parse-ModuleVersion. Will skip." -Level WARNING
				$aggregateResults.Add([PSCustomObject]@{
						ModuleName              = $moduleName
						NewVersionPreRelease    = if ($module.IsPreview) { "$($targetVersionString)-$($module.PreReleaseVersion)" }
						NewVersion              = $targetVersionString
						UpdatedPaths            = @()
						FailedPaths             = @("Version parsing failed: $targetVersionString")
						PendingRebootPaths      = @()
						PendingReboot           = $false
						OverallSuccess          = $false
						CleanedPaths            = @()
						FailedCleanPaths        = @()
						CleanPendingRebootPaths = @()
						BackupPaths             = @()
						CleanStatus             = if ($Clean.IsPresent) { 'NotRun' } else { 'NotRequested' }
					})
				continue
			}
			$latestVer = $parsedTargetVersion.ModuleVersion
			[string]$baseVerStr = $latestVer.ToString()
			$repository = $module.Repository
			$installAsPreview = $parsedTargetVersion.IsPrerelease
			if ($installAsPreview -and -not $PreRelease.IsPresent) {
				New-Log "[$moduleName] Skipping prerelease '$preReleaseVersion'; specify -PreRelease to install it." -Level WARNING
				$aggregateResults.Add([PSCustomObject]@{
						ModuleName              = $moduleName
						NewVersionPreRelease    = $preReleaseVersion
						NewVersion              = $baseVerStr
						UpdatedPaths            = @()
						FailedPaths             = @('Prerelease updates require -PreRelease')
						PendingRebootPaths      = @()
						PendingReboot           = $false
						OverallSuccess          = $false
						CleanedPaths            = @()
						FailedCleanPaths        = @()
						CleanPendingRebootPaths = @()
						BackupPaths             = @()
						CleanStatus             = if ($Clean.IsPresent) { 'NotRun' } else { 'NotRequested' }
					})
				continue
			}
			$outdatedPaths = @($module.OutdatedModules | Where-Object { $null -ne $_.Path } | Select-Object -ExpandProperty Path -Unique | Where-Object { $_ -and (Test-Path $_ -PathType Container -Verbose:$false) })
			$outdatedVersions = @($module.OutdatedModules.InstalledVersion | Select-Object -Unique)
			if ($outdatedPaths.Count -eq 0) {
				New-Log "[$moduleName][$current/$total] Skipping module: No valid outdated base paths found where old versions exist. (Checked: $($module.OutdatedModules.Path -join '; '))." -Level WARNING
				$aggregateResults.Add([PSCustomObject]@{
						ModuleName              = $moduleName
						NewVersionPreRelease    = if ($module.IsPreview) { $preReleaseVersion }
						NewVersion              = $baseVerStr
						UpdatedPaths            = @()
						FailedPaths             = @("No valid source paths provided or accessible")
						PendingRebootPaths      = @()
						PendingReboot           = $false
						OverallSuccess          = $false
						CleanedPaths            = @()
						FailedCleanPaths        = @()
						CleanPendingRebootPaths = @()
						BackupPaths             = @()
						CleanStatus             = if ($Clean.IsPresent) { 'NotRun' } else { 'NotRequested' }
					})
				continue
			}
			New-Log "[$moduleName] Target base paths based on outdated locations: $($outdatedPaths -join '; ')" -Level VERBOSE
			$displayVersion = if ($installAsPreview -and $preReleaseVersion) { $preReleaseVersion } else { $targetVersionString }
			# ShouldProcess must run before work is dispatched to parallel runspaces.
			$installApproved = $PSCmdlet.ShouldProcess("$moduleName v$displayVersion", "Update from version(s) $($outdatedVersions -join ', ') using repository '$repository' at paths: $($outdatedPaths -join ', ')")
			$cleanApproved = $false
			if ($Clean.IsPresent -and ($installApproved -or $whatIfMode)) {
				$cleanApproved = $PSCmdlet.ShouldProcess("$moduleName (Versions: $($outdatedVersions -join ', '))", "Remove outdated versions from paths: $($outdatedPaths -join ', ')")
			}
			if ($installApproved) {
				$modulesToInstall.Add([PSCustomObject]@{
						ModuleName          = $moduleName
						TargetVersionString = $targetVersionString
						PreReleaseVersion   = $preReleaseVersion
						BaseVerStr          = $baseVerStr
						Repository          = $repository
						InstallAsPreview    = $installAsPreview
						OutdatedPaths       = $outdatedPaths
						OutdatedVersions    = $outdatedVersions
						LatestVer           = $latestVer
						IsPreview           = [bool]$module.IsPreview
						CleanApproved       = $cleanApproved
					})
			}
			else {
				if ($whatIfMode) {
					New-Log "[WhatIf][$moduleName][$current/$total] Would update version(s) [$($outdatedVersions -join ', ')] to [$displayVersion] from '$repository' at: $($outdatedPaths -join '; ')"
					$aggregateResults.Add([PSCustomObject]@{
							ModuleName              = $moduleName
							Status                  = 'WhatIf'
							CurrentVersions         = @($outdatedVersions)
							NewVersionPreRelease    = if ($module.IsPreview) { $preReleaseVersion }
							NewVersion              = $baseVerStr
							Repository              = $repository
							TargetPaths             = @($outdatedPaths)
							WouldClean              = $Clean.IsPresent
							UpdatedPaths            = @()
							FailedPaths             = @()
							PendingRebootPaths      = @()
							PendingReboot           = $false
							OverallSuccess          = $null
							CleanedPaths            = @()
							FailedCleanPaths        = @()
							CleanPendingRebootPaths = @()
							BackupPaths             = @()
							CleanStatus             = if ($Clean.IsPresent) { 'WhatIf' } else { 'NotRequested' }
						})
				}
				else {
					New-Log "[$moduleName][$current/$total] Skipped update due to ShouldProcess user choice." -Level WARNING
					$aggregateResults.Add([PSCustomObject]@{
							ModuleName              = $moduleName
							NewVersionPreRelease    = if ($module.IsPreview) { $preReleaseVersion }
							NewVersion              = $baseVerStr
							UpdatedPaths            = @()
							FailedPaths             = @("Skipped by ShouldProcess")
							PendingRebootPaths      = @()
							PendingReboot           = $false
							OverallSuccess          = $false
							CleanedPaths            = @()
							FailedCleanPaths        = @()
							CleanPendingRebootPaths = @()
							BackupPaths             = @()
							CleanStatus             = if ($Clean.IsPresent) { 'NotRun' } else { 'NotRequested' }
						})
				}
			}
		}
		if ($modulesToInstall.Count -eq 0) {
			if ($whatIfMode) {
				$whatIfCount = @($aggregateResults | Where-Object Status -EQ 'WhatIf').Count
				New-Log "WhatIf preview complete: $whatIfCount module update(s) would be performed; no changes were made." -Level SUCCESS
			}
			else {
				New-Log "No modules approved for installation after pre-processing. Exiting."
			}
			return $aggregateResults
		}
		$psResourceGetModule = Get-Module -Name 'Microsoft.PowerShell.PSResourceGet' | Sort-Object Version -Descending | Select-Object -First 1
		if (-not $psResourceGetModule) {
			$psResourceGetModule = Import-Module -Name 'Microsoft.PowerShell.PSResourceGet' -PassThru -ErrorAction Stop -Verbose:$false | Sort-Object Version -Descending | Select-Object -First 1
		}
		$psResourceGetManifestPath = Join-Path -Path $psResourceGetModule.ModuleBase -ChildPath 'Microsoft.PowerShell.PSResourceGet.psd1'
		$psResourceGetModulePath = if (Test-Path -LiteralPath $psResourceGetManifestPath -PathType Leaf) { $psResourceGetManifestPath } else { [string]$psResourceGetModule.Path }
		if ([string]::IsNullOrWhiteSpace($psResourceGetModulePath)) {
			throw 'Microsoft.PowerShell.PSResourceGet is loaded, but its module path could not be resolved for the parallel installer runspaces.'
		}
		$installThrottleLimit = [Math]::Min($modulesToInstall.Count, [Math]::Max(4, [System.Environment]::ProcessorCount * 2))
		New-Log "Installing $($modulesToInstall.Count) module update(s) in parallel (throttle $installThrottleLimit)..."
		$parallelInstallResults = [System.Collections.Concurrent.ConcurrentBag[object]]::new()
		$parallelStartTime = Get-Date
		$NewLogDef = ${function:New-Log}.ToString()
		$InstallPSModuleDef = ${function:Install-PSModule}.ToString()
		$replaceLockedOnReboot = $ReplaceLockedModuleOnReboot.IsPresent
		$allowVersionedSubfolder = $AllowVersionedSubfolder.IsPresent
		$useClean = $Clean.IsPresent
		$modulesToInstall | ForEach-Object -ThrottleLimit $installThrottleLimit -Parallel {
			$script:ErrorActionPreference = 'Continue'
			$preparedModule = $_
			$moduleName = $preparedModule.ModuleName
			$VerbosePreference = $using:VerbosePreference
			$parallelInstallResults = $using:parallelInstallResults
			${function:New-Log} = $using:NewLogDef
			${function:Install-PSModule} = $using:InstallPSModuleDef
			try {
				if (-not (Get-Module -Name 'Microsoft.PowerShell.PSResourceGet')) {
					Import-Module -Name $using:psResourceGetModulePath -ErrorAction Stop -Verbose:$false
				}
				New-Log "[$moduleName] Installing version [$($preparedModule.TargetVersionString)]..." -Level VERBOSE
				$installResult = Install-PSModule -ModuleName $moduleName -TargetVersionString $preparedModule.TargetVersionString -PreReleaseVersion $preparedModule.PreReleaseVersion -RepositoryName $preparedModule.Repository -IsPreview $preparedModule.InstallAsPreview -Destinations $preparedModule.OutdatedPaths -ReplaceLockedModuleOnReboot $using:replaceLockedOnReboot -AllowVersionedSubfolder $using:allowVersionedSubfolder -ErrorAction SilentlyContinue
				$pendingRebootPaths = @($installResult.PendingRebootPaths)
				$finalResult = [PSCustomObject]@{
					ModuleName              = $moduleName
					NewVersionPreRelease    = if ($preparedModule.IsPreview) { $preparedModule.PreReleaseVersion }
					NewVersion              = $preparedModule.BaseVerStr
					UpdatedPaths            = @($installResult.UpdatedPaths)
					FailedPaths             = if ($installResult.FailedPaths) { @($installResult.FailedPaths) } else { @() }
					PendingRebootPaths      = $pendingRebootPaths
					PendingReboot           = ($pendingRebootPaths.Count -gt 0)
					OverallSuccess          = (@($installResult.FailedPaths).Count -eq 0 -and @($installResult.UpdatedPaths).Count -gt 0)
					CleanedPaths            = @()
					FailedCleanPaths        = @()
					CleanPendingRebootPaths = @()
					BackupPaths             = @()
					CleanStatus             = 'NotRequested'
					_OutdatedVersions       = $preparedModule.OutdatedVersions
					_LatestVer              = $preparedModule.LatestVer
					_PreReleaseVersion      = $preparedModule.PreReleaseVersion
					_CleanApproved          = $preparedModule.CleanApproved
				}
				$parallelInstallResults.Add($finalResult)
				if ($finalResult.PendingReboot) {
					New-Log "[$moduleName] Staged $($preparedModule.TargetVersionString) for replacement on restart at: $($finalResult.PendingRebootPaths -join '; ')." -Level WARNING
				}
				elseif ($finalResult.OverallSuccess) {
					New-Log "[$moduleName] Installed $($preparedModule.TargetVersionString) to $(@($finalResult.UpdatedPaths).Count) path(s)." -Level SUCCESS
				}
				elseif (@($finalResult.UpdatedPaths).Count -gt 0) {
					New-Log "[$moduleName] Partially installed $($preparedModule.TargetVersionString); failed paths: $($finalResult.FailedPaths -join '; ')." -Level WARNING
				}
				else {
					New-Log "[$moduleName] Installation failed for: $($finalResult.FailedPaths -join '; ')" -Level WARNING
				}
			}
			catch {
				New-Log "[$moduleName] Unhandled error during parallel install." -Level ERROR
				$parallelInstallResults.Add([PSCustomObject]@{
						ModuleName              = $moduleName
						NewVersionPreRelease    = if ($preparedModule.IsPreview) { $preparedModule.PreReleaseVersion }
						NewVersion              = $preparedModule.BaseVerStr
						UpdatedPaths            = @()
						FailedPaths             = @("Parallel install error: $($_.Exception.Message)")
						PendingRebootPaths      = @()
						PendingReboot           = $false
						OverallSuccess          = $false
						CleanedPaths            = @()
						FailedCleanPaths        = @()
						CleanPendingRebootPaths = @()
						BackupPaths             = @()
						CleanStatus             = if ($using:useClean) { 'NotRun' } else { 'NotRequested' }
						_OutdatedVersions       = $preparedModule.OutdatedVersions
						_LatestVer              = $preparedModule.LatestVer
						_PreReleaseVersion      = $preparedModule.PreReleaseVersion
						_CleanApproved          = $false
					})
			}
		}
		$parallelDuration = (Get-Date) - $parallelStartTime
		$installResultsArray = @($parallelInstallResults)
		$installPendingCount = @($installResultsArray | Where-Object PendingReboot).Count
		$installSuccessCount = @($installResultsArray | Where-Object { $_.OverallSuccess -and -not $_.PendingReboot }).Count
		$installFailureCount = $installResultsArray.Count - $installSuccessCount - $installPendingCount
		New-Log "Installation complete in $([math]::Round($parallelDuration.TotalSeconds, 2)) seconds: $installSuccessCount succeeded, $installPendingCount pending reboot, $installFailureCount failed or partial."
		$postProcessIndex = 0
		foreach ($finalResult in $installResultsArray) {
			$moduleName = $finalResult.ModuleName
			$postProcessIndex++
			$finalResult.CleanedPaths = @($finalResult.CleanedPaths)
			$finalResult.FailedCleanPaths = @($finalResult.FailedCleanPaths)
			$finalResult.CleanPendingRebootPaths = @($finalResult.CleanPendingRebootPaths)
			$finalResult.BackupPaths = @($finalResult.BackupPaths)
			$finalResult.CleanStatus = if ($useClean) { 'NotRun' } else { 'NotRequested' }
			if ($UseProgressBar.IsPresent) {
				$progressParams = @{
					Activity         = "Updating PowerShell Modules"
					Status           = "Post-processing: $moduleName"
					PercentComplete  = [math]::Round(($postProcessIndex / $installResultsArray.Count) * 100)
					CurrentOperation = if ($useClean -and $finalResult.OverallSuccess) { "[$moduleName] Cleaning old versions.." } else { "[$moduleName] Finalizing.." }
				}
				Write-Progress @progressParams
			}
			if ($finalResult.OverallSuccess -and $useClean) {
				if ($finalResult._CleanApproved) {
					$cleanResult = Remove-OutdatedVersions -ModuleName $moduleName -ModuleBasePaths $finalResult.UpdatedPaths -LatestVersion $finalResult._LatestVer -PreReleaseVersion $finalResult._PreReleaseVersion -CleanupBackupPath $CleanupBackupPath -ReplaceLockedModuleOnReboot:$ReplaceLockedModuleOnReboot -ErrorAction SilentlyContinue
					if ($cleanResult) {
						$finalResult.CleanedPaths = @($cleanResult.CleanedPaths)
						$finalResult.FailedCleanPaths = @($cleanResult.FailedPaths)
						$finalResult.CleanPendingRebootPaths = @($cleanResult.PendingRebootPaths)
						$finalResult.BackupPaths = @($cleanResult.BackupPaths)
						$finalResult.CleanStatus = Get-CleanStatusFromResult -CleanResult $cleanResult
						switch ($finalResult.CleanStatus) {
							'Succeeded' {
								New-Log "[$moduleName] Successfully cleaned $(@($cleanResult.CleanedPaths).Count) old items: $(@($cleanResult.CleanedPaths) -join '; ')" -Level SUCCESS
							}
							'NoOldVersions' {
								New-Log "[$moduleName] No old version folders required removal." -Level VERBOSE
							}
							'PendingReboot' {
								New-Log "[$moduleName] Old version folder(s) will be deleted on the next restart: $(@($cleanResult.PendingRebootPaths) -join '; ')" -Level WARNING
							}
							'Skipped' {
								New-Log "[$moduleName] Skipped cleaning due to ShouldProcess user choice." -Level WARNING
							}
							default {
								New-Log "[$moduleName] Cleanup $($finalResult.CleanStatus): cleaned $(@($cleanResult.CleanedPaths).Count), failed $(@($cleanResult.FailedPaths).Count): $((@($cleanResult.FailedPaths) | ForEach-Object { "$($_.Path) ($($_.Reason))" }) -join '; ')." -Level WARNING
							}
						}
						if (@($cleanResult.BackupPaths).Count -gt 0) {
							New-Log "[$moduleName] Backed up $(@($cleanResult.BackupPaths).Count) old version(s) to: $(@($cleanResult.BackupPaths) -join '; ')"
						}
					}
					else {
						$finalResult.CleanStatus = 'NotRun'
						New-Log "[$moduleName] Cleanup did not return a result; treating it as not run." -Level WARNING
					}
				}
				else {
					$finalResult.CleanStatus = 'Skipped'
					New-Log "[$moduleName] Skipped cleaning due to ShouldProcess user choice." -Level WARNING
				}
			}
			elseif ($useClean -and -not $finalResult.OverallSuccess) {
				$finalResult.CleanStatus = 'NotRun'
				New-Log "[$moduleName] Skipping cleaning as the update was not fully successful (Failed Paths: $($finalResult.FailedPaths -join '; '))." -Level VERBOSE
			}
			$finalResult.PSObject.Properties.Remove('_OutdatedVersions')
			$finalResult.PSObject.Properties.Remove('_LatestVer')
			$finalResult.PSObject.Properties.Remove('_PreReleaseVersion')
			$finalResult.PSObject.Properties.Remove('_CleanApproved')
			$aggregateResults.Add($finalResult)
		}
		$pendingRebootCount = ($aggregateResults | Where-Object PendingReboot).Count
		$successCount = ($aggregateResults | Where-Object { $_.OverallSuccess -and -not $_.PendingReboot }).Count
		$failCount = $total - $successCount - $pendingRebootCount
		$totalUpdateDuration = (Get-Date) - $updateStartTime
		$updateSummaryLevel = if ($failCount -gt 0 -or $pendingRebootCount -gt 0) { 'WARNING' } else { 'SUCCESS' }
		New-Log "Module update complete: $total processed in $([math]::Round($totalUpdateDuration.TotalSeconds, 2)) seconds; $successCount succeeded, $pendingRebootCount pending reboot, $failCount failed or partial." -Level $updateSummaryLevel
		if ($pendingRebootCount -gt 0) {
			New-Log "$pendingRebootCount module(s) staged; the flat update will be applied on the next reboot: $((($aggregateResults | Where-Object PendingReboot).ModuleName) -join ', ')" -Level WARNING
		}
		if ($failCount -gt 0) {
			New-Log "Modules with failures or partial updates:" -Level WARNING
			$aggregateResults | Where-Object {
				-not $_.OverallSuccess -and -not $_.PendingReboot
			} | ForEach-Object {
				$failReason = if ($_.FailedPaths) {
					"[$($_.ModuleName)] Failed Paths: $($_.FailedPaths -join '; ')"
				}
				else {
					"[$($_.ModuleName)] Unknown reason"
				}
				New-Log "$failReason" -Level WARNING
			}
		}
		if ($Clean.IsPresent) {
			$cleanedModules = @($aggregateResults | Where-Object CleanStatus -EQ 'Succeeded')
			$cleanNotNeeded = @($aggregateResults | Where-Object CleanStatus -EQ 'NoOldVersions')
			$cleanSkipped = @($aggregateResults | Where-Object CleanStatus -EQ 'Skipped')
			$cleanNotRun = @($aggregateResults | Where-Object CleanStatus -EQ 'NotRun')
			$cleanFailed = @($aggregateResults | Where-Object { $_.CleanStatus -in @('Failed', 'PartiallySucceeded') })
			$cleanPendingReboot = @($aggregateResults | Where-Object CleanStatus -EQ 'PendingReboot')
			$cleanupSummaryLevel = if ($cleanFailed.Count -gt 0) { 'WARNING' } else { 'INFO' }
			New-Log "Cleanup summary: $($cleanedModules.Count) cleaned, $($cleanNotNeeded.Count) already clean, $($cleanSkipped.Count) skipped, $($cleanNotRun.Count) not run, $($cleanFailed.Count) failed or partial, $($cleanPendingReboot.Count) pending reboot." -Level $cleanupSummaryLevel
			if ($cleanFailed.Count -gt 0 -and -not $ReplaceLockedModuleOnReboot.IsPresent) {
				$failedCleanDetails = ($cleanFailed | ForEach-Object { "[$($_.ModuleName)] $((@($_.FailedCleanPaths) | ForEach-Object { "$($_.Path) ($($_.Reason))" }) -join '; ')" }) -join ' | '
				New-Log "Old versions that could not be removed: $failedCleanDetails. Re-run with -ReplaceLockedModuleOnReboot to schedule locked or denied folders for deletion on the next restart." -Level WARNING
			}
		}
		return $aggregateResults
	}
}
#endregion Update-Modules
#region Install-PSModule
function Install-PSModule {
	<#
    .SYNOPSIS
    Installs one module version into the requested locations.
    .DESCRIPTION
    Uses Save-PSResource for each destination and falls back to Install-PSResource or
    Install-Module when needed. Flat installations are updated in place. Locked flat
    installations can be staged for restart or redirected to a versioned subfolder.
    .PARAMETER ModuleName
    Name of the module to install.
    .PARAMETER TargetVersionString
    Exact version to install.
    .PARAMETER RepositoryName
    Registered repository that provides the module.
    .PARAMETER IsPreview
    Indicates that the target is a prerelease.
    .PARAMETER Destinations
    Module base paths that require the target version.
    .PARAMETER PreReleaseVersion
    Full prerelease version string when the target is a prerelease.
    .PARAMETER ReplaceLockedModuleOnReboot
    Schedules replacement of locked flat-module files for the next Windows restart.
    .PARAMETER AllowVersionedSubfolder
    Installs a locked flat module into a versioned subfolder.
    .INPUTS
    None.
    .OUTPUTS
    System.Management.Automation.PSCustomObject with UpdatedPaths, FailedPaths, and
    PendingRebootPaths properties.
    .EXAMPLE
    Install-PSModule -ModuleName Pester -TargetVersionString 5.7.1 -RepositoryName PSGallery -IsPreview $false -Destinations 'C:\Program Files\PowerShell\Modules\Pester'
    Installs Pester 5.7.1 into the requested module location.
    .NOTES
    Internal helper used by Update-Modules. Reboot scheduling is Windows-specific.
    .LINK
    Save-PSResource
    #>
	[CmdletBinding()]
	param (
		[Parameter(Mandatory)][string]$ModuleName,
		[Parameter(Mandatory)][string]$TargetVersionString,
		[Parameter(Mandatory)][string]$RepositoryName,
		[Parameter(Mandatory)][bool]$IsPreview,
		[Parameter(Mandatory)][string[]]$Destinations,
		[string]$PreReleaseVersion,
		[bool]$ReplaceLockedModuleOnReboot = $false,
		[bool]$AllowVersionedSubfolder = $false
	)
	# PSResourceGet and legacy PowerShellGet emit progress records independently of
	# their verbose streams. Keep helper output on the New-Log path.
	$ProgressPreference = 'SilentlyContinue'
	function Test-FlatTargetLocked {
		param(
			[Parameter(Mandatory)][string]$BasePath
		)
		foreach ($f in @(Get-ChildItem -LiteralPath $BasePath -Recurse -File -Force -ErrorAction SilentlyContinue)) {
			try { $fs = [System.IO.File]::Open($f.FullName, 'Open', 'ReadWrite', 'None'); $fs.Close(); $fs.Dispose() }
			catch {
				$ex = $_.Exception
				while ($ex) {
					if ($ex -is [System.IO.IOException] -and $ex -isnot [System.IO.FileNotFoundException]) { return $true }
					$ex = $ex.InnerException
				}
			}
		}
		return $false
	}
	function Register-RebootFlatReplace {
		param(
			[Parameter(Mandatory)][string]$StagingDir,
			[Parameter(Mandatory)][string]$DestRoot
		)
		if (-not ('Win32UpdMod.PendingMove' -as [type])) {
			Add-Type -Namespace 'Win32UpdMod' -Name 'PendingMove' -MemberDefinition '[System.Runtime.InteropServices.DllImport("kernel32.dll", SetLastError = true, CharSet = System.Runtime.InteropServices.CharSet.Unicode)] public static extern bool MoveFileEx(string lpExistingFileName, string lpNewFileName, int dwFlags);' -ErrorAction Stop
		}
		$flags = 5 # MOVEFILE_REPLACE_EXISTING | MOVEFILE_DELAY_UNTIL_REBOOT
		$base = $StagingDir.TrimEnd('\')
		$scheduled = 0; $failed = 0
		foreach ($f in @(Get-ChildItem -LiteralPath $StagingDir -Recurse -File -Force -ErrorAction SilentlyContinue)) {
			$rel = $f.FullName.Substring($base.Length).TrimStart('\')
			$dest = Join-Path $DestRoot $rel
			$destDir = Split-Path $dest -Parent
			if ($destDir -and -not (Test-Path -LiteralPath $destDir)) { New-Item -ItemType Directory -Path $destDir -Force -ErrorAction SilentlyContinue | Out-Null }
			if ([Win32UpdMod.PendingMove]::MoveFileEx($f.FullName, $dest, $flags)) { $scheduled++ } else { $failed++ }
		}
		return [pscustomobject]@{ Scheduled = $scheduled; Failed = $failed }
	}
	$result = [PSCustomObject]@{
		UpdatedPaths       = [System.Collections.Generic.List[string]]::new()
		FailedPaths        = [System.Collections.Generic.List[string]]::new()
		PendingRebootPaths = [System.Collections.Generic.List[string]]::new()
	}
	if ($PreReleaseVersion) {
		$TargetVersionStringOrig = $TargetVersionString
		$TargetVersionString = $PreReleaseVersion
	}
	else {
		$TargetVersionStringOrig = $TargetVersionString
	}
	$commonSaveParams = @{
		Name                = $ModuleName
		Version             = $TargetVersionString
		Repository          = $RepositoryName
		TrustRepository     = $true
		IncludeXml          = $true
		SkipDependencyCheck = $true
		AcceptLicense       = $true
		Confirm             = $false
		PassThru            = $true
		Verbose             = $false
		ErrorAction         = 'Stop'
		WarningAction       = 'SilentlyContinue'
	}
	if ($IsPreview) { $commonSaveParams['PreRelease'] = $true }
	$pathsToRetry = [System.Collections.Generic.List[string]]::new()
	foreach ($destinationBasePath in $Destinations) {
		# Preserve flat installs by staging the target version and copying it into the module root.
		if (Test-Path -LiteralPath (Join-Path $destinationBasePath "$ModuleName.psd1") -PathType Leaf) {
			$tempRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("UpdMod_{0}" -f [guid]::NewGuid().ToString('N'))
			$newContentDir = $null; $savedItemFlat = $null
			try {
				$null = New-Item -ItemType Directory -Path $tempRoot -Force -ErrorAction Stop
				$savedItemFlat = (Save-PSResource @commonSaveParams -Path $tempRoot) | Select-Object -Last 1
				$savedModuleDir = Join-Path $tempRoot $ModuleName
				$newContentDir = Get-ChildItem -LiteralPath $savedModuleDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -match '^\d+(\.\d+)' } | Sort-Object Name | Select-Object -Last 1
			}
			catch {
				New-Log "[$moduleName] Flat update: Save-PSResource to temp failed." -Level ERROR
			}
			$expPreF = if ($PreReleaseVersion) { ($PreReleaseVersion -split '-')[-1] } else { '' }
			$actPreF = if ($savedItemFlat -and $savedItemFlat.Prerelease) { $savedItemFlat.Prerelease } else { '' }
			if ($newContentDir -and $savedItemFlat -and "$($savedItemFlat.Version)" -eq "$TargetVersionStringOrig" -and $actPreF -eq $expPreF) {
				if (-not (Test-FlatTargetLocked -BasePath $destinationBasePath)) {
					try {
						Copy-Item -Path (Join-Path $newContentDir.FullName '*') -Destination $destinationBasePath -Recurse -Force -ErrorAction Stop
						New-Log "[$moduleName] Updated FLAT (unversioned) install at '$destinationBasePath' to [$TargetVersionString] in place (no version subfolder)." -Level SUCCESS
						$result.UpdatedPaths.Add($destinationBasePath)
					}
					catch {
						New-Log "[$moduleName] Flat copy into '$destinationBasePath' failed." -Level ERROR
						$result.FailedPaths.Add($destinationBasePath)
					}
				}
				elseif ($ReplaceLockedModuleOnReboot) {
					$stagingDir = Join-Path $env:ProgramData ("UpdateModules\PendingReboot\{0}_{1}" -f $ModuleName, [guid]::NewGuid().ToString('N'))
					try {
						$null = New-Item -ItemType Directory -Path (Split-Path $stagingDir -Parent) -Force -ErrorAction SilentlyContinue
						Move-Item -LiteralPath $newContentDir.FullName -Destination $stagingDir -Force -ErrorAction Stop
						$sched = Register-RebootFlatReplace -StagingDir $stagingDir -DestRoot $destinationBasePath
						if ($sched.Scheduled -gt 0 -and $sched.Failed -eq 0) {
							New-Log "[$moduleName] '$ModuleName' is in use; scheduled $($sched.Scheduled) file(s) to replace the flat install at '$destinationBasePath' on next reboot (no version subfolder created)." -Level SUCCESS
							$result.PendingRebootPaths.Add($destinationBasePath)
						}
						else {
							New-Log "[$moduleName] Could not schedule reboot replacement for '$destinationBasePath' (scheduled=$($sched.Scheduled), failed=$($sched.Failed)). Administrator rights are required." -Level WARNING
							$result.FailedPaths.Add($destinationBasePath)
							if (Test-Path -LiteralPath $stagingDir) { Remove-Item -LiteralPath $stagingDir -Recurse -Force -ErrorAction SilentlyContinue }
						}
					}
					catch {
						New-Log "[$moduleName] Reboot-replace staging/scheduling for '$destinationBasePath' failed." -Level ERROR
						$result.FailedPaths.Add($destinationBasePath)
						if (Test-Path -LiteralPath $stagingDir) { Remove-Item -LiteralPath $stagingDir -Recurse -Force -ErrorAction SilentlyContinue }
					}
				}
				elseif ($AllowVersionedSubfolder) {
					$saveParentF = Split-Path $destinationBasePath -Parent -ErrorAction SilentlyContinue
					try {
						$svItem = (Save-PSResource @commonSaveParams -Path $saveParentF) | Select-Object -Last 1
						if ($svItem -and "$($svItem.Version)" -eq "$TargetVersionStringOrig") {
							New-Log "[$moduleName] '$ModuleName' is in use; installed [$TargetVersionString] into a version subfolder under '$destinationBasePath' (-AllowVersionedSubfolder). The flat layout could not be kept while the module is loaded." -Level WARNING
							$result.UpdatedPaths.Add($destinationBasePath)
						}
						else { $result.FailedPaths.Add($destinationBasePath) }
					}
					catch {
						New-Log "[$moduleName] Versioned-subfolder fallback for '$destinationBasePath' failed." -Level ERROR
						$result.FailedPaths.Add($destinationBasePath)
					}
				}
				else {
					New-Log "[$moduleName] Cannot update '$destinationBasePath' in place: '$ModuleName' is currently in use (files locked) and its layout is flat (unversioned). Skipped to preserve the layout. Re-run from a session that does not load '$ModuleName', or pass -ReplaceLockedModuleOnReboot or -AllowVersionedSubfolder." -Level WARNING
					$result.FailedPaths.Add($destinationBasePath)
				}
			}
			else {
				New-Log "[$moduleName] Flat update: could not obtain version [$TargetVersionString] from '$RepositoryName' for '$destinationBasePath' (saved='$($savedItemFlat.Version)'). Marking path as failed." -Level WARNING
				$result.FailedPaths.Add($destinationBasePath)
			}
			if (Test-Path -LiteralPath $tempRoot) { Remove-Item -LiteralPath $tempRoot -Recurse -Force -ErrorAction SilentlyContinue }
			continue
		}
		$saveTargetDir = Split-Path $destinationBasePath -Parent -ErrorAction SilentlyContinue
		if (-not $saveTargetDir -or -not (Test-Path $saveTargetDir -PathType Container)) {
			New-Log "[$moduleName] Install-PSModule: Cannot determine valid parent directory from destination '$destinationBasePath'. Skipping Save-PSResource for this path." -Level WARNING
			$pathsToRetry.Add($destinationBasePath)
			continue
		}
		New-Log "[$moduleName] Attempting Save-PSResource for version [$TargetVersionString] to '$saveTargetDir'..." -Level VERBOSE
		$saveRes = $null
		try {
			$saveRes = Save-PSResource @commonSaveParams -Path $saveTargetDir
		}
		catch {
			New-Log "[$moduleName] Save-PSResource failed for v$TargetVersionString to '$saveTargetDir'" -Level ERROR
			$saveRes = $null
		}
		$savedItem = $saveRes | Select-Object -Last 1
		$expectedPrerelease = if ($PreReleaseVersion) { ($PreReleaseVersion -split '-')[-1] } else { '' }
		$actualPrerelease = if ($savedItem -and $savedItem.Prerelease) { $savedItem.Prerelease } else { '' }
		if ($savedItem -and "$($savedItem.Version)" -eq "$TargetVersionStringOrig" -and $actualPrerelease -eq $expectedPrerelease) {
			$result.UpdatedPaths.Add($destinationBasePath)
		}
		else {
			$pathsToRetry.Add($destinationBasePath)
		}
	}
	if ($pathsToRetry.Count -gt 0) {
		$fallbackInstallSucceeded = $false
		$installedLocationFallback = $null
		try {
			$psResourceParams = @{
				Name                = $ModuleName
				Version             = $TargetVersionString
				Scope               = 'AllUsers'
				AcceptLicense       = $true
				SkipDependencyCheck = $true
				Confirm             = $false
				Reinstall           = $true
				TrustRepository     = $true
				Repository          = $RepositoryName
				PassThru            = $true
				Verbose             = $false
				ErrorAction         = 'Stop'
				WarningAction       = 'SilentlyContinue'
			}
			if ($IsPreview) { $psResourceParams['PreRelease'] = $true }
			New-Log "[$moduleName] Attempting Install-PSResource for version [$($psResourceParams.Version)]..." -Level VERBOSE
			$installRes1 = $null
			$installRes1 = Install-PSResource @psResourceParams
			$installedItem1 = $installRes1 | Select-Object -Last 1
			$expectedPrerelease1 = if ($PreReleaseVersion) { ($PreReleaseVersion -split '-')[-1] } else { '' }
			$actualPrerelease1 = if ($installedItem1 -and $installedItem1.Prerelease) { $installedItem1.Prerelease } else { '' }
			if ($installedItem1 -and "$($installedItem1.Version)" -eq "$TargetVersionStringOrig" -and $actualPrerelease1 -eq $expectedPrerelease1) {
				$installedLocationFallback = $installedItem1.InstalledLocation
				$fallbackInstallSucceeded = $true
			}
		}
		catch {
			New-Log "[$moduleName] Install-PSResource failed for v${TargetVersionString}" -Level ERROR
		}
		if (-not $fallbackInstallSucceeded) {
			try {
				$installModuleParams = @{
					Name               = $ModuleName
					RequiredVersion    = $TargetVersionString
					Scope              = 'AllUsers'
					Force              = $true
					AcceptLicense      = $true
					SkipPublisherCheck = $true
					AllowClobber       = $true
					PassThru           = $true
					Repository         = $RepositoryName
					Verbose            = $false
					ErrorAction        = 'Stop'
					WarningAction      = 'SilentlyContinue'
					Confirm            = $false
				}
				if ($IsPreview) {
					$installModuleCmd = Get-Command -Name 'Install-Module' -ErrorAction SilentlyContinue
					if ($installModuleCmd -and $installModuleCmd.Parameters.ContainsKey('AllowPrerelease')) {
						$installModuleParams['AllowPrerelease'] = $true
					}
				}
				try {
					Set-PSResourceRepository -Name $RepositoryName -Trusted -ErrorAction Stop -Verbose:$false
				}
				catch {
					New-Log "[$moduleName] Could not mark repository '$RepositoryName' as trusted before the Install-Module fallback" -Level ERROR
				}
				New-Log "[$moduleName] Attempting Install-Module for version [$($installModuleParams.RequiredVersion)]..." -Level DEBUG
				$installRes2 = $null
				$installRes2 = Install-Module @installModuleParams
				$installedItem2 = $installRes2 | Select-Object -Last 1
				if ($installedItem2 -and $($installedItem2.Version) -eq $TargetVersionStringOrig -and $installedItem2.PSObject.Properties.Match('Prerelease').Value -eq $(($PreReleaseVersion -split '-')[-1])) {
					$installedLocationFallback = $installedItem2.InstalledLocation
					$fallbackInstallSucceeded = $true
				}
			}
			catch {
				New-Log "[$moduleName] Install-Module (last fallback) failed" -Level ERROR
			}
		}
		if ($fallbackInstallSucceeded -and $installedLocationFallback) {
			$fallbackBaseInstallPath = Split-Path $installedLocationFallback -Parent -Verbose:$false
			foreach ($retryPath in $pathsToRetry) {
				if ($retryPath -eq $fallbackBaseInstallPath) {
					if ($result.UpdatedPaths -notcontains $retryPath) {
						$result.UpdatedPaths.Add($retryPath)
						New-Log "[$moduleName] Fallback installation to '$installedLocationFallback' satisfied the intended destination base path '$retryPath'." -Level DEBUG
					}
				}
			}
		}
		foreach ($retryPath in $pathsToRetry) {
			if ($result.UpdatedPaths -notcontains $retryPath) {
				if ($result.FailedPaths -notcontains $retryPath) {
					$result.FailedPaths.Add($retryPath)
					New-Log "[$moduleName] Marking path '$retryPath' as failed after Save-PSResource and fallback install attempts." -Level Debug
				}
			}
		}
	}
	# Keep empty result collections as empty arrays rather than @($null).
	$result.UpdatedPaths = @($result.UpdatedPaths | Select-Object -Unique -Verbose:$false)
	$result.PendingRebootPaths = @($result.PendingRebootPaths | Select-Object -Unique -Verbose:$false)
	$result.FailedPaths = @($result.FailedPaths | Select-Object -Unique -Verbose:$false)
	$result.FailedPaths = @($result.FailedPaths | Where-Object { $result.UpdatedPaths -notcontains $_ -and $result.PendingRebootPaths -notcontains $_ })
	$updatedCount = @($result.UpdatedPaths).Count
	$pendingCount = @($result.PendingRebootPaths).Count
	if ($updatedCount -eq 0 -and $pendingCount -eq 0) {
		$result.FailedPaths = @($Destinations | Select-Object -Unique)
	}
	return $result
}
#endregion Install-PSModule
#region Backup-ModuleVersionFolder
function Backup-ModuleVersionFolder {
	<#
    .SYNOPSIS
    Creates a zip backup of one module version folder.
    .DESCRIPTION
    Compresses a version folder to <BackupRootPath>\<ModuleName>\<ModuleName>_<version>.zip
    before the folder is removed. An existing archive for the same version is replaced
    and a half-written archive is deleted on failure.
    .PARAMETER ModuleName
    Name of the module the version folder belongs to.
    .PARAMETER VersionFolderPath
    Full path of the version folder to back up.
    .PARAMETER BackupRootPath
    Root folder that receives the backup archives.
    .INPUTS
    None.
    .OUTPUTS
    System.String. Full path of the created archive, or $null when the backup failed.
    .EXAMPLE
    Backup-ModuleVersionFolder -ModuleName Pester -VersionFolderPath 'C:\Program Files\WindowsPowerShell\Modules\Pester\3.4.0' -BackupRootPath 'D:\ModuleBackups'
    Creates D:\ModuleBackups\Pester\Pester_3.4.0.zip.
    .NOTES
    The archive contains the version folder itself so it can be extracted straight into
    a module base path.
    .LINK
    Remove-OutdatedVersions
    #>
	[CmdletBinding()]
	[OutputType([string])]
	param (
		[Parameter(Mandatory)][string]$ModuleName,
		[Parameter(Mandatory)][string]$VersionFolderPath,
		[Parameter(Mandatory)][string]$BackupRootPath
	)
	$backupZipPath = $null
	try {
		$versionString = Split-Path $VersionFolderPath -Leaf
		$moduleBackupDir = Join-Path $BackupRootPath $ModuleName
		if (-not (Test-Path -LiteralPath $moduleBackupDir -PathType Container)) {
			$null = New-Item -ItemType Directory -Path $moduleBackupDir -Force -ErrorAction Stop
		}
		$backupZipPath = Join-Path $moduleBackupDir ("{0}_{1}.zip" -f $ModuleName, $versionString)
		if (Test-Path -LiteralPath $backupZipPath -PathType Leaf) {
			Remove-Item -LiteralPath $backupZipPath -Force -ErrorAction Stop # The same module and version produce the same content, so an existing archive is replaced.
		}
		Add-Type -AssemblyName 'System.IO.Compression.FileSystem' -ErrorAction SilentlyContinue
		[System.IO.Compression.ZipFile]::CreateFromDirectory($VersionFolderPath, $backupZipPath, [System.IO.Compression.CompressionLevel]::Optimal, $true) # $true keeps the version folder as the archive root for easy restore.
		if ((Test-Path -LiteralPath $backupZipPath -PathType Leaf) -and ((Get-Item -LiteralPath $backupZipPath -ErrorAction Stop).Length -gt 0)) {
			New-Log "[$ModuleName] Backed up '$VersionFolderPath' to '$backupZipPath'." -Level VERBOSE
			return $backupZipPath
		}
		New-Log "[$ModuleName] Backup archive '$backupZipPath' was not created or is empty." -Level WARNING
		return $null
	}
	catch {
		New-Log "[$ModuleName] Failed to back up '$VersionFolderPath' to '$BackupRootPath'" -Level ERROR
		if ($backupZipPath -and (Test-Path -LiteralPath $backupZipPath -PathType Leaf)) { Remove-Item -LiteralPath $backupZipPath -Force -ErrorAction SilentlyContinue } # Never leave a half-written archive behind.
		return $null
	}
}
#endregion Backup-ModuleVersionFolder
#region Repair-ModuleFolderAcl
function Repair-ModuleFolderAcl {
	<#
    .SYNOPSIS
    Repairs ownership and permissions on a module version folder.
    .DESCRIPTION
    Takes ownership for the Administrators group and resets the ACL with icacls so a
    protected folder can be removed. This handles folders like the built-in Pester
    3.4.0 where TrustedInstaller is the owner and even elevated administrators only
    have read and execute permissions. The Administrators group is addressed by its
    SID S-1-5-32-544 so the repair works on all Windows languages.
    .PARAMETER ModuleName
    Name of the module, used for logging.
    .PARAMETER FolderPath
    Full path of the version folder to repair.
    .INPUTS
    None.
    .OUTPUTS
    System.Boolean. $true when every repair step succeeded.
    .EXAMPLE
    Repair-ModuleFolderAcl -ModuleName Pester -FolderPath 'C:\Program Files\WindowsPowerShell\Modules\Pester\3.4.0'
    Makes the built-in Pester 3.4.0 folder removable by an elevated session.
    .NOTES
    Requires administrator rights for folders owned by TrustedInstaller. The takeown /D
    answer is localized, so both Y and J are tried.
    .LINK
    Remove-OutdatedVersions
    #>
	[CmdletBinding()]
	[OutputType([bool])]
	param (
		[Parameter(Mandatory)][string]$ModuleName,
		[Parameter(Mandatory)][string]$FolderPath
	)
	if (-not $IsWindows) {
		New-Log "[$ModuleName] ACL repair is only supported on Windows. Skipping for '$FolderPath'." -Level VERBOSE
		return $false
	}
	$aclRepaired = $true
	try {
		New-Log "[$ModuleName] Attempting ACL repair of '$FolderPath' (takeown + icacls)..." -Level DEBUG
		$takeownOutput = & takeown.exe /F "$FolderPath" /A /R /D Y 2>&1 # /A assigns ownership to the Administrators group instead of the current user.
		if ($LASTEXITCODE -ne 0) {
			$takeownOutput = & takeown.exe /F "$FolderPath" /A /R /D J 2>&1 # The /D answer is localized (Y in English, J in for example Swedish and German), so both are tried.
		}
		if ($LASTEXITCODE -ne 0) {
			New-Log "[$ModuleName] takeown returned exit code $LASTEXITCODE for '$FolderPath'; continuing with icacls anyway. Last output: $(@($takeownOutput) | Select-Object -Last 1)" -Level VERBOSE
			$aclRepaired = $false
		}
		$icaclsResetOutput = & icacls.exe "$FolderPath" /reset /T /C /Q 2>&1 # /reset restores inherited permissions which removes protected ACLs like the built-in Pester 3.4.0 ones.
		if ($LASTEXITCODE -ne 0) {
			New-Log "[$ModuleName] icacls /reset returned exit code $LASTEXITCODE for '$FolderPath'. Last output: $(@($icaclsResetOutput) | Select-Object -Last 1)" -Level VERBOSE
			$aclRepaired = $false
		}
		$icaclsGrantOutput = & icacls.exe "$FolderPath" /grant "*S-1-5-32-544:(OI)(CI)F" /T /C /Q 2>&1 # Grants the Administrators group full control in case inheritance is disabled on the parent.
		if ($LASTEXITCODE -ne 0) {
			New-Log "[$ModuleName] icacls /grant returned exit code $LASTEXITCODE for '$FolderPath'. Last output: $(@($icaclsGrantOutput) | Select-Object -Last 1)" -Level VERBOSE
			$aclRepaired = $false
		}
		if ($aclRepaired) {
			New-Log "[$ModuleName] ACL repair of '$FolderPath' completed." -Level VERBOSE
		}
		return $aclRepaired
	}
	catch {
		New-Log "[$ModuleName] ACL repair of '$FolderPath' failed" -Level ERROR
		return $false
	}
}
#endregion Repair-ModuleFolderAcl
#region Register-PendingDeleteOnReboot
function Register-PendingDeleteOnReboot {
	<#
    .SYNOPSIS
    Schedules a folder for deletion on the next restart.
    .DESCRIPTION
    Registers every file and subfolder of the supplied folder, and the folder itself,
    in PendingFileRenameOperations using MoveFileEx with MOVEFILE_DELAY_UNTIL_REBOOT.
    Files are scheduled before their parent folders so each folder is empty when its
    deletion runs during the next boot.
    .PARAMETER ModuleName
    Name of the module, used for logging.
    .PARAMETER FolderPath
    Full path of the folder to schedule for deletion.
    .INPUTS
    None.
    .OUTPUTS
    System.Management.Automation.PSCustomObject with Scheduled and Failed counts.
    .EXAMPLE
    Register-PendingDeleteOnReboot -ModuleName Pester -FolderPath 'C:\Program Files\WindowsPowerShell\Modules\Pester\3.4.0'
    Deletes the locked folder during the next Windows restart.
    .NOTES
    Requires administrator rights. Windows-specific.
    .LINK
    Remove-OutdatedVersions
    #>
	[CmdletBinding()]
	[OutputType([pscustomobject])]
	param (
		[Parameter(Mandatory)][string]$ModuleName,
		[Parameter(Mandatory)][string]$FolderPath
	)
	$scheduledCount = 0
	$failedCount = 0
	if (-not $IsWindows) {
		New-Log "[$ModuleName] Delete-on-reboot scheduling is only supported on Windows. Skipping for '$FolderPath'." -Level VERBOSE
		return [pscustomobject]@{ Scheduled = 0; Failed = 1 }
	}
	try {
		if (-not ('Win32UpdMod.PendingMove' -as [type])) {
			Add-Type -Namespace 'Win32UpdMod' -Name 'PendingMove' -MemberDefinition '[System.Runtime.InteropServices.DllImport("kernel32.dll", SetLastError = true, CharSet = System.Runtime.InteropServices.CharSet.Unicode)] public static extern bool MoveFileEx(string lpExistingFileName, string lpNewFileName, int dwFlags);' -ErrorAction Stop
		}
		$delayUntilRebootFlag = 4 # MOVEFILE_DELAY_UNTIL_REBOOT with a null destination deletes the path during the next boot.
		$allItems = @(Get-ChildItem -LiteralPath $FolderPath -Recurse -Force -ErrorAction SilentlyContinue)
		$orderedTargets = @($allItems | Where-Object { -not $_.PSIsContainer } | Select-Object -ExpandProperty FullName) # Files must be scheduled before the folders that contain them.
		$orderedTargets += @($allItems | Where-Object { $_.PSIsContainer } | Sort-Object -Property @{E = { $_.FullName.Length }; Descending = $true } | Select-Object -ExpandProperty FullName) # Deepest folders first so each one is empty when its deletion runs.
		$orderedTargets += $FolderPath
		foreach ($target in $orderedTargets) {
			if ([Win32UpdMod.PendingMove]::MoveFileEx($target, $null, $delayUntilRebootFlag)) { $scheduledCount++ } else { $failedCount++ }
		}
	}
	catch {
		New-Log "[$ModuleName] Could not schedule '$FolderPath' for deletion on reboot" -Level ERROR
		$failedCount++
	}
	return [pscustomobject]@{ Scheduled = $scheduledCount; Failed = $failedCount }
}
#endregion Register-PendingDeleteOnReboot
#region Get-CleanStatusFromResult
function Get-CleanStatusFromResult {
	<#
    .SYNOPSIS
    Derives a CleanStatus value from a Remove-OutdatedVersions result.
    .DESCRIPTION
    Maps the cleaned, failed, pending-reboot, and skipped path counts of a structured
    cleanup result to one CleanStatus string: NoOldVersions, Succeeded, PendingReboot,
    PartiallySucceeded, Failed, or Skipped.
    .PARAMETER CleanResult
    Structured result object returned by Remove-OutdatedVersions.
    .INPUTS
    None.
    .OUTPUTS
    System.String.
    .EXAMPLE
    $cleanStatus = Get-CleanStatusFromResult -CleanResult $cleanResult
    .NOTES
    Skipped means every found folder was declined via ShouldProcess.
    .LINK
    Remove-OutdatedVersions
    #>
	[CmdletBinding()]
	[OutputType([string])]
	param (
		[Parameter(Mandatory)][pscustomobject]$CleanResult
	)
	$cleanedCount = @($CleanResult.CleanedPaths).Count
	$failedCount = @($CleanResult.FailedPaths).Count
	$pendingCount = @($CleanResult.PendingRebootPaths).Count
	if (($cleanedCount + $failedCount + $pendingCount + @($CleanResult.SkippedPaths).Count) -eq 0) { return 'NoOldVersions' }
	if ($failedCount -eq 0 -and $pendingCount -eq 0 -and $cleanedCount -eq 0) { return 'Skipped' }
	if ($failedCount -eq 0 -and $pendingCount -eq 0) { return 'Succeeded' }
	if ($failedCount -eq 0) { return 'PendingReboot' }
	if (($cleanedCount + $pendingCount) -gt 0) { return 'PartiallySucceeded' }
	return 'Failed'
}
#endregion Get-CleanStatusFromResult
#region Remove-OutdatedVersions
function Remove-OutdatedVersions {
	<#
    .SYNOPSIS
    Removes older installed versions of a module.
    .DESCRIPTION
    Preserves the requested version and removes other version folders from each module
    base path. Managed CurrentUser and AllUsers installations use Uninstall-PSResource
    first; other locations are removed directly with retry handling. Access-denied
    folders get an ACL repair (takeown and icacls) followed by one more removal attempt.
    With -ReplaceLockedModuleOnReboot, folders that still cannot be removed are
    scheduled for deletion on the next restart. With -CleanupBackupPath, every folder
    is zipped before removal and a failed backup skips that removal.
    .PARAMETER ModuleName
    Name of the module to clean.
    .PARAMETER ModuleBasePaths
    Module root directories containing version subfolders.
    .PARAMETER LatestVersion
    Numeric version that must be preserved.
    .PARAMETER DoNotClean
    Module names that must never be cleaned.
    .PARAMETER PreReleaseVersion
    Full prerelease version string that must be preserved, when applicable.
    .PARAMETER CleanupBackupPath
    Root folder that receives a <ModuleName>\<ModuleName>_<version>.zip backup of each
    version folder before it is removed. When the backup fails the folder is kept.
    .PARAMETER ReplaceLockedModuleOnReboot
    Schedules version folders that cannot be removed for deletion on the next restart.
    .PARAMETER OnlyRemoveOlderThanLatest
    Removes only folders whose parsed version is lower than LatestVersion. Folders with
    a higher or unparsable version are kept. Used by the cleanup-only mode as a safety net.
    .PARAMETER CandidateVersionPaths
    Exact existing paths that cleanup-only mode is allowed to remove. A numeric path is
    treated as a version directory; a module base path represents an older flat install.
    .INPUTS
    None.
    .OUTPUTS
    System.Management.Automation.PSCustomObject with CleanedPaths, FailedPaths (Path and
    Reason), PendingRebootPaths, SkippedPaths, BackupPaths, and OldVersionCount.
    .EXAMPLE
    Remove-OutdatedVersions -ModuleName Pester -ModuleBasePaths 'C:\Modules\Pester' -LatestVersion 5.7.1
    Removes Pester version folders other than 5.7.1.
    .NOTES
    Supports ShouldProcess. Modules outside PSResourceGet-managed locations, including
    $PSHOME, bypass Uninstall-PSResource and use direct filesystem cleanup.
    .LINK
    Uninstall-PSResource
    #>
	[CmdletBinding(SupportsShouldProcess = $true)]
	param (
		[Parameter(Mandatory)][string]$ModuleName,
		[Parameter(Mandatory)][string[]]$ModuleBasePaths,
		[Parameter(Mandatory)][version]$LatestVersion,
		[string[]]$DoNotClean = @('PackageManagement', 'PowerShellGet', 'Microsoft.PowerShell.PSResourceGet'),
		[string]$PreReleaseVersion = $null,
		[string]$CleanupBackupPath,
		[switch]$ReplaceLockedModuleOnReboot,
		[switch]$OnlyRemoveOlderThanLatest,
		[string[]]$CandidateVersionPaths
	)
	function Get-RemoveFailureReason {
		[OutputType([string])]
		param (
			[AllowNull()][System.Exception]$Exception
		)
		$currentException = $Exception
		while ($currentException) {
			if ($currentException -is [System.UnauthorizedAccessException]) { return 'AccessDenied' }
			if ($currentException -is [System.IO.IOException] -and $currentException -isnot [System.IO.FileNotFoundException] -and $currentException -isnot [System.IO.DirectoryNotFoundException]) { return 'Locked' }
			$currentException = $currentException.InnerException
		}
		return 'Unknown'
	}
	# Uninstall-PSResource emits its own progress UI even when -Verbose is disabled.
	# Update-Modules owns all user-facing progress and logging.
	$ProgressPreference = 'SilentlyContinue'
	$cleanResult = [PSCustomObject]@{
		ModuleName         = $ModuleName
		CleanedPaths       = @()
		FailedPaths        = @()
		PendingRebootPaths = @()
		SkippedPaths       = @()
		BackupPaths        = @()
		OldVersionCount    = 0
	}
	if ($ModuleName -in $DoNotClean) {
		New-Log "[$moduleName] Skipping cleaning as it is in the DoNotClean list."
		return $cleanResult
	}
	$protectedModuleRoots = [System.Collections.Generic.List[string]]::new()
	if ($env:WINDIR) { $protectedModuleRoots.Add((Join-Path $env:WINDIR 'System32\WindowsPowerShell\v1.0\Modules')) }
	if ($PSHOME) { $protectedModuleRoots.Add((Join-Path $PSHOME 'Modules')) }
	$matchedProtectedRoot = $null
	foreach ($protectedRoot in $protectedModuleRoots) {
		$normalizedProtectedRoot = [IO.Path]::GetFullPath($protectedRoot).TrimEnd([IO.Path]::DirectorySeparatorChar) + [IO.Path]::DirectorySeparatorChar
		if (@($ModuleBasePaths | Where-Object {
					([IO.Path]::GetFullPath($_).TrimEnd([IO.Path]::DirectorySeparatorChar) + [IO.Path]::DirectorySeparatorChar).StartsWith($normalizedProtectedRoot, [System.StringComparison]::OrdinalIgnoreCase)
				}).Count -gt 0) {
			$matchedProtectedRoot = $normalizedProtectedRoot
			break
		}
	}
	if ($matchedProtectedRoot) {
		New-Log "[$ModuleName] Skipping cleanup because the target is inside protected runtime module directory '$matchedProtectedRoot'." -Level WARNING
		return $cleanResult
	}
	[string]$latestVersionString = $LatestVersion.ToString()
	[string]$latestVersionFullString = if ($PreReleaseVersion) { $PreReleaseVersion } else { $latestVersionString }
	New-Log "[$moduleName] Starting cleanup of old versions (keeping v$latestVersionFullString)..." -Level VERBOSE
	$cleanedItems = [System.Collections.Generic.List[string]]::new()
	$failedItems = [System.Collections.Generic.List[object]]::new()
	$pendingRebootItems = [System.Collections.Generic.List[string]]::new()
	$skippedItems = [System.Collections.Generic.List[string]]::new()
	$backupItems = [System.Collections.Generic.List[string]]::new()
	$moduleUnloaded = $false
	$restrictToCandidatePaths = $PSBoundParameters.ContainsKey('CandidateVersionPaths')
	$candidatePathSet = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
	if ($restrictToCandidatePaths) {
		foreach ($candidatePath in @($CandidateVersionPaths)) {
			if (-not [string]::IsNullOrWhiteSpace($candidatePath)) {
				$normalizedCandidatePath = [IO.Path]::GetFullPath($candidatePath).TrimEnd([IO.Path]::DirectorySeparatorChar, [IO.Path]::AltDirectorySeparatorChar)
				$null = $candidatePathSet.Add($normalizedCandidatePath)
			}
		}
	}
	foreach ($basePath in $ModuleBasePaths) {
		if (-not (Test-Path $basePath -PathType Container)) {
			New-Log "[$moduleName] Base path '$basePath' for cleaning does not exist or is not a directory. Skipping." -Level WARNING
			continue
		}
		$versionFolders = Get-ChildItem -Path $basePath -Directory -ErrorAction SilentlyContinue -Verbose:$false | Where-Object {
			$folderName = $_.Name
			$normalizedFolderPath = [IO.Path]::GetFullPath($_.FullName).TrimEnd([IO.Path]::DirectorySeparatorChar, [IO.Path]::AltDirectorySeparatorChar)
			if ($restrictToCandidatePaths -and -not $candidatePathSet.Contains($normalizedFolderPath)) { return $false }
			if ($folderName -notmatch '^\d+(\.\d+){1,4}(-.+)?$') { return $false }
			if ($folderName -eq $latestVersionFullString -or $folderName -eq $latestVersionString) { return $false }
			$folderBase = ($folderName -split '-', 2)[0]
			$keepBase = ($latestVersionFullString -split '-', 2)[0]
			$folderVer = $null
			$keepVer = $null
			if ([version]::TryParse($folderBase, [ref]$folderVer) -and [version]::TryParse($keepBase, [ref]$keepVer)) {
				if ($folderVer -eq $keepVer) {
					$folderPre = if ($folderName -match '-(.+)$') { $Matches[1] } else { $null }
					$keepPre = if ($latestVersionFullString -match '-(.+)$') { $Matches[1] } else { $null }
					if ($folderPre -eq $keepPre) { return $false }
				}
				if ($OnlyRemoveOlderThanLatest.IsPresent -and $folderVer -gt $keepVer) {
					New-Log "[$moduleName] Keeping '$($_.FullName)': the folder version is higher than the retained v$latestVersionFullString." -Level WARNING
					return $false
				}
			}
			elseif ($OnlyRemoveOlderThanLatest.IsPresent) {
				New-Log "[$moduleName] Keeping '$($_.FullName)': the folder version could not be parsed for a safe comparison." -Level WARNING
				return $false
			}
			return $true
		}
		if ($versionFolders) {
			foreach ($versionFolder in $versionFolders) {
				$folderPath = $versionFolder.FullName
				$versionString = $versionFolder.Name
				$cleanResult.OldVersionCount++
				$removed = $false
				if (-not $PSCmdlet.ShouldProcess($folderPath, "Remove module '$ModuleName' version '$versionString'")) {
					New-Log "[$moduleName] Skipped removal of '$folderPath' due to ShouldProcess user choice." -Level DEBUG
					$skippedItems.Add($folderPath)
					continue
				}
				if (-not $moduleUnloaded) {
					Remove-Module -Name $ModuleName -Force -ErrorAction SilentlyContinue
					$moduleUnloaded = $true
				}
				if ($CleanupBackupPath) {
					$backupZipPath = Backup-ModuleVersionFolder -ModuleName $ModuleName -VersionFolderPath $folderPath -BackupRootPath $CleanupBackupPath -ErrorAction SilentlyContinue
					if ($backupZipPath) {
						$backupItems.Add($backupZipPath)
					}
					else {
						New-Log "[$moduleName] Skipping removal of '$folderPath' because the backup to '$CleanupBackupPath' failed." -Level WARNING
						$failedItems.Add([PSCustomObject]@{ Path = $folderPath; Reason = 'BackupFailed' })
						continue
					}
				}
				$uninstalledViaCmdlet = $false
				$uninstallAttempted = $false
				$auModRoot = if ($env:ProgramFiles) { (Join-Path $env:ProgramFiles 'PowerShell\Modules') + '\' } else { $null } # Uninstall-PSResource only manages the standard CurrentUser and AllUsers locations.
				$myDocumentsPath = [Environment]::GetFolderPath('MyDocuments')
				$cuModRoot = if ($myDocumentsPath) { (Join-Path $myDocumentsPath 'PowerShell\Modules') + '\' } else { $null }
				$managedScope = if ($auModRoot -and $folderPath.StartsWith($auModRoot, [System.StringComparison]::OrdinalIgnoreCase)) { 'AllUsers' }
				elseif ($cuModRoot -and $folderPath.StartsWith($cuModRoot, [System.StringComparison]::OrdinalIgnoreCase)) { 'CurrentUser' }
				else { $null }
				if ($managedScope) {
					$uninstallAttempted = $true
					try {
						Uninstall-PSResource -Name $ModuleName -Version $versionString -Scope $managedScope -Confirm:$false -Verbose:$false -SkipDependencyCheck -ErrorAction Stop -WarningAction SilentlyContinue | Out-Null
						$uninstalledViaCmdlet = $true
					}
					catch {
						New-Log "[$moduleName] Uninstall-PSResource failed for version '$versionString'" -Level ERROR
					}
				}
				else {
					New-Log "[$moduleName] '$folderPath' is in an unmanaged location that Uninstall-PSResource cannot target (it only manages the CurrentUser/AllUsers scopes). Removing the version folder directly." -Level VERBOSE
				}
				if ($uninstallAttempted) {
					$uninstallDeadline = [DateTime]::UtcNow.AddSeconds(1)
					while ((Test-Path -LiteralPath $folderPath -PathType Container) -and [DateTime]::UtcNow -lt $uninstallDeadline) {
						Start-Sleep -Milliseconds 100
					}
				}
				if (-not (Test-Path -LiteralPath $folderPath -PathType Container)) {
					$cleanedItems.Add($folderPath)
					$removed = $true
				}
				elseif ($uninstalledViaCmdlet) {
					New-Log "[$moduleName] Uninstall-PSResource returned successfully for '$versionString', but '$folderPath' still exists; using filesystem cleanup." -Level WARNING
				}
				else {
					New-Log "[$moduleName] Using filesystem cleanup for '$folderPath'." -Level VERBOSE
				}
				if (-not $removed -and (Test-Path -LiteralPath $folderPath -PathType Container -Verbose:$false)) {
					New-Log "[$moduleName] Attempting Remove-Item -Recurse -Force on '$folderPath'..." -Level DEBUG
					$lastRemoveException = $null
					for ($attempt = 1; ($attempt -le 3) -and (-not $removed); $attempt++) {
						try {
							Get-ChildItem -LiteralPath $folderPath -Recurse -Force -ErrorAction SilentlyContinue | ForEach-Object {
								if ($_.Attributes -band [System.IO.FileAttributes]::ReadOnly) { try { $_.Attributes = [System.IO.FileAttributes]::Normal } catch { $null = $_ } }
							}
							Remove-Item -LiteralPath $folderPath -Recurse -Force -ErrorAction Stop -Verbose:$false | Out-Null
						}
						catch {
							$lastRemoveException = $_.Exception
						}
						if (-not (Test-Path -LiteralPath $folderPath -PathType Container)) {
							$removed = $true
							break
						}
						if ($attempt -lt 3) {
							Start-Sleep -Milliseconds ($attempt * 200)
						}
					}
					$failureReason = Get-RemoveFailureReason -Exception $lastRemoveException
					if (-not $removed -and $failureReason -in @('AccessDenied', 'Unknown')) {
						New-Log "[$moduleName] Removal of '$folderPath' was denied ($failureReason); attempting an ACL repair before one more removal attempt..." -Level WARNING
						$null = Repair-ModuleFolderAcl -ModuleName $ModuleName -FolderPath $folderPath -ErrorAction SilentlyContinue
						try {
							Remove-Item -LiteralPath $folderPath -Recurse -Force -ErrorAction Stop -Verbose:$false | Out-Null
						}
						catch {
							$lastRemoveException = $_.Exception
							$failureReason = Get-RemoveFailureReason -Exception $lastRemoveException
						}
						if (-not (Test-Path -LiteralPath $folderPath -PathType Container)) {
							$removed = $true
							New-Log "[$moduleName] Removed '$folderPath' after the ACL repair." -Level SUCCESS
						}
					}
					if ($removed) {
						if ($cleanedItems -notcontains $folderPath) {
							$cleanedItems.Add($folderPath)
						}
					}
					elseif ($ReplaceLockedModuleOnReboot.IsPresent) {
						$rebootSchedule = Register-PendingDeleteOnReboot -ModuleName $ModuleName -FolderPath $folderPath -ErrorAction SilentlyContinue
						if ($rebootSchedule -and $rebootSchedule.Scheduled -gt 0 -and $rebootSchedule.Failed -eq 0) {
							New-Log "[$moduleName] Could not remove '$folderPath' now ($failureReason); scheduled $($rebootSchedule.Scheduled) item(s) for deletion on the next restart." -Level WARNING
							$pendingRebootItems.Add($folderPath)
						}
						else {
							$failureDetail = if ($lastRemoveException) { $lastRemoveException.Message } else { 'folder still exists after all attempts' }
							New-Log "[$moduleName] Failed to remove '$folderPath' and reboot scheduling also failed (scheduled=$($rebootSchedule.Scheduled), failed=$($rebootSchedule.Failed)): $failureDetail" -Level WARNING
							$failedItems.Add([PSCustomObject]@{ Path = $folderPath; Reason = $failureReason })
						}
					}
					else {
						$failureDetail = if ($lastRemoveException) { $lastRemoveException.Message } else { 'folder still exists after three attempts' }
						New-Log "[$moduleName] Failed to remove '$folderPath' ($failureReason): $failureDetail" -Level WARNING
						$failedItems.Add([PSCustomObject]@{ Path = $folderPath; Reason = $failureReason })
					}
				}
			}
		}
		$normalizedBasePath = [IO.Path]::GetFullPath($basePath).TrimEnd([IO.Path]::DirectorySeparatorChar, [IO.Path]::AltDirectorySeparatorChar)
		if ($restrictToCandidatePaths -and $candidatePathSet.Contains($normalizedBasePath)) {
			$flatManifestPath = Join-Path -Path $basePath -ChildPath "$ModuleName.psd1"
			if (-not (Test-Path -LiteralPath $flatManifestPath -PathType Leaf)) {
				New-Log "[$ModuleName] Candidate flat path '$basePath' no longer contains '$ModuleName.psd1'. Skipping." -Level WARNING
				$skippedItems.Add("$basePath [flat]")
				continue
			}
			try {
				$flatManifestData = Import-PowerShellDataFile -LiteralPath $flatManifestPath -ErrorAction Stop
				$flatVersionString = [string]$flatManifestData.ModuleVersion
				$flatPreRelease = if ($flatManifestData.PrivateData -and $flatManifestData.PrivateData.PSData) { [string]$flatManifestData.PrivateData.PSData.Prerelease } else { $null }
				if ($flatPreRelease) { $flatVersionString = "$flatVersionString-$flatPreRelease" }
				$parsedFlatVersion = Parse-ModuleVersion -VersionString $flatVersionString -ErrorAction SilentlyContinue
			}
			catch {
				$parsedFlatVersion = $null
				New-Log "[$ModuleName] Could not inspect candidate flat manifest '$flatManifestPath': $($_.Exception.Message)" -Level WARNING
			}
			if (-not $parsedFlatVersion -or -not $parsedFlatVersion.ModuleVersion) {
				$skippedItems.Add("$basePath [flat]")
				continue
			}
			if ($parsedFlatVersion.ModuleVersion -gt $LatestVersion -or $flatVersionString -eq $latestVersionFullString) {
				New-Log "[$ModuleName] Keeping flat version '$flatVersionString' at '$basePath' because it is not older than retained v$latestVersionFullString." -Level WARNING
				$skippedItems.Add("$basePath [flat:$flatVersionString]")
				continue
			}
			$flatItems = @(Get-ChildItem -LiteralPath $basePath -Force -ErrorAction SilentlyContinue | Where-Object {
					if (-not $_.PSIsContainer) { return $true }
					if ($_.Name -match '^\d+(\.\d+){1,4}(-.+)?$') { return $false }
					$retainedVersionDirectory = Get-ChildItem -LiteralPath $_.FullName -Directory -Recurse -Force -ErrorAction SilentlyContinue | Where-Object {
						$_.Name -eq $latestVersionFullString -or $_.Name -eq $latestVersionString
					} | Select-Object -First 1
					if ($retainedVersionDirectory) {
						New-Log "[$ModuleName] Preserving nested retained-version tree '$($_.FullName)' because it contains '$($retainedVersionDirectory.FullName)'." -Level VERBOSE
						return $false
					}
					return $true
				})
			if ($flatItems.Count -eq 0) { continue }
			$flatTarget = "$basePath [flat:$flatVersionString]"
			$cleanResult.OldVersionCount++
			if (-not $PSCmdlet.ShouldProcess($basePath, "Remove flat module '$ModuleName' version '$flatVersionString' while preserving version directories")) {
				$skippedItems.Add($flatTarget)
				continue
			}
			if (-not $moduleUnloaded) {
				Remove-Module -Name $ModuleName -Force -ErrorAction SilentlyContinue
				$moduleUnloaded = $true
			}
			if ($CleanupBackupPath) {
				try {
					$moduleBackupDir = Join-Path $CleanupBackupPath $ModuleName
					if (-not (Test-Path -LiteralPath $moduleBackupDir -PathType Container)) {
						$null = New-Item -ItemType Directory -Path $moduleBackupDir -Force -ErrorAction Stop
					}
					$backupZipPath = Join-Path $moduleBackupDir ("{0}_{1}.zip" -f $ModuleName, $flatVersionString)
					Compress-Archive -LiteralPath @($flatItems.FullName) -DestinationPath $backupZipPath -CompressionLevel Optimal -Force -ErrorAction Stop
					if (-not (Test-Path -LiteralPath $backupZipPath -PathType Leaf) -or (Get-Item -LiteralPath $backupZipPath -ErrorAction Stop).Length -eq 0) {
						throw "Backup archive '$backupZipPath' was not created or is empty."
					}
					$backupItems.Add($backupZipPath)
				}
				catch {
					New-Log "[$ModuleName] Flat backup failed for '$flatTarget': $($_.Exception.Message). The flat version was kept." -Level WARNING
					$failedItems.Add([PSCustomObject]@{ Path = $flatTarget; Reason = 'BackupFailed' })
					continue
				}
			}
			$lastFlatRemoveException = $null
			foreach ($flatItem in $flatItems) {
				try {
					if ($flatItem.PSIsContainer) { Remove-Item -LiteralPath $flatItem.FullName -Recurse -Force -ErrorAction Stop -Verbose:$false }
					else { Remove-Item -LiteralPath $flatItem.FullName -Force -ErrorAction Stop -Verbose:$false }
				}
				catch { $lastFlatRemoveException = $_.Exception }
			}
			$remainingFlatItems = @($flatItems.FullName | Where-Object { Test-Path -LiteralPath $_ })
			if ($remainingFlatItems.Count -eq 0) {
				$cleanedItems.Add($flatTarget)
				New-Log "[$ModuleName] Removed flat version '$flatVersionString' from '$basePath' and preserved all version directories." -Level SUCCESS
			}
			elseif ($ReplaceLockedModuleOnReboot.IsPresent) {
				$scheduledCount = 0
				$failedScheduleCount = 0
				foreach ($remainingPath in $remainingFlatItems) {
					$rebootSchedule = Register-PendingDeleteOnReboot -ModuleName $ModuleName -FolderPath $remainingPath -ErrorAction SilentlyContinue
					$scheduledCount += $rebootSchedule.Scheduled
					$failedScheduleCount += $rebootSchedule.Failed
				}
				if ($scheduledCount -gt 0 -and $failedScheduleCount -eq 0) { $pendingRebootItems.Add($flatTarget) }
				else { $failedItems.Add([PSCustomObject]@{ Path = $flatTarget; Reason = (Get-RemoveFailureReason -Exception $lastFlatRemoveException) }) }
			}
			else {
				$failedItems.Add([PSCustomObject]@{ Path = $flatTarget; Reason = (Get-RemoveFailureReason -Exception $lastFlatRemoveException) })
			}
		}
	}
	$cleanResult.CleanedPaths = @($cleanedItems | Select-Object -Unique -Verbose:$false)
	$cleanResult.FailedPaths = @($failedItems)
	$cleanResult.PendingRebootPaths = @($pendingRebootItems | Select-Object -Unique -Verbose:$false)
	$cleanResult.SkippedPaths = @($skippedItems | Select-Object -Unique -Verbose:$false)
	$cleanResult.BackupPaths = @($backupItems | Select-Object -Unique -Verbose:$false)
	return $cleanResult
}
#endregion Remove-OutdatedVersions
#region Get-ManifestVersionInfo
function Get-ManifestVersionInfo {
	<#
    .SYNOPSIS
    Extracts normalized module metadata from a manifest or manifest path.
    .DESCRIPTION
    Converts Test-ModuleManifest output into a module inventory record. When parsed data
    is unavailable, it infers the module name, version, path, and author from the file path.
    .PARAMETER ResData
    Object returned by Test-ModuleManifest.
    .PARAMETER Quick
    Uses ResData directly instead of reading ModuleFilePath.
    .PARAMETER ModuleFilePath
    Path to a module manifest used for fallback metadata discovery.
    .INPUTS
    None.
    .OUTPUTS
    System.Management.Automation.PSCustomObject containing module name, version, base
    path, prerelease label, and author; or null when metadata cannot be resolved.
    .EXAMPLE
    $manifest = Test-ModuleManifest 'C:\Modules\Example\1.0.0\Example.psd1'
    Get-ManifestVersionInfo -ResData $manifest -Quick
    Converts validated manifest data into an inventory record.
    .NOTES
    Internal helper used by Get-ModuleInfo.
    .LINK
    Test-ModuleManifest
    #>
	[CmdletBinding()]
	param (
		[Parameter()][object]$ResData,
		[switch]$Quick,
		[string]$ModuleFilePath
	)
	if (-not $ResData -and -not $Quick.IsPresent -and $ModuleFilePath) {
		$module = Get-ModuleformPath -Path $ModuleFilePath
		if ($module) {
			return [PSCustomObject]@{
				ModuleName          = $module.ModuleName
				ModuleVersion       = $module.ModuleVersion
				ModuleVersionString = $module.ModuleVersionString
				IsPreRelease        = $module.IsPrerelease
				PreReleaseLabel     = $module.PreReleaseLabel
				BasePath            = $module.BasePath
				Author              = $module.Author
			}
		}
	}
	if ($Quick.IsPresent -and $ResData) {
		$quickVersionString = $ResData.Version.ToString()
		$quickVersionStringPreRelease = if ($ResData.PrivateData.PSData.Prerelease) { $ResData.PrivateData.PSData.Prerelease } else { $null }
		if ($quickVersionString -and $quickVersionStringPreRelease) {
			$parsedQuickVersion = Parse-ModuleVersion -VersionString "$($quickVersionString)-$($quickVersionStringPreRelease)" -ErrorAction SilentlyContinue
		}
		else {
			$parsedQuickVersion = Parse-ModuleVersion -VersionString $($quickVersionString) -ErrorAction SilentlyContinue
		}
		[version]$quickVersion = if ($parsedQuickVersion) { $parsedQuickVersion.ModuleVersion } else { $null }
		[bool]$quickIsPre = if ($parsedQuickVersion) { $parsedQuickVersion.IsPrerelease } else { $false }
		[string]$quickPreLabel = if ($parsedQuickVersion) { $parsedQuickVersion.PreReleaseLabel } else { $null }
		$quickBasePath = if ($ResData.ModuleBase) { $ResData.ModuleBase } else { $null }
		$quickModuleName = if ($ResData.Name) { $ResData.Name } else { $null }
		if (!$quickVersion) {
			New-Log "Quick mode: Could not parse version '$quickVersionString' using Parse-ModuleVersion." -Level DEBUG
		}
		return [PSCustomObject]@{
			ModuleName          = $quickModuleName
			ModuleVersion       = $quickVersion
			ModuleVersionString = "$($parsedQuickVersion.ModuleVersionString)"
			IsPreRelease        = $quickIsPre
			PreReleaseLabel     = $quickPreLabel
			BasePath            = "$($quickBasePath)"
			Author              = $resData.Author
		}
	}
}
#endregion Get-ManifestVersionInfo
#region Test-IsResourceFile
function Test-IsResourceFile {
	<#
    .SYNOPSIS
    Identifies likely localization or resource files.
    .DESCRIPTION
    Tests a path against common culture-directory, resource-directory, and resource-file
    naming patterns so those files are not treated as module manifests.
    .PARAMETER Path
    File path to evaluate.
    .INPUTS
    None.
    .OUTPUTS
    System.Boolean.
    .EXAMPLE
    Test-IsResourceFile 'C:\Modules\Example\en-US\Example.strings.psd1'
    Returns true for a path under a culture directory.
    .NOTES
    Pattern-based detection can classify unusually named files as resources.
    .LINK
    Get-ModuleInfo
    #>
	[CmdletBinding()]
	param(
		[Parameter(Mandatory)][ValidateNotNullOrEmpty()][string]$Path
	)
	$normalizedPath = $Path -replace '/', '\'
	$fileName = Split-Path -Path $normalizedPath -Leaf
	$fileBaseName = [IO.Path]::GetFileNameWithoutExtension($fileName)
	$parentPath = Split-Path -Path $normalizedPath -Parent
	$parentName = Split-Path -Path $parentPath -Leaf
	$moduleDirectoryName = if ($parentName -match '^\d+(\.\d+){1,3}(-.+)?$') {
		Split-Path -Path (Split-Path -Path $parentPath -Parent) -Leaf
	}
	else {
		$parentName
	}
	# A manifest named after its flat or versioned module directory is always primary.
	if ($fileBaseName -ieq $moduleDirectoryName) {
		return $false
	}
	if ($normalizedPath -match '\\(Resources?|Localization|Localizations|Languages|Lang|Cultures?|i18n|l10n|DSCResources|Settings|Templates?|Tests?|TestData|Data|Runtimes?|InstallerHelpFiles)\\') {
		return $true
	}
	if ($normalizedPath -match '\\[a-z]{2}(-[a-z]{2})?\\[^\\]+\.(psd1|xml)$') {
		return $true
	}
	if ($fileBaseName -match '(^|[._-])(Resources?|Strings|Localized|Messages|Text|Errors|Labels|UI)$') {
		return $true
	}
	if ($fileName -match '^[a-z]{2,3}-[A-Z]{2,3}\.(psd1|xml)$') {
		return $true
	}
	return $false
}
#endregion Test-IsResourceFile
#region Resolve-ModuleVersion
function Resolve-ModuleVersion {
	<#
    .SYNOPSIS
    Resolves version data for a module installation path.
    .DESCRIPTION
    Parses the supplied version string and, when possible, replaces it with metadata from
    the matching module returned by Get-Module -ListAvailable.
    .PARAMETER VersionString
    Initial version string to parse.
    .PARAMETER ModuleName
    Name of the module to resolve.
    .PARAMETER Path
    File or directory path used to select the matching installation.
    .INPUTS
    None.
    .OUTPUTS
    System.Management.Automation.PSCustomObject with Module and VersionPattern properties.
    .EXAMPLE
    Resolve-ModuleVersion -VersionString 1.2.0 -ModuleName Example -Path 'C:\Modules\Example\1.2.0\Example.psd1'
    Resolves the version against the matching installed module.
    .NOTES
    Internal helper used by Get-ModuleformPath.
    .LINK
    Get-Module
    #>
	[CmdletBinding()]
	param (
		[Parameter()][string]$VersionString,
		[Parameter(Mandatory)][string]$ModuleName,
		[Parameter(Mandatory)][ValidateNotNullOrEmpty()][string]$Path
	)
	$versionPattern = Parse-ModuleVersion -VersionString $VersionString
	$module = Get-Module -Name $ModuleName -All -ListAvailable -ErrorAction SilentlyContinue -Verbose:$false | Where-Object { $Path -like ($_.ModuleBase + '\*') } | Sort-Object -Property Version -Descending -ErrorAction SilentlyContinue | Select-Object -First 1 -ErrorAction SilentlyContinue
	if ($module) {
		$versionPattern = Parse-ModuleVersion -VersionString $module.Version
	}
	return [psCustomObject]@{
		Module         = $module
		VersionPattern = $versionPattern
	}
}
#endregion Resolve-ModuleVersion
#region Get-ModuleformPath
function Get-ModuleformPath {
	<#
    .SYNOPSIS
    Infers module metadata from an installation path.
    .DESCRIPTION
    Recognizes common versioned and flat PowerShell module layouts, then resolves the
    module name, version, base path, prerelease label, and author.
    .PARAMETER Path
    Manifest or directory path to inspect.
    .INPUTS
    None.
    .OUTPUTS
    System.Management.Automation.PSCustomObject containing inferred module metadata.
    Unresolved properties are null.
    .EXAMPLE
    Get-ModuleformPath 'C:\Modules\Example\1.2.0\Example.psd1'
    Returns metadata inferred from the versioned module path.
    .NOTES
    Internal helper. The function name is retained for compatibility.
    .LINK
    Resolve-ModuleVersion
    #>
	[CmdletBinding()]
	[OutputType([PSCustomObject])]
	param (
		[Parameter(Mandatory)][string]$Path
	)
	if ([string]::IsNullOrWhiteSpace($Path)) {
		New-Log "Input path cannot be null or empty. Will abort." -Level WARNING
		return [PSCustomObject]@{
			ModuleName          = $null
			BasePath            = $null
			ModuleVersion       = $null
			ModuleVersionString = $null
			IsPrerelease        = $null
			PreReleaseLabel     = $null
			Author              = $null
		}
	}
	$trimmedPath = $Path.TrimEnd('\/')
	$normalizedPath = $trimmedPath -replace '/', '\'
	$versionPattern = '\d+(\.\d+){1,3}(-.+)?'
	$regexVersionOnly = "^$versionPattern$"
	$regexPattern1 = "(?i)^(.*\\Modules\\([^\\]+))\\($versionPattern)(?:\\.*)?$"
	New-Log "Trying Pattern 1 regex: '$regexPattern1' against '$normalizedPath'" -Level VERBOSE
	if ($normalizedPath -match $regexPattern1) {
		if ($Matches -ne $null -and $Matches.Count -ge 3) {
			[string]$modulePath = $Matches[1]
			[string]$moduleName = $Matches[2]
			[string]$matchedVersion = $Matches[3]
			$moduleData = Resolve-ModuleVersion -VersionString $matchedVersion -ModuleName $moduleName -Path $Path
			$versionPattern = $moduleData.VersionPattern
			$module = $moduleData.Module
			return [PSCustomObject]@{
				ModuleName          = $($moduleName)
				BasePath            = $($modulePath)
				ModuleVersion       = $versionPattern.ModuleVersion
				ModuleVersionString = $versionPattern.ModuleVersionString
				IsPrerelease        = $versionPattern.IsPrerelease
				PreReleaseLabel     = $versionPattern.PreReleaseLabel
				Author              = if ($module.Author) { $module.Author } else { $null }
			}
		}
	}
	New-Log "Pattern 1 did NOT match." -Level VERBOSE
	$potentialModuleBasePath = $null
	if (Test-Path -Path $normalizedPath -PathType Container -Verbose:$false) {
		$potentialModuleBasePath = $normalizedPath
		New-Log "Pattern 2: Input '$normalizedPath' is a directory. Assuming it's the ModulePath." -Level VERBOSE
	}
	else {
		$potentialModuleBasePath = Split-Path -Path $normalizedPath -Parent -ErrorAction SilentlyContinue -Verbose:$false
		New-Log "Pattern 2: Input '$normalizedPath' is a file. Assuming parent '$potentialModuleBasePath' is the ModulePath." -Level VERBOSE
	}
	if ($potentialModuleBasePath) {
		$potentialModuleName = Split-Path -Path $potentialModuleBasePath -Leaf -ErrorAction SilentlyContinue -Verbose:$false
		New-Log "Pattern 2: Potential ModuleName (leaf of ModulePath) is '$potentialModuleName'." -Level VERBOSE
		if ($potentialModuleName -match $regexVersionOnly) {
			New-Log "Pattern 2: determined ModuleName '$potentialModuleName' which looks like a version. This is usually incorrect." -Level WARNING
			$parentOfVersionDir = Split-Path -Path $potentialModuleBasePath -Parent -ErrorAction SilentlyContinue -Verbose:$false
			if ($parentOfVersionDir) {
				$betterModuleName = Split-Path -Path $parentOfVersionDir -Leaf -ErrorAction SilentlyContinue -Verbose:$false
				if ($betterModuleName -and $betterModuleName -ne 'Modules') {
					$moduleData = Resolve-ModuleVersion -VersionString $potentialModuleName -ModuleName $betterModuleName -Path $Path
					$versionPattern = $moduleData.VersionPattern
					$module = $moduleData.Module
					return [PSCustomObject]@{
						ModuleName          = $($betterModuleName)
						BasePath            = $($parentOfVersionDir)
						ModuleVersion       = $versionPattern.ModuleVersion
						ModuleVersionString = $versionPattern.ModuleVersionString
						IsPrerelease        = $versionPattern.IsPrerelease
						PreReleaseLabel     = $versionPattern.PreReleaseLabel
						Author              = if ($module.Author) { $module.Author } else { $null }
					}
				}
			}
		}
		elseif ($potentialModuleName -and $potentialModuleName -ne 'Modules') {
			New-Log "Pattern 2: Found potential module name '$potentialModuleName', attempting to find version information" -Level VERBOSE
			$version = $null
			$pathParts = $normalizedPath -split '\\'
			foreach ($part in $pathParts) {
				if ($part -match $regexVersionOnly) {
					$version = $part
					New-Log "Pattern 2: Found version '$version' in path component" -Level VERBOSE
					break
				}
			}
			if (-not $version -and $normalizedPath -like "*.psd1") {
				try {
					$manifestContent = Get-Content -Path $normalizedPath -Raw -ErrorAction SilentlyContinue -Verbose:$false
					if ($manifestContent -match "ModuleVersion\s*=\s*['`"]([^'`"]+)") {
						$version = $Matches[1]
						New-Log "Pattern 2: Found version '$version' in module manifest" -Level VERBOSE
					}
				}
				catch {
					New-Log "Pattern 2: Error reading module manifest." -Level ERROR
				}
			}
			$moduleData = Resolve-ModuleVersion -VersionString $version -ModuleName $potentialModuleName -Path $Path
			$versionPattern = $moduleData.VersionPattern
			$module = $moduleData.Module
			return [PSCustomObject]@{
				ModuleName          = $($potentialModuleName)
				BasePath            = $($potentialModuleBasePath)
				ModuleVersion       = $versionPattern.ModuleVersion
				ModuleVersionString = $versionPattern.ModuleVersionString
				IsPrerelease        = $versionPattern.IsPrerelease
				PreReleaseLabel     = $versionPattern.PreReleaseLabel
				Author              = if ($module -and $module.Author) { $module.Author } else { $null }
			}
		}
	}
	return [PSCustomObject]@{
		ModuleName          = $null
		BasePath            = $null
		ModuleVersion       = $null
		ModuleVersionString = $null
		IsPrerelease        = $null
		PreReleaseLabel     = $null
		Author              = $null
	}
}
#endregion Get-ModuleformPath
#region Get-ModuleInfoFromXml
function Get-ModuleInfoFromXml {
	<#
    .SYNOPSIS
    Reads module metadata from PSGetModuleInfo.xml or a NuSpec file.
    .DESCRIPTION
    Parses PowerShell-serialized module metadata or NuGet package metadata, including
    normalized prerelease data, and returns an inventory record compatible with
    Get-ModuleInfo. NuSpec element lookup is namespace-independent, and its module base
    path is inferred from the package's installation directory.
    .PARAMETER XmlFilePath
    Path to a PSGetModuleInfo.xml or .nuspec file.
    .INPUTS
    None.
    .OUTPUTS
    System.Management.Automation.PSCustomObject containing module name, version, base
    path, prerelease label, and author; or null when required data is missing.
    .EXAMPLE
    Get-ModuleInfoFromXml 'C:\Modules\Example\1.2.0\PSGetModuleInfo.xml'
    Reads the saved module metadata.
    .EXAMPLE
    Get-ModuleInfoFromXml 'C:\Modules\Example\1.2.0\Example.nuspec'
    Reads NuGet package metadata and infers C:\Modules\Example as the module base path.
    .NOTES
    Internal helper used by Get-ModuleInfo.
    .LINK
    Get-ModuleInfo
    #>
	[CmdletBinding()]
	param (
		[Parameter(Mandatory)][string]$XmlFilePath
	)
	try {
		[xml]$xmlContent = Get-Content -LiteralPath $XmlFilePath -Raw -ErrorAction Stop -Verbose:$false
		$isNuSpec = ([IO.Path]::GetExtension($XmlFilePath) -ieq '.nuspec') -or ($xmlContent.DocumentElement.LocalName -ieq 'package')
		$metadataType = if ($isNuSpec) { 'NuSpec' } else { 'PSGet XML' }
		$nameValue = $null
		$authorValue = $null
		$versionValue = $null
		$locationValue = $null
		$normalizedVersionValue = $null
		$prereleaseBoolText = $null
		$prereleaseStringText = $null
		$basePathValue = $null
		if ($isNuSpec) {
			$metadataNode = $xmlContent.SelectSingleNode("/*[local-name()='package']/*[local-name()='metadata']")
			if ($null -eq $metadataNode) {
				New-Log "NuSpec metadata element was not found in '$XmlFilePath'." -Level WARNING
				return $null
			}
			$nameNode = $metadataNode.SelectSingleNode("*[local-name()='id']")
			$versionNode = $metadataNode.SelectSingleNode("*[local-name()='version']")
			$authorNode = $metadataNode.SelectSingleNode("*[local-name()='authors']")
			if ($null -eq $authorNode) { $authorNode = $metadataNode.SelectSingleNode("*[local-name()='owners']") }
			$nameValue = if ($nameNode) { $nameNode.InnerText.Trim() } else { $null }
			$versionValue = if ($versionNode) { $versionNode.InnerText.Trim() } else { $null }
			$authorValue = if ($authorNode) { $authorNode.InnerText.Trim() } else { $null }
			$metadataDirectory = [IO.DirectoryInfo]::new([IO.Path]::GetDirectoryName($XmlFilePath))
			$templateTokenPattern = '^\$[^$]+\$$'
			$hasTemplateToken = ($nameValue -match $templateTokenPattern) -or
			($versionValue -match $templateTokenPattern) -or
			($authorValue -match $templateTokenPattern)
			$manifestData = $null
			$manifestPath = $null
			if ($hasTemplateToken) {
				$manifestCandidates = @(Get-ChildItem -LiteralPath $metadataDirectory.FullName -File -Filter '*.psd1' -ErrorAction SilentlyContinue |
						Where-Object { $_.BaseName -notmatch '(?i)(\.strings|\.types|\.format)$' } |
						Sort-Object -Property @{ Expression = { $_.BaseName -ieq $nameValue }; Descending = $true }, Name)
				if ($manifestCandidates.Count -gt 0) {
					$manifestPath = $manifestCandidates[0].FullName
					try {
						$manifestData = Import-PowerShellDataFile -Path $manifestPath -ErrorAction Stop
					}
					catch {
						New-Log "NuSpec: Could not read sibling manifest '$manifestPath' while resolving template metadata." -Level VERBOSE
					}
				}
			}
			if ($nameValue -match $templateTokenPattern) {
				$nameValue = if ($manifestPath) {
					[IO.Path]::GetFileNameWithoutExtension($manifestPath)
				}
				elseif ([IO.Path]::GetFileNameWithoutExtension($XmlFilePath) -notmatch $templateTokenPattern) {
					[IO.Path]::GetFileNameWithoutExtension($XmlFilePath)
				}
				else {
					$null
				}
			}
			if ($versionValue -match $templateTokenPattern) {
				$manifestVersion = if ($manifestData -and $manifestData.ModuleVersion) { [string]$manifestData.ModuleVersion } else { $null }
				$manifestPrerelease = if ($manifestData -and $manifestData.PrivateData -and $manifestData.PrivateData.PSData) { [string]$manifestData.PrivateData.PSData.Prerelease } else { $null }
				if ($manifestVersion) {
					$versionValue = if ($manifestPrerelease) { "$manifestVersion-$manifestPrerelease" } else { $manifestVersion }
					New-Log "NuSpec: Resolved template version from sibling manifest '$manifestPath' as '$versionValue'." -Level VERBOSE
				}
				else {
					$directoryVersion = Parse-ModuleVersion -VersionString $metadataDirectory.Name -ErrorAction SilentlyContinue
					if ($directoryVersion) {
						$versionValue = $metadataDirectory.Name
						New-Log "NuSpec: Resolved template version from installation directory as '$versionValue'." -Level VERBOSE
					}
				}
			}
			if ($authorValue -match $templateTokenPattern) {
				$authorValue = if ($manifestData -and $manifestData.Author) { [string]$manifestData.Author } else { $null }
			}
			if ($versionValue -match $templateTokenPattern) {
				New-Log "NuSpec: Could not resolve template version '$versionValue' in '$XmlFilePath'." -Level WARNING
				return $null
			}
			$normalizedVersionValue = if ($versionValue) { ($versionValue -split '\+', 2)[0] } else { $null }
			$ancestor = $metadataDirectory
			while ($null -ne $ancestor) {
				if (-not [string]::IsNullOrWhiteSpace($nameValue) -and $ancestor.Name -ieq $nameValue) {
					$basePathValue = $ancestor.FullName
					break
				}
				$ancestor = $ancestor.Parent
			}
			if (-not $basePathValue) {
				$directoryVersion = Parse-ModuleVersion -VersionString $metadataDirectory.Name -ErrorAction SilentlyContinue
				$basePathValue = if ($directoryVersion -and $null -ne $metadataDirectory.Parent) {
					$metadataDirectory.Parent.FullName
				}
				else {
					$metadataDirectory.FullName
				}
			}
		}
		else {
			$nsManager = New-Object System.Xml.XmlNamespaceManager($xmlContent.NameTable)
			$nsManager.AddNamespace('ps', 'http://schemas.microsoft.com/powershell/2004/04')
			$nameNode = $xmlContent.SelectSingleNode("//ps:S[@N='Name']", $nsManager)
			$nameValue = if ($nameNode) { $nameNode.'#text' } else { $null }
			$authorNode = $xmlContent.SelectSingleNode("//ps:S[@N='Author']", $nsManager)
			$authorValue = if ($authorNode) { $authorNode.'#text' } else { $null }
			$versionNode = $xmlContent.SelectSingleNode("//ps:S[@N='Version']", $nsManager)
			$versionValue = if ($versionNode) { $versionNode.'#text' } else { $null }
			$locationNode = $xmlContent.SelectSingleNode("//ps:S[@N='InstalledLocation']", $nsManager)
			$locationValue = if ($locationNode) { $locationNode.'#text' } else { $null }
			$normalizedVersionNode = $xmlContent.SelectSingleNode("//ps:Obj[@N='AdditionalMetadata']/MS/ps:S[@N='NormalizedVersion']", $nsManager)
			if (-not $normalizedVersionNode) {
				$normalizedVersionNode = $xmlContent.SelectSingleNode("//ps:S[@N='NormalizedVersion']", $nsManager)
			}
			$normalizedVersionValue = if ($normalizedVersionNode) { $normalizedVersionNode.'#text' } else { $null }
			$prereleaseBoolNode = $xmlContent.SelectSingleNode("//ps:B[@N='IsPrerelease']", $nsManager)
			$prereleaseBoolText = if ($prereleaseBoolNode) { $prereleaseBoolNode.'#text' } else { $null }
			$prereleaseStringNode = $xmlContent.SelectSingleNode("//ps:Obj[@N='AdditionalMetadata']/MS/ps:S[@N='IsPrerelease']", $nsManager)
			if (-not $prereleaseStringNode) {
				$prereleaseStringNode = $xmlContent.SelectSingleNode("//ps:S[@N='IsPrerelease']", $nsManager)
			}
			$prereleaseStringText = if ($prereleaseStringNode) { $prereleaseStringNode.'#text' } else { $null }
		}
		$parsedVersionInfo = $null
		$isPrereleaseFromParse = $false
		$preReleaseLabelFromParse = $null
		$moduleVersionObject = $null
		if ($normalizedVersionValue) {
			New-Log "$metadataType`: Attempting to parse normalized version '$normalizedVersionValue'." -Level VERBOSE
			$parsedVersionInfo = Parse-ModuleVersion -VersionString $normalizedVersionValue -ErrorAction SilentlyContinue
			if ($parsedVersionInfo) {
				New-Log "$metadataType`: Parsed normalized version '$normalizedVersionValue'. IsPre: $($parsedVersionInfo.IsPrerelease), Label: '$($parsedVersionInfo.PreReleaseLabel)'." -Level VERBOSE
			}
			else {
				New-Log "$metadataType`: Could not parse normalized version '$normalizedVersionValue'." -Level DEBUG
			}
		}
		if (-not $parsedVersionInfo -and $versionValue) {
			New-Log "$metadataType`: Attempting to parse version '$versionValue' (normalized version failed or was unavailable)." -Level VERBOSE
			$parsedVersionInfo = Parse-ModuleVersion -VersionString $versionValue -ErrorAction SilentlyContinue
			if ($parsedVersionInfo) {
				New-Log "$metadataType`: Parsed version '$versionValue'. IsPre: $($parsedVersionInfo.IsPrerelease), Label: '$($parsedVersionInfo.PreReleaseLabel)'." -Level VERBOSE
			}
			else {
				New-Log "$metadataType`: Could not parse version '$versionValue' on $XmlFilePath." -Level WARNING
			}
		}
		if ($parsedVersionInfo) {
			$moduleVersionObject = $parsedVersionInfo.ModuleVersion
			$isPrereleaseFromParse = $parsedVersionInfo.IsPrerelease
			$preReleaseLabelFromParse = $parsedVersionInfo.PreReleaseLabel
		}
		else {
			if ($versionValue) {
				try {
					$moduleVersionObject = [System.Version]$versionValue
					New-Log "$metadataType`: Created System.Version from '$versionValue' as a fallback." -Level DEBUG
				}
				catch {
					New-Log "$metadataType`: Could not create a System.Version from '$versionValue' on $XmlFilePath" -Level EXTENDEDERROR
				}
			}
		}
		$isPrereleaseFromXmlFlag = $false
		if (($prereleaseBoolText -is [string] -and $prereleaseBoolText.ToLowerInvariant() -eq 'true') -or
			($prereleaseStringText -is [string] -and $prereleaseStringText.ToLowerInvariant() -eq 'true')) {
			$isPrereleaseFromXmlFlag = $true
			New-Log "$metadataType`: An explicit IsPrerelease flag is true (Bool: '$prereleaseBoolText', String: '$prereleaseStringText')." -Level VERBOSE
		}
		$finalIsPrerelease = $isPrereleaseFromParse -or $isPrereleaseFromXmlFlag
		$finalPreReleaseLabel = $preReleaseLabelFromParse
		if ($nameValue -and $versionValue) {
			if (-not $isNuSpec -and $locationValue -and $nameValue) {
				try {
					$locationLeaf = Split-Path -Path $locationValue.TrimEnd('\', '/') -Leaf
					$basePathValue = if ($locationLeaf -ieq $nameValue) {
						$locationValue.TrimEnd('\', '/')
					}
					else {
						Join-Path -Path $locationValue -ChildPath $nameValue -ErrorAction Stop -Verbose:$false
					}
				}
				catch {
					New-Log "$metadataType`: Error constructing BasePath from location '$locationValue' and name '$nameValue'." -Level ERROR
				}
			}
			elseif (-not $isNuSpec) {
				New-Log "$metadataType`: Cannot construct BasePath; InstalledLocation or Name is missing. Location: '$locationValue', Name: '$nameValue'." -Level VERBOSE
			}
			$result = [PSCustomObject]@{
				ModuleName          = $nameValue
				ModuleVersion       = $moduleVersionObject
				ModuleVersionString = $versionValue
				BasePath            = if ($basePathValue) { "$basePathValue" } else { $null }
				isPreRelease        = $finalIsPrerelease
				PreReleaseLabel     = if ($finalIsPrerelease -and $finalPreReleaseLabel) { $finalPreReleaseLabel } else { $null }
				Author              = if ($authorValue) { $authorValue } else { $null }
			}
			New-Log "$metadataType parsed: Name='$($result.ModuleName)', VersionObj='$($result.ModuleVersion)', OrigVerStr='$($result.ModuleVersionString)', BasePath='$($result.BasePath)', IsPre=$($result.isPreRelease), Label='$($result.PreReleaseLabel)'." -Level VERBOSE
			return $result
		}
		else {
			New-Log "Could not find required name or version metadata in '$XmlFilePath'. Name: '$nameValue', Version: '$versionValue'." -Level WARNING
			return $null
		}
	}
	catch {
		New-Log "Error parsing XML metadata file '$XmlFilePath': $($_.Exception.Message)" -Level ERROR
		return $null
	}
}
#endregion Get-ModuleInfoFromXml
#region Parse-ModuleVersion
function Parse-ModuleVersion {
	<#
    .SYNOPSIS
    Parses numeric and prerelease module version strings.
    .DESCRIPTION
    Separates a two-to-four-part numeric version from an optional SemVer-style prerelease
    label and returns both the original and normalized values.
    .PARAMETER VersionString
    Version string to parse.
    .INPUTS
    None.
    .OUTPUTS
    System.Management.Automation.PSCustomObject containing ModuleVersion,
    ModuleVersionString, IsPrerelease, PreReleaseLabel, and related normalized values;
    or null when the numeric version is invalid.
    .EXAMPLE
    Parse-ModuleVersion '2.0.0-preview.3'
    Returns version 2.0.0 with prerelease label preview.3.
    .NOTES
    Build metadata is not parsed.
    .LINK
    Compare-ModuleVersion
    #>
	[CmdletBinding()]
	param (
		[Parameter()][string]$VersionString
	)
	if ([string]::IsNullOrWhiteSpace($VersionString)) { return $null }
	[version]$version = $null
	[string]$baseVersionString = $VersionString
	[string]$prereleasePart = $null
	[bool]$isSemVerStyle = $false
	[bool]$isPrerelease = $false
	$semVerRegex = '^(\d+(\.\d+){1,3})-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)$'
	if ($VersionString -match $semVerRegex) {
		$baseVersionString = $Matches[1]
		$prereleasePart = $Matches[3]
		$isSemVerStyle = $true
		$isPrerelease = $true
		New-Log "Parse-ModuleVersion: Matched SemVer pattern. Base:'$baseVersionString', Label:'$prereleasePart'" -Level VERBOSE
	}
	else {
		$baseVersionString = $VersionString
	}
	$isParseable = [version]::TryParse($baseVersionString, [ref]$version)
	if ($isParseable) {
		return [PSCustomObject]@{
			ModuleVersionStringNoPrefix = $baseVersionString
			ModuleVersionString         = $VersionString
			ModuleVersion               = $version
			IsSemVer                    = $isSemVerStyle
			IsPrerelease                = $isPrerelease
			PreReleaseLabel             = if (![string]::IsNullOrEmpty($prereleasePart)) { $prereleasePart } else { $null }
			PreReleaseVersion           = if (![string]::IsNullOrEmpty($prereleasePart)) { "$($version)-$($prereleasePart)" } else { $null }
		}
	}
	else {
		New-Log "Parse-ModuleVersion: Could not parse base version string '$baseVersionString' (derived from original '$VersionString') into a [System.Version] object." -Level WARNING
		return $null
	}
}
#endregion Parse-ModuleVersion
#region Compare-ModuleVersion
function Compare-ModuleVersion {
	<#
    .SYNOPSIS
    Compares two module version strings.
    .DESCRIPTION
    Compares numeric versions first, then prerelease labels. For equal numeric versions,
    a prerelease is treated as newer than a stable version. Recognized label priority is
    dev, alpha, beta, preview, then rc; numeric label suffixes break ties.
    .PARAMETER VersionA
    Current or first version.
    .PARAMETER VersionB
    Candidate or second version.
    .PARAMETER ReturnBoolean
    Returns true only when VersionB is newer than VersionA. Without this switch, returns
    the version string considered newer.
    .INPUTS
    None.
    .OUTPUTS
    System.Boolean when ReturnBoolean is used; otherwise System.String.
    .EXAMPLE
    Compare-ModuleVersion -VersionA '1.0.0-beta1' -VersionB '1.0.0-beta2' -ReturnBoolean
    Returns true.
    .NOTES
    The prerelease ordering is script-specific and intentionally differs from SemVer,
    where a stable release normally has higher precedence than its prereleases.
    .LINK
    Parse-ModuleVersion
    #>
	[CmdletBinding()]
	param (
		[Parameter(Mandatory)][string]$VersionA,
		[Parameter(Mandatory)][string]$VersionB,
		[Parameter()][switch]$ReturnBoolean
	)
	if ([string]::IsNullOrWhiteSpace($VersionA) -or [string]::IsNullOrWhiteSpace($VersionB)) {
		New-Log "Compare-ModuleVersion: One or both versions are null or empty." -Level VERBOSE
		if ($ReturnBoolean) { return $false } else { return $VersionA }
	}
	$typePriority = @{
		'dev'     = 5
		'alpha'   = 4
		'beta'    = 3
		'preview' = 2
		'rc'      = 1
	}
	$baseVersionA, $prereleaseA = $VersionA -split '-', 2
	$baseVersionB, $prereleaseB = $VersionB -split '-', 2
	try {
		$versionObjectA = [System.Version]::new($baseVersionA)
		$versionObjectB = [System.Version]::new($baseVersionB)
		$baseComparison = $versionObjectA.CompareTo($versionObjectB)
		if ($baseComparison -ne 0) {
			New-Log "Compare-ModuleVersion: Base versions differ - A=$baseVersionA, B=$baseVersionB. Result=$baseComparison" -Level VERBOSE
			if ($ReturnBoolean) {
				return $baseComparison -lt 0
			}
			else {
				return $(if ($baseComparison -gt 0) { $VersionA } else { $VersionB })
			}
		}
	}
	catch {
		New-Log "Compare-ModuleVersion: Error parsing version strings. Falling back to string comparison." -Level ERROR
		if ($ReturnBoolean) { return $false } else { return $VersionA }
	}
	if ($prereleaseA -and -not $prereleaseB) {
		New-Log "Compare-ModuleVersion: VersionA has prerelease ($prereleaseA), VersionB doesn't. A is newer." -Level VERBOSE
		if ($ReturnBoolean) { return $false } else { return $VersionA }
	}
	elseif (-not $prereleaseA -and $prereleaseB) {
		New-Log "Compare-ModuleVersion: VersionB has prerelease ($prereleaseB), VersionA doesn't. B is newer." -Level VERBOSE
		if ($ReturnBoolean) { return $true } else { return $VersionB }
	}
	elseif (-not $prereleaseA -and -not $prereleaseB) {
		New-Log "Compare-ModuleVersion: Neither version has prerelease. Versions are equal." -Level VERBOSE
		if ($ReturnBoolean) { return $false } else { return $VersionA }
	}
	$prereleaseA = $prereleaseA.ToLower().Trim('.- ')
	$prereleaseB = $prereleaseB.ToLower().Trim('.- ')
	$regex = "^($(($typePriority.Keys | ForEach-Object {[regex]::Escape($_)}) -join '|'))(?:[\.\-_]?(\d+))?$"
	$matchA = [regex]::Match($prereleaseA, $regex)
	$matchB = [regex]::Match($prereleaseB, $regex)
	if (-not $matchA.Success -or -not $matchB.Success) {
		New-Log "Compare-ModuleVersion: Non-standard prerelease format. Performing simple string comparison." -Level VERBOSE
		$comparisonResult = $prereleaseA.CompareTo($prereleaseB)
		if ($ReturnBoolean) {
			return $comparisonResult -lt 0
		}
		else {
			return $(if ($comparisonResult -ge 0) { $VersionA } else { $VersionB })
		}
	}
	$typeA = $matchA.Groups[1].Value
	$numberA = if ([string]::IsNullOrEmpty($matchA.Groups[2].Value)) { 0 } else { [int]$matchA.Groups[2].Value }
	$typeB = $matchB.Groups[1].Value
	$numberB = if ([string]::IsNullOrEmpty($matchB.Groups[2].Value)) { 0 } else { [int]$matchB.Groups[2].Value }
	New-Log "Compare-ModuleVersion: Comparing prerelease A='$typeA'($numberA) vs B='$typeB'($numberB)" -Level VERBOSE
	if ($typeA -ne $typeB) {
		$priorityA = $typePriority[$typeA]
		$priorityB = $typePriority[$typeB]
		New-Log "Prerelease types differ. Priority A=$priorityA, B=$priorityB." -Level VERBOSE
		if ($ReturnBoolean) {
			return $priorityB -gt $priorityA
		}
		else {
			return $(if ($priorityA -gt $priorityB) { $VersionA } else { $VersionB })
		}
	}
	New-Log "Prerelease types are the same ('$typeA'). Comparing numbers: A=$numberA, B=$numberB." -Level VERBOSE
	if ($ReturnBoolean) {
		return $numberB -gt $numberA
	}
	else {
		return $(if ($numberA -ge $numberB) { $VersionA } else { $VersionB })
	}
}
#endregion Compare-ModuleVersion
#region Parse-ModuleVersion
function Parse-ModuleVersion {
	<#
    .SYNOPSIS
    Parses numeric and prerelease module version strings.
    .DESCRIPTION
    Separates a two-to-four-part numeric version from an optional SemVer-style prerelease
    label and returns both the original and normalized values.
    .PARAMETER VersionString
    Version string to parse.
    .INPUTS
    None.
    .OUTPUTS
    System.Management.Automation.PSCustomObject containing ModuleVersion,
    ModuleVersionString, IsPrerelease, PreReleaseLabel, and related normalized values;
    or null when the numeric version is invalid.
    .EXAMPLE
    Parse-ModuleVersion '2.0.0-preview.3'
    Returns version 2.0.0 with prerelease label preview.3.
    .NOTES
    Build metadata is not parsed.
    .LINK
    Compare-ModuleVersion
    #>
	[CmdletBinding()]
	param (
		[Parameter()][string]$VersionString
	)
	if ([string]::IsNullOrWhiteSpace($VersionString)) { return $null }
	[version]$version = $null
	[string]$baseVersionString = $VersionString
	[string]$prereleasePart = $null
	[bool]$isSemVerStyle = $false
	[bool]$isPrerelease = $false
	$semVerRegex = '^(\d+(\.\d+){1,3})-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)$'
	if ($VersionString -match $semVerRegex) {
		$baseVersionString = $Matches[1]
		$prereleasePart = $Matches[3]
		$isSemVerStyle = $true
		$isPrerelease = $true
		New-Log "Parse-ModuleVersion: Matched SemVer pattern. Base:'$baseVersionString', Label:'$prereleasePart'" -Level VERBOSE
	}
	else {
		$baseVersionString = $VersionString
	}
	$isParseable = [version]::TryParse($baseVersionString, [ref]$version)
	if ($isParseable) {
		return [PSCustomObject]@{
			ModuleVersionStringNoPrefix = $baseVersionString
			ModuleVersionString         = $VersionString
			ModuleVersion               = $version
			IsSemVer                    = $isSemVerStyle
			IsPrerelease                = $isPrerelease
			PreReleaseLabel             = if (![string]::IsNullOrEmpty($prereleasePart)) { $prereleasePart } else { $null }
			PreReleaseVersion           = if (![string]::IsNullOrEmpty($prereleasePart)) { "$($version)-$($prereleasePart)" } else { $null }
		}
	}
	else {
		New-Log "Parse-ModuleVersion: Could not parse base version string '$baseVersionString' (derived from original '$VersionString') into a [System.Version] object." -Level WARNING
		return $null
	}
}
#endregion Parse-ModuleVersion
#region Compare-ModuleVersion
function Compare-ModuleVersion {
	<#
    .SYNOPSIS
    Compares two module version strings.
    .DESCRIPTION
    Compares numeric versions first, then prerelease labels. For equal numeric versions,
    a prerelease is treated as newer than a stable version. Recognized label priority is
    dev, alpha, beta, preview, then rc; numeric label suffixes break ties.
    .PARAMETER VersionA
    Current or first version.
    .PARAMETER VersionB
    Candidate or second version.
    .PARAMETER ReturnBoolean
    Returns true only when VersionB is newer than VersionA. Without this switch, returns
    the version string considered newer.
    .INPUTS
    None.
    .OUTPUTS
    System.Boolean when ReturnBoolean is used; otherwise System.String.
    .EXAMPLE
    Compare-ModuleVersion -VersionA '1.0.0-beta1' -VersionB '1.0.0-beta2' -ReturnBoolean
    Returns true.
    .NOTES
    The prerelease ordering is script-specific and intentionally differs from SemVer,
    where a stable release normally has higher precedence than its prereleases.
    .LINK
    Parse-ModuleVersion
    #>
	[CmdletBinding()]
	param (
		[Parameter(Mandatory)][string]$VersionA,
		[Parameter(Mandatory)][string]$VersionB,
		[Parameter()][switch]$ReturnBoolean
	)
	if ([string]::IsNullOrWhiteSpace($VersionA) -or [string]::IsNullOrWhiteSpace($VersionB)) {
		New-Log "Compare-ModuleVersion: One or both versions are null or empty." -Level VERBOSE
		if ($ReturnBoolean) { return $false } else { return $VersionA }
	}
	$typePriority = @{
		'dev'     = 5
		'alpha'   = 4
		'beta'    = 3
		'preview' = 2
		'rc'      = 1
	}
	$baseVersionA, $prereleaseA = $VersionA -split '-', 2
	$baseVersionB, $prereleaseB = $VersionB -split '-', 2
	try {
		$versionObjectA = [System.Version]::new($baseVersionA)
		$versionObjectB = [System.Version]::new($baseVersionB)
		$baseComparison = $versionObjectA.CompareTo($versionObjectB)
		if ($baseComparison -ne 0) {
			New-Log "Compare-ModuleVersion: Base versions differ - A=$baseVersionA, B=$baseVersionB. Result=$baseComparison" -Level VERBOSE
			if ($ReturnBoolean) {
				return $baseComparison -lt 0
			}
			else {
				return $(if ($baseComparison -gt 0) { $VersionA } else { $VersionB })
			}
		}
	}
	catch {
		New-Log "Compare-ModuleVersion: Error parsing version strings. Falling back to string comparison." -Level ERROR
		if ($ReturnBoolean) { return $false } else { return $VersionA }
	}
	if ($prereleaseA -and -not $prereleaseB) {
		New-Log "Compare-ModuleVersion: VersionA has prerelease ($prereleaseA), VersionB doesn't. A is newer." -Level VERBOSE
		if ($ReturnBoolean) { return $false } else { return $VersionA }
	}
	elseif (-not $prereleaseA -and $prereleaseB) {
		New-Log "Compare-ModuleVersion: VersionB has prerelease ($prereleaseB), VersionA doesn't. B is newer." -Level VERBOSE
		if ($ReturnBoolean) { return $true } else { return $VersionB }
	}
	elseif (-not $prereleaseA -and -not $prereleaseB) {
		New-Log "Compare-ModuleVersion: Neither version has prerelease. Versions are equal." -Level VERBOSE
		if ($ReturnBoolean) { return $false } else { return $VersionA }
	}
	$prereleaseA = $prereleaseA.ToLower().Trim('.- ')
	$prereleaseB = $prereleaseB.ToLower().Trim('.- ')
	$regex = "^($(($typePriority.Keys | ForEach-Object {[regex]::Escape($_)}) -join '|'))(?:[\.\-_]?(\d+))?$"
	$matchA = [regex]::Match($prereleaseA, $regex)
	$matchB = [regex]::Match($prereleaseB, $regex)
	if (-not $matchA.Success -or -not $matchB.Success) {
		New-Log "Compare-ModuleVersion: Non-standard prerelease format. Performing simple string comparison." -Level VERBOSE
		$comparisonResult = $prereleaseA.CompareTo($prereleaseB)
		if ($ReturnBoolean) {
			return $comparisonResult -lt 0
		}
		else {
			return $(if ($comparisonResult -ge 0) { $VersionA } else { $VersionB })
		}
	}
	$typeA = $matchA.Groups[1].Value
	$numberA = if ([string]::IsNullOrEmpty($matchA.Groups[2].Value)) { 0 } else { [int]$matchA.Groups[2].Value }
	$typeB = $matchB.Groups[1].Value
	$numberB = if ([string]::IsNullOrEmpty($matchB.Groups[2].Value)) { 0 } else { [int]$matchB.Groups[2].Value }
	New-Log "Compare-ModuleVersion: Comparing prerelease A='$typeA'($numberA) vs B='$typeB'($numberB)" -Level VERBOSE
	if ($typeA -ne $typeB) {
		$priorityA = $typePriority[$typeA]
		$priorityB = $typePriority[$typeB]
		New-Log "Prerelease types differ. Priority A=$priorityA, B=$priorityB." -Level VERBOSE
		if ($ReturnBoolean) {
			return $priorityB -gt $priorityA
		}
		else {
			return $(if ($priorityA -gt $priorityB) { $VersionA } else { $VersionB })
		}
	}
	New-Log "Prerelease types are the same ('$typeA'). Comparing numbers: A=$numberA, B=$numberB." -Level VERBOSE
	if ($ReturnBoolean) {
		return $numberB -gt $numberA
	}
	else {
		return $(if ($numberA -ge $numberB) { $VersionA } else { $VersionB })
	}
}
#endregion Compare-ModuleVersion
if (-not (Get-Command -Name New-Log -ErrorAction SilentlyContinue)) {
	try {
		$newLogUrl = 'https://raw.githubusercontent.com/Harze2k/Shared-PowerShell-Functions/main/New-Log.ps1'
		. ([ScriptBlock]::Create((Invoke-WebRequest -Uri $newLogUrl -UseBasicParsing -ErrorAction Stop).Content))
	}
	catch {
		Write-Warning "Could not load New-Log from GitHub: $($_.Exception.Message) -- using built-in fallback."
		function New-Log {
			[CmdletBinding()]
			param(
				[Parameter(ValueFromPipeline, Position = 0)]$Message,
				[Parameter(Position = 1)][string]$Level = 'INFO',
				[Parameter()][string]$LogFilePath,
				[Parameter()]$ErrorObject
			)
			process {
				$timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss.fff'
				$color = switch ($Level) {
					'ERROR' { 'Red' }
					'EXTENDEDERROR' { 'Red' }
					'WARNING' { 'Yellow' }
					'SUCCESS' { 'Green' }
					'DEBUG' { 'Blue' }
					'VERBOSE' { 'Cyan' }
					default { 'White' }
				}
				$suffix = if ($ErrorObject) { " [$($ErrorObject.Exception.Message)]" } else { '' }
				$logLine = "[$timestamp][$Level] $Message$suffix"
				Write-Host $logLine -ForegroundColor $color
				if ($LogFilePath) {
					try {
						Add-Content -Path $LogFilePath -Value $logLine -ErrorAction Stop
					}
					catch {
						Write-Warning "Failed to write to log file '$LogFilePath': $($_.Exception.Message)"
					}
				}
			}
		}
	}
}
### CONFIGURATION ###
$repos = @("PSGallery", "Nuget", "NugetGallery") #PSGallery, Nuget, NugetGallery are the only valid options for this script. If you want to use a different repository, please modify the script accordingly.
if (-not (Check-PSResourceRepository -Repositories $repos)) {
	New-Log "One or more selected repositories are not configured correctly: $($repos -join ', ')." -Level WARNING
	exit 1
}
$ignoredModules = @('Example2.Diagnostics', 'BurntToast', 'AppLocker', 'pki', 'provisioning')
$blackList = @{
	'Microsoft.Graph.Beta' = @("Nuget", "NugetGallery")
	'Microsoft.Graph'      = @("Nuget", "NugetGallery")
}
$paths = $env:PSModulePath.Split(';') | Where-Object { $_ -notmatch '\\7\\Modules|.vscode|System32' }
### MAIN SCRIPT EXECUTION ###
$script:moduleInfo = Get-ModuleInfo -Paths $paths -IgnoredModules $ignoredModules
$outdated = Get-ModuleUpdateStatus -ModuleInventory $moduleInfo -TimeoutSeconds 45 -Repositories $repos -MatchAuthor -BlackList $blackList
if ($outdated) {
	#Remove -WhatIf to actually perform the updates.
	#Use -Clean to remove old versions after update.
	#Use -PreRelease to include prerelease versions in the update check.
	#Use -MaxUpdateNumber to limit the number of updates performed in one run.
	#Use -CleanupBackupPath 'D:\ModuleBackups' to zip each old version before it is removed.
	#Use -ReplaceLockedModuleOnReboot to also schedule locked or access-denied old versions for deletion on the next restart.
	$outdated | Update-Modules -Clean -PreRelease -MaxUpdateNumber 5 -CleanupBackupPath 'C:\ModuleBackups' -WhatIf
}
else {
	New-Log "No outdated modules to update" -Level SUCCESS
}
Update-Modules -OnlyCleanUpOldModules -CleanupBackupPath 'C:\ModuleBackups' -WhatIf #Cleanup-only mode: previews the old module versions that would be removed (keeping the highest version per path) without any update check. Remove -WhatIf to clean for real, add -CleanupBackupPath 'C:\ModuleBackups' to zip each version first.