refactor: migrate composer scripts into just

Author: norberttech

.github/actions/setup-php-env/action.yml

@@ -70,6 +70,12 @@ runs:
         coverage: ${{ inputs.coverage != '' && inputs.coverage || null }}
       env: ${{ inputs.php-env != '' && fromJSON(inputs.php-env) || fromJSON('{}') }}
 
+    - name: "Install just"
+      shell: bash
+      run: |
+        curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | sudo bash -s -- --to /usr/local/bin
+        just --version
+
     - name: "Install PIE"
       if: ${{ inputs.pie-extensions != '' }}
       shell: bash

.github/workflows/baseline.yml

@@ -45,7 +45,7 @@ jobs:
           pie-extensions: "flow-php/pg-query-ext:1.x-dev"
 
       - name: "Build PHAR file"
-        run: "composer build:phar"
+        run: "just phar"
 
       - name: "Validate Flow PHAR"
         run: |
@@ -121,10 +121,10 @@ jobs:
           pie-extensions: "flow-php/pg-query-ext:1.x-dev"
 
       - name: "Generate documentation"
-        run: "composer build:docs"
+        run: "just docs"
 
       - name: "Build latest version Flow Phar for playground"
-        run: "composer build:phar"
+        run: "just phar"
 
       - name: "Install Landing dependencies"
         run: "composer install --no-interaction --no-progress "
@@ -143,7 +143,7 @@ jobs:
         working-directory: "web/landing"
 
       - name: "Generate Api References"
-        run: "composer build:docs:api"
+        run: "just docs-api"
 
       - name: "Setup Node.js"
         uses: actions/setup-node@v4

.github/workflows/docs.yml

@@ -33,12 +33,12 @@ jobs:
           cache-key-suffix: "-locked"
 
       - name: "Build Docs"
-        run: "composer build:docs"
+        run: "just docs"
 
       - name: Check for uncommitted changes
         run: |
           if [[ -n "$(git status --porcelain)" ]]; then
-            echo "Uncommitted changes detected, please run `composer build:docs` and commit the changes."
+            echo "Uncommitted changes detected, please run `just docs` and commit the changes."
             git status
             exit 1
           else

.github/workflows/job-arrow-extension.yml

@@ -91,7 +91,7 @@ jobs:
         run: composer install --no-interaction --no-progress
 
       - name: Run Parquet Integration Tests with Arrow
-        run: composer test -- --testsuite=lib-parquet-integration
+        run: just test --testsuite=lib-parquet-integration
 
       - name: Upload to Codecov
         if: ${{ !cancelled() && matrix.php == '8.3' && matrix.os == 'ubuntu-latest' }}

.github/workflows/job-extension-tests.yml

@@ -38,16 +38,16 @@ jobs:
           cache-key-suffix: "-extensions"
 
       - name: "Test Brotli"
-        run: "composer test -- --group brotli-extension"
+        run: "just test --group brotli-extension"
 
       - name: "Test LZ4"
-        run: "composer test -- --group lz4-extension"
+        run: "just test --group lz4-extension"
 
       - name: "Test ZSTD"
-        run: "composer test -- --group zstd-extension"
+        run: "just test --group zstd-extension"
 
       - name: "Test Snappy"
-        run: "composer test -- --group snappy-extension"
+        run: "just test --group snappy-extension"
 
       - name: Upload to Codecov
         if: ${{ !cancelled() && matrix.php-version == '8.3' }}

.github/workflows/job-mutation-tests.yml

@@ -42,7 +42,7 @@ jobs:
       - name: "Mutation Tests"
         run: |
           if [ "${{ github.event_name }}" = "pull_request" ]; then
-            composer test:mutation -- --git-diff-filter=AM --git-diff-base=origin/${{ github.base_ref }} --logger-github=false --log-verbosity=none
+            just test-mutation --git-diff-filter=AM --git-diff-base=origin/${{ github.base_ref }} --logger-github=false --log-verbosity=none
           else
-            composer test:mutation -- --logger-github=false --log-verbosity=none
+            just test-mutation --logger-github=false --log-verbosity=none
           fi

.github/workflows/job-static-analyze.yml

@@ -38,11 +38,8 @@ jobs:
           restore-keys: |
             php-${{ matrix.php-version }}-cache-phpstan-
 
-      - name: "Monorepo Validate"
-        run: "composer test:monorepo"
+      - name: "Lint"
+        run: "just lint"
 
-      - name: "Static Analyze - Mago"
-        run: "composer static:analyze:mago"
-
-      - name: "Static Analyze - PHPStan"
-        run: "composer static:analyze:phpstan -- --error-format=github"
+      - name: "Static Analyze"
+        run: "just analyze --error-format=github"

.github/workflows/job-tests.yml

@@ -120,7 +120,7 @@ jobs:
 
       - name: "Test"
         timeout-minutes: 10
