docs-authority.yml

name: Documentation Authority CI

on:
  push:
    branches:
      - main
      - develop
  pull_request:
    branches:
      - main
      - develop
  workflow_dispatch: # Manual trigger
  schedule:
    - cron: '0 0 * * 0' # Weekly on Sunday at midnight UTC

jobs:
  build_and_validate_docs:
    name: Build & Validate Documentation
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
    - name: 📥 Checkout repository
      uses: actions/checkout@v4
      with:
        fetch-depth: 0 # Full history for accurate change detection

    - name: 🐍 Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.11'

    - name: 📦 Install dependencies
      run: |
        python -m pip install --upgrade pip
        # Add any Python dependencies here if needed
        # pip install -r requirements.txt

    - name: 🔨 Run documentation build script
      run: |
        python scripts/build-llms-docs.py
      continue-on-error: false

    - name: ✅ Validate llms-full.txt generation
      run: |
        if [ ! -f llms-full.txt ]; then
          echo "❌ Error: llms-full.txt was not generated"
          exit 1
        fi
        
        FILE_SIZE=$(wc -c < llms-full.txt)
        LINE_COUNT=$(wc -l < llms-full.txt)
        
        echo "✓ llms-full.txt generated successfully"
        echo "📊 File size: $FILE_SIZE bytes"
        echo "📄 Line count: $LINE_COUNT lines"
        
        # Validate minimum content
        if [ $LINE_COUNT -lt 100 ]; then
          echo "⚠️  Warning: llms-full.txt has fewer than 100 lines"
          echo "This might indicate missing documentation or build errors"
          exit 1
        fi

    - name: 🔍 Check for required documentation files
      run: |
        REQUIRED_DOCS=(
          "components/docs/DOC_POLICY.md"
          "components/docs/SECURITY.md"
          "components/docs/FRAMEWORK.md"
          "components/docs/API_REFERENCE.md"
          "components/docs/ARCHITECTURE.md"
        )
        
        MISSING=0
        for doc in "${REQUIRED_DOCS[@]}"; do
          if [ ! -f "$doc" ]; then
            echo "❌ Missing required documentation: $doc"
            MISSING=$((MISSING + 1))
          else
            echo "✓ Found: $doc"
          fi
        done
        
        if [ $MISSING -gt 0 ]; then
          echo "⚠️  $MISSING required documentation file(s) missing"
          exit 1
        fi

    - name: 📊 Generate documentation statistics
      run: |
        echo "## Documentation Statistics" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "- **Total Markdown Files:** $(find components/docs -name '*.md' | wc -l)" >> $GITHUB_STEP_SUMMARY
        echo "- **llms-full.txt Size:** $(wc -c < llms-full.txt) bytes" >> $GITHUB_STEP_SUMMARY
        echo "- **Total Lines:** $(wc -l < llms-full.txt) lines" >> $GITHUB_STEP_SUMMARY
        echo "- **Build Date:** $(date -u '+%Y-%m-%d %H:%M:%S UTC')" >> $GITHUB_STEP_SUMMARY

    - name: 📤 Upload llms-full.txt as artifact
      uses: actions/upload-artifact@v4
      with:
        name: llms-full-documentation-${{ github.sha }}
        path: llms-full.txt
        retention-days: 30
        if-no-files-found: error

    - name: 🎯 Comment on PR (if applicable)
      if: github.event_name == 'pull_request'
      uses: actions/github-script@v7
      with:
        script: |
          const fs = require('fs');
          const fileSize = fs.statSync('llms-full.txt').size;
          const lineCount = fs.readFileSync('llms-full.txt', 'utf8').split('\n').length;
          
          github.rest.issues.createComment({
            issue_number: context.issue.number,
            owner: context.repo.owner,
            repo: context.repo.repo,
            body: `## 📚 Documentation Build Results\n\n` +
                  `✅ Documentation successfully built and validated!\n\n` +
                  `- **Output Size:** ${(fileSize / 1024).toFixed(1)} KB\n` +
                  `- **Total Lines:** ${lineCount.toLocaleString()}\n` +
                  `- **Build Time:** ${new Date().toISOString()}\n\n` +
                  `The \`llms-full.txt\` artifact is available in the workflow run.`
          });

    - name: 🚀 Commit updated llms-full.txt (optional)
      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
      run: |
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action"
        
        if [ -n "$(git status --porcelain llms-full.txt)" ]; then
          git add llms-full.txt
          git commit -m "docs: auto-update llms-full.txt [skip ci]"
          git push
        else
          echo "No changes to llms-full.txt"
        fi