feat(lsp): full editor tooling -- LSP server + PhpStorm plugin

.docker/jdk.Dockerfile

@@ -0,0 +1,12 @@
+FROM eclipse-temurin:21-jdk
+
+# X11 + font + GTK libs PhpStorm needs to render its Swing UI under
+# `./gradlew runIde`.  The base image ships headless deps only; without
+# these the JVM boots but dies on the first Toolkit.getDefaultToolkit()
+# call with "Can't connect to X11 window server" or a font-config error.
+RUN apt-get update \
+ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+        libxext6 libxrender1 libxi6 libxtst6 libxrandr2 libxcursor1 \
+        libxinerama1 libfontconfig1 libfreetype6 libgtk-3-0 \
+        fonts-dejavu-core \
+ && rm -rf /var/lib/apt/lists/*

.docker/php.Dockerfile

@@ -1,11 +1,29 @@
 FROM php:8.4-cli-alpine
 
+# Composer: copied from the official multi-arch image instead of curl-
+# piped install.  Reproducible across rebuilds and gets composer 2.x
+# without an interactive installer.  Both Makefile entry points
+# (`make test` and `make test/mutation`) shell out to `composer
+# install`, so this needs to be in PATH.
+COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer
+
 RUN apk add --update --no-cache linux-headers
 RUN apk add --no-cache \
     php84-dev \
-    build-base
+    build-base \
+    git \
+    unzip
 
+# Both coverage drivers are installed.  Xdebug runs as the dev-time
+# debugger; PCOV is used exclusively for Infection's coverage pass
+# (orders of magnitude less memory than Xdebug, which avoids the
+# host OOM-killer firing during the initial test run on tight
+# containers).  Infection auto-detects PCOV when it's loaded and
+# Xdebug is disabled via XDEBUG_MODE=off; the mutation Makefile
+# target does both.
 RUN pecl install \
     xdebug \
+    pcov \
     && docker-php-ext-enable \
-      xdebug
+      xdebug \
+      pcov

.github/workflows/ci-core.yml

@@ -0,0 +1,69 @@
+name: Core CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# Cancel superseded runs on the same branch (e.g. when a PR gets a new push)
+# so we don't pay for stale-commit mutation runs. The concurrency group is
+# keyed on the workflow name + ref, so this is per-workflow — the LSP CI
+# can run concurrently with this one without queueing.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  phpunit:
+    name: PHPUnit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP 8.4
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: dom, json, mbstring, tokenizer
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        uses: ramsey/composer-install@v3
+
+      - name: Run PHPUnit
+        run: make test/unit
+
+  infection:
+    name: Mutation testing
+    runs-on: ubuntu-latest
+    needs: phpunit
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP 8.4 (with Xdebug for coverage)
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: dom, json, mbstring, tokenizer
+          coverage: xdebug
+          tools: composer:v2
+
+      - name: Install dependencies
+        uses: ramsey/composer-install@v3
+
+      - name: Run Infection
+        # --min-covered-msi=93 fails CI if mutation score drops below 93 (current baseline: 94%).
+        # --threads=4 parallelizes mutant runs; safe on the 2-core ubuntu-latest runner.
+        run: make test/mutation
+
+      - name: Upload Infection report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: infection-report
+          path: |
+            var/infection.log
+            var/infection.html
+          if-no-files-found: ignore
+          retention-days: 14

.github/workflows/ci-lsp.yml

@@ -0,0 +1,94 @@
+name: LSP CI
+
+# PHPUnit runs on every PR + push to main as a hard gate.
+# Infection (mutation testing) is opt-in via workflow_dispatch -- its
+# resource envelope outgrew GitHub-hosted `ubuntu-latest` (~7 GB RAM)
+# once the suite passed ~150 tests, and the initial coverage run now
+# OOMs as SIGTERM 143 mid-stream.  Re-enable as a PR gate once the
+# job is reshaped to filter / batch the test set (see follow-up).
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Per-workflow concurrency. See ci-core.yml for the rationale.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  phpunit-lsp:
+    name: PHPUnit (LSP)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP 8.4
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: dom, json, mbstring, tokenizer
+          coverage: none
+          tools: composer:v2
+
+      # The LSP package has its own composer.json under tools/lsp/ with a
+      # path-repo pointing back at the repo root. Cache its deps separately
+      # from the core install so a core-only change doesn't bust the LSP cache.
+      - name: Install LSP dependencies
+        uses: ramsey/composer-install@v3
+        with:
+          working-directory: tools/lsp
+
+      - name: Run PHPUnit (LSP)
+        run: make -C tools/lsp test
+
+  infection-lsp:
+    name: Mutation testing (LSP)
+    # Gate: only run when explicitly requested via the Actions tab.  The
+    # 424-test suite plus per-mutation reruns overruns the GitHub-hosted
+    # runner's RAM, killing the initial coverage subprocess with SIGTERM
+    # 143.  PRs and merges to main get fast unambiguous signal from the
+    # PHPUnit job above; Infection scoring is opt-in until the job is
+    # reshaped to filter / batch the test set.
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    needs: phpunit-lsp
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP 8.4 (with PCOV for coverage)
+        # PCOV is preferred over Xdebug for Infection's initial run: an
+        # order of magnitude less memory under the same coverage scope,
+        # which keeps the runner well clear of the OOM-killer.  The
+        # Makefile target sets pcov.directory + XDEBUG_MODE=off so the
+        # driver choice is deterministic regardless of what else is loaded.
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: dom, json, mbstring, tokenizer
+          coverage: pcov
+          tools: composer:v2
+
+      - name: Install LSP dependencies
+        uses: ramsey/composer-install@v3
+        with:
+          working-directory: tools/lsp
+
+      - name: Run Infection (LSP)
+        # `make -C tools/lsp test/mutation` lazily downloads infection.phar
+        # 0.33.1 into tools/lsp/var/ (PHAR sidesteps the composer dep conflict
+        # with phpactor/language-server documented in tools/lsp/README.md).
+        # Runs with --min-covered-msi=93; current baseline is 94%.
+        run: make -C tools/lsp test/mutation
+
+      - name: Upload Infection report (LSP)
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: infection-lsp-report
+          path: |
+            tools/lsp/var/infection.log
+            tools/lsp/var/infection.html
+          if-no-files-found: ignore
+          retention-days: 14

.github/workflows/ci-phpstorm-plugin.yml

@@ -0,0 +1,141 @@
+name: PhpStorm Plugin CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# Per-workflow concurrency. See ci-core.yml for the rationale.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  gradle-build:
+    name: Gradle build (PhpStorm plugin)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # PHP + Composer are needed to build the bundled xphp-lsp.phar that
+      # processResources copies into the plugin jar at build time. Skipping
+      # this step would still produce a buildable plugin, but it would warn
+      # and ship without an embedded LSP -- defeating the zero-config
+      # install path we shipped in chunk 5.
+      - name: Setup PHP 8.4
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: dom, json, mbstring, tokenizer
+          coverage: none
+          tools: composer:v2
+
+      - name: Install LSP dependencies
+        uses: ramsey/composer-install@v3
+        with:
+          working-directory: tools/lsp
+
+      - name: Build xphp-lsp.phar
+        # Same target ci-lsp.yml's runtime relies on; the plugin's
+        # processResources picks this up from tools/lsp/var/.
+        run: make -C tools/lsp build/phar
+
+      - name: Setup JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+        with:
+          # Cache key is built from the wrapper version + build script
+          # hash, so this stays warm across PRs that don't touch the plugin
+          # build config.
+          gradle-home-cache-cleanup: true
+
+      - name: Build plugin (compile + test)
+        # `make build` from this directory is `./gradlew build`, which runs
+        # compileKotlin, test, and packages the plugin jar via the
+        # IntelliJ Platform Gradle Plugin's `composedJar` task.
+        run: make -C tools/phpstorm-plugin build
+
+      - name: Upload plugin jar
+        uses: actions/upload-artifact@v4
+        with:
+          name: xphp-phpstorm-plugin-jar
+          path: tools/phpstorm-plugin/build/libs/xphp-phpstorm-plugin-*.jar
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Upload test reports on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: phpstorm-plugin-test-reports
+          path: |
+            tools/phpstorm-plugin/build/reports/tests/
+            tools/phpstorm-plugin/build/test-results/
+          if-no-files-found: ignore
+          retention-days: 14
+
+  verify-plugin:
+    name: Plugin Verifier (PhpStorm plugin)
+    runs-on: ubuntu-latest
+    needs: gradle-build
+    steps:
+      - uses: actions/checkout@v4
+
+      # The verifier itself doesn't read the PHAR, but Gradle's build graph
+      # treats `processResources` as a prerequisite of `verifyPlugin` --
+      # and `processResources` declares xphp-lsp.phar as a required input
+      # via `inputs.file(...)` in build.gradle.kts.  Without the PHAR on
+      # disk, the build aborts before the verifier even runs:
+      #
+      #   property 'xphpLspPhar' specifies file '.../xphp-lsp.phar'
+      #   which doesn't exist.
+      #
+      # So we rebuild the same PHAR the gradle-build job built.  Both
+      # jobs sit on fresh runners; sharing via an artifact would also
+      # work but the PHAR rebuild is cheap (~2s) compared to the verifier
+      # downloading the IDE matrix that follows.
+      - name: Setup PHP 8.4
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: dom, json, mbstring, tokenizer
+          coverage: none
+          tools: composer:v2
+
+      - name: Install LSP dependencies
+        uses: ramsey/composer-install@v3
+        with:
+          working-directory: tools/lsp
+
+      - name: Build xphp-lsp.phar
+        run: make -C tools/lsp build/phar
+
+      - name: Setup JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Run IntelliJ Plugin Verifier
+        # `verifyPlugin` checks binary compatibility across the IDE matrix
+        # declared in build.gradle.kts `pluginVerification.ides {}` -- the
+        # `recommended()` set for since-build 261. A failure here means a
+        # platform API we depend on changed shape between IDE builds.
+        run: make -C tools/phpstorm-plugin verify
+
+      - name: Upload Plugin Verifier reports on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: phpstorm-plugin-verifier-reports
+          path: tools/phpstorm-plugin/build/reports/pluginVerifier/
+          if-no-files-found: ignore
+          retention-days: 14