Mago 1.12.0

This release adds clickable file paths in terminal output via OSC 8 hyperlinks, a --fail-on-remaining flag for CI workflows using --fix, improved --staged handling for partially staged files, and several bug fixes in the analyzer, linter, and configuration system.

✨ Features

Reporting

Clickable file paths via OSC 8 hyperlinks: File paths in diagnostic output are now clickable in terminals that support OSC 8 hyperlinks (iTerm2, Wezterm, Kitty, Windows Terminal, Ghostty, and others). Clicking a path opens the file directly in your editor at the correct line and column. Configure via editor-url in mago.toml or the MAGO_EDITOR_URL environment variable with %file%, %line%, and %column% placeholders. Supported in rich, medium, short, and emacs reporting formats. Hyperlinks are automatically disabled when output is piped or when --colors=never is used (#1188)

CLI

--fail-on-remaining flag for lint and analyze: When using --fix, Mago now exits with code 0 even if some issues could not be auto-fixed. The new --fail-on-remaining flag restores a non-zero exit code when unfixed issues remain, making it easy to enforce that all issues are resolved in CI pipelines (#1208)
Improved --staged --fix handling: When using --staged with --fix, Mago now detects partially staged files and only processes the staged content. Fixed files are automatically re-staged so that fixes are included in the commit without accidentally staging unstaged changes (#1199)

🐛 Bug Fixes

Analyzer

Broad type subtraction with generic parameters in negated assertions: Fixed incorrect removal of broad types (e.g., object, iterable) when subtracting generic type parameters in negated assertion contexts, which could produce false redundant-condition diagnostics (#1207)
Type narrowing from identity comparison with typed variables: The analyzer now correctly narrows variable types from identity comparisons (===) with other typed variables. Previously, the left-hand variable could remain typed as mixed after comparison with a more precisely typed value (#1206)

Linter

Overlapping edit detection in TextEditor: Fixed a long-standing bug where adjacent non-empty text edit ranges were incorrectly rejected as overlapping, causing auto-fix failures in rules like array-style and str-starts-with when multiple fixes applied to nearby code (#877)

Configuration

XDG_CONFIG_HOME fallback: When XDG_CONFIG_HOME is not set, Mago now correctly falls back to $HOME/.config before checking $HOME, matching the XDG Base Directory Specification. Previously, only $HOME was checked, causing global configuration files in ~/.config/mago.toml to be ignored (#1211)

📖 Documentation

Configuration file discovery: Documented the full configuration file lookup order: workspace directory, $XDG_CONFIG_HOME, ~/.config, ~ (#1211)
Editor integration guide: Added documentation for the editor-url configuration option with URL templates for VS Code, Cursor, Windsurf, PhpStorm/IntelliJ, Zed, Sublime Text, Emacs, and Atom (#1188)
Default PHP version corrected: Fixed the documentation to accurately state that the default PHP version is release-dependent (latest stable supported by the Mago release), not a hardcoded value (#1174)

🙏 Thank You

Issue Reporters

Thank you to everyone who reported issues and requested features that shaped this release:

Full Changelog: 1.11.0...1.12.0

carthage-software/mago 1.12.0 Mago 1.12.0 on GitHub