name: Docs — Reference Drift Check

# Fails a PR if the committed /website/docs/reference/ output disagrees
# with what tools/generate_docs_reference.py would produce from the live
# Python tool/resource registry. Contributors should regenerate locally:
#
#   cd Server && uv run python ../tools/generate_docs_reference.py
#
# or install the pre-commit hook to make this automatic:
#
#   tools/install-hooks.sh

on:
  pull_request:
    branches: [beta, main]
    paths:
      - Server/src/services/tools/**
      - Server/src/services/resources/**
      - Server/src/services/registry/**
      - website/docs/reference/**
      - tools/generate_docs_reference.py
      - .github/workflows/docs-generate.yml
  push:
    branches: [beta]
    paths:
      - Server/src/services/tools/**
      - Server/src/services/resources/**
      - Server/src/services/registry/**
      - website/docs/reference/**
      - tools/generate_docs_reference.py
      - .github/workflows/docs-generate.yml
  workflow_dispatch: {}

jobs:
  check:
    name: Check docs reference is fresh
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@v4
        with:
          version: latest

      - name: Set up Python
        run: uv python install 3.10

      - name: Sync Server deps
        working-directory: Server
        run: uv sync

      - name: Drift check
        working-directory: Server
        run: uv run python ../tools/generate_docs_reference.py --check

      - name: Tool-count sanity
        run: |
          set -euo pipefail
          # Match the decorator at start-of-line (skips imports and docstring mentions).
          decorator_count=$(grep -rhE "^@mcp_for_unity_tool\(" Server/src/services/tools/ | wc -l | tr -d ' ')
          # md_count excludes group landing pages (index.md) and the catalog root.
          md_count=$(find website/docs/reference/tools -name '*.md' -not -name 'index.md' | wc -l | tr -d ' ')
          echo "decorator_count=$decorator_count, md_count=$md_count"
          if [[ "$decorator_count" != "$md_count" ]]; then
            echo "Mismatch: $decorator_count @mcp_for_unity_tool decorators vs $md_count reference pages." >&2
            echo "Run: cd Server && uv run python ../tools/generate_docs_reference.py" >&2
            exit 1
          fi