ci.yml

# Continuous integration pipeline for CopilotAtelier.
#
#   * Build  - calculate the version with GitVersion, build and package the
#              module, then publish the output/ folder as a build artifact.
#   * Test   - on Linux, macOS and Windows, reuse the build artifact and run the
#              Sampler test workflow on PowerShell 7.
#   * Deploy - on the upstream repository, for pushes to main or v* tags,
#              publish the release to GitHub and the PowerShell Gallery and
#              raise the changelog pull request.
#
# Required repository secrets (Settings > Secrets and variables > Actions):
#   GitHubToken     - personal access token used to create the GitHub release
#                     and the changelog pull request.
#   GalleryApiToken - PowerShell Gallery API key used to publish the module.
name: CI

# Azure DevOps renames each run to the GitVersion number via
# ##vso[build.updatebuildnumber]. GitHub Actions has no equivalent: run-name is
# evaluated before any job starts and can only see the github/inputs contexts,
# so it cannot contain a version GitVersion computes mid-run. The closest we can
# get is: show the version in the run title for tag releases (the tag IS the
# version), and stamp the computed GitVersion value into the test/deploy job
# names and the build job summary on every run (see the build job's outputs).
run-name: ${{ github.ref_type == 'tag' && format('Release {0}', github.ref_name) || '' }}

on:
  push:
    branches:
      - main
    tags:
      - 'v*'
      - '!v*-*'
    paths-ignore:
      - CHANGELOG.md
  pull_request:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read

env:
  buildArtifactName: output
  defaultBranch: main

