build: modernize build system with PowerShellBuild and GitHub Actions (#163)

## Summary

- Replaces `psake.ps1` with `psakeFile.ps1` using PowerShellBuild
`-FromModule` task delegation
- Rewrites `build.ps1` with `-Bootstrap` switch and PSDepend-managed
dependencies (pinned to known-good versions)
- Adds `requirements.psd1` with pinned versions: psake 4.9.1,
PowerShellBuild 0.7.2, Pester 5.7.1, PSScriptAnalyzer 1.19.1,
BuildHelpers 2.0.16
- Replaces `appveyor.yml` with `.github/workflows/ci.yml`
(ubuntu/windows/macOS matrix, `./build.ps1 -Bootstrap -Task Test`)
- Adds PlatyPS markdown stubs in `docs/en-US/` for all public functions
- Removes `deploy.psdeploy.ps1` (superseded by PowerShellBuild `Publish`
task)

## Test plan

- [x] `./build.ps1 -Bootstrap -Task Test` passes locally on Windows
- [ ] CI matrix passes on ubuntu/windows/macOS via GitHub Actions

Closes #149

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: HeyItsGilbert

.github/workflows/ci.yml

@@ -10,13 +10,15 @@ on:
       - 'PSDepend/**'
       - 'Tests/**'
       - 'build.ps1'
-      - 'psake.ps1'
+      - 'psakeFile.ps1'
+      - 'requirements.psd1'
   pull_request:
     paths:
       - 'PSDepend/**'
       - 'Tests/**'
       - 'build.ps1'
-      - 'psake.ps1'
+      - 'psakeFile.ps1'
+      - 'requirements.psd1'
   workflow_dispatch:
 
 jobs:
@@ -29,15 +31,15 @@ jobs:
         os: [ubuntu-latest, windows-latest, macOS-latest]
     steps:
       - uses: actions/checkout@v4
-      - name: Test
+      - name: Bootstrap and Test
         shell: pwsh
-        run: ./build.ps1 -Task Test
+        run: ./build.ps1 -Bootstrap -Task Test
       - name: Upload Test Results
         if: always()
         uses: actions/upload-artifact@v4
         with:
           name: testResults-${{ matrix.os }}
-          path: ./Tests/out/testResults.xml
+          path: ./Output/testResults.xml
 
   publish-test-results:
     name: Publish Test Results

appveyor.yml

@@ -1,18 +1,62 @@
-[CmdletBinding()]
-param (
-    [parameter(Position = 0)]
-    [ValidateSet('Default','Init','Test','Build','Deploy')]
-    $Task = 'Default'
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSReviewUnusedParameter',
+    'Command',
+    Justification = 'false positive'
+)]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSReviewUnusedParameter',
+    'Parameter',
+    Justification = 'false positive'
+)]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSReviewUnusedParameter',
+    'CommandAst',
+    Justification = 'false positive'
+)]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSReviewUnusedParameter',
+    'FakeBoundParams',
+    Justification = 'false positive'
+)]
+[CmdletBinding(DefaultParameterSetName = 'task')]
+param(
+    [parameter(ParameterSetName = 'task', Position = 0)]
+    [ArgumentCompleter( {
+            param($Command, $Parameter, $WordToComplete, $CommandAst, $FakeBoundParams)
+            try {
+                Get-PSakeScriptTasks -BuildFile './psakeFile.ps1' -ErrorAction 'Stop' |
+                    Where-Object { $_.Name -like "$WordToComplete*" } |
+                    Select-Object -ExpandProperty 'Name'
+            } catch {
+                @()
+            }
+        })]
+    [string[]]$Task = 'default',
+    [switch]$Bootstrap,
+    [parameter(ParameterSetName = 'Help')]
+    [switch]$Help
 )
 
-# Grab nuget bits, install modules, set build variables, start build.
-Get-PackageProvider -Name NuGet -ForceBootstrap | Out-Null
+$ErrorActionPreference = 'Stop'
+$psakeFile = './psakeFile.ps1'
 
