Fix Build-PSBuildMarkdown + Lint Fixes

.vscode/launch.json

@@ -4,11 +4,35 @@
     // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
     "version": "0.2.0",
     "configurations": [
+        {
+            "name": "Run Build and Debug (Temp Console)",
+            "type": "PowerShell",
+            "request": "launch",
+            "script": "${cwd}/build.ps1",
+            "args": [
+                "-Task Test",
+                "-Verbose"
+            ],
+            "cwd": "${workspaceFolder}",
+            "createTemporaryIntegratedConsole": true
+        },
+        {
+            "name": "Run Build and Debug",
+            "type": "PowerShell",
+            "request": "launch",
+            "script": "${cwd}/build.ps1",
+            "args": [
+                "-Task Test",
+                "-Verbose"
+            ],
+            "cwd": "${workspaceFolder}",
+            "createTemporaryIntegratedConsole": true
+        },
         {
             "name": "PowerShell: Interactive Session",
             "type": "PowerShell",
             "request": "launch",
             "cwd": ""
         }
     ]
-}
+}

.vscode/settings.json

@@ -7,6 +7,7 @@
     "powershell.codeFormatting.useCorrectCasing": true,
     "powershell.codeFormatting.newLineAfterOpenBrace": true,
     "powershell.codeFormatting.alignPropertyValuePairs": true,
