(feat): Mago initial add (#1929)

* Mago initial addition

* Mago initial addition

* fix(ci): make Mago checks truly non-blocking

Remove the exit 1 from the Final status step so the job always
succeeds. Issues are still surfaced as GitHub annotations via
--reporting-format=github on each step.

Author: bobstrecansky

.github/workflows/mago.yml

@@ -0,0 +1,55 @@
+name: Mago (Code Quality Checks, Non Blocking)
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+
+jobs:
+  mago:
+    name: Mago Quality Checks
+    runs-on: ubuntu-latest
+    # Surfaces quality issues as annotations without blocking merges
+    continue-on-error: true
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Cache Mago
+        uses: actions/cache@v4
+        with:
+          path: .mago
+          key: ${{ runner.os }}-mago-${{ hashFiles('mago.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-mago-
+
+      - name: Setup Mago
+        uses: nhedger/setup-mago@v1
+        with:
+          version: "latest"
+          token: ${{ github.token }}
+
+      - name: Formatting
+        id: format
+        continue-on-error: true
+        run: mago format --check
+
+      - name: Linting
+        id: lint
+        continue-on-error: true
+        run: mago lint --reporting-format=github
+
+      - name: Static Analysis
+        id: analyze
+        continue-on-error: true
+        run: mago analyze --reporting-format=github
+
+      - name: Final status
+        if: ${{ always() }}
+        run: |
+          echo "format=${{ steps.format.outcome }} lint=${{ steps.lint.outcome }} analyze=${{ steps.analyze.outcome }}"

.gitignore

@@ -36,3 +36,7 @@ docs/build
 
 # cache from phpdoc
 .phpdoc
+
+# mago
+.mago/
+mago.lock

mago.toml

@@ -0,0 +1,8 @@
+# mago.toml
+[source]
+paths = ["src"]
+
+[formatter]
+print-width = 120
+tab-width = 4
+use-tabs = false

script/mago.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+if ! command -v docker >/dev/null 2>&1; then
+  echo "Error: 'docker' is not installed or not in PATH."
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="${SCRIPT_DIR}/.."
+MAGO_IMAGE="ghcr.io/carthage-software/mago"
+MAGO_DOCKER=(docker run --rm -v "${ROOT_DIR}:/app" -w /app "${MAGO_IMAGE}")
+
+echo "Running Mago formatting check..."
+"${MAGO_DOCKER[@]}" format --check
+format_exit=$?
+
+echo "Running Mago linting..."
+"${MAGO_DOCKER[@]}" lint --reporting-format=github
+lint_exit=$?
+
+echo "Running Mago static analysis..."
+"${MAGO_DOCKER[@]}" analyze --reporting-format=github
+analyze_exit=$?
+
+echo "All Mago checks completed."
+
+if [[ $format_exit -ne 0 || $lint_exit -ne 0 || $analyze_exit -ne 0 ]]; then
+  echo "One or more Mago checks failed."
+  echo "format=${format_exit} lint=${lint_exit} analyze=${analyze_exit}"
+  exit 1
+fi