documentation-validation.yml

name: Documentation Quality Gate

on:
  pull_request:
    paths:
      - '**/*.md'
      - 'docs/**'
      - 'scripts/documentation/**'
      - '.github/workflows/documentation-validation.yml'
  push:
    branches: [main, develop]
  schedule:
    - cron: '0 0 * * 0'  # Weekly full scan on Sunday
  workflow_dispatch:

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

permissions: {}

env:
  PYTHON_VERSION: "3.11"
  UV_VERSION: "0.5.7"

jobs:
  validate-links:
    name: Validate Documentation Links
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install UV
        uses: astral-sh/setup-uv@v5
        with:
          version: ${{ env.UV_VERSION }}

      - name: Set up Python
        run: uv python install ${{ env.PYTHON_VERSION }}

      - name: Install dependencies
        run: |
          uv sync --all-extras --dev

      - name: Create output directory
        run: mkdir -p output

      - name: Run link validation
        run: |
          uv run python scripts/documentation/validate_links_comprehensive.py \
            --repo-root . \
            --output output \
            --format both \
            --fail-on-broken

      - name: Upload link validation results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: link-validation-results
          path: |
            output/link_validation.json
            output/link_validation.md
          retention-days: 30

      - name: Display link validation summary
        if: always()
        run: |
          if [ -f output/link_validation.json ]; then
            python3 -c "
            import json
            with open('output/link_validation.json') as f:
                data = json.load(f)
            broken = sum(1 for r in data if r.get('status') == 'broken')
            ok = sum(1 for r in data if r.get('status') == 'ok')
            ext = sum(1 for r in data if r.get('status') == 'external')
            print('\n## Link Validation Summary')
            print(f'- Total link checks: {len(data)}')
            print(f'- OK: {ok}')
            print(f'- Broken: {broken}')
            print(f'- External: {ext}')
            "
          fi

  check-quality:
    name: Check Content Quality
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install UV
        uses: astral-sh/setup-uv@v5
        with:
          version: ${{ env.UV_VERSION }}

      - name: Set up Python
        run: uv python install ${{ env.PYTHON_VERSION }}

      - name: Install dependencies
        run: |
          uv sync --all-extras --dev

      - name: Create output directory
        run: mkdir -p output

      - name: Analyze content quality
        run: |
          uv run python scripts/documentation/analyze_content_quality.py \
            --repo-root . \
            --output output \
            --format both \
            --min-score 60
        continue-on-error: true

      - name: Upload quality results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: quality-analysis-results
          path: |
            output/content_quality.json
            output/content_quality.md
          retention-days: 30

      - name: Display quality summary
        if: always()
        run: |
          if [ -f output/content_quality.json ]; then
            python3 -c "
            import json
            with open('output/content_quality.json') as f:
                data = json.load(f)
            n = len(data)
            avg = sum(q['score'] for q in data) / n if n else 0
            ph = sum(q['metrics'].get('placeholder_count', 0) for q in data)
            low = sum(1 for q in data if q['score'] < 60)
            print('\n## Content Quality Summary')
            print(f'- Files analyzed: {n}')
            print(f'- Average score: {avg:.1f}/100')
            print(f'- Total placeholders: {ph}')
            print(f'- Files below 60: {low}')
            "
          fi

  validate-structure:
    name: Validate AGENTS.md Structure
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install UV
        uses: astral-sh/setup-uv@v5
        with:
          version: ${{ env.UV_VERSION }}

      - name: Set up Python
        run: uv python install ${{ env.PYTHON_VERSION }}

      - name: Install dependencies
        run: |
          uv sync --all-extras --dev

      - name: Create output directory
        run: mkdir -p output

      - name: Validate AGENTS.md structure
        run: |
          uv run python scripts/documentation/validate_agents_structure.py \
            --repo-root . \
            --output output \
            --format both
        continue-on-error: true

      - name: Upload structure validation results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: agents-structure-results
          path: |
            output/agents_validation.json
            output/agents_validation.md
          retention-days: 30

      - name: Display structure validation summary
        if: always()
        run: |
          if [ -f output/agents_validation.json ]; then
            python3 -c "
            import json
            with open('output/agents_validation.json') as f:
                data = json.load(f)
            total = len(data)
            valid = sum(1 for a in data if a.get('valid'))
            print('\n## AGENTS.md Structure Summary')
            print(f'- Total files: {total}')
            print(f'- Valid files: {valid}')
            print(f'- Invalid files: {total - valid}')
            "
          fi

  generate-dashboard:
    name: Generate Documentation Dashboard
    needs: [validate-links, check-quality, validate-structure]
    runs-on: ubuntu-latest
    if: always()
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install UV
        uses: astral-sh/setup-uv@v5
        with:
          version: ${{ env.UV_VERSION }}

      - name: Set up Python
        run: uv python install ${{ env.PYTHON_VERSION }}

      - name: Install dependencies
        run: |
          uv sync --all-extras --dev

      - name: Create output directory
        run: mkdir -p output

      - name: Download all artifacts
        uses: actions/download-artifact@v4
        with:
          path: artifacts

      - name: Consolidate results
        run: |
          # Move all JSON results to output directory
          find artifacts -name "*.json" -exec cp {} output/ \;
          find artifacts -name "*.html" -exec cp {} output/ \;

      - name: Generate dashboard
        run: |
          uv run python scripts/documentation/generate_dashboard.py \
            --repo-root . \
            --output output

      - name: Upload dashboard
        uses: actions/upload-artifact@v4
        with:
          name: documentation-dashboard
          path: output/documentation_dashboard.html
          retention-days: 90

      - name: Publish dashboard to GitHub Pages
        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./output
          destination_dir: documentation-quality
          keep_files: false

  enforce-quality-gate:
    name: Enforce Quality Gates
    needs: [validate-links, check-quality, validate-structure]
    runs-on: ubuntu-latest
    if: always() && github.event_name == 'pull_request'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install UV
        uses: astral-sh/setup-uv@v5
        with:
          version: ${{ env.UV_VERSION }}

      - name: Set up Python
        run: uv python install ${{ env.PYTHON_VERSION }}

      - name: Install dependencies
        run: |
          uv sync --all-extras --dev

      - name: Create output directory
        run: mkdir -p output

      - name: Download all artifacts
        uses: actions/download-artifact@v4
        with:
          path: artifacts

      - name: Consolidate results
        run: |
          find artifacts -name "*.json" -exec cp {} output/ \;

      - name: Enforce quality gates
        run: |
          uv run python scripts/documentation/enforce_quality_gate.py \
            --repo-root . \
            --output output \
            --min-quality-score 70 \
            --max-broken-links 10 \
            --max-placeholders 100 \
            --min-agents-valid-rate 80 \
            --allow-warnings

      - name: Comment PR with results
        if: always() && github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            let comment = '## 📚 Documentation Quality Check Results\n\n';
            
            // Add summary from each validation
            const files = [
              'output/link_validation.json',
              'output/content_quality.json',
              'output/agents_validation.json'
            ];
            
            for (const file of files) {
              if (fs.existsSync(file)) {
                const data = JSON.parse(fs.readFileSync(file, 'utf8'));
                if (file.includes('link_validation')) {
                  const broken = Array.isArray(data) ? data.filter(r => r.status === 'broken').length : 0;
                  const total = Array.isArray(data) ? data.length : 0;
                  comment += '### 🔗 Link Validation\n';
                  comment += `- Link checks: ${total}\n`;
                  comment += `- Broken: ${broken}\n\n`;
                } else if (file.includes('content_quality')) {
                  const arr = Array.isArray(data) ? data : [];
                  const n = arr.length;
                  const avg = n ? arr.reduce((s, q) => s + (q.score || 0), 0) / n : 0;
                  const ph = arr.reduce((s, q) => s + (q.metrics?.placeholder_count || 0), 0);
                  comment += '### 📊 Content Quality\n';
                  comment += `- Average score: ${avg.toFixed(1)}/100\n`;
                  comment += `- Total placeholders: ${ph}\n\n`;
                } else if (file.includes('agents_validation')) {
                  const arr = Array.isArray(data) ? data : [];
                  const total = arr.length;
                  const valid = arr.filter(a => a.valid).length;
                  comment += '### 🤖 AGENTS.md Structure\n';
                  comment += `- Valid files: ${valid}/${total}\n`;
                  comment += `- Invalid files: ${total - valid}\n\n`;
                }
              }
            }
            
            comment += '\n[View detailed dashboard →](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})';
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });