🚀 [Breaking pre-release]: Refactor GitHubPermission and improve initialization and comparison logic (#524)

## Description

This pull request refactors how GitHub permissions are represented and
handled throughout the codebase, consolidating the
`GitHubPermissionDefinition` and `GitHubPermission` classes and updating
related logic for consistency and correctness. The changes also improve
the handling of permissions and events in context and installation
classes, as well as streamline status calculation for installations.

### Refactoring and Consolidation of Permissions

* Merged `GitHubPermissionDefinition` into a single `GitHubPermission`
class, adding constructors and properties to better represent both
definitions and assigned values. All static permission lists and related
logic now use `GitHubPermission` instead of the previous definition
class.
* Updated all permission list instantiations to use the new
`GitHubPermission` class, ensuring consistent construction and type
usage.

### Improvements to Installation and Context Classes

* Updated constructors in `GitHubAppInstallation.ps1` to use a simpler
parameter set, replaced `$Context.HostName` with direct `$HostName`
usage, and removed a redundant constructor. Also changed the status
update method name from `UpdateStatus` to `SetStatus` and adjusted its
usage.
* Improved event and permission handling in `GitHubAppContext.ps1` and
`GitHubAppInstallationContext.ps1` by ensuring events are always stored
as arrays and permissions are only set when present.
* Ensured `FilePaths` and `Events` properties are always arrays to
prevent type inconsistencies.

### Streamlining Installation Status Calculation

* Refactored the logic for comparing permissions in `SetStatus`,
replacing manual dictionary comparison with a simpler `Compare-Object`
approach for determining if permissions match between app and
installation.
* Added a check to ensure that installation permissions exist before
attempting status calculation, improving robustness.

## 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

Author: MariusStorhaug

src/classes/public/App/GitHubAppInstallation.ps1

@@ -59,7 +59,7 @@
         $this.RepositorySelection = $Object.repository_selection
         $this.Permissions = [GitHubPermission]::NewPermissionList($Object.permissions, $this.Type)
         $this.Events = , ($Object.events)
-        $this.FilePaths = $Object.single_file_paths
+        $this.FilePaths = , ($Object.single_file_paths)
         $this.CreatedAt = $Object.created_at
         $this.UpdatedAt = $Object.updated_at
         $this.SuspendedAt = $Object.suspended_at
@@ -76,16 +76,16 @@
         $this.RepositorySelection = $Object.repository_selection
         $this.Permissions = [GitHubPermission]::NewPermissionList($Object.permissions, $this.Type)
         $this.Events = , ($Object.events)
-        $this.FilePaths = $Object.single_file_paths
+        $this.FilePaths = , ($Object.single_file_paths)
         $this.CreatedAt = $Object.created_at
         $this.UpdatedAt = $Object.updated_at
         $this.SuspendedAt = $Object.suspended_at
         $this.SuspendedBy = [GitHubUser]::new($Object.suspended_by)
         $this.Url = $Object.html_url
-        $this.UpdateStatus()
+        $this.SetStatus()
     }
 
