consistency.yml

name: API.md Consistency

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    paths:
      - "sdk/**"

permissions:
  contents: read

jobs:
  consistency:
    if: ${{ !github.event.pull_request.draft }}
    runs-on: ubuntu-latest
    outputs:
      changed_count: ${{ steps.changed.outputs.count || '0' }}
      mismatch_count: ${{ steps.consistency.outputs.mismatch_count || '0' }}
      missing_count: ${{ steps.consistency.outputs.missing_count || '0' }}
      issue_count: ${{ steps.consistency.outputs.issue_count || '0' }}
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: "20"

      - name: Find changed SDK packages
        id: changed
        env:
          API_MD_BASE_REF: ${{ github.event.pull_request.base.ref }}
          API_MD_PACKAGES_FILE: .artifacts/affected_package_dirs.txt
          API_MD_CHANGED_FILE: .artifacts/changed_package_dirs.txt
        shell: bash
        run: |
          set -euo pipefail
          node scripts/api_md_workflow/find_affected.js

      - name: Generate API.md for affected packages
        if: ${{ steps.changed.outputs.count != '0' }}
        env:
          API_MD_PACKAGES_FILE: .artifacts/affected_package_dirs.txt
        shell: bash
        run: |
          set -euo pipefail
          node scripts/api_md_workflow/regenerate.js

      - name: Check API.md consistency
        id: consistency
        env:
          API_MD_PACKAGES_FILE: .artifacts/affected_package_dirs.txt
          API_MD_MISMATCHES_FILE: .artifacts/mismatched_api_files.txt
          API_MD_MISSING_FILE: .artifacts/missing_api_files.txt
        shell: bash
        run: |
          set -euo pipefail
          if [ "${{ steps.changed.outputs.count }}" = "0" ]; then
            echo "mismatch_count=0" >> "$GITHUB_OUTPUT"
            echo "missing_count=0" >> "$GITHUB_OUTPUT"
            echo "issue_count=0" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          node scripts/api_md_workflow/find_mismatches.js

      - name: Fail when API.md is out of date
        if: ${{ steps.changed.outputs.count != '0' && steps.consistency.outputs.issue_count != '0' }}
        shell: bash
        run: |
          set -euo pipefail

          print_issues() {
            local title="$1"
            local issues_file="$2"

            if [ ! -s "$issues_file" ]; then
              return
            fi

            echo "$title"
            while IFS= read -r api_file; do
              [ -n "$api_file" ] || continue
              package_dir="${api_file%/API.md}"
              package_name="$(basename "$package_dir")"
              echo "- ${package_dir}"
              echo "  API.md: ${api_file}"
              echo "  Regenerate: python scripts/generate_api_text.py ${package_name}"
            done < "$issues_file"
            echo
          }

          echo "Generated API.md does not match committed API.md, or API.md is missing, for one or more affected packages."
          echo
          print_issues "Mismatched packages:" ".artifacts/mismatched_api_files.txt"
          print_issues "Missing API.md packages:" ".artifacts/missing_api_files.txt"
          echo "To regenerate API.md locally, run the command shown for each package from the repository root."
          exit 1