+    "powershell.scriptAnalysis.settingsPath": "tests/ScriptAnalyzerSettings.psd1",
     "search.useIgnoreFiles": true,
     "search.exclude": {
         "**/node_modules": true,

.vscode/tasks.json

@@ -6,7 +6,7 @@
     "windows": {
         "options": {
             "shell": {
-                "executable": "powershell.exe",
+                "executable": "pwsh.exe",
                 "args": [
                     "-NoProfile",
                     "-ExecutionPolicy",

CHANGELOG.md

@@ -7,10 +7,18 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+### Added
+
 - Add new dependencies variables to allow end user to modify which tasks are
   run.
 - Add localization support.
 
+### Fixed
+
+- Remove extra item from `New-MarkdownHelp` splat that would result in a failure
+  when using `$PSBPreference.Docs.Overwrite = $true`
+- Clean up some failing Script Analyzer settings, including moving the file.
+
 ## [0.7.2] 2025-05-21
 
 ### Added

PowerShellBuild/Public/Publish-PSBuildModule.ps1

@@ -27,6 +27,12 @@ function Publish-PSBuildModule {
 
         Publish version 0.1.0 of the module at path .\Output\0.1.0\MyModule to the PSGallery repository using an API key and a PowerShell credential.
     #>
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSReviewUnusedParameter',
+        '',
+        Justification = 'Both Credential and NuGetApiKey are used just not via explicit variable call.'
+    )]
+    [CmdletBinding(DefaultParameterSetName = 'ApiKey')]
     [CmdletBinding(DefaultParameterSetName = 'ApiKey')]
     param(
         [parameter(Mandatory)]

PowerShellBuild/Public/Test-PSBuildPester.ps1

@@ -36,6 +36,11 @@ function Test-PSBuildPester {
         Run Pester tests in ./tests and save results to ./out/testResults.xml
     #>
     [CmdletBinding()]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSReviewUnusedParameter',
+        'CodeCoverageThreshold',
+        Justification = 'Used inside a foreach method call.'
+    )]
     param(
         [parameter(Mandatory)]
         [string]$Path,

README.md

@@ -25,9 +25,11 @@ Install-Module -Name psake -RequiredVersion 4.8.0 -Repository PSGallery
 > [how to dot source tasks using PowerShell aliases](https://github.com/nightroman/Invoke-Build/blob/master/Tasks/Import/README.md#example-2-import-from-a-module-with-tasks)
 > example.
 
+<!-- markdownlint-disable no-inline-html -->
 <p align="center">
     <img src="media/psaketaskmodule-256x256.png" alt="Logo">
 </p>
+<!-- markdownlint-enable no-inline-html -->
 
 ## Status - Work in progress
 
@@ -209,3 +211,5 @@ $PSBPreference.Test.CodeCoverage.Enabled  = $false
 [psgallery]: https://www.powershellgallery.com/packages/PowerShellBuild
 [license-badge]: https://img.shields.io/github/license/psake/PowerShellBuild.svg
 [license]: https://raw.githubusercontent.com/psake/PowerShellBuild/main/LICENSE
+
+<!-- spell-checker:ignore PSGALLERY psaketaskmodule -->

cspell.json

@@ -11,7 +11,9 @@
     ],
     "words": [],
     "ignoreWords": [
+        "BHPS",
         "psake",
+        "pscredential",
         "MAML"
     ],
     "import": []

psakeFile.ps1

@@ -1,24 +1,24 @@
-properties {
+Properties {
     $settings = . ([IO.Path]::Combine($PSScriptRoot, 'build.settings.ps1'))
     if ($galleryApiKey) {
         $settings.PSGalleryApiKey = $galleryApiKey.GetNetworkCredential().password
     }
 }
 
-task default -depends Test
+Task default -depends Test
 
-task Init {
+Task Init {
     "STATUS: Testing with PowerShell $($settings.PSVersion)"
     'Build System Details:'
     Get-Item ENV:BH*
 } -description 'Initialize build environment'
 
-task Test -Depends Init, Analyze, Pester -description 'Run test suite'
+Task Test -depends Init, Analyze, Pester -description 'Run test suite'
 
-task Analyze -depends Build {
-    $analysis = Invoke-ScriptAnalyzer -Path $settings.ModuleOutDir -Recurse -Verbose:$false -Settings ([IO.Path]::Combine($env:BHModulePath, 'ScriptAnalyzerSettings.psd1'))
-    $errors   = $analysis | Where-Object {$_.Severity -eq 'Error'}
-    $warnings = $analysis | Where-Object {$_.Severity -eq 'Warning'}
+Task Analyze -depends Build {
+    $analysis = Invoke-ScriptAnalyzer -Path $settings.ModuleOutDir -Recurse -Verbose:$false -Settings './tests/ScriptAnalyzerSettings.psd1'
+    $errors = $analysis | Where-Object { $_.Severity -eq 'Error' }
+    $warnings = $analysis | Where-Object { $_.Severity -eq 'Warning' }
     if (@($errors).Count -gt 0) {
         Write-Error -Message 'One or more Script Analyzer errors were found. Build cannot continue!'
         $errors | Format-Table -AutoSize
@@ -30,25 +30,25 @@ task Analyze -depends Build {
     }
 } -description 'Run PSScriptAnalyzer'
 
-task Pester -depends Build {
+Task Pester -depends Build {
     Remove-Module $settings.ProjectName -ErrorAction SilentlyContinue -Verbose:$false
 
     $testResultsXml = [IO.Path]::Combine($settings.OutputDir, 'testResults.xml')
-    $testResults    = Invoke-Pester -Path $settings.Tests -Output Detailed -PassThru
+    $testResults = Invoke-Pester -Path $settings.Tests -Output Detailed -PassThru
 
     if ($testResults.FailedCount -gt 0) {
         $testResults | Format-List
         Write-Error -Message 'One or more Pester tests failed. Build cannot continue!'
     }
 } -description 'Run Pester tests'
 
-task Clean -depends Init {
+Task Clean -depends Init {
     if (Test-Path -Path $settings.ModuleOutDir) {
         Remove-Item -Path $settings.ModuleOutDir -Recurse -Force -Verbose:$false
     }
 }
 
-task Build -depends Init, Clean {
+Task Build -depends Init, Clean {
     New-Item -Path $settings.ModuleOutDir -ItemType Directory -Force > $null
     Copy-Item -Path "$($settings.SUT)/*" -Destination $settings.ModuleOutDir -Recurse
 
@@ -59,7 +59,7 @@ task Build -depends Init, Clean {
     # & .\Build\Convert-PSAke.ps1 $psakePath | Out-File -Encoding UTF8 $ibPath
 }
 
-task Publish -depends Test {
+Task Publish -depends Test {
     "    Publishing version [$($settings.Manifest.ModuleVersion)] to PSGallery..."
     if ($settings.PSGalleryApiKey) {
         Publish-Module -Path $settings.ModuleOutDir -NuGetApiKey $settings.PSGalleryApiKey

requirements.psd1

@@ -4,7 +4,7 @@
     }
     BuildHelpers     = '2.0.16'
     Pester           = @{
-        MinimumVersion = '5.6.1'
+        MinimumVersion = '5.7.1'
         Parameters     = @{
             SkipPublisherCheck = $true
         }

tests/Help.tests.ps1

@@ -1,17 +1,17 @@
 # Taken with love from @juneb_get_help (https://raw.githubusercontent.com/juneb/PesterTDD/master/Module.Help.Tests.ps1)
 
 BeforeDiscovery {
+
     function global:FilterOutCommonParams {
         param ($Params)
-        $commonParams = [System.Management.Automation.PSCmdlet]::OptionalCommonParameters +
-            [System.Management.Automation.PSCmdlet]::CommonParameters
-        $params | Where-Object { $_.Name -notin $commonParams } | Sort-Object -Property Name -Unique
+        $commonParameters = [System.Management.Automation.PSCmdlet]::CommonParameters + [System.Management.Automation.PSCmdlet]::OptionalCommonParameters
+        $params | Where-Object { $_.Name -notin $commonParameters } | Sort-Object -Property Name -Unique
     }
 
-    $manifest             = Import-PowerShellDataFile -Path $env:BHPSModuleManifest
-    $outputDir            = Join-Path -Path $env:BHProjectPath -ChildPath 'Output'
-    $outputModDir         = Join-Path -Path $outputDir -ChildPath $env:BHProjectName
-    $outputModVerDir      = Join-Path -Path $outputModDir -ChildPath $manifest.ModuleVersion
+    $manifest = Import-PowerShellDataFile -Path $env:BHPSModuleManifest
+    $outputDir = Join-Path -Path $env:BHProjectPath -ChildPath 'Output'
+    $outputModDir = Join-Path -Path $outputDir -ChildPath $env:BHProjectName
+    $outputModVerDir = Join-Path -Path $outputModDir -ChildPath $manifest.ModuleVersion
     $outputModVerManifest = Join-Path -Path $outputModVerDir -ChildPath "$($env:BHProjectName).psd1"
 
     # Get module commands
@@ -25,36 +25,32 @@ BeforeDiscovery {
     if ($PSVersionTable.PSVersion.Major -lt 6) {
         $params.CommandType[0] += 'Workflow'
     }
-    $commands = Get-Command @params
+    $script:commands = Get-Command @params
 
     ## When testing help, remember that help is cached at the beginning of each session.
     ## To test, restart session.
 }
 
-AfterAll {
-    Remove-Item Function:/FilterOutCommonParams
-}
-
 Describe "Test help for <_.Name>" -ForEach $commands {
 
     BeforeDiscovery {
         # Get command help, parameters, and links
-        $command               = $_
-        $commandHelp           = Get-Help $command.Name -ErrorAction SilentlyContinue
-        $commandParameters     = global:FilterOutCommonParams -Params $command.ParameterSets.Parameters
-        $commandParameterNames = $commandParameters.Name
-        $helpLinks             = $commandHelp.relatedLinks.navigationLink.uri
+        $command = $_
+        $commandHelp = Get-Help $command.Name -ErrorAction SilentlyContinue
+        $commandParameters = global:FilterOutCommonParams -Params $command.ParameterSets.Parameters
+        $script:commandParameterNames = $commandParameters.Name
+        $script:helpLinks = $commandHelp.relatedLinks.navigationLink.uri
     }
 
     BeforeAll {
         # These vars are needed in both discovery and test phases so we need to duplicate them here
-        $command                = $_
-        $commandName            = $_.Name
-        $commandHelp            = Get-Help $command.Name -ErrorAction SilentlyContinue
-        $commandParameters      = global:FilterOutCommonParams -Params $command.ParameterSets.Parameters
-        $commandParameterNames  = $commandParameters.Name
-        $helpParameters         = global:FilterOutCommonParams -Params $commandHelp.Parameters.Parameter
-        $helpParameterNames     = $helpParameters.Name
+        $command = $_
+        $script:commandName = $_.Name
+        $commandHelp = Get-Help $command.Name -ErrorAction SilentlyContinue
+        $commandParameters = global:FilterOutCommonParams -Params $command.ParameterSets.Parameters
+        $script:commandParameterNames = $commandParameters.Name
+        $helpParameters = global:FilterOutCommonParams -Params $commandHelp.Parameters.Parameter
+        $script:helpParameterNames = $helpParameters.Name
     }
 
     # If help is not found, synopsis in auto-generated help is the syntax diagram
@@ -81,13 +77,13 @@ Describe "Test help for <_.Name>" -ForEach $commands {
         (Invoke-WebRequest -Uri $_ -UseBasicParsing).StatusCode | Should -Be '200'
     }
 
-    Context "Parameter <_.Name>" -Foreach $commandParameters {
+    Context "Parameter <_.Name>" -ForEach $commandParameters {
 
         BeforeAll {
-            $parameter         = $_
-            $parameterName     = $parameter.Name
-            $parameterHelp     = $commandHelp.parameters.parameter | Where-Object Name -eq $parameterName
-            $parameterHelpType = if ($parameterHelp.ParameterValue) { $parameterHelp.ParameterValue.Trim() }
+            $parameter = $_
+            $parameterName = $parameter.Name
+            $parameterHelp = $commandHelp.parameters.parameter | Where-Object Name -EQ $parameterName
+            $script:parameterHelpType = if ($parameterHelp.ParameterValue) { $parameterHelp.ParameterValue.Trim() }
         }
 
         # Should be a description for every parameter
@@ -107,7 +103,7 @@ Describe "Test help for <_.Name>" -ForEach $commands {
         }
     }
 
-    Context "Test <_> help parameter help for <commandName>" -Foreach $helpParameterNames {
+    Context "Test <_> help parameter help for <commandName>" -ForEach $helpParameterNames {
 
         # Shouldn't find extra parameters in help.
         It "finds help parameter in code: <_>" {

tests/Manifest.tests.ps1

@@ -1,22 +1,23 @@
 BeforeAll {
+    Set-Location "$PSScriptRoot/.."
     Set-BuildEnvironment -Force
-    $moduleName         = $env:BHProjectName
-    $manifest           = Import-PowerShellDataFile -Path $env:BHPSModuleManifest
-    $outputDir          = Join-Path -Path $ENV:BHProjectPath -ChildPath 'Output'
-    $outputModDir       = Join-Path -Path $outputDir -ChildPath $env:BHProjectName
-    $outputModVerDir    = Join-Path -Path $outputModDir -ChildPath $manifest.ModuleVersion
+    $moduleName = $env:BHProjectName
+    $manifest = Import-PowerShellDataFile -Path $env:BHPSModuleManifest
+    $outputDir = Join-Path -Path $ENV:BHProjectPath -ChildPath 'Output'
+    $outputModDir = Join-Path -Path $outputDir -ChildPath $env:BHProjectName
+    $outputModVerDir = Join-Path -Path $outputModDir -ChildPath $manifest.ModuleVersion
     $outputManifestPath = Join-Path -Path $outputModVerDir -Child "$($moduleName).psd1"
-    $manifestData       = Test-ModuleManifest -Path $outputManifestPath -Verbose:$false -ErrorAction Stop -WarningAction SilentlyContinue
+    $manifestData = Test-ModuleManifest -Path $outputManifestPath -Verbose:$false -ErrorAction Stop -WarningAction SilentlyContinue
 
-    $changelogPath    = Join-Path -Path $env:BHProjectPath -Child 'CHANGELOG.md'
+    $changelogPath = Join-Path -Path $env:BHProjectPath -Child 'CHANGELOG.md'
     $changelogVersion = Get-Content $changelogPath | ForEach-Object {
         if ($_ -match "^##\s\[(?<Version>(\d+\.){1,3}\d+)\]") {
             $changelogVersion = $matches.Version
             break
         }
     }
 
-    $script:manifest    = $null
+    $script:manifest = $null
 }
 Describe 'Module manifest' {
 
@@ -47,15 +48,15 @@ Describe 'Module manifest' {
         }
 
         It 'Has a valid guid' {
-            {[guid]::Parse($manifestData.Guid)} | Should -Not -Throw
+            { [guid]::Parse($manifestData.Guid) } | Should -Not -Throw
         }
 
         It 'Has a valid copyright' {
             $manifestData.CopyRight | Should -Not -BeNullOrEmpty
         }
 
         It 'Has a valid version in the changelog' {
-            $changelogVersion               | Should -Not -BeNullOrEmpty
+            $changelogVersion | Should -Not -BeNullOrEmpty
             $changelogVersion -as [Version] | Should -Not -BeNullOrEmpty
         }
 
@@ -76,7 +77,7 @@ Describe 'Git tagging' -Skip {
     }
 
     It 'Is tagged with a valid version' {
-        $gitTagVersion               | Should -Not -BeNullOrEmpty
+        $gitTagVersion | Should -Not -BeNullOrEmpty
         $gitTagVersion -as [Version] | Should -Not -BeNullOrEmpty
     }