Cap auto worker scaling at 20 processes

`auto` had no ceiling: with the scheduler already bounding the count by
the usable cores, `max(1, $cpuCores)` was no limit at all, so a
128-thread machine got 128 workers. The measurements behind the feature
show where the returns diminish - 8 to 16 workers cut wall time by a
third for 20 % more CPU time, 16 to 32 bought 6 % for 73 % more - and
memory grows with every worker, so stop at AUTO_PROCESSES_LIMIT and say
so in `diagnose`.

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

Author: ondrejmirtes

src/Parallel/Scheduler.php

@@ -21,6 +21,14 @@ final class Scheduler implements DiagnoseExtension
 
 	public const AUTO = 'auto';
 
+	/**
+	 * Where auto scaling stops, because the returns diminish: on a 16c/32t
+	 * workstation going from 8 to 16 workers cut wall time by a third for 20 %
+	 * more CPU time, 16 to 32 bought 6 % for 73 % more, and memory grows with
+	 * every worker (https://github.com/phpstan/phpstan-src/pull/6256).
+	 */
+	private const AUTO_PROCESSES_LIMIT = 20;
+
 	/** @var array{int, int, int, int, string}|null */
 	private ?array $storedData = null;
 
@@ -100,6 +108,13 @@ private function resolveMaximumNumberOfProcesses(int $cpuCores): array
 			return [$this->maximumNumberOfProcesses, 'configured'];
 		}
 
+		if ($cpuCores > self::AUTO_PROCESSES_LIMIT) {
+			return [
+				self::AUTO_PROCESSES_LIMIT,
+				sprintf('auto, capped at %d processes (%d usable CPU cores)', self::AUTO_PROCESSES_LIMIT, $cpuCores),
+			];
+		}
+
 		return [
 			max(1, $cpuCores),
 			sprintf('auto, limited by %d usable CPU cores', $cpuCores),

tests/PHPStan/Parallel/SchedulerTest.php

@@ -175,6 +175,16 @@ public function testAutoUsesAllUsableCores(): void
 		$this->assertSame(12, $schedule->getNumberOfProcesses());
 	}
 
+	public function testAutoIsCappedAtTheProcessLimit(): void
+	{
+		// 64 usable cores and 5000 files worth of jobs - auto stops where the
+		// returns diminish rather than spawning a worker per core
+		$scheduler = new Scheduler(20, Scheduler::AUTO, 2);
+		$schedule = $scheduler->scheduleWork(64, array_fill(0, 5000, 'file.php'), static fn (string $file): int => 0);
+
+		$this->assertSame(20, $schedule->getNumberOfProcesses());
+	}
+
 	public function testAutoIsStillCappedByTheJobCount(): void
 	{
 		// 40 files -> 2 jobs at size 20, at least 2 jobs per process -> a single