🔄 [Maintenance]: Sync main into push release work

Co-authored-by: Copilot App <[email protected]>

Author: MariusStorhaug

.github/actions/Test-PSModule/action.yml

@@ -283,6 +283,7 @@ runs:
       id: test
       env:
         LocalTestPath: ${{ steps.paths.outputs.LocalTestPath }}
+        PSMODULE_TEST_PSMODULE_MODULE_NAME: ${{ steps.paths.outputs.ModuleName }}
         WorkingDirectory: ${{ inputs.WorkingDirectory }}
       with:
         Debug: ${{ inputs.Debug }}

.github/actions/Test-PSModule/src/tests/SourceCode/PSModule/PSModule.Container.ps1

@@ -1,7 +1,8 @@
 @{
     Path = Get-ChildItem -Path $PSScriptRoot -Filter *.Tests.ps1 | Select-Object -ExpandProperty FullName
     Data = @{
-        Path      = $env:PSMODULE_INVOKE_PESTER_INPUT_Run_Path
-        TestsPath = $env:LocalTestPath
+        ModuleName = $env:PSMODULE_TEST_PSMODULE_MODULE_NAME
+        Path       = $env:PSMODULE_INVOKE_PESTER_INPUT_Run_Path
+        TestsPath  = $env:LocalTestPath
     }
 }

.github/actions/Test-PSModule/src/tests/SourceCode/PSModule/PSModule.Tests.ps1

@@ -10,6 +10,10 @@
     'PSUseDeclaredVarsMoreThanAssignments', 'functionBearingFiles',
     Justification = 'Variables are used in the test.'
 )]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSUseDeclaredVarsMoreThanAssignments', 'publicHelpLinkTestCases',
