LRU-cap resolved local type aliases in UsefulTypeAliasResolver

[ondrejmirtes]

Problem

UsefulTypeAliasResolver::$resolvedLocalTypeAliases caches every resolved @phpstan-type local alias forever, keyed by Class::alias. Resolved alias Types transitively pin ClassReflections (ObjectType::$classReflection, EnumCaseObjectType::$classReflection, …) and through them whole BetterReflection trees.

Retention-path instrumentation on the ShipMonk backend named this cache as the single largest type-level pin of the reflection universe — a sampled path:

ReflectionNamedType ← ReflectionEnum ← ClassReflection
  ← EnumCaseObjectType::$classReflection ← UnionType
  ← UsefulTypeAliasResolver::$resolvedLocalTypeAliases[]

Types are stronger pins than reflections themselves: bounding this one cache freed more memory than bounding any reflection-side cache in the same experiment series.

Change

Cap $resolvedLocalTypeAliases at 2048 entries with LRU eviction (move-to-end on hit, evict-first on insert). Evicted aliases are re-resolved on demand — pure recomputation. Global aliases are untouched (bounded by config).

Measured (2,358-file project, single process)

• −34 MB end-of-run memory (largest single win in the prototype series that reached −76 MB / −8% total together with Replace PhpClassReflectionExtension::evictPrivateSymbols() with a shared LRU over the member caches #5986/LRU-cap the per-class reflection registries and resolved local type aliases #5988)
• error output byte-identical (89/776 errors on two configs; the project uses local aliases heavily)
• no measurable time cost: interleaved A/B capped vs uncapped, 100 s vs 95 s (within environmental noise)

The 2048 cap could be promoted to a cache.* parameter if desired.

Tests: LocalTypeAliasesRuleTest + type-alias NSRT assertions pass; phpcs clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NrTvR9j1mW2NNNC8RkuTsF

Configurability + default (added)

The cap is now a cache.* parameter (cache.resolvedLocalTypeAliasesCountMax, default 2048, 0 disables eviction), following the phpStormStubsNodesCountMax pattern.

The default comes from a cap sweep on the 2,358-file project (all LRU caps set to the sweep value, single process, error output identical — 776 — at every point):

cap	elapsed	end usage
512	101 s	936.5 MB
1024	93 s	912.5 MB
2048	88 s	880.5 MB
4096	84 s	894.5 MB
8192	92 s	930.6 MB
unlimited	98 s	930.5 MB

The curve is U-shaped: too-small caps are actively harmful — evicted entries are recreated as fresh object graphs while the old copies are still pinned by sibling caches, so duplicates accumulate (this also explains why very small caps regressed memory on large projects before). Too-large caps converge to unbounded retention. Elapsed time shows no trend across the whole range — the knob trades memory only, so 2048 is chosen purely on the memory optimum.

[ondrejmirtes]

Combined into #5988 per review preference.