docs.yml

name: Check Documentation

on:
  pull_request:
    paths:
      - 'lib/**/*.dart'
      - 'README.md'
  workflow_dispatch:

jobs:
  doc-check:
    name: Documentation Check
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.27.0'
          channel: 'stable'
          cache: true

      - name: Get dependencies
        run: flutter pub get

      - name: Generate documentation
        run: |
          dart doc --output docs/api
          echo "Documentation generated successfully!"

      - name: Check for undocumented public APIs
        run: |
          echo "## 📚 Documentation Coverage" > doc_report.md
          echo "" >> doc_report.md
          
          # Check for missing documentation
          flutter analyze --no-fatal-infos 2>&1 | grep -i "document" > doc_warnings.txt || true
          
          if [ -s doc_warnings.txt ]; then
            echo "⚠️ **Found undocumented APIs:**" >> doc_report.md
            echo "\`\`\`" >> doc_report.md
            cat doc_warnings.txt >> doc_report.md
            echo "\`\`\`" >> doc_report.md
          else
            echo "✅ **All public APIs are documented!**" >> doc_report.md
          fi
          
          echo "" >> doc_report.md
          echo "---" >> doc_report.md
          echo "*Tip: Add documentation comments to all public classes, methods, and functions.*" >> doc_report.md

      - name: Comment PR with documentation report
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('doc_report.md', 'utf8');
            
            const { data: comments } = await github.rest.issues.listComments({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
            });
            
            const botComment = comments.find(comment => 
              comment.user.type === 'Bot' && 
              comment.body.includes('📚 Documentation Coverage')
            );
            
            const commentBody = `${report}\n\n---\n*Updated: ${new Date().toUTCString()}*`;
            
            if (botComment) {
              await github.rest.issues.updateComment({
                comment_id: botComment.id,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: commentBody
              });
            } else {
              await github.rest.issues.createComment({
                issue_number: context.issue.number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: commentBody
              });
            }

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