docs-ci.yml

name: Documentation Quality CI

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

jobs:
  validate-documentation:
    name: Validate Documentation Quality
    runs-on: ubuntu-latest

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

      - name: Set up dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y bc jq python3 python3-yaml

      - name: Make scripts executable
        run: chmod +x docs/scripts/*.sh

      - name: Run link validation
        id: links
        run: |
          echo "Running link validation..."
          docs/scripts/validate-links.sh --json > /tmp/links.json || true
          cat /tmp/links.json
          echo "links_result=$(cat /tmp/links.json | jq -r '.success_rate')" >> $GITHUB_OUTPUT

      - name: Run frontmatter validation
        id: frontmatter
        run: |
          echo "Running frontmatter validation..."
          docs/scripts/validate-frontmatter.sh --json > /tmp/frontmatter.json || true
          cat /tmp/frontmatter.json
          echo "frontmatter_result=$(cat /tmp/frontmatter.json | jq -r '.success_rate')" >> $GITHUB_OUTPUT

      - name: Run Mermaid diagram validation
        id: mermaid
        run: |
          echo "Running Mermaid validation..."
          docs/scripts/validate-mermaid.sh --json > /tmp/mermaid.json || true
          cat /tmp/mermaid.json
          echo "mermaid_result=$(cat /tmp/mermaid.json | jq -r '.success_rate')" >> $GITHUB_OUTPUT

      - name: Detect ASCII diagrams
        id: ascii
        run: |
          echo "Detecting ASCII diagrams..."
          docs/scripts/detect-ascii.sh --json > /tmp/ascii.json || true
          cat /tmp/ascii.json
          echo "ascii_count=$(cat /tmp/ascii.json | jq -r '.ascii_diagrams_found')" >> $GITHUB_OUTPUT

      - name: Validate UK English spelling
        id: spelling
        run: |
          echo "Validating UK English spelling..."
          docs/scripts/validate-spelling.sh --json > /tmp/spelling.json || true
          cat /tmp/spelling.json
          echo "spelling_errors=$(cat /tmp/spelling.json | jq -r '.spelling_errors')" >> $GITHUB_OUTPUT

      - name: Validate structure
        id: structure
        run: |
          echo "Validating structure..."
          docs/scripts/validate-structure.sh --json > /tmp/structure.json || true
          cat /tmp/structure.json
          echo "structure_errors=$(cat /tmp/structure.json | jq -r '.structure_errors')" >> $GITHUB_OUTPUT

      - name: Calculate overall quality score
        id: quality
        run: |
          links_score=${{ steps.links.outputs.links_result }}
          frontmatter_score=${{ steps.frontmatter.outputs.frontmatter_result }}
          mermaid_score=${{ steps.mermaid.outputs.mermaid_result }}
          ascii_count=${{ steps.ascii.outputs.ascii_count }}
          spelling_errors=${{ steps.spelling.outputs.spelling_errors }}
          structure_errors=${{ steps.structure.outputs.structure_errors }}

          # Calculate weighted score
          overall_score=$(echo "scale=2; ($links_score + $frontmatter_score + $mermaid_score) / 3 - ($ascii_count * 2) - ($spelling_errors * 0.5) - ($structure_errors * 0.5)" | bc)

          # Ensure 0-100 range
          if (( $(echo "$overall_score < 0" | bc -l) )); then
            overall_score=0
          elif (( $(echo "$overall_score > 100" | bc -l) )); then
            overall_score=100
          fi

          echo "overall_score=$overall_score" >> $GITHUB_OUTPUT
          echo "### Documentation Quality Score: ${overall_score}%" >> $GITHUB_STEP_SUMMARY

          if (( $(echo "$overall_score >= 90" | bc -l) )); then
            echo "✅ Documentation quality is excellent!" >> $GITHUB_STEP_SUMMARY
          else
            echo "⚠️ Documentation quality needs improvement" >> $GITHUB_STEP_SUMMARY
          fi

      - name: Generate report
        if: always()
        run: |
          docs/scripts/generate-reports.sh

      - name: Upload validation reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: validation-reports
          path: docs/reports/
          retention-days: 30

      - name: Comment PR with results
        if: github.event_name == 'pull_request' && always()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const reportPath = 'docs/reports/';
            const files = fs.readdirSync(reportPath).filter(f => f.endsWith('.md'));

            if (files.length > 0) {
              const latestReport = files.sort().reverse()[0];
              const report = fs.readFileSync(reportPath + latestReport, 'utf8');

              github.rest.issues.createComment({
                issue_number: context.issue.number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: report
              });
            }

      - name: Check quality threshold
        run: |
          overall_score=${{ steps.quality.outputs.overall_score }}

          if (( $(echo "$overall_score < 90" | bc -l) )); then
            echo "❌ Documentation quality score ($overall_score%) is below the required threshold of 90%"
            exit 1
          else
            echo "✅ Documentation quality score ($overall_score%) meets the threshold"
          fi