name: Docs Testing

on:
  pull_request:
    paths:
      - "docs/**"
      - "superset/db_engine_specs/**"
      - ".github/workflows/superset-docs-verify.yml"
    types: [synchronize, opened, reopened, ready_for_review]
  # zizmor: ignore[dangerous-triggers] - runs in base-branch context and only consumes artifacts from the trusted upstream workflow
  workflow_run:
    workflows: ["Python-Integration"]
    types: [completed]

# cancel previous workflow jobs for PRs
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.workflow_run.head_sha || github.run_id }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  lychee:
    # See docs here: https://github.com/lycheeverse/lychee-action
    # Only run on pull_request, not workflow_run
    if: github.event_name == 'pull_request'
    name: Link Checking
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      # Restores the on-disk request cache (.lycheecache) lychee writes when
      # `--cache` is set, so re-runs don't re-check every external link from
      # scratch. Key never matches exactly (github.run_id is unique per run),
      # so actions/cache always saves a fresh copy afterwards; restore-keys
      # falls back to the most recent prior cache on lookup.
      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: .lycheecache
          key: lychee-cache-${{ github.run_id }}
          restore-keys: lychee-cache-
      # v2.8.0 and v2.9.0 are both on ASF Infra's action allowlist
      # (apache/infrastructure-actions approved_patterns.yml) as of this
      # writing. Do not bump past v2.9.0 without opening an Infra ticket
      # to allow the new SHA first!
      - uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0
        continue-on-error: true # This will make the job advisory (non-blocking, no red X)
        with:
          fail: false
          args: >-
            --verbose --no-progress
            --cache --max-cache-age 7d
            --exclude '^https://github.com/apache/(superset|incubator-superset)/(pull|issues)/\d+'
            --exclude '^https://github.com/apache/(superset|incubator-superset)/commit/[a-f0-9]+'
            --exclude 'superset-frontend/.*CHANGELOG\.md'
            --exclude 'http://localhost:8088/'
            --exclude 'http://127.0.0.1:3000/'
            --exclude 'http://localhost:9001/'
            --exclude 'https://charts.bitnami.com/bitnami'
            --exclude 'https://www.li.me/'
            --exclude 'https://www.fanatics.com/'
            --exclude 'https://tails.com/gb/'
            --exclude 'https://www.techaudit.info/'
            --exclude 'https://avetilearning.com/'
            --exclude 'https://www.udemy.com/'
            --exclude 'https://trustmedis.com/'
            --exclude 'http://theiconic.com.au/'
            --exclude 'https://dev.mysql.com/doc/refman/5.7/en/innodb-limits.html'
            --exclude '^https://img\.shields\.io/.*'
            --exclude 'https://vkusvill.ru/'
            --exclude 'https://www.linkedin.com/in/mark-thomas-b16751158/'
            --exclude 'https://theiconic.com.au/'
            --exclude 'https://wattbewerb.de/'
            --exclude 'https://timbr.ai/'
            --exclude 'https://opensource.org/license/apache-2-0'
            --exclude 'https://www.plaidcloud.com/'
            './**/*.md' './**/*.mdx'

  build-on-pr:
    # Build docs when PR changes docs/** (uses committed databases.json)
    if: github.event_name == 'pull_request'
    name: Build (PR trigger)
    runs-on: ubuntu-26.04
    defaults:
      run:
        working-directory: docs
    steps:
      - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
          submodules: recursive
      - name: Set up Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version-file: "./docs/.nvmrc"
      - name: yarn install
        run: |
          yarn install --check-cache
      - name: Lint docs links
        # Fast source-level check for bare relative internal links
        # like `[Foo](../foo)` that Docusaurus's onBrokenLinks
        # setting can't catch. Runs in seconds; fails fast before
        # the expensive build step.
        run: |
          yarn lint:docs-links
      - name: yarn typecheck
        run: |
          yarn typecheck
      - name: yarn build
        run: |
          yarn build

  build-after-tests:
    # Build docs after integration tests complete (uses fresh diagnostics)
    # Only runs if integration tests succeeded
    if: >
      github.event_name == 'workflow_run' &&
      github.event.workflow_run.conclusion == 'success' &&
      github.event.workflow_run.head_repository.full_name == github.repository
    name: Build (after integration tests)
    runs-on: ubuntu-26.04
    defaults:
      run:
        working-directory: docs
    steps:
      - name: "Checkout PR head: ${{ github.event.workflow_run.head_sha }}"
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          persist-credentials: false
          submodules: recursive
      - name: Set up Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version-file: "./docs/.nvmrc"
      - name: yarn install
        run: |
          yarn install --check-cache
      - name: Download database diagnostics from integration tests
        uses: dawidd6/action-download-artifact@b6e2e70617bc3265edd6dab6c906732b2f1ae151 # v21
        with:
          workflow: superset-python-integrationtest.yml
          run_id: ${{ github.event.workflow_run.id }}
          name: database-diagnostics
          path: docs/src/data/
          if_no_artifact_found: "warning"
      - name: Use fresh diagnostics
        run: |
          if [ -f "src/data/databases-diagnostics.json" ]; then
            echo "Using fresh diagnostics from integration tests"
            mv src/data/databases-diagnostics.json src/data/databases.json
          else
            echo "Warning: No diagnostics artifact found, using committed data"
          fi
      - name: yarn typecheck
        run: |
          yarn typecheck
      - name: yarn build
        run: |
          yarn build