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

@@ -353,6 +353,43 @@ jobs:
               ../bashunit assert contains 'Scanned files with changed symbols (1); re-analysing the files affected by them.' "$OUTPUT"
               ../bashunit assert contains 'Result cache restored. 1 file will be reanalysed.' "$OUTPUT"
               ../bashunit assert 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 assert exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit assert contains 'UseFoo::run() should return string but returns int.' "$OUTPUT"
+              patch -p0 < phpdoc-change.patch
+              OUTPUT=$(../bashunit assert exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit assert not_contains 'Result cache not used' "$OUTPUT"
+              ../bashunit assert contains 'UseChild::run() should return int but returns string.' "$OUTPUT"
+              ../bashunit assert not_contains 'UseFoo::run()' "$OUTPUT"
+              # A comment outside the PHPDocs changes nothing the analysed files see.
+              patch -p0 < comment-change.patch
+              OUTPUT=$(../bashunit assert exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit assert 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 assert exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit assert not_contains 'Result cache not used' "$OUTPUT"
+              ../bashunit assert contains 'Foo::get() has invalid return type ResultCacheE2EStubEdit\NotAClass.' "$OUTPUT"
+              ../bashunit assert contains 'UseFoo::run() should return string but returns ResultCacheE2EStubEdit\NotAClass.' "$OUTPUT"
+              patch -p0 -R < invalid-phpdoc.patch
+              OUTPUT=$(../bashunit assert exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit assert not_contains 'has invalid return type' "$OUTPUT"
+              ../bashunit assert 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 assert exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit assert contains 'declares different symbols' "$OUTPUT"
+              ../bashunit assert contains 'UseBar::run() should return string but returns int.' "$OUTPUT"
           - script: |
               cd e2e/bug-15125
               composer install

.gitignore

@@ -22,6 +22,7 @@ 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/restart-manager/probe.log

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;
+	}
+
+}