preview-docs.yml

name: preview-docs

on: pull_request

jobs:
  preview:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

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

      - name: Install dependencies
        run: yarn install

      - name: Build and generate preview
        id: generate-docs
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
        run: |
          yarn build 2>&1 | tee /tmp/build.log
          if [ ${PIPESTATUS[0]} -ne 0 ]; then
            exit 1
          fi

          URL=$(grep -oP 'Published docs to \Khttps://[^\s]+' /tmp/build.log | head -1)
          if [ -z "$URL" ]; then
            echo "::error::Could not extract preview URL from build output"
            exit 1
          fi
          echo "preview_url=$URL" >> $GITHUB_OUTPUT

      - name: Post initial PR comment
        uses: actions/github-script@v7
        env:
          PREVIEW_URL: ${{ steps.generate-docs.outputs.preview_url }}
        with:
          script: |
            const previewUrl = process.env.PREVIEW_URL;
            const MARKER = '<!-- preview-docs-bot -->';

            let body = MARKER + '\n';
            body += `## 🌿 Preview\n\n`;
            body += `${previewUrl}\n\n`;
            body += `⏳ Link check in progress...`;
            body += `\n\n---\n[View workflow run](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId})`;

            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
            });

            const existing = comments.find(c => c.body.includes(MARKER));
            if (existing) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: existing.id,
                body
              });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body
              });
            }

      - name: Wait for sitemap availability
        run: |
          SITEMAP_URL="${{ steps.generate-docs.outputs.preview_url }}/sitemap.xml"
          echo "Waiting for sitemap to be available: $SITEMAP_URL"

          for i in {1..6}; do
            if curl -sf "$SITEMAP_URL" > /dev/null 2>&1; then
              echo "Sitemap is available"
              exit 0
            fi
            echo "Attempt $i: Sitemap not ready, waiting 5 seconds..."
            sleep 5
          done

          echo "::warning::Sitemap may not be fully available yet, proceeding anyway"

      - name: Cache lychee
        uses: actions/cache@v4
        with:
          path: ~/.cargo/bin/lychee
          key: lychee-${{ runner.os }}

      - name: Install lychee
        uses: taiki-e/install-action@v2
        with:
          tool: lychee

      - name: Check links
        id: check-links
        run: |
          set +e
          yarn check-links \
            --sitemap "${{ steps.generate-docs.outputs.preview_url }}/sitemap.xml" \
            --no-progress \
            --output /tmp/link-report.md
          echo "exit_code=$?" >> $GITHUB_OUTPUT

      - name: Comment PR status
        uses: actions/github-script@v7
        env:
          EXIT_CODE: ${{ steps.check-links.outputs.exit_code }}
          PREVIEW_URL: ${{ steps.generate-docs.outputs.preview_url }}
        with:
          script: |
            const fs = require('fs');
            const failed = process.env.EXIT_CODE !== '0';
            const previewUrl = process.env.PREVIEW_URL;

            // GitHub comment limit is 65536 characters
            const MAX_COMMENT_LENGTH = 65000; // Leave some buffer

            // Read the report file
            let report = '';
            try {
              report = fs.readFileSync('/tmp/link-report.md', 'utf8');
            } catch (e) {
              // File may not exist if script failed early
            }

            const MARKER = '<!-- preview-docs-bot -->';
            const workflowLink = `\n\n---\n[View workflow run](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId})`;
            const artifactNote = `\n\n> **Note:** The full report is available as an artifact in the [workflow run](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}).`;

            let body = MARKER + '\n';

            if (failed) {
              body += `## ❌ Link Check Failed\n\n`;
              body += `**Preview:** ${previewUrl}\n\n`;
              if (report) {
                // Extract just the broken links section from the report
                const brokenSection = report.match(/## ❌ [\s\S]*?(?=##|$)/);
                let reportContent = brokenSection ? brokenSection[0] : report;

                // Check if we need to truncate
                const reservedLength = body.length + workflowLink.length + artifactNote.length + 200; // buffer for truncation message
                const maxReportLength = MAX_COMMENT_LENGTH - reservedLength;

                if (reportContent.length > maxReportLength) {
                  // Count total broken links from the header (e.g., "## ❌ 2158 Broken Link(s)")
                  const countMatch = reportContent.match(/## ❌ (\d+) Broken Link/);
                  const totalCount = countMatch ? countMatch[1] : 'many';

                  // Truncate at a table row boundary to keep formatting clean
                  let truncated = reportContent.substring(0, maxReportLength);
                  const lastPipeNewline = truncated.lastIndexOf('|\n');
                  if (lastPipeNewline > 0) {
                    truncated = truncated.substring(0, lastPipeNewline + 2);
                  }

                  // Count how many links are shown
                  const shownLinks = (truncated.match(/\| 404 \|/g) || []).length;

                  reportContent = truncated;
                  reportContent += `\n\n**⚠️ Report truncated** - Showing ${shownLinks} of ${totalCount} broken links. Download the full report from the workflow artifacts.`;
                  body += reportContent + artifactNote;
                } else {
                  body += reportContent;
                }
              } else {
                body += `Broken links were found in the preview. Check the workflow logs for details.\n`;
              }
            } else {
              body += `## 🌿 Preview\n\n`;
              body += `${previewUrl}\n\n`;
              body += `✅ All links are valid.`;
            }
            body += workflowLink;

            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
            });

            const existing = comments.find(c => c.body.includes(MARKER));
            if (existing) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: existing.id,
                body
              });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body
              });
            }

      - name: Upload link report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: link-report
          path: /tmp/link-report.md
          if-no-files-found: ignore

      - name: Exit with link check result
        if: steps.check-links.outputs.exit_code != '0'
        run: exit 1