Add Mago as task

composer.json

@@ -53,6 +53,7 @@
         "atoum/atoum": "Lets GrumPHP run your unit tests.",
         "behat/behat": "Lets GrumPHP validate your project features.",
         "brianium/paratest": "Lets GrumPHP run PHPUnit in parallel.",
+        "carthage-software/mago": "Lets GrumPHP help you write better PHP code.",
         "codeception/codeception": "Lets GrumPHP run your project's full stack tests",
         "consolidation/robo": "Lets GrumPHP run your automated PHP tasks.",
         "designsecurity/progpilot": "Lets GrumPHP be sure that there are no vulnerabilities in your code.",

doc/tasks.md

@@ -32,6 +32,10 @@ grumphp:
         infection: ~
         jsonlint: ~
         kahlan: ~
+        mago_analyze: ~
+        mago_format: ~
+        mago_guard: ~
+        mago_lint: ~
         make: ~
         npm_script: ~
         paratest: ~
@@ -99,6 +103,11 @@ Every task has its own default configuration. It is possible to overwrite the pa
 - [Infection](tasks/infection.md)
 - [JsonLint](tasks/jsonlint.md)
 - [Kahlan](tasks/kahlan.md)
+- [Mago](tasks/mago.md)
+  - [Mago Analyzer](tasks/mago/analyzer.md)
+  - [Mago Formatter](tasks/mago/formatter.md)
+  - [Mago Guard](tasks/mago/guard.md)
+  - [Mago Linter](tasks/mago/linter.md)
 - [Make](tasks/make.md)
 - [NPM script](tasks/npm_script.md)
 - [Paratest](tasks/paratest.md)

doc/tasks/mago.md

@@ -0,0 +1,8 @@
+# Mago
+
+The Mago's toolchain.
+
+- [mago_analyze](mago/analyzer.md)
+- [mago_format](mago/formatter.md)
+- [mago_guard](mago/guard.md)
+- [mago_lint](mago/linter.md)

doc/tasks/mago/analyzer.md

@@ -0,0 +1,119 @@
+# Mago Analyzer
+
+Perform deep static analysis on PHP code including type checking, control flow analysis, and detection of logical errors.
+
+## Composer
+
+```bash
+composer require --dev carthage-software/mago
+```
+
+## Config
+
+The task lives under the `mago_analyze` namespace and has following configurable parameters:
+
+```yaml
+# grumphp.yml
+grumphp:
+    tasks:
+        mago_analyze:
+            no-stubs: ~
+            staged: ~
+            retain-codes: []
+            ignore-baseline: ~
+            fix: ~
+            fail-on-remaining: ~
+            sort: ~
+            fixable-only: ~
+            reporting-format: ~
+            reporting-target: ~
+            minimum-report-level: ~
+            minimum-fail-level: ~
+            dry-run: ~
+```
+
+**no-stubs**
+
+*Type: bool*
+
+Disable built-in PHP and library stubs for analysis. By default, the analyzer uses stubs for built-in PHP functions and popular libraries to provide accurate type information. Disabling this may result in more reported issues when external symbols can't be resolved.
+
+**staged**
+
+*Type: bool*
+
+Only analyze files that are staged in git. Designed for git pre-commit hooks. Fails if not in a git repository.
+
+**retain-codes**
+
+*Type: string[] — Default: []*
+
+Reporting filter: only display issues matching the specified rule codes (e.g. `invalid-argument`, `semantics`). All rules still run; only the output is filtered. Can be specified multiple times.
+
+**ignore-baseline**
+
+*Type: bool*
+
+Ignore the baseline file and report all issues, including those currently suppressed. The baseline file must be generated manually via `mago analyze --generate-baseline`.
+
+**fix**
+
+*Default: null*
+
+Apply automatic fixes to the source code. Accepted values:
+
+- `safe` — apply only safe fixes (default fix mode)
+- `potentially-unsafe` — also apply fixes that may require manual review
+- `unsafe` — also apply fixes that might change code behavior
+
+Cannot be used together with `fixable-only`, `reporting-format`, or `reporting-target`.
+
+**fail-on-remaining**
+
+*Type: bool*
+
+Exit with a non-zero status if there are issues remaining after fixing. Useful in CI/CD pipelines to ensure all issues are addressed. Requires `fix` to be set.
+
+**sort**
+
+*Type: bool*
+
+Sort reported issues by severity level, rule code, and file location. By default, issues are reported in the order they appear in files.
+
+**fixable-only**
+
+*Type: bool*
+
+Filter output to only show issues that can be automatically fixed. Cannot be used together with `fix`.
+
+**reporting-format**
+
+*Default: null (mago default: medium)*
+
+Output format for issue reports. Not available when using `fix`. Possible values:
+
+`rich`, `medium`, `short`, `ariadne`, `github`, `gitlab`, `json`, `count`, `code-count`, `checkstyle`, `emacs`, `sarif`
+
+**reporting-target**
+
+*Default: null (mago default: stdout)*
+
+Where to send the output. Not available when using `fix`. Possible values: `stdout`, `stderr`
+
+**minimum-report-level**
+
+*Default: null (mago default: all levels)*
+
+Minimum severity level to display in the report. Issues below this level are not shown. Possible values: `note`, `help`, `warning`, `error`
+
+**minimum-fail-level**
+
+*Default: null (mago default: error)*
+
+Minimum severity level that causes the command to fail. For example, setting this to `warning` means the command fails on warnings and errors, but not on notes or help suggestions. Possible values: `note`, `help`, `warning`, `error`
+
+**dry-run**
+
+*Type: bool*
+
+Preview fixes without writing any changes to disk. Shows what changes would be made without modifying any files. Requires `fix` to be set.