-    GitHubAppInstallation([PSCustomObject] $Object, [string] $Target, [string] $Type, [GitHubContext] $Context) {
+    GitHubAppInstallation([PSCustomObject] $Object, [string] $Target, [string] $Type, [string] $HostName) {
         $this.ID = $Object.id
         $this.App = [GitHubApp]::new(
             [PSCustomObject]@{
@@ -96,7 +96,7 @@
         $this.Target = [GitHubOwner]@{
             Name = $Target
             Type = $Type
-            Url  = "https://$($Context.HostName)/$Target"
+            Url  = "https://$HostName/$Target"
         }
         $this.Type = $Type
         $this.RepositorySelection = $Object.repository_selection
@@ -107,38 +107,21 @@
         $this.UpdatedAt = $Object.updated_at
         $this.SuspendedAt = $Object.suspended_at
         $this.SuspendedBy = [GitHubUser]::new($Object.suspended_by)
-        $this.Url = "https://$($Context.HostName)/$($Type.ToLower())s/$Target/settings/installations/$($Object.id)"
+        $this.Url = "https://$HostName/$($Type.ToLower())s/$Target/settings/installations/$($Object.id)"
         $this.Status = 'Unknown'
     }
 
-    GitHubAppInstallation([PSCustomObject] $Object, [string] $Target, [string] $Type, [GitHubContext] $Context, [GitHubApp] $App) {
-        $this.ID = $Object.id
-        $this.App = $App
-        $this.Target = [GitHubOwner]@{
-            Name = $Target
-            Type = $Type
-            Url  = "https://$($Context.HostName)/$Target"
-        }
-        $this.Type = $Type
-        $this.RepositorySelection = $Object.repository_selection
-        $this.Permissions = [GitHubPermission]::NewPermissionList($Object.permissions, $this.Type)
-        $this.Events = , ($Object.events)
-        $this.FilePaths = $Object.single_file_paths
-        $this.CreatedAt = $Object.created_at
-        $this.UpdatedAt = $Object.updated_at
-        $this.SuspendedAt = $Object.suspended_at
-        $this.SuspendedBy = [GitHubUser]::new($Object.suspended_by)
-        $this.Url = "https://$($Context.HostName)/$($Type.ToLower())s/$Target/settings/installations/$($Object.id)"
-        $this.UpdateStatus()
-    }
-
     # Updates the Status property by comparing installation permissions with app permissions
     # filtered by the appropriate scope based on installation type
-    [void] UpdateStatus() {
+    [void] SetStatus() {
         if (-not $this.App -or -not $this.App.Permissions) {
             $this.Status = 'Unknown'
             return
         }
+        if (-not $this.Permissions) {
+            $this.Status = 'Unknown'
+            return
+        }
 
         # Get app permissions filtered by installation type scope
         $appPermissionsFiltered = switch ($this.Type) {
@@ -156,38 +139,7 @@
             }
         }
 
-        # Compare permissions by creating lookup dictionaries
-        $appPermissionLookup = @{}
-        foreach ($perm in $appPermissionsFiltered) {
-            $appPermissionLookup[$perm.Name] = $perm.Value
-        }
-
-        $installationPermissionLookup = @{}
-        foreach ($perm in $this.Permissions) {
-            $installationPermissionLookup[$perm.Name] = $perm.Value
-        }
-
-        # Check if permissions match
-        $permissionsMatch = $true
-
-        # Check if all app permissions exist in installation with same values
-        foreach ($name in $appPermissionLookup.Keys) {
-            if (-not $installationPermissionLookup.ContainsKey($name) -or
-                $installationPermissionLookup[$name] -ne $appPermissionLookup[$name]) {
-                $permissionsMatch = $false
-                break
-            }
-        }
-
-        # Check if installation has any extra permissions not in the app
-        if ($permissionsMatch) {
-            foreach ($name in $installationPermissionLookup.Keys) {
-                if (-not $appPermissionLookup.ContainsKey($name)) {
-                    $permissionsMatch = $false
-                    break
-                }
-            }
-        }
+        $permissionsMatch = Compare-Object -ReferenceObject $appPermissionsFiltered -DifferenceObject $this.Permissions | Measure-Object
 
         $this.Status = $permissionsMatch ? 'Ok' : 'Outdated'
     }

src/classes/public/Context/GitHubContext/GitHubAppContext.ps1

@@ -47,7 +47,9 @@
         $this.KeyVaultKeyReference = $Object.KeyVaultKeyReference
         $this.OwnerName = $Object.OwnerName
         $this.OwnerType = $Object.OwnerType
-        $this.Permissions = [GitHubPermission]::NewPermissionList($Object.Permissions)
-        $this.Events = $Object.Events
+        if ($Object.Permissions) {
+            $this.Permissions = [GitHubPermission]::NewPermissionList($Object.Permissions)
+        }
+        $this.Events = , ($Object.Events)
     }
 }

src/classes/public/Context/GitHubContext/GitHubAppInstallationContext.ps1

@@ -42,7 +42,7 @@
         $this.ClientID = $Object.ClientID
         $this.InstallationID = $Object.InstallationID
         $this.Permissions = [GitHubPermission]::NewPermissionList($Object.Permissions, $Object.InstallationType)
-        $this.Events = $Object.Events
+        $this.Events = , ($Object.Events)
         $this.InstallationType = $Object.InstallationType
         $this.InstallationName = $Object.InstallationName
     }