08-maintenance_docs-orphan-check.yml

name: Docs Orphan Check

# Detects orphaned module-doc directories in docs/de and docs/en and reports
# broken PRIMARY_SOURCES references back to supported source-doc roots
# such as src/, include/, examples/, tools/, benchmarks/, tests/,
# and external/chimera/.
#
# Triggers:
#   - Push to develop/main that touches supported source-doc roots or docs/de/, docs/en/
#   - Any pull_request touching those paths
#   - Daily schedule at 04:00 UTC
#   - Manual dispatch

on:
  push:
    branches: [develop, main]
    paths:
      - 'src/*/**'
      - 'include/*/**'
      - 'examples/*/**'
      - 'tools/*/**'
      - 'benchmarks/*/**'
      - 'tests/*/**'
      - 'docs/de/**'
      - 'docs/en/**'
      - 'tools/module_docs_builder.py'
      - 'scripts/docs-orphan-check.py'
      - '.github/workflows/08-maintenance_docs-orphan-check.yml'
  pull_request:
    branches: [develop, main]
    paths:
      - 'src/*/**'
      - 'include/*/**'
      - 'examples/*/**'
      - 'tools/*/**'
      - 'benchmarks/*/**'
      - 'tests/*/**'
      - 'docs/de/**'
      - 'docs/en/**'
      - 'tools/module_docs_builder.py'
      - 'scripts/docs-orphan-check.py'
      - '.github/workflows/08-maintenance_docs-orphan-check.yml'
  schedule:
    - cron: '0 4 * * *'   # Daily at 04:00 UTC
  workflow_dispatch:
    inputs:
      fail_on_findings:
        description: 'Fail the workflow when orphan module-doc dirs or broken references are found'
        type: boolean
        default: false

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  check:
    name: docs/de + docs/en Orphan Check
    runs-on: ubuntu-latest

    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Run docs orphan check
        id: orphan_check
        run: |
          FAIL_FLAG=""
          if [ "${{ inputs.fail_on_findings }}" = "true" ]; then
            FAIL_FLAG="--fail-on-findings"
          fi

          python3 scripts/docs-orphan-check.py \
            --format text \
            --output /tmp/docs-orphan-check.txt \
            $FAIL_FLAG

      - name: Generate JSON orphan report
        if: always()
        run: |
          python3 scripts/docs-orphan-check.py \
            --format json \
            --output /tmp/docs-orphan-check.json \
            --quiet
        continue-on-error: true

      - name: Upload orphan-check reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: docs-orphan-check-${{ github.run_number }}
          path: |
            /tmp/docs-orphan-check.txt
            /tmp/docs-orphan-check.json
          retention-days: 30
          if-no-files-found: ignore

      - name: Write job summary
        if: always()
        run: |
          {
            echo "## Docs Orphan Check"
            echo ""
            echo "| Parameter | Value |"
            echo "|-----------|-------|"
            echo "| **Script** | \`scripts/docs-orphan-check.py\` |"
            echo "| **Docs roots** | \`docs/de\`, \`docs/en\` |"
            echo "| **Event** | \`${{ github.event_name }}\` |"
            echo "| **Branch** | \`${{ github.ref_name }}\` |"
            if [ -f /tmp/docs-orphan-check.json ]; then
              CODE=$(python3 -c "import json; d=json.load(open('/tmp/docs-orphan-check.json')); print(d['summary']['code_modules'])" 2>/dev/null || echo "n/a")
              DIRS=$(python3 -c "import json; d=json.load(open('/tmp/docs-orphan-check.json')); print(d['summary']['module_docs_dirs'])" 2>/dev/null || echo "n/a")
              ORPHANS=$(python3 -c "import json; d=json.load(open('/tmp/docs-orphan-check.json')); print(d['summary']['orphan_module_dirs'])" 2>/dev/null || echo "n/a")
              BROKEN=$(python3 -c "import json; d=json.load(open('/tmp/docs-orphan-check.json')); print(d['summary']['broken_primary_references'])" 2>/dev/null || echo "n/a")
              echo "| **Code modules** | ${CODE} |"
              echo "| **Module doc dirs** | ${DIRS} |"
              echo "| **Orphan dirs** | ${ORPHANS} |"
              echo "| **Broken references** | ${BROKEN} |"
            fi
            echo ""

            if [ -f /tmp/docs-orphan-check.txt ]; then
              echo "**Text Report:**"
              echo '```'
              cat /tmp/docs-orphan-check.txt
              echo '```'
            fi
          } >> "$GITHUB_STEP_SUMMARY"