doc/tasks/mago/formatter.md

@@ -0,0 +1,32 @@
+# Mago Formatter
+
+Automatically format PHP code to match the configured style preferences.
+
+## Composer
+
+```bash
+composer require --dev carthage-software/mago
+```
+
+## Config
+
+The task lives under the `mago_format` namespace and has following configurable parameters:
+
+```yaml
+# grumphp.yml
+grumphp:
+    tasks:
+        mago_format:
+            type: default
+```
+
+**type**
+
+*Default: default — Possible values: `default`, `dry-run`, `check`, `staged`*
+
+Controls how the formatter runs:
+
+- `default` — apply formatting changes in-place
+- `dry-run` — print a diff of changes without modifying any files
+- `check` — exit with failure if any file would be changed, without modifying files. Ideal for CI environments
+- `staged` — format files currently staged in git. Designed for git pre-commit hooks. Fails if not in a git repository

doc/tasks/mago/guard.md

@@ -0,0 +1,123 @@
+# Mago Guard
+
+Enforce architectural rules and layer dependencies. Checks that code follows defined architectural constraints, such as ensuring that certain layers don't depend on others.
+
+## Composer
+
+```bash
+composer require --dev carthage-software/mago
+```
+
+## Config
+
+The task lives under the `mago_guard` namespace and has following configurable parameters:
+
+```yaml
+# grumphp.yml
+grumphp:
+    tasks:
+        mago_guard:
+            no-stubs: ~
+            checks: all
+            retain-codes: []
+            ignore-baseline: ~
+            fix: ~
+            fail-on-remaining: ~
+            sort: ~
+            fixable-only: ~
+            reporting-format: ~
+            reporting-target: ~
+            minimum-report-level: ~
+            minimum-fail-level: ~
+            dry-run: ~
+```
+
+**no-stubs**
+
+*Type: bool*
+
+Disable built-in PHP and library stubs. By default, guard uses stubs for built-in PHP functions and popular libraries to provide accurate symbol information. Disabling this may result in more warnings when external symbols can't be resolved.
+
+**checks**
+
+*Default: all — Possible values: `all`, `structural`, `perimeter`*
+
+Controls which checks are run:
+
+- `all` — run both structural and perimeter checks
+- `structural` — run only structural checks (naming conventions, modifiers, inheritance constraints)
+- `perimeter` — run only perimeter checks (dependency boundaries, layer restrictions)
+
+**retain-codes**
+
+*Type: string[] — Default: []*
+
+Reporting filter: only display issues matching the specified rule codes. All rules still run; only the output is filtered. Can be specified multiple times.
+
+**ignore-baseline**
+
+*Type: bool*
+
+Ignore the baseline file and report all issues, including those currently suppressed. The baseline file must be generated manually via `mago guard --generate-baseline`.
+
+**fix**
+
+*Default: null*
+
+Apply automatic fixes to the source code. Accepted values:
+
+- `safe` — apply only safe fixes (default fix mode)
+- `potentially-unsafe` — also apply fixes that may require manual review
+- `unsafe` — also apply fixes that might change code behavior
+
+Cannot be used together with `fixable-only`, `reporting-format`, or `reporting-target`.
+
+**fail-on-remaining**
+
+*Type: bool*
+
+Exit with a non-zero status if there are issues remaining after fixing. Useful in CI/CD pipelines to ensure all issues are addressed. Requires `fix` to be set.
+
+**sort**
+
+*Type: bool*
+
+Sort reported issues by severity level, rule code, and file location. By default, issues are reported in the order they appear in files.
+
+**fixable-only**
+
+*Type: bool*
+
+Filter output to only show issues that can be automatically fixed. Cannot be used together with `fix`.
+
+**reporting-format**
+
+*Default: null (mago default: medium)*
+
+Output format for issue reports. Not available when using `fix`. Possible values:
+
+`rich`, `medium`, `short`, `ariadne`, `github`, `gitlab`, `json`, `count`, `code-count`, `checkstyle`, `emacs`, `sarif`
+
+**reporting-target**
+
+*Default: null (mago default: stdout)*
+
+Where to send the output. Not available when using `fix`. Possible values: `stdout`, `stderr`
+
+**minimum-report-level**
+
+*Default: null (mago default: all levels)*
+
+Minimum severity level to display in the report. Issues below this level are not shown. Possible values: `note`, `help`, `warning`, `error`
+
+**minimum-fail-level**
+
+*Default: null (mago default: error)*
+
+Minimum severity level that causes the command to fail. For example, setting this to `warning` means the command fails on warnings and errors, but not on notes or help suggestions. Possible values: `note`, `help`, `warning`, `error`
+
+**dry-run**
+
+*Type: bool*
+
+Preview fixes without writing any changes to disk. Shows what changes would be made without modifying any files. Requires `fix` to be set.