ci.yml

# D116 — CI runs the gate the change set calls for, not every gate every time.
#
# The first job works out what this push or pull request can have moved:
# `scripts/gate-scope.mjs` maps every changed path to an owner, takes the
# downstream closure over the package graph, and publishes the plan. The
# quick-tier jobs below consume it — source quality always, because `check` is
# in every plan, and the Node suite matrix only when the plan names files for
# it.
#
# The heavy tier — the browser suite, packed-consumer acceptance, and the full
# Node suite with every `*.slow.test.ts` — is not on the path of a
# push. D116 §三 puts it before a release: it runs on a `v*` tag, once a day on
# a schedule, and whenever somebody asks for it. That is the same tier
# `npm run release:check` runs locally, and it is the only place the browser and
# packed-consumer verdicts are taken. Between those runs the quick tier's
# emitted-output fingerprint stands in for them: those two suites only ever run
# emitted artifacts, so a byte-identical `output-fingerprint.lock` is an
# unchanged verdict.
#
# Two gates carry macOS-only coverage and therefore run on both runners:
# `tests/desktop/desktop.test.ts` and `tests/acceptance/package.acceptance.ts` both stop before
# `velar package` on any other platform, because @velarscript/desktop 0.10
# builds only the macOS system-WebView host. Linux proves the single-project
# compiler contract; macOS is the only place the packaged .app, its size
# budget, and the installed toolchain's desktop path are actually produced.
# D116 §六 keeps the macOS runner in the quick tier's Node matrix and gives the
# heavy tier's macOS run to tags alone. There is no Windows runner: D101 ruling
# 7 keeps the Windows and Linux desktop hosts as later milestones, and a runner
# for a target the language does not claim yet would gate on nothing.
name: Velar CI

on:
  push:
    branches:
      - main
    tags:
      - "v*"
  pull_request:
  schedule:
    # 03:00 UTC daily: the heavy tier's standing run, so a verdict is never
    # older than a day even on a week of quick-tier-only pushes.
    - cron: "0 3 * * *"
  workflow_dispatch:

permissions:
  contents: read
  packages: read

