refactor: complete overhaul of PlatyPS Markdown generation.

shoddyguard · shoddyguard · commit c830c46e4dd2 · 2024-04-13T03:44:04.000+01:00
Make use of Get/Set/Format Brownserve content to drastically speed up documentation generation.
Some de-duping may still be beneficial for m0ar gains.
diff --git a/Module/Private/PowerShell/platyPS/Update-PlatyPSModulePageDescription.ps1 b/Module/Private/PowerShell/platyPS/Update-PlatyPSModulePageDescription.ps1
@@ -28,39 +28,30 @@ function Update-PlatyPSModulePageDescription
             Position = 1
         )]
         [ValidateNotNullOrEmpty()]
-        [string]
-        $ModulePagePath
+        [BrownserveContent]
+        $ModulePageContent
     )
     begin
     {
     }
     process
     {
-        $ModulePageContent = Get-Content $ModulePagePath -ErrorAction 'Stop' -Raw
-        if (!$ModulePageContent)
-        {
-            throw 'Module page content is empty'
-        }
-        if ($ModulePageContent -imatch '## Description[\s\n]*{{ Fill in the Description }}')
+        $ModulePageContentString = $ModulePageContent.ToString()
+
+        # We don't yet support automatically updating the module description in the module page.
+        # only setting it if it's not already set.
+        if ($ModulePageContentString -imatch '## Description[\s\n]*{{ Fill in the Description }}')
         {
             # .Replace method doesn't work 🤷‍♀️ so use the -replace param instead.
-            $NewModulePageContent = $ModulePageContent -Replace '## Description[\s\n]*{{ Fill in the Description }}', "## Description`r`n$ModuleDescription"
-            try
-            {
-                Set-Content `
-                    -Path $ModulePagePath `
-                    -Value $NewModulePageContent `
-                    -NoNewline `
-                    -ErrorAction 'Stop'
-            }
-            catch
-            {
-                throw "Failed to update module page description.`n$($_.Exception.Message)"
-            }
+            $NewModulePageContent = $ModulePageContentString -Replace '## Description[\s\n]*{{ Fill in the Description }}', "## Description`n`n$ModuleDescription"
+            $ModulePageContent.Content = $NewModulePageContent | Format-BrownserveContent | Select-Object -ExpandProperty Content
+
+            return $ModulePageContent
         }
         else
         {
             Write-Verbose 'Module page description already set'
+            return $ModulePageContent
         }
     }
     end
diff --git a/Module/Private/PowerShell/platyPS/Update-PlatyPSModulePageGUID.ps1 b/Module/Private/PowerShell/platyPS/Update-PlatyPSModulePageGUID.ps1
@@ -28,34 +28,21 @@ function Update-PlatyPSModulePageGUID
             Position = 1
         )]
         [ValidateNotNullOrEmpty()]
-        [string]
-        $ModulePagePath
+        [BrownserveContent]
+        $ModulePageContent
     )
     begin
     {
     }
     process
     {
-        $ModulePageContent = Get-Content $ModulePagePath -ErrorAction 'Stop' -Raw
-        if (!$ModulePageContent)
-        {
-            throw 'Module page content is empty'
-        }
+        $ModulePageContentString = $ModulePageContent.ToString()
         $NewModuleGUID = $ModuleGUID.ToString()
-        $NewModulePageContent = $ModulePageContent -replace 'Module Guid: ([\w|\d|-]*)', "Module Guid: $NewModuleGUID"
+        $NewModulePageContent = $ModulePageContentString -replace 'Module Guid: ([\w|\d|-]*)', "Module Guid: $NewModuleGUID"
 
-        try
-        {
-            Set-Content `
-                -Path $ModulePagePath `
-                -Value $NewModulePageContent `
-                -NoNewline `
-                -ErrorAction 'Stop'
-        }
-        catch
-        {
-            throw "Failed to update module page GUID.`n$($_.Exception.Message)"
-        }
+        $ModulePageContent.Content = $NewModulePageContent | Format-BrownserveContent | Select-Object -ExpandProperty Content
+
+        return $ModulePageContent
     }
     end
     {
diff --git a/Module/Private/PowerShell/platyPS/Update-PlatyPSModulePageLinks.ps1 b/Module/Private/PowerShell/platyPS/Update-PlatyPSModulePageLinks.ps1
@@ -22,41 +22,38 @@ function Update-PlatyPSModulePageLinks
         [string]
         $CmdletDocumentationPath,
 
-        # The path to the module page
+        # The content of the module page
         [Parameter(
             Mandatory = $true,
             ValueFromPipelineByPropertyName = $true,
             Position = 1
         )]
         [ValidateNotNullOrEmpty()]
-        [string]
-        $ModulePagePath
+        [BrownserveContent]
+        $ModulePageContent
     )
     begin
     {
     }
     process
     {
-        $ModulePageContent = Get-Content $ModulePagePath -ErrorAction 'Stop' -Raw
-        if (!$ModulePageContent)
-        {
-            throw 'Module page content is empty'
-        }
+        $ModulePageContentString = $ModulePageContent.ToString()
+        <#
+            As it stands we expect the module page path to be one level above the cmdlet documentation path.
+            e.g:
+                | ModulePage.md
+                | CmdletDocumentation
+                    | Cmdlet1.md
+                    | Cmdlet2.md
+                    | Cmdlet3.md
+            We may want to change this assumption in the future.
+        #>
         $ModulePageAdjustment = Split-Path $CmdletDocumentationPath -Leaf
-        $NewModulePageContent = $ModulePageContent -replace '\(([\w|\d]*-[\w|\d]*.md)\)', "(./$ModulePageAdjustment/`$1)"
+        $NewModulePageContent = $ModulePageContentString -replace '\(([\w|\d]*-[\w|\d]*.md)\)', "(./$ModulePageAdjustment/`$1)"
+
+        $ModulePageContent.Content = $NewModulePageContent | Format-BrownserveContent | Select-Object -ExpandProperty Content
 
-        try
-        {
-            Set-Content `
-                -Path $ModulePagePath `
-                -Value $NewModulePageContent `
-                -NoNewline `
-                -ErrorAction 'Stop'
-        }
-        catch
-        {
-            throw "Failed to update module page links.`n$($_.Exception.Message)"
-        }
+        return $ModulePageContent
     }
     end
     {
diff --git a/Module/Public/Build/New-BrownservePowerShellModuleBuild.ps1 b/Module/Public/Build/New-BrownservePowerShellModuleBuild.ps1
@@ -23,7 +23,6 @@ function New-BrownservePowerShellModuleBuild
         [string]
         $RepoName
     )
