🚀 [Feature]: Add a Compare-PSCustomObject function (#3)

## Description

This pull request introduces a major overhaul to the `PSCustomObject`
module, focusing on adding new functionality for comparing PowerShell
custom objects, removing outdated features, and updating documentation
and examples accordingly. The most important changes are grouped below
by theme.

### New Functionality

* Added a new function `Compare-PSCustomObject` to compare two
PowerShell custom objects and return a detailed overview of their
differences. This includes an option to filter only the changed
properties.
* Introduced a new test suite in `tests/PSCustomObject.Tests.ps1` to
validate the functionality of `Compare-PSCustomObject`.

### Documentation Updates

* Updated `README.md` to reflect the new module focus on
`PSCustomObject`, replacing placeholder content with meaningful
descriptions, installation instructions, and an example usage of
`Compare-PSCustomObject`.
[[1]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L1-R3)
[[2]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L15-L37)
* Removed outdated sections in `README.md` such as "Acknowledgements"
and placeholder documentation links.
[[1]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L47-L51)
[[2]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L66-L69)

### Example Updates

* Replaced the old `General.ps1` example with a new example
demonstrating the usage of `Compare-PSCustomObject`.

### Removed Legacy Features

* Removed the `Get-PSModuleTest` function, which was no longer relevant
to the updated module purpose.
* Deleted the corresponding test suite for `Get-PSModuleTest` in
`tests/PSModuleTest.Tests.ps1`.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [x] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: MariusStorhaug

README.md

@@ -1,6 +1,6 @@
-# {{ NAME }}
+# PSCustomObject
 
-{{ DESCRIPTION }}
+This module provides a set of functions for working with PowerShell custom objects (PSCustomObject).
 
 ## Prerequisites
 
@@ -12,29 +12,61 @@ This uses the following external resources:
 To install the module from the PowerShell Gallery, you can use the following command:
 
 ```powershell
-Install-PSResource -Name {{ NAME }}
-Import-Module -Name {{ NAME }}
+Install-PSResource -Name PSCustomObject
+Import-Module -Name PSCustomObject
 ```
 
 ## Usage
 
 Here is a list of example that are typical use cases for the module.
 
-### Example 1: Greet an entity
+### Example 1: Compare two objects
 
-Provide examples for typical commands that a user would like to do with the module.
+This example shows how to compare two objects and get the differences between them.
 
 ```powershell
-Greet-Entity -Name 'World'
-Hello, World!
+$object1 = [PSCustomObject]@{
+    Name  = 'Test'
+    Value = 1
+}
+
+$object2 = [PSCustomObject]@{
+    Name  = 'Test'
+    Value = 2
+}
+
+$object1 | Compare-PSCustomObject $object2
+
+# Output:
+# Property Left Right Changed
+# -------- ---- ----- -------
+# Name     Test Test    False
+# Value    1    2        True
+
 ```
 
-### Example 2
+### Example 2: Compare two objects showing only changed properties
 
-Provide examples for typical commands that a user would like to do with the module.
+This example shows how to compare two objects and get the differences between them.
 
 ```powershell
-Import-Module -Name PSModuleTemplate
+$object1 = [PSCustomObject]@{
+    Name  = 'Test'
+    Value = 1
+}
+
+$object2 = [PSCustomObject]@{
+    Name  = 'Test'
+    Value = 2
+}
+
+$object1 | Compare-PSCustomObject $object2 -OnlyChanged
+
+# Output:
+# Property Left Right Changed
+# -------- ---- ----- -------
+# Value    1    2        True
+
 ```
 
 ### Find more examples
@@ -44,11 +76,6 @@ To find more examples of how to use the module, please refer to the [examples](e
 Alternatively, you can use the Get-Command -Module 'This module' to find more commands that are available in the module.
 To find examples of each of the commands you can use Get-Help -Examples 'CommandName'.
 
-## Documentation
-
-Link to further documentation if available, or describe where in the repository users can find more detailed documentation about
-the module's functions and features.
-
 ## Contributing
 
 Coder or not, you can contribute to the project! We welcome all contributions.
@@ -63,7 +90,3 @@ Please see the issues tab on this project and submit a new issue that matches yo
 
 If you do code, we'd love to have your contributions. Please read the [Contribution guidelines](CONTRIBUTING.md) for more information.
 You can either help by picking up an existing issue or submit a new one if you have an idea for a new feature or improvement.
-
-## Acknowledgements
-
-Here is a list of people and projects that helped this project in some way.

examples/General.ps1

@@ -1,19 +1,17 @@
-<#
-  .SYNOPSIS
-    This is a general example of how to use the module.
-#>
+$object1 = [PSCustomObject]@{
+    Name  = 'Test'
+    Value = 1
+}
 
-# Import the module
-Import-Module -Name 'PSModule'
+$object2 = [PSCustomObject]@{
+    Name  = 'Test'
+    Value = 2
+}
 
-# Define the path to the font file
-$FontFilePath = 'C:\Fonts\CodeNewRoman\CodeNewRomanNerdFontPropo-Regular.tff'
+$object1 | Compare-PSCustomObject $object2
 
-# Install the font
-Install-Font -Path $FontFilePath -Verbose
-
-# List installed fonts
-Get-Font -Name 'CodeNewRomanNerdFontPropo-Regular'
-
-# Uninstall the font
-Get-Font -Name 'CodeNewRomanNerdFontPropo-Regular' | Uninstall-Font -Verbose
+# Output:
+# Property Left Right Changed
+# -------- ---- ----- -------
+# Name     Test Test    False
+# Value    1    2        True

src/functions/public/Compare-PSCustomObject.ps1

@@ -0,0 +1,66 @@
+filter Compare-PSCustomObject {
+    <#
+        .SYNOPSIS
+        Compare two PSCustomObjects and return the comparison.
+
+        .DESCRIPTION
+        This function compares two PSCustomObjects and returns an overview of the differences.
+        It can also filter to show only the properties that have changed.
+
+        .EXAMPLE
+        Compare-PSCustomObject -Left $object1 -Right $object2 -OnlyChanged
+
+        .EXAMPLE
+        $object1 = [PSCustomObject]@{
+            Name  = 'Test'
+            Value = 1
+        }
+        $object2 = [PSCustomObject]@{
+            Name  = 'Test'
+            Value = 2
+        }
+        $object1 | Compare-PSCustomObject $object2
+
+        Output:
+        ```powershell
+        Property Left Right Changed
+        -------- ---- ----- -------
+        Name     Test Test    False
+        Value    1    2        True
+        ```
+
+        .LINK
+        https://psmodule.io/PSCustomObject/Functions/Compare-PSCustomObject
+    #>
+    [Alias('Compare-PSObject')]
+    [CmdletBinding()]
+    param (
+        # The left object to compare
+        [Parameter(Mandatory, ValueFromPipeline)]
+        [object] $Left,
+
+        # The right object to compare
+        [Parameter(Mandatory, Position = 0)]
+        [object] $Right,
+
+        # Only show properties that have changed
+        [Parameter()]
+        [switch] $OnlyChanged
+    )
+
+    $diff = foreach ($propertyName in $Left.psobject.Properties.Name) {
+        $leftValue = $Left.$propertyName
+        $rightValue = $Right.$propertyName
+        [PSCustomObject]@{
+            Property = $propertyName
+            Left     = "$leftValue"
+            Right    = "$rightValue"
+            Changed  = "$leftValue" -ne "$rightValue"
+        }
+    }
+
+    if ($OnlyChanged) {
+        return $diff | Where-Object { $_.Changed }
+    }
+    $diff
+}

src/functions/public/Get-PSModuleTest.ps1

@@ -0,0 +1,68 @@
+#Requires -Modules @{ ModuleName = 'Pester'; RequiredVersion = '5.7.1' }
+
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSUseDeclaredVarsMoreThanAssignments', '',
+    Justification = 'Pester grouping syntax: known issue.'
+)]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSAvoidUsingConvertToSecureStringWithPlainText', '',
+    Justification = 'Used to create a secure string for testing.'
+)]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSAvoidUsingWriteHost', '',
+    Justification = 'Log outputs to GitHub Actions logs.'
+)]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSAvoidLongLines', '',
+    Justification = 'Long test descriptions and skip switches'
+)]
+[CmdletBinding()]
+param()
+
+Describe 'PSCustomObject' {
+    It 'Function: Compare-PSCustomObject' {
+        $Left = [PSCustomObject]@{
+            Name  = 'Test'
+            Value = 1
+        }
+
+        $Right = [PSCustomObject]@{
+            Name  = 'Test'
+            Value = 2
+        }
+
+        LogGroup 'Diff' {
+            $diff = $Left | Compare-PSCustomObject $Right
+            Write-Host "$($diff | Format-Table | Out-String)"
+        }
+
+        $diff | Should -HaveCount 2
+        $diff.Property | Should -BeIn @('Name', 'Value')
+        $diff.Left | Should -BeIn @('Test', 1)
+        $diff.Right | Should -BeIn @('Test', 2)
+        $diff.Changed | Should -Contain $true
+    }
+
+    It 'Function: Compare-PSCustomObject -OnlyChanged' {
+        $Left = [PSCustomObject]@{
+            Name  = 'Test'
+            Value = 1
+        }
+
+        $Right = [PSCustomObject]@{
+            Name  = 'Test'
+            Value = 2
+        }
+
+        LogGroup 'Diff' {
+            $diff = $Left | Compare-PSCustomObject $Right -OnlyChanged
+            Write-Host "$($diff | Format-Table | Out-String)"
+        }
+
+        $diff | Should -HaveCount 1
+        $diff.Property | Should -Be 'Value'
+        $diff.Left | Should -Be 1
+        $diff.Right | Should -Be 2
+        $diff.Changed | Should -Be $true
+    }
+}