MVP: basic functionality to support xphp v0.1.0

.docker/jdk.Dockerfile

@@ -0,0 +1,20 @@
+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 \
+        ibxrender1 \
+        ibxi6 \
+        ibxtst6 \
+        ibxrandr2 \
+        ibxcursor1 \
+        libxinerama1 \
+        ibfontconfig1 \
+        ibfreetype6 \
+        ibgtk-3-0 \
+        fonts-dejavu-core \
+    && rm -rf /var/lib/apt/lists/*

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

@@ -0,0 +1,100 @@
+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
+      - uses: gradle/actions/wrapper-validation@v6
+      - 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.
+        #
+        # The build's downloadLspPhar task fetches the xphp LSP binary from
+        # `xphpLspPharUrl` in gradle.properties and bundles it at
+        # bin/xphp-lsp.phar.  The build FAILS if that property is unset/empty
+        # -- by design, so a jar never ships without an embedded LSP.
+        run: make build
+
+      - name: Upload plugin jar
+        uses: actions/upload-artifact@v4
+        with:
+          name: xphp-phpstorm-plugin-jar
+          path: 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: |
+            build/reports/tests/
+            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
+
+      - 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.
+        #
+        # The verifier itself doesn't read the PHAR, but Gradle's build graph
+        # treats `processResources` (which downloads + bundles the PHAR from
+        # `xphpLspPharUrl` in gradle.properties) as a prerequisite of
+        # `verifyPlugin`, so the property must be set or the build aborts
+        # before the verifier runs.
+        run: make verify
+
+      - name: Upload Plugin Verifier reports on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: phpstorm-plugin-verifier-reports
+          path: build/reports/pluginVerifier/
+          if-no-files-found: ignore
+          retention-days: 14

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

@@ -0,0 +1,109 @@
+name: PhpStorm Plugin Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  # Required to create the Release and upload assets to it.  Read-only
+  # checkout would otherwise fail when softprops/action-gh-release tries
+  # to POST to the releases API.
+  contents: write
+
+# Don't cancel a release mid-upload -- a half-uploaded asset is worse
+# than a duplicate run.  Concurrency group keys on the tag, so two tags
+# released back-to-back don't collide.
+concurrency:
+  group: release-phpstorm-plugin-${{ github.event.inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Build + publish PhpStorm plugin
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve tag + version
+        id: tag
+        # On a push:tags trigger, GITHUB_REF is `refs/tags/v0.1.0`.
+        # On workflow_dispatch, the user-supplied input takes over.
+        # `version` is the tag minus the leading `v` so it threads
+        # straight into Gradle's pluginVersion (which has no v prefix).
+        run: |
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            tag="${{ github.event.inputs.tag }}"
+          else
+            tag="${GITHUB_REF#refs/tags/}"
+          fi
+          if [[ ! "$tag" =~ ^v[0-9] ]]; then
+            echo "::error::tag '$tag' must start with 'v' followed by a digit (e.g. v0.1.0)"
+            exit 1
+          fi
+          version="${tag#v}"
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout at tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.tag.outputs.tag }}
+          fetch-depth: 1
+
+      - 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: Build plugin zip with tag-derived version
+        # -PpluginVersion overrides the gradle.properties default, so:
+        #   - the produced zip is xphp-phpstorm-plugin-<version>.zip
+        #   - plugin.xml's <version> matches the git tag
+        #   - the JetBrains Marketplace update channel (if ever published)
+        #     reads the tag-driven version, not a stale 0.1.0
+        #
+        # downloadLspPhar fetches the xphp LSP binary from `xphpLspPharUrl` in
+        # gradle.properties and bundles it at bin/xphp-lsp.phar.  buildPlugin
+        # FAILS if that property is unset/empty -- a release zip never ships
+        # without an embedded LSP.
+        run: |
+          ./gradlew 
+            buildPlugin \
+            -PpluginVersion=${{ steps.tag.outputs.version }}
+
+      - name: Locate built zip
+        id: zip
+        # `ls` produces a single match because Gradle emits exactly one
+        # zip per buildPlugin run.  Fail loudly if the path doesn't
+        # match what we expected -- catches a Gradle config drift early.
+        run: |
+          path=$(ls build/distributions/xphp-phpstorm-plugin-${{ steps.tag.outputs.version }}.zip)
+          if [[ ! -f "$path" ]]; then
+            echo "::error::zip not found at expected path"
+            ls -la build/distributions/ || true
+            exit 1
+          fi
+          echo "path=$path" >> "$GITHUB_OUTPUT"
+          echo "name=$(basename "$path")" >> "$GITHUB_OUTPUT"
+
+      - name: Create release and upload zip
+        # softprops/action-gh-release creates the GitHub Release if it
+        # doesn't exist yet (push:tags case) and updates it idempotently
+        # on workflow_dispatch re-runs.  `files:` uploads the zip as a
+        # release asset -- the resulting download URL is:
+        #   https://github.com/<owner>/<repo>/releases/download/<tag>/<asset>
+        # i.e. the tag appears in the URL path AND inside the asset
+        # filename (`...-<version>.zip`), so the version is impossible
+        # to miss from either direction.
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.tag.outputs.tag }}
+          name: ${{ steps.tag.outputs.tag }}
+          draft: false
+          prerelease: false
+          files: ${{ steps.zip.outputs.path }}
+          generate_release_notes: true
+          fail_on_unmatched_files: true

.gitignore

@@ -0,0 +1,14 @@
+docker-compose.override.yml
+
+# Gradle artifacts.
+.gradle/
+build/
+
+# IntelliJ Platform Gradle Plugin local artifact cache + plugin sandbox --
+# generated by `prepareSandbox` / `prepareTestSandbox` and the IDE-installer
+# resolution machinery.  Regenerated on demand by `./gradlew build`.
+.intellijPlatform/
+
+# IDE workspace.
+.idea/
+*.iml

LICENSE

@@ -1,13 +1,13 @@
 MIT License
 
-Copyright (c) 2026 xphp-lang
+Copyright (c) 2026-present Matheus Martins
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
@@ -17,5 +17,5 @@ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

Makefile

@@ -0,0 +1,57 @@
+.PHONY: build
+build:
+	./gradlew build
+
+.PHONY: test
+test:
+	./gradlew test
+
+.PHONY: verify
+verify:
+	# Plugin Verifier compatibility check.  Catches binary-incompat issues
+	# (removed/changed IntelliJ Platform APIs) against the IDE matrix the
+	# IntelliJ Platform Gradle Plugin's `pluginVerification.ides {}` block
+	# resolves -- currently the `recommended()` set for since-build 261.
+	./gradlew verifyPlugin
+
+.PHONY: run-ide
+run-ide: x11-grant
+	# Boots a sandboxed PhpStorm with this plugin loaded.  Used for the
+	# manual smoke tests: open a .xphp file, confirm diagnostics / hover /
+	# go-to-definition / completion.  Sandbox is fully isolated from any
+	# PhpStorm install on the host (separate config/system dirs, separate
+	# JVM process); safe to run alongside your daily IDE.
+	./gradlew runIde
+
+# Allow the jdk container's GUI clients to reach the host's X server so
+# the sandbox PhpStorm window from `run-ide` actually displays.
+# `xhost +local:docker` is idempotent (re-adding an existing rule is a
+# no-op), so we can call it before every `run-ide` without leaking ACL
+# entries.  Pre-req only for `run-ide`; headless targets don't need it.
+# Guarded with `command -v` so contributors on macOS / Windows / WSL
+# (where xhost may be absent or unnecessary) don't hit a confusing
+# error before `runIde` even gets a chance.  Linux+X11 is the
+# documented build host; this just degrades gracefully off it.
+.PHONY: x11-grant
+x11-grant:
+	@command -v xhost >/dev/null 2>&1 && xhost +local:docker || \
+	  echo "(skipping xhost: not on X11 or xhost not installed)"
+
+.PHONY: dist
+dist:
+	# Produce the installable plugin zip at build/distributions/.  Use this
+	# when you want to install into your *existing* PhpStorm (not the
+	# sandbox `run-ide` boots): once the zip exists, in your running IDE go
+	# to Settings -> Plugins -> gear icon -> "Install Plugin from Disk..."
+	# and pick the file.  Requires PhpStorm 2026.1 or newer (since-build=261);
+	# older builds reject the install with an "incompatible build number"
+	# error.  Restart of PhpStorm required after install.
+	./gradlew buildPlugin
+	@echo
+	@echo "Installable plugin distribution:"
+	@ls -la build/distributions/ 2>/dev/null || \
+	  echo "  (build/distributions/ not created; check gradle output above)"
+
+.PHONY: clean
+clean:
+	gradlew clean