api-spec.yml

on:
  pull_request:
    paths:
      - "src/**/*.php"
      - "config/**"
      - "composer.json"
      - "composer.lock"
      - "public/spec.yaml"
      - "docker-compose.yml"
      - "docker-compose.override.yml"

name: API Spec review

env:
  COMPOSE_USER: root

jobs:
  api-spec:
    runs-on: ubuntu-latest
    name: Ensure committed API specification is up to date
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          fetch-depth: 2

      - name: Cache vendor
        uses: actions/cache@v5
        with:
          path: vendor
          key: vendor-php8.5-${{ hashFiles('composer.lock') }}
          restore-keys: vendor-php8.5-

      - name: Install dependencies
        run: |
          docker network create frontend
          # The spec export only needs PHP — pull phpfpm alone and run it as a
          # one-off (--no-deps skips mariadb), not the whole stack.
          docker compose pull --quiet phpfpm
          docker compose run --rm --no-deps phpfpm composer install --no-interaction

      - name: Export API specification
        run: |
          docker compose run --rm --no-deps phpfpm bin/console api:openapi:export --yaml --output=public/spec.yaml --no-interaction

      - name: Check for changes in specification
        id: git-diff-spec
        continue-on-error: true
        run: git diff --diff-filter=ACMRT --exit-code public/spec.yaml

      - name: Find previous export comment
        id: prev-export-comment
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          id=$(gh api \
            "repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments" \
            --paginate \
            --jq '.[] | select(.body | startswith("<!-- api-spec-export -->")) | .id' \
            | tail -n1)
          echo "id=${id:-}" >> "$GITHUB_OUTPUT"

      - name: Comment PR - spec out of date
        if: steps.git-diff-spec.outcome == 'failure'
        env:
          GH_TOKEN: ${{ github.token }}
          PREV_ID: ${{ steps.prev-export-comment.outputs.id }}
        run: |
          {
            echo "<!-- api-spec-export -->"
            echo "## 🛑 Exported API specification file not up to date"
            echo ""
            echo "Run \`task api:spec:export\` to export the API specification, then commit and push the changes."
          } > comment.md
          if [ -n "$PREV_ID" ]; then
            jq -Rs '{body: .}' < comment.md \
              | gh api "repos/${{ github.repository }}/issues/comments/$PREV_ID" --method PATCH --input -
          else
            gh pr comment ${{ github.event.pull_request.number }} --body-file comment.md
          fi

      # Self-heal: once the committed spec matches the export again, edit the
      # previous 🛑 comment to ✅ instead of leaving a stale failure comment.
      - name: Mark export comment resolved (when up to date)
        if: steps.git-diff-spec.outcome == 'success' && steps.prev-export-comment.outputs.id != ''
        env:
          GH_TOKEN: ${{ github.token }}
          PREV_ID: ${{ steps.prev-export-comment.outputs.id }}
        run: |
          {
            echo "<!-- api-spec-export -->"
            echo "## ✅ Exported API specification is up to date"
            echo ""
            echo "_Resolved — the committed \`public/spec.yaml\` matches the export._"
          } > comment.md
          jq -Rs '{body: .}' < comment.md \
            | gh api "repos/${{ github.repository }}/issues/comments/$PREV_ID" --method PATCH --input -

      - name: Fail job api spec is not up to date
        if: steps.git-diff-spec.outcome == 'failure'
        run: |
          exit 1

  detect-breaking-changes:
    name: Detect breaking changes in API specification
    runs-on: ubuntu-latest
    needs: [api-spec]
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Fetch base branch for comparison
        env:
          BASE_REF: ${{ github.base_ref }}
        run: git fetch --depth=1 origin "$BASE_REF"

      # oasdiff cannot parse `headers: []` (it expects a map); normalise both specs.
      - name: Sanitise specs (headers -> map)
        env:
          BASE_REF: ${{ github.base_ref }}
        run: |
          mkdir -p .api-spec-tmp
          git show "origin/$BASE_REF:public/spec.yaml" | sed 's/headers: \[\]/headers: {}/g' > .api-spec-tmp/base.yaml
          sed 's/headers: \[\]/headers: {}/g' public/spec.yaml > .api-spec-tmp/revision.yaml

      - name: Detect breaking changes
        id: breaking
        continue-on-error: true
        uses: oasdiff/oasdiff-action/breaking@v0.1.5
        with:
          base: .api-spec-tmp/base.yaml
          revision: .api-spec-tmp/revision.yaml
          fail-on: ERR
          # Compare effective (flattened) schemas so an allOf/$ref restructure is
          # not reported as removed properties. Never masks real diffs.
          flatten-allof: true
          # Upload to oasdiff.com to get a side-by-side review link (exposed as
          # the review_url output), but suppress the action's own comment with an
          # empty token — we post a single combined comment below.
          review: true
          github-token: ""

      - name: Generate changelog
        id: changelog
        continue-on-error: true
        uses: oasdiff/oasdiff-action/changelog@v0.1.5
        with:
          base: .api-spec-tmp/base.yaml
          revision: .api-spec-tmp/revision.yaml
          format: markdown
          output-to-file: changelog.md
          flatten-allof: true
          # As above: keep the upload/review_url output, suppress the auto-comment.
          review: true
          github-token: ""

      - name: Determine whether the spec changed
        id: changes
        run: |
          # oasdiff writes "No changelog changes" (v0.1.x) / "No changes" (older)
          # when the spec is unchanged; treat either as no change.
          if [ -s changelog.md ] && ! grep -qiE 'no (changelog )?changes' changelog.md; then
            echo "has_changes=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_changes=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Find previous workflow comment
        id: prev-comment
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          id=$(gh api \
            "repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments" \
            --paginate \
            --jq '.[] | select(.body | startswith("<!-- api-spec-workflow -->")) | .id' \
            | tail -n1)
          echo "id=${id:-}" >> "$GITHUB_OUTPUT"

      - name: Comment PR - non-breaking changes
        if: steps.breaking.outcome == 'success' && steps.changes.outputs.has_changes == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
          PREV_ID: ${{ steps.prev-comment.outputs.id }}
          REVIEW_URL: ${{ steps.changelog.outputs.review_url }}
        run: |
          {
            echo "<!-- api-spec-workflow -->"
            echo "## ⚠️ API specification — non-breaking changes"
            echo ""
            echo "<details><summary>API changes</summary>"
            echo ""
            cat changelog.md
            echo ""
            echo "</details>"
            if [ -n "$REVIEW_URL" ]; then
              printf '\n🔍 [View the full side-by-side review](%s)\n' "$REVIEW_URL"
            fi
          } > comment.md
          if [ -n "$PREV_ID" ]; then
            jq -Rs '{body: .}' < comment.md \
              | gh api "repos/${{ github.repository }}/issues/comments/$PREV_ID" --method PATCH --input -
          else
            gh pr comment ${{ github.event.pull_request.number }} --body-file comment.md
          fi

      - name: Comment PR - breaking changes
        if: steps.breaking.outcome == 'failure'
        env:
          GH_TOKEN: ${{ github.token }}
          PREV_ID: ${{ steps.prev-comment.outputs.id }}
          REVIEW_URL: ${{ steps.breaking.outputs.review_url }}
        run: |
          {
            echo "<!-- api-spec-workflow -->"
            echo "## 🛑 API specification — breaking changes detected"
            echo ""
            if [ -s changelog.md ]; then
              echo "<details><summary>API changes</summary>"
              echo ""
              cat changelog.md
              echo ""
              echo "</details>"
            else
              echo "The breaking-changes check flagged incompatible changes. Review the workflow logs for details."
            fi
            if [ -n "$REVIEW_URL" ]; then
              printf '\n🔍 [View the full side-by-side review](%s)\n' "$REVIEW_URL"
            fi
          } > comment.md
          if [ -n "$PREV_ID" ]; then
            jq -Rs '{body: .}' < comment.md \
              | gh api "repos/${{ github.repository }}/issues/comments/$PREV_ID" --method PATCH --input -
          else
            gh pr comment ${{ github.event.pull_request.number }} --body-file comment.md
          fi

      - name: Mark previous comment resolved (when no changes)
        if: steps.breaking.outcome == 'success' && steps.changes.outputs.has_changes == 'false' && steps.prev-comment.outputs.id != ''
        env:
          GH_TOKEN: ${{ github.token }}
          PREV_ID: ${{ steps.prev-comment.outputs.id }}
        run: |
          {
            echo "<!-- api-spec-workflow -->"
            echo "## ✅ API specification"
            echo ""
            echo "_No changes detected on this run — previous diff resolved._"
          } > comment.md
          jq -Rs '{body: .}' < comment.md \
            | gh api "repos/${{ github.repository }}/issues/comments/$PREV_ID" --method PATCH --input -

      - name: Fail if breaking changes detected
        if: steps.breaking.outcome == 'failure'
        run: |
          exit 1