-Install-Module Psake, PSDeploy, BuildHelpers -force -AllowClobber -Scope CurrentUser
-Install-Module Pester -RequiredVersion 4.10.1 -Force -AllowClobber -SkipPublisherCheck -Scope CurrentUser
-Import-Module Psake, BuildHelpers
+if ($Bootstrap) {
+    if (-not (Get-PackageProvider -Name NuGet -ErrorAction SilentlyContinue)) {
+        Install-PackageProvider -Name NuGet -Force -Scope CurrentUser | Out-Null
+    }
+    Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
+    if (-not (Get-Module -Name PSDepend -ListAvailable)) {
+        Install-Module -Name PSDepend -Repository PSGallery -Scope CurrentUser -Force -RequiredVersion '0.3.8'
+    }
+    Import-Module -Name PSDepend -Verbose:$false
+    Invoke-PSDepend -Path './requirements.psd1' -Install -Import -Force -WarningAction SilentlyContinue
+}
 
-Set-BuildEnvironment -ErrorAction SilentlyContinue
-
-Invoke-psake -buildFile $ENV:BHProjectPath\psake.ps1 -taskList $Task -nologo
-exit ( [int]( -not $psake.build_success ) )
+if ($PSCmdlet.ParameterSetName -eq 'Help') {
+    Get-PSakeScriptTasks -BuildFile $psakeFile |
+        Format-Table -Property Name, Description, Alias, DependsOn
+} else {
+    Set-BuildEnvironment -Force
+    Invoke-Psake -BuildFile $psakeFile -TaskList $Task -NoLogo
+    exit ([int](-not $psake.build_success))
+}

build.ps1

@@ -0,0 +1,162 @@
+---
+external help file: PSDepend-help.xml
+Module Name: PSDepend
+online version: https://github.com/PowerShellOrg/PSDepend
+schema: 2.0.0
+---
+
+# Get-Dependency
+
+## SYNOPSIS
+
+Read a dependency psd1 file.
+
+## SYNTAX
+
+### File (Default)
+```
+Get-Dependency [-Path <String[]>] [-Tags <String[]>] [-Recurse] [-Credentials <Hashtable>]
+ [-ProgressAction <ActionPreference>] [<CommonParameters>]
+```
+
+### Hashtable
+```
+Get-Dependency [-Tags <String[]>] [-InputObject <Hashtable[]>] [-Credentials <Hashtable>]
+ [-ProgressAction <ActionPreference>] [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+Reads a PSDepend dependency file (.psd1) and returns structured dependency objects.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+Get-Dependency -Path .\requirements.psd1
+```
+
+Returns all dependencies defined in requirements.psd1.
+
+### Example 2
+
+```powershell
+Get-Dependency -Path . -Recurse -Tags 'prod'
+```
+
+Recursively finds all dependency files under the current directory and returns dependencies tagged 'prod'.
+
+## PARAMETERS
+
+### -Path
+
+Path to project root or a specific dependency file.
+
+```yaml
+Type: String[]
+Parameter Sets: File
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Tags
+
+Limit results to dependencies with one or more matching tags.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Recurse
+
+Search recursively for dependency files under Path.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: File
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -InputObject
+
+Treat a hashtable as dependency file contents rather than reading from disk.
+
+```yaml
+Type: Hashtable[]
+Parameter Sets: Hashtable
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Credentials
+
+Hashtable of PSCredentials keyed by credential name for private feeds.
+
+```yaml
+Type: Hashtable
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ProgressAction
+{{ Fill ProgressAction Description }}
+
+```yaml
+Type: ActionPreference
+Parameter Sets: (All)
+Aliases: proga
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### System.Collections.Hashtable[]
+
+## OUTPUTS
+
+### PSDepend.Dependency
+
+## NOTES
+
+## RELATED LINKS
+
+[Invoke-PSDepend](Invoke-PSDepend.md)