Raise CachedParser source-byte cap to 4 MB, add eviction floor, make it configurable

The 512 KB cap from bf4d513 effectively shrank the 256-entry LRU to
~45 entries on WordPress: its hot working set includes 25 files over
100 KB (formatting.php, post.php, functions.php, ...) that everything
else pulls in through reflection, so all evictions were size-based and
the hottest files were re-parsed 100x per run. The WordPress
integration-test PHPStan step regressed from ~105 s to ~150 s (+42%);
locally +39% user CPU (274 s vs 197 s uncapped).

Sweep on WordPress (user CPU / median worker peak memory):
512 KB 274 s / 250 MB, 1 MB 250 s / 268 MB, 2 MB 225 s / 316 MB,
4 MB 199 s / 400 MB, uncapped 197 s / 542 MB. A typical project
(phpstan-src itself) has a natural LRU appetite of only 1.3 MB and is
unconstrained by the new default either way.

Since both the memory cost of a cached entry and the CPU cost of
re-parsing it scale with its source size, the value-per-byte of an
entry is its access frequency alone - eviction order should stay
recency-based, and the byte cap is only a memory safety net, so it must
be generous enough to hold a big project's hot working set.

The new eviction floor guarantees minimum residency: without it, a
single source larger than the whole cap would flush the entire cache on
every insertion, degenerating the cache to one entry when such sources
are hot.

The cap is exposed as cache.nodesByStringSourceBytesMax (0 = unlimited)
alongside the other cache limits.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012SoHaGT1YXNue8VzSKT7aG

Author: ondrejmirtes

conf/config.neon

@@ -124,6 +124,7 @@ parameters:
 	internalErrorsCountLimit: 50
 	cache:
 		nodesByStringCountMax: 256
+		nodesByStringSourceBytesMax: 4194304
 		resolvedPhpDocBlockCacheCountMax: 2048
 		nameScopeMapMemoryCacheCountMax: 512
 		phpStormStubsNodesCountMax: 128

conf/parametersSchema.neon

