Add ConvertToHumanReadableSize function and associated tests; update CI/CD workflow and VSCode settings

Author: marko-stanojevic

.github/workflows/powershell-script-module-release.yml

@@ -99,6 +99,7 @@ jobs:
         shell: pwsh
         env:
           PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
+          NUGETORG_API_KEY: ${{ secrets.NUGETORG_API_KEY }}
         run: |
           Set-StrictMode -Version Latest
           [void] (Import-Module InvokeBuild)

.vscode/settings.json

@@ -26,6 +26,8 @@
     "powershell.codeFormatting.preset": "OTBS",
     // Adds a space between a keyword and its associated scriptblock expression.
     "powershell.codeFormatting.whitespaceBeforeOpenBrace": true,
+    // Remove trailing whitespace at the end of lines.
+    "powershell.codeFormatting.trimTrailingWhitespace": true,
     // Adds a space between a keyword (if, elseif, while, switch, etc) and its associated conditional expression.
     "powershell.codeFormatting.whitespaceBeforeOpenParen": true,
     // Adds spaces before and after an operator ('=', '+', '-', etc.).
@@ -47,20 +49,22 @@
         "MD007": {
             "indent": 4
         },
+        // MD013 - Line length
         "MD013": {
             "line_length": 240
         },
+        // MD026 - Trailing punctuation in header
         "MD026": {
             "punctuation": ".,;:!"
         },
-        "MD029": {
-            "style": "one"
-        },
+        // MD029 - Ordered list item prefix
+        "MD029": false,
+        // MD030 - Spaces after list markers
         "MD033": false,
+        // MD034 - Bare URL used
         "MD034": false,
