mirror of https://github.com/raandree/NTFSSecurity
Browse Source
* fix(help): ship the generated help file so Get-Help works Get-Help showed only the syntax of the cmdlets: the module shipped a pre-4.x MAML file for the old command names under the wrong name (NTFSSecurity-Help.xml), while PowerShell looks for en-US\NTFSSecurity.dll-Help.xml. - Generate en-US\NTFSSecurity.dll-Help.xml from Docs/Cmdlets with New-ExternalHelp and commit it. The csproj copies it to the output, so every build ships it, including the local Debug builds that releases are published from. - List all runtime files, including the help file, in FileList. - Remove the stale NTFSSecurity-Help.xml and the unused help editor project NTFSSecurity\Help\NTFSSecurity.Help.pshproj. - Add Tests\Help.Tests.ps1 (Pester 5): Get-Help shows the synopsis, parameters, examples, and online link of every page, and Get-Help -Online resolves to the GitHub page. - Reword six sentences in five cmdlet pages so that each link ends its sentence: platyPS drops the space after a link in the help text. - CI regenerates the help file and fails when it differs from the committed file, then runs the Pester tests. - Document the regeneration step and the link rule in the contributor guide. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant <ai@example.com> * ci: report each Pester test once on AppVeyor AppVeyor build 54834154 passed all 218 Pester tests but listed 870 on its Tests tab: the NUnit import files a Pester 5 test under every block that contains it (Pester, test file, Describe, and Context). Report the results through the build worker API instead (POST api/tests/batch): one entry per test with its outcome, duration, and error message. Outside AppVeyor, and when no test ran, the step sends nothing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant <ai@example.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant <ai@example.com>pull/94/head
Raimund Andrée
1 week ago
committed by
GitHub
GitHub
20 changed files with 10348 additions and 5163 deletions
@ -0,0 +1,26 @@ |
|||
--- |
|||
status: accepted |
|||
date: 2026-10-02 |
|||
last-verified: 2026-10-02 |
|||
owner: shared |
|||
source: maintainer choice in work package 2 (option A) |
|||
--- |
|||
|
|||
# Decision 8: Commit the generated help file and check it in CI |
|||
|
|||
- Choice: `NTFSSecurity\en-US\NTFSSecurity.dll-Help.xml` is generated from |
|||
`Docs/Cmdlets` with `New-ExternalHelp` (platyPS 0.14.2, Windows |
|||
PowerShell 5.1) and committed. `NTFSSecurity.csproj` copies it to the |
|||
output as `Content`, the manifest `FileList` lists it, and `appveyor.yml` |
|||
regenerates it and fails on `git status --porcelain -- NTFSSecurity/en-US`. |
|||
- Rationale: Releases are built locally in Visual Studio (Debug, written to |
|||
`C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`) and published |
|||
by hand with `Publish-Module`. A committed file ships with every build |
|||
and needs no tool on the build machine. Generating it in an MSBuild step |
|||
would need platyPS on every build machine, or would silently ship without |
|||
help when platyPS is missing. |
|||
- Consequence: every change to `Docs/Cmdlets` must be followed by |
|||
`New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath .\NTFSSecurity\en-US |
|||
-Force`. The output is deterministic (byte-identical between runs), so |
|||
the CI check is exact. |
|||
- Rejected: an MSBuild `AfterBuild` target that runs platyPS. |
|||
File diff suppressed because it is too large
File diff suppressed because it is too large
File diff suppressed because it is too large
@ -0,0 +1,115 @@ |
|||
<# |
|||
Tests that Get-Help shows the help that is generated from Docs/Cmdlets for |
|||
every cmdlet of the module built in NTFSSecurity\bin\Release. |
|||
#> |
|||
[Diagnostics.CodeAnalysis.SuppressMessageAttribute( |
|||
'PSUseDeclaredVarsMoreThanAssignments', '', Justification = 'Pester shares variables between blocks.' |
|||
)] |
|||
param () |
|||
|
|||
BeforeDiscovery { |
|||
$pagePath = Join-Path -Path $PSScriptRoot -ChildPath '..\Docs\Cmdlets' |
|||
$sectionPattern = '(?ms)^## (?<Heading>[A-Z ]+?)\s*$(?<Text>.*?)(?=^## |\z)' |
|||
|
|||
$helpPages = foreach ($page in Get-ChildItem -Path $pagePath -Filter '*.md') { |
|||
$content = Get-Content -LiteralPath $page.FullName -Raw |
|||
$sections = @{} |
|||
foreach ($match in [regex]::Matches($content, $sectionPattern)) { |
|||
$sections[$match.Groups['Heading'].Value] = $match.Groups['Text'].Value |
|||
} |
|||
|
|||
$parameterNames = [regex]::Matches("$($sections['PARAMETERS'])", '(?m)^### -(?<Name>\w+)') | |
|||
ForEach-Object -Process { $_.Groups['Name'].Value } |
|||
|
|||
@{ |
|||
CommandName = $page.BaseName |
|||
Synopsis = "$($sections['SYNOPSIS'])".Trim() |
|||
ExampleCount = [regex]::Matches("$($sections['EXAMPLES'])", '(?m)^### ').Count |
|||
ParameterNames = @($parameterNames) |
|||
OnlineUri = [regex]::Match($content, '(?m)^online version: (?<Uri>\S+)').Groups['Uri'].Value |
|||
} |
|||
} |
|||
} |
|||
|
|||
Describe 'Help of the NTFSSecurity cmdlets' { |
|||
BeforeAll { |
|||
$modulePath = Join-Path -Path $PSScriptRoot -ChildPath '..\NTFSSecurity\bin\Release\NTFSSecurity.psd1' |
|||
$module = Import-Module -Name $modulePath -Force -PassThru -ErrorAction Stop |
|||
$pagePath = Join-Path -Path $PSScriptRoot -ChildPath '..\Docs\Cmdlets' |
|||
|
|||
<# |
|||
With this test hook, Get-Help -Online returns the URI instead of opening a browser. In PowerShell 7, |
|||
the hook also makes Get-Help ignore the help file, so this test runs only in Windows PowerShell. |
|||
#> |
|||
$testHooks = [psobject].Assembly.GetType('System.Management.Automation.Internal.InternalTestHooks') |
|||
$bypassOnlineHelp = if ($testHooks -and $PSVersionTable.PSEdition -ne 'Core') { |
|||
$testHooks.GetField('BypassOnlineHelpRetrieval', [Reflection.BindingFlags] 'NonPublic, Static') |
|||
} |
|||
} |
|||
|
|||
AfterAll { |
|||
Remove-Module -Name NTFSSecurity -Force -ErrorAction SilentlyContinue |
|||
} |
|||
|
|||
It 'Should ship the help file in the en-US folder' { |
|||
Join-Path -Path $module.ModuleBase -ChildPath 'en-US\NTFSSecurity.dll-Help.xml' | Should -Exist |
|||
} |
|||
|
|||
It 'Should have a page in Docs/Cmdlets for every exported cmdlet' { |
|||
$pageNames = (Get-ChildItem -Path $pagePath -Filter '*.md').BaseName | Sort-Object |
|||
$cmdletNames = (Get-Command -Module NTFSSecurity -CommandType Cmdlet).Name | Sort-Object |
|||
|
|||
$cmdletNames -join ', ' | Should -BeExactly ($pageNames -join ', ') |
|||
} |
|||
|
|||
Context '<CommandName>' -ForEach $helpPages { |
|||
BeforeAll { |
|||
$help = Get-Help -Name $CommandName -Full |
|||
} |
|||
|
|||
It 'Should show the synopsis from Docs/Cmdlets' { |
|||
"$($help.Synopsis)".Trim() | Should -BeExactly $Synopsis |
|||
} |
|||
|
|||
It 'Should describe the parameters from Docs/Cmdlets' { |
|||
$describedParameterNames = foreach ($parameter in $help.parameters.parameter) { |
|||
if (($parameter.description.Text -join '').Trim()) { |
|||
$parameter.name |
|||
} |
|||
} |
|||
|
|||
($describedParameterNames | Sort-Object) -join ', ' | |
|||
Should -BeExactly (($ParameterNames | Sort-Object) -join ', ') |
|||
} |
|||
|
|||
It 'Should show the <ExampleCount> examples from Docs/Cmdlets' { |
|||
@($help.examples.example | Where-Object -FilterScript { $_ }) | Should -HaveCount $ExampleCount |
|||
} |
|||
|
|||
It 'Should link to the online version from Docs/Cmdlets' { |
|||
@($help.relatedLinks.navigationLink)[0].uri | Should -BeExactly $OnlineUri |
|||
} |
|||
|
|||
It 'Should keep the space after each link in the help text' { |
|||
# platyPS writes an inline link as "text (url)" and drops the space that follows it. |
|||
$help | Out-String -Width 4096 | Should -Not -Match '\((?:\.\./|https?://)[^)\s]+\)\w' |
|||
} |
|||
|
|||
It 'Should open the online version with Get-Help -Online' { |
|||
if (-not $bypassOnlineHelp) { |
|||
$reason = 'the test hook for Get-Help -Online reads the help file only in Windows PowerShell' |
|||
Set-ItResult -Skipped -Because $reason |
|||
return |
|||
} |
|||
|
|||
$bypassOnlineHelp.SetValue($null, $true) |
|||
try { |
|||
$onlineHelp = Get-Help -Name $CommandName -Online |
|||
} finally { |
|||
$bypassOnlineHelp.SetValue($null, $false) |
|||
} |
|||
|
|||
"$onlineHelp" | Should -Match ('{0}$' -f [regex]::Escape($OnlineUri)) |
|||
} |
|||
} |
|||
} |
|||
Loading…
Reference in new issue