lychee.yml

name: 🍈 Lychee

on:
  pull_request:
    paths:
      - "apps/docs/content/**"
      - ".github/workflows/lychee.yml"

concurrency:
  group: lychee-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  check:
    name: Check Links
    runs-on: ubuntu-latest
    permissions: write-all
    steps:
      - uses: actions/checkout@v4

      - name: 📄 Get changed docs files
        id: changed-docs
        uses: tj-actions/changed-files@v46
        with:
          files: |
            apps/docs/content/**/*.md
            apps/docs/content/**/*.mdx

      - name: Skip when no docs files changed
        if: ${{ steps.changed-docs.outputs.any_changed != 'true' }}
        run: echo "No docs markdown changes in this PR. Skipping lychee."

      - name: 🍈 Lychee Link Checker (First Run)
        id: lychee
        if: ${{ steps.changed-docs.outputs.any_changed == 'true' }}
        uses: lycheeverse/lychee-action@v2
        with:
          args: >-
            --cache
            --cache-exclude-status 429,500,502,503,504
            --max-cache-age 5m
            --verbose
            --no-progress
            --base-url 'https://local.invalid/'
            --timeout 20
            --max-concurrency 8
            --max-retries 8
            --retry-wait-time 5
            --scheme http
            --scheme https
            --exclude '^https?://local\.invalid/'
            --exclude '^https?://localhost'
            --exclude 'https://www.gnu.org'
            --exclude 'https://docs.solidjs.com'
            --accept 200,201,204,301,302,303,307,308,403,429
            ${{ steps.changed-docs.outputs.all_changed_files }}
          output: lychee/out.md
          fail: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: 🔄 Retry Lychee Link Checker (Second Run for Timeouts)
        id: lychee-retry
        if: ${{ always() && steps.changed-docs.outputs.any_changed == 'true' && steps.lychee.outputs.exit_code != 0 }}
        uses: lycheeverse/lychee-action@v2
        with:
          args: >-
            --cache
            --cache-exclude-status 429,500,502,503,504
            --max-cache-age 5m
            --verbose
            --no-progress
            --base-url 'https://local.invalid/'
            --timeout 30
            --max-concurrency 8
            --max-retries 10
            --retry-wait-time 10
            --scheme http
            --scheme https
            --exclude '^https?://local\.invalid/'
            --exclude '^https?://localhost'
            --exclude 'https://www.gnu.org'
            --exclude 'https://docs.solidjs.com'
            --accept 200,201,204,301,302,303,307,308,403,429
            ${{ steps.changed-docs.outputs.all_changed_files }}
          output: lychee/out-retry.md
          fail: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: 📝 Clean up Lychee Report
        if: ${{ always() && github.event.pull_request.head.repo.fork == false && steps.changed-docs.outputs.any_changed == 'true' }}
        run: |
          mkdir -p lychee

          # Use retry results if available, otherwise use first run results
          if [ -f "lychee/out-retry.md" ]; then
            REPORT_FILE="lychee/out-retry.md"
          elif [ -f "lychee/out.md" ]; then
            REPORT_FILE="lychee/out.md"
          fi

          if [ -n "$REPORT_FILE" ]; then
            # Parse stats from lychee markdown table
            TOTAL=$(grep 'Total' "$REPORT_FILE" | grep -oE '\| [0-9]+ +\|' | grep -oE '[0-9]+' || echo "0")
            SUCCESS=$(grep 'Successful' "$REPORT_FILE" | grep -oE '\| [0-9]+ +\|' | grep -oE '[0-9]+' || echo "0")
            ERRORS=$(grep 'Errors' "$REPORT_FILE" | grep -oE '\| [0-9]+ +\|' | grep -oE '[0-9]+' || echo "0")
            REDIRECTS=$(grep 'Redirected' "$REPORT_FILE" | grep -oE '\| [0-9]+ +\|' | grep -oE '[0-9]+' || echo "0")
            EXCLUDED=$(grep 'Excluded' "$REPORT_FILE" | grep -oE '\| [0-9]+ +\|' | grep -oE '[0-9]+' || echo "0")
            TIMEOUTS=$(grep 'Timeouts' "$REPORT_FILE" | grep -oE '\| [0-9]+ +\|' | grep -oE '[0-9]+' || echo "0")
            UNKNOWN=$(grep 'Unknown' "$REPORT_FILE" | grep -oE '\| [0-9]+ +\|' | grep -oE '[0-9]+' || echo "0")
            UNSUPPORTED=$(grep 'Unsupported' "$REPORT_FILE" | grep -oE '\| [0-9]+ +\|' | grep -oE '[0-9]+' || echo "0")

            # Extract errors section
            ERRORS_SECTION=$(sed -n '/^## Errors/,/^## /p' "$REPORT_FILE" | sed '$d' | tail -n +2)

            # Format errors section
            FORMATTED_ERRORS=""
            while IFS= read -r line; do
              if [[ $line =~ ^### ]]; then
                file=$(echo "$line" | sed 's/### Errors in //')
                FORMATTED_ERRORS+="\n**\`$file\`**\n"
              elif [[ $line =~ ^\* ]]; then
                FORMATTED_ERRORS+="$line\n"
              fi
            done <<< "$ERRORS_SECTION"

            # Create formatted output using echo statements
            echo "## 🍈 Lychee Link Check Report" > lychee/formatted.md
            echo "" >> lychee/formatted.md
            echo "**$TOTAL links:** \`✅ $SUCCESS OK\` | \`🚫 $ERRORS errors\` | \`🔀 $REDIRECTS redirects\` | \`👻 $EXCLUDED excluded\`" >> lychee/formatted.md
            echo "" >> lychee/formatted.md

            if [ "$ERRORS" -eq 0 ]; then
              echo "### ✅ All links are working!" >> lychee/formatted.md
            else
              echo "### ❌ Errors" >> lychee/formatted.md
              # Keep PR comment concise so we never exceed GitHub's 65,536-char limit
              echo -e "$FORMATTED_ERRORS" | awk 'NR<=200' >> lychee/formatted.md
              TOTAL_ERROR_LINES=$(echo -e "$FORMATTED_ERRORS" | wc -l | tr -d ' ')
              if [ "$TOTAL_ERROR_LINES" -gt 200 ]; then
                echo "" >> lychee/formatted.md
                echo "_Showing first 200 lines of errors. See workflow artifact for full report._" >> lychee/formatted.md
              fi
            fi
            echo "---" >> lychee/formatted.md
            echo "" >> lychee/formatted.md
            echo "<details>" >> lychee/formatted.md
            echo "<summary>Full Statistics Table</summary>" >> lychee/formatted.md
            echo "" >> lychee/formatted.md
            echo "| Status | Count |" >> lychee/formatted.md
            echo "|--------|-------|" >> lychee/formatted.md
            echo "| ✅ Successful | $SUCCESS |" >> lychee/formatted.md
            echo "| 🔀 Redirected | $REDIRECTS |" >> lychee/formatted.md
            echo "| 👻 Excluded | $EXCLUDED |" >> lychee/formatted.md
            echo "| 🚫 Errors | $ERRORS |" >> lychee/formatted.md
            echo "| ⛔ Unsupported | $UNSUPPORTED |" >> lychee/formatted.md
            echo "| ⏳ Timeouts | $TIMEOUTS |" >> lychee/formatted.md
            echo "| ❓ Unknown | $UNKNOWN |" >> lychee/formatted.md
            echo "" >> lychee/formatted.md
            echo "</details>" >> lychee/formatted.md

            # Hard truncate as a final guardrail for sticky PR comments
            python3 -c "from pathlib import Path; p = Path('lychee/formatted.md'); max_chars = 60000; note = '\n\n_Comment truncated to avoid GitHub body limit. Download the artifact for full details._\n'; text = p.read_text(encoding='utf-8') if p.exists() else ''; p.write_text(text[: max_chars - len(note)] + note, encoding='utf-8') if p.exists() and len(text) > max_chars else None"
          else
            # Ensure sticky PR comment always has content even if Lychee output is missing
            printf '%s\n' '## 🍈 Lychee Link Check Report' '' 'Lychee did not produce a markdown report file for this run.' 'Check the workflow logs and uploaded artifact for details.' > lychee/formatted.md
          fi

      - name: 📦 Upload Lychee reports
        if: ${{ always() && steps.changed-docs.outputs.any_changed == 'true' }}
        uses: actions/upload-artifact@v4
        with:
          name: lychee-report-${{ github.run_id }}
          path: lychee/
          if-no-files-found: ignore

      - name: 📝 Comment Broken Links
        if: ${{ always() && github.event.pull_request.head.repo.fork == false && steps.changed-docs.outputs.any_changed == 'true' }}
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: lychee
          path: lychee/formatted.md

      - name: 🚫 Fail if broken links found
        if: ${{ steps.changed-docs.outputs.any_changed == 'true' && (steps.lychee-retry.conclusion == 'success' && steps.lychee-retry.outputs.exit_code != 0 || steps.lychee-retry.conclusion == 'failure') }}
        run: |
          if [ "${{ steps.lychee-retry.conclusion }}" == "success" ]; then
            echo "Failing based on retry run results"
            exit ${{ steps.lychee-retry.outputs.exit_code }}
          else
            echo "Failing based on first run results"
            exit ${{ steps.lychee.outputs.exit_code }}
          fi