fortress-completion-finalize.yml

# ------------------------------------------------------------------------------------
#  Completion Report Finalization (Reusable Workflow) (GoFortress)
#
#  Purpose: Finalize the completion report by generating job summaries, performance
#  insights, and assembling all report sections into the final published report.
#
#  This workflow handles:
#    - Job results summary with status indicators
#    - Performance insights and workflow analytics
#    - Report assembly from all sub-workflow sections
#    - Final publication to GitHub Step Summary
#
#  Maintainer: @mrz1836
#
# ------------------------------------------------------------------------------------

name: GoFortress (Completion Finalize)

on:
  workflow_call:
    inputs:
      all-inputs:
        description: "JSON string of all original workflow inputs"
        required: true
        type: string
      statistics-report:
        description: "Statistics section markdown content"
        required: true
        type: string
      tests-report:
        description: "Tests section markdown content"
        required: true
        type: string
      timing-data:
        description: "JSON string of timing metrics"
        required: true
        type: string
    outputs:
      final-report:
        description: "Complete assembled report"
        value: ${{ jobs.finalize-report.outputs.report-content }}

# Security: Restrict default permissions (jobs must explicitly request what they need)
permissions: {}

jobs:
  # ----------------------------------------------------------------------------------
  # Report Finalization
  # ----------------------------------------------------------------------------------
  finalize-report:
    name: ✅ Finalize Report
    runs-on: ubuntu-latest
    if: always()
    permissions:
      contents: read
      actions: read
    outputs:
      report-content: ${{ steps.set-output.outputs.content }}
    steps:
      # --------------------------------------------------------------------
      # Checkout repository for local actions
      # --------------------------------------------------------------------
      - name: 📥 Checkout Repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      # --------------------------------------------------------------------
      # Parse inputs and setup
      # --------------------------------------------------------------------
      - name: 🔧 Parse workflow inputs
        env:
          ALL_INPUTS: ${{ inputs.all-inputs }}
          TIMING_DATA: ${{ inputs.timing-data }}
        run: |
          echo "📋 Parsing workflow inputs..."
          # Note: Replace hyphens with underscores in keys for GitHub Actions expression compatibility
          # Use heredoc syntax to safely handle multiline values (e.g., env-json)
          echo "$ALL_INPUTS" | jq -r 'to_entries | .[] | @base64' | while read -r entry; do
            decoded=$(echo "$entry" | base64 -d)
            key=$(echo "$decoded" | jq -r '.key')
            value=$(echo "$decoded" | jq -r '.value')
            normalized_key=$(echo "$key" | tr '-' '_')
            {
              echo "INPUT_$normalized_key<<EOF_INPUT_$normalized_key"
              echo "$value"
              echo "EOF_INPUT_$normalized_key"
            } >> $GITHUB_ENV
          done

          echo "📋 Parsing timing data..."
          echo "$TIMING_DATA" | jq -r 'to_entries | .[] | @base64' | while read -r entry; do
            decoded=$(echo "$entry" | base64 -d)
            key=$(echo "$decoded" | jq -r '.key')
            value=$(echo "$decoded" | jq -r '.value')
            normalized_key=$(echo "$key" | tr '-' '_')
            {
              echo "TIMING_$normalized_key<<EOF_TIMING_$normalized_key"
              echo "$value"
              echo "EOF_TIMING_$normalized_key"
            } >> $GITHUB_ENV
          done

      # --------------------------------------------------------------------
      # Download report sections from sub-workflows
      # --------------------------------------------------------------------
      - name: 📥 Download statistics section
        if: always()
        uses: ./.github/actions/download-artifact-resilient
        with:
          pattern: "statistics-section"
          path: ./sections/
          merge-multiple: false
          max-retries: ${{ env.ARTIFACT_DOWNLOAD_RETRIES }}
          retry-delay: ${{ env.ARTIFACT_DOWNLOAD_RETRY_DELAY }}
          timeout: ${{ env.ARTIFACT_DOWNLOAD_TIMEOUT }}
          continue-on-error: ${{ env.ARTIFACT_DOWNLOAD_CONTINUE_ON_ERROR }}

      - name: 📥 Download tests section
        if: always()
        uses: ./.github/actions/download-artifact-resilient
        with:
          pattern: "tests-section"
          path: ./sections/
          merge-multiple: false
          max-retries: ${{ env.ARTIFACT_DOWNLOAD_RETRIES }}
          retry-delay: ${{ env.ARTIFACT_DOWNLOAD_RETRY_DELAY }}
          timeout: ${{ env.ARTIFACT_DOWNLOAD_TIMEOUT }}
          continue-on-error: ${{ env.ARTIFACT_DOWNLOAD_CONTINUE_ON_ERROR }}

      # --------------------------------------------------------------------
      # Initialize final report with STATUS BANNER FIRST
      # --------------------------------------------------------------------
      - name: 📝 Initialize Final Report
        run: |
          # Determine overall workflow status
          WORKFLOW_FAILED=false
          FAILED_JOBS=""

          # Check each critical job result
          if [[ "${{ env.INPUT_setup_result }}" != "success" && "${{ env.INPUT_setup_result }}" != "skipped" ]]; then
            WORKFLOW_FAILED=true
            FAILED_JOBS="$FAILED_JOBS- ❌ Setup Configuration\n"
          fi
          if [[ "${{ env.INPUT_test_magex_result }}" != "success" && "${{ env.INPUT_test_magex_result }}" != "skipped" ]]; then
            WORKFLOW_FAILED=true
            FAILED_JOBS="$FAILED_JOBS- ❌ Test MAGE-X\n"
          fi
          if [[ "${{ env.INPUT_pre_commit_result }}" != "success" && "${{ env.INPUT_pre_commit_result }}" != "skipped" ]]; then
            WORKFLOW_FAILED=true
            FAILED_JOBS="$FAILED_JOBS- ❌ Pre-commit Checks\n"
          fi
          if [[ "${{ env.INPUT_security_result }}" != "success" && "${{ env.INPUT_security_result }}" != "skipped" ]]; then
            WORKFLOW_FAILED=true
            FAILED_JOBS="$FAILED_JOBS- ❌ Security Scans\n"
          fi
          if [[ "${{ env.INPUT_code_quality_result }}" != "success" && "${{ env.INPUT_code_quality_result }}" != "skipped" ]]; then
            WORKFLOW_FAILED=true
            FAILED_JOBS="$FAILED_JOBS- ❌ Code Quality\n"
          fi
          if [[ "${{ env.INPUT_test_suite_result }}" != "success" && "${{ env.INPUT_test_suite_result }}" != "skipped" ]]; then
            WORKFLOW_FAILED=true
            FAILED_JOBS="$FAILED_JOBS- ❌ Test Suite\n"
          fi
          if [[ "${{ env.INPUT_benchmarks_result }}" != "success" && "${{ env.INPUT_benchmarks_result }}" != "skipped" ]]; then
            WORKFLOW_FAILED=true
            FAILED_JOBS="$FAILED_JOBS- ❌ Benchmarks\n"
          fi
          if [[ "${{ env.INPUT_release_result }}" != "success" && "${{ env.INPUT_release_result }}" != "skipped" ]]; then
            WORKFLOW_FAILED=true
            FAILED_JOBS="$FAILED_JOBS- ❌ Release\n"
          fi

          SUMMARY_TIME=$(date -u +"%Y-%m-%d %H:%M:%S UTC")

          {
            # =================================================================
            # STATUS BANNER (Always visible at top - immediate failure visibility)
            # =================================================================
            echo "# 🏁 Workflow Complete"
            echo ""

            if [[ "$WORKFLOW_FAILED" == "true" ]]; then
              echo "> [!CAUTION]"
              echo "> ## 🔴 WORKFLOW FAILED"
              echo ">"
              echo "> **Failed Jobs:**"
              echo -e "$FAILED_JOBS" | while IFS= read -r line; do echo "> $line"; done
              echo ""
            else
              echo "> [!TIP]"
              echo "> ## 🟢 ALL CHECKS PASSED"
            fi
            echo ""
            echo "| Job | Result |"
            echo "|-----|--------|"
            echo "| Setup Configuration | $([ "${{ env.INPUT_setup_result }}" = "success" ] && echo "✅ Passed" || ([ "${{ env.INPUT_setup_result }}" = "skipped" ] && echo "⏭️ Skipped" || echo "❌ Failed")) |"
            echo "| Test MAGE-X | $([ "${{ env.INPUT_test_magex_result }}" = "success" ] && echo "✅ Passed" || ([ "${{ env.INPUT_test_magex_result }}" = "skipped" ] && echo "⏭️ Skipped" || echo "❌ Failed")) |"
            echo "| Pre-commit Checks | $([ "${{ env.INPUT_pre_commit_result }}" = "success" ] && echo "✅ Passed" || ([ "${{ env.INPUT_pre_commit_result }}" = "skipped" ] && echo "⏭️ Skipped" || echo "❌ Failed")) |"
            echo "| Security Scans | $([ "${{ env.INPUT_security_result }}" = "success" ] && echo "✅ Passed" || ([ "${{ env.INPUT_security_result }}" = "skipped" ] && echo "⏭️ Skipped" || echo "❌ Failed")) |"
            echo "| Code Quality | $([ "${{ env.INPUT_code_quality_result }}" = "success" ] && echo "✅ Passed" || ([ "${{ env.INPUT_code_quality_result }}" = "skipped" ] && echo "⏭️ Skipped" || echo "❌ Failed")) |"
            echo "| Test Suite | $([ "${{ env.INPUT_test_suite_result }}" = "success" ] && echo "✅ Passed" || ([ "${{ env.INPUT_test_suite_result }}" = "skipped" ] && echo "⏭️ Skipped" || echo "❌ Failed")) |"
            # Only show benchmarks if attempted
            if [[ "${{ env.INPUT_benchmarks_result }}" != "skipped" ]]; then
              echo "| Benchmarks | $([ "${{ env.INPUT_benchmarks_result }}" = "success" ] && echo "✅ Passed" || echo "❌ Failed") |"
            fi
            # Only show release if attempted
            if [[ "${{ env.INPUT_release_result }}" != "skipped" ]]; then
              echo "| Release | $([ "${{ env.INPUT_release_result }}" = "success" ] && echo "✅ Passed" || echo "❌ Failed") |"
            fi
            echo ""
            echo "**Duration:** ${TIMING_total_minutes:-0}m ${TIMING_total_seconds:-0}s"
            echo ""
            echo "**Generated:** $SUMMARY_TIME"
            echo ""

            # =================================================================
            # DETAILED SECTIONS (Collapsed by default)
            # =================================================================
            echo "<details>"
            echo "<summary>📊 Statistics (Cache, Coverage, LOC)</summary>"
            echo ""
          } > final-report.md

      # --------------------------------------------------------------------
      # Append report sections from sub-workflows (inside collapsed details)
      # --------------------------------------------------------------------
      - name: 📄 Append Statistics Section
        if: always()
        run: |
          if [ -f "./sections/statistics-section.md" ]; then
            echo "📊 Adding statistics section..."
            cat "./sections/statistics-section.md" >> final-report.md
          else
            echo "⚠️ Statistics section not found, using input content..."
            cat << 'EOF' >> final-report.md
          ${{ inputs.statistics-report }}
          EOF
          fi
          # Close statistics details, open tests details
          {
            echo ""
            echo "</details>"
            echo ""
            echo "<details>"
            echo "<summary>🧪 Test Analysis</summary>"
            echo ""
          } >> final-report.md

      - name: 📄 Append Tests Section
        if: always()
        run: |
          if [ -f "./sections/tests-section.md" ]; then
            echo "🧪 Adding tests section..."
            cat "./sections/tests-section.md" >> final-report.md
          else
            echo "⚠️ Tests section not found, using input content..."
            cat << 'EOF' >> final-report.md
          ${{ inputs.tests-report }}
          EOF
          fi
          # Close tests details
          echo "" >> final-report.md
          echo "</details>" >> final-report.md
          echo "" >> final-report.md

      # --------------------------------------------------------------------
      # Generate Job Results Summary
      # --------------------------------------------------------------------
      - name: 🔧 Generate Job Results Summary
        id: job-results
        run: |
          # Add fork PR specific information if this is a fork PR (collapsed by default)
          if [[ "${{ env.INPUT_is_fork_pr }}" == "true" ]]; then
            {
              echo "<details>"
              echo "<summary>🔐 Fork PR Security Status</summary>"
              echo ""
              echo "⚠️ **This workflow ran on a FORK Pull Request**"
              echo ""
              echo "**Security Mode:** \`${{ env.INPUT_fork_security_mode }}\`"
              echo ""
              echo "**Jobs That Ran:** Setup, MAGE-X Testing, Code Quality, Pre-Commit$([ "${{ env.INPUT_benchmarks_result }}" != "skipped" ] && echo ", Benchmarks")"
              echo ""
              echo "**Jobs Skipped (Require Secrets):** Security Scans, Test Suite with Coverage, Release"
              echo ""
              echo "</details>"
              echo ""
            } >> final-report.md
          fi

          # Add release-specific information if this was a tag push
          if [[ "${{ github.ref }}" == refs/tags/v* ]]; then
            {
              echo "### 📦 Release Information"
            } >> final-report.md

            if [[ "${{ env.INPUT_release_result }}" == "success" ]]; then
              {
                echo "✅ Release ${{ github.ref_name }} created successfully!"
                echo "[View Release](https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }})"
              } >> final-report.md
            elif [[ "${{ env.INPUT_release_result }}" == "skipped" ]]; then
              echo "⏭️ Release was skipped (likely due to test failures)" >> final-report.md
            elif [[ "${{ env.INPUT_release_result }}" == "failure" ]]; then
              echo "❌ Release creation failed - check logs for details" >> final-report.md
            fi
            echo "" >> final-report.md
          fi

      # --------------------------------------------------------------------
      # Generate performance insights (collapsed)
      # --------------------------------------------------------------------
      - name: 🚀 Generate Performance Insights
        id: performance-insights
        run: |
          TOTAL_DURATION=${TIMING_total_duration:-0}
          TOTAL_MINUTES=${TIMING_total_minutes:-0}
          TOTAL_SECONDS=${TIMING_total_seconds:-0}

          {
            echo "<details>"
            echo "<summary>⏱️ Performance Insights</summary>"
            echo ""
          } >> final-report.md

          # Overall timing insights
          if [[ $TOTAL_DURATION -gt 600 ]]; then
            echo "- ⚠️ Workflow took longer than 10 minutes (${TOTAL_MINUTES}m ${TOTAL_SECONDS}s)" >> final-report.md
          elif [[ $TOTAL_DURATION -gt 300 && $TOTAL_DURATION -le 600 ]]; then
            echo "- ℹ️ Workflow completed in ${TOTAL_MINUTES}m ${TOTAL_SECONDS}s" >> final-report.md
          elif [[ $TOTAL_DURATION -gt 180 && $TOTAL_DURATION -le 300 ]]; then
            echo "- 🎉 Great: Under 5 minutes (${TOTAL_MINUTES}m ${TOTAL_SECONDS}s)" >> final-report.md
          elif [[ $TOTAL_DURATION -le 180 ]]; then
            echo "- 🚀 Excellent: Under 3 minutes!" >> final-report.md
          fi

          # Standard insights
          {
            echo "- **Parallel Jobs**: Multiple jobs ran in parallel"
            echo "- **Matrix Strategy**: $(echo '${{ env.INPUT_test_matrix }}' | jq '.include | length') configurations"
          } >> final-report.md

          echo "" >> final-report.md
          echo "</details>" >> final-report.md
          echo "" >> final-report.md

      # --------------------------------------------------------------------
      # Add compact footer
      # --------------------------------------------------------------------
      - name: ✅ Add Report Footer
        run: |
          {
            echo "---"
            echo "_🎯 Workflow completed at $(date -u +"%H:%M:%S UTC") — GoFortress CI/CD Pipeline_"
          } >> final-report.md

      # --------------------------------------------------------------------
      # Publish final report to GitHub Step Summary
      # --------------------------------------------------------------------
      - name: 📋 Publish to GitHub Step Summary
        run: |
          # Write the final report to GitHub Step Summary
          cat final-report.md >> $GITHUB_STEP_SUMMARY
          echo "✅ Completion report generated and published successfully"

      # --------------------------------------------------------------------
      # Upload final report artifact
      # --------------------------------------------------------------------
      - name: 📤 Upload Final Report
        id: upload-final
        uses: ./.github/actions/upload-statistics
        with:
          artifact-name: "final-completion-report"
          artifact-path: "final-report.md"
          retention-days: "7"

      - name: 📋 Set Output Content
        id: set-output
        run: |
          echo "content<<EOF" >> $GITHUB_OUTPUT
          cat final-report.md >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT