ModuleCI.yml

name: CI
on:
  workflow_call:
    inputs:
      changelog_validation_level:
        description: >-
          How CHANGELOG.md format problems are treated: none, warn, or error.
          Defaults to warn because the check enforces a SemVer rule -- a patch
          release may contain only Fixed and Security sections -- that published
          history cannot be edited to satisfy. Set error once a repository is clean.
        required: false
        type: string
        default: 'warn'
      changelog_validation_depth:
        description: >-
          How many entries to validate, newest first. Lower this to enforce on recent
          releases while ignoring older ones that cannot be fixed.
        required: false
        type: number
        default: 100
      code_coverage_report_path:
        description: >-
          Workspace-relative path to the JaCoCo code coverage report the build
          produces. Every step that uses it is skipped when no file is there, so
          a module that does not measure coverage needs no configuration. The
          default follows the tests/out/ convention the test results already use.
          A module that leaves $PSBPreference.Test.CodeCoverage.OutputFile at the
          PowerShellBuild default writes codeCoverage.xml to the project root
          instead, and should point this input at that path.
        required: false
        type: string
        default: 'tests/out/coverage.xml'
permissions:
  checks: write
  pull-requests: write
  contents: read
  issues: write
jobs:
  lint:
    name: Run Linters
    runs-on: [ubuntu-latest]
    steps:
      - uses: actions/checkout@v4
      # Validates CHANGELOG.md against the Keep a Changelog format. Level and depth are
      # fails: the action also enforces a SemVer rule that a patch release may contain
      # only Fixed and Security sections, and existing psake module histories violate
      # that in releases already published, which no edit can undo. Raise to error once
      # a repository is clean, per repository, rather than org-wide.
      # Skipped when the
      # repository has no changelog, so a consumer without one is not failed for it.
      # validation_depth defaults to 10 entries; raised so older releases are checked
      # too, which is where format drift accumulates unnoticed.
      - name: Validate changelog (keepachangelog)
        if: hashFiles('CHANGELOG.md') != ''
        uses: mindsers/changelog-reader-action@v2
        with:
          validation_level: ${{ inputs.changelog_validation_level }}
          validation_depth: ${{ inputs.changelog_validation_depth }}
          path: ./CHANGELOG.md
      - uses: streetsidesoftware/cspell-action@v6
        with:
          strict: false
          suggestions: true
          incremental_files_only: true
      - shell: pwsh
        name: Apply PSScriptAnalyzer Fixes
        run: Invoke-ScriptAnalyzer . -Fix
      - name: PSScriptAnalyzer Fixes
        uses: reviewdog/action-suggester@v1.21.0
        with:
          tool_name: "PSScriptAnalyzer"
  test:
    name: Run Pwsh Tests
    # We still have the azure pipeline setup that's running windows
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macOS-latest]
    steps:
      - uses: actions/checkout@v4
      - name: Test
        shell: pwsh
        run: ./build.ps1 -Task Test -Bootstrap
      - name: Upload Unit Test Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: Unit Test Results (OS ${{ matrix.os }})
          path: ./tests/out/testResults.xml
      - name: Upload Code Coverage Results
        # Skipped when the build produced no coverage report, so a module that does
        # not measure coverage is not failed for it.
        if: always() && hashFiles(inputs.code_coverage_report_path) != ''
        uses: actions/upload-artifact@v4
        with:
          name: Code Coverage Results (OS ${{ matrix.os }})
          path: ${{ inputs.code_coverage_report_path }}
      # Renders the JaCoCo totals into the run summary so the number is visible without
      # downloading the artifact. Deliberately reports and never gates: Pester instruments
      # the current session only, so anything a test exercises in a child process is
      # uncounted and the figure understates real coverage. It is a floor and a trend
      # line, and a build-failing threshold over it would be actively misleading. Parsed
      # in PowerShell rather than by a coverage action because the common ones read
      # Cobertura, and this keeps the caveat above attached to the number it describes.
      - name: Summarize Code Coverage
        if: always() && hashFiles(inputs.code_coverage_report_path) != ''
        shell: pwsh
        env:
          COVERAGE_REPORT_PATH: ${{ inputs.code_coverage_report_path }}
        run: |
          $ErrorActionPreference = 'Stop'
          [xml]$report = Get-Content -Path $env:COVERAGE_REPORT_PATH -Raw
          $summary = @(
              '### Code coverage'
              ''
              '| Metric | Covered | Total | Coverage |'
              '| --- | ---: | ---: | ---: |'
              foreach ($counter in $report.report.counter) {
                  $covered = [int]$counter.covered
                  $total = $covered + [int]$counter.missed
                  $percent = if ($total -gt 0) { 100 * $covered / $total } else { 0 }
                  '| {0} | {1} | {2} | {3:N1}% |' -f $counter.type.ToLower(), $covered, $total, $percent
              }
              ''
              ('_Measured in the test session only, so code exercised in child processes is not ' +
               'counted. Treat this as a floor and a trend line, not as the true figure._')
          ) -join "`n"
          [IO.File]::AppendAllText($env:GITHUB_STEP_SUMMARY, $summary + "`n", [Text.UTF8Encoding]::new($false))
  test_powershell:
    name: Run Tests (Windows PowerShell 5.1)
    # Windows PowerShell 5.1 (Desktop) is not a runner OS, so it is run as a
    # separate job using the built-in `powershell` shell on windows-latest.
    # Modules that declare Windows PowerShell (Desktop) support must build and
    # test cleanly on the lowest supported engine, not just PowerShell 7+.
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - name: Test
        shell: powershell
        run: ./build.ps1 -Task Test -Bootstrap
      - name: Upload Unit Test Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: Unit Test Results (Windows PowerShell 5.1)
          path: ./tests/out/testResults.xml
      - name: Upload Code Coverage Results
        # Skipped when the build produced no coverage report, so a module that does
        # not measure coverage is not failed for it.
        if: always() && hashFiles(inputs.code_coverage_report_path) != ''
        uses: actions/upload-artifact@v4
        with:
          name: Code Coverage Results (Windows PowerShell 5.1)
          path: ${{ inputs.code_coverage_report_path }}
      # Renders the JaCoCo totals into the run summary so the number is visible without
      # downloading the artifact. Deliberately reports and never gates: Pester instruments
      # the current session only, so anything a test exercises in a child process is
      # uncounted and the figure understates real coverage. It is a floor and a trend
      # line, and a build-failing threshold over it would be actively misleading. Parsed
      # in PowerShell rather than by a coverage action because the common ones read
      # Cobertura, and this keeps the caveat above attached to the number it describes.
      - name: Summarize Code Coverage
        if: always() && hashFiles(inputs.code_coverage_report_path) != ''
        shell: powershell
        env:
          COVERAGE_REPORT_PATH: ${{ inputs.code_coverage_report_path }}
        run: |
          $ErrorActionPreference = 'Stop'
          [xml]$report = Get-Content -Path $env:COVERAGE_REPORT_PATH -Raw
          $summary = @(
              '### Code coverage'
              ''
              '| Metric | Covered | Total | Coverage |'
              '| --- | ---: | ---: | ---: |'
              foreach ($counter in $report.report.counter) {
                  $covered = [int]$counter.covered
                  $total = $covered + [int]$counter.missed
                  $percent = if ($total -gt 0) { 100 * $covered / $total } else { 0 }
                  '| {0} | {1} | {2} | {3:N1}% |' -f $counter.type.ToLower(), $covered, $total, $percent
              }
              ''
              ('_Measured in the test session only, so code exercised in child processes is not ' +
               'counted. Treat this as a floor and a trend line, not as the true figure._')
          ) -join "`n"
          [IO.File]::AppendAllText($env:GITHUB_STEP_SUMMARY, $summary + "`n", [Text.UTF8Encoding]::new($false))
  publish-test-results:
    name: "Publish Unit Tests Results"
    needs:
      - test
      - test_powershell
    runs-on: ubuntu-latest
    # Publish whenever the test jobs ran (pass or fail); only skip if the
    # workflow itself was cancelled.
    if: ${{ !cancelled() }}
    steps:
      - name: Download Artifacts
        uses: actions/download-artifact@v4
        with:
          # Restricted to the test result artifacts. The test jobs also upload code
          # coverage reports, and the publisher below would try to read those as test
          # results if they landed in the same directory.
          pattern: Unit Test Results*
          path: artifacts

      - name: Publish Unit Test Results
        uses: EnricoMi/publish-unit-test-result-action@v2
        with:
          files: artifacts/**/*.xml