@danmoisan/drm-copilot-mcp 0.0.1

package/resources/powershell/PoshQC/PoshQC.Testing.psm1

@@ -0,0 +1,409 @@
+<#
+.SYNOPSIS
+Runs the bundled PoshQC suite in one pass.
+.DESCRIPTION
+Executes formatting, analysis, and Pester checks against the selected workspace root and scan folders.
+#>
+function Invoke-PoshQCSuite {
+    [CmdletBinding()]
+    param(
+        [string] $Root,
+        [string[]] $ScanFolders,
+        [string] $PssaSettingsPath = $script:PssaSettings,
+        [string] $PesterSettingsPath = $script:PesterSettings,
+        [string[]] $ExcludeDirs = $script:DefaultExcludedDirs,
+        [switch] $DisableKoverageCopy,
+        [string] $KoverageOutputPath
+    )
+
+    $ErrorActionPreference = 'Stop'
+
+    Invoke-PoshQCFormat -Root $Root -ScanFolders $ScanFolders -SettingsPath $PssaSettingsPath -ExcludeDirs $ExcludeDirs
+    Invoke-PoshQCAnalyze -Root $Root -ScanFolders $ScanFolders -SettingsPath $PssaSettingsPath -ExcludeDirs $ExcludeDirs
+    Invoke-PoshQCTest -Root $Root -ScanFolders $ScanFolders -SettingsPath $PesterSettingsPath -ExcludeDirs $ExcludeDirs -DisableKoverageCopy:$DisableKoverageCopy -KoverageOutputPath $KoverageOutputPath
+}
+
+<#
+.SYNOPSIS
+Converts coverage XML paths from absolute to relative.
+.DESCRIPTION
+Rewrites Pester coverage XML file paths to be relative to the repo root for Koverage compatibility.
+.PARAMETER InputPath
+Path to input coverage XML file.
+.PARAMETER OutputPath
+Path to write relative-path coverage XML.
+.PARAMETER RepoRoot
+Repository root directory for path relativization.
+.PARAMETER InputContent
+Alternative to InputPath - provide XML content directly.
+.PARAMETER PassThru
+Return the converted XML content as output.
+#>
+function Convert-PoshQCCoverageToRelative {
+    [CmdletBinding()]
+    param(
+        [Parameter()][string] $InputPath,
+        [Parameter()][string] $OutputPath,
+        [Parameter()][string] $RepoRoot,
+        [Parameter()][string] $InputContent,
+        [switch] $PassThru,
+        [scriptblock] $ResolvePath = { param([string] $Path) (Resolve-Path -Path $Path -ErrorAction Stop).Path },
+        [scriptblock] $JoinPath = { param([string] $Parent, [string] $Child) Join-Path -Path $Parent -ChildPath $Child },
+        [scriptblock] $TestPathExists = { param([string] $Path) Test-Path $Path },
+        [scriptblock] $ReadContent = { param([string] $Path) Get-Content -Path $Path -Raw },
+        [scriptblock] $WriteContent = { param([string] $Path, [string] $Content) Set-Content -Path $Path -Value $Content -Encoding UTF8 },
+        [scriptblock] $EnsureDirectory = {
+            param([string] $Path)
+            $dir = Split-Path -Parent $Path
+            if ($dir -and -not (Test-Path $dir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
+        },
+        [scriptblock] $GetDefaultOutputPath = {
+            param([string] $ResolvedInputPath, [string] $ResolvedRoot)
+            $coverageDir = if ($ResolvedInputPath) { Split-Path -Parent $ResolvedInputPath } else { $ResolvedRoot }
+            $coverageBase = if ($ResolvedInputPath) { [IO.Path]::GetFileNameWithoutExtension($ResolvedInputPath) } else { 'powershell-coverage' }
+            Join-Path -Path $coverageDir -ChildPath "$coverageBase.koverage.xml"
+        },
+        [scriptblock] $Logger = {
+            param([string] $Message)
+            Write-Information $Message -InformationAction Continue
+        }
+    )
+
+    $ErrorActionPreference = 'Stop'
+
+    if (-not $RepoRoot) {
+        $RepoRoot = $PWD.ProviderPath
+    }
+
+    if (-not $InputPath -and -not $InputContent) {
+        & $Logger 'No coverage input provided; skipping conversion.'
+        return
+    }
+
+    $resolvedRoot = $RepoRoot
+    try {
+        $maybeResolvedRoot = & $ResolvePath $RepoRoot
+        if ($maybeResolvedRoot) {
+            $resolvedRoot = if ($maybeResolvedRoot -is [string]) { $maybeResolvedRoot } else { $maybeResolvedRoot.Path }
+        }
+    }
+    catch {
+        $resolvedRoot = $RepoRoot
+    }
+
+    $resolvedInputPath = $null
+    if ($InputPath) {
+        $resolvedInputPath = if ([IO.Path]::IsPathRooted($InputPath)) { $InputPath } else { & $JoinPath $resolvedRoot $InputPath }
+        if (-not (& $TestPathExists $resolvedInputPath)) {
+            & $Logger "Coverage file not found; skipping Koverage output: $resolvedInputPath"
+            return
+        }
+
+        if (-not $InputContent) {
+            $InputContent = & $ReadContent $resolvedInputPath
+        }
+    }
+
+    $repoRootClean = ConvertTo-PoshQCPath $resolvedRoot
+    # Normalize to forward slashes for consistent regex matching across platforms
+    $repoRootNormalized = $repoRootClean -replace '\\', '/'
+    $escapedRoot = [regex]::Escape($repoRootNormalized)
+    # Replace forward slashes with character class that matches both separators
+    $flexiblePattern = $escapedRoot -replace '/', '[\\/]'
+    # Match both forward and backslashes after the path
+    $escapedPrefixPattern = "$flexiblePattern[\\/]"
+    $fixedContent = $InputContent -replace $escapedPrefixPattern, ''
+
+    if ($PassThru) {
+        return $fixedContent
+    }
+
+    if (-not $OutputPath) {
+        $OutputPath = & $GetDefaultOutputPath $resolvedInputPath $resolvedRoot
+    }
+
+    $resolvedOutputPath = if ([IO.Path]::IsPathRooted($OutputPath)) { $OutputPath } else { & $JoinPath $resolvedRoot $OutputPath }
+    & $EnsureDirectory $resolvedOutputPath
+    & $WriteContent $resolvedOutputPath $fixedContent
+    & $Logger "Wrote Koverage coverage copy: $resolvedOutputPath"
+}
+
+<#
+.SYNOPSIS
+Runs Pester tests with coverage reporting.
+.DESCRIPTION
+Executes Pester tests using repo configuration, generates coverage reports in multiple formats.
+.PARAMETER Root
+Root directory for test discovery. Defaults to current location.
+.PARAMETER ScanFolders
+Optional workspace-relative or workspace-contained folders to scan instead of the entire root.
+.PARAMETER SettingsPath
+Path to Pester configuration file.
+.PARAMETER ExcludeDirs
+Directory names to exclude from test/coverage paths.
+.PARAMETER KoverageOutputPath
+Custom path for Koverage-compatible coverage XML output.
+.PARAMETER DisableKoverageCopy
+Skip creation of Koverage-friendly coverage copy.
+.PARAMETER ScanFolders
+Optional workspace-relative or workspace-contained folders to scan instead of the entire root.
+#>
+function Invoke-PoshQCTest {
+    [CmdletBinding()]
+    param(
+        [string] $Root,
+        [string[]] $ScanFolders,
+        [string] $SettingsPath = $script:PesterSettings,
+        [string[]] $ExcludeDirs = $script:DefaultExcludedDirs,
+        [string] $KoverageOutputPath,
+        [switch] $DisableKoverageCopy,
+        [scriptblock] $EnsureModule = {
+            param([string] $Name, [string] $ErrorMessage)
+            if (-not (Get-Module -ListAvailable -Name $Name)) { throw $ErrorMessage }
+            Import-Module $Name -ErrorAction Stop
+        },
+        [scriptblock] $TestPathExists = { param([string] $Path) Test-Path $Path },
+        [scriptblock] $LoadSettings = { param([string] $Path) Import-PowerShellDataFile -Path $Path },
+        [scriptblock] $BuildConfiguration = { param($Settings) New-PesterConfiguration -Hashtable $Settings },
+        [scriptblock] $ExpandRunPaths = {
+            param($Config, [string] $RootPath, [string[]] $Excluded)
+            $initialPaths = if ($Config.Run.Path -is [System.Array]) { @($Config.Run.Path) } elseif ($Config.Run.Path -and $Config.Run.Path.Value) { @($Config.Run.Path.Value) } else { @() }
+            if ($initialPaths) {
+                $resolvedPaths = @(
+                    $initialPaths |
+                        ForEach-Object { Join-Path $RootPath $_ } |
+                            Where-Object { $Excluded -notcontains (Split-Path -Path $_ -Leaf) }
+                )
+                $Config.Run.Path = $resolvedPaths
+            }
+
+            if ($Excluded) {
+                $excludedPaths = @($Excluded | ForEach-Object { Join-Path $RootPath $_ })
+                $existingExclude = if ($Config.Run.ExcludePath -is [System.Array]) { @($Config.Run.ExcludePath | ForEach-Object { Join-Path $RootPath $_ }) } elseif ($Config.Run.ExcludePath -and $Config.Run.ExcludePath.Value) { @($Config.Run.ExcludePath.Value | ForEach-Object { Join-Path $RootPath $_ }) } else { @() }
+                $Config.Run.ExcludePath = $existingExclude + $excludedPaths
+            }
+
+            $Config
+        },
+        [scriptblock] $EnsureResultPath = {
+            param($Config, [string] $RootPath)
+            if ($Config.TestResult.Enabled.Value -and $Config.TestResult.OutputPath.Value) {
+                $resultPath = $Config.TestResult.OutputPath.Value
+                $resultDir = Split-Path -Parent $resultPath
+                if (-not [string]::IsNullOrWhiteSpace($resultDir)) {
+                    $resolvedResultDir = if ([IO.Path]::IsPathRooted($resultDir)) { $resultDir } else { Join-Path $RootPath $resultDir }
+                    New-Item -ItemType Directory -Path $resolvedResultDir -Force | Out-Null
+                }
+                $Config.TestResult.OutputPath = if ([IO.Path]::IsPathRooted($resultPath)) {
+                    $resultPath
+                } else {
+                    Join-Path $RootPath $resultPath
+                }
+            }
+            $Config
+        },
+        [scriptblock] $ResolveScanFolders = {
+            param([string] $RootPath, [string[]] $Folders)
+            Resolve-PoshQCScanFolder -Root $RootPath -ScanFolders $Folders
+        },
+        [scriptblock] $ExpandCoveragePaths = {
+            param($Config, [string] $RootPath)
+            if (-not $Config.CodeCoverage) { return $Config }
+
+            if ($Config.CodeCoverage.Path.Value) {
+                $Config.CodeCoverage.Path = @(
+                    $Config.CodeCoverage.Path.Value | ForEach-Object { if ([IO.Path]::IsPathRooted($_)) { $_ } else { Join-Path $RootPath $_ } }
+                )
+            }
+
+            if ($Config.CodeCoverage.OutputPath.Value) {
+                $coveragePath = $Config.CodeCoverage.OutputPath.Value
+                $coverageDir = Split-Path -Parent $coveragePath
+                if (-not [string]::IsNullOrWhiteSpace($coverageDir)) {
+                    $resolvedCoverageDir = if ([IO.Path]::IsPathRooted($coverageDir)) { $coverageDir } else { Join-Path $RootPath $coverageDir }
+                    New-Item -ItemType Directory -Path $resolvedCoverageDir -Force | Out-Null
+                }
+                $Config.CodeCoverage.OutputPath = if ([IO.Path]::IsPathRooted($coveragePath)) {
+                    $coveragePath
+                } else {
+                    Join-Path $RootPath $coveragePath
+                }
+            }
+
+            $Config
+        },
+        [scriptblock] $EnumerateTests = {
+            param([string[]] $Paths, [string[]] $Excluded, [scriptblock] $TestPathFn)
+            $tests = @()
+            foreach ($path in $Paths) {
+                if (-not (& $TestPathFn $path)) { continue }
+                $tests += Get-ChildItem -Path $path -Recurse -Include *.Tests.ps1 | Where-Object {
+                    $parts = $_.FullName -split '[\\/]+' | Where-Object { $_ -ne '' }
+                    foreach ($dir in $Excluded) {
+                        if ($parts -contains $dir) { return $false }
+                    }
+                    return $true
+                }
+            }
+            @($tests | Sort-Object -Property FullName -Stable)
+        },
+        [scriptblock] $Logger = {
+            param([string] $Message)
+            # Use Write-Information so the replayed summary stays visible while respecting approved verbs.
+            Write-Information $Message -InformationAction Continue
+        },
+        [scriptblock] $InvokePester = { param($Config) Invoke-Pester -Configuration $Config },
+        [scriptblock] $CopyCoverage = {
+            param([string] $CoveragePath, [string] $RepoRoot, [string] $KoveragePath)
+            Convert-PoshQCCoverageToRelative -InputPath $CoveragePath -OutputPath $KoveragePath -RepoRoot $RepoRoot
+        }
+    )
+
+    $ErrorActionPreference = 'Stop'
+
+    if (-not $Root) {
+        $Root = $PWD.ProviderPath
+    }
+
+    & $EnsureModule 'Pester' "Pester is not installed. Run Install-PoshQCTool (alias Install-PoshQCTools) first."
+
+    if (-not (& $TestPathExists $SettingsPath)) {
+        throw "Settings not found: $SettingsPath"
+    }
+
+    $settings = & $LoadSettings $SettingsPath
+    $config = & $BuildConfiguration $settings
+    $config = & $ExpandRunPaths $config $Root $ExcludeDirs
+    $config = & $EnsureResultPath $config $Root
+    $config = & $ExpandCoveragePaths $config $Root
+    if ($ScanFolders -and $ScanFolders.Count -gt 0) {
+        $resolvedScanFolders = @(& $ResolveScanFolders $Root $ScanFolders)
+        if ($resolvedScanFolders.Count -gt 0) {
+            $config.Run.Path = $resolvedScanFolders
+        }
+    }
+
+    # Reduce console noise from Pester while we replay a concise summary at the end.
+    if ($config.Output -and $config.Output.Verbosity) {
+        $config.Output.Verbosity = 'Normal'
+    }
+
+    if (-not $config.Run.PassThru) {
+        $config.Run.PassThru = $true
+    }
+
+    $coverageEnabled = $false
+    if ($config.CodeCoverage) {
+        if ($config.CodeCoverage.Enabled -is [bool]) {
+            $coverageEnabled = $config.CodeCoverage.Enabled
+        } elseif ($config.CodeCoverage.Enabled -and $config.CodeCoverage.Enabled.Value) {
+            $coverageEnabled = [bool]$config.CodeCoverage.Enabled.Value
+        }
+    }
+
+    if ($coverageEnabled -and $config.CodeCoverage) {
+        if ($config.CodeCoverage.Path.Value) {
+            $resolvedCoveragePaths = @(
+                $config.CodeCoverage.Path.Value |
+                    ForEach-Object {
+                        if ([IO.Path]::IsPathRooted($_)) { $_ } else { Join-Path $Root $_ }
+                    }
+            )
+            $config.CodeCoverage.Path = $resolvedCoveragePaths
+        }
+
+        if ($config.CodeCoverage.OutputPath.Value) {
+            $coveragePath = $config.CodeCoverage.OutputPath.Value
+            $coverageDir = Split-Path -Parent $coveragePath
+            if (-not [string]::IsNullOrWhiteSpace($coverageDir)) {
+                $resolvedCoverageDir = if ([IO.Path]::IsPathRooted($coverageDir)) { $coverageDir } else { Join-Path $Root $coverageDir }
+                New-Item -ItemType Directory -Path $resolvedCoverageDir -Force | Out-Null
+            }
+            $config.CodeCoverage.OutputPath = if ([IO.Path]::IsPathRooted($coveragePath)) {
+                $coveragePath
+            } else {
+                Join-Path $Root $coveragePath
+            }
+        }
+    }
+
+    $coverageOutputPath = $null
+    if ($config.CodeCoverage) {
+        if ($config.CodeCoverage.OutputPath -is [string]) {
+            $coverageOutputPath = $config.CodeCoverage.OutputPath
+        } elseif ($config.CodeCoverage.OutputPath -and $config.CodeCoverage.OutputPath.Value) {
+            $coverageOutputPath = $config.CodeCoverage.OutputPath.Value
+        }
+    }
+
+    $runPaths = if ($config.Run.Path -is [System.Array]) { [string[]]$config.Run.Path } elseif ($config.Run.Path -and $config.Run.Path.Value) { [string[]]$config.Run.Path.Value } else { @() }
+    $testFiles = & $EnumerateTests $runPaths $ExcludeDirs $TestPathExists
+    if (-not $testFiles) {
+        & $Logger "No Pester test files found under configured paths for root $Root"
+        return
+    }
+
+    $pesterResult = & $InvokePester $config
+
+    $shouldEmitKoverageCopy = -not $DisableKoverageCopy
+    if ($shouldEmitKoverageCopy -and $coverageEnabled -and $coverageOutputPath) {
+        $derivedKoveragePath = $null
+        if ($coverageOutputPath) {
+            $coverageBaseName = [IO.Path]::GetFileNameWithoutExtension($coverageOutputPath)
+            $coverageParent = Split-Path -Parent $coverageOutputPath
+            $derivedKoveragePath = Join-Path $coverageParent "$coverageBaseName.koverage.xml"
+        }
+
+        $effectiveKoveragePath = if ($PSBoundParameters.ContainsKey('KoverageOutputPath') -and -not [string]::IsNullOrWhiteSpace($KoverageOutputPath)) {
+            $KoverageOutputPath
+        } else {
+            $derivedKoveragePath
+        }
+
+        & $CopyCoverage $coverageOutputPath $Root $effectiveKoveragePath
+    }
+
+    if ($pesterResult) {
+        $durationSeconds = [math]::Round($pesterResult.Duration.TotalSeconds, 2)
+        $testsSummary = "Tests completed in {0:N2}s" -f $durationSeconds
+        $countsSummary = "Tests Passed: {0}, Failed: {1}, Skipped: {2}, Inconclusive: {3}, NotRun: {4}" -f `
+            $pesterResult.PassedCount, `
+            $pesterResult.FailedCount, `
+            $pesterResult.SkippedCount, `
+            $pesterResult.InconclusiveCount, `
+            $pesterResult.NotRunCount
+
+        $coverageLines = $null
+        if ($coverageEnabled -and $pesterResult.CodeCoverage) {
+            $coverageReport = $pesterResult.CodeCoverage.CoverageReport
+            if ($coverageReport -is [string] -and -not [string]::IsNullOrWhiteSpace($coverageReport)) {
+                $rawCoverageLines = @($coverageReport -split "`r?`n")
+                $trimmedCoverageLines = @()
+
+                foreach ($line in $rawCoverageLines) {
+                    if ([string]::IsNullOrWhiteSpace($line)) { continue }
+                    if ($line -match '^\s*Missed commands') { break }
+                    $trimmedCoverageLines += $line.TrimEnd()
+                }
+
+                if (-not $trimmedCoverageLines -and $rawCoverageLines) {
+                    $trimmedCoverageLines = @($rawCoverageLines[0])
+                }
+
+                if ($trimmedCoverageLines) {
+                    $coverageLines = $trimmedCoverageLines
+                }
+            }
+        }
+
+        & $Logger ''
+        & $Logger 'Pester summary (replayed for readability):'
+        & $Logger $testsSummary
+        & $Logger $countsSummary
+        if ($coverageLines) {
+            foreach ($line in $coverageLines) {
+                & $Logger $line
+            }
+        }
+    }
+}

package/resources/powershell/PoshQC/PoshQC.psd1

@@ -0,0 +1,31 @@
+@{
+    RootModule           = 'PoshQC.psm1'
+    ModuleVersion        = '0.1.1'
+    GUID                 = '6a9b1a8b-1e8b-4c1f-9d6a-34b8e8c2f0e4'
+    Author               = 'Dan Moisan'
+    CompanyName          = 'Dan Moisan'
+    Copyright            = '(c) Dan Moisan. All rights reserved.'
+    Description          = 'Reusable PowerShell QC helpers (format, analyze, test) using Invoke-Formatter, PSScriptAnalyzer, and Pester.'
+    PowerShellVersion    = '5.1'
+    CompatiblePSEditions = @('Desktop', 'Core')
+    RequiredModules      = @(
+        @{ ModuleName = 'PSScriptAnalyzer'; ModuleVersion = '1.22.0' },
+        @{ ModuleName = 'Pester'; ModuleVersion = '5.6.1' }
+    )
+    FunctionsToExport    = @(
+        'Convert-PoshQCCoverageToRelative',
+        'Get-PoshQCFileList',
+        'Install-PoshQCTool',
+        'Invoke-PoshQCFormat',
+        'Invoke-PoshQCAnalyze',
+        'Invoke-PoshQCAnalyzeAutofix',
+        'Invoke-PoshQCSuite',
+        'Invoke-PoshQCTest'
+    )
+    CmdletsToExport      = @()
+    VariablesToExport    = @()
+    AliasesToExport      = @('Install-PoshQCTools')
+    PrivateData          = @{}
+}
+
+

package/resources/powershell/PoshQC/PoshQC.psm1

@@ -0,0 +1,101 @@
+$script:ModuleRoot = Split-Path -Parent $PSCommandPath
+$script:PssaSettings = Join-Path $ModuleRoot 'settings/pssa.settings.psd1'
+$script:PesterSettings = Join-Path $ModuleRoot 'settings/pester.runsettings.psd1'
+
+$script:DefaultExcludedDirs = @(
+    '.git', '.venv', 'venv', 'node_modules', 'dist', 'build', '.pytest_cache',
+    '__pycache__', '.mypy_cache', '.ruff_cache', '.vscode', '.idea', 'artifacts',
+    '.vscode-test'
+)
+
+<#
+.SYNOPSIS
+Installs PoshQC dependencies (PSScriptAnalyzer and Pester).
+.DESCRIPTION
+Ensures PSGallery is trusted and installs required module versions in the CurrentUser scope.
+#>
+function Install-PoshQCTool {
+    [CmdletBinding()]
+    param(
+        [scriptblock] $SetTls = { [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 },
+        [scriptblock] $GetRepository = { param([string] $Name) Get-PSRepository -Name $Name -ErrorAction SilentlyContinue },
+        [scriptblock] $RegisterRepository = { Register-PSRepository -Default -InstallationPolicy Trusted },
+        [scriptblock] $SetRepository = { param([string] $Name, [string] $Policy) Set-PSRepository -Name $Name -InstallationPolicy $Policy -ErrorAction Stop },
+        [scriptblock] $FindModule = { param([string] $Name) Get-Module -ListAvailable -Name $Name },
+        [scriptblock] $InstallModule = { param([string] $Name, [string] $Version) Install-Module -Name $Name -RequiredVersion $Version -Scope CurrentUser -AllowClobber -Force },
+        [scriptblock] $Logger = {
+            param([string] $Message, [string] $Level = 'Information')
+            switch ($Level) {
+                'Warning' { Write-Warning $Message }
+                'Verbose' { Write-Verbose $Message }
+                default { Write-Information $Message -InformationAction Continue }
+            }
+        }
+    )
+
+    $ErrorActionPreference = 'Stop'
+
+    try {
+        & $SetTls
+    } catch {
+        & $Logger "Unable to enforce TLS 1.2 for module install: $($_.Exception.Message)" 'Verbose'
+    }
+    $gallery = & $GetRepository 'PSGallery'
+    if (-not $gallery) {
+        & $Logger 'PSGallery not found; registering.'
+        & $RegisterRepository
+    } elseif ($gallery.InstallationPolicy -ne 'Trusted') {
+        try {
+            & $SetRepository 'PSGallery' 'Trusted'
+        } catch {
+            & $Logger 'Could not set PSGallery as trusted automatically. You may be prompted during install.' 'Warning'
+        }
+    }
+
+    $requiredModules = @(
+        @{ Name = 'PSScriptAnalyzer'; Version = '1.22.0' },
+        @{ Name = 'Pester'; Version = '5.6.1' }
+    )
+
+    foreach ($module in $requiredModules) {
+        $installed = & $FindModule $module.Name | Where-Object { $_.Version -ge [version]$module.Version } | Select-Object -First 1
+        if ($installed) {
+            & $Logger "$($module.Name) $($installed.Version) already present."
+            continue
+        }
+
+        & $Logger "Installing $($module.Name) $($module.Version) (CurrentUser scope)..."
+        try {
+            & $InstallModule $module.Name $module.Version
+        } catch {
+            throw "Failed to install $($module.Name) $($module.Version): $($_.Exception.Message)"
+        }
+
+        $post = & $FindModule $module.Name | Where-Object { $_.Version -ge [version]$module.Version } | Select-Object -First 1
+        if (-not $post) {
+            throw "Failed to install $($module.Name) $($module.Version)."
+        }
+        & $Logger "$($module.Name) $($module.Version) installed."
+    }
+}
+
+# PowerShell 7.6+ treats dot-sourced .psm1 files as isolated modules, so
+# functions defined in them do not enter the parent module scope.  Loading the
+# file content as a scriptblock bypasses that behaviour.
+. ([scriptblock]::Create((Get-Content (Join-Path $script:ModuleRoot 'PoshQC.FileDiscovery.psm1') -Raw)))
+. ([scriptblock]::Create((Get-Content (Join-Path $script:ModuleRoot 'PoshQC.Analyzer.psm1') -Raw)))
+. ([scriptblock]::Create((Get-Content (Join-Path $script:ModuleRoot 'PoshQC.Testing.psm1') -Raw)))
+
+Set-Alias -Name Install-PoshQCTools -Value Install-PoshQCTool
+
+Export-ModuleMember -Function @(
+    'Get-PoshQCFileList',
+    'Install-PoshQCTool',
+    'Invoke-PoshQCFormat',
+    'Invoke-PoshQCAnalyze',
+    'Invoke-PoshQCAnalyzeAutofix',
+    'Invoke-PoshQCSuite',
+    'Invoke-PoshQCTest',
+    'Convert-PoshQCCoverageToRelative'
+) -Alias @('Install-PoshQCTools')
+

package/resources/powershell/PoshQC/README.md

@@ -0,0 +1,80 @@
+# PoshQC
+
+PoshQC is a lightweight PowerShell quality gate that wraps Invoke-Formatter, PSScriptAnalyzer, and Pester with repo-safe defaults. It targets both Windows PowerShell 5.1 and PowerShell 7.6+.
+
+## What it does
+
+- Formats PowerShell code with consistent indentation and pipeline alignment.
+- Lints with PSScriptAnalyzer using a strict, dual-runtime ruleset.
+- Runs Pester tests with code coverage (CoverageGutters output), plus an optional Koverage-friendly copy.
+- Provides a single suite entry point that can format, analyze, and test a selected workspace scope.
+- Provides a one-time dependency installer for PSScriptAnalyzer and Pester.
+
+## Requirements
+
+- PowerShell 5.1 or 7.6+
+- Modules: PSScriptAnalyzer 1.22.0, Pester 5.6.1 (installed automatically via the helper if missing)
+
+## Getting started
+
+1) Install dependencies (CurrentUser scope):
+
+   ```powershell
+   Import-Module ./PoshQC.psm1
+   Install-PoshQCTool  # alias: Install-PoshQCTools
+   ```
+2) Format everything under the repo root:
+
+   ```powershell
+   Import-Module ./PoshQC.psm1
+   Invoke-PoshQCFormat -Root .
+   ```
+3) Lint with PSScriptAnalyzer:
+
+   ```powershell
+   Invoke-PoshQCAnalyze -Root .
+   ```
+4) Test with Pester + coverage:
+
+   ```powershell
+   Invoke-PoshQCTest -Root .
+   ```
+
+5) Run the full suite against a selected scope:
+
+   ```powershell
+   Import-Module ./PoshQC.psm1
+   Invoke-PoshQCSuite -Root . -ScanFolders @('scripts', 'tests/powershell')
+   ```
+
+   - Writes JUnit XML to `artifacts/pester/pester-junit.xml`.
+   - Writes CoverageGutters XML to `artifacts/pester/powershell-coverage.xml`.
+   - Also emits `*.koverage.xml` (relative paths) for VS Code Coverage Gutters and Koverage. Disable with `-DisableKoverageCopy` or override the path with `-KoverageOutputPath`.
+
+## Functions
+
+- `Install-PoshQCTool` / `Install-PoshQCTools`: install required modules.
+- `Invoke-PoshQCFormat`: run Invoke-Formatter across the repo, honoring exclusions.
+- `Invoke-PoshQCAnalyze`: run PSScriptAnalyzer with the bundled settings.
+- `Invoke-PoshQCSuite`: run format, analyze, and test in one pass, optionally narrowing the scan scope with `-ScanFolders`.
+- `Invoke-PoshQCTest`: run Pester using the bundled runsettings, including coverage and optional Koverage copy.
+- `Convert-PoshQCCoverageToRelative`: utility to strip repo-root prefixes and write a `.koverage.xml` copy (used internally by `Invoke-PoshQCTest`).
+
+## Configuration
+
+- PSScriptAnalyzer settings: `./settings/pssa.settings.psd1`
+   - Enforces compatible syntax for 5.1 and 7.6, 4-space indentation, ShouldProcess for state-changing functions, and safety guards (no Invoke-Expression, no global vars, etc.).
+- Pester settings: `./settings/pester.runsettings.psd1`
+  - Runs tests under `scripts` and `tests/powershell`, outputs JUnit XML and CoverageGutters coverage, and enables coverage over `scripts/dev-tools/*.ps1`, `scripts/powershell/**/*.psm1`, and `src/**/*.ps1`.
+  - When `-ScanFolders` is supplied to `Invoke-PoshQCSuite` or the lower-level commands, the suite narrows discovery to those workspace-relative or workspace-contained folders.
+
+## Typical workflow
+
+- Day-to-day: run `Invoke-PoshQCFormat`, `Invoke-PoshQCAnalyze`, then `Invoke-PoshQCTest` before committing.
+- Bundled / scoped: run `Invoke-PoshQCSuite -Root . -ScanFolders @('scripts', 'tests/powershell')` when you want the suite to focus on selected workspace folders.
+- CI: call `Invoke-PoshQCTest` to get tests + coverage and consume JUnit/CoverageGutters artifacts.
+
+## Notes for standalone use
+
+- Place `PoshQC.psm1`, `PoshQC.psd1`, and the `settings/` folder together; import the module from that directory.
+- Adjust `settings/pester.runsettings.psd1` and `settings/pssa.settings.psd1` to match your repo paths and policies.

package/resources/powershell/PoshQC/settings/pester.runsettings.psd1

@@ -0,0 +1,59 @@
+@{
+    Run          = @{
+        Path = @('scripts', 'tests/powershell', 'tests/scripts')
+        Exit = $true
+    }
+    Should       = @{
+        ErrorAction = 'Stop'
+    }
+    Output       = @{
+        Verbosity = 'Detailed'
+    }
+    TestResult   = @{
+        Enabled      = $true
+        OutputFormat = 'JUnitXml'
+        OutputPath   = 'artifacts/pester/pester-junit.xml'
+    }
+    CodeCoverage = @{
+        Enabled               = $true
+        # Use Pester's CoverageGutters format so VS Code Coverage Gutters
+        # can map file paths correctly.
+        OutputFormat          = 'CoverageGutters'
+        OutputPath            = 'artifacts/pester/powershell-coverage.xml'
+        Path                  = @(
+            '.claude/hooks/validate-bash.ps1'
+            '.claude/hooks/check-python-test-purity.ps1'
+            '.claude/hooks/check-powershell-test-purity.ps1'
+            '.claude/hooks/enforce-python-batch-budget.ps1'
+            '.claude/hooks/enforce-powershell-batch-budget.ps1'
+        )
+        ExcludedPath          = @(
+            '.claude/hooks/validate-feature-review-coverage.ps1' # Feature-review wrapper around repository evidence; not deterministic in normal unit-test execution.
+            'scripts/dev-tools/bootstrap-host.ps1' # Host bootstrap entrypoint for external setup; not deterministic in normal unit-test execution.
+            'scripts/dev-tools/bootstrap-host.helpers.ps1' # Bootstrap helper for host setup; not deterministic in normal unit-test execution.
+            'scripts/dev-tools/format-powershell.ps1' # Thin formatter wrapper around external tooling; not deterministic in normal unit-test execution.
+            'scripts/dev-tools/load-openai-key.ps1' # Local secret-loading wrapper; not deterministic in normal unit-test execution.
+            'scripts/dev-tools/publish-sideloaded-extension.ps1' # VS Code extension publication wrapper; not deterministic in normal unit-test execution.
+            'scripts/dev-tools/run-actionlint.ps1' # External actionlint wrapper; not deterministic in normal unit-test execution.
+            'scripts/dev-tools/run-pester.ps1' # Pester CLI wrapper; not deterministic in normal unit-test execution.
+            'scripts/dev-tools/run-poshqc-suite.ps1' # PoshQC CLI wrapper; not deterministic in normal unit-test execution.
+            'scripts/dev-tools/run-psscriptanalyzer.ps1' # PSScriptAnalyzer CLI wrapper; not deterministic in normal unit-test execution.
+            'scripts/dev-tools/verify-host.ps1' # Host verification wrapper for local tools; not deterministic in normal unit-test execution.
+            'scripts/dev-tools/vscode-cli.helpers.ps1' # VS Code CLI helper around external processes; not deterministic in normal unit-test execution.
+            'scripts/powershell/PoshQC/PoshQC.Analyzer.psm1' # Analyzer orchestration module over external tooling; not deterministic in normal unit-test execution.
+            'scripts/powershell/PoshQC/PoshQC.FileDiscovery.psm1' # File-discovery module coupled to workspace traversal; not deterministic in normal unit-test execution.
+            'scripts/powershell/PoshQC/PoshQC.Testing.psm1' # Pester orchestration module over external tooling; not deterministic in normal unit-test execution.
+        )
+        # Optional: don't fail the run on coverage percentage
+        CoveragePercentTarget = 0
+    }
+}
+
+
+
+
+
+
+
+
+