docs-validation.yml

name: Documentation Validation

on:
  push:
    branches:
      - 5.x
      - 6.x
      - 5.next
    paths:
      - 'docs/**'
      - '.github/**'
      - 'toc_*.json'
      - 'config.js'
  pull_request:
    paths:
      - 'docs/**'
      - '.github/**'
      - 'toc_*.json'
      - 'config.js'

jobs:
  js-lint:
    name: Validate JavaScript Files
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Validate config.js syntax
        run: node --check config.js

  json-lint:
    name: Validate JSON Files
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Validate JSON syntax
        run: |
          for file in toc_*.json; do
            if ! jq empty "$file" 2>/dev/null; then
              echo "Invalid JSON: $file"
              exit 1
            fi
            echo "✅ Valid: $file"
          done

  toc-link-check:
    name: Validate TOC Links
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Check TOC links exist
        run: node bin/check-toc-links.js

  markdown-lint:
    name: Lint Markdown
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Lint markdown files
        uses: DavidAnson/markdownlint-cli2-action@v22
        with:
          config: './.github/.markdownlint-cli2.jsonc'
          globs: 'docs/**/*.md'

  spell-check:
    name: Spell Check
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Check spelling
        uses: streetsidesoftware/cspell-action@v8
        with:
          files: 'docs/**/*.md'
          config: '.github/cspell.json'
          incremental_files_only: true

  link-check:
    name: Check Internal Links
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Get changed markdown files
        id: changed-files
        run: |
          if [ "${{ github.event_name }}" == "pull_request" ]; then
            # Get files changed in PR
            FILES=$(git diff --name-only --diff-filter=d origin/${{ github.base_ref }}...HEAD | grep '\.md$' || true)
            if [ -z "$FILES" ]; then
              echo "No markdown files changed"
              echo "files=" >> $GITHUB_OUTPUT
            else
              # Convert to space-separated list for script
              echo "files=$(echo $FILES | tr '\n' ' ')" >> $GITHUB_OUTPUT
              echo "Checking files:"
              echo "$FILES"
            fi
          else
            # For push events, check all files using glob pattern
            echo 'files="docs/**/*.md"' >> $GITHUB_OUTPUT
            echo 'Checking all files: docs/**/*.md'
          fi

      - name: Check internal links
        if: steps.changed-files.outputs.files != ''
        run: node bin/check-links.js --baseline .github/linkchecker-baseline.json ${{ steps.changed-files.outputs.files }}