Sort the result cache's package dependencies before writing them

Every other section of the file is ordered before it is written; this one
followed the order the workers happened to finish in, so two identical runs
of a 4524-file project produced caches of the same size differing in 9848
lines. A run reading the file back does not care, but it means a result
cache cannot be hashed, deduplicated or compared between machines.

The packages of a single file need the same treatment: they are collected in
the order that file's dependencies are reflected, so a file naming Mailer
before Logger records their packages in that order.

The e2e fixture makes both observable without depending on a race. Four
files are split into two parallel jobs, so the section reaches the main
process interleaved and no worker completion order can put it in ascending
order by accident; and each file declares the two packages in reverse
alphabetical order. Dropping either sort fails the assertion on every run,
naming what is out of order.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: SanderMuller

.github/workflows/e2e-tests.yml

@@ -930,6 +930,17 @@ jobs:
               echo "$OUTPUT"
               ../bashunit -a contains 'Composer packages changed (test/logger); re-analysing the files depending on them and the files with errors.' "$OUTPUT"
               ../bashunit -a contains 'Result cache restored. 1 file will be reanalysed.' "$OUTPUT"
+          - script: |
+              cd e2e/result-cache-deterministic-order
+              composer install
+              # Nothing in the written file may depend on the order the parallel workers happened to
+              # finish in: a result cache that is not reproducible cannot be hashed, compared or
+              # deduplicated between two machines. The fixture splits four files into two jobs, so no
+              # completion order puts them in ascending order by accident, and assert-sorted.php fails
+              # if any entry section of the cache is out of key order.
+              ../../bin/phpstan analyse
+              OUTPUT=$(php assert-sorted.php tmp/resultCache.php 2>&1) || { echo "$OUTPUT"; exit 1; }
+              echo "$OUTPUT"
           - script: |
               cd e2e/result-cache-path-repository
               composer install

e2e/result-cache-deterministic-order/.gitignore

@@ -0,0 +1,2 @@
+/vendor
+/composer.lock

e2e/result-cache-deterministic-order/assert-sorted.php

@@ -0,0 +1,107 @@
+<?php declare(strict_types = 1);
+
+// Reads the framed result cache and fails if any of its entry sections is not in key order.
+// The order the workers happen to finish in must not reach the file: a cache that is not
+// reproducible cannot be hashed, compared or deduplicated between two machines.
+
+$path = $argv[1] ?? null;
+if ($path === null || !is_file($path)) {
+	fwrite(STDERR, sprintf("Result cache %s does not exist.\n", $path ?? '<missing argument>'));
+	exit(1);
+}
+
+$handle = fopen($path, 'r');
+if ($handle === false) {
+	fwrite(STDERR, sprintf("Cannot open %s.\n", $path));
+	exit(1);
+}
+
+fgets($handle); // the PHP prefix line that keeps the file inert when included
+
+$unsorted = [];
+$sections = 0;
+$packageLists = [];
+while (($header = fgets($handle)) !== false) {
+	$header = rtrim($header, "\n");
+	if ($header === '') {
+		continue;
+	}
+
+	$parts = explode(' ', $header, 2);
+	if (count($parts) !== 2) {
+		fwrite(STDERR, sprintf("Malformed frame header \"%s\".\n", $header));
+		exit(1);
+	}
+
+	[$name, $size] = $parts;
+	if (!str_ends_with($name, '*')) {
+		fread($handle, (int) $size);
+
+		continue;
+	}
+
+	$name = substr($name, 0, -1);
+	$keys = [];
+	for ($i = 0; $i < (int) $size; $i++) {
+		$length = (int) rtrim((string) fgets($handle), "\n");
+		$entry = unserialize((string) fread($handle, $length));
+		$key = (string) array_key_first($entry);
+		$keys[] = $key;
+		if ($name !== 'packageDependencies') {
+			continue;
+		}
+
+		// The packages of one file are collected in the order its dependencies are reflected,
+		// so their order has to be fixed too, not just the order of the files. Unlike the key
+		// order, this does not depend on how the scheduler composes jobs, so it still fails
+		// without the sort even when the whole project runs as a single job.
+		$packageLists[$key] = $entry[array_key_first($entry)];
+	}
+
+	$sections++;
+	$sorted = $keys;
+	sort($sorted, SORT_STRING);
+	if ($keys === $sorted) {
+		continue;
+	}
+
+	$unsorted[$name] = $keys;
+}
+
+fclose($handle);
+
+if ($sections === 0) {
+	fwrite(STDERR, "The result cache has no entry sections, so nothing was checked.\n");
+	exit(1);
+}
+
+if ($packageLists === []) {
+	fwrite(STDERR, "The result cache recorded no package dependencies, so nothing was checked.\n");
+	exit(1);
+}
+
+$problems = [];
+foreach ($unsorted as $name => $keys) {
+	$problems[] = sprintf('Section "%s" is not in key order: %s', $name, implode(', ', array_map('basename', $keys)));
+}
+
+foreach ($packageLists as $file => $packages) {
+	$sortedPackages = $packages;
+	sort($sortedPackages, SORT_STRING);
+	if ($packages === $sortedPackages) {
+		continue;
+	}
+
+	$problems[] = sprintf('The packages of %s are not in order: %s', basename($file), implode(', ', $packages));
+}
+
+if ($problems !== []) {
+	fwrite(STDERR, implode("\n", $problems) . "\n");
+	exit(1);
+}
+
+echo sprintf(
+	"All %d entry sections of the result cache are in key order, and so are the packages of all %d files that have package dependencies.\n",
+	$sections,
+	count($packageLists),
+);

