Mago `1.0.0-rc.1` 🎉

We're excited to announce Mago 1.0.0-rc.1, a major milestone toward the 1.0.0 release! This release candidate includes significant performance improvements, comprehensive type system enhancements, and numerous bug fixes based on community feedback.

📊 Release Highlights

🚀 Watch Mode with Incremental Analysis - Real-time analysis with intelligent re-analysis of only changed files
📝 Full Type Alias Support - Complete implementation of @type, @psalm-type, and @phpstan-type
✅ Comprehensive Inheritance Validation - 20+ new issue codes for class hierarchy validation
📤 SARIF Format Support - Better integration with security and analysis tools
⚙️ Configuration Enhancements - JSON schema support, YAML/JSON configuration files
💰 67 GitHub issues closed in this release
🤝 12 merged pull requests from community contributors

🎉 New Features

🧬 Type System Enhancements

Full Type Alias Support

Mago now has complete support for type aliases in docblocks:

/**
 * @type UserId = positive-int
 * @psalm-type UserData = array{id: UserId, name: string}
 */
class User {
    /** @param UserData $data */
    public function __construct(private array $data) {}
}

/**
 * @import-type UserData from User
 */
class UserService {
    /** @param !User::UserData $data */  // Reference without importing
    public function process(array $data): void {}
}

Features:

Define type aliases with @type, @psalm-type, and @phpstan-type tags
Import type aliases with @import-type (with as keyword support for renaming)
Reference without importing using !ClassName::AliasName syntax
Support for self and static references
Type aliases can reference other aliases, creating dependency chains

Index Access Type Support

Added support for T[K] (index access) type syntax for more precise array typing.

Literal-Int Type Support

Added support for literal-int type to distinguish between literal integer values (e.g., 42) and general integer types.

`@inheritDoc` Support

Full support for @inheritDoc tag in docblocks, including inline {@inheritDoc} syntax.

🔍 Static Analysis Improvements

Comprehensive Inheritance Validation

Mago now validates class inheritance, interface implementation, and trait composition following PHP's type system rules and the Liskov Substitution Principle.

Validates:

Property type compatibility (covariance/contravariance)
Method signature compatibility
Constant type and value compatibility
Visibility rules (cannot make members more restrictive)
Access modifiers (static, readonly, final)
Parameter counts and defaults

New Issue Codes (20+):

IncompatibleConstantAccess, IncompatibleConstantOverride, IncompatibleConstantType
IncompatibleParameterCount, IncompatibleParameterName, IncompatibleParameterType
IncompatiblePropertyAccess, IncompatiblePropertyDefault, IncompatiblePropertyOverride, IncompatiblePropertyType
IncompatibleReturnType, IncompatibleVisibility
MissingOverrideAttribute
And more...

Trait Constant Override Validation

Validates trait constant override rules - prevents classes from overriding trait constants with different values.

Auto-Fix Support for Redundancy Issues

The analyzer can now automatically fix various redundancy issues with mago analyze --fix --fmt.

Conditional Return Type for `json_encode()`

Special handler recognizes the JSON_THROW_ON_ERROR flag and returns string instead of string|false.

🎯 Special Function Handlers

`array_merge` and `Psl\Dict\merge`

Special type inference for array_merge and PSL's Psl\Dict\merge with proper key/value tracking.

`array_filter` with Callback Assertion

Better type narrowing when using array_filter with callback assertions like is_int(...).

`compact()` Handler

Preserves type information when using compact() - knows the exact keys and their types.

🧹 Linter Rules

New Rules

no-self-assignment - Detects assignments where a variable is assigned to itself ($x = $x;)
prefer-early-continue - Encourages early returns to reduce nesting
prefer-static-closure - Performance optimization for closures that don't use $this

Previously Disabled Rules Now Enabled

The following rules are now enabled by default:

no-redundant-use - Detects unused imports
no-variable-variable - Warns about variable variables
no-redundant-readonly - Detects redundant readonly modifiers
sensitive-parameter - Validates sensitive parameter handling

