snippets.yml

name: Snippet checks

on:
  pull_request:
  push:
    branches:
      - develop
      - main

jobs:
  extract-sdk-version:
    name: Extract SDK version
    runs-on: ubuntu-latest
    outputs:
      sdk-version: ${{ steps.version.outputs.version }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

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

      - name: Extract SDK version from package.json
        id: version
        run: |
          VERSION=$(node -p "require('./package.json').dependencies['@wraith-protocol/sdk']")
          echo "version=$VERSION" >> $GITHUB_OUTPUT
          echo "Detected SDK version: $VERSION"

  check-snippets:
    name: Compile docs snippets
    runs-on: ubuntu-latest
    needs: extract-sdk-version
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: Download published SDK artifact
        run: |
          echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}"
          cd /tmp
          npm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}

      - name: Install dependencies with pinned SDK
        run: |
          pnpm install --frozen-lockfile
          pnpm remove @wraith-protocol/sdk
          pnpm add /tmp/wraith-protocol-sdk-${{ needs.extract-sdk-version.outputs.sdk-version }}.tgz

      - name: Record tested SDK version
        run: |
          echo "Testing against SDK version: ${{ needs.extract-sdk-version.outputs.sdk-version }}"

      - name: Check snippets
        run: pnpm run check:snippets

      - name: Check integration guides
        run: pnpm run check:integration-guides

      - name: Check placeholders
        run: pnpm run check:placeholders

      - name: Check nav coverage
        run: pnpm run check:nav-coverage

      - name: Check contract registry
        run: pnpm run check:contract-registry

      - name: Check compatibility matrix
        run: pnpm run check:compatibility-matrix

      - name: Check redirects and anchors
        env:
          DOCS_DIFF_BASE: ${{ github.event.pull_request.base.sha || github.event.before }}
          DOCS_DIFF_HEAD: ${{ github.event.pull_request.head.sha || github.sha }}
        run: pnpm run check:redirects-and-anchors

      - name: Test redirects and anchors check
        run: pnpm run test:redirects-and-anchors

      - name: Test compatibility matrix (regression fixtures)
        run: pnpm run test:compatibility-matrix

  check-snippets-extended:
    name: Compile Rust / Python / shell / config snippets
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # -----------------------------------------------------------------------
      # Rust — pinned stable toolchain for reproducibility.
      # -----------------------------------------------------------------------
      - name: Setup Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: "1.78.0"

      # -----------------------------------------------------------------------
      # Python — pinned minor version; patch resolved by setup-python.
      # -----------------------------------------------------------------------
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # bash is already present on ubuntu-latest; print versions for the log.
      - name: Verify toolchains
        run: |
          rustc --version
          python3 --version
          bash --version | head -1

      - name: Check extended snippets (Rust / Python / shell / JSON / TOML / YAML)
        run: pnpm run check:snippets-extended

  # ---------------------------------------------------------------------------
  # Stellar testnet snippet validation — split into two steps so that
  # deterministic content regressions block merges while provider outages
  # are surfaced as annotations without blocking.
  #
  # Exit codes from check-stellar-testnet-snippets.ts:
  #   0  – passed
  #   1  – content regression   → always a hard failure
  #   2  – provider outage      → warning annotation, does NOT block merge
  # ---------------------------------------------------------------------------
  stellar-testnet-snippets:
    name: Stellar snippet testnet validation
    runs-on: ubuntu-latest
    # No top-level continue-on-error — individual steps control leniency.
    needs: extract-sdk-version
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: Download published SDK artifact
        run: |
          echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}"
          cd /tmp
          npm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}

      - name: Install dependencies with pinned SDK
        run: |
          pnpm install --frozen-lockfile
          pnpm remove @wraith-protocol/sdk
          pnpm add /tmp/wraith-protocol-sdk-${{ needs.extract-sdk-version.outputs.sdk-version }}.tgz

      - name: Record tested SDK version
        run: |
          echo "Testing against SDK version: ${{ needs.extract-sdk-version.outputs.sdk-version }}"

      # BLOCKING: deterministic content checks only (snippet count, file
      # existence). A failure here means a real doc regression. Exit 1.
      - name: Validate Stellar snippet content (blocking)
        env:
          MODE: content
        run: pnpm run check:stellar-testnet

      # NON-BLOCKING: live provider availability checks.
      #
      # continue-on-error keeps the job alive regardless of exit status, but it
      # collapses outcome/conclusion so we cannot distinguish exit 1 from exit 2
      # through those fields alone.  We therefore capture the raw exit status
      # explicitly and write it to GITHUB_OUTPUT before the shell exits, giving
      # the next step a reliable signal to branch on.
      #
      # Exit codes (defined in check-stellar-testnet-snippets.ts):
      #   0  – all checks passed
      #   1  – content regression   → hard failure, blocks merge
      #   2  – provider outage      → warning annotation only, does NOT block
      - name: Validate Stellar testnet provider availability (non-blocking)
        id: provider-check
        continue-on-error: true
        env:
          MODE: provider
        run: |
          set +e
          pnpm run check:stellar-testnet
          STATUS=$?
          set -e
          echo "exit-status=$STATUS" >> "$GITHUB_OUTPUT"
          exit $STATUS

      # Exit 1  → content regression from a reachable provider; hard-fail.
      # Exit 2  → provider outage; emit a warning annotation and continue.
      # Exit 0  → all good; nothing to do.
      - name: Classify provider-check exit status
        if: always()
        env:
          PROVIDER_EXIT: ${{ steps.provider-check.outputs.exit-status }}
        run: |
          case "$PROVIDER_EXIT" in
            0)
              echo "Provider check passed."
              ;;
            1)
              echo "::error::Provider step detected a content regression (exit 1). Failing the job."
              exit 1
              ;;
            2)
              echo "::warning::Provider step reported a testnet outage (exit 2). Non-blocking."
              ;;
            *)
              echo "::error::Provider step exited with unexpected status '$PROVIDER_EXIT'. Failing the job."
              exit 1
              ;;
          esac

      - name: Test exit-status classification logic
        run: pnpm run test:stellar-testnet

  mint-validation:
    name: Mint config validation and preview redirect checks
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Validate Mint navigation and configuration
        run: npx --yes mintlify@4.2.1082 validate

      - name: Run preview redirect unit tests
        run: pnpm run test:preview-redirect

      # The live preview check needs a deployed Mintlify preview. It is only
      # required when that URL is actually supplied — without one there is
      # nothing to verify, and the unit tests above already cover the
      # redirect logic.
      - name: Verify live preview redirect
        if: ${{ env.MINTLIFY_PREVIEW_URL != '' }}
        run: node scripts/check-preview-redirect.mjs


  playground-smoke:
    name: Playground smoke test
    runs-on: ubuntu-latest
    needs: extract-sdk-version
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: Download published SDK artifact
        run: |
          echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}"
          cd /tmp
          npm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}

      - name: Install dependencies with pinned SDK
        run: |
          pnpm install --frozen-lockfile
          pnpm remove @wraith-protocol/sdk
          pnpm add /tmp/wraith-protocol-sdk-${{ needs.extract-sdk-version.outputs.sdk-version }}.tgz

      - name: Record tested SDK version
        run: |
          echo "Testing against SDK version: ${{ needs.extract-sdk-version.outputs.sdk-version }}"

      - name: Verify playground fixtures are in sync
        run: pnpm run check:playground-fixtures

      - name: Install Playwright browser
        run: pnpm exec playwright install --with-deps chromium

      - name: Run playground smoke tests
        run: pnpm run test:playground

  check-stellar-reference:
    name: Stellar contract reference check
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: Install Stellar CLI
        # Pinned to the same minor used during the last registry verification.
        # Update this pin when the CLI interface changes in a way that affects
        # `stellar contract inspect` output parsing.
        run: |
          curl -sSfL https://github.com/stellar/stellar-cli/releases/download/v28.1.0/stellar-cli-28.1.0-x86_64-unknown-linux-gnu.tar.gz \
            | tar -xz -C /usr/local/bin stellar
          stellar version

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # Only the two contracts that currently have live testnet addresses are
      # listed here (from scripts/contract-registry.json, stellar-testnet block).
      # stealth-registry and stealth-sender are not yet deployed and are omitted
      # until their addresses appear in the registry.
      - name: Check Stellar generated reference
        env:
          STELLAR_CONTRACT_IDS: >-
            {
              "stealth-announcer": "CCJLJ2QRBJAAKIG6ELNQVXLLWMKKWVN5O2FKWUETHZGMPAD4MHK7WVWL",
              "wraith-names": "CDEMB3MAE62ZOCCKZPTYSXR5CS5WVENPOU5MDVK4PNKTZXFVDC74AFBV"
            }
          STELLAR_NETWORK: testnet
        run: >-
          pnpm exec tsx scripts/generate-stellar-reference.ts
          --check
          --require-contracts=stealth-announcer,wraith-names