-    
     begin
     {
         try
@@ -45,7 +44,6 @@ function New-BrownservePowerShellModuleBuild
             throw "Cannot determine RepoName automatically."
         }
     }
-    
     process
     {
         switch ($CICDProvider)
@@ -56,15 +54,9 @@ function New-BrownservePowerShellModuleBuild
                 $WorkflowDirectory = Join-Path $GitHubDirectory 'workflows'
                 $BuildWorkflowPath = Join-Path $WorkflowDirectory 'build.yaml'
                 $ReleaseWorkflowPath = Join-Path $WorkflowDirectory 'release.yaml'
+                $FilesToCheck = @( $BuildWorkflowPath, $ReleaseWorkflowPath)
 
-                if ((Test-Path $BuildWorkflowPath))
-                {
-                    throw "Build workflow already exists at '$BuildWorkflowPath'"
-                }
-                if ((Test-Path $ReleaseWorkflowPath))
-                {
-                    throw "Build workflow already exists at '$ReleaseWorkflowPath'"
-                }
+                $FilesToCheck | Assert-PathDoesNotExist
 
                 # These steps are always needed regardless of the build
                 $DefaultSteps = @(
@@ -77,51 +69,81 @@ function New-BrownservePowerShellModuleBuild
                     }
                 )
 
