powershell-ci.yml

# PowerShell CI Workflow
#
# Purpose: Run PSScriptAnalyzer linting and Pester tests for PowerShell scripts
# Runs on: push and pull_request events
#
# Jobs:
#   - powershell-lint: Runs PSScriptAnalyzer on all .ps1 files (skips if no files found)
#   - test: Runs Pester tests on Windows, macOS, and Linux (skips if no *.Tests.ps1 files found)
#
# Note: This workflow is OPTIONAL and can be removed for non-PowerShell projects.
# To remove PowerShell support entirely, delete:
#   - .github/workflows/powershell-ci.yml (this file)
#   - .github/instructions/powershell.instructions.md
#   - .github/linting/PSScriptAnalyzerSettings.psd1
#   - tests/PowerShell/ directory
#   - templates/powershell/ directory
#
# Configuration:
#   - Linting: .github/linting/PSScriptAnalyzerSettings.psd1
#   - Testing: Pester configuration is inline in the workflow steps below
#
# Template Repository Consideration:
# This workflow does NOT use path-based filtering (on.push.paths or
# on.pull_request.paths) because this is a template repository. Path
# filtering would prevent the workflow from being properly tested and
# copied by users of the template. Template repositories should run all
# workflows on all changes to ensure accuracy when the template is used.

name: PowerShell CI

on:
  push:
    branches: ["**"]
  pull_request:
    branches: ["**"]

permissions:
  contents: read

jobs:
  powershell-lint:
    name: Lint (PSScriptAnalyzer)
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Find PowerShell files
        id: find-ps1
        run: |
          # Find all .ps1 files in the repository
          ps1_files=$(find . -name "*.ps1" -type f 2>/dev/null | grep -v "node_modules" || true)
          if [ -z "$ps1_files" ]; then
            echo "No PowerShell files found in repository"
            echo "found=false" >> "$GITHUB_OUTPUT"
          else
            echo "Found PowerShell files:"
            echo "$ps1_files"
            echo "found=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Install PSScriptAnalyzer
        if: steps.find-ps1.outputs.found == 'true'
        shell: pwsh
        run: |
          if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
            Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser
          }
          Import-Module PSScriptAnalyzer

      - name: Run PSScriptAnalyzer
        if: steps.find-ps1.outputs.found == 'true'
        shell: pwsh
        run: |
          $settingsPath = ".github/linting/PSScriptAnalyzerSettings.psd1"
          $ps1Files = Get-ChildItem -Path . -Filter "*.ps1" -Recurse -File |
            Where-Object { $_.FullName -notmatch "node_modules" }

          # Per-file rule exclusions for files that cannot be modified to
          # satisfy certain rules (e.g., v1.0-targeted templates with
          # intentionally unused parameters, or v1.0 scripts that cannot
          # use [CmdletBinding(SupportsShouldProcess)] attributes).
          $perFileExclusions = @{
            '_RobustCloudServiceFunctionTemplate.ps1' = @(
              'PSReviewUnusedParameter',
              'PSUseDeclaredVarsMoreThanAssignments'
            )
            '_SimpleFunctionTemplate.ps1' = @(
              'PSReviewUnusedParameter',
              'PSUseDeclaredVarsMoreThanAssignments'
            )
            'Test-FileWriteability.ps1' = @(
              'PSUseShouldProcessForStateChangingFunctions'
            )
            'Export-ADDSOUPermissions.ps1' = @(
              'PSUseShouldProcessForStateChangingFunctions'
            )
          }

          $hasErrors = $false

          foreach ($file in $ps1Files) {
            Write-Host "Analyzing: $($file.FullName)"
            $results = Invoke-ScriptAnalyzer -Path $file.FullName -Settings $settingsPath

            # Filter out per-file excluded rules
            $excludedRules = $perFileExclusions[$file.Name]
            if ($excludedRules) {
              $results = $results | Where-Object { $_.RuleName -notin $excludedRules }
            }

            if ($results) {
              $hasErrors = $true
              foreach ($result in $results) {
                $severity = $result.Severity
                $message = "$($file.Name):$($result.Line):$($result.Column): [$severity] $($result.RuleName) - $($result.Message)"

                if ($severity -eq 'Error') {
                  Write-Host "::error file=$($file.FullName),line=$($result.Line),col=$($result.Column)::$($result.RuleName) - $($result.Message)"
                } else {
                  Write-Host "::warning file=$($file.FullName),line=$($result.Line),col=$($result.Column)::$($result.RuleName) - $($result.Message)"
                }
              }
            }
          }

          if ($hasErrors) {
            Write-Host ""
            Write-Host "::error::PSScriptAnalyzer found issues. See above for details."
            exit 1
          } else {
            Write-Host ""
            Write-Host "All PowerShell files passed linting."
          }

      - name: Skip - No PowerShell files
        if: steps.find-ps1.outputs.found != 'true'
        run: echo "Skipping PSScriptAnalyzer - no PowerShell files found in repository"

  # Pester Test Job
  #
  # Purpose: Run Pester 5.x tests across multiple operating systems
  #
  # Customization:
  #   - To change test location, update $config.Run.Path in "Run Pester tests" step
  #   - To change output format, update $config.TestResult.OutputFormat
  #   - To add test filters, use $config.Filter.* properties
  #
  # Requirements:
  #   - Pester test files must use *.Tests.ps1 naming convention
  #   - Tests should be placed in tests/PowerShell/ or tests/ directory
  #   - See templates/powershell/Example.Tests.ps1 for test template
  test:
    name: PowerShell Tests (Pester)
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Find Pester test files
        id: find-tests
        shell: pwsh
        run: |
          $testFiles = Get-ChildItem -Path . -Filter "*.Tests.ps1" -Recurse -File |
            Where-Object { $_.FullName -notmatch "node_modules" }
          if ($testFiles.Count -eq 0) {
            Write-Host "No Pester test files found"
            "found=false" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
          } else {
            Write-Host "Found $($testFiles.Count) Pester test file(s):"
            $testFiles | ForEach-Object { Write-Host "  - $($_.FullName)" }
            "found=true" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
          }

      - name: Install Pester
        if: steps.find-tests.outputs.found == 'true'
        shell: pwsh
        run: |
          Install-Module -Name Pester -MinimumVersion 5.0 -Force -Scope CurrentUser
          Import-Module Pester
          Write-Host "Pester version: $((Get-Module Pester).Version)"

      - name: Run Pester tests
        if: steps.find-tests.outputs.found == 'true'
        shell: pwsh
        run: |
          $config = New-PesterConfiguration
          # Run tests from tests/ directory (includes subdirectories)
          $config.Run.Path = "tests/"
          # Exit with non-zero code if tests fail
          $config.Run.Exit = $true
          # Enable test result output
          $config.TestResult.Enabled = $true
          $config.TestResult.OutputFormat = "NUnitXml"
          $config.TestResult.OutputPath = "testResults.xml"
          # Show detailed output
          $config.Output.Verbosity = "Detailed"

          Invoke-Pester -Configuration $config

      - name: Skip - No Pester tests
        if: steps.find-tests.outputs.found != 'true'
        run: echo "Skipping Pester tests - no *.Tests.ps1 files found in repository"