feat(type-aliases): file-local generic type aliases via compile-time substitution

[math3usmartins]

Adds compile-time type aliases to xphp — a reusable name for a type, generic or not. An alias is a compile-time substitution: it is expanded into its body before specialization and has no runtime existence, so the emitted PHP never mentions the alias name and there is no runtime cost.

type UserId     = Ident;               // non-generic
type Pair<A, B> = Dict<A, Bag<B>>;     // generic
type Num        = int|string;          // union body
type MaybeUser  = ?User;               // nullable body

A use is replaced by its expanded body and then monomorphized exactly as if the body had been written by hand — Pair<int, User> records and specializes the same Dict<int, Bag<User>> an explicit type would, with no separate code path.

[greptile-apps]

Greptile Summary

This PR adds file-local compile-time type aliases to xphp (type Name[<A,B>] = Body;), expanding alias references into their bodies before monomorphization so the emitted PHP never mentions the alias name. Supported body forms are single-head (generic or not), union (int|string), and nullable (?Box); intersection, DNF, and closure-signature bodies are rejected.

• Core expansion engine (XphpSourceParser): scan strips type … ; declarations to whitespace, builds a per-file alias table, and a new expandAliasToUnion / expandAlias pair replaces every alias reference in the AST with its resolved body before normal monomorphization proceeds. Cycle detection threads the $visited chain through both body expansion and argument expansion (line 4184), catching type A<T> = Bag<A<T>>-style argument-path cycles in addition to direct body cycles.
• Deferred bound validation (AliasBoundObligation*/AliasBoundValidator): because the TypeHierarchy does not exist at parse time, alias-parameter bounds are captured as obligations during parsing and verified in a single post-hierarchy pass, reusing the same Registry::checkAliasBounds seam as generic classes.
• Error coverage: six stable diagnostic codes (xphp.alias_cycle, xphp.alias_arity, xphp.alias_duplicate, xphp.alias_class_collision, xphp.alias_unsupported_body, xphp.alias_compound_in_non_slot) are thrown in compile mode and collected in check mode, with dedicated integration tests for each rejection path including the argument-path cycle variant.

Confidence Score: 5/5

Safe to merge — both previously flagged P1 issues are confirmed fixed and only P2-level observations remain.

Both prior P1 findings have been resolved: argument expansion now correctly threads $visited through expandAlias (preventing silent infinite expansion on arg-path alias cycles), and the unsupported-body error message no longer incorrectly lists union/nullable bodies. The two remaining observations (PHP keyword types array/callable unsupported in alias bodies, and the asymmetric empty-$visited passed from buildBoundExprNode) are P2-level and both have architectural justifications. Test coverage in TypeAliasIntegrationTest is thorough, including an explicit test for the previously-flagged argument-cycle case.

Files Needing Attention: No files require special attention. XphpSourceParser.php is the largest and most complex changed file but the logic is well-tested.

Important Files Changed

Filename	Overview
src/Transpiler/Monomorphize/XphpSourceParser.php	Core of the PR: adds ~750 lines for alias scanning, table-building, and AST-level expansion. Cycle detection correctly threads $visited through argument expansion (addressing the prior argument-path cycle concern). Two separate cycle-detection mechanisms (visited chain for body-path, inFlight flag for bound-path) are both sound. PHP keyword types array/callable silently fail as alias bodies due to isNameToken token-ID filtering.
src/Transpiler/Monomorphize/AliasBoundObligation.php	New value object capturing a deferred alias-parameter bound obligation (typeParams + padded args + label + location). Simple and correct.
src/Transpiler/Monomorphize/AliasBoundObligationCollector.php	New collector that accumulates obligations and provides absorb() for per-file isolation — a failed file's obligations are dropped rather than validated against a hierarchy that no longer contains its types.
src/Transpiler/Monomorphize/AliasBoundValidator.php	New stateless validator that iterates obligations and delegates to Registry::checkAliasBounds, reusing the identical bound-check seam as generic classes.
src/Transpiler/Monomorphize/Compiler.php	Threads AliasBoundObligationCollector through both compile() and check() pipelines, calling AliasBoundValidator::validate after the hierarchy is built. Per-file obligation isolation in check() is correctly implemented.
src/Transpiler/Monomorphize/Registry.php	Adds checkAliasBounds static method — a thin wrapper around the existing checkBounds/groundSiblingBounds machinery so alias-parameter bound errors surface as identical xphp.bound_violation diagnostics.
src/Transpiler/Monomorphize/XphpParseException.php	Minor addition: optional stable diagnostic code attached to the exception, enabling check-mode to report alias-specific codes (e.g. xphp.alias_cycle) rather than the generic parse-error code.
test/Transpiler/Monomorphize/TypeAliasIntegrationTest.php	709-line integration test suite covering all supported alias forms (generic, non-generic, concrete-instantiation, union body, nullable body, transitive alias), all six error codes, both compile and check modes, and the argument-path cycle variant (the previously-flagged P1 case).
test/fixture/compile/type_aliases/source/Types.xphp	Runtime fixture exercising generic, non-generic, concrete-instantiation, union-body, and nullable-body aliases with real specializations; verifiable via runtime.php.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Source .xphp file"] --> B["scanAndStrip()\nDetect & blank 'type Name = Body;'\nRecord aliasMarkers"]
    B --> C["nikic/php-parser\nParse cleaned source -> AST"]
    C --> D["buildAliasTable()\nFQN -> {params, body}\nReject: duplicate / class-collision / null body"]
    D --> E["resolveAndAttach() traversal\nleaveNode(Name)"]
    E --> F{"Name in\naliasTable?"}
    F -->|No| G["Leave node unchanged"]
    F -->|Yes| H["expandAliasToUnion(ref, visited, line)"]
    H --> I{"Visited\ncycle?"}
    I -->|Yes| J["Throw alias_cycle"]
    I -->|No| K["padAliasArgs -> resolveAliasBody\ncaptureAliasBoundObligation"]
    K --> L{"union\nmembers?"}
    L -->|1 member| M["Return single TypeRef node"]
    L -->|2+ members| N{"ATTR_ALIAS_WHOLE_SLOT\nset?"}
    N -->|Yes| O["Build UnionType / NullableType node"]
    N -->|No| P["Throw alias_compound_in_non_slot"]
    K --> Q["Expand body members recursively\nwith updated visited chain"]
    Q --> H
    R["AliasBoundObligationCollector\nper-file obligations"] --> S["AliasBoundValidator.validate()\nafter TypeHierarchy built"]
    S --> T{"Bound\nviolated?"}
    T -->|compile| U["Throw bound_violation"]
    T -->|check| V["Collect diagnostic"]

Loading

_{Reviews (2): Last reviewed commit: "fix(monomorphize): correct alias-body me..." | Re-trigger Greptile}