diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 7742df4..4a07b68 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -5,9 +5,11 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [2.0.2] +## [2.2.0] - Catesta template module changes + - Added `MarkdownRepair.ps1` and added Markdown repair logic to InvokeBuild script. This is to account for an issue in PowerShell `7.4.0`+ where a new parameter was introduced that platyPS can not handle during help creation. Ref: [platyPS issue]([text](https://github.com/PowerShell/platyPS/issues/595)). + - If a build is run and the build environment is `7.4.0`+ the Markdown repair will run to account for the new parameter and repair markdown for help creation. - CI/CD Changes: - Azure: - Updated `testRunner` alias reference to `testResultsFormat` @@ -15,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Pester bumped from `5.4.0` to `5.5.0` - InvokeBuild bumped from `5.10.2` to `5.10.4` - Catesta primary module changes + - Added `MarkdownRepair.ps1` and added Markdown repair logic to InvokeBuild script. - Plaster bumped from `1.1.3` to `1.1.4` - Pester bumped from `5.4.0` to `5.5.0` - InvokeBuild bumped from `5.10.2` to `5.10.4` diff --git a/docs/Catesta-ModuleSchema.md b/docs/Catesta-ModuleSchema.md index ffbdc9e..7f67cd1 100644 --- a/docs/Catesta-ModuleSchema.md +++ b/docs/Catesta-ModuleSchema.md @@ -260,7 +260,6 @@ Help = 'Yes' Pester = '5' - } New-ModuleProject -ModuleParameters $moduleParameters -DestinationPath . ``` diff --git a/docs/Catesta-VaultSchema.md b/docs/Catesta-VaultSchema.md index c44f844..11609a3 100644 --- a/docs/Catesta-VaultSchema.md +++ b/docs/Catesta-VaultSchema.md @@ -251,7 +251,6 @@ CodingStyle = 'Stroustrup' Pester = '5' - } New-ModuleProject -ModuleParameters $vaultParameters -DestinationPath . ``` diff --git a/docs/Catesta.md b/docs/Catesta.md index 3d4a350..b01bc16 100644 --- a/docs/Catesta.md +++ b/docs/Catesta.md @@ -2,7 +2,7 @@ Module Name: Catesta Module Guid: 6796b193-9013-468a-b022-837749af2d06 Download Help Link: NA -Help Version: 2.0.2 +Help Version: 2.2.0 Locale: en-US --- diff --git a/docs/New-ModuleProject.md b/docs/New-ModuleProject.md index 4a29ad8..ade52b7 100644 --- a/docs/New-ModuleProject.md +++ b/docs/New-ModuleProject.md @@ -357,7 +357,7 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -Verbose, -WarningAction, -WarningVariable, and -ProgressAction. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -382,4 +382,3 @@ Read the manifest schemas to understand how to properly craft a ModuleParameters [https://www.catesta.dev/en/latest/New-ModuleProject/](https://www.catesta.dev/en/latest/New-ModuleProject/) [https://docs.microsoft.com/powershell/scripting/developer/module/writing-a-windows-powershell-module](https://docs.microsoft.com/powershell/scripting/developer/module/writing-a-windows-powershell-module) - diff --git a/docs/New-VaultProject.md b/docs/New-VaultProject.md index 38c3ba4..e2b2d10 100644 --- a/docs/New-VaultProject.md +++ b/docs/New-VaultProject.md @@ -349,7 +349,7 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -Verbose, -WarningAction, -WarningVariable, and -ProgressAction. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -369,4 +369,3 @@ Author: Jake Morrison - @jakemorrison - https://www.techthoughts.info/ [https://www.catesta.dev/en/latest/Catesta-Vault-Extension/](https://www.catesta.dev/en/latest/Catesta-Vault-Extension/) [https://github.com/PowerShell/SecretManagement](https://github.com/PowerShell/SecretManagement) - diff --git a/src/Catesta.build.ps1 b/src/Catesta.build.ps1 index 883e870..b1722e1 100644 --- a/src/Catesta.build.ps1 +++ b/src/Catesta.build.ps1 @@ -396,6 +396,17 @@ Add-BuildTask CreateMarkdownHelp -After CreateHelpStart { throw 'Missing GUID. Please review and rebuild.' } + Write-Build Gray ' Evaluating if running 7.4.0 or higher...' + # https://github.com/PowerShell/platyPS/issues/595 + if ($PSVersionTable.PSVersion -ge [version]'7.4.0') { + Write-Build Gray ' Performing Markdown repair' + # dot source markdown repair + . $BuildRoot\MarkdownRepair.ps1 + $OutputDir | Get-ChildItem -File | ForEach-Object { + Repair-PlatyPSMarkdown -Path $_.FullName + } + } + Write-Build Gray ' Checking for missing documentation in md files...' $MissingDocumentation = Select-String -Path "$script:ArtifactsPath\docs\*.md" -Pattern "({{.*}})" if ($MissingDocumentation.Count -gt 0) { diff --git a/src/Catesta/Catesta.psd1 b/src/Catesta/Catesta.psd1 index e77177b..871d912 100644 --- a/src/Catesta/Catesta.psd1 +++ b/src/Catesta/Catesta.psd1 @@ -12,7 +12,7 @@ RootModule = 'Catesta.psm1' # Version number of this module. - ModuleVersion = '2.0.2' + ModuleVersion = '2.2.0' # Supported PSEditions # CompatiblePSEditions = @() diff --git a/src/Catesta/Resources/Module/plasterManifest.xml b/src/Catesta/Resources/Module/plasterManifest.xml index c33cd3f..6e392ef 100644 --- a/src/Catesta/Resources/Module/plasterManifest.xml +++ b/src/Catesta/Resources/Module/plasterManifest.xml @@ -18,7 +18,7 @@ Catesta 258a61ba-566b-4c3a-8230-c2b6861a1a8d - 2.0.2 + 2.2.0 Catesta Scaffolds a new PowerShell module project Jake Morrison @@ -179,6 +179,7 @@ + diff --git a/src/Catesta/Resources/Module/src/MarkdownRepair.ps1 b/src/Catesta/Resources/Module/src/MarkdownRepair.ps1 new file mode 100644 index 0000000..aa011ec --- /dev/null +++ b/src/Catesta/Resources/Module/src/MarkdownRepair.ps1 @@ -0,0 +1,135 @@ +<# +.SYNOPSIS + Repair PlatyPS generated markdown files. +.NOTES + This file is temporarily required to handle platyPS help generation. + https://github.com/PowerShell/platyPS/issues/595 + This is a result of a breaking change introduced in PowerShell 7.4.0: + https://learn.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-74?view=powershell-7.4 + Breaking Changes: Added the ProgressAction parameter to the Common Parameters + modified from source: https://github.com/PowerShell/platyPS/issues/595#issuecomment-1820971702 +#> + +function Remove-CommonParameterFromMarkdown { + <# + .SYNOPSIS + Remove a PlatyPS generated parameter block. + .DESCRIPTION + Removes parameter block for the provided parameter name from the markdown file provided. + #> + param( + [Parameter(Mandatory)] + [string[]] + $Path, + + [Parameter(Mandatory = $false)] + [string[]] + $ParameterName = @('ProgressAction') + ) + $ErrorActionPreference = 'Stop' + foreach ($p in $Path) { + $content = (Get-Content -Path $p -Raw).TrimEnd() + $updateFile = $false + foreach ($param in $ParameterName) { + if (-not ($Param.StartsWith('-'))) { + $param = "-$($param)" + } + # Remove the parameter block + $pattern = "(?m)^### $param\r?\n[\S\s]*?(?=#{2,3}?)" + $newContent = $content -replace $pattern, '' + # Remove the parameter from the syntax block + $pattern = " \[$param\s?.*?]" + $newContent = $newContent -replace $pattern, '' + if ($null -ne (Compare-Object -ReferenceObject $content -DifferenceObject $newContent)) { + Write-Verbose "Added $param to $p" + # Update file content + $content = $newContent + $updateFile = $true + } + } + # Save file if content has changed + if ($updateFile) { + $newContent | Out-File -Encoding utf8 -FilePath $p + Write-Verbose "Updated file: $p" + } + } + return +} + +function Add-MissingCommonParameterToMarkdown { + param( + [Parameter(Mandatory)] + [string[]] + $Path, + + [Parameter(Mandatory = $false)] + [string[]] + $ParameterName = @('ProgressAction') + ) + $ErrorActionPreference = 'Stop' + foreach ($p in $Path) { + $content = (Get-Content -Path $p -Raw).TrimEnd() + $updateFile = $false + foreach ($NewParameter in $ParameterName) { + if (-not ($NewParameter.StartsWith('-'))) { + $NewParameter = "-$($NewParameter)" + } + $pattern = '(?m)^This cmdlet supports the common parameters:(.+?)\.' + $replacement = { + $Params = $_.Groups[1].Captures[0].ToString() -split ' ' + $CommonParameters = @() + foreach ($CommonParameter in $Params) { + if ($CommonParameter.StartsWith('-')) { + if ($CommonParameter.EndsWith(',')) { + $CleanParam = $CommonParameter.Substring(0, $CommonParameter.Length - 1) + } + elseif ($p.EndsWith('.')) { + $CleanParam = $CommonParameter.Substring(0, $CommonParameter.Length - 1) + } + else { + $CleanParam = $CommonParameter + } + $CommonParameters += $CleanParam + } + } + if ($NewParameter -notin $CommonParameters) { + $CommonParameters += $NewParameter + } + $CommonParameters[-1] = "and $($CommonParameters[-1]). " + return "This cmdlet supports the common parameters: " + (($CommonParameters | Sort-Object) -join ', ') + } + $newContent = $content -replace $pattern, $replacement + if ($null -ne (Compare-Object -ReferenceObject $content -DifferenceObject $newContent)) { + Write-Verbose "Added $NewParameter to $p" + $updateFile = $true + $content = $newContent + } + } + # Save file if content has changed + if ($updateFile) { + $newContent | Out-File -Encoding utf8 -FilePath $p + Write-Verbose "Updated file: $p" + } + } + return +} + +function Repair-PlatyPSMarkdown { + param( + [Parameter(Mandatory)] + [string[]] + $Path, + + [Parameter()] + [string[]] + $ParameterName = @('ProgressAction') + ) + $ErrorActionPreference = 'Stop' + $Parameters = @{ + Path = $Path + ParameterName = $ParameterName + } + $null = Remove-CommonParameterFromMarkdown @Parameters + $null = Add-MissingCommonParameterToMarkdown @Parameters + return +} diff --git a/src/Catesta/Resources/Module/src/PSModule.build.ps1 b/src/Catesta/Resources/Module/src/PSModule.build.ps1 index 2ab2de5..337c924 100644 --- a/src/Catesta/Resources/Module/src/PSModule.build.ps1 +++ b/src/Catesta/Resources/Module/src/PSModule.build.ps1 @@ -535,6 +535,17 @@ Add-BuildTask CreateMarkdownHelp -After CreateHelpStart { throw 'Missing GUID. Please review and rebuild.' } + Write-Build Gray ' Evaluating if running 7.4.0 or higher...' + # https://github.com/PowerShell/platyPS/issues/595 + if ($PSVersionTable.PSVersion -ge [version]'7.4.0') { + Write-Build Gray ' Performing Markdown repair' + # dot source markdown repair + . $BuildRoot\MarkdownRepair.ps1 + $OutputDir | Get-ChildItem -File | ForEach-Object { + Repair-PlatyPSMarkdown -Path $_.FullName + } + } + Write-Build Gray ' Checking for missing documentation in md files...' $MissingDocumentation = Select-String -Path "$script:ArtifactsPath\docs\*.md" -Pattern "({{.*}})" if ($MissingDocumentation.Count -gt 0) { diff --git a/src/Catesta/Resources/Vault/plasterManifest.xml b/src/Catesta/Resources/Vault/plasterManifest.xml index dcce753..1529879 100644 --- a/src/Catesta/Resources/Vault/plasterManifest.xml +++ b/src/Catesta/Resources/Vault/plasterManifest.xml @@ -6,7 +6,7 @@ Catesta d531e058-52b8-4dd2-8162-01c95d1eb8f7 - 2.0.2 + 2.2.0 Catesta Scaffolds a new PowerShell SecretManagement extension vault module project Jake Morrison diff --git a/src/MarkdownRepair.ps1 b/src/MarkdownRepair.ps1 new file mode 100644 index 0000000..aa011ec --- /dev/null +++ b/src/MarkdownRepair.ps1 @@ -0,0 +1,135 @@ +<# +.SYNOPSIS + Repair PlatyPS generated markdown files. +.NOTES + This file is temporarily required to handle platyPS help generation. + https://github.com/PowerShell/platyPS/issues/595 + This is a result of a breaking change introduced in PowerShell 7.4.0: + https://learn.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-74?view=powershell-7.4 + Breaking Changes: Added the ProgressAction parameter to the Common Parameters + modified from source: https://github.com/PowerShell/platyPS/issues/595#issuecomment-1820971702 +#> + +function Remove-CommonParameterFromMarkdown { + <# + .SYNOPSIS + Remove a PlatyPS generated parameter block. + .DESCRIPTION + Removes parameter block for the provided parameter name from the markdown file provided. + #> + param( + [Parameter(Mandatory)] + [string[]] + $Path, + + [Parameter(Mandatory = $false)] + [string[]] + $ParameterName = @('ProgressAction') + ) + $ErrorActionPreference = 'Stop' + foreach ($p in $Path) { + $content = (Get-Content -Path $p -Raw).TrimEnd() + $updateFile = $false + foreach ($param in $ParameterName) { + if (-not ($Param.StartsWith('-'))) { + $param = "-$($param)" + } + # Remove the parameter block + $pattern = "(?m)^### $param\r?\n[\S\s]*?(?=#{2,3}?)" + $newContent = $content -replace $pattern, '' + # Remove the parameter from the syntax block + $pattern = " \[$param\s?.*?]" + $newContent = $newContent -replace $pattern, '' + if ($null -ne (Compare-Object -ReferenceObject $content -DifferenceObject $newContent)) { + Write-Verbose "Added $param to $p" + # Update file content + $content = $newContent + $updateFile = $true + } + } + # Save file if content has changed + if ($updateFile) { + $newContent | Out-File -Encoding utf8 -FilePath $p + Write-Verbose "Updated file: $p" + } + } + return +} + +function Add-MissingCommonParameterToMarkdown { + param( + [Parameter(Mandatory)] + [string[]] + $Path, + + [Parameter(Mandatory = $false)] + [string[]] + $ParameterName = @('ProgressAction') + ) + $ErrorActionPreference = 'Stop' + foreach ($p in $Path) { + $content = (Get-Content -Path $p -Raw).TrimEnd() + $updateFile = $false + foreach ($NewParameter in $ParameterName) { + if (-not ($NewParameter.StartsWith('-'))) { + $NewParameter = "-$($NewParameter)" + } + $pattern = '(?m)^This cmdlet supports the common parameters:(.+?)\.' + $replacement = { + $Params = $_.Groups[1].Captures[0].ToString() -split ' ' + $CommonParameters = @() + foreach ($CommonParameter in $Params) { + if ($CommonParameter.StartsWith('-')) { + if ($CommonParameter.EndsWith(',')) { + $CleanParam = $CommonParameter.Substring(0, $CommonParameter.Length - 1) + } + elseif ($p.EndsWith('.')) { + $CleanParam = $CommonParameter.Substring(0, $CommonParameter.Length - 1) + } + else { + $CleanParam = $CommonParameter + } + $CommonParameters += $CleanParam + } + } + if ($NewParameter -notin $CommonParameters) { + $CommonParameters += $NewParameter + } + $CommonParameters[-1] = "and $($CommonParameters[-1]). " + return "This cmdlet supports the common parameters: " + (($CommonParameters | Sort-Object) -join ', ') + } + $newContent = $content -replace $pattern, $replacement + if ($null -ne (Compare-Object -ReferenceObject $content -DifferenceObject $newContent)) { + Write-Verbose "Added $NewParameter to $p" + $updateFile = $true + $content = $newContent + } + } + # Save file if content has changed + if ($updateFile) { + $newContent | Out-File -Encoding utf8 -FilePath $p + Write-Verbose "Updated file: $p" + } + } + return +} + +function Repair-PlatyPSMarkdown { + param( + [Parameter(Mandatory)] + [string[]] + $Path, + + [Parameter()] + [string[]] + $ParameterName = @('ProgressAction') + ) + $ErrorActionPreference = 'Stop' + $Parameters = @{ + Path = $Path + ParameterName = $ParameterName + } + $null = Remove-CommonParameterFromMarkdown @Parameters + $null = Add-MissingCommonParameterToMarkdown @Parameters + return +} diff --git a/src/Tests/Integration/FileChecks.Tests.ps1 b/src/Tests/Integration/FileChecks.Tests.ps1 index f6f8561..e8d4066 100644 --- a/src/Tests/Integration/FileChecks.Tests.ps1 +++ b/src/Tests/Integration/FileChecks.Tests.ps1 @@ -58,6 +58,10 @@ Describe 'File Checks' { $srcFiles.Name.Contains('PSModule.Settings.ps1') | Should -BeExactly $true } #it + It 'should have markdown repair file' { + $srcFiles.Name.Contains('MarkdownRepair.ps1') | Should -BeExactly $true + } #it + It 'should have a PSScriptAnalyzerSettings file' { $srcFiles.Name.Contains('PSScriptAnalyzerSettings.psd1') | Should -BeExactly $true } #it diff --git a/src/Tests/Integration/New-ModuleProject.Tests.ps1 b/src/Tests/Integration/New-ModuleProject.Tests.ps1 index 7d66fd1..4e27e9f 100644 --- a/src/Tests/Integration/New-ModuleProject.Tests.ps1 +++ b/src/Tests/Integration/New-ModuleProject.Tests.ps1 @@ -70,6 +70,7 @@ Describe 'Module Integration Tests' { $moduleOnlyFiles.Name.Contains('Imports.ps1') | Should -BeExactly $true $moduleOnlyFiles.Name.Contains('modulename.build.ps1') | Should -BeExactly $true $moduleOnlyFiles.Name.Contains('modulename.Settings.ps1') | Should -BeExactly $true + $moduleOnlyFiles.Name.Contains('MarkdownRepair.ps1') | Should -BeExactly $true $moduleOnlyFiles.Name.Contains('PSScriptAnalyzerSettings.psd1') | Should -BeExactly $true $moduleOnlyFiles.Name.Contains('Get-HelloWorld.ps1') | Should -BeExactly $true $moduleOnlyFiles.Name.Contains('Get-Day.ps1') | Should -BeExactly $true @@ -139,6 +140,31 @@ Describe 'Module Integration Tests' { } #it + It 'should generate a module only scaffold with base elements with no MarkdownRepair if help is not selected' { + $moduleParameters = @{ + VAULT = 'text' + ModuleName = 'modulename' + Description = 'text' + Version = '0.0.1' + FN = 'user full name' + CICD = 'NONE' + RepoType = 'NONE' + CodingStyle = 'Stroustrup' + Help = 'No' + Pester = '5' + S3Bucket = 'PSGallery' + PassThru = $true + NoLogo = $true + } + $eval = New-ModuleProject -ModuleParameters $moduleParameters -DestinationPath $outPutPath + $eval | Should -Not -BeNullOrEmpty + + $moduleOnlyFiles = Get-ChildItem -Path $outPutPathStar -Recurse -Force + + $moduleOnlyFiles.Name.Contains('MarkdownRepair.ps1') | Should -BeExactly $false + + } #it + } #context_module_only Context 'AWS-CodeBuild' {