Fix deployment help links and coverage gaps (#232)

stiwicourage · web-flow · commit 4a996efd114f · 2026-05-24T12:38:31.000+02:00
* fix(#215): restore deploy help related links * fix(#215): close raw upload coverage gaps * #215 fix: nomalize command help related links
diff --git a/.github/instructions/platyps-help.instructions.md b/.github/instructions/platyps-help.instructions.md
@@ -66,6 +66,9 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/<CommandName>.md |
 - The `external help file` field must always use the module name, not the command name: `NovaModuleTools-Help.xml`. The `Module Name` field must match the project name. When both fields use the module name, Nova build produces a single `<ModuleName>-Help.xml` under `dist/<ModuleName>/en-US/`. If either field contains a command name instead, the build produces per-command XML files and the module manifest cannot find its help.
 - Keep the H1 title equal to the exact command name.
 - Preserve the standard PlatyPS section order with uppercase H2 headers: `SYNOPSIS`, `SYNTAX`, optional `ALIASES`, `DESCRIPTION`, `EXAMPLES`, `PARAMETERS`, `INPUTS`, `OUTPUTS`, `NOTES`, and `RELATED LINKS`.
+- In `## RELATED LINKS`, use only a bulleted list of Markdown links. Do not use bare URLs or backticked command names as list items.
+- Prefer relative links to sibling command-help files when the related topic has a matching file in `docs/NovaModuleTools/en-US/`, for example `[Invoke-NovaBuild](./Invoke-NovaBuild.md)`.
+- Do not use GitHub blob URLs in shipped command help. If a relative command-help link is not suitable after PlatyPS validation, use the related topic's `novamoduletools.com` `HelpUri` instead.
 - Keep at least one example under `## EXAMPLES`.
 - Keep parameter sections as `### -ParameterName` blocks with the PlatyPS-generated YAML metadata code block.
 - Only hand-edit parameter metadata when PlatyPS cannot infer it correctly, especially `DefaultValue` and `SupportsWildcards`.
@@ -82,6 +85,7 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/<CommandName>.md |
 - Use `Update-MarkdownCommandHelp` after command or parameter changes so syntax, aliases, and parameter metadata stay synchronized with the implementation.
 - Use `Test-MarkdownCommandHelp` as the quick structural gate before handoff; use `Import-MarkdownCommandHelp` diagnostics when you need more detail.
 - Use existing valid files under `docs/NovaModuleTools/en-US/` as the structural template before inventing a new layout.
+- Validate any new `RELATED LINKS` target style through the real PlatyPS import/export path before applying it repo-wide.
 - Keep command help separate from contributor docs and project/site docs.
 
 ## Review expectations
@@ -90,4 +94,5 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/<CommandName>.md |
 - Reviewers should flag help files where `external help file` contains a command name (e.g., `Get-Something-Help.xml`) instead of the module name (`NovaModuleTools-Help.xml`). This produces per-command XML files that the module manifest cannot locate at runtime.
 - Reviewers should flag help files that would fail `Test-MarkdownCommandHelp` or produce diagnostics/errors when imported with `Import-MarkdownCommandHelp`.
 - Reviewers should flag any new public entry point that does not add its matching command-help file in the same change.
+- Reviewers should flag `RELATED LINKS` entries that use GitHub blob URLs, plain URLs, or bare/backticked command names instead of Markdown links.
 - Treat build errors from `Import-MarkdownCommandHelp` as a sign that the file is not valid PlatyPS help yet.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -26,6 +26,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 ### Fixed
 
 - `Test-NovaBuild` now expands configured Pester coverage globs into concrete source files before invoking Pester, so nested helpers remain measurable in `artifacts/coverage.xml` while repository and scaffolded `project.json` defaults can stay on the simpler `src/private/**/*.ps1` entry.
+- PowerShell command help `RELATED LINKS` now use valid PlatyPS Markdown links and point to shipped help topics instead of GitHub blob pages.
 
 ### Security
 
diff --git a/RELEASE_NOTE.md b/RELEASE_NOTE.md
@@ -21,6 +21,8 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 
 ### Fixed
 
+- PowerShell command help `RELATED LINKS` now use valid help-topic links instead of GitHub blob pages.
+
 ### Security
 
 ## [3.0.1] - 2026-05-18
diff --git a/docs/NovaModuleTools/en-US/Deploy-NovaPackage.md b/docs/NovaModuleTools/en-US/Deploy-NovaPackage.md
@@ -382,5 +382,5 @@ If no upload target can be resolved, `Deploy-NovaPackage` fails fast with a clea
 
 ## RELATED LINKS
 
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/New-NovaModulePackage.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Publish-NovaModule.md
+- [New-NovaModulePackage](./New-NovaModulePackage.md)
+- [Publish-NovaModule](./Publish-NovaModule.md)
diff --git a/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md b/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md
@@ -189,6 +189,6 @@ This command throws a clear error when `project.json` is missing or empty.
 
 ## RELATED LINKS
 
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Test-NovaBuild.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)
+- [Test-NovaBuild](./Test-NovaBuild.md)
+- [Update-NovaModuleVersion](./Update-NovaModuleVersion.md)
diff --git a/docs/NovaModuleTools/en-US/Get-NovaUpdateNotificationPreference.md b/docs/NovaModuleTools/en-US/Get-NovaUpdateNotificationPreference.md
@@ -81,6 +81,6 @@ When prerelease notifications are enabled again, `Update-NovaModuleTool` / `Upda
 
 ## RELATED LINKS
 
-- `Invoke-NovaBuild`
-- `Set-NovaUpdateNotificationPreference`
-- `Update-NovaModuleTool`
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)
+- [Set-NovaUpdateNotificationPreference](./Set-NovaUpdateNotificationPreference.md)
+- [Update-NovaModuleTool](./Update-NovaModuleTools.md)
diff --git a/docs/NovaModuleTools/en-US/Initialize-NovaModule.md b/docs/NovaModuleTools/en-US/Initialize-NovaModule.md
@@ -152,5 +152,5 @@ Generated projects start with NovaModuleTools defaults for recursive discovery,
 
 ## RELATED LINKS
 
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)
+- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md)
diff --git a/docs/NovaModuleTools/en-US/Install-NovaCli.md b/docs/NovaModuleTools/en-US/Install-NovaCli.md
@@ -172,4 +172,4 @@ After running `Install-NovaCli`, add the destination directory to your shell `PA
 
 ## RELATED LINKS
 
-- `Publish-NovaModule`
+- [Publish-NovaModule](./Publish-NovaModule.md)
diff --git a/docs/NovaModuleTools/en-US/Invoke-NovaAgenticCopilotScaffold.md b/docs/NovaModuleTools/en-US/Invoke-NovaAgenticCopilotScaffold.md
@@ -203,5 +203,5 @@ This workflow does not persist `ShortName` to `project.json` and does not infer
 
 ## RELATED LINKS
 
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Initialize-NovaModule.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md
+- [Initialize-NovaModule](./Initialize-NovaModule.md)
+- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md)
diff --git a/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md b/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md
@@ -174,7 +174,7 @@ Files under `src/public` are expected to contain exactly one top-level function
 
 ## RELATED LINKS
 
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Test-NovaBuild.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Publish-NovaModule.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Update-NovaModuleTools.md
+- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md)
+- [Test-NovaBuild](./Test-NovaBuild.md)
+- [Publish-NovaModule](./Publish-NovaModule.md)
+- [Update-NovaModuleTool](./Update-NovaModuleTools.md)
diff --git a/docs/NovaModuleTools/en-US/Invoke-NovaRelease.md b/docs/NovaModuleTools/en-US/Invoke-NovaRelease.md
@@ -325,7 +325,7 @@ and `-Confirm` support.
 
 ## RELATED LINKS
 
