⚙️ [Maintenance]: Public help-link checks now support any HTTPS host (#532)

Public command help-link validation now works with any HTTPS
documentation host while preserving the required module and function
path structure. Repositories can publish their command reference outside
the PSModule documentation site without weakening the canonical URL
contract.

## Changed: Public help-link validation

Every public function must provide a first `.LINK` entry. The test fails
immediately when no `.LINK` section is found. When a link is present, it
must be an absolute HTTPS URL with a host and the canonical
`/Module/Functions/<relative-command>/` path; query strings and
fragments are rejected.

The PowerShell module standard, framework-test reference, pre-review
validation checklist, module-structuring guide, and skip-test guide now
document this requirement using a configurable HTTPS documentation host.

---
<details>
<summary>Technical details</summary>

- Changed
`.github/actions/Test-PSModule/src/tests/SourceCode/PSModule/PSModule.Tests.ps1`
to require a link, then parse the first `.LINK` URI and validate its
scheme, host, path, query, and fragment instead of comparing against a
hardcoded `psmodule.io` origin.
- Updated one grouped command fixture in each test repository to use
`https://docs.example.com`, proving the test does not depend on the
PSModule host.
- Documented `PublicHelpLink` in
`docs/content/reference/powershell-module-standard.md` and
`docs/content/reference/framework-test-ids.md`.
- Added the requirement to
`docs/content/guides/validating-before-review.md` and replaced
fixed-host examples in the structuring and skip-test guides with
`<DocumentationHost>`.
- Validation: the targeted Pester 6.1.0 source-code suite passed 13
tests for both `tests/srcTestRepo` and `tests/srcWithManifestTestRepo`;
`zensical build --strict` and `git diff --check` passed.

| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| `.github/actions/Test-PSModule/**` (PowerShell) | MSX PowerShell
standard | Public command help-link contract | Aligned |
| `tests/**` (PowerShell fixtures) | MSX PowerShell standard |
Source-code test fixtures | Aligned |
| `docs/content/reference/**` and `docs/content/guides/**` (Markdown) |
MSX Documentation Model, Markdown | Module layout and framework-test
guidance | Aligned |

Issue convergence sweep: scoped to reusable public help-link validation
and its contributor guidance. This change does not generate missing
links during scaffolding or build, so the broader follow-up remains
open.

</details>

<details>
<summary>Relevant issues (or links)</summary>

### Related work

- References #445
- References #453

</details>

---------

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

Author: MariusStorhaug

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

@@ -59,7 +59,6 @@ BeforeDiscovery {
 
                 @{
                     DocumentationPath = $documentationPath
-                    ExpectedLink      = "https://psmodule.io/$ModuleName/Functions/$documentationPath/"
                     FilePath          = $_.FullName
                 }
             }
@@ -360,15 +359,25 @@ 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)
+            It 'Should require a canonical documentation link for <DocumentationPath> (ID: PublicHelpLink)' -ForEach $publicHelpLinkTestCases {
+                param($DocumentationPath, $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"
+                $link = $links[0].Groups['Uri'].Value
+                $parsedLink = $null
+                [Uri]::TryCreate($link, [UriKind]::Absolute, [ref]$parsedLink) |
+                    Should -BeTrue -Because "$DocumentationPath should use an absolute documentation link"
+                $parsedLink.Scheme |
+                    Should -BeExactly 'https' -Because "$DocumentationPath should use HTTPS for its documentation link"
+                $parsedLink.Host |
+                    Should -Not -BeNullOrEmpty -Because "$DocumentationPath should specify a documentation host"
+                $parsedLink.AbsolutePath |
+                    Should -BeExactly "/$ModuleName/Functions/$DocumentationPath/" -Because "$DocumentationPath should use the canonical documentation path"
+                $parsedLink.Query | Should -BeNullOrEmpty -Because "$DocumentationPath should not add a query to its documentation link"
+                $parsedLink.Fragment | Should -BeNullOrEmpty -Because "$DocumentationPath should not add a fragment to its documentation link"
             }
             It 'All public functions/filters have tests (ID: FunctionTest)' {
                 $issues = @('')

docs/content/guides/skipping-framework-tests.md

@@ -62,7 +62,7 @@ function Get-ComplexData {
         This file intentionally skips only the FunctionCount framework test.
 
         .LINK
-        https://psmodule.io/<ModuleName>/Functions/Get-ComplexData
+        https://<DocumentationHost>/<ModuleName>/Functions/Get-ComplexData
     #>
     [OutputType([PSCustomObject])]
     [CmdletBinding()]
@@ -104,7 +104,7 @@ function Get-RawData {
         This function is a private helper for Get-ComplexData.
 
         .LINK
-        https://psmodule.io/<ModuleName>/Functions/Get-ComplexData
+        https://<DocumentationHost>/<ModuleName>/Functions/Get-ComplexData
     #>
     [OutputType([string])]
     [CmdletBinding()]
@@ -145,7 +145,7 @@ function Format-ComplexData {
         This function is a private helper for Get-ComplexData.
 
         .LINK
-        https://psmodule.io/<ModuleName>/Functions/Get-ComplexData
+        https://<DocumentationHost>/<ModuleName>/Functions/Get-ComplexData
     #>
     [OutputType([PSCustomObject])]
     [CmdletBinding()]
@@ -163,7 +163,7 @@ function Format-ComplexData {
 }
 ```
 
-Replace `<ModuleName>` with the module's published name. If the public function belongs to a group, insert `<Group>/` between `Functions/` and `Get-ComplexData`.
+Replace `<DocumentationHost>` with the HTTPS host that publishes the module documentation and `<ModuleName>` with the module's published name. If the public function belongs to a group, insert `<Group>/` between `Functions/` and `Get-ComplexData`.
 
 The skip exempts only `FunctionCount`. Every function in the file must still follow the [PowerShell function standard](https://msx.no/docs/Coding-Standards/PowerShell/Functions/), including complete comment-based help, matching `[OutputType()]` and `.OUTPUTS` metadata, typed parameters, and implicit output.
 

docs/content/guides/structuring-your-module.md

@@ -67,12 +67,12 @@ Key expectations:
 - A group's overview page (`<Category>/<Category>.md` named after the folder, or `<Category>/index.md`) becomes that group's section landing page in the docs navigation.
 - The build step compiles `src/` into a root module file and removes the original project layout from the artifact.
 - Documentation generation mirrors the `src/functions/public` hierarchy so help content always aligns with source.
-- Put the canonical public help URL first in each public command's comment-based help. For a command at `src/functions/public/<Group>/<Name>.ps1`, use `https://psmodule.io/<ModuleName>/Functions/<Group>/<Name>/`. `Test-PSModule` enforces this as `PublicHelpLink`; additional `.LINK` entries may follow.
+- Put the canonical public help URL first in each public command's comment-based help. For a command at `src/functions/public/<Group>/<Name>.ps1`, use `https://<DocumentationHost>/<ModuleName>/Functions/<Group>/<Name>/` with the HTTPS host that publishes the module documentation. `Test-PSModule` enforces this as `PublicHelpLink`; additional `.LINK` entries may follow.
 - Point each private helper's `.LINK` entry to the public command it supports, using that command's canonical grouped URL.
 
 ### Grouping and published help URLs
 
-Process-PSModule generates command help and publishes each page to mirror the relative path under `src/functions/public/`. Moving an existing command into a group therefore changes its published URL from `https://psmodule.io/<ModuleName>/Functions/<Name>/` to `https://psmodule.io/<ModuleName>/Functions/<Group>/<Name>/`.
+Process-PSModule generates command help and publishes each page to mirror the relative path under `src/functions/public/`. Moving an existing command into a group therefore changes its published URL from `https://<DocumentationHost>/<ModuleName>/Functions/<Name>/` to `https://<DocumentationHost>/<ModuleName>/Functions/<Group>/<Name>/`.
 
 When regrouping a command, update its first public `.LINK`, every private-helper `.LINK` that points to it, and any other references to the old URL in the same change. Process-PSModule does not create redirects for the old path; arrange a redirect separately in the publishing layer when existing links must continue to work.
 

docs/content/guides/validating-before-review.md

@@ -55,6 +55,7 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR 
 
    - comment-based help is present for every changed function, including private helpers
    - help sections, examples, `.INPUTS`, `.OUTPUTS`, and parameter documentation match the function contract from [MSX PowerShell Functions](https://msx.no/docs/Coding-Standards/PowerShell/Functions/)
+   - every public function has a first `.LINK` entry using an absolute HTTPS URL whose path matches the generated command documentation path
    - public-function links and usage examples are current enough that generated documentation will stay accurate
 
    Do not treat help as optional cleanup. In PSModule repositories, the function help is part of the delivered behavior.

docs/content/reference/framework-test-ids.md

@@ -26,6 +26,7 @@ Run by the [Test source code](pipeline-stages.md#test-source-code) job against f
 | `CmdletBinding` | Functions (Generic) | Functions should include the `[CmdletBinding()]` attribute. | `#SkipTest:CmdletBinding:Simple helper function` |
 | `ParamBlock` | Functions (Generic) | Functions should have a parameter block (`param()`). | `#SkipTest:ParamBlock:No parameters needed` |
 | `FunctionTest` | Functions (Public) | All public functions and filters should have corresponding tests. | `#SkipTest:FunctionTest:Test in development` |
+| `PublicHelpLink` | Functions (Public) | Every public function and filter should have a first `.LINK` entry with an absolute HTTPS URL whose path matches its generated command documentation path. | `#SkipTest:PublicHelpLink:Legacy documentation link` |
 
 ## Module tests
 

docs/content/reference/powershell-module-standard.md

@@ -358,6 +358,7 @@ The CI pipeline automatically tests every source file against the following rule
 | `CmdletBinding` | Every function must have `[CmdletBinding()]` |
 | `ParamBlock` | Every function must have a `param()` block |
 | `FunctionTest` | Every public function must be referenced by the tests; its behavior must be covered whether the suite is per-command or grouped |
+| `PublicHelpLink` | Every public function must have a first `.LINK` entry with an absolute HTTPS URL whose path is `/Module/Functions/<relative-command>/` |
 
 To skip a specific rule for one file only, add a comment at the very top of that file:
 

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

@@ -17,7 +17,7 @@ function Get-PSModuleTest {
         "Hello, World!"
 
         .LINK
-        https://psmodule.io/PSModuleTest2/Functions/PSModule/Get-PSModuleTest/
+        https://docs.example.com/PSModuleTest2/Functions/PSModule/Get-PSModuleTest/
     #>
     [CmdletBinding()]
     param (

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

@@ -17,7 +17,7 @@ function Get-PSModuleTest {
         "Hello, World!"
 
         .LINK
-        https://psmodule.io/PSModuleTest/Functions/PSModule/Get-PSModuleTest/
+        https://docs.example.com/PSModuleTest/Functions/PSModule/Get-PSModuleTest/
     #>
     [CmdletBinding()]
     param (