phpunit.yml

name: PHPUnit Tests

on:
  push:
    branches: [ master, main, develop ]
  pull_request:
    branches: [ master, main, develop ]

jobs:
  test:
    name: PHPUnit Test Suite
    runs-on: ubuntu-26.04
    timeout-minutes: 25

    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: root
          MYSQL_DATABASE: phlix_test
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=5

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Setup PHP
        uses: shivammathur/setup-php@4424c9aab975b57bd706ee5a39c6b4334d6e4f60 # S304 SHA-pin v2.40.0 (published 2026-10-08 — adds ubuntu-26.04 support), was floating @v2; bump via refs/tags/v2 on shivammathur/setup-php
        with:
          php-version: '8.3'
          # S314 — the canonical contract from
          # scripts/required-php-extensions.php (mirrored by composer.json's `require`
          # and `config.platform`), plus this job's non-required extras. Needed in full
          # because `config.platform-check: true` aborts every `vendor/autoload.php`
          # include when one is missing.
          extensions: ctype, curl, dom, exif, fileinfo, filter, gd, hash, iconv, json, ldap, libxml, mbstring, openssl, pcntl, pdo, pdo_mysql, posix, random, simplexml, sockets, sodium, zip, zlib, mysql, swoole, pcov
          # PCOV is dramatically faster than Xdebug for line-coverage, which keeps
          # the full ~3700-test suite comfortably inside timeout-minutes.
          coverage: pcov

      - name: Build and enable php-uv
        # S309 — this clone is PINNED to an immutable commit: the SAME full SHA the
        # production base image compiles (docker/Dockerfile.base, PHP_UV_REF). An
        # unpinned --depth=1 HEAD here was a supply-chain surface, and a third-party
        # TLS hiccup reddened an unrelated PR (#666). Do NOT float it back to HEAD:
        # --depth=1 keeps a single commit, so it can only ever track whatever the tip
        # is at fetch time — a full clone is what makes the fixed SHA durably reachable.
        run: |
          sudo apt-get update && sudo apt-get install -y --no-install-recommends libuv1-dev
          git clone https://github.com/bwoebi/php-uv.git /tmp/php-uv
          cd /tmp/php-uv
          git checkout --quiet --detach 670a609efc36c9043be37bae4126f06ed30fde21
          test "$(git rev-parse HEAD)" = 670a609efc36c9043be37bae4126f06ed30fde21
          phpize && ./configure --with-uv && make -j"$(nproc)" && sudo make install
          echo "extension=uv.so" | sudo tee "$(php-config --ini-dir 2>/dev/null || php -i | awk -F'=> ' '/Scan this dir/{print $2}')/zz-uv.ini"

      - name: Verify swoole + uv loaded
        run: php -m | grep -iE '^(swoole|uv)$'

      - name: Verify ffmpeg (distro binary; BtbN pin retired)
        # Post-fix reality: FfmpegRunner's mjpeg/image2 outputs (single thumbnail,
        # thumbnail batch, trickplay sprite, BIF frames) now carry
        # `-strict unofficial`, so the S-F19 partial-success contract holds on
        # every ffmpeg era and the distro binary needs no substitution.
        # History: ubuntu-26.04's apt ffmpeg is 8.x, whose mjpeg encoder hard-
        # aborts an EMPTY output flush (out-of-range `-ss`) with
        # "Non full-range YUV is non-standard" → exit 234, killing the whole
        # batch — where 6.1/7.0 (the ubuntu-24.04 image's era, every historical
        # green run) treated it as a warning and exited 0. The interim migration
        # workaround pinned a BtbN n6.1.3 static build over /usr/bin; this lane's
        # product fix (src/Media/Transcoding/FfmpegRunner.php
        # MJPEG_STRICTNESS_ARGS, argv-shape pins in
        # tests/Unit/Media/Transcoding/FfmpegRunnerThumbnailBatchTest.php, and
        # real-binary before/after measured 2026-10-08 on BtbN master N-127252,
        # 6.1.3 and apt 6.1.1: pre-fix 8.x exit 234 → post-fix exit 0 with
        # reachable frames written) makes that pin obsolete. Historical footnote:
        # johnvansickle 7.0.2-static was rejected en route — its bundled ffprobe
        # SIGSEGVs on plain MPEG-TS probes.
        # The step stays fail-loud: presence + version banner before the suite,
        # so a future image that drops ffmpeg reds here instead of silently
        # skipping FfmpegThumbnailBatchTest's real-binary legs.
        run: |
          set -euo pipefail
          if ! command -v ffmpeg >/dev/null; then
            sudo apt-get update
            sudo apt-get install -y --no-install-recommends ffmpeg
          fi
          test -x "$(command -v ffmpeg)"
          test -x "$(command -v ffprobe)"
          ffmpeg -version | head -1
          ffprobe -version | head -1

      - name: Setup Node.js
        # S305. `tests/Support/Browser/hls-playback-probe.mjs` drives headless Chrome
        # over the DevTools protocol using node's BUILT-IN global WebSocket (no ws, no
        # puppeteer, no playwright), which requires node >= 22. Pinned to the same major
        # as web-ui.yml so the two jobs cannot diverge. This is a tool-cache install, not
        # a network clone of an unpinned third-party repo (cf. S309).
        uses: actions/setup-node@v6
        with:
          node-version: '24'

      - name: Get Composer cache directory
        id: composer-cache
        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT

      - name: Cache Composer dependencies
        uses: actions/cache@v5
        with:
          path: ${{ steps.composer-cache.outputs.dir }}
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-composer-

      - name: Install Composer dependencies
        run: composer install --no-interaction --prefer-dist

      - name: Assert required PHP extensions loaded (S304)
        # S304 — naming is NOT a gate: setup-php's fail_fast defaults to false, so an
        # extension it cannot install leaves a red cross in the log and a GREEN step
        # (plan_updates.md:6258). This executed assertion consumes the S314 contract
        # (scripts/required-php-extensions.php — one list, never re-derived) and fails
        # the job, naming any absent extension — including the security-critical sodium
        # (HubJwtValidator, SodiumTokenCipher) and hash (SignedUrl, JwtHandler) that
        # this job's suite reaches through vendor/autoload.php. plan_updates.md:6260.
        run: php scripts/assert-php-extensions.php

      - name: Install the browser E2E prerequisites (S305)
        # Puts hls.js on disk and REFUSES to continue without a browser, node >= 22 and
        # ffmpeg. Everything about hls.js — version, URL and sha512 — is read from
        # web-ui/package-lock.json and the downloaded bytes are verified against that
        # hash before extraction, so nothing here is fetched at an unpinned ref (S309).
        #
        # Before this step existed, the three Fmp4HlsPlaybackE2ETest cases skipped on
        # EVERY CI run because hls.js was absent — `Skipped: 6` against master's 3,
        # measured on PR #664 (run 31263130044) — and the job stayed green, because a
        # skipped test reads as a pass.
        #
        # It runs after `composer install` because it uses the autoloader to reach
        # tests/Support/Browser/BrowserProbeEnvironment.php — the single place that says
        # where hls.js/chrome/node have to be, shared with the test that needs them.
        #
        # Do NOT add `continue-on-error`, `|| true`, an `if:`, or any of the script's
        # `--lock/--dest/--tarball/--skip-binaries` options (they exist only for the
        # offline unit test). tests/Unit/Support/BrowserE2EGateTest.php fails on each.
        run: php scripts/ci-browser-e2e-prereqs.php

      - name: Apply database migrations
        # Apply every migration to the MySQL service DB so real-DB Integration
        # tests run against the actual schema (table defs, foreign keys, bound
        # LIMIT queries) instead of a hand-rolled simulation. Idempotent: the
        # runner downgrades duplicate-column/key errors to notes.
        #
        # ⚠ S159 — this step is a GATE. Until S159 run-migrations.php printed
        # "  Warning: <error>" for a genuinely failing migration and then exited
        # 0 regardless, so this step could not go red and a broken migration
        # reached master invisibly. It now exits 1 when the runner recorded a
        # non-idempotent error. Do NOT "fix" a red here with `|| true` or
        # `continue-on-error` — read the Warning lines and fix the migration.
        #
        # An "already applied" replay is still exit 0, so a re-run is not a
        # failure — but only for a CLOSED LIST of four MySQL error numbers:
        # 1050 table exists, 1060 duplicate column, 1061 duplicate key name,
        # 1091 can't drop. A seed `INSERT` replayed (1062), `ADD PRIMARY KEY`
        # replayed (1068) and a duplicate FOREIGN KEY / CHECK constraint NAME
        # (1826 / 3822) are GENUINE failures on purpose, so a new migration must
        # use `INSERT IGNORE` / guard its `ADD PRIMARY KEY` / guard its
        # `ADD CONSTRAINT` rather than expect the squelch to cover it.
        # 1826/3822 were considered for the set and REJECTED: those names are
        # unique per SCHEMA, not per table, so the collision can be with another
        # table entirely and the failing statement may have created nothing.
        # See MigrationRunner::IDEMPOTENT_ERROR_CODES.
        #
        # Both directions are asserted by
        # tests/Integration/Common/Database/MigrationFailureVisibilityTest.php,
        # which runs in the Integration suite step below.
        env:
          DB_HOST: 127.0.0.1
          DB_PORT: '3306'
          DB_DATABASE: phlix_test
          DB_USER: root
          DB_PASSWORD: root
        run: php scripts/run-migrations.php

      # ── S457 — the suite now runs in three shapes, not one process ──────────
      # Unit runs under paraunit at parallel 8 (it touches no DB); Integration runs
      # under paraunit at parallel 8 against EIGHT CLONED schemas (phlix_test_w1..w8,
      # claimed per-worker by tests/bootstrap.php — some tests assert on GLOBAL row
      # counts, so two workers on one schema corrupt each other, S47-class); E2E runs
      # SERIALLY as the tail because parallel E2E contends for the hardware encoder
      # and HwaccelE2ETest flakes under load. Coverage is collected per suite as
      # serialized php-code-coverage objects and merged into coverage.xml by
      # scripts/parallel/merge-coverage.php (PHPUnit's own Clover writer — exact
      # metrics, byte-compatible). The JUnit evidence is collected per child
      # (.phpunit-junit/junit-<chunk>.xml via the __PHLIX_WORKER__ seam in
      # scripts/parallel/php) and merged into junit.xml, so every consumer of the old
      # single-run artifacts (the S305 gate, the coverage threshold, the S120 escape
      # check, codecov/codacy uploads) reads the same filenames with the same
      # semantics. tests/Unit/Support/ParallelTestWiringTest.php pins this whole shape.
      #
      # ⚠ The literal `vendor/bin/phpunit` may appear exactly TWICE in this file (this
      # job's E2E tail + `Run Server-specific tests`) — SkippedTestNameReportingTest's
      # invocation-site census counts them and scripts/skipped-test-names.sh documents
      # "phpunit.yml twice". run-suite.sh invokes `vendor/bin/paraunit`, which is not
      # a phpunit invocation the census tracks by design.

      - name: Clone shard databases for parallel Integration runs
        # mysqldump-pipes the freshly migrated phlix_test into phlix_test_w1..w8.
        # scripts/parallel/run-suite.sh refuses Integration unless shard count >=
        # parallel count; keep the literal 8s in this step and the next two in step.
        env:
          PHLIX_TEST_DB_SHARDS: '8'
          DB_HOST: 127.0.0.1
          DB_PORT: '3306'
          DB_DATABASE: phlix_test
          DB_USER: root
          DB_PASSWORD: root
        run: bash scripts/parallel-test-db.sh create

      - name: Run Unit suite (paraunit, parallel 8)
        # DB-free by design; the wrapper enforces per-worker TMPDIR isolation (the
        # S439 zero-residue census is per-worker inside each private TMPDIR — the
        # shared-TMPDIR shape WOULD leave cross-worker residue and the census cannot
        # see another worker's directory, which is the honest caveat of this seam).
        # --coverage writes the merged coverage OBJECT to coverage-unit.covobj.
        run: bash scripts/parallel/run-suite.sh Unit 8 --coverage coverage-unit.covobj

      - name: Run Integration suite (paraunit, parallel 8 on 8 cloned schemas)
        # Each worker claims one phlix_test_wK via tests/bootstrap.php's flock slots.
        run: bash scripts/parallel/run-suite.sh Integration 8 8 --coverage coverage-integration.covobj

      - name: Run E2E suite (serial tail)
        # Serial on purpose (hardware-encoder contention, see above). Carries the
        # Serialized suite too: the multicast-receive classes (Mdns/Ssdp MulticastJoin
        # + SsdpMSearchListener) are excluded from the parallel Unit lane in
        # phpunit-parallel.xml because their negative-arm sockets receive under 8-way
        # multicast contention on the runner (CI runs 1 and 2 evidence), and pass in any
        # serial lane — this one. Serialized membership lives in phpunit-parallel.xml, so
        # adding a class there needs no edit to this command.
        # Loads phpunit-parallel.xml because it is the report-target-free copy of the config:
        # the CLI below owns coverage-e2e.covobj and junit-e2e.xml explicitly, exactly as
        # S305 owned junit.xml before this step existed.
        #
        # ⚠ S305 — `--log-junit` is NOT optional decoration. The merge step below folds
        # it into junit.xml and the "S305 browser-E2E gate" step reads junit.xml to
        # prove the headless-browser cases executed rather than skipped. Removing the
        # flag makes that gate fail loudly (it does not degrade to a pass), and
        # tests/Unit/Support/BrowserE2EGateTest.php fails on the edit as well.
        #
        # S345 — skipped-test NAMES come from `displayDetailsOnSkippedTests="true"` on
        # the config root (carried by phpunit-parallel.xml too), not from a CLI flag.
        # Compare NAME SETS via scripts/skipped-test-names.sh over `gh run view --log`,
        # never the `Skipped: N` count — the count cannot tell "a test started skipping"
        # from "a skipped test became a failure" from "a test disappeared".
        run: ./vendor/bin/phpunit --configuration=phpunit-parallel.xml --testsuite E2E,Serialized --coverage-php coverage-e2e.covobj --log-junit .phpunit-junit/junit-e2e.xml

      - name: Merge parallel coverage and JUnit artifacts
        # Produces the two artifacts every downstream step already expects:
        # coverage.xml (Clover, union of the three suites) and junit.xml (every
        # testcase from every worker + the E2E tail, counted once).
        run: |
          php scripts/parallel/merge-coverage.php coverage.xml coverage-unit.covobj coverage-integration.covobj coverage-e2e.covobj
          php scripts/parallel/merge-junit.php .phpunit-junit junit.xml

      - name: S305 browser-E2E gate
        # ADDITIVE gate. It reads the JUnit report and fails when any of the three
        # Fmp4HlsPlaybackE2ETest cases is ABSENT, SKIPPED, or executed with zero
        # assertions — each by exact class+name, never by substring. It prints the total
        # test-case count and the whole-run skip census so a run that inspected nothing
        # cannot look like a clean pass.
        #
        # `if: always()` for the same reason the S120 guard has it, and one more: on a
        # RED run the most valuable thing this gate can say is "yes, the browser cases
        # ran, and they are what failed". `always()` is a condition that cannot evaluate
        # false, so it is not the "gate that passes by not running" shape an ordinary
        # `if:` would be — and the test named above pins it to exactly that expression.
        #
        # Do NOT delete this step, add `continue-on-error`, or drop `if: always()`.
        if: always()
        run: php scripts/assert-browser-e2e-ran.php junit.xml

      - name: S120 assertion-escape guard
        # ADDITIVE step — it reads the report the PHPUnit extension registered in
        # phpunit.xml leaves behind when a test contained an assertion failure that did
        # not decide the test's outcome (an ExpectationFailedException swallowed between
        # the assertion and PHPUnit — by catch (\Throwable), catch (\Exception) or
        # catch (\RuntimeException), or by a `return` inside a `finally`).
        # No report file => exit 0. `if: always()` so it still reports when the suite
        # itself failed, which is exactly when a degraded message hurts most.
        #
        # Do NOT delete this step, add continue-on-error to it, or drop `if: always()`.
        # tests/Unit/Support/AssertionEscapeGuardWiringTest.php parses this file and
        # fails on each of those three edits, and on the removal of the <bootstrap>
        # registration in phpunit.xml that feeds it.
        if: always()
        run: php scripts/assertion-escape-check.php

      - name: Assert the coverage report and its parser exist
        # ADDITIVE guard, and the direct analogue of "Assert Psalm is actually
        # installed" in coding-standards.yml (S146). It exists because the
        # threshold step below spent the life of this repo reporting success
        # while measuring nothing: it shelled out to `xmllint`, which is NOT
        # installed on ubuntu-24.04 (then-latest), hid the resulting "command not found"
        # behind `2>/dev/null`, substituted `0` via `|| echo "0"`, and then read
        # that `0` as "empty report — skip" and exited 0.
        #
        # Evidence (do not re-litigate): Ubuntu 24.04.4 LTS, image provisioner
        # 20260707.563 — `libxml2-utils` is absent from that image's
        # installed-apt-packages manifest. And in run 30354212368 the step body
        # started at 11:21:28.1580647 and printed its WARNING at
        # 11:21:28.1685980: 10.5 ms for two supposed parses of a ~4 MB Clover
        # report. Two real xmllint parses of that file measure 461 ms; two
        # command-not-found failures measure 5 ms.
        #
        # A missing tool must fail loudly rather than degrade into a no-op.
        run: |
          if [ ! -f coverage.xml ]; then
            echo "::error::coverage.xml was not produced by the 'Merge parallel coverage and JUnit artifacts' step. The coverage gate cannot run — fix the test run, do not skip the gate."
            exit 1
          fi
          if [ ! -s coverage.xml ]; then
            echo "::error::coverage.xml exists but is empty (0 bytes)."
            exit 1
          fi
          if ! php -r 'exit(class_exists("DOMDocument") && class_exists("DOMXPath") ? 0 : 1);'; then
            echo "::error::PHP is missing ext-dom (DOMDocument/DOMXPath). Add 'dom' to the setup-php extensions list — do not re-add a conditional that skips the coverage gate when its parser is missing (S146)."
            exit 1
          fi
          echo "coverage.xml present ($(wc -c < coverage.xml) bytes); PHP XML parser available."

      - name: Check minimum coverage threshold
        # The threshold logic is unchanged in intent — a MIN_COVERAGE floor over
        # statement coverage computed from Clover's
        # `statements`/`coveredstatements` on /coverage/project/metrics. The
        # XPath was never the problem and is preserved verbatim inside the
        # script; the Cobertura-style `line-rate` attribute still does not exist
        # in PHPUnit's output, so do not reach for it.
        #
        # What changed is WHO parses. scripts/coverage-threshold-check.php reads
        # the report with ext-dom and does the arithmetic in PHP, which removes
        # both external-tool dependencies this step used to carry: `xmllint`
        # (proven absent above) and `bc` (also absent from the Ubuntu 24.04
        # manifest — never observed failing only because the xmllint line
        # short-circuited three lines above it).
        #
        # Every failure mode in that script is exit 1: missing report, missing
        # parser, unparseable XML, missing/non-numeric metric, zero statements.
        # There is no `exit 0` fallback and no `|| echo "0"`. Do not add one —
        # a gate that cannot measure must not report success.
        env:
          MIN_COVERAGE: '40'
        run: php scripts/coverage-threshold-check.php coverage.xml

      - name: Upload coverage to Codecov
        if: env.CODECOV_TOKEN != ''
        env:
          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
        uses: codecov/codecov-action@v6
        with:
          files: ./coverage.xml
          # Non-blocking: Codecov upload is informational. A repo not
          # yet activated in the Codecov UI returns "Repository not
          # found" — that should not fail the test workflow. Activate
          # at https://app.codecov.io to flip this on later.
          fail_ci_if_error: false
          token: ${{ secrets.CODECOV_TOKEN }}

      - name: Upload coverage to Codacy
        uses: codacy/codacy-coverage-reporter-action@v1
        # Non-blocking for the same reason as the Codecov step above: a missing
        # or expired token, or a repo not yet activated in the Codacy UI, must
        # not fail the test workflow. This action has no fail_ci_if_error input,
        # so continue-on-error is how that guarantee is expressed.
        # NOTE: continue-on-error makes a FAILED step report "success" — to check
        # whether an upload actually happened, read the step log for
        # "Coverage data uploaded successfully", not the step conclusion.
        continue-on-error: true
        with:
          api-token: ${{ secrets.CODACY_API_TOKEN }}
          coverage-reports: ./coverage.xml

  test-server:
    name: Server Component Tests
    runs-on: ubuntu-26.04

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Setup PHP
        uses: shivammathur/setup-php@4424c9aab975b57bd706ee5a39c6b4334d6e4f60 # S304 SHA-pin v2.40.0 (published 2026-10-08 — adds ubuntu-26.04 support), was floating @v2; bump via refs/tags/v2 on shivammathur/setup-php
        with:
          php-version: '8.3'
          # S314 — the canonical contract from
          # scripts/required-php-extensions.php (mirrored by composer.json's `require`
          # and `config.platform`), plus this job's non-required extras. Needed in full
          # because `config.platform-check: true` aborts every `vendor/autoload.php`
          # include when one is missing.
          extensions: ctype, curl, dom, exif, fileinfo, filter, gd, hash, iconv, json, ldap, libxml, mbstring, openssl, pcntl, pdo, pdo_mysql, posix, random, simplexml, sockets, sodium, zip, zlib, swoole, pcov
          # phpunit.xml sets failOnWarning="true"; with no coverage driver the
          # runner emits "No code coverage driver available", which trips that
          # flag and fails the job. PCOV is cheap, so enable it here too.
          coverage: pcov

      - name: Build and enable php-uv
        # S309 — this clone is PINNED to an immutable commit: the SAME full SHA the
        # production base image compiles (docker/Dockerfile.base, PHP_UV_REF). An
        # unpinned --depth=1 HEAD here was a supply-chain surface, and a third-party
        # TLS hiccup reddened an unrelated PR (#666). Do NOT float it back to HEAD:
        # --depth=1 keeps a single commit, so it can only ever track whatever the tip
        # is at fetch time — a full clone is what makes the fixed SHA durably reachable.
        run: |
          sudo apt-get update && sudo apt-get install -y --no-install-recommends libuv1-dev
          git clone https://github.com/bwoebi/php-uv.git /tmp/php-uv
          cd /tmp/php-uv
          git checkout --quiet --detach 670a609efc36c9043be37bae4126f06ed30fde21
          test "$(git rev-parse HEAD)" = 670a609efc36c9043be37bae4126f06ed30fde21
          phpize && ./configure --with-uv && make -j"$(nproc)" && sudo make install
          echo "extension=uv.so" | sudo tee "$(php-config --ini-dir 2>/dev/null || php -i | awk -F'=> ' '/Scan this dir/{print $2}')/zz-uv.ini"

      - name: Verify swoole + uv loaded
        run: php -m | grep -iE '^(swoole|uv)$'

      - name: Install Composer dependencies
        run: composer install --no-interaction --prefer-dist

      - name: Assert required PHP extensions loaded (S304)
        # S304 — executed assertion, not the `extensions:` line, is the gate (setup-php
        # fail_fast defaults false → a failed install is still a green step). Consumes the
        # S314 contract scripts/required-php-extensions.php; fails naming any absent ext
        # (incl. sodium/hash). This job boots server source via tests/Unit/Server/.
        # plan_updates.md:6258-6260.
        run: php scripts/assert-php-extensions.php

      - name: Run Server-specific tests
        run: ./vendor/bin/phpunit tests/Unit/Server/

      - name: Assert PHPCS is actually installed
        # S183. The "Check code style" step below used to be the whole gate, wrapped
        # in `if [ -f vendor/bin/phpcs ]`. That is the shape S146 removed from
        # coding-standards.yml's Psalm, PHPCS and Security-Audit steps — and this copy
        # survived, in a DIFFERENT workflow file, for the same reason all the others
        # did: the binary exists today, so the guard looks harmless.
        #
        # It is not. When `vendor/` is partial — an interrupted `composer install`, a
        # cache restore that lands incompletely, the dependency being dropped from
        # require-dev — the condition goes false, the body never runs, the step exits
        # 0, and "Server Component Tests" reports GREEN having sniffed zero files.
        # Nothing in the log says so. GitHub scores that identically to a real pass,
        # and this repo has no branch protection to notice the difference.
        #
        # The absence path is the one that matters, so it is tested by execution, not
        # by reading: tests/Unit/Support/WorkflowToolGateTest.php extracts THIS step's
        # `run` body out of this file and runs it under bash in a scratch directory —
        # once with no vendor/bin/phpcs (must exit non-zero and print `::error::`) and
        # once with a stub binary present (must exit 0). Re-adding an
        # `if [ -f ... ]` guard anywhere in this repo's workflows reds that test too.
        run: |
          if [ ! -f vendor/bin/phpcs ]; then
            echo "::error::vendor/bin/phpcs is missing. squizlabs/php_codesniffer must stay in composer.json require-dev — do not re-add an 'if [ -f ... ]' guard around the style step (S146, S183)."
            exit 1
          fi
          ./vendor/bin/phpcs --version

      - name: Check code style
        # Unconditional on purpose — see the assertion step above. Do NOT add `-n`
        # (S109: it deletes warnings from the report rather than making them
        # non-blocking), `|| true`, `continue-on-error:` or an `if:`.
        run: ./vendor/bin/phpcs --standard=PSR12 src/Server/

  assertion-escape-probe:
    name: Assertion-Escape Prober (S180)
    runs-on: ubuntu-26.04
    # ⚠ NOT because the prober is slow. That was the assumption S180 started from and
    # it is FALSE, measured: the full 22-site bulk probe takes **7.2 s** wall clock on
    # the dev box (`/usr/bin/time` → REAL=7.24 s), because every probed site is a fast
    # mocked-DB test. The one genuinely slow site (~16 s: it runs a whole coroutine
    # concurrency file) is the one the baseline excludes. Do not re-justify this job on
    # runtime.
    #
    # The real reasons, in order:
    #  1. ATTRIBUTION. A named check that can only mean "an assertion cannot fail its
    #     test" is legible; the same finding buried in the 11-step "PHPUnit Test
    #     Suite" job is not. The runtime half of S120's guard already lives there.
    #  2. The prober SPLICES tripwires into tracked test files and restores them. That
    #     belongs nowhere near the job that produces the coverage artifact.
    #  3. Its own timeout, so it cannot be starved by the `test` job's 25 minutes.
    timeout-minutes: 20

    # ⚠ THERE IS DELIBERATELY NO `if:` ON THIS JOB OR ON ANY OF ITS STEPS.
    # A skipped GitHub job reports conclusion `skipped`, and `skipped` COUNTS AS
    # SUCCESS for a status check — so an `if:` here would be a gate that passes by
    # not running, which is precisely the defect S120 exists to catch, one level up.
    # tests/Unit/Support/AssertionEscapeProbeGateTest.php asserts the absence of an
    # `if:` on BOTH this job and its probe step, and kills six more neutering edits.

    services:
      # Copied from the `test` job above, VERBATIM.
      #
      # MEASURED FIRST, so the reason is not a guess: no site this job probes needs
      # MySQL today — all 22 use a mocked Workerman\MySQL\Connection, and the probe
      # produced the identical 19 GATES / 3 NOT-REACHED census with a live
      # mysql:8.0.46 and with no database at all. The service is here for the FUTURE
      # case, and it is not hypothetical: a site whose test needs MySQL self-skips
      # without one, so its tripwire never executes, so it probes NOT-REACHED — and
      # the S180 baseline reconciliation would then red this job over an environment
      # difference instead of over anything in the diff. Matching the `test` job's
      # environment is what keeps a verdict here meaning the same thing as a verdict
      # there.
      #
      # The ONE site that is genuinely unsafe to probe is excluded BY NAME in
      # tests/Support/AssertionEscape/probe-baseline.json, with its measurement in the
      # `reason` field. That is how the known flake is kept out — NOT by withholding
      # the database, which would only have hidden it behind a second defect.
      mysql:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: root
          MYSQL_DATABASE: phlix_test
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=5

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Setup PHP
        uses: shivammathur/setup-php@4424c9aab975b57bd706ee5a39c6b4334d6e4f60 # S304 SHA-pin v2.40.0 (published 2026-10-08 — adds ubuntu-26.04 support), was floating @v2; bump via refs/tags/v2 on shivammathur/setup-php
        with:
          php-version: '8.3'
          # Same list as the `test` job. pcov is kept even though every probe run
          # passes --no-coverage: phpunit.xml configures a <coverage> section, and
          # failOnWarning="true" turns "No code coverage driver available" into a
          # failed run. php-uv is deliberately NOT built here (it costs minutes and
          # nothing the prober runs needs it); if a probed test ever does, this job
          # will say so loudly rather than skip.
          # S314 — the canonical contract from
          # scripts/required-php-extensions.php (mirrored by composer.json's `require`
          # and `config.platform`), plus this job's non-required extras. Needed in full
          # because `config.platform-check: true` aborts every `vendor/autoload.php`
          # include when one is missing.
          extensions: ctype, curl, dom, exif, fileinfo, filter, gd, hash, iconv, json, ldap, libxml, mbstring, openssl, pcntl, pdo, pdo_mysql, posix, random, simplexml, sockets, sodium, zip, zlib, mysql, swoole, pcov
          coverage: pcov

      - name: Install Composer dependencies
        run: composer install --no-interaction --prefer-dist

      - name: Assert required PHP extensions loaded (S304)
        # S304 — executed assertion, not the `extensions:` line, is the gate (setup-php
        # fail_fast defaults false → a failed install is still a green step). The probe
        # audit requires vendor/autoload.php, so this job runs server source. Consumes the
        # S314 contract; fails naming any absent ext (incl. sodium/hash). plan_updates.md:6258-6260.
        run: php scripts/assert-php-extensions.php

      - name: Apply database migrations
        env:
          DB_HOST: 127.0.0.1
          DB_PORT: '3306'
          DB_DATABASE: phlix_test
          DB_USER: root
          DB_PASSWORD: root
        run: php scripts/run-migrations.php

      - name: Probe every assertion-bearing closure
        # S180. THE STATIC HALF of S120's guard. It plants a named tripwire before the
        # first assertion in each assertion-bearing closure under tests/, runs the
        # owning test, and reads the verdict off the run — so it decides, by
        # execution, whether that assertion can fail its test at all.
        #
        # It catches what the RUNTIME guard cannot: an assertion failure that never
        # reaches Assert::assertThat() emits no event, so Assert::fail(), mock
        # parameter/invocation rules and markTestSkipped() are invisible to it. The
        # live escape found on 2026-08-02
        # (tests/Unit/Playlists/SmartPlaylistRefreshSubscriberTest.php) was exactly
        # that shape: this prober reported it DEGRADED while the runtime guard
        # reported exit 0, silent.
        #
        # ⚠ ADDITIVE, NOT A REPLACEMENT. The enumeration is LEXICAL: 186 closures
        # reach an assertion only through a HELPER and carry no assert* token, so this
        # job sees none of them. The runtime guard (the "S120 assertion-escape guard"
        # step in the `test` job) covers those. A green here does NOT mean the suite
        # is free of swallowed assertions — do not delete either half because the
        # other one is green.
        #
        # Do NOT add `if:`, `continue-on-error:` or `|| true` to this step, and do not
        # narrow it to a subset of sites. The undecided (NOT-REACHED) census is
        # reconciled against tests/Support/AssertionEscape/probe-baseline.json in BOTH
        # directions, so the honest way to change what this job accepts is to edit that
        # JSON in a reviewable diff, with a reason.
        run: php scripts/assertion-escape-audit.php --probe