+    Justification = 'Variable is used during Pester test discovery.'
+)]
 [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
     'PSAvoidUsingWriteHost', '',
     Justification = 'Logging to Github Actions.'
@@ -20,6 +24,10 @@
 )]
 [CmdLetBinding()]
 param(
+    # The name of the module.
+    [Parameter(Mandatory)]
+    [string] $ModuleName,
+
     # The path to the 'src' folder of the repo.
     [Parameter(Mandatory)]
     [string] $Path,
@@ -29,6 +37,37 @@ param(
     [string] $TestsPath
 )
 
+BeforeDiscovery {
+    $publicFunctionsPath = Join-Path -Path $Path -ChildPath 'functions/public'
+    $publicHelpLinkTestCases = if (Test-Path -Path $publicFunctionsPath) {
+        Get-ChildItem -Path $publicFunctionsPath -Filter '*.ps1' -Recurse -File |
+            Sort-Object -Property FullName |
+            ForEach-Object {
+                $ast = [System.Management.Automation.Language.Parser]::ParseFile($_.FullName, [ref]$null, [ref]$null)
+                $functionTokens = $ast.FindAll({ $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] }, $true)
+                if ($functionTokens.Count -eq 0) {
+                    return
+                }
+
+                $relativePath = [IO.Path]::GetRelativePath($publicFunctionsPath, $_.FullName)
+                $relativeDirectory = Split-Path -Path $relativePath -Parent
+                $documentationPath = if ($relativeDirectory) {
+                    '{0}/{1}' -f ($relativeDirectory -replace '[\\/]', '/'), $_.BaseName
+                } else {
+                    $_.BaseName
+                }
+
+                @{
+                    DocumentationPath = $documentationPath
+                    ExpectedLink      = "https://psmodule.io/$ModuleName/Functions/$documentationPath/"
+                    FilePath          = $_.FullName
+                }
+            }
+    } else {
+        @()
+    }
+}
+
 BeforeAll {
     $scriptFiles = Get-ChildItem -Path $Path -Include *.psm1, *.ps1 -Recurse -File
     Write-Host "::group:: - Script files     [$($scriptFiles.Count)]"
@@ -163,24 +202,6 @@ Describe 'PSModule - SourceCode tests' {
             $issues -join [Environment]::NewLine |
                 Should -BeNullOrEmpty -Because "the script should use '`$null = ...' instead of '... | Out-Null'"
         }
-        It 'Should not use ternary operations for compatibility reasons (ID: NoTernary)' -Skip {
-            $issues = @('')
-            $scriptFiles | ForEach-Object {
-                $filePath = $_.FullName
-                $relativePath = $filePath.Replace($Path, '').Trim('\').Trim('/')
-                $skipTest = Select-String -Path $filePath -Pattern '#SkipTest:NoTernary:(?<Reason>.+)' -AllMatches
-                if ($skipTest.Matches.Count -gt 0) {
-                    $skipReason = $skipTest.Matches.Groups | Where-Object { $_.Name -eq 'Reason' } | Select-Object -ExpandProperty Value
-                    Write-Host "::warning title=Skipping NoTernary test:: - $relativePath - $skipReason"
-                } else {
-                    Select-String -Path $filePath -Pattern '(?<!\|)\s+\?\s' -AllMatches | ForEach-Object {
-                        $issues += " - $relativePath`:L$($_.LineNumber) - $($_.Line)"
-                    }
-                }
-            }
-            $issues -join [Environment]::NewLine |
-                Should -BeNullOrEmpty -Because 'the script should not use ternary operations for compatibility with PS 5.1 and below'
-        }
         It 'all powershell keywords are lowercase (ID: LowercaseKeywords)' {
             $issues = @('')
             $scriptFiles | ForEach-Object {
@@ -339,6 +360,16 @@ Describe 'PSModule - SourceCode tests' {
                     $tokens.count -ne 0
                 }
             }
+            It 'Should put the canonical documentation link first for <DocumentationPath> (ID: PublicHelpLink)' -ForEach $publicHelpLinkTestCases {
+                param($DocumentationPath, $ExpectedLink, $FilePath)
+
+                $content = Get-Content -Path $FilePath -Raw
+                $links = [regex]::Matches($content, '(?ms)^\s*\.LINK\s*\r?\n\s*(?<Uri>\S+)')
+
+                $links.Count | Should -BeGreaterThan 0 -Because "$DocumentationPath should have a documentation link"
+                $links[0].Groups['Uri'].Value |
+                    Should -BeExactly $ExpectedLink -Because "$DocumentationPath should put its canonical documentation link first"
+            }
             It 'All public functions/filters have tests (ID: FunctionTest)' {
                 $issues = @('')
 

.github/workflows/Test-SourceCode.yml

@@ -37,6 +37,7 @@ jobs:
       - name: Test-SourceCode
         uses: ./_wf/.github/actions/Test-PSModule
         with:
+          Name: ${{ fromJson(inputs.Settings).Name }}
           Debug: ${{ fromJson(inputs.Settings).Debug }}
           Prerelease: ${{ fromJson(inputs.Settings).Prerelease }}
           Verbose: ${{ fromJson(inputs.Settings).Verbose }}

tests/srcTestRepo/src/functions/public/PSModule/Get-PSModuleTest.ps1

@@ -15,6 +15,9 @@ function Get-PSModuleTest {
         Test-PSModule -Name 'World'
 
         "Hello, World!"
+
+        .LINK
+        https://psmodule.io/PSModuleTest2/Functions/PSModule/Get-PSModuleTest/
     #>
     [CmdletBinding()]
     param (

tests/srcTestRepo/src/functions/public/PSModule/New-PSModuleTest.ps1

@@ -13,6 +13,9 @@ function New-PSModuleTest {
 
         "Hello, World!"
 
+        .LINK
+        https://psmodule.io/PSModuleTest2/Functions/PSModule/New-PSModuleTest/
+
         .NOTES
         Testing if a module can have a [Markdown based link](https://example.com).
         !"#¤%&/()=?`´^¨*'-_+§½{[]}<>|@£$€¥¢:;.,"

tests/srcTestRepo/src/functions/public/SomethingElse/Set-PSModuleTest.ps1

@@ -10,6 +10,9 @@
         Test-PSModule -Name 'World'
 
         "Hello, World!"
+
+        .LINK
+        https://psmodule.io/PSModuleTest2/Functions/SomethingElse/Set-PSModuleTest/
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '', Scope = 'Function',

tests/srcTestRepo/src/functions/public/Test-PSModuleTest.ps1

@@ -10,6 +10,9 @@
         Test-PSModule -Name 'World'
 
         "Hello, World!"
+
+        .LINK
+        https://psmodule.io/PSModuleTest2/Functions/Test-PSModuleTest/
     #>
     [CmdletBinding()]
     param (

tests/srcWithManifestTestRepo/src/functions/public/PSModule/Get-PSModuleTest.ps1

@@ -15,6 +15,9 @@ function Get-PSModuleTest {
         Test-PSModule -Name 'World'
 
         "Hello, World!"
+
+        .LINK
+        https://psmodule.io/PSModuleTest/Functions/PSModule/Get-PSModuleTest/
     #>
     [CmdletBinding()]
     param (

tests/srcWithManifestTestRepo/src/functions/public/PSModule/New-PSModuleTest.ps1

@@ -13,6 +13,9 @@ function New-PSModuleTest {
 
         "Hello, World!"
 
+        .LINK
+        https://psmodule.io/PSModuleTest/Functions/PSModule/New-PSModuleTest/
+
         .NOTES
         Testing if a module can have a [Markdown based link](https://example.com).
         !"#¤%&/()=?`´^¨*'-_+§½{[]}<>|@£$€¥¢:;.,"