Compiling drops a hand-written about_<Module>.help.txt unless CopyDirectories names the culture directory

[tablackburn]

Found while surveying how consumers configure PowerShellBuild, for the decisions on #206 and #207. Verified in packages already published to the PowerShell Gallery, so this is affecting real modules today rather than being a hypothetical.

What happens

In compile mode, Build-PSBuildModule stages only three things into the output:

1. *.psm1, *.psd1 and *.ps1xml at depth 1
2. whatever $PSBPreference.Build.CopyDirectories names
3. the concatenated *.ps1 files from CompileDirectories, written into the root module

A hand-written en-US/about_<Module>.help.txt in the source tree is none of those. It is silently left behind, and the built module ships without its about topic. The build reports success.

Non-compile mode is unaffected: it does a bulk Copy-Item $Path/* -Recurse -Force, so the whole source tree including en-US/ arrives in the output.

Evidence from published packages

Downloaded the .nupkg for five consumers that ship a hand-written about topic in source:

Module	CopyDirectories	About topic in the published package
PowerShellOrg/Plaster	@(en-US, Schema, Templates)	ships
PowerShellOrg/PSDepend	@(PSDependScripts, en-US)	ships
diecknet/DavinciTimestamp	not set	dropped
poshbotio/PoshBot.FYI	not set	dropped
pauby/PsTodoTxt	not set	dropped

All five have about_*.help.txt in their source tree. The only thing separating the two groups is whether CopyDirectories happens to name the culture directory.

For the three affected modules the published en-US/ contains only the platyPS-generated MAML (<Module>-help.xml). Get-Help about_<Module> returns nothing for their users.

Why it is easy to miss

Nothing warns. The consumer sees a green build and a package that looks complete, and the file they wrote is simply absent. It is the same shape as #201 and #207 — a plausible-looking artifact with something quietly missing — and the three affected authors presumably do not know.

It is also not obvious from the settings. CopyDirectories reads as an escape hatch for extra content, not as the mechanism by which help files reach the output; a consumer who ships an about topic has no particular reason to think it applies to them.

Scope

14 of the 86 surveyed public consumers ship a hand-written about topic. Four of those compile. Three of the four are affected; the fourth (Plaster) is safe only because it sets CopyDirectories for unrelated reasons.

Options

1. Stage <Culture>/ automatically in compile mode, the way *.psd1 and *.psm1 are staged, since a culture directory is part of a module rather than incidental content. Closest to what a consumer expects, and makes CopyDirectories = @("en-US") unnecessary rather than load-bearing.
2. Stage any about_*.help.txt found under a culture directory, narrower than (1) — it would not bring Messages.psd1 or other localized data along, which some modules do want and others may not.
3. Warn when compiling if a culture directory exists in source and CopyDirectories does not name it. No behavior change; makes the silent drop visible. Weakest, but the least likely to surprise anyone.
4. Document it in the CopyDirectories settings row and the README. Cheapest; leaves three published modules broken and the next consumer to hit it none the wiser.

I lean (1). A module's culture directory carries its localized data and its about topics, and dropping it while carefully copying the manifest is hard to justify as intended behavior. But it changes what lands in the output for every compiling consumer, so it is a maintainer call.

Related: #206 and #207 are also in Build-PSBuildModule's staging logic, and #207 in particular concerns the same culture directory. Worth deciding the three together.

[tablackburn]

Worth fixing alongside this: the reason nothing caught #210, #211 or #212.

Two blind spots compound, and neither is about the staging code itself.

PowerShellBuild does not build itself with Build-PSBuildModule. The repository's own Build task is a plain bootstrap:

Copy-Item -Path "$($settings.SUT)/*" -Destination $settings.ModuleOutDir -Recurse

So the staging code never runs against this repository's own source during its own build. That is a defensible bootstrap choice, but it does mean the module's output is not evidence that the module's staging works.

The one place staging is exercised -- tests/fixtures/PSBuildTestFixture via build.tests.ps1 -- has no culture directory. The whole fixture is:

PSBuildTestFixture/
    excludeme.txt
    PSBuildTestFixture.psd1
    PSBuildTestFixture.psm1
    Private/Test-WidgetName.ps1
    Public/Get-Widget.ps1
    Public/Set-Widget.ps1

No en-US/, no .psd1 below the root, no about_*.help.txt. Every one of #210, #211 and #212 requires at least one of those three to be observable, so the suite is structurally incapable of seeing any of them.

That the bug is real is easy to confirm despite both blind spots -- running the shipped Build-PSBuildModule directly against this repository's own PowerShellBuild/ source stages Messages.psd1 into the output root:

--- root of staged output ---
   build.properties.ps1
   IB.tasks.ps1
   Messages.psd1          <-- #211
   PowerShellBuild.psd1
   PowerShellBuild.psm1
   psakeFile.ps1
   ScriptAnalyzerSettings.psd1

Suggestion: add a culture directory to the fixture -- en-US/Messages.psd1 and a hand-written en-US/about_PSBuildTestFixture.help.txt -- as part of whichever change fixes these. It costs two small files and makes all three defects detectable by tests that already run, in both compile and non-compile modes. Without it the fixes are only as good as their bespoke tests, and the next defect in this area is invisible again.