Development

.github/workflows/ci.yml

@@ -0,0 +1,11 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml

.github/workflows/release.yml

@@ -0,0 +1,91 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+
+  # ── Gate ────────────────────────────────────────────────────────────────────
+  # The release job will not run until every matrix leg of `test` passes.
+  # If any PHP version fails, the release is blocked.
+  test:
+    uses: ./.github/workflows/test.yml
+
+  # ── Release ─────────────────────────────────────────────────────────────────
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: test               # hard gate — every PHP matrix leg must be green
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      # ── Determine version type from the tag ─────────────────────────────────
+      #
+      # Supported tag patterns:
+      #   v1.0.0           → stable, classified as major / minor / patch
+      #   v1.0.0-alpha.1   → alpha  (pre-release)
+      #   v1.0.0-beta.2    → beta   (pre-release)
+      #   v1.0.0-rc.1      → release candidate (pre-release)
+      #   v1.0.0-anything  → generic pre-release
+      #
+      - name: Determine version type
+        id: version
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          VERSION="${TAG#v}"
+
+          if [[ "$VERSION" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)(-(.+))?$ ]]; then
+            MAJOR="${BASH_REMATCH[1]}"
+            MINOR="${BASH_REMATCH[2]}"
+            PATCH="${BASH_REMATCH[3]}"
+            PRE_ID="${BASH_REMATCH[5]}"
+
+            if [[ -n "$PRE_ID" ]]; then
+              # ── Pre-release ────────────────────────────────────────────────
+              PRERELEASE=true
+              if   [[ "$PRE_ID" =~ ^alpha ]]; then TYPE="alpha"; LABEL="Alpha";
+              elif [[ "$PRE_ID" =~ ^beta  ]]; then TYPE="beta";  LABEL="Beta";
+              elif [[ "$PRE_ID" =~ ^rc    ]]; then TYPE="rc";    LABEL="Release Candidate";
+              else                                 TYPE="pre";   LABEL="Pre-release";
+              fi
+            else
+              # ── Stable release ─────────────────────────────────────────────
+              PRERELEASE=false
+              if   [[ "$MAJOR" == "0" ]];                          then TYPE="prestable"; LABEL="0.x Release";
+              elif [[ "$MINOR" == "0" && "$PATCH" == "0" ]];       then TYPE="major";      LABEL="Major Release";
+              elif [[ "$PATCH" == "0" ]];                          then TYPE="minor";      LABEL="Minor Release";
+              else                                                      TYPE="patch";      LABEL="Patch";
+              fi
+            fi
+          else
+            # Fallback for non-semver tags
+            TYPE="release"; LABEL="Release"; PRERELEASE=false
+          fi
+
+          echo "type=$TYPE"             >> $GITHUB_OUTPUT
+          echo "label=$LABEL"           >> $GITHUB_OUTPUT
+          echo "prerelease=$PRERELEASE" >> $GITHUB_OUTPUT
+          echo "version=$VERSION"       >> $GITHUB_OUTPUT
+
+          echo "### Version info"                       >> $GITHUB_STEP_SUMMARY
+          echo "| Field | Value |"                      >> $GITHUB_STEP_SUMMARY
+          echo "|---|---|"                               >> $GITHUB_STEP_SUMMARY
+          echo "| Tag         | \`$TAG\`       |"       >> $GITHUB_STEP_SUMMARY
+          echo "| Version     | \`$VERSION\`   |"       >> $GITHUB_STEP_SUMMARY
+          echo "| Type        | \`$TYPE\`      |"       >> $GITHUB_STEP_SUMMARY
+          echo "| Label       | $LABEL         |"       >> $GITHUB_STEP_SUMMARY
+          echo "| Pre-release | $PRERELEASE    |"       >> $GITHUB_STEP_SUMMARY
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: "${{ github.ref_name }} — ${{ steps.version.outputs.label }}"
+          prerelease: ${{ steps.version.outputs.prerelease }}
+          generate_release_notes: true

.github/workflows/test.yml

@@ -0,0 +1,76 @@
+name: Tests
+
+on:
+  workflow_call:
+
+jobs:
+
+  # ── Unit tests + static analysis ─────────────────────────────────────────────
+  # The whole suite is mock-based (Mockery/Pest) — no external services needed.
+  # Floor is PHP 8.2 here because the dev toolchain (pestphp/pest ^3) requires it;
+  # 8.4 guards against new deprecations. Runtime support for 8.1 is verified
+  # separately by the `floor` job below.
+  unit:
+    name: Unit — PHP ${{ matrix.php }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.2', '8.3', '8.4']
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Setup PHP ${{ matrix.php }}
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: json, curl, mbstring
+          coverage: none
+
+      # composer.lock is not committed (this is a library), so the cache key is
+      # derived from composer.json instead.
+      - name: Cache Composer packages
+        uses: actions/cache@v5
+        with:
+          path: vendor
+          key: php-${{ matrix.php }}-composer-${{ hashFiles('composer.json') }}
+          restore-keys: php-${{ matrix.php }}-composer-
+
+      - name: Validate composer.json
+        run: composer validate --no-check-publish --no-check-lock
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-interaction
+
+      - name: Run PHPStan
+        run: vendor/bin/phpstan analyse --no-progress --memory-limit=1G
+
+      - name: Run unit tests
+        run: vendor/bin/pest --colors=always
+
+  # ── PHP 8.1 runtime floor ────────────────────────────────────────────────────
+  # The library supports PHP 8.1, but the dev toolchain (Pest 3) requires 8.2, so
+  # the full suite can't run there. `composer install` is no help either: even with
+  # --no-dev, Composer still *resolves* require-dev platform constraints, and Pest's
+  # `php ^8.2` blocks resolution on 8.1. A syntax lint needs no dependencies, so
+  # this leg parses every source file on PHP 8.1 — catching any 8.2-only syntax and
+  # backing the `"php": "^8.1"` claim in composer.json.
+  floor:
+    name: Floor — PHP 8.1 (lint)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Setup PHP 8.1
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.1'
+          coverage: none
+
+      - name: Lint sources on PHP 8.1
+        run: find src -name '*.php' -print0 | xargs -0 -n1 -P4 php -l