-- `Invoke-NovaBuild`
-- `Test-NovaBuild`
-- `Update-NovaModuleVersion`
-- `Publish-NovaModule`
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)
+- [Test-NovaBuild](./Test-NovaBuild.md)
+- [Update-NovaModuleVersion](./Update-NovaModuleVersion.md)
+- [Publish-NovaModule](./Publish-NovaModule.md)
diff --git a/docs/NovaModuleTools/en-US/New-NovaModulePackage.md b/docs/NovaModuleTools/en-US/New-NovaModulePackage.md
@@ -277,5 +277,5 @@ Files under `src/public` are expected to contain exactly one top-level function
 
 ## RELATED LINKS
 
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Test-NovaBuild.md
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)
+- [Test-NovaBuild](./Test-NovaBuild.md)
diff --git a/docs/NovaModuleTools/en-US/Publish-NovaModule.md b/docs/NovaModuleTools/en-US/Publish-NovaModule.md
@@ -302,6 +302,6 @@ When `-ContinuousIntegration` is used, Nova restores the built `dist/` module af
 
 ## RELATED LINKS
 
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Test-NovaBuild.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaRelease.md
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)
+- [Test-NovaBuild](./Test-NovaBuild.md)
+- [Invoke-NovaRelease](./Invoke-NovaRelease.md)
diff --git a/docs/NovaModuleTools/en-US/Set-NovaUpdateNotificationPreference.md b/docs/NovaModuleTools/en-US/Set-NovaUpdateNotificationPreference.md
@@ -197,5 +197,5 @@ Use this command together with `Get-NovaUpdateNotificationPreference` when you w
 
 ## RELATED LINKS
 