jobs:
  build:
    name: Package Module
    runs-on: ubuntu-latest
    # Expose the GitVersion value to downstream jobs so they can show it in their
    # display names - the closest GitHub gets to Azure DevOps' run renaming.
    outputs:
      fullSemVer: ${{ steps.gitversion.outputs.FullSemVer }}
      nuGetVersion: ${{ steps.gitversion.outputs.NuGetVersionV2 }}
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          # GitVersion needs the full history to calculate the version.
          fetch-depth: 0

      - name: Calculate ModuleVersion (GitVersion)
        id: gitversion
        shell: pwsh
        env:
          # GitVersion 5.x targets an older .NET; allow it to run on the
          # runner's newer shared framework.
          DOTNET_ROLL_FORWARD: LatestMajor
        run: |
          dotnet tool install --global GitVersion.Tool --version 5.*
          # Prepend, so a GitVersion already on the image cannot shadow the pinned one.
          $env:PATH = (Join-Path -Path $HOME -ChildPath '.dotnet/tools') + [System.IO.Path]::PathSeparator + $env:PATH
          Write-Host -Object "Resolved dotnet-gitversion: $((Get-Command -Name dotnet-gitversion).Source)"

          # GitVersion writes diagnostics and JSON to the same standard output
          # stream, so piping straight into ConvertFrom-Json replaces the real
          # error with a parser error and the cause is lost, and requiring the
          # output to start with '{' fails a run that actually succeeded.
          # GitHub sets $ErrorActionPreference to Stop, which would otherwise make a
          # non-zero exit throw before the output can be shown.
          $PSNativeCommandUseErrorActionPreference = $false
          $gitVersionOutput = (& dotnet-gitversion 2>&1 | Out-String).Trim()
          $gitVersionExitCode = $LASTEXITCODE

          $outputLine = $gitVersionOutput -split '\r?\n'
          $jsonStartIndex = -1

          for ($i = 0; $i -lt $outputLine.Length; $i++)
          {
              if ($outputLine[$i].Trim() -eq '{')
              {
                  $jsonStartIndex = $i
                  break
              }
          }

          if ($gitVersionExitCode -ne 0 -or $jsonStartIndex -lt 0)
          {
              Write-Host -Object '--- dotnet-gitversion output ---'
              Write-Host -Object $gitVersionOutput
              Write-Host -Object '--- end of output ---'
              throw "dotnet-gitversion exited with code $gitVersionExitCode and did not return JSON."
          }

          if ($jsonStartIndex -gt 0)
          {
              # Surfaced, not swallowed: a branch-configuration multi-match shows up
              # here, and GitVersion.yml is what has to change when it does.
              Write-Host -Object '--- dotnet-gitversion diagnostics ---'
              Write-Host -Object ($outputLine[0..($jsonStartIndex - 1)] -join [System.Environment]::NewLine)
              Write-Host -Object '--- end of diagnostics ---'
          }

          $gitVersionJson = $outputLine[$jsonStartIndex..($outputLine.Length - 1)] -join [System.Environment]::NewLine

          try
          {
              $gitVersionObject = $gitVersionJson | ConvertFrom-Json -ErrorAction Stop
          }
          catch
          {
              Write-Host -Object '--- dotnet-gitversion output ---'
              Write-Host -Object $gitVersionOutput
              Write-Host -Object '--- end of output ---'
              throw "dotnet-gitversion returned output that is not valid JSON: $($_.Exception.Message)"
          }

          $gitVersionObject.PSObject.Properties.ForEach{
              Write-Host -Object "Setting output '$($_.Name)' with value '$($_.Value)'."
              "$($_.Name)=$($_.Value)" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
          }
          Write-Host -Object "ModuleVersion (FullSemVer): $($gitVersionObject.FullSemVer)"
          "## CopilotAtelier $($gitVersionObject.FullSemVer)" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8

      - name: Build & Package Module
        shell: pwsh
        env:
          ModuleVersion: ${{ steps.gitversion.outputs.NuGetVersionV2 }}
        run: ./build.ps1 -ResolveDependency -Tasks pack

      - name: Publish Build Artifact
        uses: actions/upload-artifact@v7
        with:
          name: ${{ env.buildArtifactName }}
          path: output/
          include-hidden-files: true
          if-no-files-found: error
          retention-days: 7

  test:
    name: Test ${{ needs.build.outputs.fullSemVer }} (${{ matrix.name }})
    needs: build
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        include:
          # The repository also tests Windows-only customizations, so the
          # non-Windows runners select the module's portable tests by tag.
          - name: ubuntu-latest
            artifact: ubuntu-latest
            os: ubuntu-latest
            arguments: "-Tasks test -PesterTag @('Unit','QA')"
          - name: macos-latest
            artifact: macos-latest
            os: macos-latest
            arguments: "-Tasks test -PesterTag @('Unit','QA')"
          - name: windows-latest (PowerShell 7)
            artifact: windows-latest-pwsh
            os: windows-latest
            arguments: '-Tasks test'

    # If a leg ever needs a different interpreter, parameterise this from the
    # matrix - a step's own `shell` key does not accept the matrix context.
    defaults:
      run:
        shell: pwsh

    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Download Build Artifact
        uses: actions/download-artifact@v8
        with:
          name: ${{ env.buildArtifactName }}
          path: output/

      # tests/SkillsRefValidate.Tests.ps1 shells out to the upstream reference
      # validator through uv. Without this step it would skip, and a skipped
      # gate is a green build with no validation behind it.
      # Pinned to a full release tag: setup-uv publishes no floating major
      # alias past v7, so `@v8`/`@v9` do not resolve.
      - name: Install uv (skills-ref reference validator)
        uses: astral-sh/setup-uv@v9.0.0

      - name: Run Tests
        run: ./build.ps1 ${{ matrix.arguments }}

      - name: Publish Test Results
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: CodeCoverage-${{ matrix.artifact }}
          path: output/testResults/
          if-no-files-found: warn

  deploy:
    name: Deploy Module ${{ needs.build.outputs.fullSemVer }}
    needs: [build, test]
    runs-on: ubuntu-latest
    # Only deploy from the upstream repository, for pushes to the default
    # branch or for version tags.
    if: >-
      github.repository_owner == 'raandree' &&
      (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/'))
    permissions:
      contents: write
      pull-requests: write
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Download Build Artifact
        uses: actions/download-artifact@v8
        with:
          name: ${{ env.buildArtifactName }}
          path: output/

      # Sampler's release tasks skip themselves when their token is empty, and a
      # skipped Publish_Release_To_GitHub still lets the Gallery publish run. That
      # ships a version without the v* tag GitVersion anchors the next pre-release
      # number on, so the following build recomputes the published version and the
      # Gallery rejects it with HTTP 409. Fail here instead of releasing untagged.
      - name: Verify Release Secrets
        shell: pwsh
        env:
          GitHubToken: ${{ secrets.GitHubToken }}
          GalleryApiToken: ${{ secrets.GalleryApiToken }}
        run: |
          $missingSecret = @('GitHubToken', 'GalleryApiToken') |
              Where-Object -FilterScript { -not [System.Environment]::GetEnvironmentVariable($_) }

          if ($missingSecret)
          {
              throw ("Missing repository secret: {0}. Add it under Settings > Secrets and variables > Actions." -f ($missingSecret -join ', '))
          }

      - name: Publish Release
        shell: pwsh
        env:
          GitHubToken: ${{ secrets.GitHubToken }}
          GalleryApiToken: ${{ secrets.GalleryApiToken }}
          ModuleVersion: ${{ needs.build.outputs.nuGetVersion }}
          ReleaseBranch: ${{ env.defaultBranch }}
          MainGitBranch: ${{ env.defaultBranch }}
        run: ./build.ps1 -Tasks publish

      - name: Send Changelog PR
        shell: pwsh
        env:
          GitHubToken: ${{ secrets.GitHubToken }}
          ReleaseBranch: ${{ env.defaultBranch }}
          MainGitBranch: ${{ env.defaultBranch }}
        run: ./build.ps1 -Tasks Create_ChangeLog_GitHub_PR