+                # This command is used to run the module build script, we build up the params separately and splat them in
+                $RunCommand = "./$($ModuleInfo.Name)/.build/build.ps1 @Params"
+
+                # Params for building/testing the module
+                $BuildTestParams = @"
+`$Params = @{
+    BranchName = `$env:GITHUB_REF
+    GitHubRepoName = '$RepoName'
+    Build = 'BuildTestAndCheck'
+    Verbose = `$true
+}
+"@
                 # Steps for building and testing the module
-                $BuildRunCommand = @"
-./$($ModuleInfo.Name)/.build/build.ps1 ``
--GitHubRepoName '$RepoName' ``
--BranchName `$env:GITHUB_REF ``
--Build BuildPackTest ``
--Verbose
+                $StageReleaseParams = @"
+`$Params = @{
+    BranchName = `$env:GITHUB_REF
+    GitHubRepoName = '$RepoName'
+    Build = 'StageRelease'
+    GitHubStageReleaseToken = `$env:GitHubPAT
+    ReleaseType = '`${{inputs.release_type}}'
+    UseWorkingCopy = `$true
+    Verbose = `$true
+    }
+    if (`$env:ReleaseNotice)
+    {
+        `$Params.Add('ReleaseNotice', `$env:ReleaseNotice)
+    }
+"@
+            $ReleaseParams = @"
+`$Params = @{
+    BranchName = `$env:GITHUB_REF
+    GitHubRepoName = '$RepoName'
+    Build = 'Release'
+    GitHubReleaseToken = `$env:GitHubPAT
+    NugetFeedAPIKey = `$env:NugetFeedAPIKey
+    PSGalleryAPIKey = `$env:PSGalleryAPIKey
+    PublishTo = `${{ inputs.publish_to }}
+    Verbose = `$true
+}
 "@
                 $BuildSteps = $DefaultSteps
                 $BuildSteps += [ordered]@{
-                    name  = 'build-and-test-module'
+                    name  = 'run-build-script'
                     shell = 'pwsh'
-                    run   = $BuildRunCommand
+                    run   = $BuildTestParams + "`n" + $RunCommand
                 }
 
                 $BuildJobs = @{
-                    JobTitle = 'build-and-test'
+                    JobTitle = 'BuildTestAndCheck'
                     RunsOn   = 'ubuntu-latest'
                     Steps    = $BuildSteps
                 }
 
-                # Steps for releasing the module
-                $ReleaseRunCommand = @"
-./$($ModuleInfo.Name)/.build/build.ps1 ``
--GitHubRepoName '$RepoName' ``
--BranchName `$env:GITHUB_REF ``
--Build release ``
--NugetFeedAPIKey `$env:NugetFeedAPIKey ``
--PSGalleryAPIKey `$env:PSGalleryAPIKey ``
--Verbose
-"@
+                $StageReleaseSteps = $DefaultSteps
+                # We need to fetch the full history so that we can determine the changelog entries from the previous release
+                $StageReleaseSteps[0].with.Add('fetch-depth', 0)
+                $StageReleaseSteps += [ordered]@{
+                    name  = 'stage-release'
+                    shell = 'pwsh'
+                    run   = $StageReleaseParams + "`n" + $RunCommand
+                }
 
                 $ReleaseSteps = $DefaultSteps
                 $ReleaseSteps += [ordered]@{
                     name  = 'build-and-release-module'
                     shell = 'pwsh'
-                    run   = $ReleaseRunCommand
+                    run   = $ReleaseParams + "`n" + $RunCommand
                 }
-                
+
                 $ReleaseJobs = @{
                     JobTitle = 'release'
                     RunsOn   = 'ubuntu-latest'
                     Steps    = $ReleaseSteps
                 }
-                
+
                 try
                 {
                     $BuildWorkflowContent = New-GitHubActionsWorkflow `
@@ -132,6 +154,14 @@ function New-BrownservePowerShellModuleBuild
                     {
                         throw 'Workflow content empty.'
                     }
+                    $StageReleaseWorkflowContent = New-GitHubActionsWorkflow `
+                        -Name 'stage-release' `
+                        -ExecuteOn 'workflow_dispatch' `
+                        -Jobs $StageReleaseJobs
+                    if (!$StageReleaseWorkflowContent)
+                    {
+                        throw 'Workflow content empty'
+                    }
                     $ReleaseWorkflowContent = New-GitHubActionsWorkflow `
                         -Name 'release' `
                         -ExecuteOn 'workflow_dispatch' `
@@ -146,6 +176,7 @@ function New-BrownservePowerShellModuleBuild
                     throw "Failed to create GitHub Actions workflow.`n$($_.Exception.Message)"
                 }
                 Write-Verbose "Build workflow content:`n$BuildWorkflowContent"
+                Write-Verbose "Stage release workflow content:`n$StageReleaseWorkflowContent"
                 Write-Verbose "Release workflow content:`n$ReleaseWorkflowContent"
                 try
                 {
@@ -158,6 +189,7 @@ function New-BrownservePowerShellModuleBuild
                         New-Item $WorkflowDirectory -ItemType Directory -ErrorAction 'stop' | Out-Null
                     }
                     New-Item $BuildWorkflowPath -ItemType File -Value $BuildWorkflowContent -ErrorAction 'Stop' | Out-Null
+                    New-Item $StageReleaseWorkflowPath -ItemType File -Value $StageReleaseWorkflowContent -ErrorAction 'Stop' | Out-Null
                     New-Item $ReleaseWorkflowPath -ItemType File -Value $ReleaseWorkflowContent -ErrorAction 'Stop' | Out-Null
                 }
                 catch
@@ -171,9 +203,7 @@ function New-BrownservePowerShellModuleBuild
             }
         }
     }
-    
     end
     {
-       
     }
-}
+}
diff --git a/Module/Public/Markdown/Format-Markdown.ps1 b/Module/Public/Markdown/Format-Markdown.ps1
@@ -6,11 +6,14 @@
 #>
 function Format-Markdown
 {
-    [CmdletBinding()]
+    [CmdletBinding(
+        DefaultParameterSetName = 'Path'
+    )]
     param
     (
         # The path to the markdown file to format.
         [Parameter(
+            ParameterSetName = 'Path',
             Mandatory = $true,
             ValueFromPipelineByPropertyName = $true,
             Position = 0
@@ -39,12 +42,12 @@ function Format-Markdown
 
         # Special hidden parameter to pass in markdown from the pipeline.
         [Parameter(
+            ParameterSetName = 'Pipeline',
             Mandatory = $false,
             ValueFromPipeline = $true,
             ValueFromPipelineByPropertyName = $true,
             DontShow
         )]
-        [ValidateNotNullOrEmpty()]
         [array]
         $Markdown
     )
diff --git a/Module/Public/PowerShell/PlatyPS/Build-ModuleDocumentation.ps1 b/Module/Public/PowerShell/PlatyPS/Build-ModuleDocumentation.ps1
