Re-analyse only the files using a symbol whose stub PHPDoc changed

A changed project stub file invalidated the whole result cache. Now a
file that uses a class or a function declared in a project stub file
records a dependency on that stub file, as it does for a scanned file.
When the stub file changes, the restore compares its exported nodes,
and only the files that depend on it are analysed again.

When the stub file declares other symbols than before, or nothing
depends on it, the whole cache is still invalidated: the files using a
newly stubbed symbol have no dependency on the stub file yet.

After a stub file changes, all project stub files are validated again,
because stub validation otherwise runs only in a full analysis.

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

Author: SanderMuller

.github/workflows/e2e-tests.yml

@@ -317,6 +317,43 @@ jobs:
               ../bashunit -a contains 'Scanned files with changed symbols (1); re-analysing the files affected by them.' "$OUTPUT"
               ../bashunit -a contains 'Result cache restored. 1 file will be reanalysed.' "$OUTPUT"
               ../bashunit -a contains 'Instantiated class ResultCacheE2EGenerated\Foo not found.' "$OUTPUT"
+          - script: |
+              cd e2e/result-cache-stub-edit
+              # A project stub file is a dependency of the files using the symbols it declares, so editing
+              # a PHPDoc in it re-analyses just those files. The expected lines come from a cold run.
+              OUTPUT=$(../bashunit -a exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit -a contains 'UseFoo::run() should return string but returns int.' "$OUTPUT"
+              patch -p0 < phpdoc-change.patch
+              OUTPUT=$(../bashunit -a exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit -a not_contains 'Result cache not used' "$OUTPUT"
+              ../bashunit -a contains 'UseChild::run() should return int but returns string.' "$OUTPUT"
+              ../bashunit -a not_contains 'UseFoo::run()' "$OUTPUT"
+              # A comment outside the PHPDocs changes nothing the analysed files see.
+              patch -p0 < comment-change.patch
+              OUTPUT=$(../bashunit -a exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit -a contains 'Result cache restored. 0 files will be reanalysed.' "$OUTPUT"
+              # The stub files are validated again, as in a full analysis.
+              patch -p0 < invalid-phpdoc.patch
+              OUTPUT=$(../bashunit -a exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit -a not_contains 'Result cache not used' "$OUTPUT"
+              ../bashunit -a contains 'Foo::get() has invalid return type ResultCacheE2EStubEdit\NotAClass.' "$OUTPUT"
+              ../bashunit -a contains 'UseFoo::run() should return string but returns ResultCacheE2EStubEdit\NotAClass.' "$OUTPUT"
+              patch -p0 -R < invalid-phpdoc.patch
+              OUTPUT=$(../bashunit -a exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit -a not_contains 'has invalid return type' "$OUTPUT"
+              ../bashunit -a contains 'UseChild::run() should return int but returns string.' "$OUTPUT"
+              # A class the stub file did not declare before: the files using it depend only on the file
+              # declaring it, so the whole result cache is invalidated.
+              patch -p0 < new-symbol.patch
+              OUTPUT=$(../bashunit -a exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit -a contains 'declares different symbols' "$OUTPUT"
+              ../bashunit -a contains 'UseBar::run() should return string but returns int.' "$OUTPUT"
           - script: |
               cd e2e/bug-15125
               composer install

.gitignore

@@ -21,5 +21,6 @@ e2e/bashunit
 /e2e/result-cache-moved-tmpdir/tmp-a
 /e2e/result-cache-moved-tmpdir/tmp-b
 /e2e/result-cache-stale-objects/tmp
+/e2e/result-cache-stub-edit/tmp
 /e2e/result-cache-truncated/tmp
 /e2e/result-cache-worker-count/tmp

e2e/result-cache-stub-edit/comment-change.patch

@@ -0,0 +1,10 @@
+--- stubs/Foo.stub
++++ stubs/Foo.stub
+@@ -2,6 +2,7 @@
+ 
+ namespace ResultCacheE2EStubEdit;
+ 
++// Foo is generated from a template.
+ class Foo
+ {
+ 

e2e/result-cache-stub-edit/invalid-phpdoc.patch

@@ -0,0 +1,11 @@
+--- stubs/Foo.stub
++++ stubs/Foo.stub
+@@ -6,7 +6,7 @@
+ class Foo
+ {
+ 
+-	/** @return string */
++	/** @return NotAClass */
+ 	public function get() {}
+ 
+ }

e2e/result-cache-stub-edit/new-symbol.patch

@@ -0,0 +1,14 @@
+--- stubs/Foo.stub
++++ stubs/Foo.stub
+@@ -10,3 +10,11 @@
+ 	public function get() {}
+ 
+ }
++
++class Bar
++{
++
++	/** @return int */
++	public function get() {}
++
++}

e2e/result-cache-stub-edit/phpdoc-change.patch

@@ -0,0 +1,11 @@
+--- stubs/Foo.stub
++++ stubs/Foo.stub
+@@ -5,7 +5,7 @@
+ class Foo
+ {
+ 
+-	/** @return int */
++	/** @return string */
+ 	public function get() {}
+ 
+ }

e2e/result-cache-stub-edit/phpstan.neon

@@ -0,0 +1,7 @@
+parameters:
+	level: 5
+	paths:
+		- src
+	stubFiles:
+		- stubs/Foo.stub
+	tmpDir: tmp

e2e/result-cache-stub-edit/src/Bar.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace ResultCacheE2EStubEdit;
+
+class Bar
+{
+
+	/** @return mixed */
+	public function get()
+	{
+		return 1;
+	}
+
+}

e2e/result-cache-stub-edit/src/Child.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace ResultCacheE2EStubEdit;
+
+class Child extends Foo
+{
+
+}

e2e/result-cache-stub-edit/src/Foo.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace ResultCacheE2EStubEdit;
+
+class Foo
+{
+
+	/** @return mixed */
+	public function get()
+	{
+		return 1;
+	}
+
+}