module/step-summary.psm1

#Requires -PSEdition Core
#Requires -Version 7.2
Import-Module -Name (
    @(
        'utility.psm1'
    ) |
        ForEach-Object -Process { Join-Path -Path $PSScriptRoot -ChildPath $_ }
) -Prefix 'GitHubActions' -Scope 'Local'
<#
.SYNOPSIS
GitHub Actions - Add Step Summary (Raw)
.DESCRIPTION
Add some GitHub flavored Markdown for step so that it will 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 finishes, 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
Content.
.PARAMETER NoNewLine
Do 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-StepSummary {
    [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_add-githubactionsstepsummary#Add-GitHubActionsStepSummary')]
    [OutputType([Void])]
    Param (
        [Parameter(Mandatory = $True, Position = 0, ValueFromPipeline = $True)][AllowEmptyCollection()][AllowEmptyString()][AllowNull()][Alias('Content')][String[]]$Value,
        [Switch]$NoNewLine
    )
    Begin {
        [Boolean]$NoOperation = $False# When the requirements are not fulfill, only stop this function but not others.
        If (!(Test-GitHubActionsEnvironment -StepSummary)) {
            Write-Error -Message 'Unable to get GitHub Actions step summary resources!' -Category 'ResourceUnavailable'
            $NoOperation = $True
        }
        [String[]]$Result = @()
    }
    Process {
        If ($NoOperation) {
            Return
        }
        If ($Value.Count -igt 0) {
            $Result += $Value |
                Join-String -Separator "`n"
        }
    }
    End {
        If ($NoOperation) {
            Return
        }
        If ($Result.Count -igt 0) {
            Add-Content -LiteralPath $Env:GITHUB_STEP_SUMMARY -Value (
                $Result |
                    Join-String -Separator "`n"
            ) -Confirm:$False -NoNewline:$NoNewLine.IsPresent -Encoding 'UTF8NoBOM'
        }
    }
}
Set-Alias -Name 'Add-StepSummaryRaw' -Value 'Add-StepSummary' -Option 'ReadOnly' -Scope 'Local'
<#
.SYNOPSIS
GitHub Actions - Add Step Summary Header
.DESCRIPTION
Add header for step so that it will display on the summary page of a run.
.PARAMETER Level
Header level
.PARAMETER Header
Header title.
.OUTPUTS
[Void]
#>

Function Add-StepSummaryHeader {
    [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_add-githubactionsstepsummaryheader#Add-GitHubActionsStepSummaryHeader')]
    [OutputType([Void])]
    Param (
        [Parameter(Mandatory = $True, Position = 0)][ValidateRange(1, 6)][Byte]$Level,
        [Parameter(Mandatory = $True, Position = 1)][ValidatePattern('^.+$', ErrorMessage = 'Parameter `Header` must be in single line string!')][Alias('Title', 'Value')][String]$Header
    )
    Add-StepSummary -Value "$('#' * $Level) $Header"
}
<#
.SYNOPSIS
GitHub Actions - Add Step Summary Image
.DESCRIPTION
Add image for step so that it will display on the summary page of a run.
 
IMPORTANT: Not support reference image!
.PARAMETER Uri
Image URI.
.PARAMETER Title
Image title.
.PARAMETER AlternativeText
Image alternative text.
.PARAMETER Width
Image width, by pixels (px).
.PARAMETER Height
Image height, by pixels (px).
.PARAMETER NoNewLine
Do 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-StepSummaryImage {
    [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_add-githubactionsstepsummaryimage#Add-GitHubActionsStepSummaryImage')]
    [OutputType([Void])]
    Param (
        [Parameter(Mandatory = $True, Position = 0)][Alias('Url')][String]$Uri,
        [String]$Title,
        [Alias('AltText')][String]$AlternativeText,
        [ValidateRange(0, [Int32]::MaxValue)][Int32]$Width = -1,
        [ValidateRange(0, [Int32]::MaxValue)][Int32]$Height = -1,
        [Switch]$NoNewLine
    )
    If (
        $Width -igt -1 -or
        $Height -igt -1
    ) {
        [String]$ResultHtml = "<img src=`"$([Uri]::EscapeUriString($Uri))`""
        If ($Title.Length -igt 0) {
            $ResultHtml += " title=`"$([System.Web.HttpUtility]::HtmlAttributeEncode($Title))`""
        }
        If ($AlternativeText.Length -igt 0) {
            $ResultHtml += " alt=`"$([System.Web.HttpUtility]::HtmlAttributeEncode($AlternativeText))`""
        }
        If ($Width -igt -1) {
            $ResultHtml += " width=`"$Width`""
        }
        If ($Height -igt -1) {
            $ResultHtml += " height=`"$Height`""
        }
        $ResultHtml += ' />'
        Add-StepSummary -Value $ResultHtml -NoNewLine:$NoNewLine.IsPresent
    }
    Else {
        [String]$ResultMarkdown = "![$([System.Web.HttpUtility]::HtmlAttributeEncode($AlternativeText))]($([Uri]::EscapeUriString($Uri))"
        If ($Title.Length -igt 0) {
            $ResultMarkdown += " `"$([System.Web.HttpUtility]::HtmlAttributeEncode($Title))`""
        }
        $ResultMarkdown += ')'
        Add-StepSummary -Value $ResultMarkdown -NoNewLine:$NoNewLine.IsPresent
    }
}
Set-Alias -Name 'Add-StepSummaryPicture' -Value 'Add-StepSummaryImage' -Option 'ReadOnly' -Scope 'Local'
<#
.SYNOPSIS
GitHub Actions - Add Step Summary Link
.DESCRIPTION
Add link for step so that it will display on the summary page of a run.
 
IMPORTANT: Not support reference link!
.PARAMETER Text
Link text.
.PARAMETER Uri
Link URI.
.PARAMETER Title
Link title.
.PARAMETER NoNewLine
Do 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-StepSummaryLink {
    [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_add-githubactionsstepsummarylink#Add-GitHubActionsStepSummaryLink')]
    [OutputType([Void])]
    Param (
        [Parameter(Mandatory = $True, Position = 0)][String]$Text,
        [Parameter(Mandatory = $True, Position = 1)][Alias('Url')][String]$Uri,
        [String]$Title,
        [Switch]$NoNewLine
    )
    [String]$ResultMarkdown = "[$([System.Web.HttpUtility]::HtmlAttributeEncode($Text))]($([Uri]::EscapeUriString($Uri))"
    If ($Title.Length -igt 0) {
        $ResultMarkdown += " `"$([System.Web.HttpUtility]::HtmlAttributeEncode($Title))`""
    }
    $ResultMarkdown += ')'
    Add-StepSummary -Value $ResultMarkdown -NoNewLine:$NoNewLine.IsPresent
}
Set-Alias -Name 'Add-StepSummaryHyperlink' -Value 'Add-StepSummaryLink' -Option 'ReadOnly' -Scope 'Local'
<#
.SYNOPSIS
GitHub Actions - Add Step Summary Subscript Text
.DESCRIPTION
Add subscript text for step so that it will display on the summary page of a run.
.PARAMETER Text
Text that need to subscript.
.PARAMETER NoNewLine
Do 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-StepSummarySubscriptText {
    [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_add-githubactionsstepsummarysubscripttext#Add-GitHubActionsStepSummarySubscriptText')]
    [OutputType([Void])]
    Param (
        [Parameter(Mandatory = $True, Position = 0)][Alias('Input', 'InputObject', 'Object')][String]$Text,
        [Switch]$NoNewLine
    )
    Add-StepSummary -Value "<sub>$([System.Web.HttpUtility]::HtmlEncode($Text))</sub>" -NoNewLine:$NoNewLine.IsPresent
}
Set-Alias -Name 'Add-StepSummarySubscript' -Value 'Add-StepSummarySubscriptText' -Option 'ReadOnly' -Scope 'Local'
<#
.SYNOPSIS
GitHub Actions - Add Step Summary Superscript Text
.DESCRIPTION
Add superscript text for step so that it will display on the summary page of a run.
.PARAMETER Text
Text that need to superscript.
.PARAMETER NoNewLine
Do 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-StepSummarySuperscriptText {
    [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_add-githubactionsstepsummarysuperscripttext#Add-GitHubActionsStepSummarySuperscriptText')]
    [OutputType([Void])]
    Param (
        [Parameter(Mandatory = $True, Position = 0)][Alias('Input', 'InputObject', 'Object')][String]$Text,
        [Switch]$NoNewLine
    )
    Add-StepSummary -Value "<sup>$([System.Web.HttpUtility]::HtmlEncode($Text))</sup>" -NoNewLine:$NoNewLine.IsPresent
}
Set-Alias -Name 'Add-StepSummarySuperscript' -Value 'Add-StepSummarySuperscriptText' -Option 'ReadOnly' -Scope 'Local'
<#
.SYNOPSIS
GitHub Actions - Get Step Summary
.DESCRIPTION
Get step summary that previously added/setted from functions `Add-GitHubActionsStepSummary` and `Set-GitHubActionsStepSummary`.
.PARAMETER Raw
Ignore newline characters and return 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 Sizes
Get step summary sizes instead of the content.
.OUTPUTS
[String] Step summary with the entire contents in one string.
[String[]] Step summary with separate contents in multiple string by newline characters.
[UInt32] Step summary sizes.
#>

Function Get-StepSummary {
    [CmdletBinding(DefaultParameterSetName = 'Content', HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_get-githubactionsstepsummary#Get-GitHubActionsStepSummary')]
    [OutputType(([String], [String[]]), ParameterSetName = 'Content')]
    [OutputType([UInt32], ParameterSetName = 'Sizes')]
    Param (
        [Parameter(ParameterSetName = 'Content')][Switch]$Raw,
        [Parameter(Mandatory = $True, ParameterSetName = 'Sizes')][Alias('Size')][Switch]$Sizes
    )
    If (!(Test-GitHubActionsEnvironment -StepSummary)) {
        Write-Error -Message 'Unable to get GitHub Actions step summary resources!' -Category 'ResourceUnavailable'
        Return
    }
    Switch ($PSCmdlet.ParameterSetName) {
        'Content' {
            Get-Content -LiteralPath $Env:GITHUB_STEP_SUMMARY -Raw:$Raw.IsPresent -Encoding 'UTF8NoBOM' |
                Write-Output
        }
        'Sizes' {
            Get-Item -LiteralPath $Env:GITHUB_STEP_SUMMARY |
                Select-Object -ExpandProperty 'Length' |
                Write-Output
        }
    }
}
<#
.SYNOPSIS
GitHub Actions - Remove Step Summary
.DESCRIPTION
Remove step summary that previously added/setted from functions `Add-GitHubActionsStepSummary` and `Set-GitHubActionsStepSummary`.
.OUTPUTS
[Void]
#>

Function Remove-StepSummary {
    [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_remove-githubactionsstepsummary#Remove-GitHubActionsStepSummary')]
    [OutputType([Void])]
    Param ()
    If (!(Test-GitHubActionsEnvironment -StepSummary)) {
        Write-Error -Message 'Unable to get GitHub Actions step summary resources!' -Category 'ResourceUnavailable'
        Return
    }
    Remove-Item -LiteralPath $Env:GITHUB_STEP_SUMMARY -Confirm:$False
}
<#
.SYNOPSIS
GitHub Actions - Set Step Summary
.DESCRIPTION
Set some GitHub flavored Markdown for step so that it will 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 finishes, 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
Content.
.PARAMETER NoNewLine
Do 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-StepSummary {
    [CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_set-githubactionsstepsummary#Set-GitHubActionsStepSummary')]
    [OutputType([Void])]
    Param (
        [Parameter(Mandatory = $True, Position = 0, ValueFromPipeline = $True)][AllowEmptyCollection()][AllowEmptyString()][AllowNull()][Alias('Content')][String[]]$Value,
        [Switch]$NoNewLine
    )
    Begin {
        [Boolean]$NoOperation = $False# When the requirements are not fulfill, only stop this function but not others.
        If (!(Test-GitHubActionsEnvironment -StepSummary)) {
            Write-Error -Message 'Unable to get GitHub Actions step summary resources!' -Category 'ResourceUnavailable'
            $NoOperation = $True
        }
        [String[]]$Result = @()
    }
    Process {
        If ($NoOperation) {
            Return
        }
        If ($Value.Count -igt 0) {
            $Result += $Value |
                Join-String -Separator "`n"
        }
    }
    End {
        If ($NoOperation) {
            Return
        }
        If ($Result.Count -igt 0) {
            Set-Content -LiteralPath $Env:GITHUB_STEP_SUMMARY -Value (
                $Result |
                    Join-String -Separator "`n"
            ) -Confirm:$False -NoNewline:$NoNewLine.IsPresent -Encoding 'UTF8NoBOM'
        }
    }
}
Export-ModuleMember -Function @(
    'Add-StepSummary',
    'Add-StepSummaryHeader',
    'Add-StepSummaryImage',
    'Add-StepSummaryLink',
    'Add-StepSummarySubscriptText'
    'Add-StepSummarySuperscriptText'
    'Get-StepSummary',
    'Remove-StepSummary',
    'Set-StepSummary'
) -Alias @(
    'Add-StepSummaryHyperlink',
    'Add-StepSummaryPicture',
    'Add-StepSummaryRaw',
    'Add-StepSummarySubscript',
    'Add-StepSummarySuperscript'
)