auto-sync-docs.yml

name: Auto Sync Docs

on:
  push:
    branches:
      - develop
  workflow_dispatch:

# Ensure the token used by steps has the rights to create branches/PRs when available.
permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  auto-sync-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          # Need full history for diff against origin/main
          fetch-depth: 0
      - name: Check for outdated references in docs and wiki
        run: |
          # Search for the word 'template' but ignore known benign occurrences:
          # - files under docs/archive/ (historical notes)
          # - Prometheus console flag lines which include 'templates' as part of the flag
            if grep -rnI --line-number -E '\.template\b' docs/ wiki-content/ | grep -v -E '^docs/archive/|--web.console.templates=' > /tmp/outdated_refs.txt; then
            echo "❌ Outdated references found:"
            cat /tmp/outdated_refs.txt
            # Fail the job when running in CI
            exit 1
          else
            echo "✅ No outdated references found."
          fi
      - name: Validate Markdown links in docs and wiki
        run: |
          set -euo pipefail
          echo "Collecting markdown files (excluding docs/archive/)..."
          # Docs: count and run link-check if any (exclude archived docs)
          DOCS_COUNT=$(find docs -type f -name '*.md' ! -path 'docs/archive/*' 2>/dev/null | wc -l | tr -d ' ' || true)
          if [ -n "$DOCS_COUNT" ] && [ "$DOCS_COUNT" -gt 0 ]; then
            echo "Running markdown-link-check on $DOCS_COUNT docs files..."
            find docs -type f -name '*.md' ! -path 'docs/archive/*' -print0 \
              | xargs -0 npx -y markdown-link-check@3.14.2 --config .markdown-link-check.json
          else
            echo "No docs markdown files found to check."
          fi

          # Wiki: only run if directory exists and files found
          if [ -d wiki-content ]; then
            WIKI_COUNT=$(find wiki-content -type f -name '*.md' 2>/dev/null | wc -l | tr -d ' ' || true)
            if [ -n "$WIKI_COUNT" ] && [ "$WIKI_COUNT" -gt 0 ]; then
              echo "Running markdown-link-check on $WIKI_COUNT wiki files..."
              find wiki-content -type f -name '*.md' -print0 \
                | xargs -0 npx -y markdown-link-check@3.14.2 --config .markdown-link-check.json
            else
              echo "No wiki markdown files found to check."
            fi
          else
            echo "No wiki-content directory present, skipping wiki link-check."
          fi
      - name: Generate Documentation and Wiki Patch
        id: gen-patch
        run: |
          # Produce a unified diff of docs and wiki content against origin/main
          set -euo pipefail
          git fetch origin main --depth=1 || true
          git diff origin/main -- docs/ wiki-content/ > docs-wiki-full-patch.diff || true
          # Expose whether the patch file contains changes so downstream steps can skip when nothing changed
          if [ -s docs-wiki-full-patch.diff ]; then
            echo "changed=true" >> "$GITHUB_OUTPUT"
          else
            echo "changed=false" >> "$GITHUB_OUTPUT"
          fi
      - name: Upload Docs and Wiki Patch Artifact
        uses: actions/upload-artifact@v7
        with:
          name: docs-wiki-full-patch
          path: docs-wiki-full-patch.diff
      - name: Find existing auto-sync PR into develop
        id: find-pr
        if: steps.gen-patch.outputs.changed == 'true'
        uses: actions/github-script@v8
        with:
          script: |
            const fs = require('fs');
            const owner = context.repo.owner;
            const repo = context.repo.repo;
            const pulls = await github.rest.pulls.list({ owner, repo, base: 'develop', state: 'open', per_page: 100 });
            const found = pulls.data.find(p => p.head && p.head.ref && p.head.ref.startsWith('docs-wiki/auto-sync-'));
            const info = { pr_found: false, pr_number: null, pr_branch: null };
            if (found) {
              info.pr_found = true;
              info.pr_number = found.number;
              info.pr_branch = found.head.ref;
            }
            fs.writeFileSync('pr-info.json', JSON.stringify(info));

      - name: Update existing auto-sync branch (if present)
        run: |
          set -euo pipefail
          if [ ! -f pr-info.json ]; then
            echo "pr-info.json not found; skipping update step"
            exit 0
          fi
          PR_FOUND=$(jq -r '.pr_found' pr-info.json)
          PR_BRANCH=$(jq -r '.pr_branch' pr-info.json)
          if [ "$PR_FOUND" != "true" ]; then
            echo "No existing auto-sync PR found; skipping update step"
            exit 0
          fi
          echo "Found existing PR branch: $PR_BRANCH. Updating with new patch..."
          PATCH_FILE='docs-wiki-full-patch.diff'
          # Move patch aside to avoid checkout conflicts with untracked files
          if [ -f "$PATCH_FILE" ]; then
            TMP_PATCH=$(mktemp)
            mv "$PATCH_FILE" "$TMP_PATCH"
            PATCH_MOVED=true
          else
            PATCH_MOVED=false
          fi
          # Ensure we have full history and the target branch fetched
          git fetch origin +refs/heads/$PR_BRANCH:refs/remotes/origin/$PR_BRANCH || true
          # Create or reset local branch to the remote head
          if git show-ref --verify --quiet refs/remotes/origin/$PR_BRANCH; then
            git checkout -B $PR_BRANCH origin/$PR_BRANCH
          else
            git checkout -B $PR_BRANCH
          fi
          # Restore patch into working tree
          if [ "$PATCH_MOVED" = true ]; then
            mv "$TMP_PATCH" "$PATCH_FILE"
          fi
          # Apply the generated diff; if no changes, commit will be skipped
          if git apply --index "$PATCH_FILE"; then
            git commit -m "docs: automated documentation and wiki sync (update existing PR)" || echo "No changes to commit"
            git push origin HEAD:$PR_BRANCH
          else
            echo "git apply failed or resulted in no changes; aborting update step"
          fi
          # Clean up temp file if any remains
          if [ -n "${TMP_PATCH:-}" ] && [ -f "${TMP_PATCH}" ]; then
            rm -f "${TMP_PATCH}"
          fi

      - name: Create Pull Request for Docs and Wiki Updates (new PR)
        if: steps.gen-patch.outputs.changed == 'true'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          # Read pr-info.json if present
          if [ -f pr-info.json ]; then
            PR_FOUND=$(jq -r '.pr_found' pr-info.json)
          else
            PR_FOUND=false
          fi
          if [ "$PR_FOUND" = "true" ]; then
            echo "Existing PR found; skipping new PR creation."
            exit 0
          fi

          BRANCH="docs-wiki/auto-sync-${{ github.run_id }}"
          echo "Creating new branch $BRANCH from develop and applying patch..."
          git fetch origin develop
          git checkout -b "$BRANCH" origin/develop

          # Apply patch; if it fails or produces no changes, we still try to commit safely
          if git apply --index docs-wiki-full-patch.diff; then
            git commit -m "docs: automated documentation and wiki sync" || echo "No changes to commit"
          else
            echo "git apply failed or produced no changes; attempting to continue if commit possible"
            git commit -m "docs: automated documentation and wiki sync" || echo "No changes to commit"
          fi

          echo "Pushing branch to origin..."
          git push origin HEAD:"$BRANCH"

          echo "Creating PR via REST API..."
          API_URL="https://api.github.com/repos/${{ github.repository }}/pulls"
          PR_BODY=$(jq -Rs . < docs-wiki-full-patch.diff || echo '"Patch unavailable"')
          PAYLOAD=$(jq -n --arg title "Automated Documentation and Wiki Sync" \
            --arg head "$BRANCH" --arg base "develop" --arg body "This PR was created automatically to sync documentation and wiki blocks/examples with the latest code and workflow changes. The full patch is attached as an artifact on the workflow run if you need to review the complete diff." \
            '{title: $title, head: $head, base: $base, body: $body}')

          resp=$(curl -sS -H "Authorization: Bearer $GITHUB_TOKEN" -H "Accept: application/vnd.github+json" -X POST "$API_URL" --data "$PAYLOAD" || true)
          echo "$resp" | jq -r '.html_url // .message'
      - name: Lint Markdown
        # yamllint disable-line rule:line-length
        uses: DavidAnson/markdownlint-cli2-action@07035fd053f7be764496c0f8d8f9f41f98305101  # v22.0.0
        with:
          globs: |
            docs/**/*.md
            wiki-content/**/*.md
            !docs/archive/**