e2e/result-cache-deterministic-order/composer.json

@@ -0,0 +1,26 @@
+{
+	"name": "phpstan/result-cache-deterministic-order-e2e",
+	"repositories": [
+		{
+			"type": "path",
+			"url": "./logger",
+			"options": {
+				"symlink": false
+			}
+		},
+		{
+			"type": "path",
+			"url": "./mailer",
+			"options": {
+				"symlink": false
+			}
+		}
+	],
+	"require": {
+		"test/logger": "*",
+		"test/mailer": "*"
+	},
+	"autoload": {
+		"classmap": ["src"]
+	}
+}

e2e/result-cache-deterministic-order/logger/composer.json

@@ -0,0 +1 @@
+{ "name": "test/logger", "version": "1.0.0", "autoload": { "classmap": ["src"] } }

e2e/result-cache-deterministic-order/logger/src/Logger.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Test\Logger;
+
+class Logger
+{
+
+	public function info(string $message): void
+	{
+	}
+
+}

e2e/result-cache-deterministic-order/mailer/composer.json

@@ -0,0 +1 @@
+{ "name": "test/mailer", "version": "1.0.0", "autoload": { "classmap": ["src"] } }

e2e/result-cache-deterministic-order/mailer/src/Mailer.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Test\Mailer;
+
+class Mailer
+{
+
+	public function send(string $message): void
+	{
+	}
+
+}

e2e/result-cache-deterministic-order/phpstan.neon

@@ -0,0 +1,12 @@
+parameters:
+	level: 5
+	tmpDir: tmp
+	paths:
+		- src
+	parallel:
+		# Two jobs of two files each, so the four files reach the main process interleaved
+		# (F1, F3 in one job, F2, F4 in the other) and no worker completion order can put
+		# them in ascending order by accident.
+		jobSize: 2
+		maximumNumberOfProcesses: 4
+		minimumNumberOfJobsPerProcess: 1

e2e/result-cache-deterministic-order/src/F1.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace ResultCacheDeterministicOrderE2E;
+
+use Test\Logger\Logger;
+use Test\Mailer\Mailer;
+
+// Mailer is declared before Logger on purpose: the packages of one file are collected in the
+// order its dependencies are reflected, so without a sort this file records test/mailer first.
+class F1
+{
+
+	public function __construct(private Mailer $mailer, private Logger $logger)
+	{
+	}
+
+	public function doFoo(): void
+	{
+		$this->mailer->send('hello');
+		$this->logger->info('hello');
+	}
+
+}