name: Puter.js API Tests

# Always triggers so it can be a required PR check; the `changes` job below
# decides whether puter.js-relevant paths actually changed (the suites live
# in src/puter-js/tests, so test-only changes are covered by the same glob,
# plus the pieces the runners depend on: the worker preamble, the in-memory
# test env in testUtil, and the backend vitest config the API-tests config
# extends), and every other job is skipped — not absent — when they didn't,
# which still satisfies a required check. Backend and extension changes run
# backend-tests.yaml instead.
on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      puterjs: ${{ steps.filter.outputs.puterjs }}
    steps:
      - uses: actions/checkout@v7
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            puterjs:
              - 'src/puter-js/**'
              - 'src/worker/**'
              - 'src/backend/testUtil.ts'
              - 'src/backend/vitest.config.ts'
              - 'tools/**'
              - 'package.json'
              - 'package-lock.json'
              - '.github/workflows/puterjs-tests.yaml'

  # The JSDoc in src/puter-js/src is the source of truth for the SDK's public
  # types. The declarations shipped to npm are generated from it at build time
  # and never committed, so what needs guarding is the JSDoc itself: this
  # generates the declarations and type-checks the published surface without
  # skipLibCheck, which is how broken re-exports used to go unnoticed.
  #
  # Its own job rather than a step in `test`: that one builds bundles and
  # installs a browser, and this needs neither.
  types:
    needs: changes
    if: needs.changes.outputs.puterjs == 'true'
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Check the puter.js JSDoc produces declarations that type-check
        run: npm run check:puterjs:types

  test:
    needs: changes
    if: needs.changes.outputs.puterjs == 'true'
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      # The runners exercise the built artifacts: the SDK bundle
      # (src/puter-js/dist) for node + browser, and the worker preamble
      # (src/worker/dist) for workerd.
      - name: Build puter.js SDK and worker preamble
        run: npm run build:workerLib

      - name: Install Playwright chromium
        run: npx playwright install --with-deps chromium

      - name: Run puter.js API tests (node, browser, workerd)
        run: npm run test:puterjs
        env:
          CI: 'true'

  # SDK coverage on both refs, reported as a PR comment — same shape as
  # backend-tests.yaml. This run uses the istanbul-instrumented bundle
  # (the `test` job above keeps exercising the production build).
  # `needs.changes` gates the steps below, not this job, on purpose: a
  # job-level `if` on a matrix job skips the whole job as one unexpanded
  # check ("coverage (${{ matrix.artifact }})", literally, since there's no
  # matrix context to fill it in) instead of two real per-artifact checks —
  # confusing to read, and unusable if this ever gets pinned as a required
  # check. Letting the matrix always expand keeps the check names stable.
  coverage:
    needs: changes
    # Overrides the default matrix naming, which would otherwise bake the
    # base/head branch name (matrix.ref) into the check name — making it a
    # different string on every PR and impossible to pin as a required check.
    name: coverage (${{ matrix.artifact }})
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - ref: ${{ github.base_ref }}
            artifact: base
          - ref: ${{ github.head_ref }}
            artifact: pr

    steps:
      - name: Checkout ${{ matrix.ref }}
        if: needs.changes.outputs.puterjs == 'true'
        uses: actions/checkout@v7
        with:
          ref: ${{ matrix.ref }}
          repository: ${{ github.event.pull_request.head.repo.full_name }}

      - name: Set up Node.js
        if: needs.changes.outputs.puterjs == 'true'
        uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: 'npm'

      - name: Install dependencies
        if: needs.changes.outputs.puterjs == 'true'
        run: npm ci

      - name: Install Playwright chromium
        if: needs.changes.outputs.puterjs == 'true'
        run: npx playwright install --with-deps chromium

      # The base leg is best-effort — it only enriches the PR comment with
      # a comparison, and the base ref may predate the coverage script.
      - name: Run puter.js API tests with coverage
        if: needs.changes.outputs.puterjs == 'true'
        continue-on-error: ${{ matrix.artifact == 'base' }}
        run: npm run test:puterjs:coverage
        env:
          CI: 'true'

      - name: Upload coverage artifact
        if: needs.changes.outputs.puterjs == 'true' && !cancelled()
        uses: actions/upload-artifact@v4
        with:
          name: puterjs-coverage-${{ matrix.artifact }}
          path: src/puter-js/coverage/coverage-*.json
          retention-days: 14
          if-no-files-found: ignore

  report-coverage:
    needs: [changes, coverage]
    if: always() && needs.changes.outputs.puterjs == 'true'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7

      - name: Download PR coverage
        uses: actions/download-artifact@v8
        with:
          name: puterjs-coverage-pr
          path: src/puter-js/coverage

      # May not exist (base ref without the coverage script, or a failed
      # base run) — then report without the comparison column.
      - name: Download base coverage
        id: base-coverage
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          name: puterjs-coverage-base
          path: coverage-base

      - name: Report coverage on PR
        if: steps.base-coverage.outcome == 'success'
        uses: davelosert/vitest-coverage-report-action@v2
        with:
          name: puter.js SDK
          json-summary-path: src/puter-js/coverage/coverage-summary.json
          json-final-path: src/puter-js/coverage/coverage-final.json
          json-summary-compare-path: coverage-base/coverage-summary.json

      - name: Report coverage on PR (no base comparison)
        if: steps.base-coverage.outcome != 'success'
        uses: davelosert/vitest-coverage-report-action@v2
        with:
          name: puter.js SDK
          json-summary-path: src/puter-js/coverage/coverage-summary.json
          json-final-path: src/puter-js/coverage/coverage-final.json