📊 Reporting & Output

SARIF Format Support

Added support for SARIF (Static Analysis Results Interchange Format) for integration with GitHub Code Scanning, security dashboards, and CI/CD pipelines.

mago analyze --reporting-format sarif > results.sarif

Baseline Improvements

Major improvements to baseline management:

Cross-platform path normalization - Works correctly on Windows and Unix
Detailed statistics - Dead/removed issues, filtered counts, severity levels
Stricter baseline checking - New fail_on_out_of_sync_baseline parameter
Better API - Moved to mago-reporting crate for reusability

Enhanced Annotations for CI/CD

Annotation messages now included in GitHub, GitLab, and Checkstyle formats with column information and detailed context.

⚙️ Configuration

JSON Schema Support

Generate JSON schema for configuration validation with IDE autocomplete:

mago config --schema > mago-schema.json

YAML and JSON Configuration Support

Configuration files can now be written in YAML or JSON in addition to TOML.

Search Order: workspace directory → XDG_CONFIG_HOME → home directory
Format Priority: TOML > YAML > JSON

🖥️ CLI Enhancements

Shell Completions

Generate shell completions for Bash, Zsh, Fish, and PowerShell:

mago generate-completions bash > /etc/bash_completion.d/mago

Install Specific Versions

Installation script now supports version selection:

curl -sSL https://mago.sh/install | bash -s -- --version=1.0.0-rc.1

⚡ Performance

Watch Mode

New --watch flag for continuous analysis during development:

mago analyze --watch

Watches your filesystem and automatically re-analyzes only the files that changed and their dependencies. Powered by intelligent incremental analysis internally - dramatically faster than re-analyzing the entire codebase!

Type Pre-allocation Optimization

Re-use pre-allocated types for better memory usage and performance.

🔧 Breaking Changes

Configuration File Behavior Change

⚠️ BREAKING CHANGE: Configuration files are no longer merged from multiple locations.

What Changed:

Only ONE configuration file is loaded (first found in search order)
No merging between global and workspace configs

Migration: Consolidate your configuration into a single file if you previously relied on merging.

Previously Disabled Rules Now Enabled

Several linter rules are now enabled by default. You may see new warnings/errors for:

Unused imports
Variable variables
Redundant readonly modifiers
Sensitive parameter handling

Comprehensive Inheritance Validation

The new strict inheritance validation may report issues in class hierarchies that were previously undetected.

🐛 Bug Fixes

🧬 Type System & Analysis

Array key access in union types - Corrected error reporting
False positives - Fixed multiple issues to improve accuracy
Null coalesce type narrowing - Fixed when right-hand side is never type
isset() false positives - Fixed several issues with union array types and type checks after isset()
Nullability preservation - Preserve nullability when merging docblock types with real types

🔤 Syntax & Parser

Reserved keywords in string interpolation - Now accepts reserved keywords in array access ("$array[class]")
Static in constant expressions - Correctly disallows static in constant expressions (matches PHP behavior)

🎨 Formatter

String interpolation alignment - Preserve alignment for braced expressions
Echo tags recognition - No longer flagged as useless code
Empty single-line comments - Allow empty comments in blocks

🧹 Linter

--only flag - Fixed flag being ignored when linting
Only filter warning - Warn when filter doesn't match any rule
Unfulfilled expectations - Don't report on non-active rules

💥 Other Fixes

Extreme values - Prevent panics on extreme numeric values
Try statement return detection - Fixed detection when calling functions returning never

🏗️ Internal Changes

Orchestrator Crate

Major architectural refactoring introducing the orchestrator crate - separates CLI from core analysis engine.

Rust 1.91 Update

Updated to Rust 1.91 for latest language features and performance improvements.

SPL Stubs

Improved SPL (Standard PHP Library) stubs with better type definitions.

⚠️ Migration Notes

Upgrading from Previous Versions

