Nothing tests the Build-PSBuildUpdatableHelp branch that deletes a consumer's output directory

[tablackburn]

Build-PSBuildUpdatableHelp contains the only code path in the module that deletes files a consumer may care about, and no test exercises it.

The branch

if (-not (Test-Path -LiteralPath $OutputPath)) {
    New-Item @newItemSplat > $null
} else {
    Write-Verbose ($LocalizedData.DirectoryAlreadyExists -f $OutputPath)
    $removeItemSplat = @{
        Recurse = $true
        Force   = $true
        Verbose = ($VerbosePreference -eq 'Continue')
    }
    Get-ChildItem $OutputPath | Remove-Item @removeItemSplat
}

Get-ChildItem with no -Filter, then Remove-Item -Recurse -Force. Everything in OutputPath goes, whether PowerShellBuild wrote it or not.

Measured

Pointing the function at an OutputPath that already holds a previous build's output plus a directory PowerShellBuild never created:

BEFORE:
  \PreviousBuild.cab
  \Probe_HelpInfo.xml
  \consumer-subfolder
  \consumer-subfolder\notes.txt

AFTER:
  (empty)

The deletion happens before any cabinet is written, so it also happens on a run that then fails — in the measurement above New-HelpCabinetFile errored afterwards, and the consumer was left with an empty directory and no new cabinet.

Nothing reaches it

Every call site in the suite supplies a fresh OutputPath that does not yet exist, so the New-Item branch is the only one taken:

• tests/Build-PSBuildHelp.tests.ps1 calls the function three times (lines 214, 271, 330), each with a UpdatableHelpPath from a distinct New-PSBuildDocsScenario. That helper returns <scenario>/Output/UpdatableHelp from a freshly copied fixture, and the fixture (tests/fixtures/PSBuildTestFixture) contains no Output directory. Nothing pre-creates the path, and no scenario is used twice.
• tests/build.tests.ps1 runs the GenerateUpdatableHelp task once, in a job, and its AfterAll removes the output path afterwards.

There is no assertion anywhere that stale content is removed, and none that content outside PowerShellBuild's own output survives or does not.

Why it matters

$PSBPreference.Docs.UpdatableHelpOutDir is a consumer-set path. A consumer who points it at a directory that holds anything else — a checked-in HelpInfo.xml, a hand-maintained README, a sibling artifact directory, or in the worst case a path chosen carelessly — loses all of it on the next GenerateUpdatableHelp, silently, at Write-Verbose level.

The behaviour itself is defensible: leaving a previous build's cabinets in place would produce an output directory holding cabinets for commands that no longer exist, and the function's own comments explain that half-produced output is what the surrounding guards exist to prevent. What is not defensible is that it is the module's only destructive operation and the one behaviour with no test at all. Every other file-touching path in Build-PSBuildUpdatableHelp — the manifest guard, the HelpInfoUri guard, the missing landing page, the missing locale directory — was covered in #149 and #124. This one was not.

It is also cheap to test. The scenario helper already produces the directory layout; the test is one New-Item on UpdatableHelpPath and one sentinel file before the call.

Options

1. Test the branch as written. Pre-create OutputPath, drop a sentinel file and a sentinel subdirectory in it, run the function, and assert both are gone and the new cabinet is present. Cheap, and it pins the current contract so a future refactor cannot quietly change it in either direction.
2. Test it and narrow what is deleted. Remove only what this function produces — *.cab, *.zip, *HelpInfo.xml — rather than the whole directory. Safer for a consumer who shares the directory, and it still solves the stale-cabinet problem the wholesale delete exists for. It does leave a cabinet behind if the locale ever changes, which the current behaviour handles.
3. Test it and require the directory to be PowerShellBuild's. Refuse, or warn, when OutputPath already contains files that do not match the produced set. Most protective, most surprising, and it would break a consumer whose directory legitimately holds something else.
4. Test it and document it. Keep the behaviour, and say in the README's settings table that $PSBPreference.Docs.UpdatableHelpOutDir is cleared on every run. Whatever else is done, the table currently says nothing about it, and a consumer cannot learn this except by losing something.

(1) plus (4) is the minimum that makes the behaviour deliberate rather than incidental. (2) is worth weighing on its own merits, but the test should exist regardless of which behaviour is chosen — writing it first is what makes the choice visible.

Related: #149 (which added the rest of this function's coverage), #124 (the docs-tree locale handling immediately above this branch).

[tablackburn]

Milestoned to v1.1.0 rather than v1.0.0. Recording the reasoning so it does not have to be worked out again.

The deletion is real, but reaching it requires every one of the following:

1. The consumer explicitly invokes GenerateUpdatableHelp. BuildHelp defaults to @('GenerateMarkdown', 'GenerateMAML'), so GenerateUpdatableHelp depends on BuildHelp while nothing depends on GenerateUpdatableHelp. It is a leaf task that no default chain reaches.
2. The build is running on Windows. Build-PSBuildUpdatableHelp warns and returns otherwise.
3. Microsoft.PowerShell.PlatyPS is installed, or the task's PreCondition skips it.
4. The module manifest declares a HelpInfoUri, or the function warns and returns.
5. At least one locale has both a landing page and MAML, or if (-not $cabinetWork) { return } fires.
6. OutputPath already exists with content, which means at least a second run.

The realistic failure this branch suggests -- clearing the directory and then producing nothing -- is already guarded. The $cabinetWork loop above deliberately computes what can be built before touching OutputPath, with a comment giving that exact rationale.

What remains, and is worth covering when this is picked up: the clear still happens before New-HelpCabinetFile runs, so a failure part-way through leaves an emptied directory where a working cabinet used to be. That is ordinary build-output-directory behaviour, recoverable by re-running a task the consumer explicitly asked for, which is why it is not a 1.0.0 blocker. It is still the case worth asserting on when the test is written.