name: Docs External Link Audit

on:
  schedule:
    - cron: "47 7 * * 1"
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: docs-external-link-audit
  cancel-in-progress: false

jobs:
  audit:
    runs-on: ubuntu-24.04
    timeout-minutes: 45
    steps:
      - name: Checkout
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false

      - name: Setup Node.js and pnpm
        uses: ./.github/actions/setup-node-env
        with:
          install-bun: "false"
          install-deps: "false"

      - name: Install link audit dependencies
        run: pnpm install --filter . --frozen-lockfile --ignore-scripts

      - name: Prepare MDX link audit input
        run: >-
          node scripts/docs-link-audit.mjs
          --prepare-external-links
          .artifacts/docs-external-links/mdx

      - name: Audit external links
        uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0
        with:
          args: >-
            --no-progress
            --base-url https://docs.openclaw.ai
            --exclude-all-private
            --accept '100..=399,401,403,429,500..=599'
            --accept-timeouts
            --max-retries 2
            --retry-wait-time 2
            --timeout 20
            --scheme http
            --scheme https
            --exclude '^https://docs\.openclaw\.ai/'
            --exclude '^https://github\.com/openclaw/maintainers/'
            --exclude '^https://(claude\.ai|help\.openai\.com|openai\.com|platform\.openai\.com|support\.discord\.com|www\.npmjs\.com|www\.raspberrypi\.com)/'
            './README.md'
            './CONTRIBUTING.md'
            './SECURITY.md'
            './docs/**/*.md'
            './docs/**/*.mdx'
            './docs/docs.json'
            './.artifacts/docs-external-links/mdx/**/*.md'
            './.artifacts/docs-external-links/mdx/**/*.mdx'
          fail: false
          failIfEmpty: true
          format: markdown
          output: .artifacts/docs-external-links/report.md

      # The main pass follows redirects. This pass stops at the first response
      # so permanent moves remain visible without flagging temporary redirects.
      - name: Report permanent redirects
        if: always()
        continue-on-error: true
        run: >-
          lychee
          --no-progress
          --base-url https://docs.openclaw.ai
          --exclude-all-private
          --accept '100..=300,302..=307,309..=599'
          --accept-timeouts
          --max-retries 2
          --retry-wait-time 2
          --timeout 20
          --max-redirects 0
          --scheme http
          --scheme https
          --exclude '^https://docs\.openclaw\.ai/'
          --exclude '^https://github\.com/openclaw/maintainers/'
          --exclude '^https://(claude\.ai|help\.openai\.com|openai\.com|platform\.openai\.com|support\.discord\.com|www\.npmjs\.com|www\.raspberrypi\.com)/'
          --format markdown
          --output .artifacts/docs-external-links/permanent-redirects.md
          './README.md'
          './CONTRIBUTING.md'
          './SECURITY.md'
          './docs/**/*.md'
          './docs/**/*.mdx'
          './docs/docs.json'
          './.artifacts/docs-external-links/mdx/**/*.md'
          './.artifacts/docs-external-links/mdx/**/*.mdx'

      - name: Upload audit report
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: docs-external-link-audit
          path: .artifacts/docs-external-links
          include-hidden-files: true
          if-no-files-found: warn
          retention-days: 14