🩹 [Patch]: Align function parameters and logging (#207)

## Description - Fixes 🩹 [Patch]: Cleanup debug/verbose logging #187 - Fixes Align default parameter handling #78 This pull request introduces several new features and improvements, including new PowerShell filters for GitHub workflow runs, updates to the coverage report, and enhancements to existing scripts. The most important changes are summarized below: ### Main change: - Update all functions to use a function for showing the execution path to the function in begin and end blocks of the functions. The exec path starts at the first non '<ScriptBlock>' and non-powershell script so it doesn't drown out the logs with useless info. Main goal of this change is to clearly see where we are in the function execution. These only show if `-Debug` is provided. - Aligned all functions to use a $body hashtable for inputs to the API call, instead of having some strange function with automated case style management. Plain and simple, use a @Body hashtable, an $inputObject variable for the calls to the API and the API call itself. Easy as that. Likely more alignment to come via classes to drive consistency at a later point. - All functions should now have a begin process and end block. Debug functions are omitted from this requirement. ### Function changes: - Splitting `Get-GitHubWorkflowRun` into two new private functions and referencing them in the public function. - `Get-GitHubWorkflowRunByRepo` - `Get-GitHubWorkflowRunByWorkflow` ### Workflow Enhancements: * Added `Initialize-PSModule` step to the `Set-CoverageReport.yml` workflow, to install MarkdownPS automatically before the script is run. ### Codebase Enhancements: * Updated `Get-GitHubAppByName`, `Get-GitHubAuthenticatedApp`, `Assert-GitHubContext`, `Remove-GitHubContext`, `Resolve-GitHubContext`, and `Set-GitHubContext` scripts to use `Write-Debug` instead of `Write-Verbose` for improved debugging. ## Type of change  - [ ] 📖 [Docs] - [ ] 🪲 [Fix] - [x] 🩹 [Patch] - [ ] ⚠️ [Security fix] - [ ] 🚀 [Feature] - [ ] 🌟 [Breaking change] ## Checklist  - [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: github-actions <[email protected]>
PSModule · Dec 16, 2024 · 0a503f8 · 0a503f8
1 parent 77ac2d7
commit 0a503f8
Show file tree

Hide file tree

Showing 230 changed files with 6,704 additions and 3,415 deletions.
diff --git a/.github/workflows/Set-CoverageReport.yml b/.github/workflows/Set-CoverageReport.yml
@@ -16,6 +16,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      - name: Initialize-PSModule
+        uses: PSModule/Initialize-PSModule@v1
+
       - name: Update coverage report
         uses: PSModule/GitHub-Script@v1
         with:

diff --git a/Coverage.md b/Coverage.md
@@ -9,15 +9,15 @@
     </tr>
     <tr>
         <td>Covered functions</td>
-        <td>155</td>
+        <td>156</td>
     </tr>
     <tr>
         <td>Missing functions</td>
-        <td>825</td>
+        <td>824</td>
     </tr>
     <tr>
         <td>Coverage</td>
-        <td>15.82%</td>
+        <td>15.92%</td>
     </tr>
 </table>
 
@@ -54,7 +54,7 @@
 | `/emojis`                                                                                                                 |                    | :white_check_mark: |                    |                    |                    |
 | `/enterprises/{enterprise}/dependabot/alerts`                                                                             |                    | :x:                |                    |                    |                    |
 | `/enterprises/{enterprise}/secret-scanning/alerts`                                                                        |                    | :x:                |                    |                    |                    |
-| `/events`                                                                                                                 |                    | :x:                |                    |                    |                    |
+| `/events`                                                                                                                 |                    | :white_check_mark: |                    |                    |                    |
 | `/feeds`                                                                                                                  |                    | :x:                |                    |                    |                    |
 | `/gists`                                                                                                                  |                    | :x:                |                    | :x:                |                    |
 | `/gists/public`                                                                                                           |                    | :x:                |                    |                    |                    |

diff --git a/src/functions/private/Actions/Get-GitHubWorkflowRunByRepo.ps1 b/src/functions/private/Actions/Get-GitHubWorkflowRunByRepo.ps1
@@ -0,0 +1,138 @@
+filter Get-GitHubWorkflowRunByRepo {
+    <#
+        .SYNOPSIS
+        List workflow runs for a repository
+
+        .DESCRIPTION
+        Lists all workflow runs for a repository. You can use parameters to narrow the list of results. For more information about using parameters,
+        see [Parameters](https://docs.github.com/rest/guides/getting-started-with-the-rest-api#parameters).
+        Anyone with read access to the repository can use this endpoint.
+        OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.
+        This endpoint will return up to 1,000 results for each search when using the following parameters: `actor`, `branch`, `check_suite_id`,
+        `created`, `event`, `head_sha`, `status`.
+
+        .EXAMPLE
+        Get-GitHubWorkflowRunByRepo -Owner 'owner' -Repo 'repo'
+
+        Lists all workflow runs for a repository.
+
+        .EXAMPLE
+        Get-GitHubWorkflowRunByRepo -Owner 'owner' -Repo 'repo' -Actor 'octocat' -Branch 'main' -Event 'push' -Status 'success'
+
+        Lists all workflow runs for a repository with the specified actor, branch, event, and status.
+
+        .NOTES
+        [List workflow runs for a repository](https://docs.github.com/rest/actions/workflow-runs?apiVersion=2022-11-28#list-workflow-runs-for-a-repository)
+    #>
+    [CmdletBinding(DefaultParameterSetName = 'Repo')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidLongLines', '', Justification = 'Contains a long link.')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidAssignmentToAutomaticVariable', 'Event',
+        Justification = 'A parameter that is used in the api call.')]
+    param(
+        # The account owner of the repository. The name is not case sensitive.
+        [Parameter(Mandatory)]
+        [string] $Owner,
+
+        # The name of the repository. The name is not case sensitive.
+        [Parameter(Mandatory)]
+        [string] $Repo,
+
+        # Returns someone's workflow runs. Use the login for the user who created the push associated with the check suite or workflow run.
+        [Parameter()]
+        [string] $Actor,
+
+        # Returns workflow runs associated with a branch. Use the name of the branch of the `push`.
+        [Parameter()]
+        [string] $Branch,
+
+        # Returns workflow run triggered by the event you specify. For example, `push`, `pull_request` or `issue`. For more information, see
+        # "[Events that trigger workflows])(https://docs.github.com/actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows)."
+        [Parameter()]
+        [string] $Event,
+
+        # Returns workflow runs with the check run status or conclusion that you specify. For example, a conclusion can be success or a status can be
+        # `in_progress`. Only GitHub Actions can set a status of `waiting`, `pending`, or `requested`.
+        # Can be one of: `completed`, `action_required`, `cancelled`, `failure`, `neutral`, `skipped`, `stale`, `success`, `timed_out`, `in_progress`,
+        # `queued`, `requested`, `waiting`, `pending`.
+        [Parameter()]
+        [ValidateSet('completed', 'action_required', 'cancelled', 'failure', 'neutral', 'skipped', 'stale', 'success', 'timed_out', 'in_progress',
+            'queued', 'requested', 'waiting', 'pending')]
+        [string] $Status,
+
+        # Returns workflow runs created within the given date-time range. For more information on the syntax, see
+        # "[Understanding the search syntax](https://docs.github.com/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates)."
+        [Parameter()]
+        [datetime] $Created,
+
+        # If `true` pull requests are omitted from the response (empty array).
+        [Parameter()]
+        [switch] $ExcludePullRequests,
+
+        # Returns workflow runs with the check_suite_id that you specify.
+        [Parameter()]
+        [int] $CheckSuiteID,
+
+        # Only returns workflow runs that are associated with the specified head_sha.
+        [Parameter()]
+        [string] $HeadSHA,
+
+        # The number of results per page (max 100).
+        [Parameter()]
+        [ValidateRange(0, 100)]
+        [int] $PerPage,
+
+        # The context to run the command in. Used to get the details for the API call.
+        # Can be either a string or a GitHubContext object.
+        [Parameter()]
+        [object] $Context = (Get-GitHubContext)
+    )
+
+    begin {
+        $stackPath = Get-PSCallStackPath
+        Write-Debug "[$stackPath] - Start"
+        $Context = Resolve-GitHubContext -Context $Context
+        Assert-GitHubContext -Context $Context -AuthType IAT, PAT, UAT
+        if ([string]::IsNullOrEmpty($Owner)) {
+            $Owner = $Context.Owner
+        }
+        Write-Debug "Owner: [$Owner]"
+
+        if ([string]::IsNullOrEmpty($Repo)) {
+            $Repo = $Context.Repo
+        }
+        Write-Debug "Repo: [$Repo]"
+    }
+
+    process {
+        try {
+            $body = @{
+                actor                 = $Actor
+                branch                = $Branch
+                event                 = $Event
+                status                = $Status
+                created               = $Created
+                exclude_pull_requests = $ExcludePullRequests
+                check_suite_id        = $CheckSuiteID
+                head_sha              = $HeadSHA
+                per_page              = $PerPage
+            }
+
+            $inputObject = @{
+                Context     = $Context
+                APIEndpoint = "/repos/$Owner/$Repo/actions/runs"
+                Method      = 'GET'
+                Body        = $body
+            }
+
+            Invoke-GitHubAPI @inputObject | ForEach-Object {
+                Write-Output $_.Response.workflow_runs
+            }
+        } catch {
+            throw $_
+        }
+    }
+
+    end {
+        Write-Debug "[$stackPath] - End"
+    }
+}
diff --git a/src/functions/private/Actions/Get-GitHubWorkflowRunByWorkflow.ps1 b/src/functions/private/Actions/Get-GitHubWorkflowRunByWorkflow.ps1
@@ -0,0 +1,145 @@
+filter Get-GitHubWorkflowRunByWorkflow {
+    <#
+        .SYNOPSIS
+        List workflow runs for a workflow
+
+        .DESCRIPTION
+        List all workflow runs for a workflow. You can replace `workflow_id` with the workflow filename. For example, you could use `main.yaml`.
+        You can use parameters to narrow the list of results. For more information about using parameters, see
+        [Parameters](https://docs.github.com/rest/guides/getting-started-with-the-rest-api#parameters).
+        Anyone with read access to the repository can use this endpoint
+        OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.
+        This endpoint will return up to 1,000 results for each search when using the following parameters: `actor`, `branch`, `check_suite_id`,
+        `created`, `event`, `head_sha`, `status`.
+
+        .EXAMPLE
+        Get-GitHubWorkflowRunByWorkflow -Owner 'octocat' -Repo 'Hello-World' -ID '42'
+
+        Gets all workflow runs for the workflow with the ID `42` in the repository `Hello-World` owned by `octocat`.
+
+        .EXAMPLE
+        Get-GitHubWorkflowRunByWorkflow -Owner 'octocat' -Repo 'Hello-World' -ID '42' -Actor 'octocat' -Branch 'main' -Event 'push' -Status 'success'
+
+        Gets all workflow runs for the workflow with the ID `42` in the repository `Hello-World` owned by `octocat` that were triggered by the user
+        `octocat` on the branch `main` and have the status `success`.
+
+        .NOTES
+        [List workflow runs for a workflow](https://docs.github.com/rest/actions/workflow-runs?apiVersion=2022-11-28#list-workflow-runs-for-a-workflow)
+    #>
+    [CmdletBinding(DefaultParameterSetName = 'Repo')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidLongLines', '', Justification = 'Contains a long link.')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidAssignmentToAutomaticVariable', 'Event',
+        Justification = 'A parameter that is used in the api call.')]
+    param(
+        # The account owner of the repository. The name is not case sensitive.
+        [Parameter(Mandatory)]
+        [string] $Owner,
+
+        # The name of the repository. The name is not case sensitive.
+        [Parameter(Mandatory)]
+        [string] $Repo,
+
+        # The ID of the workflow. You can also pass the workflow filename as a string.
+        [Parameter(Mandatory)]
+        [Alias('workflow_id', 'WorkflowID')]
+        [string] $ID,
+
+        # Returns someone's workflow runs. Use the login for the user who created the push associated with the check suite or workflow run.
+        [Parameter()]
+        [string] $Actor,
+
+        # Returns workflow runs associated with a branch. Use the name of the branch of the `push`.
+        [Parameter()]
+        [string] $Branch,
+
+        # Returns workflow run triggered by the event you specify. For example, `push`, `pull_request` or `issue`. For more information, see
+        # "[Events that trigger workflows])(https://docs.github.com/actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows)."
+        [Parameter()]
+        [string] $Event,
+
+        # Returns workflow runs with the check run status or conclusion that you specify. For example, a conclusion can be success or a status can be
+        # `in_progress`. Only GitHub Actions can set a status of `waiting`, `pending`, or `requested`.
+        # Can be one of: `completed`, `action_required`, `cancelled`, `failure`, `neutral`, `skipped`, `stale`, `success`, `timed_out`, `in_progress`,
+        # `queued`, `requested`, `waiting`, `pending`.
+        [Parameter()]
+        [ValidateSet('completed', 'action_required', 'cancelled', 'failure', 'neutral', 'skipped', 'stale', 'success', 'timed_out', 'in_progress',
+            'queued', 'requested', 'waiting', 'pending')]
+        [string] $Status,
+
+        # Returns workflow runs created within the given date-time range. For more information on the syntax, see
+        # "[Understanding the search syntax](https://docs.github.com/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates)."
+        [Parameter()]
+        [datetime] $Created,
+
+        # If `true` pull requests are omitted from the response (empty array).
+        [Parameter()]
+        [switch] $ExcludePullRequests,
+
+        # Returns workflow runs with the check_suite_id that you specify.
+        [Parameter()]
+        [int] $CheckSuiteID,
+
+        # Only returns workflow runs that are associated with the specified head_sha.
+        [Parameter()]
+        [string] $HeadSHA,
+
+        # The number of results per page (max 100).
+        [Parameter()]
+        [ValidateRange(0, 100)]
+        [int] $PerPage,
+
+        # The context to run the command in. Used to get the details for the API call.
+        # Can be either a string or a GitHubContext object.
+        [Parameter()]
+        [object] $Context = (Get-GitHubContext)
+    )
+
+    begin {
+        $stackPath = Get-PSCallStackPath
+        Write-Debug "[$stackPath] - Start"
+        $Context = Resolve-GitHubContext -Context $Context
+        Assert-GitHubContext -Context $Context -AuthType IAT, PAT, UAT
+        if ([string]::IsNullOrEmpty($Owner)) {
+            $Owner = $Context.Owner
+        }
+        Write-Debug "Owner: [$Owner]"
+
+        if ([string]::IsNullOrEmpty($Repo)) {
+            $Repo = $Context.Repo
+        }
+        Write-Debug "Repo: [$Repo]"
+    }
+
+    process {
+        try {
+            $body = @{
+                actor                 = $Actor
+                branch                = $Branch
+                event                 = $Event
+                status                = $Status
+                created               = $Created
+                exclude_pull_requests = $ExcludePullRequests
+                check_suite_id        = $CheckSuiteID
+                head_sha              = $HeadSHA
+                per_page              = $PerPage
+            }
+
+            $inputObject = @{
+                Context     = $Context
+                APIEndpoint = "/repos/$Owner/$Repo/actions/workflows/$ID/runs"
+                Method      = 'GET'
+                Body        = $body
+            }
+
+            Invoke-GitHubAPI @inputObject | ForEach-Object {
+                Write-Output $_.Response.workflow_runs
+            }
+        } catch {
+            throw $_
+        }
+    }
+
+    end {
+        Write-Debug "[$stackPath] - End"
+    }
+}
diff --git a/src/functions/private/Apps/Get-GitHubAppByName.ps1 b/src/functions/private/Apps/Get-GitHubAppByName.ps1
@@ -31,24 +31,28 @@
     )
 
     begin {
-        $commandName = $MyInvocation.MyCommand.Name
-        Write-Verbose "[$commandName] - Start"
+        $stackPath = Get-PSCallStackPath
+        Write-Debug "[$stackPath] - Start"
         $Context = Resolve-GitHubContext -Context $Context
         Assert-GitHubContext -Context $Context -AuthType IAT, PAT, UAT
     }
 
     process {
-        $inputObject = @{
-            Context     = $Context
-            APIEndpoint = "/apps/$AppSlug"
-            Method      = 'GET'
-        }
-
-        Invoke-GitHubAPI @inputObject | ForEach-Object {
-            Write-Output $_.Response
+        try {
+            $inputObject = @{
+                Context     = $Context
+                APIEndpoint = "/apps/$AppSlug"
+                Method      = 'GET'
+            }
+
+            Invoke-GitHubAPI @inputObject | ForEach-Object {
+                Write-Output $_.Response
+            }
+        } catch {
+            throw $_
         }
     }
     end {
-        Write-Verbose "[$commandName] - End"
+        Write-Debug "[$stackPath] - End"
     }
 }