-- `Get-NovaUpdateNotificationPreference`
-- `Update-NovaModuleTool`
+- [Get-NovaUpdateNotificationPreference](./Get-NovaUpdateNotificationPreference.md)
+- [Update-NovaModuleTool](./Update-NovaModuleTools.md)
diff --git a/docs/NovaModuleTools/en-US/Test-NovaBuild.md b/docs/NovaModuleTools/en-US/Test-NovaBuild.md
@@ -260,6 +260,6 @@ If `project.json` configures `Pester.CodeCoverage.CoveragePercentTarget`, `Test-
 
 ## RELATED LINKS
 
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Publish-NovaModule.md
+- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md)
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)
+- [Publish-NovaModule](./Publish-NovaModule.md)
diff --git a/docs/NovaModuleTools/en-US/Update-NovaModuleTools.md b/docs/NovaModuleTools/en-US/Update-NovaModuleTools.md
@@ -149,6 +149,6 @@ Use `Get-NovaUpdateNotificationPreference` and `Set-NovaUpdateNotificationPrefer
 
 ## RELATED LINKS
 
-- `Get-NovaUpdateNotificationPreference`
-- `Set-NovaUpdateNotificationPreference`
-- `Invoke-NovaBuild`
+- [Get-NovaUpdateNotificationPreference](./Get-NovaUpdateNotificationPreference.md)
+- [Set-NovaUpdateNotificationPreference](./Set-NovaUpdateNotificationPreference.md)
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)
diff --git a/docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md b/docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md
@@ -303,6 +303,6 @@ When Git-based inference is unavailable, `Update-NovaModuleVersion` now requires
 
 ## RELATED LINKS
 
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md
-- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaRelease.md
+- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md)
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)
+- [Invoke-NovaRelease](./Invoke-NovaRelease.md)
diff --git a/src/resources/agentic-copilot/.github/instructions/platyps-help.instructions.md b/src/resources/agentic-copilot/.github/instructions/platyps-help.instructions.md
@@ -66,6 +66,9 @@ Import-MarkdownCommandHelp -Path ./docs/{{ProjectName}}/en-US/<CommandName>.md |
 - The `external help file` field must always use the module name, not the command name: `{{ProjectName}}-Help.xml`. The `Module Name` field must match the project name. When both fields use the module name, Nova build produces a single `<ModuleName>-Help.xml` under `dist/<ModuleName>/en-US/`. If either field contains a command name instead, the build produces per-command XML files and the module manifest cannot find its help.
 - Keep the H1 title equal to the exact command name.
 - Preserve the standard PlatyPS section order with uppercase H2 headers: `SYNOPSIS`, `SYNTAX`, optional `ALIASES`, `DESCRIPTION`, `EXAMPLES`, `PARAMETERS`, `INPUTS`, `OUTPUTS`, `NOTES`, and `RELATED LINKS`.
+- In `## RELATED LINKS`, use only a bulleted list of Markdown links. Do not use bare URLs or backticked command names as list items.
+- Prefer relative links to sibling command-help files when the related topic has a matching file in `docs/{{ProjectName}}/en-US/`, for example `[Invoke-NovaBuild](./Invoke-NovaBuild.md)`.
+- Do not use GitHub blob URLs in shipped command help. If a relative command-help link is not suitable after PlatyPS validation, use the related topic's `novamoduletools.com` `HelpUri` instead.
 - Keep at least one example under `## EXAMPLES`.
 - Keep parameter sections as `### -ParameterName` blocks with the PlatyPS-generated YAML metadata code block.
 - Only hand-edit parameter metadata when PlatyPS cannot infer it correctly, especially `DefaultValue` and `SupportsWildcards`.
@@ -82,6 +85,7 @@ Import-MarkdownCommandHelp -Path ./docs/{{ProjectName}}/en-US/<CommandName>.md |
 - Use `Update-MarkdownCommandHelp` after command or parameter changes so syntax, aliases, and parameter metadata stay synchronized with the implementation.
 - Use `Test-MarkdownCommandHelp` as the quick structural gate before handoff; use `Import-MarkdownCommandHelp` diagnostics when you need more detail.
 - Use existing valid files under `docs/{{ProjectName}}/en-US/` as the structural template before inventing a new layout.
