markdown-validation.yml

name: Markdown Content Validation

on:
  pull_request:
    branches: [ main, master ]
    paths:
      - 'categories/**/*.md'
      - 'pages/**/*.md'
      - 'scripts/**'
      - '.github/workflows/markdown-validation.yml'

jobs:
  validate-markdown:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'

    - name: Check metadata completeness
      id: check-metadata
      run: |
        echo "🔍 Checking metadata completeness..."
        
        # Run metadata check and capture output
        if node scripts/check-metadata.js > metadata-report.txt 2>&1; then
          echo "metadata_status=success" >> $GITHUB_OUTPUT
          echo "✅ Metadata validation succeeded"
        else
          echo "metadata_status=failed" >> $GITHUB_OUTPUT
          echo "❌ Metadata validation failed"
        fi
        
        # Extract summary statistics
        editlink_coverage=$(grep "editlink:" metadata-report.txt | grep -o '[0-9.]*% coverage' | head -1 || echo "0% coverage")
        title_coverage=$(grep "title:" metadata-report.txt | grep -o '[0-9.]*% coverage' | head -1 || echo "0% coverage")
        
        echo "editlink_coverage=$editlink_coverage" >> $GITHUB_OUTPUT
        echo "title_coverage=$title_coverage" >> $GITHUB_OUTPUT
        
        echo "Metadata check completed"

    - name: Validate tags
      id: validate-tags
      run: |
        echo "🏷️ Validating tags against approved list..."
        
        # Run tag validation and capture exit code
        if node scripts/validate-tags.js > tag-validation-report.txt 2>&1; then
          echo "validation_status=success" >> $GITHUB_OUTPUT
          echo "✅ All tags are valid"
        else
          echo "validation_status=failed" >> $GITHUB_OUTPUT
          echo "❌ Tag validation failed"
          
          # Extract invalid tags for summary
          invalid_tags=$(grep -A 1000 "INVALID TAGS SUMMARY" tag-validation-report.txt | grep "❌" | head -5 | sed 's/❌ //' || echo "See detailed report for invalid tags")
          
          # Save invalid tags to output (escape for GitHub Actions)
          {
            echo 'invalid_tags<<EOF'
            echo "$invalid_tags"
            echo 'EOF'
          } >> $GITHUB_OUTPUT
        fi

    - name: Generate detailed reports
      run: |
        echo "📋 Generating detailed reports..."
        
        # Create a comprehensive report
        cat > validation-summary.md << 'EOF'
        # 📊 Markdown Content Validation Report
        
        ## Metadata Completeness
        
        **Status**: ${{ steps.check-metadata.outputs.metadata_status == 'success' && '✅ Metadata validation succeeded' || '❌ Metadata validation failed' }}
        
        ## Tag Validation
        
        **Status**: ${{ steps.validate-tags.outputs.validation_status == 'success' && '✅ All tags valid' || '❌ Invalid tags found' }}
        
        ## Detailed Reports
        
        <details>
        <summary>📋 Metadata Analysis Report</summary>
        
        ```
        EOF
        
        cat metadata-report.txt >> validation-summary.md
        
        cat >> validation-summary.md << 'EOF'
        ```
        
        </details>
        
        <details>
        <summary>🏷️ Tag Validation Report</summary>
        
        ```
        EOF
        
        cat tag-validation-report.txt >> validation-summary.md
        
        cat >> validation-summary.md << 'EOF'
        ```
        
        </details>
        
        ---
        
        *This report was automatically generated by the Markdown Content Validation workflow.*
        EOF

    - name: Upload validation reports
      uses: actions/upload-artifact@v4
      with:
        name: markdown-validation-reports
        path: |
          validation-summary.md
          metadata-report.txt
          tag-validation-report.txt

    - name: Comment on PR
      uses: actions/github-script@v7
      with:
        script: |
          const fs = require('fs');
          
          // Read the validation summary
          const summary = fs.readFileSync('validation-summary.md', 'utf8');
          
          // Determine overall status
          const metadataStatus = '${{ steps.check-metadata.outputs.metadata_status }}';
          const tagStatus = '${{ steps.validate-tags.outputs.validation_status }}';
          
          let overallStatus = '✅ PASSED';
          let statusEmoji = '✅';
          
          if (tagStatus === 'failed') {
            overallStatus = '❌ FAILED';
            statusEmoji = '❌';
          } else if (metadataStatus === 'failed') {
            overallStatus = '⚠️ WARNINGS';
            statusEmoji = '⚠️';
          }
          
          let comment = `
          ${summary}

          ## Result
          
          ${tagStatus === 'failed' ? '- ❌ **Fix invalid tags** before merging' : '- ✅ All tags are valid'}
          `;
          
          // Add specific invalid tags if validation failed
          if (tagStatus === 'failed') {
            const invalidTags = `${{ steps.validate-tags.outputs.invalid_tags }}`;
            if (invalidTags && invalidTags.trim() !== '' && !invalidTags.includes('See detailed report')) {
              comment += `

          ## ❌ Invalid Tags Found

          The following tags are not in the approved list:
          ${invalidTags}

          **Fix Required**: Please remove these invalid tags or add them to the approved tags list before merging.
              `;
            }
          }
          
          // Find existing comment
          const { data: comments } = await github.rest.issues.listComments({
            owner: context.repo.owner,
            repo: context.repo.repo,
            issue_number: context.issue.number,
          });
          
          const existingComment = comments.find(comment => 
            comment.user.type === 'Bot' && 
            comment.body.includes('Markdown Content Validation')
          );
          
          if (existingComment) {
            // Update existing comment
            await github.rest.issues.updateComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              comment_id: existingComment.id,
              body: comment
            });
          } else {
            // Create new comment
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: comment
            });
          }

    - name: Check validation results
      run: |
        echo "🔍 Final validation check..."
        
        if [ "${{ steps.validate-tags.outputs.validation_status }}" = "failed" ]; then
          echo "❌ Tag validation failed - blocking merge"
          echo "Please fix invalid tags before merging this PR"
          exit 1
        fi
        
        echo "✅ All critical validations passed"
        echo "Note: Metadata warnings don't block the merge but should be addressed"

    - name: Generate status summary
      run: |
        echo "## 📊 Validation Summary" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "| Check | Status | Coverage |" >> $GITHUB_STEP_SUMMARY
        echo "|-------|---------|----------|" >> $GITHUB_STEP_SUMMARY
        echo "| Tag Validation | ${{ steps.validate-tags.outputs.validation_status == 'success' && '✅ Passed' || '❌ Failed' }} | - |" >> $GITHUB_STEP_SUMMARY
        echo "| editlink Field | ⚠️ Warnings | ${{ steps.check-metadata.outputs.editlink_coverage }} |" >> $GITHUB_STEP_SUMMARY
        echo "| title Field | ⚠️ Warnings | ${{ steps.check-metadata.outputs.title_coverage }} |" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        echo "### 🎯 Action Items" >> $GITHUB_STEP_SUMMARY
        echo "" >> $GITHUB_STEP_SUMMARY
        if [ "${{ steps.validate-tags.outputs.validation_status }}" = "failed" ]; then
          echo "- ❌ **CRITICAL**: Fix invalid tags (blocks merge)" >> $GITHUB_STEP_SUMMARY
        fi
        echo "- 📈 Consider adding missing metadata fields" >> $GITHUB_STEP_SUMMARY
        echo "- 📥 Download detailed reports from workflow artifacts" >> $GITHUB_STEP_SUMMARY