NetClean 1.0.0: PS7-only, security hardening, live-tested bug fixes, release infra

.github/PULL_REQUEST_TEMPLATE.md

@@ -18,3 +18,18 @@
 ### Testing and verification
 
 Describe how this change was tested.
+
+### Security and compliance
+
+- [ ] This change does not weaken security controls or introduce unsafe behaviors.
+- [ ] If the change modifies state-changing behavior, `ShouldProcess` support is included where applicable.
+
+### CI checks (automatic)
+
+- [ ] PSScriptAnalyzer: no warnings/errors.
+- [ ] Pester tests: all tests pass.
+- [ ] Any new public functions have tests and documentation updated.
+
+### Reviewer notes
+
+- Provide any special verification steps, permissions needed, or rationale for approving.

.github/workflows/ci.yml

@@ -2,35 +2,245 @@ name: CI
 
 on:
   push:
-    branches: [ main ]
+    branches:
+      - main
+      - 'ci/**'
+      - 'feature/**'
+      - 'bugfix/**'
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE'
   pull_request:
-    branches: [ main ]
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE'
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  # Coverage floor (94) is duplicated in tests/Run-NetClean-Coverage.ps1's
+  # $MinimumCoverage default and in the comment-coverage job's
+  # min-coverage-overall below - update all three together when ratcheting.
+  COVERAGE_GATE: '94'
 
 jobs:
-  build-and-test:
+  test-and-analyze:
+    name: PSSA + Pester + Coverage
     runs-on: windows-latest
+    timeout-minutes: 15
+
+    defaults:
+      run:
+        shell: pwsh
 
     steps:
