Notify in CI when a slow full analysis ran without a pre-existing result cache

.github/workflows/e2e-tests.yml

@@ -352,6 +352,20 @@ jobs:
               composer install
               ../../bin/phpstan -vvv
               ../../bin/phpstan -vvv
+          - script: |
+              cd e2e/result-cache-ci-notification
+              # https://github.com/phpstan/phpstan/issues/14881
+              # A slow full analysis in CI without a pre-existing result cache should hint
+              # the user to persist the result cache directory between runs.
+              ../../bin/phpstan clear-result-cache
+              OUTPUT=$(../../bin/phpstan analyse 2>&1)
+              echo "$OUTPUT"
+              ../bashunit -a contains 'Persist PHPStan' "$OUTPUT"
+              ../bashunit -a contains 'to make your pipeline dramatically faster' "$OUTPUT"
+              # The second run finds the cache present, so the hint is not shown again.
+              OUTPUT=$(../../bin/phpstan analyse 2>&1)
+              echo "$OUTPUT"
+              ../bashunit -a not_contains 'to make your pipeline dramatically faster' "$OUTPUT"
           - script: |
               cd e2e/bug-12606
               export CONFIGTEST=test

conf/config.neon

@@ -167,6 +167,7 @@ parameters:
 	resultCachePath: %tmpDir%/resultCache.php
 	resultCacheSkipIfOlderThanDays: 7
 	resultCacheChecksProjectExtensionFilesDependencies: false
+	resultCacheCiNotificationSeconds: 60
 	dynamicConstantNames:
 		- ICONV_IMPL
 		- LIBXML_VERSION

conf/parametersSchema.neon

@@ -161,6 +161,7 @@ parametersSchema:
 	resultCachePath: string()
 	resultCacheSkipIfOlderThanDays: int()
 	resultCacheChecksProjectExtensionFilesDependencies: bool()
+	resultCacheCiNotificationSeconds: int()
 	dynamicConstantNames: arrayOf(string())
 	customRulesetUsed: schema(bool(), nullable())
 	rootDir: string()

e2e/result-cache-ci-notification/phpstan.neon

@@ -0,0 +1,6 @@
+parameters:
+	level: 0
+	paths:
+		- src
+	# Notify already after 0 seconds so the slow-analysis condition is always met in the test.
+	resultCacheCiNotificationSeconds: 0

e2e/result-cache-ci-notification/src/Foo.php

@@ -0,0 +1,13 @@
+<?php declare(strict_types = 1);
+
+namespace ResultCacheCiNotificationE2E;
+
+class Foo
+{
+
+	public function bar(): int
+	{
+		return 1;
+	}
+
+}

src/Analyser/ResultCache/ResultCacheManager.php

@@ -117,6 +117,15 @@ public function __construct(
 	{
 	}
 
+	/**
+	 * Whether the result cache file was present on disk when PHPStan started.
+	 * Distinguishes "the cache never existed" from "the cache existed but was invalid".
+	 */
+	public function resultCacheExists(): bool
+	{
+		return is_file($this->cacheFilePath);
+	}
+
 	/**
 	 * @param string[] $allAnalysedFiles
 	 * @param mixed[]|null $projectConfigArray

src/Command/AnalyseApplication.php

@@ -71,6 +71,7 @@ public function analyse(
 			$fileReplacements = [$insteadOfFile => $tmpFile];
 		}
 		$resultCacheManager = $this->resultCacheManagerFactory->create($fileReplacements);
+		$resultCacheExisted = $resultCacheManager->resultCacheExists();
 
 		$ignoredErrorHelperResult = $this->ignoredErrorHelper->initialize();
 		$fileSpecificErrors = [];
@@ -190,6 +191,7 @@ public function analyse(
 			$isResultCacheUsed,
 			$changedProjectExtensionFilesOutsideOfAnalysedPaths,
 			$processedFiles,
+			$resultCacheExisted,
 		);
 	}
 

src/Command/AnalyseCommand.php

@@ -54,6 +54,7 @@
 use function is_bool;
 use function is_file;
 use function is_string;
+use function microtime;
 use function pathinfo;
 use function rewind;
 use function sprintf;
@@ -494,6 +495,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 				$analysisResult->isResultCacheUsed(),
 				$analysisResult->getChangedProjectExtensionFilesOutsideOfAnalysedPaths(),
 				$analysisResult->getProcessedFiles(),
+				$analysisResult->resultCacheExisted(),
 			);
 
 			$exitCode = $errorFormatter->formatErrors($analysisResult, $inceptionResult->getStdOutput());
@@ -650,6 +652,13 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 			}
 		}
 
+		$this->reportMissingResultCacheInCi(
+			$errorOutput,
+			$analysisResult,
+			$onlyFiles,
+			$container->getParameter('resultCacheCiNotificationSeconds'),
+		);
+
 		$this->runDiagnoseExtensions($container, $inceptionResult->getErrorOutput(), $analysisResult->getProcessedFiles());
 
 		return $inceptionResult->handleReturn(
@@ -659,6 +668,31 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 		);
 	}
 
+	private function reportMissingResultCacheInCi(Output $errorOutput, AnalysisResult $analysisResult, bool $onlyFiles, int $resultCacheCiNotificationSeconds): void
+	{
+		if (
+			$onlyFiles
+			|| $analysisResult->isResultCacheUsed()
+			|| $analysisResult->resultCacheExisted()
+		) {
+			return;
+		}
+
+		if (microtime(true) - $this->analysisStartTime < $resultCacheCiNotificationSeconds) {
+			return;
+		}
+
+		if (!(new CiDetector())->isCiDetected()) {
+			return;
+		}
+
+		$errorOutput->writeLineFormatted('<comment>Tip: This CI run analysed your whole project from scratch, which is why it was slow.</comment>');
+		$errorOutput->writeLineFormatted('Persist PHPStan\'s result cache directory between CI runs to make your pipeline dramatically faster.');
+		$errorOutput->writeLineFormatted('Only changed files and their dependencies are re-analysed, so most runs finish in a fraction of the time.');
+		$errorOutput->writeLineFormatted('Learn how to set it up: https://phpstan.org/user-guide/result-cache');
+		$errorOutput->writeLineFormatted('');
+	}
+
 	private function createStreamOutput(): StreamOutput
 	{
 		$resource = fopen('php://memory', 'w', false);

src/Command/AnalysisResult.php

@@ -39,6 +39,7 @@ public function __construct(
 		private bool $isResultCacheUsed,
 		private array $changedProjectExtensionFilesOutsideOfAnalysedPaths,
 		private array $processedFiles = [],
+		private bool $resultCacheExisted = true,
 	)
 	{
 		usort(
@@ -142,6 +143,16 @@ public function isResultCacheUsed(): bool
 		return $this->isResultCacheUsed;
 	}
 
+	/**
+	 * Whether the result cache file existed when PHPStan started.
+	 * False means the cache was never created; a stale/invalid cache that
+	 * triggered a full re-analysis still counts as existing.
+	 */
+	public function resultCacheExisted(): bool
+	{
+		return $this->resultCacheExisted;
+	}
+
 	/**
 	 * @return array<string, string>
 	 */
@@ -177,6 +188,7 @@ public function withFileSpecificErrors(array $fileSpecificErrors): self
 			$this->isResultCacheUsed,
 			$this->changedProjectExtensionFilesOutsideOfAnalysedPaths,
 			$this->processedFiles,
+			$this->resultCacheExisted,
 		);
 	}