|
| 1 | +# Mago checks |
| 2 | + |
| 3 | +Install development dependencies with `composer install`, then run: |
| 4 | + |
| 5 | +```sh |
| 6 | +composer check # formatting, linter, analyzer for source and tests |
| 7 | +composer format # apply formatting |
| 8 | +composer lint |
| 9 | +composer analyze |
| 10 | +``` |
| 11 | + |
| 12 | +Mago is pinned to **1.47.4**, the newest published version verified for this upgrade. |
| 13 | +Update the pin deliberately and run the full checks before upgrading. Composer installs the |
| 14 | +platform-specific launcher; its first invocation downloads the matching binary. |
| 15 | +CI provides `GITHUB_TOKEN` for that download. Scripts invoke the project-local PHP |
| 16 | +launcher explicitly so an older system-wide binary cannot be used accidentally. |
| 17 | +There is no baseline. |
| 18 | + |
| 19 | +The formatter, linter, and analyzer have been run successfully with 1.47.4 against |
| 20 | +both configurations. On Windows, the Composer launcher needs PHP's ZIP extension |
| 21 | +and a configured trusted CA certificate bundle to download and extract its binary. |
| 22 | + |
| 23 | +`mago.toml` targets PHP 8.1 for library code. `mago-tests.toml` targets PHP 8.2 because |
| 24 | +some fixtures intentionally exercise readonly classes and traits; PHPUnit skips |
| 25 | +the applicable tests on PHP 8.1. Both configurations read dependency declarations |
| 26 | +without checking vendor code. Generated AOP cache and coverage files are excluded. |
| 27 | + |
| 28 | +The linter uses its default correctness, consistency, and maintainability checks. |
| 29 | +Exceptions in configuration are explicit design choices: mandatory strict types |
| 30 | +would change coercion behavior; named arguments and boolean flags are existing API |
| 31 | +choices; `isset` intentionally distinguishes null; aggregate complexity metrics |
| 32 | +are left to review. Analyzer missing-type checks are enabled. CI fails on all |
| 33 | +reported severities. No analyzer issue codes are ignored globally. |
| 34 | + |
| 35 | +The vendor type patch in `tools/mago/patches/CodeTransformerKernel.php` models its |
| 36 | +dependency injection callback as a generic extension point. The default remains |
| 37 | +the original one-argument callback returning a Transformer. AopKernel specializes |
| 38 | +it to its established two-argument callback returning an aspect or transformer. |
| 39 | +This replaces the previous callback suppression without changing runtime code or |
| 40 | +loosening TransformerManager's contract. `composer check-mago-types` checks valid |
| 41 | +callbacks and rejects scalar returns and incorrect default transformer callbacks. |
| 42 | +It runs as part of `composer check`, including in CI. Its deliberately invalid |
| 43 | +fixtures live in `tools/mago/tests` and are checked separately from library code. |
| 44 | + |
| 45 | +Two narrow `@mago-expect` annotations still cover four property-access diagnostics. |
| 46 | +These are explicit analyzer exceptions, not fixes to the analyzer's limitations: |
| 47 | + |
| 48 | +- Two property-access closures operate on a declaration validated through reflection. |
| 49 | + Mago cannot prove a runtime property name exists on the subject. Reference, scope, |
| 50 | + uninitialized-property, and unset behavior have runtime regression tests. |
| 51 | + |
| 52 | +These expectations name individual diagnostics at the affected operations. Mago |
| 53 | +reports an unfulfilled expectation if a future release stops producing a diagnostic, |
| 54 | +so stale exceptions fail CI. No baseline, file exclusions for these operations, or |
| 55 | +global analyzer diagnostic suppressions are used. |
| 56 | + |
| 57 | +An extension experiment confirmed that Mago 1.47.4 does not dispatch property type |
| 58 | +providers for these unresolved runtime operations. The experiment was discarded; |
| 59 | +no custom extension or issue filter is installed. |
| 60 | + |
| 61 | +Performance fixture generation now uses a shared service interface and validates |
| 62 | +generated service instantiation through reflection. Its construction work is part |
| 63 | +of the class-loading measurement; compare loading results only against runs using |
| 64 | +the same harness. The timed method-execution loop is unchanged. |
0 commit comments