Skip to content

fix: Correct three defects in how a module is staged - #225

Open
tablackburn wants to merge 3 commits into
mainfrom
fix/210-211-212-staging
Open

fix: Correct three defects in how a module is staged#225
tablackburn wants to merge 3 commits into
mainfrom
fix/210-211-212-staging

Conversation

@tablackburn

Copy link
Copy Markdown
Contributor

Summary

Fixes three defects in Build-PSBuildModule's staging logic, sequenced #211#210#212
because each is only visible once the one before it is fixed. Closes #210, #211, #212.

Host-dependence, measured

-Depth with -Include degrades to a full -Recurse on Windows PowerShell 5.1. Same glob,
same tree (tests/), two hosts:

Host before after
PowerShell 7.6.5 root + depth 1 root only
Windows PowerShell 5.1 11 matches, down to depth 3 root only (2)

Readme discovery, on 5.1: before, tests/TestModule/README.md came back first and
Select-Object -First 1 would have taken it. After: the project root's readme, on both hosts.

Staging, before and after

Fixture built with CopyDirectories = @(), a readme, a hand-written en-US about topic, and
a bin/ holding no help (bin is the culture name for Bini).

before / compile after / compile before / non-compile after / non-compile
stray root Messages.psd1 present gone present gone
en-US/Messages.psd1 dropped staged staged staged
about topic content readme hand-written hand-written hand-written
warning when readme skipped yes none yes
bin/ staged no no n/a (bulk copy) n/a

Closing the blind spot

tests/fixtures/PSBuildTestFixture had no culture directory, no .psd1 below its root and
no about topic, so the suite was structurally incapable of seeing any of these three — which
is how all of them survived since 2018. It now ships en-US/Messages.psd1 and a hand-written
en-US/about_PSBuildTestFixture.help.txt.

Assertions that moved because of it, each deliberate:

Test plan

Copilot AI lite review requested due to automatic review settings August 28, 2026 22:07

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

tablackburn and others added 3 commits August 28, 2026 18:10
PSBuildTestFixture had no culture directory, no .psd1 below its root and no
about topic, so the staging tests were structurally incapable of observing
#210, #211 or #212. All three have been reachable since
2018 with the suite green.

Adds en-US/Messages.psd1 and a hand-written en-US/about_PSBuildTestFixture.help.txt
and asserts both in the fixture layout test.

Narrows one assertion in Build-PSBuildHelp.tests.ps1 as a consequence.
Microsoft.PowerShell.PlatyPS 1.x warns "File '' is not a valid help file type"
for every file in the module's locale directory that is not the generated MAML,
a hand-written about topic included, and with an empty name in its own message.
That is upstream behavior about what the module ships, not the docs-tree defect
the context pins, so it now asserts that no landing-page warning is reported
rather than that no warning at all is.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011GYJrhbrDzqufaeMqD9QjT
Sequenced #211, #210, #212, because each one is only visible once the one
before it is fixed.

#211: the loose-file glob used -Path $Path with -Include
and -Depth 1, so it recursed one level and copied en-US/Messages.psd1 flat into
the output root, where nothing reads it. Both halves of the fix are required:
the trailing wildcard alone still matches the culture directory, and dropping
-Depth alone matches nothing at all, because without recursion -Include filters
against the leaf of -Path. On Windows PowerShell 5.1, -Depth with -Include
degrades to a full -Recurse, so files at any depth were flattened into the root
and the contents of a package depended on which host built it. The same pattern
in the readme discovery in psakeFile.ps1 and IB.tasks.ps1 is fixed with it.

#210: compile mode staged the loose root files and
CopyDirectories and nothing else, so a hand-written about topic never reached
the output unless CopyDirectories happened to name the culture directory.
Compile mode now stages a source culture directory on its own. Get-PSBuildHelpLocale
answers which directories are cultures, but deliberately over-reports -- 'bin'
is Bini and 'ps' is Pashto -- so staging is decided by content: an about topic,
MAML help, or localized data.

#212: the two modes disagreed about whether a source about
topic or the readme won, by accident of statement ordering. A source about topic
now wins in both, with a warning, because ConvertReadMeToAboutHelp performs no
conversion -- it is a plain copy of the Markdown, which is not a conformant
about topic. The guard tests the source about *file*, which is narrower than
the culture *directory* guard #207 removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011GYJrhbrDzqufaeMqD9QjT
One changelog entry per issue, and migration entries for the two changes a
consumer can see on upgrade: the output root loses a stray copy of a culture
directory's .psd1 and the readme now has to be at the project root to be
found (#211), and a hand-written about topic now wins over
ConvertReadMeToAboutHelp with a warning (#212).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011GYJrhbrDzqufaeMqD9QjT
@tablackburn
tablackburn force-pushed the fix/210-211-212-staging branch from 8aa718c to f97dac2 Compare August 28, 2026 22:10
@github-actions

Copy link
Copy Markdown

Test Results

    4 files  ± 0    909 suites  +20   2m 9s ⏱️ -18s
  613 tests +17    610 ✅ +17   3 💤 ±0  0 ❌ ±0 
2 435 runs  +68  2 363 ✅ +68  72 💤 ±0  0 ❌ ±0 

Results for commit f97dac2. ± Comparison against base commit 3ea9e82.

This pull request removes 2 and adds 19 tests. Note that renamed tests count towards both.
Build-PSBuildModule.Converting the readme into about help.Writes the readme as the about help file in the culture directory
Build-PSBuildModule.Converting the readme into about help.Writes the readme content unchanged
Build-PSBuildModule.Building with compilation.Does not flatten a culture directory file into the output root
Build-PSBuildModule.Building with compilation.Does not stage a directory that only shares a name with a culture
Build-PSBuildModule.Building with compilation.Stages Messages.psd1 in the culture directory without CopyDirectories naming it
Build-PSBuildModule.Building with compilation.Stages about_PSBuildTestFixture.help.txt in the culture directory without CopyDirectories naming it
Build-PSBuildModule.Building without compilation.Does not flatten a culture directory file into the output root
Build-PSBuildModule.Building without compilation.Stages Messages.psd1 in the culture directory
Build-PSBuildModule.Building without compilation.Stages about_PSBuildTestFixture.help.txt in the culture directory
Build-PSBuildModule.Choosing the about help culture.Leaves the hand-written topic in its own culture directory alone
Build-PSBuildModule.Converting the readme into about help when compiling.Emits no warning
Build-PSBuildModule.Converting the readme into about help when compiling.Keeps the rest of the source culture directory
…

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants