🩹 [Patch]: Framework artifacts stay under .PSModule (#540)

Framework-generated artifacts now stay under the consumer repository's
`.PSModule` directory instead of root-level `outputs`, `_site`,
`TestResult`, and `CodeCoverage` paths. Invoke-Pester keeps its internal
`.temp` state at `[System.IO.Path]::GetTempPath()/Invoke-Pester`,
outside the consumer worktree.

## Changed: Framework artifact directory

- Built modules use `.PSModule/module`.
- Generated documentation uses `.PSModule/docs`.
- Zensical workspace and GitHub Pages payload use `.PSModule/site`, with
generated HTML at `.PSModule/site/_site`.
- Framework tests write reports to
`<WorkingDirectory>/.PSModule/TestResult/<suite>-TestResult-Report.xml`
and
`<WorkingDirectory>/.PSModule/CodeCoverage/<suite>-CodeCoverage-Report.xml`
through Invoke-Pester's existing report-path inputs.
- Build, test, lint, publish, release, artifact download/upload, Pages,
action defaults, implementation tests, fixtures, and references use the
new locations.
- Aggregation-runner-only `CodeCoverage/`, `CodeCoverage-MissedPaths/`,
`TestResults/`, and `super-linter-output/` locations are unchanged.

## Adopting this release

No consumer configuration, code, or invocation changes are required.
`workflow.yml` is the supported consumer contract; component actions,
nested reusable workflows, and their intermediate artifact paths are
internal implementation details.

## Release impact

- Effective decision: `release:patch`.
- Semantic effect: Patch release; the supported `workflow.yml` contract
is unchanged.

## Invoke-Pester compatibility

This change uses Invoke-Pester v5.1.1, pinned to its immutable release
commit `c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb`. The release includes
PSModule/Invoke-Pester#78, which honors the existing
`TestResult_OutputPath` and `CodeCoverage_OutputPath` action inputs used
for the `.PSModule` report paths.

## Technical details

- Fixture assertions require generated documentation under
`.PSModule/docs`.
- Focused Pester tests cover publish and release paths.
- A focused site experiment verifies `.PSModule/site/_site` is produced
without legacy root artifact directories.
- Changed workflow YAML files parse successfully.

Author: MariusStorhaug

.github/actions/Build-PSModule/action.yml

@@ -9,7 +9,7 @@ inputs:
   OutputFolder:
     description: Path to the folder where the built module is outputted.
     required: false
-    default: 'outputs/module'
+    default: '.PSModule/module'
   Version:
     description: Module version to stamp into the manifest.
     required: true

.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleManifest.ps1

@@ -28,7 +28,7 @@
         [Parameter(Mandatory)]
         [string] $ModuleName,
 
-        # Folder where the built modules are outputted. 'outputs/modules/MyModule'
+        # Folder where the built module is outputted. '.PSModule/module/MyModule'
         [Parameter(Mandatory)]
         [System.IO.DirectoryInfo] $ModuleOutputFolder,
 

.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleRootModule.ps1

@@ -43,7 +43,7 @@
         [Parameter(Mandatory)]
         [string] $ModuleName,
 
-        # Folder where the built modules are outputted. 'outputs/modules/MyModule'
+        # Folder where the built module is outputted. '.PSModule/module/MyModule'
         [Parameter(Mandatory)]
         [System.IO.DirectoryInfo] $ModuleOutputFolder
     )

.github/actions/Build-ZensicalSite/README.md

@@ -1,6 +1,6 @@
 # Build-ZensicalSite
 
-Builds Zensical documentation site output and normalizes it to `<working-directory>/_site`.
+Builds Zensical documentation site output at `<working-directory>/.PSModule/site/_site`.
 
 ## Inputs
 

.github/actions/Build-ZensicalSite/src/build-zensical-site.ps1