@@ -148,6 +148,7 @@ parametersSchema:
 	internalErrorsCountLimit: int()
 	cache: structure([
 		nodesByStringCountMax: int(),
+		nodesByStringSourceBytesMax: int(),
 		resolvedPhpDocBlockCacheCountMax: int(),
 		nameScopeMapMemoryCacheCountMax: int(),
 		phpStormStubsNodesCountMax: int(),

conf/parsers.neon

@@ -69,6 +69,7 @@ services:
 		arguments:
 			originalParser: @pathRoutingParser
 			cachedNodesByStringCountMax: %cache.nodesByStringCountMax%
+			cachedSourceBytesMax: %cache.nodesByStringSourceBytesMax%
 		autowired: false
 
 	freshStubParser:
@@ -82,4 +83,5 @@ services:
 		arguments:
 			originalParser: @freshStubParser
 			cachedNodesByStringCountMax: %cache.nodesByStringCountMax%
+			cachedSourceBytesMax: %cache.nodesByStringSourceBytesMax%
 		autowired: false

src/Parser/CachedParser.php

@@ -11,12 +11,12 @@ final class CachedParser implements Parser
 {
 
 	/**
-	 * The AST of a parsed file takes up roughly 50-60x more memory
-	 * than the source code itself. Together with the entry count limit,
-	 * this caps the total source size of the cached ASTs so that a few
-	 * large files cannot pin hundreds of megabytes in each worker process.
+	 * Size-based eviction never shrinks the cache below this many entries.
+	 * Without this floor, a single source larger than $cachedSourceBytesMax
+	 * would flush the whole cache on every insertion, degenerating the cache
+	 * to a single entry whenever such a source is hot.
 	 */
-	private const CACHED_SOURCE_BYTES_LIMIT = 524_288;
+	private const SIZE_EVICTION_FLOOR_LIMIT = 32;
 
 	/** @var array<string, Node\Stmt[]>*/
 	private array $cachedNodesByString = [];
@@ -28,9 +28,19 @@ final class CachedParser implements Parser
 	/** @var array<string, true> */
 	private array $parsedByString = [];
 
+	/**
+	 * The AST of a parsed file takes up roughly 50-60x more memory than the
+	 * source code itself, so alongside the entry count limit, the total source
+	 * size of the cached ASTs is capped by $cachedSourceBytesMax (0 = unlimited)
+	 * so that large files cannot pin hundreds of megabytes in each worker
+	 * process. The cap has to be generous enough to hold a big project's hot
+	 * working set (WordPress needs ~4 MB) because evicting a hot file costs
+	 * a re-parse proportional to the very bytes the eviction saved.
+	 */
 	public function __construct(
 		private Parser $originalParser,
 		private int $cachedNodesByStringCountMax,
+		private int $cachedSourceBytesMax,
 	)
 	{
 	}
@@ -105,7 +115,11 @@ private function evictLeastRecentlyUsed(int $incomingSourceBytes): void
 
 		while (
 			$this->cachedNodesByStringCount >= $this->cachedNodesByStringCountMax
-			|| $this->cachedSourceBytes + $incomingSourceBytes > self::CACHED_SOURCE_BYTES_LIMIT
+			|| (
+				$this->cachedSourceBytesMax > 0
+				&& $this->cachedSourceBytes + $incomingSourceBytes > $this->cachedSourceBytesMax
+				&& $this->cachedNodesByStringCount > self::SIZE_EVICTION_FLOOR_LIMIT
+			)
 		) {
 			$oldestKey = array_key_first($this->cachedNodesByString);
 			if ($oldestKey === null) {

tests/PHPStan/Parser/CachedParserTest.php

@@ -11,6 +11,7 @@
 use PHPStan\Testing\PHPStanTestCase;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\MockObject\Stub;
+use function sprintf;
 
 class CachedParserTest extends PHPStanTestCase
 {
@@ -24,6 +25,7 @@ public function testParseFileClearCache(
 		$parser = new CachedParser(
 			$this->getParserStub(),
 			$cachedNodesByStringCountMax,
+			1048576,
 		);
 
 		$this->assertSame(
@@ -63,6 +65,57 @@ public static function dataParseFileClearCache(): Generator
 		];
 	}
 
+	public function testSourceBytesLimitEvictsAboveFloor(): void
+	{
+		// byte capacity (5000 / 100 = 50 entries) binds before the count limit (500)
+		$parser = new CachedParser($this->getParserStub(), 500, 5000);
+
+		for ($i = 0; $i < 100; $i++) {
+			$parser->parseString(sprintf('%0100d', $i));
+		}
+
+		$this->assertSame(50, $parser->getCachedNodesByStringCount());
+	}
+
+	public function testSourceBytesLimitNeverEvictsBelowFloor(): void
+	{
+		// byte capacity (1000 / 100 = 10 entries) is below the floor of 32,
+		// so the floor wins and the cache keeps growing to 32 + 1 entries
+		$parser = new CachedParser($this->getParserStub(), 500, 1000);
+
+		for ($i = 0; $i < 100; $i++) {
+			$parser->parseString(sprintf('%0100d', $i));
+		}
+
+		$this->assertSame(33, $parser->getCachedNodesByStringCount());
+	}
+
+	public function testSourceLargerThanBytesLimitDoesNotFlushCache(): void
+	{
+		$parser = new CachedParser($this->getParserStub(), 500, 5000);
+
+		for ($i = 0; $i < 20; $i++) {
+			$parser->parseString(sprintf('%0100d', $i));
+		}
+		$this->assertSame(20, $parser->getCachedNodesByStringCount());
+
+		// an entry bigger than the whole byte limit must not evict the
+		// resident entries (count is below the floor) and is cached itself
+		$parser->parseString(sprintf('%010000d', 0));
+		$this->assertSame(21, $parser->getCachedNodesByStringCount());
+	}
+
+	public function testSourceBytesLimitZeroMeansUnlimited(): void
+	{
+		$parser = new CachedParser($this->getParserStub(), 500, 0);
+
+		for ($i = 0; $i < 100; $i++) {
+			$parser->parseString(sprintf('%0100d', $i));
+		}
+
+		$this->assertSame(100, $parser->getCachedNodesByStringCount());
+	}
+
 	private function getParserStub(): Parser&Stub
 	{
 		$mock = $this->createStub(Parser::class);
@@ -88,7 +141,7 @@ public function testParseTheSameFileWithDifferentMethod(): void
 			self::getContainer()->getService('php8Parser'),
 			null,
 		);
-		$parser = new CachedParser($pathRoutingParser, 500);
+		$parser = new CachedParser($pathRoutingParser, 500, 4194304);
 		$path = $fileHelper->normalizePath(__DIR__ . '/data/test.php');
 		$pathRoutingParser->setAnalysedFiles([$path]);
 		$contents = FileReader::read($path);
@@ -134,7 +187,7 @@ public function testWithExprCacheHelper(): void
 			self::getContainer()->getService('php8Parser'),
 			null,
 		);
-		$parser = new CachedParser($pathRoutingParser, 500);
+		$parser = new CachedParser($pathRoutingParser, 500, 4194304);
 		$path = $fileHelper->normalizePath(__DIR__ . '/data/parser-cache-bug.php');
 		$pathRoutingParser->setAnalysedFiles([$path]);
 		$contents = FileReader::read($path);