documentation.yml

name: Documentation Quality Assurance

on:
  push:
    branches: [ main, develop, 'claude/**' ]
    paths:
      - 'docs/**'
      - '**.md'
      - '.github/workflows/documentation.yml'
  pull_request:
    branches: [ main, develop ]
    paths:
      - 'docs/**'
      - '**.md'

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

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

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

      - name: Check required files
        run: |
          echo "Checking for required documentation files..."

          REQUIRED_FILES=(
            "README.md"
            "01-getting-started/README.md"
            "02-architecture/README.md"
            "03-development/CLAUDE.md"
            "03-development/README.md"
            "04-api/README.md"
            "05-testing/README.md"
            "06-deployment/README.md"
            "07-status/README.md"
          )

          MISSING=0
          for file in "${REQUIRED_FILES[@]}"; do
            if [ ! -f "$file" ]; then
              echo "MISSING: $file"
              MISSING=$((MISSING + 1))
            else
              echo "OK: $file"
            fi
          done

          if [ $MISSING -gt 0 ]; then
            echo "::error::$MISSING required documentation files missing"
            exit 1
          fi

          echo "All required documentation files present"

      - name: Check folder structure
        run: |
          echo "Checking documentation folder structure..."

          REQUIRED_DIRS=(
            "01-getting-started"
            "02-architecture"
            "02-architecture/diagrams"
            "03-development"
            "04-api"
            "05-testing"
            "06-deployment"
            "07-status"
            "archive"
          )

          MISSING=0
          for dir in "${REQUIRED_DIRS[@]}"; do
            if [ ! -d "$dir" ]; then
              echo "MISSING: $dir"
              MISSING=$((MISSING + 1))
            else
              echo "OK: $dir"
            fi
          done

          if [ $MISSING -gt 0 ]; then
            echo "::error::$MISSING required directories missing"
            exit 1
          fi

          echo "All required directories present"

  check-links:
    name: Check for Broken Links
    runs-on: ubuntu-latest

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

      - name: Check markdown links
        uses: gaurav-nelson/github-action-markdown-link-check@v1
        with:
          use-quiet-mode: 'yes'
          config-file: '.github/markdown-link-check-config.json'
          check-modified-files-only: 'yes'
          base-branch: 'main'

  generate-report:
    name: Generate Documentation Report
    runs-on: ubuntu-latest
    needs: [validate-structure, check-links]

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

      - name: Generate documentation metrics
        env:
          GITHUB_REF_NAME_SAFE: ${{ github.ref_name }}
          GITHUB_SHA_SAFE: ${{ github.sha }}
        run: |
          echo "# Documentation Quality Report" > docs-report.md
          echo "" >> docs-report.md
          echo "**Date:** $(date)" >> docs-report.md
          echo "**Branch:** ${GITHUB_REF_NAME_SAFE}" >> docs-report.md
          echo "**Commit:** ${GITHUB_SHA_SAFE}" >> docs-report.md
          echo "" >> docs-report.md
          echo "## Metrics" >> docs-report.md
          echo "" >> docs-report.md

          MD_COUNT=$(find . -name "*.md" -type f | wc -l)
          echo "- Total markdown files: $MD_COUNT" >> docs-report.md

          TOTAL_LINES=$(find . -name "*.md" -type f -exec wc -l {} + | tail -1 | awk '{print $1}')
          echo "- Total documentation lines: $TOTAL_LINES" >> docs-report.md

          DIAGRAM_COUNT=$(find 02-architecture/diagrams -name "*.png" 2>/dev/null | wc -l)
          echo "- Total diagrams: $DIAGRAM_COUNT" >> docs-report.md

          FOLDER_COUNT=$(find . -type d -not -path '*/\.*' | wc -l)
          echo "- Total folders: $FOLDER_COUNT" >> docs-report.md

          echo "" >> docs-report.md
          echo "## Quality Checks" >> docs-report.md
          echo "" >> docs-report.md
          echo "Documentation structure validated" >> docs-report.md
          echo "No broken links found" >> docs-report.md
          echo "All required files present" >> docs-report.md

          echo "" >> docs-report.md
          echo "## Documentation Organization" >> docs-report.md
          echo "" >> docs-report.md
          echo '```' >> docs-report.md
          tree -L 2 -d --charset ascii || ls -R | head -50
          echo '```' >> docs-report.md

          cat docs-report.md

      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: documentation-report
          path: docs-report.md
          retention-days: 30

  success-notification:
    name: Documentation Quality Passed
    runs-on: ubuntu-latest
    needs: [validate-structure, check-links, generate-report]
    if: success()

    steps:
      - name: Success message
        run: |
          echo "Documentation quality assurance passed!"
          echo "All checks completed successfully"