📁 Configuration Files - Consolidate multiple configs into a single file (no more merging)
🧹 Linter Rules - Review new warnings from previously disabled rules
🔍 Inheritance Validation - Review and fix newly reported incompatibilities
🎨 JSON Schema - Generate schema for IDE autocomplete: mago config --schema > mago-schema.json
⌨️ Shell Completions - Install completions for better CLI experience

🙏 Acknowledgments

Thank you to all contributors who reported issues, provided feedback, and helped make this release possible! 💝

Contributors

Special thanks to our community contributors who submitted pull requests:

Issues Closed

This release closes 67 GitHub issues:

#623, #622, #621, #620, #619, #618, #617, #616, #615, #614, #612, #610, #609, #608, #607, #606, #604, #603, #602, #601, #600, #599, #598, #597, #596, #595, #593, #592, #591, #590, #589, #588, #587, #586, #584, #583, #582, #580, #576, #575, #566, #542, #533, #526, #525, #519, #496, #486, #452, #447, #425, #424, #423, #420, #404, #398, #385, #378, #373, #353, #350, #340, #302, #265, #233, #202, #201, #74

📦 Installation

Install Latest Version

curl -sSL https://mago.sh/install | bash

Install Specific Version

curl -sSL https://mago.sh/install | bash -s -- --version=1.0.0-rc.1

Upgrade Existing Installation

mago self-update

🎯 What's Next

This release candidate represents a significant milestone toward version 1.0.0. The architectural refactoring, comprehensive type system improvements, and performance enhancements set a solid foundation for future development. 🚀

Language Server Protocol (LSP)

LSP support has been intentionally delayed to version 2.0.0 to ensure Mago 1.0.0 delivers a solid, stable foundation without rushing critical features. Read more about this decision: Why Mago 1.0.0 Won't Ship With an LSP

Upcoming in Future Releases:

Additional linter rules
More special function handlers
Performance optimizations
Enhanced type inference capabilities

Full Changelog: 1.0.0-beta.34...1.0.0-rc.1

carthage-software/mago 1.0.0-rc.1 Mago 1.0.0-rc.1 on GitHub

Mago 1.0.0-rc.1 🎉

📊 Release Highlights

🎉 New Features

🧬 Type System Enhancements

Full Type Alias Support

Index Access Type Support

Literal-Int Type Support

@inheritDoc Support

🔍 Static Analysis Improvements

Comprehensive Inheritance Validation

Trait Constant Override Validation

Auto-Fix Support for Redundancy Issues

Conditional Return Type for json_encode()

🎯 Special Function Handlers

array_merge and Psl\Dict\merge

array_filter with Callback Assertion

compact() Handler

🧹 Linter Rules

New Rules

Previously Disabled Rules Now Enabled

📊 Reporting & Output

SARIF Format Support

Baseline Improvements

Enhanced Annotations for CI/CD

⚙️ Configuration

JSON Schema Support

YAML and JSON Configuration Support

🖥️ CLI Enhancements

Shell Completions

Install Specific Versions

⚡ Performance

Watch Mode

Type Pre-allocation Optimization

🔧 Breaking Changes

Configuration File Behavior Change

Previously Disabled Rules Now Enabled

Comprehensive Inheritance Validation

🐛 Bug Fixes

🧬 Type System & Analysis

🔤 Syntax & Parser

🎨 Formatter

🧹 Linter

💥 Other Fixes

🏗️ Internal Changes

Orchestrator Crate

Rust 1.91 Update

SPL Stubs

⚠️ Migration Notes

Upgrading from Previous Versions

🙏 Acknowledgments

Contributors

Issues Closed

📦 Installation

Install Latest Version

Install Specific Version

Upgrade Existing Installation

🎯 What's Next

Language Server Protocol (LSP)

carthage-software/mago 1.0.0-rc.1
Mago 1.0.0-rc.1

on GitHub

Mago `1.0.0-rc.1` 🎉

`@inheritDoc` Support

Conditional Return Type for `json_encode()`

`array_merge` and `Psl\Dict\merge`

`array_filter` with Callback Assertion

`compact()` Handler