module/summary.psm1
|
#Requires -PSEdition Core -Version 7.2 Import-Module -Name @( (Join-Path -Path $PSScriptRoot -ChildPath 'command-file.psm1') ) -Prefix 'GitHubActions' -Scope 'Local' #> <# .SYNOPSIS GitHub Actions - Add Summary (Raw) .DESCRIPTION Add some GitHub flavored Markdown for the current step to display on the summary page of a run. Can use to display and group unique content, such as test result summaries, so that viewing the result of a run does not need to go into the logs to see important information related to the run, such as failures. When a run's job finished, the summaries for all steps in a job are grouped together into a single job summary and are shown on the run summary page. If multiple jobs generate summaries, the job summaries are ordered by job completion time. .PARAMETER Value Contents of the summary. .PARAMETER NoNewLine Whether to not add a new line or carriage return to the content; The string representations of the input objects are concatenated to form the output, no spaces or newlines are inserted between the output strings, no newline is added after the last output string. .OUTPUTS [Void] #> Function Add-Summary { [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_addgithubactionssummary')] [OutputType([Void])] Param ( [Parameter(Mandatory = $True, Position = 0, ValueFromPipeline = $True, ValueFromPipelineByPropertyName = $True)][AllowEmptyCollection()][AllowEmptyString()][AllowNull()][Alias('Content')][Object[]]$Value, [Parameter(ValueFromPipelineByPropertyName = $True)][Switch]$NoNewLine ) Begin { [Boolean]$ShouldProceed = $True Try { Test-SummaryPath } Catch { $ShouldProceed = $False Write-Error -Message "Unable to write the GitHub Actions summary: $_" -Category 'ResourceUnavailable' } } Process { If (!$ShouldProceed) { Return } If ($Value.Count -gt 0) { Add-Content -LiteralPath $Env:GITHUB_STEP_SUMMARY -Value $Value -Confirm:$False -NoNewline:($NoNewLine.IsPresent) -Encoding 'UTF8NoBOM' } } } Set-Alias -Name 'Add-SummaryRaw' -Value 'Add-Summary' -Option 'ReadOnly' -Scope 'Local' <# .SYNOPSIS GitHub Actions - Add Summary Header .DESCRIPTION Add header for the current step to display on the summary page of a run. .PARAMETER Level Level of the header. .PARAMETER Header Title of the header. .OUTPUTS [Void] #> Function Add-SummaryHeader { [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_addgithubactionssummaryheader')] [OutputType([Void])] Param ( [Parameter(Mandatory = $True, Position = 0)][ValidateRange(1, 6)][Byte]$Level, [Parameter(Mandatory = $True, Position = 1)][ValidatePattern('^.+$', ErrorMessage = 'Value is not a single line string!')][Alias('Title', 'Value')][String]$Header ) Add-Summary -Value "$('#' * $Level) $Header" } <# .SYNOPSIS GitHub Actions - Add Summary Image .DESCRIPTION Add image for the current step to display on the summary page of a run. IMPORTANT: Not support reference image! .PARAMETER Uri URI of the image. .PARAMETER Title Title of the image. .PARAMETER AlternativeText Alternative text of the image. .PARAMETER Width Width of the image, by pixels (px). .PARAMETER Height Height of the image, by pixels (px). .PARAMETER NoNewLine Whether to not add a new line or carriage return to the content; The string representations of the input objects are concatenated to form the output, no spaces or newlines are inserted between the output strings, no newline is added after the last output string. .OUTPUTS [Void] #> Function Add-SummaryImage { [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_addgithubactionssummaryimage')] [OutputType([Void])] Param ( [Parameter(Mandatory = $True, Position = 0)][Alias('Url')][String]$Uri, [AllowEmptyString()][AllowNull()][String]$Title, [AllowEmptyString()][AllowNull()][Alias('Alt', 'AltText')][String]$AlternativeText, [ValidateRange(0, [Int32]::MaxValue)][Int32]$Width = -1, [ValidateRange(0, [Int32]::MaxValue)][Int32]$Height = -1, [Switch]$NoNewLine ) If ( $Width -gt -1 -or $Height -gt -1 ) { [String]$ResultHtml = "<img src=`"$([Uri]::EscapeUriString($Uri))`"" If ($Title.Length -gt 0) { $ResultHtml += " title=`"$([System.Web.HttpUtility]::HtmlAttributeEncode($Title))`"" } If ($AlternativeText.Length -gt 0) { $ResultHtml += " alt=`"$([System.Web.HttpUtility]::HtmlAttributeEncode($AlternativeText))`"" } If ($Width -gt -1) { $ResultHtml += " width=`"$Width`"" } If ($Height -gt -1) { $ResultHtml += " height=`"$Height`"" } $ResultHtml += ' />' Add-Summary -Value $ResultHtml -NoNewLine:($NoNewLine.IsPresent) } Else { [String]$ResultMarkdown = "![$([System.Web.HttpUtility]::HtmlAttributeEncode($AlternativeText))]($([Uri]::EscapeUriString($Uri))" If ($Title.Length -gt 0) { $ResultMarkdown += " `"$([System.Web.HttpUtility]::HtmlAttributeEncode($Title))`"" } $ResultMarkdown += ')' Add-Summary -Value $ResultMarkdown -NoNewLine:($NoNewLine.IsPresent) } } Set-Alias -Name 'Add-SummaryPicture' -Value 'Add-SummaryImage' -Option 'ReadOnly' -Scope 'Local' <# .SYNOPSIS GitHub Actions - Add Summary Link .DESCRIPTION Add link for the current step to display on the summary page of a run. IMPORTANT: Not support reference link! .PARAMETER Text Text of the link. .PARAMETER Uri URI of the link. .PARAMETER Title Title of the link. .PARAMETER NoNewLine Whether to not add a new line or carriage return to the content; The string representations of the input objects are concatenated to form the output, no spaces or newlines are inserted between the output strings, no newline is added after the last output string. .OUTPUTS [Void] #> Function Add-SummaryLink { [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_addgithubactionssummarylink')] [OutputType([Void])] Param ( [Parameter(Mandatory = $True, Position = 0)][String]$Text, [Parameter(Mandatory = $True, Position = 1)][Alias('Url')][String]$Uri, [AllowEmptyString()][AllowNull()][String]$Title, [Switch]$NoNewLine ) [String]$ResultMarkdown = "[$([System.Web.HttpUtility]::HtmlAttributeEncode($Text))]($([Uri]::EscapeUriString($Uri))" If ($Title.Length -gt 0) { $ResultMarkdown += " `"$([System.Web.HttpUtility]::HtmlAttributeEncode($Title))`"" } $ResultMarkdown += ')' Add-Summary -Value $ResultMarkdown -NoNewLine:($NoNewLine.IsPresent) } Set-Alias -Name 'Add-SummaryHyperlink' -Value 'Add-SummaryLink' -Option 'ReadOnly' -Scope 'Local' <# .SYNOPSIS GitHub Actions - Add Summary Subscript Text .DESCRIPTION Add subscript text for the current step to display on the summary page of a run. .PARAMETER Text A string that need to subscript text. .PARAMETER NoNewLine Whether to not add a new line or carriage return to the content; The string representations of the input objects are concatenated to form the output, no spaces or newlines are inserted between the output strings, no newline is added after the last output string. .OUTPUTS [Void] #> Function Add-SummarySubscriptText { [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_addgithubactionssummarysubscripttext')] [OutputType([Void])] Param ( [Parameter(Mandatory = $True, Position = 0)][Alias('Input', 'InputObject', 'Object')][String]$Text, [Switch]$NoNewLine ) Add-Summary -Value "<sub>$([System.Web.HttpUtility]::HtmlEncode($Text))</sub>" -NoNewLine:($NoNewLine.IsPresent) } Set-Alias -Name 'Add-SummarySubscript' -Value 'Add-SummarySubscriptText' -Option 'ReadOnly' -Scope 'Local' <# .SYNOPSIS GitHub Actions - Add Summary Superscript Text .DESCRIPTION Add superscript text for the current step to display on the summary page of a run. .PARAMETER Text A string that need to superscript text. .PARAMETER NoNewLine Whether to not add a new line or carriage return to the content; The string representations of the input objects are concatenated to form the output, no spaces or newlines are inserted between the output strings, no newline is added after the last output string. .OUTPUTS [Void] #> Function Add-SummarySuperscriptText { [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_addgithubactionssummarysuperscripttext')] [OutputType([Void])] Param ( [Parameter(Mandatory = $True, Position = 0)][Alias('Input', 'InputObject', 'Object')][String]$Text, [Switch]$NoNewLine ) Add-Summary -Value "<sup>$([System.Web.HttpUtility]::HtmlEncode($Text))</sup>" -NoNewLine:($NoNewLine.IsPresent) } Set-Alias -Name 'Add-SummarySuperscript' -Value 'Add-SummarySuperscriptText' -Option 'ReadOnly' -Scope 'Local' <# .SYNOPSIS GitHub Actions - Clear Summary .DESCRIPTION Clear the summary that set in the current step. .OUTPUTS [Void] #> Function Clear-Summary { [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_cleargithubactionssummary')] [OutputType([Void])] Param () Clear-GitHubActionsFileCommand -FileCommand 'GITHUB_STEP_SUMMARY' } Set-Alias -Name 'Remove-Summary' -Value 'Clear-Summary' -Option 'ReadOnly' -Scope 'Local' <# .SYNOPSIS GitHub Actions - Get Summary .DESCRIPTION Get the summary that set in the current step. .PARAMETER Raw Whether to ignore newline characters and output the entire contents of a file in one string with the newlines preserved; By default, newline characters in a file are used as delimiters to separate the input into an array of strings. .PARAMETER Size Whether to get the size of the summary instead of the contents of the summary. .OUTPUTS [String] Summary with the entire contents in one string. [String[]] Summary with the entire contents in multiple strings separated by newline characters. [UInt32] Size of the summary. #> Function Get-Summary { [CmdletBinding(DefaultParameterSetName = 'Content', HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_getgithubactionssummary')] [OutputType([String], ParameterSetName = 'ContentRaw')] [OutputType([String[]], ParameterSetName = 'Content')] [OutputType([UInt32], ParameterSetName = 'Size')] Param ( [Parameter(Mandatory = $True, ParameterSetName = 'ContentRaw')][Switch]$Raw, [Parameter(Mandatory = $True, ParameterSetName = 'Size')][Alias('Sizes')][Switch]$Size ) Try { If ([String]::IsNullOrEmpty($Env:GITHUB_STEP_SUMMARY)) { Throw 'Environment path `GITHUB_STEP_SUMMARY` is not defined!' } If (![System.IO.Path]::IsPathFullyQualified($Env:GITHUB_STEP_SUMMARY)) { Throw "``$Env:GITHUB_STEP_SUMMARY`` (environment path ``GITHUB_STEP_SUMMARY``) is not a valid absolute path!" } If (!(Test-Path -LiteralPath $Env:GITHUB_STEP_SUMMARY -PathType 'Leaf')) { Throw 'File is not exist!' } If ($PSCmdlet.ParameterSetName -ieq 'Size') { Get-Item -LiteralPath $Env:GITHUB_STEP_SUMMARY | Select-Object -ExpandProperty 'Length' | Write-Output } Else { Get-Content -LiteralPath $Env:GITHUB_STEP_SUMMARY -Raw:($PSCmdlet.ParameterSetName -ieq 'ContentRaw') -Encoding 'UTF8NoBOM' | Write-Output } } Catch { Write-Error -Message "Unable to get the GitHub Actions summary: $_" -Category 'ResourceUnavailable' } } <# .SYNOPSIS GitHub Actions - Internal - Test Summary Path .DESCRIPTION Test summary path. .OUTPUTS [Void] #> Function Test-SummaryPath { [OutputType([Void])] Param () If ([String]::IsNullOrEmpty($Env:GITHUB_STEP_SUMMARY)) { Throw 'Environment path `GITHUB_STEP_SUMMARY` is not defined!' } If (![System.IO.Path]::IsPathFullyQualified($Env:GITHUB_STEP_SUMMARY)) { Throw "``$Env:GITHUB_STEP_SUMMARY`` (environment path ``GITHUB_STEP_SUMMARY``) is not a valid absolute path!" } If (!(Test-Path -LiteralPath $Env:GITHUB_STEP_SUMMARY -PathType 'Leaf')) { Throw 'File is not exist!' } } <# .SYNOPSIS GitHub Actions - Set Summary .DESCRIPTION Set some GitHub flavored Markdown for the current step to display on the summary page of a run. Can use to display and group unique content, such as test result summaries, so that viewing the result of a run does not need to go into the logs to see important information related to the run, such as failures. When a run's job finished, the summaries for all steps in a job are grouped together into a single job summary and are shown on the run summary page. If multiple jobs generate summaries, the job summaries are ordered by job completion time. .PARAMETER Value Contents of the summary. .PARAMETER NoNewLine Whether to not add a new line or carriage return to the content; The string representations of the input objects are concatenated to form the output, no spaces or newlines are inserted between the output strings, no newline is added after the last output string. .OUTPUTS [Void] #> Function Set-Summary { [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_setgithubactionssummary')] [OutputType([Void])] Param ( [Parameter(Mandatory = $True, Position = 0, ValueFromPipeline = $True, ValueFromPipelineByPropertyName = $True)][AllowEmptyCollection()][AllowEmptyString()][AllowNull()][Alias('Content')][String[]]$Value, [Switch]$NoNewLine ) Begin { [Boolean]$ShouldProceed = $True Try { Test-SummaryPath } Catch { $ShouldProceed = $False Write-Error -Message "Unable to write the GitHub Actions summary: $_" -Category 'ResourceUnavailable' } [String[]]$Result = @() } Process { If (!$ShouldProceed) { Return } If ($Value.Count -gt 0) { $Result += $Value | Join-String -Separator "`n" } } End { If ($Result.Count -gt 0) { $Result | Join-String -Separator "`n" | Set-Content -LiteralPath $Env:GITHUB_STEP_SUMMARY -Confirm:$False -NoNewline:($NoNewLine.IsPresent) -Encoding 'UTF8NoBOM' } } } Export-ModuleMember -Function @( 'Add-Summary', 'Add-SummaryHeader', 'Add-SummaryImage', 'Add-SummaryLink', 'Add-SummarySubscriptText' 'Add-SummarySuperscriptText' 'Clear-Summary', 'Get-Summary', 'Set-Summary' ) -Alias @( 'Add-SummaryHyperlink', 'Add-SummaryPicture', 'Add-SummaryRaw', 'Add-SummarySubscript', 'Add-SummarySuperscript', 'Remove-Summary' ) |