-    - name: Checkout
-      uses: actions/checkout@v4
-
-    - name: Setup PowerShell
-      uses: PowerShell/PowerShell@v3
-
-    - name: Install Pester v5 and PSScriptAnalyzer
-      shell: pwsh
-      run: |
-        Install-Module -Name Pester -Force -Scope CurrentUser -RequiredVersion 5.* -AllowClobber
-        Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser -AllowClobber
-
-    - name: Run PSScriptAnalyzer
-      shell: pwsh
-      run: |
-        Import-Module PSScriptAnalyzer
-        Invoke-ScriptAnalyzer -Path . -SettingsPath .\PSScriptAnalyzerSettings.psd1 -Recurse -Severity Warning,Error
-
-    - name: Run Tests (Pester v5)
-      shell: pwsh
-      run: |
-        Import-Module Pester
-        Invoke-Pester -Script .\tests\Netclean.Tests.ps1 -PassThru
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Show PowerShell environment
+        run: |
+          $PSVersionTable
+          Get-Module Pester -ListAvailable |
+            Sort-Object Version -Descending |
+            Select-Object -First 5 Name, Version, Path
+
+      - name: Resolve PowerShell 7 user module path
+        id: modpath
+        run: |
+          $path = Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'PowerShell\Modules'
+          "path=$path" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+
+      - name: Cache PowerShell modules
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.modpath.outputs.path }}
+          # Cache is keyed on the exact pinned versions below - bump this key's
+          # version numbers whenever RequiredVersion changes in the step below,
+          # so a version bump naturally forces a fresh install instead of
+          # reusing a stale cached copy.
+          key: ps7-modules-Pester6.0.1-PSScriptAnalyzer1.25.0-v1
+
+      - name: Install PowerShell test and analysis tools
+        run: |
+          if (-not (Get-Module -ListAvailable -Name Pester | Where-Object Version -eq ([version]'6.0.1'))) {
+            Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
+            Install-Module Pester -Scope CurrentUser -RequiredVersion 6.0.1 -Force -SkipPublisherCheck -ErrorAction Stop
+          }
+          if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer | Where-Object Version -eq ([version]'1.25.0'))) {
+            Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
+            Install-Module PSScriptAnalyzer -Scope CurrentUser -RequiredVersion 1.25.0 -Force -ErrorAction Stop
+          }
+          Import-Module Pester -RequiredVersion 6.0.1 -Force -ErrorAction Stop
+          if ((Get-Module Pester).Version -ne [version]'6.0.1') {
+            throw 'CI requires Pester 6.0.1.'
+          }
+          Get-Module PSScriptAnalyzer -ListAvailable |
+            Sort-Object Version -Descending |
+            Select-Object -First 1 Name, Version, Path
+
+      - name: Validate module manifest
+        run: |
+          Test-ModuleManifest .\NetClean.psd1 | Out-Null
+          Write-Host 'Module manifest validated successfully.'
+
+      - name: Run PSScriptAnalyzer
+        run: |
+          .\tests\Invoke-NetCleanAnalyzer.ps1 | Format-List
+
+      - name: Run Pester with coverage
+        run: |
+          Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
+          .\tests\Run-NetClean-Coverage.ps1 -MinimumCoverage $env:COVERAGE_GATE
+
+      - name: Locate coverage output (if present)
+        id: find_coverage
+        run: |
+          $candidates = Get-ChildItem -Path tests/TestResults -Recurse -Filter 'coverage*.xml' -ErrorAction SilentlyContinue |
+                        Select-Object -First 1 -ExpandProperty FullName
+          if ($candidates) {
+            Write-Host "Found coverage file: $candidates"
+            "coverage_path=$candidates" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+          } else {
+            Write-Host "No coverage file found."
+            "coverage_path=" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+          }
+
+      - name: Upload test artifacts
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: netclean-test-results
+          path: |
+            tests/TestResults/**
+          if-no-files-found: warn
+          retention-days: 14
+
+      - name: Upload coverage artifact (for badge generation)
+        if: always() && steps.find_coverage.outputs.coverage_path != ''
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: coverage
+          path: ${{ steps.find_coverage.outputs.coverage_path }}
+          if-no-files-found: error
+          retention-days: 30
+
+  publish-coverage-badge:
+    name: Publish coverage badge
+    needs: test-and-analyze
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: windows-latest
+    timeout-minutes: 10
+
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    defaults:
+      run:
+        shell: pwsh
+
+    steps:
+      - name: Download coverage artifact
+        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
+        with:
+          name: coverage
+          path: coverage-artifact
+
+      - name: Generate GitHub Pages coverage badge payload
+        run: |
+          $coverageXmlPath = Join-Path $env:GITHUB_WORKSPACE 'coverage-artifact/coverage.xml'
+          if (-not (Test-Path -LiteralPath $coverageXmlPath)) {
+            throw "Coverage XML not found at $coverageXmlPath"
+          }
+
+          [xml]$doc = Get-Content -LiteralPath $coverageXmlPath
+          $lineCounter = $doc.SelectNodes('//counter') | Where-Object { $_.GetAttribute('type') -eq 'LINE' } | Select-Object -First 1
+          if (-not $lineCounter) {
+            throw 'No LINE counter found in coverage XML.'
+          }
+
+          $missed = [int]$lineCounter.GetAttribute('missed')
+          $covered = [int]$lineCounter.GetAttribute('covered')
+          $total = $missed + $covered
+          $percent = if ($total -gt 0) { [math]::Round(($covered / $total) * 100, 2) } else { 100 }
+          $message = '{0:N2}%' -f $percent
+          $color = if ($percent -ge 94) { 'brightgreen' } elseif ($percent -ge 90) { 'green' } elseif ($percent -ge 80) { 'yellow' } else { 'red' }
+
+          $sitePath = Join-Path $env:GITHUB_WORKSPACE 'pages-site'
+          New-Item -ItemType Directory -Path $sitePath -Force | Out-Null
+
+          $badge = [ordered]@{
+            schemaVersion = 1
+            label = 'coverage'
+            message = $message
+            color = $color
+          }
+
+          $badge | ConvertTo-Json -Compress | Set-Content -LiteralPath (Join-Path $sitePath 'coverage.json') -Encoding utf8
+          @(
+            '<!doctype html>',
+            '<html lang="en">',
+            '<head>',
+            '  <meta charset="utf-8">',
+            '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+            '  <title>NetClean coverage badge</title>',
+            '</head>',
+            '<body>',
+            '  <p>NetClean coverage badge JSON is published at <a href="coverage.json">coverage.json</a>.</p>',
+            '</body>',
+            '</html>'
+          ) -join [Environment]::NewLine | Set-Content -LiteralPath (Join-Path $sitePath 'index.html') -Encoding utf8
+
+      - name: Upload GitHub Pages site artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: pages-site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+  comment-coverage:
+    name: Comment coverage on pull request
+    # Only run for same-repo PRs to avoid token permission issues on forks
+    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+    needs: test-and-analyze
+    runs-on: windows-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Download test and coverage artifacts (test results)
+        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
+        with:
+          name: netclean-test-results
+          path: tests/TestResults
+
+      - name: Download coverage artifact (for PR comment)
+        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
+        with:
+          name: coverage
+          path: tests/TestResults
+
+      - name: Comment PR with coverage summary
+        uses: madrapps/jacoco-report@e51ce1f46f7f8b5331593f935e59cbaf44b84920 # v1.8.0
+        with:
+          paths: |
+            ${{ github.workspace }}/tests/TestResults/coverage.xml
+          token: ${{ secrets.GITHUB_TOKEN }}
+          min-coverage-overall: 94
+          min-coverage-changed-files: 95
+          title: NetClean Coverage Report
+          update-comment: true