feat: add cmdlets to work around even more PlatyPS issues.

This time PowerShell/platyPS#595 hopefully this is the last one for a while... 😬

Author: shoddyguard

Module/Private/PowerShell/platyPS/Add-PlatyPSCommonParameter.ps1

@@ -0,0 +1,88 @@
+<#
+.SYNOPSIS
+    Adds a set of common parameters to a function's documentation footer.
+.DESCRIPTION
+    This works around a bug in platyPS (https://github.com/PowerShell/platyPS/issues/595) that isn't likely to be
+    fixed until the the PlatyPS rewrite has been completed.
+    Should more common parameters be added to PowerShell in the future, this script will need to be updated.
+#>
+function Add-PlatyPSCommonParameter
+{
+    [CmdletBinding()]
+    param
+    (
+        # The content to check for common parameters.
+        [Parameter(
+            Mandatory = $true,
+            ValueFromPipelineByPropertyName = $true,
+            Position = 0
+        )]
+        [BrownserveContent[]]
+        $Content,
+
+        # The common parameters to remove.
+        [Parameter(
+            Mandatory = $false,
+            Position = 1
+        )]
+        [string[]]
+        $Parameter = @('-ProgressAction')
+    )
+
+    begin
+    {
+        $Return = @()
+    }
+
+    process
+    {
+        foreach ($FileToProcess in $Content)
+        {
+            $StringContent = $FileToProcess.ToString()
+            $SupportedCommonParamPattern = '(?m)^This cmdlet supports the common parameters:(?<common_params>.+?)\.'
+            if ($StringContent -match $SupportedCommonParamPattern)
+            {
+                $CommonParams = $Matches['common_params'] -replace ',', '' -split ' ' |
+                    Where-Object {$_ -match '^-'}
+                if (!$CommonParams)
+                {
+                    throw 'Failed to extract common parameters from the supported common parameters section.'
+                }
+                $Parameter | ForEach-Object {
+                    $ParameterName = $_
+                    if (!$ParameterName.StartsWith('-'))
+                    {
+                        $ParameterName = "-$ParameterName"
+                    }
+                    if ($ParameterName -notin $CommonParams)
+                    {
+                        $CommonParams += $ParameterName
+                    }
+                }
+                $CommonParams = $CommonParams | Sort-Object
+                $CommonParams[-1] = "and $($CommonParams[-1])"
+                $CommonParams = $CommonParams -join ', '
+                $StringContent = $StringContent -replace $SupportedCommonParamPattern, "This cmdlet supports the common parameters: $CommonParams."
+                $ProcessedContent = $StringContent | Format-BrownserveContent | Select-Object -ExpandProperty Content
+                $FileToProcess.Content = $ProcessedContent
+                $Return += $FileToProcess
+            }
+            else
+            {
+                throw 'Failed to find the supported common parameters section.'
+            }
+        }
+    }
+
+    end
+    {
+        if ($Return.Count -gt 0)
+        {
+            return $Return
+        }
+        else
+        {
+            return $null
+        }
+    }
+}

Module/Private/PowerShell/platyPS/Remove-PlatyPSCommonParameter.ps1

@@ -0,0 +1,69 @@
+<#
+.SYNOPSIS
+    Removes a set of common parameters from a function's documentation.
+.DESCRIPTION
+    This works around a bug in platyPS (https://github.com/PowerShell/platyPS/issues/595) that isn't likely to be
+    fixed until the the PlatyPS rewrite has been completed.
+    Should more common parameters be added to PowerShell in the future, this script will need to be updated.
+#>
+function Remove-PlatyPSCommonParameter
+{
+    [CmdletBinding()]
+    param
+    (
+        # The content to check for common parameters.
+        [Parameter(
+            Mandatory = $true,
+            ValueFromPipelineByPropertyName = $true,
+            Position = 0
+        )]
+        [BrownserveContent[]]
+        $Content,
+
+        # The common parameters to remove.
+        [Parameter(
+            Mandatory = $false,
+            Position = 1
+        )]
+        [string[]]
+        $Parameter = @('-ProgressAction')
+    )
+
+    begin
+    {
+        $Return = @()
+    }
+
+    process
+    {
+        foreach ($FileToProcess in $Content)
+        {
+            $StringContent = $FileToProcess.ToString()
+            # Regex adapted from: https://github.com/PowerShell/platyPS/issues/595#issuecomment-1820971702
+            $Parameter | ForEach-Object {
+                $ParameterName = $_
+                if (!$ParameterName.StartsWith('-'))
+                {
+                    $ParameterName = "-$ParameterName"
+                }
+                $StringContent = $StringContent -replace "(?m)^### $_\r?\n[\S\s]*?(?=#{2,3}?)", ''
+                $StringContent = $StringContent -replace " \[$_\s?.*?]"
+            }
+            $ProcessedContent = $StringContent | Format-BrownserveContent | Select-Object -ExpandProperty Content
+            $FileToProcess.Content = $ProcessedContent
+            $Return += $FileToProcess
+        }
+    }
+
+    end
+    {
+        if ($Return.Count -gt 0)
+        {
+            return $Return
+        }
+        else
+        {
+            return $null
+        }
+    }
+}