From 560988eed47fa0b8471e95431b545a038a9ea608 Mon Sep 17 00:00:00 2001
From: Jesse Squire <jsquire@microsoft.com>
Date: Thu, 27 Jun 2024 13:31:29 -0400
Subject: [PATCH] [Validate-AzsdkCodeOwners] UX enhancements (#8506)

The focus of these changes is to improve the usability and user experience of the validation script.

The previous output was basic and lacked details outside of verbose mode - which included raw HTTP response payloads.   These changes include more context and clear color/symbol indications of what information is missing.
---
 .../scripts/Validate-AzsdkCodeOwner.ps1       | 92 +++++++++++++------
 1 file changed, 62 insertions(+), 30 deletions(-)

diff --git a/tools/github/scripts/Validate-AzsdkCodeOwner.ps1 b/tools/github/scripts/Validate-AzsdkCodeOwner.ps1
index 034b7692647..3c37ef160ee 100644
--- a/tools/github/scripts/Validate-AzsdkCodeOwner.ps1
+++ b/tools/github/scripts/Validate-AzsdkCodeOwner.ps1
@@ -13,63 +13,95 @@ $hasPermissions = $false
 
 # Verify that the user exists and has the correct public
 # organization memberships.
-$response = (gh api "https://api.github.com/users/$UserName/orgs")
-$json = $response | ConvertFrom-Json
+$orgResponse = (gh api "https://api.github.com/users/$UserName/orgs")
+$orgs = $orgResponse | ConvertFrom-Json
 
-Write-Verbose "Orginizations API Response:"
-Write-Verbose "`t$response"
+if ($orgs -ne $null) {
+    $orgs = $orgs | select -Expand login
+} else {
+    $orgs = @()
+}
 
-# If there were no organizations, the user fails validation.
-if ($json -ne $null) {
+# Validate that the user has the required public organization memberships.
+$requiredOrgs = [System.Collections.Generic.HashSet[String]]::new([StringComparer]::InvariantCultureIgnoreCase)
+$requiredOrgs.Add("Microsoft") | Out-Null
+$requiredOrgs.Add("Azure") | Out-Null
 
-    # If the user is not a member of Microsoft or Azure, the user fails validation.
-    $orgs = [System.Collections.Generic.HashSet[String]]::new([StringComparer]::InvariantCultureIgnoreCase)
+# Capture non-required organizations for verbose output.
+$otherOrgs = $orgs | where { -not $requiredOrgs.Contains($_) }
+
+Write-Host ""
+Write-Host "Required Orginizations:" -ForegroundColor DarkGray
 
-    foreach ($org in $json) {
-        $orgs.Add("$($org.login)") | Out-Null
+foreach ($org in $orgs) {
+    if ($requiredOrgs.Contains($org)) {
+        Write-Host "`t$([char]0x2713) $($org) " -ForegroundColor Green
+        $requiredOrgs.Remove($org) | Out-Null
     }
+}
 
-    Write-Verbose ""
-    Write-Verbose "Orginizations:"
+# Any required organizations left are not present for the user.
+foreach ($org in $requiredOrgs) {
+    Write-Host "`tx $($org)" -ForegroundColor Red
+}
 
-    foreach ($org in $orgs) {
-        Write-Verbose "`t$($org)"
-    }
+# Write the other public organizations for the user, if
+# verbose output is enabled.
+if ($otherOrgs.Length -gt 0) {
+    Write-Verbose ""
+    Write-Verbose "Other Orginizations:"
 
-    if ($orgs.Contains("Microsoft") -and $orgs.Contains("Azure")) {
-        $hasOrgs = $true
+    foreach ($org in $otherOrgs) {
+        Write-Verbose "`t$($org) (not required)"
     }
 }
 
+$hasOrgs = ($requiredOrgs.Count -eq 0)
+
 # Verify that the user exists and has the correct permissions
 # to the repository.  Delegage to the GH CLI here, as this is a
 # priviledged operation that requires an authenticated caller.
-$response = (gh api "https://api.github.com/repos/Azure/azure-sdk-for-net/collaborators/$UserName/permission")
-
-Write-Verbose ""
-Write-Verbose "Permissions API Response:"
-Write-Verbose "`t$response"
+$permResponse = (gh api "https://api.github.com/repos/Azure/azure-sdk-for-net/collaborators/$UserName/permission")
+$permission = ($permResponse | ConvertFrom-Json).permission
 
-$permission = ($response | ConvertFrom-Json).permission
+Write-Host ""
+Write-Host "Required Permissions:" -ForegroundColor DarkGray
 
 if ($permission -eq "admin" -or $permission -eq "write") {
+    Write-Host "`t$([char]0x2713) $($permission) " -ForegroundColor Green
     $hasPermissions = $true
+} else {
+    Write-Host "`tx $($permission)" -ForegroundColor Red
 }
 
 # Validate the user and write the results.
 $isValid = ($hasOrgs -and $hasPermissions)
 
 Write-Host ""
-Write-Host "Has organization memberships: " -NoNewline
-Write-host $hasOrgs -ForegroundColor "$(if ($hasOrgs) { "Green" } else { "Red" })"
-Write-Host "Has permissions: " -NoNewline
-Write-Host $hasPermissions -ForegroundColor "$(if ($hasPermissions) { "Green" } else { "Red" })"
 Write-Host ""
-Write-Host "Is valid: " -NoNewline
-Write-Host $isValid -ForegroundColor "$(if ($isValid) { "Green" } else { "Red" })"
+Write-Host "Validation result for '$UserName':" -ForegroundColor White
+
+if ($isValid) {
+    Write-Host "`t$([char]0x2713) Valid code owner" -ForegroundColor Green
+} else {
+    Write-Host "`tx Not a valid code owner" -ForegroundColor Red
+}
+
 Write-Host ""
 Write-Host ""
 
+# If verbose output is requested, write the raw API responses.
+Write-Verbose "Orginizations API Response:"
+Write-Verbose "`t$orgResponse"
+
+Write-Verbose ""
+Write-Verbose ""
+Write-Verbose "Permissions API Response:"
+Write-Verbose "`t$permResponse"
+
+Write-Verbose ""
+Write-Verbose ""
+
 <#
 .SYNOPSIS
 Tests a GitHub account for the permissions and public organization memberships required of a code owner in the Azure SDK repositories.
@@ -90,4 +122,4 @@ Tests GitHub user "jsquire" to validate requirements are met for a code owner in
 .EXAMPLE
 Validate-AzsdkCodeOwner.ps1 jsquire -Verbose
 Tests GitHub user "jsquire" to validate requirements are met for a code owner in the Azure SDK repositories, showing the raw output from GitHub API calls.
-#>
\ No newline at end of file
+#>