Ci/pester v5 coverage re-branching after history re-write

.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,146 @@ name: CI
 
 on:
   push:
-    branches: [ main ]
+    branches:
+      - main
+      - ci/**
+      - feature/**
+      - bugfix/**
   pull_request:
-    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
 
 jobs:
-  build-and-test:
+  test-and-analyze:
+    name: PSSA + Pester + Coverage
     runs-on: windows-latest
 
+    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: Install PowerShell test and analysis tools
+        run: |
+          Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
+          Install-Module Pester -Scope CurrentUser -RequiredVersion 6.0.1 -Force -SkipPublisherCheck -ErrorAction Stop
+          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 94
+
+      - name: Upload test and coverage 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
+
+  windows-powershell-compatibility:
+    name: Windows PowerShell 5.1 compatibility
+    runs-on: windows-latest
+
+    defaults:
+      run:
+        shell: powershell
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Validate Windows PowerShell environment
+        run: |
+          $PSVersionTable
+          if ($PSVersionTable.PSVersion -lt [version]'5.1' -or $PSVersionTable.PSEdition -ne 'Desktop') {
+            throw 'This job requires Windows PowerShell 5.1.'
+          }
+
+      - name: Install compatibility test tools
+        run: |
+          [Net.ServicePointManager]::SecurityProtocol =
+            [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+          Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
+          Install-Module Pester -Scope CurrentUser -RequiredVersion 6.0.1 -Force -SkipPublisherCheck -ErrorAction Stop
+          Install-Module PSScriptAnalyzer -Scope CurrentUser -RequiredVersion 1.25.0 -Force -ErrorAction Stop
+          Import-Module Pester -RequiredVersion 6.0.1 -Force -ErrorAction Stop
+          Import-Module PSScriptAnalyzer -RequiredVersion 1.25.0 -Force -ErrorAction Stop
+
+      - name: Validate module manifest
+        run: |
+          Test-ModuleManifest .\NetClean.psd1 | Out-Null
+          Write-Output 'Module manifest validated successfully under Windows PowerShell 5.1.'
+
+      - name: Run complete Pester suite
+        run: |
+          $config = New-PesterConfiguration
+          $config.Run.Path = (Resolve-Path .\tests).Path
+          $config.Run.PassThru = $true
+          $config.Run.Throw = $true
+          $config.Output.Verbosity = 'Normal'
+          $result = Invoke-Pester -Configuration $config
+          if ($result.FailedCount -gt 0) {
+            throw "Pester reported $($result.FailedCount) failed test(s) under Windows PowerShell 5.1."
+          }
+
+  comment-coverage:
+    name: Comment coverage on pull request
+    if: github.event_name == 'pull_request'
+    needs: test-and-analyze
+    runs-on: windows-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Download test and coverage artifacts
+        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
+        with:
+          name: netclean-test-results
+          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

.gitignore

@@ -1,6 +1,11 @@
 # Ignore common AI/chat artifacts and local assistant data
 # Adjust these patterns to match your editor/assistant storage locations
 
+# Ignore common AI/chat artifacts and local assistant data
+# Adjust these patterns to match your editor/assistant storage locations
+.ai/
+**/.ai/
+
 # Copilot / assistant caches
 .copilot/
 .copilot/*
@@ -22,3 +27,7 @@ ai_outputs/
 
 # Node/npm lockfiles or others you might not want to commit (optional)
 # package-lock.json
+
+# Generated test and coverage output
+tests/TestResults/
+coverage*.xml

CHANGELOG.md

@@ -4,11 +4,45 @@ All notable changes to this project should be documented in this file.
 
 ## Unreleased
 
-- Add detailed `README.md` with usage, backups, safety notes, and examples.
-- Add example wrapper scripts in `examples/` (`run-netclean.ps1`, `restore-wifi-profiles.ps1`, `register-scheduledtask.ps1`).
-- Add GitHub Actions workflow for linting and safe `-DryRun` execution.
-- Add `.gitignore` to exclude AI/chat artifacts.
-- Add `CONTRIBUTING.md` and PR template.
+- Add conference-preparation adapter reset and verification: IPv4 DHCP, Quad9 IPv4/IPv6 DNS, DNS over HTTPS without plaintext fallback where supported, IPv6 retained with IPv4 preferred, protected/managed-adapter boundaries, private adapter backups, and a machine-readable verification ledger.
+- Add conditional post-cleanup evidence for Wi-Fi disconnection and DNS/ARP caches; cache state is evaluated only when no physical wired LAN is connected.
+- Upgrade the test toolchain to Pester 6.0.1, make test files discovery-isolated, and fail coverage runs on discovery or container errors.
+- Add isolated registry System tests that exercise real Registry-provider detection, native backup, protected-boundary cleanup, and independent verification against synthetic Pester `TestRegistry:` data.
+- Fix native registry export argument quoting for keys and output paths containing spaces.
+- Raise the overall command-coverage ratchet from 68% to 69% after the isolated System tests increased Pester 6's measured production coverage from 68.43% to 69.42%; retain the 95% changed-file and long-term overall targets.
+- Expand fail-closed cleanup verification coverage for registry and user artifacts, event logs, DNS and ARP caches, and physical-adapter discovery; preserve fail-soft registry discovery while allowing verification callers to surface query failures.
+- Treat physical adapters without an interface index as having no queryable ARP entries instead of failing under strict mode.
+- Raise the overall command-coverage ratchet from 69% to 71% after the verification failure matrix increased measured production coverage from 69.42% to 71.29%, and align Pester's displayed target with the enforced runner and pull-request gates.
+- Add source-matrix and correlation tests for Security Center products, services, drivers, uninstall records, adapters, PnP devices, service registry data, file metadata/signatures, and protected service/adapter registry boundaries.
+- Allow empty metadata paths to reach the existing fail-soft guard instead of failing during parameter binding.
+- Raise the overall command-coverage ratchet from 71% to 80% after protection-discovery tests increased measured production coverage from 71.29% to 80.17%.
+- Add functional contracts for menus, confirmation, summaries, previews, safe Preview routing, live backup-directory creation, and mocked dry/live restart or shutdown actions.
+- Make launcher-owned settings explicitly script-scoped, allow empty lists to reach their existing summary output, and correct invalid-input feedback that passed an unsupported parameter to `Write-Verbose`.
+- Raise the overall command-coverage ratchet from 80% to 85% after launcher and user-facing tests increased measured production coverage from 80.17% to 85.56%.
+- Raise the overall command-coverage ratchet from 85% to 90% after failure-path, strict-mode, and active-helper tests increased measured production coverage to 92.05%.
+- Expand active-path protection discovery, workflow, registry export, cleanup, and verification tests to 95.09% measured production coverage, and raise the overall command-coverage ratchet from 90% to 94% while retaining the 95% changed-file gate.
+- Reject test-directory files as coverage sources so test code cannot inflate reported production coverage.
+- Preserve textual vendor inference when executable metadata is present but does not identify a vendor.
+- Normalize exported `Wi-Fi-<profile>.xml` filenames before using them as expected profile names during workflow verification.
+- Retry a PSScriptAnalyzer target once only when version 1.25.0 raises its intermittent `NullReferenceException`; all repeated null references, other exceptions, and analyzer findings remain fatal.
+- Temporarily omit performance tuning from the interactive menu while retaining explicit `-Mode PerformanceTune` compatibility.
+- Add a parallel Windows PowerShell 5.1 compatibility job and update workflow actions to immutable Node.js 24 release commits.
+- Treat Workplace registration as preserved user-level SSO rather than organization management unless independent domain, Entra join, enterprise join, or MDM evidence exists.
+- Preserve identity, account, token, credential, and BrokerPlugin stores through explicit narrow cleanup allowlists and regression tests.
+- Capture `netsh` Wi-Fi profile output as UTF-8 while restoring the caller's console encoding so non-ASCII SSID names render correctly.
+
+- Refactor: Make repository PSScriptAnalyzer-clean across all scripts and module functions.
+	- Replace `Write-Host` with structured logging and proper streams.
+	- Add `CmdletBinding(SupportsShouldProcess=$true)` to state-changing functions.
+	- Rename functions to use approved verbs and singular nouns; add backward-compatible aliases.
+	- Harden `catch` blocks to surface errors (no empty catches).
+	- Remove unsafe `Invoke-Expression` usage and use safer execution patterns.
+	- Fix scoping (avoid `global:`), remove unused variables, and avoid assigning to automatic variables in examples/tests.
+	- Fix file encoding/BOM for Unicode files and remove non-ASCII artifacts that triggered analyzer warnings.
+	- Update examples and tests to be analyzer- and CI-friendly.
+	- Add unit tests and ensure Pester tests pass locally.
+
+These changes were made to improve safety, testability, and to ensure CI fails fast on analyzer or test regressions.
 
 ## 0.1.0 - 2026-03-07
 

CONTRIBUTING.md

@@ -1,35 +1,38 @@
 # Contributing
 
-Thanks for considering contributing to `netclean` — your help improves the tool for everyone.
+Contributions should be small, focused, and based on the latest `main` branch unless a maintainer specifies another base.
 
-Please follow these guidelines for a smooth collaboration:
+## Engineering expectations
 
-- Fork the repository and open a feature branch from `main`.
-- Keep commits small and focused; use clear commit messages.
-- Run `PSScriptAnalyzer` locally and fix warnings where practical.
+- Use red-green-refactor: add or correct a focused Pester 6 test, observe the intended failure, apply the smallest production change, then refactor with the suite green.
+- Preserve dry-run, `ShouldProcess`, protected-artifact, and backup behavior for state-changing operations.
+- Keep functions compact and single-purpose; isolate native commands and filesystem/registry access behind testable helpers.
+- Do not weaken security checks, analyzer rules, test assertions, the 94% overall coverage ratchet, or the 95% changed-file target to make CI pass. Current total coverage exceeds 95%; preserve that result and raise the enforced ratchet only when durable margin permits.
+- Treat network performance tuning as tabled. Do not expose it in the interactive menu or expand that code without explicit maintainer direction.
+- Update public help, README, and CHANGELOG entries when behavior or interfaces change.
 
-Suggested checks before opening a pull request:
+## Local validation
 
 ```powershell
-Install-Module -Name PSScriptAnalyzer -Scope CurrentUser -Force
-Invoke-ScriptAnalyzer -Path . -Recurse
-```
-
-Pull request checklist
+Install-Module Pester -Scope CurrentUser -RequiredVersion 6.0.1 -Force -SkipPublisherCheck
+Install-Module PSScriptAnalyzer -Scope CurrentUser -RequiredVersion 1.25.0 -Force
 
-- [ ] Code changes include tests or verification steps (if applicable).
-- [ ] README and CHANGELOG updated if behavior or interface changed.
-- [ ] CI passes (GitHub Actions will lint and run safe dry-runs).
+.\tests\Invoke-NetCleanAnalyzer.ps1
 
-Code style and tests
+Invoke-Pester -Path .\tests
+.\tests\Run-NetClean-Coverage.ps1
+```
 
-- Use clear, descriptive names for functions and parameters.
-- Keep scripts idempotent where possible and add checks for required privileges.
+Run the complete Pester suite under both PowerShell 7.4 or later and Windows PowerShell 5.1 before submitting changes. The authoritative coverage run remains on PowerShell 7 and is intentionally sequential.
 
-Reporting issues
+The repository's registry System tests are safe for normal local and CI runs: Pester creates a random, container-scoped `TestRegistry:` key under HKCU, and the suite populates it only with synthetic data. Run tests that change real adapters, Wi-Fi state, caches, event logs, or restart behavior only on a disposable Windows system you control. Never commit generated test results, coverage reports, logs, exported registry data, Wi-Fi profiles, credentials, or other machine inventory.
 
-- Use the repository's Issues to report bugs or request features. Provide reproduction steps and environment details.
+## Pull request checklist
 
-License
+- [ ] A focused test demonstrated the defect or missing behavior before the implementation change.
+- [ ] Pester 6.0.1 tests pass under PowerShell 7.4 or later and Windows PowerShell 5.1.
+- [ ] PSScriptAnalyzer reports no warnings or errors.
+- [ ] Documentation and change notes match the implementation.
+- [ ] No generated output, secrets, credentials, or host-specific inventory is included.
 
-By contributing you agree that your contributions will be licensed under the project's license.
+Contributions are licensed under the repository's GPLv3 license.