@@ -6,24 +6,17 @@ param(
 $ErrorActionPreference = 'Stop'
 
 $resolvedWorkingDirectory = Resolve-Path -Path $WorkingDirectory | Select-Object -ExpandProperty Path
-$siteWorkingDirectory = Join-Path -Path $resolvedWorkingDirectory -ChildPath 'outputs/site'
-$outputSitePath = Join-Path -Path $resolvedWorkingDirectory -ChildPath '_site'
+$siteWorkingDirectory = Join-Path -Path $resolvedWorkingDirectory -ChildPath '.PSModule/site'
+$outputSitePath = Join-Path -Path $siteWorkingDirectory -ChildPath '_site'
 
 Set-Location -Path $siteWorkingDirectory
 
 if (-not (Test-Path -Path 'zensical.toml')) {
-    throw "No documentation config file found in outputs/site. Expected zensical.toml."
+    throw "No documentation config file found in .PSModule/site. Expected zensical.toml."
 }
 
 zensical build --config-file 'zensical.toml'
 
-if (Test-Path -Path '_site') {
-    if (Test-Path -Path $outputSitePath) {
-        Remove-Item -Path $outputSitePath -Recurse -Force
-    }
-    Move-Item -Path '_site' -Destination $outputSitePath -Force
-}
-
 if (-not (Test-Path -Path $outputSitePath)) {
     throw "Expected Zensical output at $outputSitePath but it was not created."
 }

.github/actions/Build-ZensicalSite/src/main.ps1

@@ -2,11 +2,11 @@
 
 <#
     .SYNOPSIS
-    Builds the Zensical site and normalizes output to the expected _site path.
+    Builds the Zensical site under the framework artifact directory.
 
     .DESCRIPTION
-    Runs zensical build from outputs/site and moves the generated _site directory
-    to <WorkingDirectory>/_site for downstream workflow steps.
+    Runs zensical build from .PSModule/site. The generated site remains at
+    <WorkingDirectory>/.PSModule/site/_site for downstream workflow steps.
 
     .EXAMPLE
     ./main.ps1 -WorkingDirectory '.'
@@ -19,32 +19,25 @@
 #>
 [CmdletBinding()]
 param(
-    # Build working directory containing outputs/site and destination _site.
+    # Build working directory containing the Zensical project and output.
     [Parameter(Mandatory)]
     [string]$WorkingDirectory
 )
 
 $ErrorActionPreference = 'Stop'
 
 $resolvedWorkingDirectory = Resolve-Path -Path $WorkingDirectory | Select-Object -ExpandProperty Path
-$siteWorkingDirectory = Join-Path -Path $resolvedWorkingDirectory -ChildPath 'outputs/site'
-$outputSitePath = Join-Path -Path $resolvedWorkingDirectory -ChildPath '_site'
+$siteWorkingDirectory = Join-Path -Path $resolvedWorkingDirectory -ChildPath '.PSModule/site'
+$outputSitePath = Join-Path -Path $siteWorkingDirectory -ChildPath '_site'
 
 Set-Location -Path $siteWorkingDirectory
 
 if (-not (Test-Path -Path 'zensical.toml')) {
-    throw "No documentation config file found in outputs/site. Expected zensical.toml."
+    throw "No documentation config file found in .PSModule/site. Expected zensical.toml."
 }
 
 zensical build --config-file 'zensical.toml'
 
-if (Test-Path -Path '_site') {
-    if (Test-Path -Path $outputSitePath) {
-        Remove-Item -Path $outputSitePath -Recurse -Force
-    }
-    Move-Item -Path '_site' -Destination $outputSitePath -Force
-}
-
 if (-not (Test-Path -Path $outputSitePath)) {
     throw "Expected Zensical output at $outputSitePath but it was not created."
 }

.github/actions/Document-PSModule/src/main.ps1

@@ -40,8 +40,8 @@ Get-ChildItem -Path $path -Filter '*.ps1' -Recurse | Resolve-Path -Relative | Fo
 Write-Host '::group::Loading inputs'
 $env:GITHUB_REPOSITORY_NAME = $env:GITHUB_REPOSITORY -replace '.+/'
 $moduleSourceFolderPath = Resolve-Path -Path 'src' | Select-Object -ExpandProperty Path
-$modulesOutputFolderPath = Join-Path -Path . -ChildPath 'outputs/module'
-$docsOutputFolderPath = Join-Path -Path . -ChildPath 'outputs/docs'
+$modulesOutputFolderPath = Join-Path -Path . -ChildPath '.PSModule/module'
+$docsOutputFolderPath = Join-Path -Path . -ChildPath '.PSModule/docs'
 
 $params = @{
     ModuleName              = [string]::IsNullOrEmpty($Name) ? $env:GITHUB_REPOSITORY_NAME : $Name

.github/actions/Inject-SiteScripts/README.md

@@ -13,6 +13,6 @@ Injects JavaScript snippets from `.github/scripts/site-injectors/*.js` into gene
 - name: Inject shared site scripts
   uses: ./_wf/.github/actions/Inject-SiteScripts
   with:
-    SitePath: ./_site
+    SitePath: ./.PSModule/site/_site
     WorkflowPath: _wf
 ```

.github/actions/Inject-SiteScripts/src/main.ps1

@@ -9,7 +9,7 @@
     repository and injects each script into every HTML file under SitePath, once per file.
 
     .EXAMPLE
-    ./main.ps1 -SitePath './_site' -WorkflowPath '_wf'
+    ./main.ps1 -SitePath './.PSModule/site/_site' -WorkflowPath '_wf'
 
     .INPUTS
     None.

.github/actions/Publish-PSModule/README.md

@@ -7,7 +7,7 @@ Publishes a pre-versioned PowerShell module artifact to the PowerShell Gallery.
 | Name | Description | Required | Default |
 | --- | --- | --- | --- |
 | `Name` | Name of the module to publish. | No | Repository name |
-| `ModulePath` | Path containing the built `<Name>/` module directory. | No | `outputs/module` |
+| `ModulePath` | Path containing the built `<Name>/` module directory. | No | `.PSModule/module` |
 | `ArtifactName` | Name of the module artifact to download. | No | `module` |
 | `PSGALLERY_API_KEY` | PowerShell Gallery API key. | Yes | N/A |
 | `WhatIf` | Logs publishing operations without publishing the module. | No | `false` |
@@ -24,7 +24,7 @@ This action does not provide outputs.
   uses: ./.github/actions/Publish-PSModule
   with:
     Name: ExampleModule
-    ModulePath: outputs/module
+    ModulePath: .PSModule/module
     ArtifactName: module
     PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
 ```