@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

package/resources/powershell/PoshQC/PoshQC.Shard.psm1

@@ -0,0 +1,296 @@
+<#
+.SYNOPSIS
+Selects the test files assigned to one shard (issue #953).
+.DESCRIPTION
+Assigns the files in longest-processing-time order (issue #953, CR-10): heaviest file first, equal weights
+in ordinal path order, each file to the shard with the least assigned weight, then the fewest files, then
+the lowest index, so the shard loads differ by at most the weight of one file. When Weight is omitted every
+file weighs 1, which assigns the files round-robin in ordinal path order. Returns this shard's files in
+input order. Throws when ShardCount is below 1, ShardIndex is outside 1..ShardCount, Weight and TestFile
+differ in length, or a weight is negative (CR-18).
+.PARAMETER TestFile
+Ordered list of test file paths to distribute.
+.PARAMETER ShardIndex
+One-based index of the shard to select.
+.PARAMETER ShardCount
+Total number of shards.
+.PARAMETER Weight
+Optional non-negative weight of each test file (for example its size in bytes), parallel to TestFile.
+#>
+function Get-PoshQCShardSlice {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][string[]] $TestFile,
+        [Parameter(Mandatory)][int] $ShardIndex,
+        [Parameter(Mandatory)][int] $ShardCount,
+        [long[]] $Weight
+    )
+
+    if ($ShardCount -lt 1) {
+        throw "ShardCount must be at least 1; received $ShardCount."
+    }
+    if ($ShardIndex -lt 1 -or $ShardIndex -gt $ShardCount) {
+        throw "ShardIndex must be between 1 and $ShardCount; received $ShardIndex."
+    }
+    if ($null -eq $Weight) {
+        $Weight = [long[]] (@(1) * $TestFile.Count)
+    }
+    if ($Weight.Count -ne $TestFile.Count) {
+        throw "Weight lists $($Weight.Count) values; TestFile lists $($TestFile.Count) files."
+    }
+    for ($position = 0; $position -lt $Weight.Count; $position++) {
+        if ($Weight[$position] -lt 0) {
+            throw "Weight must not be negative; '$($TestFile[$position])' has weight $($Weight[$position])."
+        }
+    }
+
+    $order = [int[]] @(for ($position = 0; $position -lt $TestFile.Count; $position++) { $position })
+    $heaviestFirst = [System.Comparison[int]] {
+        param([int] $Left, [int] $Right)
+        $byWeight = $Weight[$Right].CompareTo($Weight[$Left])
+        if ($byWeight -ne 0) { return $byWeight }
+        [string]::CompareOrdinal($TestFile[$Left], $TestFile[$Right])
+    }
+    [System.Array]::Sort($order, $heaviestFirst)
+
+    $load = New-Object 'long[]' $ShardCount
+    $fileCount = New-Object 'int[]' $ShardCount
+    $selected = New-Object 'System.Collections.Generic.HashSet[int]'
+    foreach ($position in $order) {
+        $target = 0
+        for ($shard = 1; $shard -lt $ShardCount; $shard++) {
+            if ($load[$shard] -lt $load[$target] -or ($load[$shard] -eq $load[$target] -and $fileCount[$shard] -lt $fileCount[$target])) {
+                $target = $shard
+            }
+        }
+        $load[$target] += $Weight[$position]
+        $fileCount[$target]++
+        if ($target -eq $ShardIndex - 1) {
+            [void] $selected.Add($position)
+        }
+    }
+
+    for ($position = 0; $position -lt $TestFile.Count; $position++) {
+        if ($selected.Contains($position)) {
+            $TestFile[$position]
+        }
+    }
+}
+
+<#
+.SYNOPSIS
+Builds the shard manifest for one shard (issue #953).
+.DESCRIPTION
+Returns an in-memory object with shardIndex, shardCount, all (root-relative forward-slash paths
+of every input file), selected (root-relative paths of this shard's slice), and selectedFullPath
+(the slice as given). Relative paths are computed by case-insensitive removal of the root prefix;
+a path outside the root keeps its forward-slash form.
+.PARAMETER RootPath
+Workspace root that the relative paths are computed against.
+.PARAMETER TestFile
+Ordered list of test file paths to distribute.
+.PARAMETER ShardIndex
+One-based index of the shard.
+.PARAMETER ShardCount
+Total number of shards.
+.PARAMETER Weight
+Optional weight of each test file, passed to Get-PoshQCShardSlice.
+#>
+function New-PoshQCShardManifest {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'Pure in-memory factory that changes no system state.')]
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][string] $RootPath,
+        [Parameter(Mandatory)][AllowEmptyCollection()][string[]] $TestFile,
+        [Parameter(Mandatory)][int] $ShardIndex,
+        [Parameter(Mandatory)][int] $ShardCount,
+        [long[]] $Weight
+    )
+
+    $sliceArguments = @{ TestFile = $TestFile; ShardIndex = $ShardIndex; ShardCount = $ShardCount }
+    if ($PSBoundParameters.ContainsKey('Weight')) {
+        $sliceArguments['Weight'] = $Weight
+    }
+    $selected = @(Get-PoshQCShardSlice @sliceArguments)
+    $prefix = ($RootPath -replace '\\', '/').TrimEnd('/') + '/'
+    $toRelative = {
+        param([string] $Path)
+        $normalized = $Path -replace '\\', '/'
+        if ($normalized.StartsWith($prefix, [System.StringComparison]::OrdinalIgnoreCase)) {
+            $normalized.Substring($prefix.Length)
+        } else {
+            $normalized
+        }
+    }
+
+    [pscustomobject]@{
+        shardIndex       = $ShardIndex
+        shardCount       = $ShardCount
+        all              = @($TestFile | ForEach-Object { & $toRelative $_ })
+        selected         = @($selected | ForEach-Object { & $toRelative $_ })
+        selectedFullPath = $selected
+    }
+}
+
+<#
+.SYNOPSIS
+Verifies that a set of shard manifests covers every test file exactly once (issue #953).
+.DESCRIPTION
+Throws unless the shard indices are exactly 1..N once each, every manifest declares shardCount N,
+every 'all' list is identical, the 'selected' lists are pairwise disjoint, and their union sorted
+ordinally equals 'all' sorted ordinally. Returns $true otherwise.
+.PARAMETER ShardManifest
+The manifests produced by New-PoshQCShardManifest, one per shard (for example loaded from JSON).
+#>
+function Test-PoshQCShardCompleteness {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)][object[]] $ShardManifest
+    )
+
+    $count = $ShardManifest.Count
+    $indices = @($ShardManifest | ForEach-Object { [int] $_.shardIndex } | Sort-Object)
+    if (($indices -join ',') -ne ((1..$count) -join ',')) {
+        throw "Shard indices '$($indices -join ',')' are not exactly 1..$count."
+    }
+
+    $reference = @($ShardManifest[0].all | ForEach-Object { [string] $_ })
+    $seen = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::Ordinal)
+    foreach ($manifest in $ShardManifest) {
+        if ([int] $manifest.shardCount -ne $count) {
+            throw "Shard $($manifest.shardIndex) declares shardCount $($manifest.shardCount); $count manifests were supplied."
+        }
+        $all = @($manifest.all | ForEach-Object { [string] $_ })
+        if (($all -join "`n") -cne ($reference -join "`n")) {
+            throw "Shard $($manifest.shardIndex) reports an 'all' list that differs from shard $($ShardManifest[0].shardIndex)."
+        }
+        foreach ($path in @($manifest.selected | ForEach-Object { [string] $_ })) {
+            if (-not $seen.Add($path)) {
+                throw "Test file '$path' is selected by more than one shard."
+            }
+        }
+    }
+
+    [string[]] $union = @($seen)
+    [string[]] $expected = $reference
+    [System.Array]::Sort($union, [System.StringComparer]::Ordinal)
+    [System.Array]::Sort($expected, [System.StringComparer]::Ordinal)
+    if (($union -join "`n") -cne ($expected -join "`n")) {
+        $missing = @($expected | Where-Object { -not $seen.Contains($_) })
+        throw "The shard selections do not cover every test file; missing or extra entries (missing: $($missing -join ', '))."
+    }
+
+    $true
+}
+
+<#
+.SYNOPSIS
+Verifies that the shard test counts add up to the discovery count (issue #953).
+.DESCRIPTION
+Throws unless the sum of ShardTestCount equals DiscoveryCount. Returns $true otherwise.
+.PARAMETER ShardTestCount
+The test count reported by each shard (for example the JUnit testsuites/@tests value).
+.PARAMETER DiscoveryCount
+The test count reported by a discovery-only Pester pass over every test file.
+#>
+function Test-PoshQCShardTestCount {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][int[]] $ShardTestCount,
+        [Parameter(Mandatory)][int] $DiscoveryCount
+    )
+
+    $sum = 0
+    foreach ($testCount in $ShardTestCount) {
+        $sum += $testCount
+    }
+    if ($sum -ne $DiscoveryCount) {
+        throw "Shard test counts sum to $sum; the discovery pass found $DiscoveryCount tests."
+    }
+
+    $true
+}
+
+<#
+.SYNOPSIS
+Selects this shard's test files for Invoke-PoshQCTest (issue #953).
+.DESCRIPTION
+Weights each enumerated test file with Get-PoshQCShardTestFileWeight (a FileInfo item, as the default
+EnumerateTests seam returns, weighs the UTF-8 size of its text with CRLF counted as LF; CR-19), builds
+the manifest with New-PoshQCShardManifest, and throws when the shard selects no test file (CR-13), so Pester
+never runs with an empty Run.Path. When ShardFileListPath is set, WriteShardFileList receives the path and
+the manifest JSON without selectedFullPath. Returns the full paths of the selected files.
+.PARAMETER RootPath
+Workspace root that the manifest paths are relative to.
+.PARAMETER TestFile
+Enumerated test files: FileInfo items, objects with FullName (and optionally Length), or path strings.
+.PARAMETER ShardIndex
+One-based index of the shard.
+.PARAMETER ShardCount
+Total number of shards.
+.PARAMETER ShardFileListPath
+Optional path that receives the shard manifest JSON.
+.PARAMETER WriteShardFileList
+Seam that writes the manifest JSON; receives the path and the JSON text.
+#>
+function Select-PoshQCShardTestFile {
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory)][string] $RootPath,
+        [Parameter(Mandatory)][AllowEmptyCollection()][object[]] $TestFile,
+        [Parameter(Mandatory)][int] $ShardIndex,
+        [Parameter(Mandatory)][int] $ShardCount,
+        [string] $ShardFileListPath,
+        [Parameter(Mandatory)][scriptblock] $WriteShardFileList
+    )
+
+    $paths = [string[]] @($TestFile | ForEach-Object { if ($_ -is [string]) { $_ } else { $_.FullName } })
+    $weights = [long[]] @(Get-PoshQCShardTestFileWeight -TestFile $TestFile)
+    $manifest = New-PoshQCShardManifest -RootPath $RootPath -TestFile $paths -ShardIndex $ShardIndex -ShardCount $ShardCount -Weight $weights
+    if (@($manifest.selected).Count -eq 0) {
+        throw "Shard $ShardIndex of $ShardCount selects no test file; $($paths.Count) test files cannot fill $ShardCount shards. Lower the shard count."
+    }
+    if ($ShardFileListPath) {
+        & $WriteShardFileList $ShardFileListPath ($manifest | Select-Object -Property shardIndex, shardCount, all, selected | ConvertTo-Json -Depth 4)
+    }
+    [string[]] $manifest.selectedFullPath
+}
+
+<#
+.SYNOPSIS
+Returns the shard weight of each enumerated test file (issue #953, CR-19).
+.DESCRIPTION
+A FileInfo item weighs the UTF-8 byte count of its text after every CRLF pair is replaced by LF, so a checkout
+with CRLF line endings computes the same weights, and therefore the same shard assignment, as a checkout with
+LF line endings. Another object weighs its Length property when it has one; a plain path string, or an object
+without a Length property, weighs 1. Returns one weight per item, in input order.
+.PARAMETER TestFile
+Enumerated test files: FileInfo items, objects with FullName (and optionally Length), or path strings.
+.PARAMETER ReadTestFileText
+Seam that returns the text of a test file from its full path. Defaults to [System.IO.File]::ReadAllText.
+#>
+function Get-PoshQCShardTestFileWeight {
+    [CmdletBinding()]
+    [OutputType([long[]])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][object[]] $TestFile,
+        [scriptblock] $ReadTestFileText = { param([string] $Path) [System.IO.File]::ReadAllText($Path) }
+    )
+
+    $weights = New-Object 'System.Collections.Generic.List[long]'
+    foreach ($item in $TestFile) {
+        if ($item -is [System.IO.FileInfo]) {
+            $text = [string] (& $ReadTestFileText $item.FullName)
+            $weights.Add([System.Text.Encoding]::UTF8.GetByteCount($text.Replace("`r`n", "`n")))
+        } elseif ($item -isnot [string] -and $null -ne $item.PSObject.Properties['Length']) {
+            $weights.Add([long] $item.Length)
+        } else {
+            $weights.Add(1)
+        }
+    }
+    [long[]] $weights.ToArray()
+}

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

