Public/Get-PGDiskPressure.ps1

<#
.SYNOPSIS
Reports utilisation for a local Windows drive.
 
.DESCRIPTION
Returns total, used and free capacity together with the percentage of the drive
currently in use. ProfileGuardian uses this result to gate lifecycle actions.
 
.PARAMETER Drive
The local drive identifier. The default is the Windows system drive.
 
.EXAMPLE
Get-PGDiskPressure -Drive 'C:'
 
.OUTPUTS
ProfileGuardian.DiskPressure
#>

function Get-PGDiskPressure {
    [CmdletBinding()]
    param(
        [string]$Drive
    )

    Assert-PGWindows
    $resolvedDrive = Resolve-PGDrive -Drive $Drive
    $disk = Get-CimInstance -ClassName Win32_LogicalDisk -Filter "DeviceID='$resolvedDrive'" -ErrorAction Stop |
        Select-Object -First 1

    if ($null -eq $disk -or $null -eq $disk.Size -or [double]$disk.Size -le 0) {
        throw "Windows did not return a valid size for drive '$resolvedDrive'."
    }
    if ($null -eq $disk.FreeSpace) {
        throw "Windows did not return free-space data for drive '$resolvedDrive'."
    }

    $size = [double]$disk.Size
    $free = [double]$disk.FreeSpace
    if ($free -lt 0 -or $free -gt $size) {
        throw "Windows returned invalid free-space data for drive '$resolvedDrive'."
    }
    $used = $size - $free

    $result = [pscustomobject]@{
        Drive       = $resolvedDrive
        TotalGB     = [math]::Round($size / 1GB, 2)
        UsedGB      = [math]::Round($used / 1GB, 2)
        FreeGB      = [math]::Round($free / 1GB, 2)
        UsedPercent = [math]::Round(($used / $size) * 100, 2)
    }
    $result.PSObject.TypeNames.Insert(0, 'ProfileGuardian.DiskPressure')
    return $result
}