# A pull request that receives a second push has no use for the first push's
# jobs. A commit on main does: every commit there keeps its own verdict.
concurrency:
  group: velar-ci-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  scope:
    # D116 §二.2 — the change set is computed from git, not reported by a human.
    # This job needs no install and no build: the ownership it reads is the
    # committed `tests/ownership.generated.json`, which `check` regenerates and
    # compares on every run.
    name: Scope
    runs-on: ubuntu-latest
    timeout-minutes: 10
    outputs:
      plan: ${{ steps.plan.outputs.plan }}
      run-node: ${{ steps.plan.outputs.run-node }}
      run-fingerprint: ${{ steps.plan.outputs.run-fingerprint }}
      node-files: ${{ steps.plan.outputs.node-files }}
    steps:
      # The full history: a scope computed against a base commit the runner does
      # not have would look exactly like a change set of nothing.
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v6
        with:
          node-version: "24.x"
      - name: Plan the suites this change set can have moved
        id: plan
        env:
          # A push carries the commit it advanced from; a pull request carries
          # its base. A first push to a new branch reports the all-zero sha,
          # which `gate-scope.mjs` reads as "no base given" and answers by
          # falling back to HEAD~1.
          BASE: ${{ github.event.before || github.event.pull_request.base.sha }}
        run: |
          node scripts/gate-scope.mjs --explain --since "$BASE"
          node scripts/gate-scope.mjs --json --since "$BASE" > gate-plan.json
          {
            echo "plan<<VELAR_PLAN_EOF"
            cat gate-plan.json
            echo "VELAR_PLAN_EOF"
            echo "run-node=$(node -p 'String(require("./gate-plan.json").suites.node.length > 0)')"
            echo "run-fingerprint=$(node -p 'String(require("./gate-plan.json").suites.fingerprint)')"
            echo "node-files=$(node -p 'String(require("./gate-plan.json").suites.node.length)')"
          } >> "$GITHUB_OUTPUT"

  quality:
    # `check` is in every plan — it is the one suite a documentation-only change
    # still has to pass — so this job has no condition. The emitted-output
    # fingerprint rides with it: it needs the same build `check` has just done.
    name: Source quality
    needs: scope
    runs-on: ubuntu-latest
    timeout-minutes: 25
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "24.x"
          cache: npm
      - run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ github.token }}
      - run: npm run check
      - name: Take the plan from the scope job
        if: needs.scope.outputs.run-fingerprint == 'true'
        env:
          PLAN: ${{ needs.scope.outputs.plan }}
        run: printf '%s' "$PLAN" > gate-plan.json
      - name: Compare the emitted output against its lock
        if: needs.scope.outputs.run-fingerprint == 'true'
        run: node scripts/gate.mjs --plan gate-plan.json --only fingerprint

  node-suite:
    # Formatting, documentation, boundaries and types are one platform's job;
    # the Node suite is not. It compiles and runs real programs, and its
    # desktop packaging coverage exists only on macOS. Which files it runs is
    # the plan's answer, not this file's.
    name: Node suite
    needs: scope
    if: needs.scope.outputs.run-node == 'true'
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "24.x"
          cache: npm
      - run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ github.token }}
      # The Node suite is not browser-free: web-error-paths, browser-lifecycle
      # and module-enum-surface drive a real Chromium, the historical hardening
      # waves drive several more, and the engine-matrix hardening tests
      # ([CLI-29], [CLI-31]) run --browser=all — so this job needs all three
      # engines. The browser-suite job below stays deliberately
      # Chromium-only per the release-process doc; the matrix tests are the
      # exception, and they live in test:full.
      - name: Cache the locked Playwright browsers
        uses: actions/cache@v6
        with:
          path: ${{ runner.os == 'macOS' && '~/Library/Caches/ms-playwright' || '~/.cache/ms-playwright' }}
          key: playwright-all-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
      - name: Install the locked browser engines
        run: npx playwright install chromium firefox webkit
      - name: Install browser system dependencies
        if: runner.os == 'Linux'
        run: npx playwright install-deps chromium firefox webkit
      - name: Read the pinned Desktop runtime version
        if: runner.os == 'macOS'
        id: desktop-runtime
        run: |
          version="$(node --input-type=module -e 'import { DESKTOP_NODE_RUNTIME_VERSION } from "./packages/desktop/src/config.ts"; process.stdout.write(DESKTOP_NODE_RUNTIME_VERSION)')"
          echo "version=$version" >> "$GITHUB_OUTPUT"
      # `velar package` embeds one pinned Node.js runtime, and the first build on
      # a machine downloads its ~50 MiB archive from nodejs.org. The version is
      # read from the one place that pins it rather than written here a second
      # time, so bumping the pin invalidates this key on its own and a runner
      # never restores an executable the toolchain no longer embeds. There are no
      # restore-keys for the same reason: an older cache would be restored and
      # then downloaded past.
      - name: Cache the embedded Desktop Node runtime
        if: runner.os == 'macOS'
        uses: actions/cache@v6
        with:
          path: ~/Library/Caches/velarscript/desktop-runtimes
          key: desktop-runtime-${{ runner.os }}-${{ steps.desktop-runtime.outputs.version }}
      - name: Take the plan from the scope job
        env:
          PLAN: ${{ needs.scope.outputs.plan }}
        run: printf '%s' "$PLAN" > gate-plan.json
      - run: npm run build:packages
      - name: Run the planned Node test files
        run: node scripts/gate.mjs --plan gate-plan.json --only node,projects

  browser-suite:
    # Heavy tier. 1x1 by design: the current host and Chromium. The browser gate
    # holds no platform-specific branch, so it is not repeated on macOS.
    name: Browser suite (heavy tier)
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    timeout-minutes: 40
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "24.x"
          cache: npm
      - run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ github.token }}
      # Keyed on the lockfile, because the lockfile is what pins the Playwright
      # version whose Chromium revision these gates expect.
      - name: Cache the locked Playwright browsers
        uses: actions/cache@v6
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
      - name: Install the locked Chromium build
        run: npx playwright install chromium
      - name: Install Chromium system dependencies
        run: npx playwright install-deps chromium
      - run: npm run test:browser

  packed-consumers:
    # Heavy tier. `velar package` for a desktop project is reached here only
    # through the installed toolchain, and only on macOS.
    name: Packed consumers (heavy tier)
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/v')
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
    timeout-minutes: 40
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "24.x"
          cache: npm
      - run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ github.token }}
      - name: Read the pinned Desktop runtime version
        if: runner.os == 'macOS'
        id: desktop-runtime
        run: |
          version="$(node --input-type=module -e 'import { DESKTOP_NODE_RUNTIME_VERSION } from "./packages/desktop/src/config.ts"; process.stdout.write(DESKTOP_NODE_RUNTIME_VERSION)')"
          echo "version=$version" >> "$GITHUB_OUTPUT"
      # The same runtime the Node suite caches: this gate reaches `velar package`
      # through the installed toolchain, which downloads the identical archive
      # into the identical cache, so the two jobs share one key rather than one
      # of them paying for it every run.
      - name: Cache the embedded Desktop Node runtime
        if: runner.os == 'macOS'
        uses: actions/cache@v6
        with:
          path: ~/Library/Caches/velarscript/desktop-runtimes
          key: desktop-runtime-${{ runner.os }}-${{ steps.desktop-runtime.outputs.version }}
      - run: npm run test:packages

  full-node-suite:
    # Heavy tier: the quick suite plus every `*.slow.test.ts`.
    # macOS joins it on a tag only, per
    # D116 §六 — the quick tier's matrix already runs the macOS-only desktop
    # coverage on every push.
    name: Full Node suite (heavy tier)
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/v')
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: ${{ startsWith(github.ref, 'refs/tags/v') && fromJSON('["ubuntu-latest", "macos-latest"]') || fromJSON('["ubuntu-latest"]') }}
    timeout-minutes: 90
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "24.x"
          cache: npm
      - run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ github.token }}
      - name: Cache the locked Playwright browsers
        uses: actions/cache@v6
        with:
          path: ${{ runner.os == 'macOS' && '~/Library/Caches/ms-playwright' || '~/.cache/ms-playwright' }}
          key: playwright-all-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
      - name: Install the locked browser engines
        run: npx playwright install chromium firefox webkit
      - name: Install browser system dependencies
        if: runner.os == 'Linux'
        run: npx playwright install-deps chromium firefox webkit
      - name: Read the pinned Desktop runtime version
        if: runner.os == 'macOS'
        id: desktop-runtime
        run: |
          version="$(node --input-type=module -e 'import { DESKTOP_NODE_RUNTIME_VERSION } from "./packages/desktop/src/config.ts"; process.stdout.write(DESKTOP_NODE_RUNTIME_VERSION)')"
          echo "version=$version" >> "$GITHUB_OUTPUT"
      - name: Cache the embedded Desktop Node runtime
        if: runner.os == 'macOS'
        uses: actions/cache@v6
        with:
          path: ~/Library/Caches/velarscript/desktop-runtimes
          key: desktop-runtime-${{ runner.os }}-${{ steps.desktop-runtime.outputs.version }}
      - run: npm run test:full