@@ -147,6 +147,17 @@ Custom path for Koverage-compatible coverage XML output.
 Skip creation of Koverage-friendly coverage copy.
 .PARAMETER ScanFolders
 Optional workspace-relative or workspace-contained folders to scan instead of the entire root.
+.PARAMETER ResolveCoveragePopulation
+Injectable seam that derives the code-coverage file population from the workspace (issue #527).
+Defaults to Resolve-PoshQCCoveragePopulation.
+.PARAMETER ShardIndex
+One-based shard index; used only when ShardCount is greater than 0 (issue #953).
+.PARAMETER ShardCount
+Number of shards. When greater than 0, Run.Path is set to this shard's size-balanced slice of the test files (Select-PoshQCShardTestFile).
+.PARAMETER ShardFileListPath
+Optional path that receives the shard manifest (shardIndex, shardCount, all, selected) as JSON.
+.PARAMETER WriteShardFileList
+Injectable seam that writes the shard manifest JSON. Defaults to Set-Content.
 #>
 function Invoke-PoshQCTest {
     [CmdletBinding()]
@@ -157,12 +168,19 @@ function Invoke-PoshQCTest {
         [string[]] $ExcludeDirs = $script:DefaultExcludedDirs,
         [string] $KoverageOutputPath,
         [switch] $DisableKoverageCopy,
+        [int] $ShardIndex = 0,
+        [int] $ShardCount = 0,
+        [string] $ShardFileListPath,
+        [scriptblock] $WriteShardFileList = { param([string] $Path, [string] $Json) Set-Content -LiteralPath $Path -Value $Json -Encoding utf8 },
         [scriptblock] $EnsureModule = {
-            param([string] $Name, [string] $ErrorMessage)
-            if (-not (Get-Module -ListAvailable -Name $Name)) { throw $ErrorMessage }
+            param([string] $Name, [string] $ErrorMessage, [string] $MinimumVersion, [string] $MaximumVersion)
+            # Issue #953 (CR-1): only an installed version inside the supported range counts as present, so a host
+            # whose only Pester is 6.x or the inbox 3.4.0 receives the actionable message instead of an import error.
+            if (-not (Get-Module -ListAvailable -FullyQualifiedName @{ ModuleName = $Name; ModuleVersion = $MinimumVersion; MaximumVersion = $MaximumVersion })) { throw $ErrorMessage }
             # Import globally so Pester's Describe/It/Mock resolve in test containers that the
             # default $InvokePester trampoline now hosts in the global session state (issue #392).
-            Import-Module $Name -Global -ErrorAction Stop
+            # Issue #953 (D8, CR-2): -MinimumVersion and -MaximumVersion keep the import inside the supported range.
+            Import-Module $Name -Global -MinimumVersion $MinimumVersion -MaximumVersion $MaximumVersion -ErrorAction Stop
         },
         [scriptblock] $TestPathExists = { param([string] $Path) Test-Path $Path },
         [scriptblock] $LoadSettings = { param([string] $Path) Import-PowerShellDataFile -Path $Path },
@@ -282,6 +300,10 @@ function Invoke-PoshQCTest {
         [scriptblock] $CopyCoverage = {
             param([string] $CoveragePath, [string] $RepoRoot, [string] $KoveragePath)
             Convert-PoshQCCoverageToRelative -InputPath $CoveragePath -OutputPath $KoveragePath -RepoRoot $RepoRoot
+        },
+        [scriptblock] $ResolveCoveragePopulation = {
+            param([string] $RootPath, $Settings, [string] $SettingsFile, [string[]] $ScanFolderRoots, [string[]] $Excluded, [scriptblock] $PathExists, [scriptblock] $Log)
+            Resolve-PoshQCCoveragePopulation -Root $RootPath -Settings $Settings -SettingsFile $SettingsFile -ScanFolderRoots $ScanFolderRoots -ExcludeDirs $Excluded -SettingsPathExists $PathExists -Logger $Log
         }
     )
 
@@ -290,8 +312,12 @@ function Invoke-PoshQCTest {
     if (-not $Root) {
         $Root = $PWD.ProviderPath
     }
+    # Resolve a relative -Root once so run, coverage, and output paths are absolute (issue #527).
+    if (-not [IO.Path]::IsPathRooted($Root)) {
+        $Root = [IO.Path]::GetFullPath([IO.Path]::Combine($PWD.ProviderPath, $Root))
+    }
 
-    & $EnsureModule 'Pester' "Pester is not installed. Run Install-PoshQCTool (alias Install-PoshQCTools) first."
+    & $EnsureModule 'Pester' "Pester is not installed in the supported range (5.9.0 to 5.99.99). Run Install-PoshQCTool (alias Install-PoshQCTools) first." '5.9.0' '5.99.99'
 
     if (-not (& $TestPathExists $SettingsPath)) {
         throw "Settings not found: $SettingsPath"
@@ -336,34 +362,20 @@ function Invoke-PoshQCTest {
     }
 
     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 $_ }
-                    }
-            )
-
-            # Prune coverage paths that do not exist under the resolved root before Pester sees
-            # them. Pester's Resolve-CoverageInfo discards the whole set and raises a terminating
-            # error on the first unresolvable entry, which aborts the run at RunStart in any
-            # workspace that does not contain this repository's coverage layout (issue #409).
-            # Rooted entries are tested as-is; they are never re-joined to $Root.
-            $survivingCoveragePaths = @($resolvedCoveragePaths | Where-Object { & $TestPathExists $_ })
-            foreach ($prunedPath in @($resolvedCoveragePaths | Where-Object { $survivingCoveragePaths -notcontains $_ })) {
-                # Log every prune individually so coverage removal is never silent.
-                & $Logger "Pruned nonexistent code coverage path: $prunedPath"
-            }
-
-            if ($survivingCoveragePaths.Count -gt 0) {
-                $config.CodeCoverage.Path = $survivingCoveragePaths
-            } else {
-                # An enabled-but-empty path set makes Pester instrument every Run.Path directory,
-                # so disable coverage for this invocation instead and continue with the test run.
-                $config.CodeCoverage.Enabled = $false
-                $coverageEnabled = $false
-                & $Logger "Code coverage disabled for this invocation: no configured coverage path exists under root '$Root'."
-            }
+        # The coverage population is derived from the workspace, not from a list shipped with the
+        # module, so the measured set does not depend on which module copy was loaded (issue #527).
+        # Nonexistent caller-supplied entries are pruned and logged by the resolver (issue #409).
+        $population = & $ResolveCoveragePopulation $Root $settings $SettingsPath $effectiveScanFolders $ExcludeDirs $TestPathExists $Logger
+        $populationPaths = @($population.Paths | Where-Object { $_ })
+        & $Logger "Code coverage population: source=$($population.Source); files=$($populationPaths.Count)"
+        if ($populationPaths.Count -gt 0) {
+            $config.CodeCoverage.Path = $populationPaths
+        } else {
+            # An enabled-but-empty path set makes Pester instrument every Run.Path directory,
+            # so disable coverage for this invocation instead and continue with the test run.
+            $config.CodeCoverage.Enabled = $false
+            $coverageEnabled = $false
+            & $Logger "Code coverage disabled for this invocation: no configured coverage path exists under root '$Root'."
         }
 
         if ($config.CodeCoverage.OutputPath.Value) {
@@ -396,6 +408,10 @@ function Invoke-PoshQCTest {
         & $Logger "No Pester test files found under configured paths for root $Root"
         return
     }
+    if ($ShardCount -gt 0) {
+        # Issue #953 (FR-09, CR-10, CR-13): run only this shard's size-balanced slice of the enumerated test files.
+        $config.Run.Path = [string[]] @(Select-PoshQCShardTestFile -RootPath $Root -TestFile @($testFiles) -ShardIndex $ShardIndex -ShardCount $ShardCount -ShardFileListPath $ShardFileListPath -WriteShardFileList $WriteShardFileList)
+    }
 
     $pesterResult = & $InvokePester $config
 

package/resources/powershell/PoshQC/PoshQC.psd1

@@ -16,7 +16,13 @@
         'Invoke-PoshQCAnalyze',
         'Invoke-PoshQCAnalyzeAutofix',
         'Invoke-PoshQCSuite',
-        'Invoke-PoshQCTest'
+        'Invoke-PoshQCTest',
+        'Get-PoshQCShardSlice',
+        'Merge-PoshQCCoverageReport',
+        'Get-PoshQCCoverageLineSummary',
+        'New-PoshQCShardManifest',
+        'Test-PoshQCShardCompleteness',
+        'Test-PoshQCShardTestCount'
     )
     CmdletsToExport      = @()
     VariablesToExport    = @()

package/resources/powershell/PoshQC/PoshQC.psm1

@@ -54,11 +54,16 @@ function Install-PoshQCTool {
 
     $requiredModules = @(
         @{ Name = 'PSScriptAnalyzer'; Version = '1.22.0' },
-        @{ Name = 'Pester'; Version = '5.6.1' }
+        # Issue #953 (D8): UpperBound is exclusive; an installed Pester 6.x does not satisfy the requirement.
+        @{ Name = 'Pester'; Version = '5.9.0'; UpperBound = '6.0.0' }
     )
 
+    # Issue #953 (CR-3): one version-range predicate serves the present check and the post-install check.
+    # Where-Object runs it in this function's scope, so $module is the requirement of the current iteration.
+    $isSupportedVersion = { $_.Version -ge [version]$module.Version -and (-not $module.ContainsKey('UpperBound') -or $_.Version -lt [version]$module.UpperBound) }
+
     foreach ($module in $requiredModules) {
-        $installed = & $FindModule $module.Name | Where-Object { $_.Version -ge [version]$module.Version } | Select-Object -First 1
+        $installed = & $FindModule $module.Name | Where-Object -FilterScript $isSupportedVersion | Select-Object -First 1
         if ($installed) {
             & $Logger "$($module.Name) $($installed.Version) already present."
             continue
@@ -71,8 +76,7 @@ function Install-PoshQCTool {
             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) {
+        if (-not (& $FindModule $module.Name | Where-Object -FilterScript $isSupportedVersion | Select-Object -First 1)) {
             throw "Failed to install $($module.Name) $($module.Version)."
         }
         & $Logger "$($module.Name) $($module.Version) installed."
@@ -113,7 +117,10 @@ if (-not $subModuleCache) {
 foreach ($subModuleName in @(
         'PoshQC.FileDiscovery.psm1',
         'PoshQC.ScanConfig.psm1',
+        'PoshQC.Coverage.psm1',
         'PoshQC.Analyzer.psm1',
+        'PoshQC.Shard.psm1',
+        'PoshQC.CoverageMerge.psm1',
         'PoshQC.Testing.psm1'
     )) {
     $subModulePath = Join-Path $script:ModuleRoot $subModuleName
@@ -142,6 +149,12 @@ Export-ModuleMember -Function @(
     'Invoke-PoshQCSuite',
     'Invoke-PoshQCTest',
     'Convert-PoshQCCoverageToRelative',
-    'Get-PoshQCScanConfigFolder'
+    'Get-PoshQCScanConfigFolder',
+    'Get-PoshQCShardSlice',
+    'Merge-PoshQCCoverageReport',
+    'Get-PoshQCCoverageLineSummary',
+    'New-PoshQCShardManifest',
+    'Test-PoshQCShardCompleteness',
+    'Test-PoshQCShardTestCount'
 ) -Alias @('Install-PoshQCTools')
 

package/resources/powershell/PoshQC/README.md

@@ -13,7 +13,7 @@ PoshQC is a lightweight PowerShell quality gate that wraps Invoke-Formatter, PSS
 ## Requirements
 
 - PowerShell 5.1 or 7.6+
-- Modules: PSScriptAnalyzer 1.22.0, Pester 5.6.1 (installed automatically via the helper if missing)
+- Modules: PSScriptAnalyzer 1.22.0, Pester 5.9.0 or later, below 6.0 (installed automatically via the helper if missing)
 
 ## Getting started
 
@@ -59,14 +59,32 @@ PoshQC is a lightweight PowerShell quality gate that wraps Invoke-Formatter, PSS
 - `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`).
+- `Get-PoshQCShardSlice`: select one shard's test files; with `-Weight` (non-negative values, for example text sizes in bytes) the heaviest files are assigned first to the least-loaded shard, and a negative weight is rejected.
+- `New-PoshQCShardManifest`: build the in-memory shard manifest (`shardIndex`, `shardCount`, `all`, `selected`, `selectedFullPath`).
+- `Test-PoshQCShardCompleteness`: throw unless a set of shard manifests selects every test file exactly once.
+- `Test-PoshQCShardTestCount`: throw unless the shard test counts sum to a discovery-pass test count.
+- `Merge-PoshQCCoverageReport`: merge the CoverageGutters XML texts of the shards at LINE granularity (no file I/O, no threshold).
+- `Get-PoshQCCoverageLineSummary`: return covered, missed, total, and percent from a report's LINE counter.
 
 ## 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`.
+  - Runs tests under `scripts` and `tests/powershell`, outputs JUnit XML and CoverageGutters coverage, and enables coverage. The shipped runsettings carry no `CodeCoverage.Path` list; `Invoke-PoshQCTest` derives the coverage population from the workspace (see Coverage population below).
+  - Coverage uses Pester's profiler-based mode (`CodeCoverage.UseBreakpoints = $false`, issue #953), which needs Pester 5.4 or later and is faster than breakpoint mode on the same coverage population. The PoshQC suites target PowerShell 7; profiler mode under Windows PowerShell 5.1 is not exercised in CI. To use breakpoint mode, pass a settings file with `UseBreakpoints = $true` through `-SettingsPath`.
   - When `-ScanFolders` is supplied to `Invoke-PoshQCSuite` or the lower-level commands, the suite narrows discovery to those workspace-relative or workspace-contained folders.
+- Coverage population (issue #527): `Invoke-PoshQCTest` measures the same file set for the same workspace whichever module copy is loaded.
+  - Workspace configuration: `config/poshqc-coverage.json` with the schema `{"version": 1, "roots": [...]}`. Each root is a workspace-relative folder. The file is validated fail-fast, and every error names `config/poshqc-coverage.json`: empty content, invalid JSON, a `version` other than 1, a missing or non-array `roots`, and a blank, absolute, or `..`-segment entry are rejected. An empty `roots` array yields an empty population.
+  - Precedence, reported as the source name: (1) `settings` - a caller-supplied settings file (`-SettingsPath` other than the module's own `settings/pester.runsettings.psd1`) with a non-empty `CodeCoverage.Path` is honored, and each entry that does not exist is pruned and logged; a `CodeCoverage.Path` list in the module's own settings file is ignored and the ignore is logged. (2) `config` - `config/poshqc-coverage.json` exists. (3) `fallback` - the effective test scan folders: explicit `-ScanFolders`, else `config/poshqc-scan.json`, else the settings `Run.Path`.
+  - Built-in exclusions: `.ps1` and `.psm1` files only; files named `*.Tests.ps1` are excluded, as are files whose first root-relative segment is `tests` and files under any root-relative directory named in `DefaultExcludedDirs` (for example `node_modules`, `artifacts`, `.venv`). A nonexistent root is skipped with a warning.
+  - An empty population disables coverage for that invocation, logs `Code coverage disabled for this invocation`, and still runs the tests.
+  - Each run logs `Code coverage population: source=<source>; files=<count>` before Pester starts.
+- Sharded runs (issue #953): `Invoke-PoshQCTest -ShardIndex <n> -ShardCount <N>` runs only shard n of N.
+  - Test files are weighted by the UTF-8 size in bytes of their text with CRLF line endings counted as LF, and assigned heaviest first to the shard with the least assigned weight (ties: fewer files, then the lower shard index; equal sizes are taken in ordinal path order), so runners whose checkouts differ only in line-ending conversion compute the same assignment.
+  - `-ShardFileListPath <path>` writes the shard manifest (`shardIndex`, `shardCount`, `all`, `selected`) as JSON through the `-WriteShardFileList` seam.
+  - A shard that selects no test file (more shards than test files) stops with an error before Pester runs.
+  - `Merge-PoshQCCoverageReport` merges the shard reports with `ci = max(ci)` per line and recomputes the LINE and INSTRUCTION counters, so the merged LINE figures are exact. It omits `class` and `method` elements and METHOD and CLASS counters, because those cannot be recomputed from line hits.
 
 ## Typical workflow
 
@@ -77,4 +95,4 @@ PoshQC is a lightweight PowerShell quality gate that wraps Invoke-Formatter, PSS
 ## 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.
+- Adjust `settings/pester.runsettings.psd1` and `settings/pssa.settings.psd1` to match your repo paths and policies. Declare coverage roots in `config/poshqc-coverage.json` at the workspace root rather than in the runsettings.