ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      run_markdownlint:
        description: "Run Markdownlint"
        type: boolean
        default: false
      run_docs:
        description: "Run Docs Generation"
        type: boolean
        default: false
  workflow_call:
    inputs:
      run_docs:
        description: "Run Docs Generation"
        type: boolean
        default: true
    secrets:
      DOCS_TOKEN:
        description: "Token with write access to the docs repo"
        required: false

permissions:
  contents: write
  pull-requests: write

jobs:
  changes:
    name: Detect Changes
    runs-on: ubuntu-latest
    outputs:
      markdown: ${{ steps.filter.outputs.markdown }}
      docs: ${{ steps.filter.outputs.docs }}
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Check path filters
        id: filter
        uses: dorny/paths-filter@v4
        with:
          filters: |
            markdown:
              - '**/*.md'
            docs:
              - 'scripts/**/*.lua'
              - '.markdownlint.jsonc'
              - '.prettierrc.json'

  markdownlint:
    name: Markdownlint
    needs: changes
    if: |
      (github.event_name != 'workflow_dispatch' || inputs.run_markdownlint) &&
      (needs.changes.outputs.markdown == 'true' || inputs.run_markdownlint)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Lint Markdown
        run: npx --yes markdownlint-cli2 "**/*.md"

  discover:
    name: Discover Repositories
    needs: changes
    if: |
      github.event_name != 'pull_request' &&
      (github.event_name != 'workflow_dispatch' || inputs.run_docs) &&
      (needs.changes.outputs.markdown == 'true' || needs.changes.outputs.docs == 'true' || inputs.run_docs)
    runs-on: ubuntu-latest
    outputs:
      repos: ${{ steps.repos.outputs.repos }}
    steps:
      - name: Discover source repos
        id: repos
        env:
          GH_TOKEN: ${{ github.token }}
          ORG: ${{ github.repository_owner }}
        run: |
          set -euo pipefail

          RUNNING_REPO="${GITHUB_REPOSITORY#*/}"

          # Convert to lowercase to avoid case-sensitivity mismatches
          RUNNING_REPO="${RUNNING_REPO,,}"
          ORG="${ORG,,}"

          # If running on a library repo, return it and exit early
          if [ "${RUNNING_REPO}" != "${ORG}.github.io" ]; then
            clone_url="https://github.com/${GITHUB_REPOSITORY}.git"
            echo "repos=$(jq -cn --arg name "$RUNNING_REPO" --arg clone_url "$clone_url" '[{name: $name, clone_url: $clone_url}]')" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          tmp="$(mktemp -d)"
          repos_file="$tmp/repos.jsonl"

          gh api --paginate "/orgs/${ORG}/repos" \
            --jq '.[] | select(.archived == false and .disabled == false) | [.name, .clone_url] | @tsv' \
            > "$repos_file"

          found="[]"
          while IFS=$'\t' read -r name clone_url; do
            name_lower="${name,,}"
            [ "${name_lower}" != "${ORG}.github.io" ] || continue

            if gh api "/repos/${ORG}/${name}/contents/types" >/dev/null 2>&1; then
              found="$(jq --arg name "$name" --arg clone_url "$clone_url" \
                '. + [{ "name": $name, "clone_url": $clone_url }]' <<< "$found")"
            fi
          done < "$repos_file"

          echo "repos=$(jq -c . <<< "$found")" >> "$GITHUB_OUTPUT"

  generate:
    name: Generate API Docs (${{ matrix.repo.name }})
    needs: discover
    if: ${{ needs.discover.outputs.repos != '[]' }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        repo: ${{ fromJson(needs.discover.outputs.repos) }}
    steps:
      - name: Checkout docs repo
        uses: actions/checkout@v6
        with:
          repository: ${{ github.repository_owner }}/${{ github.repository_owner }}.github.io
          path: _docs

      - name: Checkout source repo
        uses: actions/checkout@v6
        with:
          repository: ${{ github.repository_owner }}/${{ matrix.repo.name }}
          path: _source
          fetch-depth: 1

      - name: Validate types directory
        run: |
          if [ ! -d "_source/types" ]; then
            echo "::error::The 'types' directory does not exist in the source repository: ${{ matrix.repo.name }}"
            exit 1
          fi

      - name: Setup LuaJIT
        uses: leafo/gh-actions-lua@v13
        with:
          luaVersion: "luajit"

      - name: Generate docs
        run: |
          set -euo pipefail

          output_dir="_docs/docs/src/${REPO_NAME}/api"
          mkdir -p "$output_dir"
          find "$output_dir" -maxdepth 1 -type f -name "*.md" ! -name "ecodes.md" -delete

          luajit _docs/scripts/generate-api-docs.lua "_source/types" "$output_dir"
        env:
          REPO_NAME: ${{ matrix.repo.name }}

      - name: Format docs
        run: |
          set -euo pipefail

          if compgen -G "_docs/docs/src/${REPO_NAME}/api/*.md" > /dev/null; then
            npx --yes prettier@3.8.3 --write "_docs/docs/src/${REPO_NAME}/api/*.md"
          fi
        env:
          REPO_NAME: ${{ matrix.repo.name }}

      - name: Open docs PR
        uses: peter-evans/create-pull-request@v8
        with:
          token: ${{ secrets.DOCS_TOKEN }}
          path: _docs
          commit-message: "docs(${{ matrix.repo.name }}): generate API docs"
          title: "docs(${{ matrix.repo.name }}): generate API docs"
          body: "Generate and format API docs from `${{ matrix.repo.name }}` LuaLS type annotations."
          branch: "automation/generate-docs-${{ matrix.repo.name }}"
          add-paths: |
            docs/src/${{ matrix.repo.name }}/api