⚙️ [Maintenance]: Public help links follow canonical documentation paths (#420)

Public module source validation requires each **public function-bearing
script** under `src/functions/public` to put its canonical
generated-documentation URL first in comment-based help.

## Changed: Canonical public help links are enforced for
function-bearing files

The source-code standards suite derives documentation paths from
recursive public function paths and validates the first `.LINK` against
`https://psmodule.io/<ModuleName>/Functions/<relative
path>/<FunctionName>/`.

## Technical Details

- `Test-SourceCode` forwards the configured module name into the shared
test action instead of falling back to the repository name.
- Public help-link validation applies only to public scripts that define
at least one function/filter.
- Covers ungrouped and nested public function scripts.
- Requires at least one `.LINK`, exact URL casing/content, first-link
ordering, and a trailing slash.
- Fixture repos cover both grouped and ungrouped function paths while
non-function public scripts are not forced to provide canonical links.

## Downstream dependency status (live)

- `PSModule/Domeneshop` PR **#17** has already been merged into `main`
at `2ca6f788c4b68a72c63d6472ae19720bc90cc8b9` while still pinned to
`Process-PSModule` **v6.1.13**
(`fb1bdb8fefd243292f779d2a856a38db6fe6daf4`).
- That downstream state currently lacks the local `PublicHelpLinks` /
`ModuleRequirements` / `TestLayout` checks intended by this framework
update.
- Merging this PR unblocks downstream alignment by making the canonical
public help-link validation available in the framework version line.

## Validation

- Focused PublicHelpLink runs pass for both dynamic module names (4
cases each after scoping).
- Full source-code standards suites pass for both fixtures (13 tests
each).
- PSScriptAnalyzer reports no warnings or errors in changed files.
- Draft PR CI passes, including linter, CodeQL, action analysis, and
both workflow-test matrices.

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

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)]"
@@ -321,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).
         !"#¤%&/()=?`´^¨*'-_+§½{[]}<>|@£$€¥¢:;.,"