check_api_ref.yml

name: Check API reference changes

on:
  pull_request:
    paths:
      - "haystack/**/*.py"
      - "pydoc/*.yml"

permissions:
  contents: read

jobs:
  test-api-reference-build:
    runs-on: ubuntu-slim
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: "3.13"

      - name: Detect API reference changes
        id: changed
        shell: python
        run: |
          import os
          import subprocess
          from pathlib import Path

          import sys
          sys.path.insert(0, ".github/utils")
          from docstrings_checksum import docstrings_checksum

          def git(*args):
              result = subprocess.run(["git", *args], capture_output=True, text=True)
              return result.stdout.strip(), result.returncode

          base_sha, _ = git("rev-parse", "HEAD^1")
          diff_output, _ = git("diff", "--name-only", f"{base_sha}...HEAD")
          changed_files = set(diff_output.splitlines())

          needs_check = False

          # If any pydoc config changed, always rebuild
          if any(f.startswith("pydoc/") and f.endswith(".yml") for f in changed_files):
              needs_check = True

          # If Python files changed, compare docstring checksums
          if not needs_check and any(f.startswith("haystack/") and f.endswith(".py") for f in changed_files):
              runner_temp = os.environ["RUNNER_TEMP"]
              base_worktree = os.path.join(runner_temp, "base")
              _, rc = git("worktree", "add", base_worktree, base_sha)

              pr_checksum = docstrings_checksum(Path(".").glob("haystack/**/*.py"))
              base_checksum = ""
              if rc == 0:
                  base_checksum = docstrings_checksum(Path(base_worktree).glob("haystack/**/*.py"))

              if pr_checksum != base_checksum:
                  needs_check = True

          print(f"API reference check needed: {needs_check}")
          with open(os.environ["GITHUB_OUTPUT"], "a") as f:
              f.write(f"needs_check={str(needs_check).lower()}\n")

      - name: Install Hatch
        if: steps.changed.outputs.needs_check == 'true'
        run: |
          python -m pip install --upgrade pip
          pip install hatch --uploaded-prior-to=P1D

      - name: Generate API references
        if: steps.changed.outputs.needs_check == 'true'
        run: hatch run docs

      - name: Set up Node.js
        if: steps.changed.outputs.needs_check == 'true'
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: "22"

      - name: Run Docusaurus md/mdx checker
        if: steps.changed.outputs.needs_check == 'true'
        working-directory: tmp_api_reference
        run: |
          # docusaurus-mdx-checker is a package that is not frequently updated. Its dependency katex sometimes ships a
          # broken ESM build, where a __VERSION__ placeholder is left unresolved, causing a ReferenceError at import time.
          # Node 22+ prefers ESM when available. We force CJS (CommonJS) resolution to use the working katex build.
          # This should be safe because docusaurus-mdx-checker and its dependencies provide CJS builds.
          export NODE_OPTIONS="--conditions=require"
          npx docusaurus-mdx-checker@3.0.0 -v || {
              echo ""
              echo "For common MDX problems, see https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3#common-mdx-problems"
              exit 1
            }