perf.yml

name: perf

# On-demand performance-benchmark guard. The multi-minute perf specs are too
# costly to re-run on every commit, and their timings are noisy on shared
# runners (a time-based schedule would add noise, not signal); only their
# structural metrics (sizes, counts) are deterministic. They run only when
# explicitly wanted:
#
#   * manually (``workflow_dispatch``),
#   * on a pull request carrying the ``run-perf`` label,
#   * on every push to ``main`` (release merges),
#   * on every ``vX.Y.Z`` release tag.
#
# Results are tracked over time by ``benchmark-action/github-action-benchmark``
# on the orphan ``benchmarks`` branch (chart at ``dev/bench/.../index.html``).
# On pull requests a deterministic regression beyond the threshold fails the
# check (the regression gate); on ``main`` / tags the history is recorded but
# never fails, since the change is already merged.
on:
  workflow_dispatch:
  pull_request:
    types: [opened, synchronize, reopened, labeled]
  push:
    branches: [main]
    tags: ["v*.*.*"]

# A release pushes ``main`` and a tag; each is a distinct ref and runs once.
# Cancel only superseded runs of the *same* ref (rapid re-pushes).
concurrency:
  group: perf-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: write
  pull-requests: write

jobs:
  perf:
    name: Performance benchmarks (on-demand)
    # On a pull request, run only when the PR carries the ``run-perf`` label
    # (opt-in). Manual / push / tag events always run.
    if: >-
      github.event_name != 'pull_request' ||
      contains(github.event.pull_request.labels.*.name, 'run-perf')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

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

      - name: Set up Python
        uses: actions/setup-python@v7
        with:
          python-version: "3.12"

      - name: Install npm dependencies
        run: npm ci

      - name: Prepare configured Sigima and guidata dependencies
        run: >-
          python scripts/sigima_dependency.py prepare-pyodide
          --wheel-dir .wheels
          --github-env "$GITHUB_ENV"

      # Same configuration as the CI: provenance_capsule_perf measures the
      # provenance and capsule paths, and must not skip them.
      - name: Prepare configured DataLab-Capsule dependency
        run: >-
          python scripts/capsule_dependency.py prepare-pyodide
          --wheel-dir .wheels
          --github-env "$GITHUB_ENV"

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

      - name: Run perf benchmarks
        # ``test:e2e:perf`` is ``playwright test --project=perf`` (image_perf,
        # signal_perf, opfs_*, provenance_capsule_perf with its quick profile);
        # the comparative ``benchmark`` project is never run here.
        # PW_PERF is redundant with the ``--project=perf`` flag but makes the
        # opt-in explicit.
        env:
          PW_PERF: "1"
          DLW_REQUIRE_PROVENANCE: "1"
        run: npm run test:e2e:perf

      - name: Convert results to benchmark format
        run: node scripts/perf-to-benchmark-json.mjs

      - name: Track deterministic metrics (regression gate)
        uses: benchmark-action/github-action-benchmark@v1
        with:
          name: DataLab-Web perf (deterministic)
          tool: customSmallerIsBetter
          output-file-path: tests/benchmark/results/bench-determinist.json
          github-token: ${{ secrets.GITHUB_TOKEN }}
          gh-pages-branch: benchmarks
          benchmark-data-dir-path: dev/bench/determinist
          alert-threshold: "125%"
          comment-on-alert: true
          summary-always: true
          # Memory / payload-size metrics are deterministic, so a real
          # increase is a genuine regression: fail the check on PRs. On
          # main / tags only record + comment (already merged).
          fail-on-alert: ${{ github.event_name == 'pull_request' }}
          auto-push: ${{ github.event_name != 'pull_request' }}
          save-data-file: ${{ github.event_name != 'pull_request' }}

      - name: Track timing metrics (trend only)
        uses: benchmark-action/github-action-benchmark@v1
        with:
          name: DataLab-Web perf (timings)
          tool: customSmallerIsBetter
          output-file-path: tests/benchmark/results/bench-timings.json
          github-token: ${{ secrets.GITHUB_TOKEN }}
          gh-pages-branch: benchmarks
          benchmark-data-dir-path: dev/bench/timings
          # Wall-clock timings are noisy on shared runners and some complete
          # below the useful timing floor. Keep their history and job summary
          # for trend inspection, but do not turn relative fluctuations into
          # PR comments; actionable alerts come from the deterministic suite.
          alert-threshold: "200%"
          comment-on-alert: false
          summary-always: true
          fail-on-alert: false
          auto-push: ${{ github.event_name != 'pull_request' }}
          save-data-file: ${{ github.event_name != 'pull_request' }}

      - name: Upload raw perf results
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: perf-results
          path: |
            tests/benchmark/results/*.json
            playwright-report/
          retention-days: 14