Cache degraded static analysis results when the version of PHP-Parser is exactly known

Author: sebastianbergmann

src/StaticAnalysis/CachingSourceAnalyser.php

@@ -94,11 +94,13 @@ public function analyse(string $sourceCodeFile, string $sourceCode, bool $useAnn
             $ignoreDeprecatedCode,
         );
 
-        // The version of PHP-Parser cannot always be determined exactly (see
-        // PhpParserVersion::id()), in which case a cached degraded result
-        // would outlive a PHP-Parser upgrade that adds support for the syntax
-        // that could not be parsed
-        if ($analysisResult->wasParsed()) {
+        // A degraded analysis result for a file that could not be parsed is
+        // only cached when the version of PHP-Parser is exactly known: the
+        // version is part of the cache key, so a PHP-Parser upgrade that adds
+        // support for the syntax that could not be parsed invalidates the
+        // cache entry. When the version is not exactly known, a cached
+        // degraded result could outlive such an upgrade.
+        if ($analysisResult->wasParsed() || PhpParserVersion::isExact()) {
             $this->write($cacheFile, $analysisResult);
         }
 

src/Util/PhpParserVersion.php

@@ -15,6 +15,7 @@
 use function filemtime;
 use function filesize;
 use function is_file;
+use function str_ends_with;
 use function str_starts_with;
 use function strlen;
 use function substr;
@@ -34,6 +35,7 @@ final class PhpParserVersion
      * @var ?non-empty-string
      */
     private static ?string $version = null;
+    private static bool $exact      = false;
 
     /**
      * Returns a string that identifies the version of nikic/php-parser that is
@@ -55,6 +57,20 @@ public static function id(): string
         return self::$version;
     }
 
+    /**
+     * Whether id() identifies the version of nikic/php-parser exactly:
+     * whenever the installed version of nikic/php-parser can change, id() is
+     * guaranteed to change as well. This does not hold for a version that was
+     * installed from a branch and has no source reference recorded, and it
+     * does not hold when the version cannot be determined at all.
+     */
+    public static function isExact(): bool
+    {
+        self::id();
+
+        return self::$exact;
+    }
+
     /**
      * @return ?non-empty-string
      */
@@ -110,12 +126,35 @@ private static function versionFromComposer(): string
         }
 
         if ($reference === null) {
+            self::$exact = self::isExactVersion($version);
+
             return $version;
         }
 
+        self::$exact = true;
+
         return $version . ' (' . $reference . ')';
     }
 
+    /**
+     * A version string identifies the installed code exactly when it carries
+     * a source reference or refers to an immutable release. A branch version
+     * such as "dev-main" or "5.6.x-dev" without a source reference does not:
+     * the branch can move without the version string changing.
+     */
+    private static function isExactVersion(string $version): bool
+    {
+        if (str_ends_with($version, ')')) {
+            return true;
+        }
+
+        if (str_starts_with($version, 'dev-')) {
+            return false;
+        }
+
+        return !str_ends_with($version, '-dev');
+    }
+
     /**
      * @codeCoverageIgnore
      *
@@ -138,6 +177,8 @@ private static function versionFromPharManifest(): string
                 $version = self::versionFromManifest($contents);
 
                 if ($version !== null) {
+                    self::$exact = self::isExactVersion($version);
+
                     return $version;
                 }
             }
@@ -147,6 +188,8 @@ private static function versionFromPharManifest(): string
         $size             = filesize($phar);
 
         if ($modificationTime !== false && $size !== false) {
+            self::$exact = true;
+
             return $phar . ':' . $modificationTime . ':' . $size;
         }
 

tests/tests/StaticAnalysis/CachingSourceAnalyserTest.php

@@ -12,10 +12,12 @@
 use const DIRECTORY_SEPARATOR;
 use function file_get_contents;
 use function sys_get_temp_dir;
+use function uniqid;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Group;
 use PHPUnit\Framework\Attributes\Small;
 use PHPUnit\Framework\Attributes\UsesClass;
+use SebastianBergmann\CodeCoverage\Util\PhpParserVersion;
 
 #[CoversClass(CachingSourceAnalyser::class)]
 #[UsesClass(ParsingSourceAnalyser::class)]
@@ -25,22 +27,33 @@
 #[Small]
 final class CachingSourceAnalyserTest extends SourceAnalyserTestCase
 {
-    public function testDoesNotCacheAnalysisResultForFileThatCannotBeParsed(): void
+    public function testCachesAnalysisResultForFileThatCannotBeParsedWhenVersionOfPhpParserIsExactlyKnown(): void
     {
+        if (!PhpParserVersion::isExact()) {
+            $this->markTestSkipped('The version of nikic/php-parser is not exactly known');
+        }
+
         $file   = TEST_FILES_PATH . 'source_that_cannot_be_parsed.php';
         $source = file_get_contents($file);
 
         if ($source === false) {
             $this->fail('Could not read ' . $file);
         }
 
-        $analyser = $this->cachingAnalyser();
+        $analyser = new CachingSourceAnalyser(
+            sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'php-code-coverage-caching-test-' . uniqid(),
+            new ParsingSourceAnalyser,
+        );
+
+        $firstResult  = $analyser->analyse($file, $source, true, true);
+        $secondResult = $analyser->analyse($file, $source, true, true);
 
-        $analyser->analyse($file, $source, true, true);
-        $analyser->analyse($file, $source, true, true);
+        $this->assertSame(1, $analyser->cacheHits());
+        $this->assertSame(1, $analyser->cacheMisses());
 
-        $this->assertSame(0, $analyser->cacheHits());
-        $this->assertSame(2, $analyser->cacheMisses());
+        $this->assertFalse($firstResult->wasParsed());
+        $this->assertFalse($secondResult->wasParsed());
+        $this->assertSame($firstResult->parseError(), $secondResult->parseError());
     }
 
     protected function analyser(): SourceAnalyser

tests/tests/Util/PhpParserVersionTest.php

@@ -33,6 +33,11 @@ public function testIdentifiesVersionOfPhpParserInstalledThroughComposer(): void
         $this->assertStringStartsWith($prettyVersion, $version);
     }
 
+    public function testVersionOfPhpParserInstalledThroughComposerIsExactlyKnown(): void
+    {
+        $this->assertTrue(PhpParserVersion::isExact());
+    }
+
     public function testExtractsVersionOfPhpParserFromPharManifest(): void
     {
         $manifest = "phpunit/phpunit: 13.3.0\nnikic/php-parser: 5.6.1 (abc1234)\nsebastian/version: 7.0.0\n";