build.yml

name: Build Variant

on:
  push:
    branches: [master, ver/*, feat/*]
  pull_request:
    branches: [master, ver/*, feat/*]
  workflow_dispatch:
    inputs:
      variant:
        description: 'Which src/rc/<variant>.rc to build, or all of them'
        type: choice
        required: true
        default: all
        options:
          - all
          - control
          - control84
          - control85
          - min85
          - trim85
          - nopdo85
          - noopcache85
          - mergefunc85
          - mbstring
          - nolto
          - jspi
          - jspimb
          - jspisjlj
          - jspimbsjlj
          - wasm64
          - long64
      php_wasm_ref:
        description: 'seanmorris/php-wasm git ref (tag, branch or SHA). Recorded in the release notes'
        type: string
        required: true
        default: master
      patch_vm_interrupt:
        description: 'Apply patch-vm-interrupt.sh (needed for slice exports)'
        type: boolean
        default: false
      release_tag:
        description: 'Release tag to create. Empty derives snapshot-<short sha>'
        type: string
        required: false
      prerelease:
        description: 'Mark the release as a prerelease'
        type: boolean
        default: true
      publish:
        description: 'Attach the artifacts to a Release. Off archives them only'
        type: boolean
        default: true

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}-${{ inputs.variant }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

env:
  PHP_WASM_DIR: /tmp/phpwasm-build/php-wasm
  PHP_WASM_REF: ${{ inputs.php_wasm_ref || 'master' }}

jobs:
  lint:
    runs-on: ubuntu-latest
    timeout-minutes: 10

    permissions:
      contents: read

    steps:
      - uses: actions/checkout@v7
      - name: Set up Bun
        uses: oven-sh/setup-bun@v2
        with:
          bun-version: 'latest'
      - name: Install Dependencies
        run: bun install --frozen-lockfile
      - name: Parse Every Script
        run: bash tools/lint-shell.sh
      - name: Drive the Patch State Machines
        run: bun run test
      - name: Run ShellCheck
        run: |
          if ! command -v shellcheck > /dev/null; then
            sudo apt-get update
            sudo apt-get install -y shellcheck
          fi
          shellcheck --version
          find src tools -name '*.sh' -print0 | xargs -0 shellcheck -x
      - name: Check C Formatting
        run: |
          pip install 'clang-tools>=1.2.0'
          clang-tools install --version 21 clang-format --no-progress-bar
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          export PATH="$HOME/.local/bin:$PATH"
          clang-format --version
          bun run lint:c
      - name: Reject Committed Artifacts
        run: |
          found="$(git ls-files '*.wasm' '*.o' '*.a')"
          if [ -n "$found" ]; then
            echo "build artifacts are tracked in git; they belong in a Release:"
            echo "$found"
            exit 1
          fi
          echo "no tracked build artifacts"
      - name: Evaluate Every RC Against php-wasm's Guards
        run: |
          git clone --depth 1 https://github.com/seanmorris/php-wasm /tmp/rc-lint-php-wasm
          cd /tmp/rc-lint-php-wasm && npm install --no-audit --no-fund > /dev/null
          cd "$GITHUB_WORKSPACE" && bash tools/lint-rc.sh /tmp/rc-lint-php-wasm

      - name: Run Markdownlint
        run: bun run lint:md

  plan:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    needs: lint

    permissions:
      contents: read

    outputs:
      variants: ${{ steps.pick.outputs.variants }}
      release_tag: ${{ steps.pick.outputs.release_tag }}

    steps:
      - uses: actions/checkout@v7
      - name: Pick the Variants and the Tag
        id: pick
        run: |
          if [ '${{ github.event_name }}' = 'workflow_dispatch' ] && [ '${{ inputs.variant }}' != 'all' ]; then
            variants="$(printf '%s' '${{ inputs.variant }}' | jq -R . | jq -cs .)"
          else
            variants="$(find src/rc -name '*.rc' -exec basename {} .rc ';' | sort | jq -R . | jq -cs .)"
          fi
          echo "variants=$variants"
          echo "variants=$variants" >> "$GITHUB_OUTPUT"

          tag='${{ inputs.release_tag }}'
          if [ -z "$tag" ]; then
            tag="snapshot-$(echo '${{ github.sha }}' | cut -c1-7)"
          fi
          echo "release_tag=$tag"
          echo "release_tag=$tag" >> "$GITHUB_OUTPUT"

  build:
    runs-on: ubuntu-latest
    timeout-minutes: 350
    needs: plan

    strategy:
      fail-fast: false
      matrix:
        variant: ${{ fromJSON(needs.plan.outputs.variants) }}

    permissions:
      contents: read
      id-token: write
      attestations: write

    steps:
      - uses: actions/checkout@v7

      - name: Check the RC Exists
        run: |
          # a .rc.pending variant is invisible to the push matrix but buildable by dispatch, which
          # is the only way an unproven arm gets its first green run without failing every push
          RC="src/rc/${{ matrix.variant }}.rc"
          if [ ! -f "$RC" ] && [ -f "$RC.pending" ]; then
            echo "::warning::building the PENDING rc $RC.pending; rename it to $RC once it links"
            RC="$RC.pending"
          fi
          test -f "$RC" || { echo "no rc file at src/rc/${{ matrix.variant }}.rc"; exit 1; }
          echo "RC=$RC" >> "$GITHUB_ENV"
          echo "PHP_VERSION=$(grep -m1 '^PHP_VERSION=' "$RC" | cut -d= -f2)" >> "$GITHUB_ENV"

      - name: Ensure GNU make 4.4 or Newer
        run: |
          have=$(make --version | head -1 | grep -oE '[0-9]+\.[0-9]+' | head -1)
          echo "make on the runner: $have"
          if [ "$(printf '%s\n4.4\n' "$have" | sort -V | head -1)" = "4.4" ]; then
            echo "make is new enough"
            exit 0
          fi
          echo "building GNU make 4.4.1 from source"
          MAKE_SHA256=dd16fb1d67bfab79a72f5e8390735c49e3e8e70b4945a15ab1f81ddb78658fb3
          for url in \
            https://ftpmirror.gnu.org/gnu/make/make-4.4.1.tar.gz \
            https://mirrors.kernel.org/gnu/make/make-4.4.1.tar.gz \
            https://ftp.gnu.org/gnu/make/make-4.4.1.tar.gz; do
            echo "trying $url"
            if curl -fsSL --connect-timeout 15 --max-time 300 --retry 2 --retry-connrefused \
              "$url" -o /tmp/make.tar.gz; then
              if echo "$MAKE_SHA256  /tmp/make.tar.gz" | sha256sum -c -; then
                break
              fi
              echo "::warning::$url served an unexpected checksum; trying the next mirror" >&2
            fi
            rm -f /tmp/make.tar.gz
          done
          test -f /tmp/make.tar.gz || { echo "::error::every make 4.4.1 mirror failed" >&2; exit 1; }
          mkdir -p /tmp/make-src && tar -xzf /tmp/make.tar.gz --strip-components=1 -C /tmp/make-src
          cd /tmp/make-src && ./configure --prefix=/usr/local > /dev/null && make -j"$(nproc)" > /dev/null
          sudo make install
          hash -r
          make --version | head -1

      - name: Pin the Builder Image by Digest
        run: |
          bash src/pin-builder-image.sh
          echo "BUILDER_IMAGE_PINNED=$(bash src/pin-builder-image.sh --print)" >> "$GITHUB_ENV"

      - name: Clone php-wasm at the Requested Ref
        run: |
          mkdir -p "$(dirname "$PHP_WASM_DIR")"
          git clone https://github.com/seanmorris/php-wasm "$PHP_WASM_DIR"
          cd "$PHP_WASM_DIR"
          git checkout --detach "$PHP_WASM_REF"
          echo "PHP_WASM_SHA=$(git rev-parse HEAD)" >> "$GITHUB_ENV"

      - name: Install php-wasm's Node Packages
        run: |
          cd "$PHP_WASM_DIR"
          npm install --no-audit --no-fund
          echo "packages visible to the Makefile: $(npm ls -p | wc -l)"

      - name: Stage the RC
        run: |
          cp "$RC" "$PHP_WASM_DIR/.php-wasm-rc"

      - name: Fetch and Patch the PHP Sources
        run: |
          cd "$PHP_WASM_DIR"
          make "third_party/php${PHP_VERSION}-src/patched" \
            PHP_BUILDER_DIR="$PHP_WASM_DIR" \
            IS_TTY=0 \
            ENV_DIR="$PHP_WASM_DIR/" \
            ENV_FILE="$PHP_WASM_DIR/.php-wasm-rc"
          test -f "third_party/php${PHP_VERSION}-src/Zend/zend_execute.c"

      - name: Drop ext/opcache
        run: |
          if grep -qE '^DROP_OPCACHE=1' "$RC"; then
            PHP_VERSION="$PHP_VERSION" bash src/patch-drop-opcache.sh "$PHP_WASM_DIR"
            PHP_VERSION="$PHP_VERSION" bash src/patch-drop-opcache.sh "$PHP_WASM_DIR" --verify
          else
            echo "rc does not set DROP_OPCACHE, leaving ext/opcache intact"
          fi

      - name: Drop lexbor's HTML Half
        run: |
          if grep -qE '^DROP_LEXBOR_HTML=1' "$RC"; then
            PHP_VERSION="$PHP_VERSION" bash src/patch-drop-lexbor-html.sh "$PHP_WASM_DIR"
            PHP_VERSION="$PHP_VERSION" bash src/patch-drop-lexbor-html.sh "$PHP_WASM_DIR" --verify
          else
            echo "rc does not set DROP_LEXBOR_HTML, leaving lexbor intact"
          fi

      - name: Apply the VM Interrupt Patch
        if: ${{ inputs.patch_vm_interrupt }}
        run: PHP_VERSION="$PHP_VERSION" bash src/patch-vm-interrupt.sh "$PHP_WASM_DIR"

      - name: Verify the VM Interrupt Patch Applied
        if: ${{ inputs.patch_vm_interrupt }}
        run: PHP_VERSION="$PHP_VERSION" bash src/patch-vm-interrupt.sh "$PHP_WASM_DIR" --verify

      - name: Verify the Tree Is NOT Patched When It Should Not Be
        if: ${{ !inputs.patch_vm_interrupt }}
        run: |
          if PHP_VERSION="$PHP_VERSION" bash src/patch-vm-interrupt.sh "$PHP_WASM_DIR" --verify; then
            echo "::error::the tree is patched but this variant asked for an unpatched control" >&2
            exit 1
          fi
          echo "confirmed unpatched, which is what this variant asked for"

      - name: Restore the Emscripten Sysroot
        id: emsdk-cache
        uses: actions/cache/restore@v6
        with:
          path: /tmp/emsdk-cache
          key: emsdk-${{ runner.os }}-${{ hashFiles('src/pin-builder-image.sh') }}-${{ matrix.variant }}
          restore-keys: |
            emsdk-${{ runner.os }}-${{ hashFiles('src/pin-builder-image.sh') }}-

      - name: Fetch the Libraries php-wasm Does Not
        run: |
          ICONV=""
          if grep -qE '^[[:space:]]*WITH_ICONV=[^0]' "$RC" || grep -q -- '--with-iconv' "$RC"; then
            ICONV="--with-iconv"
          fi
          # every library has to carry the same pointer width as php-src or wasm-ld rejects the
          # final link, and the emsdk cache is keyed per variant so the ABIs cannot collide
          if grep -q 'MEMORY64=1' "$RC"; then
            export MEMORY64=1
          fi
          bash src/fetch-deps.sh "$PHP_WASM_DIR" $ICONV

      - name: Retype vrzno for the LP64 ABI
        run: |
          if grep -q 'MEMORY64=1' "$RC"; then
            PHP_VERSION="$PHP_VERSION" bash src/patch-vrzno-lp64.sh "$PHP_WASM_DIR"
            PHP_VERSION="$PHP_VERSION" bash src/patch-vrzno-lp64.sh "$PHP_WASM_DIR" --verify
          else
            echo "rc is wasm32, leaving vrzno's ILP32 call sites intact"
          fi

      - name: Enlarge Swap for the LTO Link
        run: |
          echo "before:"
          free -h
          sudo swapoff -a || true
          sudo rm -f /mnt/swapfile
          sudo fallocate -l 24G /mnt/swapfile
          sudo chmod 600 /mnt/swapfile
          sudo mkswap /mnt/swapfile > /dev/null
          sudo swapon /mnt/swapfile
          echo "after:"
          free -h

      - name: Build the Variant
        run: |
          # the compile-half flags used to be derived here, which meant a local build of the same
          # variant silently compiled without them; build-variant.sh owns that now
          JOBS="$(nproc)" bash src/build-variant.sh "${{ matrix.variant }}" "$PHP_WASM_DIR"

      - name: Report Whether the Kernel Killed the Link
        if: failure()
        run: |
          if sudo dmesg | grep -iE 'out of memory|killed process'; then
            free -h
            echo "::error::the kernel OOM-killed a build process; raise the swap step above" >&2
          else
            echo "No kernel OOM kill in dmesg. This step says NOTHING about why the build failed;"
            echo "it only rules out memory exhaustion. Read the build log above for the real cause."
          fi

      - name: Save the Emscripten Sysroot
        if: ${{ !cancelled() && steps.emsdk-cache.outputs.cache-hit != 'true' }}
        uses: actions/cache/save@v6
        with:
          path: /tmp/emsdk-cache
          key: ${{ steps.emsdk-cache.outputs.cache-primary-key }}

      - name: Fix emscripten's MEMORY64 Glue Defects
        run: |
          if grep -q 'MEMORY64=1' "$RC"; then
            # the glue that SHIPS is the one staged from vendor/static-<variant>. an earlier version
            # searched PHP_WASM_DIR and found the build tree's copy, so both fixes and their --verify
            # landed on a file the artifact does not contain
            GLUE="vendor/static-${{ matrix.variant }}/php${PHP_VERSION}-worker.mjs"
            test -f "$GLUE" || { echo "::error::no glue at $GLUE; nothing would be patched" >&2; exit 1; }
            node src/patch-lp64-glue.mjs "$GLUE"
            node src/patch-lp64-glue.mjs "$GLUE" --verify

            # php-wasm's OWN library JS calls vrzno's exports too -- `jsToZval` reaches
            # `vrzno_expose_create_null` -- and those sites are not in ext/vrzno, so patching the C
            # cannot reach them. Measured: one site survived and threw `Cannot convert N to a BigInt`
            VRZNO="$PHP_WASM_DIR/third_party/php${PHP_VERSION}-src/ext/vrzno"
            node src/patch-vrzno-lp64.mjs "$VRZNO" --extra "$GLUE"
            node src/patch-vrzno-lp64.mjs "$VRZNO" --extra "$GLUE" --verify
          else
            echo "rc is wasm32, emscripten's memory64 glue defects do not apply"
          fi

      - name: Inspect and Assert the Artifact
        run: |
          set -o pipefail
          OUT="vendor/static-${{ matrix.variant }}"
          ARGS=(--expect-static "--expect-rc=$RC")
          if grep -q 'JSPI=1' "$RC"; then
            ARGS+=(--expect-jspi)
          fi
          if [ "${{ inputs.patch_vm_interrupt }}" = 'true' ]; then
            ARGS+=(--expect-slice)
          fi
          if grep -qE '^DROP_OPCACHE=1' "$RC"; then
            ARGS+=(--expect-no-opcache)
          fi
          echo "asserting: ${ARGS[*]}"
          bash src/inspect-build.sh "$OUT" "${ARGS[@]}" | tee /tmp/inspect.txt

      - name: Record the Toolchain
        run: |
          emcc_version="$(docker run --rm "$BUILDER_IMAGE_PINNED" emcc --version 2>/dev/null | head -1)"
          {
            echo "emcc: ${emcc_version:-unavailable}"
            echo "builder image: $BUILDER_IMAGE_PINNED"
          } > /tmp/toolchain.txt
          cat /tmp/toolchain.txt

      - name: Stage the Assets Under Variant-Qualified Names
        run: |
          mkdir -p dist
          for f in "vendor/static-${{ matrix.variant }}"/*.wasm "vendor/static-${{ matrix.variant }}"/*.mjs; do
            [ -f "$f" ] || continue
            cp "$f" "dist/phasm-${{ matrix.variant }}-$(basename "$f")"
          done
          ls -l dist

      - name: Assert the STAGED Glue Carries the LP64 Fixes
        run: |
          # against dist/ rather than against the build tree: a --verify that passes on a copy the
          # artifact does not contain is what published a wasm64 build with neither fix in it
          if grep -q 'MEMORY64=1' "$RC"; then
            node src/patch-lp64-glue.mjs \
              "dist/phasm-${{ matrix.variant }}-php${PHP_VERSION}-worker.mjs" --verify
          else
            echo "rc is wasm32, nothing to assert"
          fi

      - name: Compose the Release Notes Fragment
        run: |
          mkdir -p notes
          {
            echo "### \`${{ matrix.variant }}\`"
            echo
            echo '| input | value |'
            echo '| --- | --- |'
            echo "| variant | \`${{ matrix.variant }}\` |"
            echo "| php-wasm ref | \`$PHP_WASM_REF\` |"
            echo "| php-wasm commit | \`$PHP_WASM_SHA\` |"
            echo "| rc sha256 | \`$(sha256sum "$RC" | cut -d' ' -f1)\` |"
            echo "| builder image | \`$BUILDER_IMAGE_PINNED\` |"
            echo "| vm interrupt patch | ${{ inputs.patch_vm_interrupt || false }} |"
            echo "| this repo | \`${{ github.sha }}\` |"
            echo
            echo '```txt'
            cat /tmp/toolchain.txt
            cat /tmp/inspect.txt
            echo '```'
            echo
          } > "notes/${{ matrix.variant }}.md"
          cat "notes/${{ matrix.variant }}.md"

      - name: Archive the Artifact
        id: archive
        uses: actions/upload-artifact@v7
        with:
          name: phasm-${{ matrix.variant }}-${{ github.sha }}
          path: |
            dist/*
            notes/*
          overwrite: true
          if-no-files-found: error

      - name: Attest Build Artifacts
        if: ${{ github.event_name != 'pull_request' }}
        uses: actions/attest-build-provenance@v4
        with:
          subject-path: dist/*

      - name: Archive the Build Log on Failure
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: phasm-${{ matrix.variant }}-${{ github.sha }}-logs
          path: |
            /tmp/inspect.txt
            /tmp/toolchain.txt
            ${{ env.PHP_WASM_DIR }}/config.log
          retention-days: 14
          if-no-files-found: ignore

  publish:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    needs: [plan, build]
    if: ${{ github.event_name != 'pull_request' && (github.event_name != 'workflow_dispatch' || inputs.publish) }}

    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v7

      - name: Download Every Variant
        uses: actions/download-artifact@v8
        with:
          pattern: phasm-*-${{ github.sha }}
          path: staged
          merge-multiple: true

      - name: Assemble the Release Body
        run: |
          {
            if [ '${{ github.event_name }}' = 'workflow_dispatch' ]; then
              echo "Built by \`.github/workflows/build.yml\` on request."
            else
              echo "Snapshot of \`${{ github.sha }}\` on \`${{ github.ref_name }}\`, built by"
              echo "\`.github/workflows/build.yml\`. A snapshot is a prerelease and is never promoted;"
              echo "\`release.yml\` cuts the named releases."
            fi
            echo
            for f in staged/notes/*.md; do
              [ -f "$f" ] || continue
              cat "$f"
            done
          } > /tmp/body.md
          cat /tmp/body.md
          ls -l staged/dist

      - name: Create the Prerelease as a Draft
        uses: softprops/action-gh-release@v3
        with:
          tag_name: ${{ needs.plan.outputs.release_tag }}
          name: phasm ${{ needs.plan.outputs.release_tag }}
          body_path: /tmp/body.md
          draft: true
          prerelease: ${{ github.event_name != 'workflow_dispatch' || inputs.prerelease }}
          files: staged/dist/*
      - name: Publish the Draft
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh release edit '${{ needs.plan.outputs.release_tag }}' \
            --repo '${{ github.repository }}' --draft=false
          gh release view '${{ needs.plan.outputs.release_tag }}' \
            --repo '${{ github.repository }}' --json assets \
            --jq '"assets uploaded: \(.assets | length)"'

  notify:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    needs: [plan, publish]

    permissions:
      contents: read
      actions: read

    env:
      CONSUMER_REPO: drupflare/worker
      CONSUMER_WORKFLOW: interpreter.yml
      CONSUMER_VARIANTS: control85
      DISPATCH_EVENT: phasm-interpreter-published
      RELEASE_TAG: ${{ needs.plan.outputs.release_tag }}

    steps:
      - uses: actions/checkout@v7

      - name: Notify the Consumer of Each Published Interpreter
        env:
          GH_TOKEN: ${{ github.token }}
          CONSUMER_TOKEN: ${{ secrets.PHASM_TOKEN }}
        run: |
          if [ -z "$CONSUMER_TOKEN" ]; then
            echo "::error::PHASM_TOKEN is unset, so $CONSUMER_REPO cannot be notified" >&2
            exit 1
          fi
          gh api "repos/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}/artifacts?per_page=100" \
            > /tmp/artifacts.json

          notified=0
          for variant in $CONSUMER_VARIANTS; do
            rc="src/rc/${variant}.rc"
            # a consumed variant with no rc is a misconfiguration of CONSUMER_VARIANTS rather than
            # a property of this run, so it fails instead of being skipped like the case below
            if [ ! -f "$rc" ]; then
              echo "::error::CONSUMER_VARIANTS names $variant, which has no src/rc/${variant}.rc" >&2
              exit 1
            fi
            php_version="$(grep -m1 '^PHP_VERSION=' "$rc" | cut -d= -f2)"
            if [ -z "$php_version" ]; then
              echo "::error::$rc declares no PHP_VERSION" >&2
              exit 1
            fi
            artifact_id="$(jq -r --arg n "phasm-${variant}-${GITHUB_SHA}" \
              '[.artifacts[] | select(.name == $n)] | .[0].id // empty' /tmp/artifacts.json)"
            if [ -z "$artifact_id" ]; then
              # MISSING CANNOT MEAN FAILED HERE: publish needs build, and this job needs publish, so
              # a build that failed never reaches this line. A single-variant dispatch -- wasm64,
              # say -- is the normal way a run carries nothing the consumer wants
              echo "::notice::this run did not build $variant; nothing to notify for it"
              continue
            fi

            jq -nc --arg e "$DISPATCH_EVENT" --arg v "$variant" --arg p "$php_version" \
              --arg a "$artifact_id" --arg r "$GITHUB_RUN_ID" --arg c "$GITHUB_SHA" \
              --arg t "$RELEASE_TAG" \
              '{event_type: $e, client_payload: {variant: $v, php_version: $p, artifact_id: $a,
                run_id: $r, commit: $c, tag: $t}}' > /tmp/dispatch.json

            if GH_TOKEN="$CONSUMER_TOKEN" gh api --method POST \
              "repos/${CONSUMER_REPO}/dispatches" --input /tmp/dispatch.json; then
              echo "repository_dispatch accepted: $variant php$php_version artifact $artifact_id"
            else
              echo "::warning::repository_dispatch was refused; PHASM_TOKEN needs Contents: write"
              GH_TOKEN="$CONSUMER_TOKEN" gh workflow run "$CONSUMER_WORKFLOW" \
                --repo "$CONSUMER_REPO" \
                -f variant="$variant" \
                -f php_version="$php_version" \
                -f artifact_id="$artifact_id"
              echo "workflow_dispatch accepted: $variant php$php_version artifact $artifact_id"
            fi
            notified=$((notified + 1))
          done

          if [ "$notified" -eq 0 ]; then
            echo "::notice::this run built nothing $CONSUMER_REPO consumes; it stays on its pin"
            exit 0
          fi
          echo "notified $CONSUMER_REPO about $notified interpreter(s)"