+- Validate any new `RELATED LINKS` target style through the real PlatyPS import/export path before applying it repo-wide.
 - Keep command help separate from contributor docs and project/site docs.
 
 ## Review expectations
@@ -90,4 +94,5 @@ Import-MarkdownCommandHelp -Path ./docs/{{ProjectName}}/en-US/<CommandName>.md |
 - Reviewers should flag help files where `external help file` contains a command name (e.g., `Get-Something-Help.xml`) instead of the module name (`{{ProjectName}}-Help.xml`). This produces per-command XML files that the module manifest cannot locate at runtime.
 - Reviewers should flag help files that would fail `Test-MarkdownCommandHelp` or produce diagnostics/errors when imported with `Import-MarkdownCommandHelp`.
 - Reviewers should flag any new public entry point that does not add its matching command-help file in the same change.
+- Reviewers should flag `RELATED LINKS` entries that use GitHub blob URLs, plain URLs, or bare/backticked command names instead of Markdown links.
 - Treat build errors from `Import-MarkdownCommandHelp` as a sign that the file is not valid PlatyPS help yet.
diff --git a/tests/CommandHelpRelatedLinks.Tests.ps1 b/tests/CommandHelpRelatedLinks.Tests.ps1
@@ -0,0 +1,58 @@
+BeforeAll {
+    $projectRoot = Split-Path -Parent $PSScriptRoot
+    $script:docsDirectory = Join-Path $projectRoot 'docs/NovaModuleTools/en-US'
+    $script:helpFiles = Get-ChildItem -LiteralPath $script:docsDirectory -Filter '*.md' -File |
+        Where-Object Name -ne 'NovaModuleTools.md'
+
+    $script:relatedLinks = foreach ($file in $script:helpFiles) {
+        $content = Get-Content -LiteralPath $file.FullName -Raw
+        $sectionMatch = [regex]::Match($content, '(?ms)^## RELATED LINKS\r?\n\r?\n(?<body>.*)$')
+        if (-not $sectionMatch.Success) {
+            continue
+        }
+
+        $linkLineList = @(
+            $sectionMatch.Groups['body'].Value -split '\r?\n' |
+                Where-Object { $_ -match '^- ' }
+        )
+
+        foreach ($line in $linkLineList) {
+            $lineMatch = [regex]::Match($line, '^- \[(?<text>[^\]]+)\]\((?<uri>[^)]+)\)$')
+            [pscustomobject]@{
+                FileName = $file.Name
+                Line = $line
+                Text = $lineMatch.Groups['text'].Value
+                Uri = $lineMatch.Groups['uri'].Value
+                IsMarkdownLink = $lineMatch.Success
+            }
+        }
+    }
+}
+
+Describe 'command help related links' {
+    It 'uses Markdown link syntax for every related-links entry' {
+        foreach ($entry in $script:relatedLinks) {
+            $entry.Line | Should -Match '^- \[[^\]]+\]\([^)]+\)$' -Because $entry.FileName
+        }
+    }
+
+    It 'does not use GitHub blob links in related-links entries' {
+        foreach ($entry in $script:relatedLinks) {
+            $entry.Line | Should -Not -Match 'github\.com/.*/blob/' -Because $entry.FileName
+        }
+    }
+
+    It 'uses resolvable internal help links or Nova website links in related-links entries' {
+        foreach ($entry in $script:relatedLinks) {
+            $entry.IsMarkdownLink | Should -BeTrue -Because $entry.FileName
+
+            if ($entry.Uri -match '^\./(?<target>[^/]+\.md)$') {
+                $targetPath = Join-Path $script:docsDirectory $Matches['target']
+                (Test-Path -LiteralPath $targetPath -PathType Leaf) | Should -BeTrue -Because "$($entry.FileName): $($entry.Uri)"
+                continue
+            }
+
+            $entry.Uri | Should -Match '^https://www\.novamoduletools\.com/' -Because "$($entry.FileName): $($entry.Uri)"
+        }
+    }
+}

Original file line number	Diff line number	Diff line change
@@ -172,4 +172,4 @@ After running `Install-NovaCli`, add the destination directory to your shell `PA
`172`	`172`
`173`	`173`	`## RELATED LINKS`
`174`	`174`
`175`		-- `Publish-NovaModule`
	`175`	`+- [Publish-NovaModule](./Publish-NovaModule.md)`