docs-validation.yml

name: Documentation Validation

on:
  pull_request:
    paths:
      - 'docs/**'
      - 'scripts/validar_estructura_docs.sh'
      - '.github/workflows/docs-validation.yml'
  push:
    branches:
      - main
      - develop
      - 'claude/**'
    paths:
      - 'docs/**'

jobs:
  validate-structure:
    name: Validate Docs Structure
    runs-on: ubuntu-latest

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

      - name: Make validation script executable
        run: chmod +x scripts/validar_estructura_docs.sh

      - name: Run structure validation
        run: |
          echo "::group::Validating documentation structure"
          ./scripts/validar_estructura_docs.sh
          echo "::endgroup::"

      - name: Check validation result
        if: failure()
        run: |
          echo "::error::Documentation structure validation failed"
          echo "Please review the errors above and fix them"
          exit 1

  check-old-references:
    name: Check for Old Structure References
    runs-on: ubuntu-latest

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

      - name: Check for old structure references
        run: bash scripts/validation/docs/check_docs_old_references.sh

  check-markdown-links:
    name: Check Markdown Links
    runs-on: ubuntu-latest

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

      - name: Install markdown-link-check
        run: npm install -g markdown-link-check

      - name: Check internal links in critical docs
        run: |
          echo "::group::Checking internal links"

          # Check critical documentation files
          CRITICAL_DOCS=(
            "docs/README.md"
            "docs/backend/README.md"
            "docs/frontend/README.md"
            "docs/infrastructure/README.md"
            "docs/anexos/analisis_nov_2025/RESUMEN_EJECUTIVO_REORGANIZACION.md"
          )

          ERROR_COUNT=0

          for doc in "${CRITICAL_DOCS[@]}"; do
            if [ -f "$doc" ]; then
              echo "Checking: $doc"
              if ! markdown-link-check "$doc" --config .github/markdown-link-check-config.json 2>/dev/null; then
                echo "::warning::Broken links found in $doc"
                ERROR_COUNT=$((ERROR_COUNT + 1))
              fi
            fi
          done

          if [ $ERROR_COUNT -gt 0 ]; then
            echo "::warning::Found $ERROR_COUNT files with broken links"
            echo "Please review and fix broken links"
            # Don't fail the build for broken links, just warn
          else
            echo "[OK] All checked links are valid"
          fi

          echo "::endgroup::"
        continue-on-error: true

  validate-auto-generated-docs:
    name: Validate Auto-Generated Docs
    runs-on: ubuntu-latest

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

      - name: Check auto-generated docs metadata
        run: bash scripts/validation/docs/validate_autogenerated_docs.sh

  count-docs-stats:
    name: Documentation Statistics
    runs-on: ubuntu-latest

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

      - name: Generate documentation statistics
        run: bash scripts/validation/docs/generate_docs_stats.sh

  summary:
    name: Validation Summary
    runs-on: ubuntu-latest
    needs: [validate-structure, check-old-references, validate-auto-generated-docs, count-docs-stats]
    if: always()

    steps:
      - name: Check overall status
        run: |
          echo "::group::Validation Summary"

          if [ "${{ needs.validate-structure.result }}" == "success" ] && \
             [ "${{ needs.check-old-references.result }}" == "success" ] && \
             [ "${{ needs.validate-auto-generated-docs.result }}" == "success" ]; then
            echo "[PASS] All documentation validation checks passed!"
            echo ""
            echo "Documentation structure is valid and consistent."
          else
            echo "[FAIL] Some documentation validation checks failed"
            echo ""
            echo "Results:"
            echo "  - Structure validation: ${{ needs.validate-structure.result }}"
            echo "  - Old references check: ${{ needs.check-old-references.result }}"
            echo "  - Auto-generated docs: ${{ needs.validate-auto-generated-docs.result }}"
            echo ""
            echo "Please review the errors above and fix them before merging."
            exit 1
          fi

          echo "::endgroup::"