From c4ef3cfedf4b7dd334b15420ffaad0a67ea89d82 Mon Sep 17 00:00:00 2001
From: Mathieu Santostefano <msantostefano@proton.me>
Date: Mon, 21 Sep 2026 17:20:24 +0200
Subject: [PATCH] feat: install Mago 1.50.0 in the image

The image carried Mago 1.46.0 as long as it was based on jakzal/phpqa. The
lean rewrite (361dada) dropped it along with the rest of the toolbox, so
projects calling "mago" in the container now fail.

Mago comes back pinned, as the static musl build extracted to /tools/mago
for amd64 and arm64, at 1.50.0 instead of 1.46.0: the formatter of 1.46 is
not idempotent (on a 693 file code base, 19 files still move on a second
pass, none on a third), which leaves a tree "mago format --check" refuses
after a single pass. 1.50 settles in one.

The version lives in the MAGO_VERSION build argument.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ARCHITECTURE.md |  2 +-
 CHANGELOG.md    |  6 ++++++
 Dockerfile      | 20 ++++++++++++++++++++
 README.md       |  3 ++-
 4 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index e1622dd..d4e0061 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -32,7 +32,7 @@ phpqa/
 ### 1. Image Docker (`Dockerfile`)
 
 Image Docker construite en deux étapes (`php:X.Y-cli` pour compiler, `debian:slim` à l'exécution) avec :
-- Uniquement les outils QA appelés par les tâches Castor (PHPStan, ECS, Rector, Deptrac, PHPUnit, Infection, parallel-lint)
+- Uniquement les outils QA appelés par les tâches Castor (PHPStan, ECS, Rector, Deptrac, PHPUnit, Infection, parallel-lint, Mago)
 - Castor pré-installé (binaire statique)
 - Les extensions PHP nécessaires aux projets Symfony/Doctrine
 - Le layout `/tools/.composer/vendor-bin/...` hérité de `jakzal/phpqa`, référencé par les projets
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3357467..5537a74 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Mago 1.50.0 (`/tools/mago`), the formatter, linter and analyzer of Carthage Software.
+  Static musl binary, amd64 and arm64, pinned by the `MAGO_VERSION` build argument.
+  The image carried Mago 1.46.0 through `jakzal/phpqa`; the lean rewrite dropped it.
+
 ### Changed - Lean Docker image (3.2 GB → ~0.8 GB, 689 MB → ~150 MB compressed)
 
 - The image is no longer based on `jakzal/phpqa`. It is a two-stage build on the official
diff --git a/Dockerfile b/Dockerfile
index 070e337..92f7831 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,5 +1,6 @@
 ARG PHP_VERSION=8.4
 ARG DEBIAN_RELEASE=trixie
+ARG MAGO_VERSION=1.50.0
 
 # ============================================================
 # Stage 1: build PHP extensions and install QA tools
@@ -163,6 +164,24 @@ RUN set -eux; \
 	mv ~/.local/bin/castor /usr/local/bin/castor; \
 	chmod 755 /usr/local/bin/castor
 
+# ------------------------------------------------------------
+# Mago (https://mago.carthage.software/): formatter, linter and analyzer
+# in a single Rust binary. The musl build is statically linked, so it adds
+# nothing to the runtime libraries computed below.
+# ------------------------------------------------------------
+ARG MAGO_VERSION
+ARG TARGETARCH
+RUN set -eux; \
+	case "$TARGETARCH" in \
+		amd64) mago_arch=x86_64 ;; \
+		arm64) mago_arch=aarch64 ;; \
+		*) echo "unsupported architecture: $TARGETARCH" >&2; exit 1 ;; \
+	esac; \
+	target="mago-${MAGO_VERSION}-${mago_arch}-unknown-linux-musl"; \
+	curl -sSL "https://github.com/carthage-software/mago/releases/download/${MAGO_VERSION}/${target}.tar.gz" \
+		| tar -xz -C /tools --strip-components=1 "${target}/mago"; \
+	chmod 755 /tools/mago
+
 # ------------------------------------------------------------
 # Compute the Debian packages providing the shared libraries needed
 # at runtime by PHP, its extensions and Castor. The list is consumed
@@ -232,6 +251,7 @@ RUN set -eux; \
 	infection --version; \
 	phpunit --version; \
 	parallel-lint --version; \
+	mago --version; \
 	find /tmp /var/tmp -mindepth 1 -delete; \
 	chown -R 1001:1001 /tools/.composer/cache
 
diff --git a/README.md b/README.md
index 6c2662a..28a6983 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 This repository provides:
 
 1. **🐳 Lean Docker Image** (~800 MB, ~150 MB compressed) built on the official `php:X.Y-cli` images with:
-   - ✅ Only the QA tools used by the Castor tasks (PHPStan, ECS, Rector, Deptrac, PHPUnit, Infection, parallel-lint)
+   - ✅ Only the QA tools used by the Castor tasks (PHPStan, ECS, Rector, Deptrac, PHPUnit, Infection, parallel-lint, Mago)
    - 🛠️ [Castor](https://github.com/jolicode/castor) pre-installed as a task runner (static build, works on every PHP version)
    - 🧩 The PHP extensions needed by Symfony/Doctrine projects (intl, pdo_pgsql, redis, amqp, imagick, xdebug, ...)
    - 🧪 Enhanced PHPUnit, PHPStan, and Infection tooling
@@ -126,6 +126,7 @@ ship its own copy in `vendor/bin`:
 | PHPUnit helpers (slow test detector, foundry, browser-kit, ...) | `/tools/.composer/vendor-bin/phpunit` |
 | `phpunit-10` … `phpunit-13` (PHAR), `phpunit` → newest one supported by the PHP version | `/tools` |
 | `parallel-lint` (PHAR) | `/tools` |
+| `mago` (static binary) | `/tools` |
 | `composer`, `castor` | `/usr/local/bin` |
 
 Other tools: `git`, `curl`, `wget`, `jq`, `unzip`, `openssh-client`.