-        "MD038": false,
-        "MD042": false,
-        "MD024": false,
+        //MD045 - Multiple consecutive blank lines
+        "MD045": false,
         "no-hard-tabs": true
     },
     "[jsonc]": {

README.md

@@ -180,8 +180,6 @@ Comprehensive documentation is available in the [`docs/`](docs/) directory:
 - 🛠️ **[Development Guide](docs/development.md)** - Creating functions, building, testing, and generating help
 - 🔄 **[CI/CD & Publishing Guide](docs/ci-cd.md)** - Automated pipelines, versioning, and PowerShell Gallery publishing
 
-
-
 ## 🤝 Contributing
 
 Contributions are welcome! Whether it’s bug fixes, improvements, or ideas for new features, your input helps make this template better for everyone. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on:
@@ -199,7 +197,6 @@ If this template saves you time or helps your projects succeed, consider support
 - 💬 Provide feedback via issues or discussions
 - ❤️ Sponsor ongoing development via GitHub Sponsors
 
-
 ---
 
 Built with ❤️ by [Warehouse Finds](https://github.com/WarehouseFinds)

docs/ci-cd.md

@@ -559,42 +559,6 @@ git push origin v1.0.0
 - Make breaking changes in patch versions
 - Publish untested code to PowerShell Gallery
 
-## Advanced Configuration
-
-### Customizing CI Workflow
-
-Edit `.github/workflows/ci.yml`:
-
-```yaml
-# Change test coverage threshold
-- name: Run Tests
-  run: |
-    Invoke-Build Invoke-UnitTests
-  env:
-    COVERAGE_THRESHOLD: 80  # Change to your requirement
-
-# Add custom quality gates
-- name: Custom Check
-  run: |
-    # Your custom validation
-```
-
-### Custom GitVersion Configuration
-
-Edit `GitVersion.yml`:
-
-```yaml
-# Change version increment behavior
-mode: ContinuousDelivery
-increment: Inherit
-
-# Customize branch configuration
-branches:
-  main:
-    tag: ''
-    increment: Patch
-```
-
 ## Resources
 
 - 📖 [GitHub Actions Documentation](https://docs.github.com/actions)

src/Private/ConvertToHumanReadableSize.Tests.ps1

@@ -0,0 +1,112 @@
+BeforeAll {
+    . $PSCommandPath.Replace('.Tests.ps1', '.ps1')
+}
+
+Describe 'ConvertToHumanReadableSize' {
+    Context 'Parameter Validation' {
+        It 'Should require Bytes parameter' {
+            { ConvertToHumanReadableSize } | Should -Throw
+        }
+
+        It 'Should not accept negative values' {
+            { ConvertToHumanReadableSize -Bytes -1 } | Should -Throw
+        }
+
+        It 'Should accept zero' {
+            { ConvertToHumanReadableSize -Bytes 0 } | Should -Not -Throw
+        }
+
+        It 'Should accept maximum long value' {
+            { ConvertToHumanReadableSize -Bytes ([long]::MaxValue) } | Should -Not -Throw
+        }
+    }
+
+    Context 'Size Conversion' {
+        It 'Should return "0 bytes" for zero input' {
+            $result = ConvertToHumanReadableSize -Bytes 0
+            $result | Should -Be '0 bytes'
+        }
+
+        It 'Should format bytes correctly' {
+            $result = ConvertToHumanReadableSize -Bytes 512
+            $result | Should -Be '512 bytes'
+        }
+
+        It 'Should convert to KB correctly' {
+            $result = ConvertToHumanReadableSize -Bytes 1024
+            $result | Should -Be '1.00 KB'
+        }
+
+        It 'Should convert to MB correctly' {
+            $result = ConvertToHumanReadableSize -Bytes 1048576
+            $result | Should -Be '1.00 MB'
+        }
+
+        It 'Should convert to GB correctly' {
+            $result = ConvertToHumanReadableSize -Bytes 1073741824
+            $result | Should -Be '1.00 GB'
+        }
+
+        It 'Should convert to TB correctly' {
+            $result = ConvertToHumanReadableSize -Bytes 1099511627776
+            $result | Should -Be '1.00 TB'
+        }
+
+        It 'Should format decimal places correctly' {
+            $result = ConvertToHumanReadableSize -Bytes 1536
+            $result | Should -Be '1.50 KB'
+        }
+
+        It 'Should round to two decimal places' {
+            $result = ConvertToHumanReadableSize -Bytes 1555
+            $result | Should -Match '^\d+\.\d{2} KB$'
+        }
+    }
+
+    Context 'Largest Unit Selection' {
+        It 'Should prefer larger units' {
+            $result = ConvertToHumanReadableSize -Bytes (5GB + 500MB)
+            $result | Should -Match 'GB'
+            $result | Should -Not -Match 'MB'
+        }
+
+        It 'Should use bytes for values less than 1KB' {
+            $result = ConvertToHumanReadableSize -Bytes 1023
+            $result | Should -Be '1023 bytes'
+        }
+    }
+
+    Context 'Edge Cases' {
+        It 'Should handle 1 byte' {
+            $result = ConvertToHumanReadableSize -Bytes 1
+            $result | Should -Be '1 bytes'
+        }
+
+        It 'Should handle exactly 1KB boundary' {
+            $result = ConvertToHumanReadableSize -Bytes 1024
+            $result | Should -Be '1.00 KB'
+        }
+
+        It 'Should handle exactly 1MB boundary' {
+            $result = ConvertToHumanReadableSize -Bytes (1024 * 1024)
+            $result | Should -Be '1.00 MB'
+        }
+
+        It 'Should handle large TB values' {
+            $result = ConvertToHumanReadableSize -Bytes (10 * 1TB)
+            $result | Should -Be '10.00 TB'
+        }
+    }
+
+    Context 'Return Type' {
+        It 'Should return string type' {
+            $result = ConvertToHumanReadableSize -Bytes 1024
+            $result | Should -BeOfType [string]
+        }
+
+        It 'Should not return null' {
+            $result = ConvertToHumanReadableSize -Bytes 0
+            $result | Should -Not -BeNullOrEmpty
+        }
+    }
+}

src/Private/ConvertToHumanReadableSize.ps1

@@ -0,0 +1,62 @@
+function ConvertToHumanReadableSize {
+    <#
+    .SYNOPSIS
+        Converts byte size to human-readable format
+    
+    .DESCRIPTION
+        Internal helper function that converts file sizes in bytes to
+        human-readable format (KB, MB, GB, TB).
+    
+    .PARAMETER Bytes
+        The size in bytes to convert
+    
+    .EXAMPLE
+        ConvertToHumanReadableSize -Bytes 1024
+        Returns: "1.00 KB"
+    
+    .EXAMPLE
+        ConvertToHumanReadableSize -Bytes 1048576
+        Returns: "1.00 MB"
+    
+    .OUTPUTS
+        System.String
+    
+    .NOTES
+        Private function - not exported from module
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param (
+        [Parameter(Mandatory)]
+        [ValidateRange(0, [long]::MaxValue)]
+        [long]
+        $Bytes
+    )
+    
+    # Fail fast: Handle zero bytes
+    if ($Bytes -eq 0) {
+        return "0 bytes"
+    }
+    
+    # Fail fast: Validate non-negative
+    if ($Bytes -lt 0) {
+        throw "Bytes parameter must be non-negative. Received: $Bytes"
+    }
+    
+    $sizes = @(
+        @{ Name = 'TB'; Value = 1TB }
+        @{ Name = 'GB'; Value = 1GB }
+        @{ Name = 'MB'; Value = 1MB }
+        @{ Name = 'KB'; Value = 1KB }
+    )
+    
+    foreach ($size in $sizes) {
+        if ($Bytes -ge $size.Value) {
+            $value = $Bytes / $size.Value
+            return "{0:N2} {1}" -f $value, $size.Name
+        }
+    }
+    
+    # Less than 1 KB
+    return "$Bytes bytes"
+}