-        run: "composer test -- --coverage-clover=./var/phpunit/coverage/clover/coverage.xml --log-junit ./var/phpunit/logs/junit.xml"
+        run: "just test --coverage-clover=./var/phpunit/coverage/clover/coverage.xml --log-junit ./var/phpunit/logs/junit.xml"
         env:
           PGSQL_DATABASE_URL: pgsql://postgres:postgres@127.0.0.1:${{ job.services.postgres.ports[5432] }}/postgres?serverVersion=11&charset=utf8
           MYSQL_DATABASE_URL: mysql://mysql:mysql@127.0.0.1:${{ job.services.mysql.ports[3306] }}/mysql

.github/workflows/release.yml

@@ -32,7 +32,7 @@ jobs:
           pie-extensions: "flow-php/pg-query-ext:1.x-dev"
 
       - name: "Build PHAR file"
-        run: "composer build:phar"
+        run: "just phar"
 
       - name: "Validate Flow PHAR"
         run: |

Justfile

@@ -0,0 +1,94 @@
+# Flow PHP task runner.
+# Run `just` or `just --list` to see available recipes.
+
+set shell := ["bash", "-cu"]
+
+default:
+    @just --list
+
+# Install all dependencies (root + tool dirs via composer post-install-cmd hook).
+install:
+    composer install
+
+# Update all dependencies (root + tool dirs via composer post-update-cmd hook).
+update:
+    composer update
+
+# Full build pipeline: lint, static analysis, tests, mutation.
+build: lint analyze test test-mutation
+
+# Run PHPUnit. Extra arguments are forwarded (e.g. `just test --filter=foo`).
+test *args:
+    tools/phpunit/vendor/bin/phpunit {{args}}
+
+# Run mutation testing with Infection.
+test-mutation *args:
+    tools/infection/vendor/bin/infection --threads=max {{args}}
+
+# Run tests for the landing site.
+test-website:
+    composer test --working-dir=./web/landing
+
+# Run all linters: Mago format-check + Mago lint + monorepo validation.
+lint: lint-mago lint-monorepo
+
+# Run Mago format check and lint.
+lint-mago:
+    tools/mago/vendor/bin/mago format --check
+    tools/mago/vendor/bin/mago lint
+
+# Validate the monorepo configuration.
+lint-monorepo:
+    tools/monorepo/vendor/bin/monorepo-builder validate
+
+# Lint markdown links across the repository.
+lint-links:
+    docker run -t --rm -v $PWD:/app norberttech/md-link-linter --exclude=vendor --exclude=.scratchpad --exclude=documentation .
+
+# Run static analysis (PHPStan).
+analyze *args:
+    tools/phpstan/vendor/bin/phpstan analyze -c phpstan.neon --memory-limit=-1 {{args}}
+
+# Auto-fix code style with Mago (format + lint --fix).
+fix:
+    tools/mago/vendor/bin/mago format
+    tools/mago/vendor/bin/mago lint --fix --potentially-unsafe --format-after-fix
+
+# Build the Flow PHAR archive and copy it into the landing site assets.
+phar:
+    bin/build-phar.sh
+    cp ./build/flow.phar ./web/landing/assets/wasm/tools/flow.phar
+
+# Build the WASM artifact (also rebuilds the PHAR).
+wasm: && phar
+    cd wasm && ./build.sh
+
+# Build the Docker image.
+docker:
+    docker buildx build -t flow-php/flow:latest . --progress=plain --load
+
+# Dump DSL and API JSON used by the landing site.
+docs:
+    bin/docs.php dsl:dump web/landing/resources/dsl.json
+    bin/docs.php api:dump web/landing/resources/api.json
+
+# Generate phpDocumentor API docs for every package config under phpdoc/.
+docs-api:
+    for cfg in phpdoc/*.xml; do \
+        ./tools/phpdocumentor/vendor/bin/phpdoc --config="$cfg" || exit 1; \
+    done
+
+# Regenerate Parquet Thrift PHP classes.
+gen-thrift: && fix
+    grep -q 'namespace php Flow.Parquet.ThriftModel' src/lib/parquet/src/Flow/Parquet/Resources/Thrift/parquet.thrift || { echo "Flow php namespace not found in thrift definition!"; exit 1; }
+    rm src/lib/parquet/src/Flow/Parquet/ThriftModel/*.php
+    thrift --gen php --out src/lib/parquet/src src/lib/parquet/src/Flow/Parquet/Resources/Thrift/parquet.thrift
+
+# Regenerate PostgreSQL pg_query Protobuf PHP classes.
+gen-protobuf-pg: && fix
+    rm -rf src/lib/postgresql/src/Flow/PostgreSql/Protobuf
+    protoc --php_out=src/lib/postgresql/src --proto_path=src/lib/postgresql/resources/proto pg_query.proto
+
+# Regenerate OpenTelemetry OTLP Protobuf PHP classes.
+gen-protobuf-otlp:
+    src/bridge/telemetry/otlp/bin/generate-proto.sh