phan: Improve phpunit stub munging (#37164)

In Psalm, `@psalm-assert Foo $arg` asserts both that if the function
doesn't throw then the argument is an instance of Foo _and_ that if the
function does throw then the argument is not an instance of Foo. If you
want only the first without the second, you do `@psalm-assert =Foo $arg`
instead.

Phan, on the other hand, never makes the inverse assumption. So
effectively `@phan-assert Foo $arg` is equivalent to
`@psalm-assert =Foo $arg`, and trying to `@phan-assert =Foo` is a syntax
error.

Thus, when we're munging the phpunit annotations, the `=` needs to be
stripped when converting `@psalm-assert` to `@phan-assert`. This will
allow Phan to infer correct types for `assertInstanceOf()` and
`assertSame()`.

.phan/stubs/phpunit-stubs.php

@@ -825,7 +825,7 @@ final public static function assertObjectNotHasProperty(string $propertyName, ob
      *
      * @phan-param ExpectedType $expected
      *
-     * @phan-assert =ExpectedType $actual
+     * @phan-assert ExpectedType $actual
      */
     public static function assertSame($expected, $actual, string $message = ''): void
     {
@@ -852,7 +852,7 @@ public static function assertNotSame($expected, $actual, string $message = ''):
      *
      * @phan-param class-string<ExpectedType> $expected
      *
-     * @phan-assert =ExpectedType $actual
+     * @phan-assert ExpectedType $actual
      */
     public static function assertInstanceOf(string $expected, $actual, string $message = ''): void
     {
@@ -2773,7 +2773,7 @@ function assertObjectNotHasProperty(string $attributeName, object $object, strin
  *
  * @phan-param ExpectedType $expected
  *
- * @phan-assert =ExpectedType $actual
+ * @phan-assert ExpectedType $actual
  *
  * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
  *
@@ -2808,7 +2808,7 @@ function assertNotSame($expected, $actual, string $message = '', ...$func_get_ar
  *
  * @phan-param class-string<ExpectedType> $expected
  *
- * @phan-assert =ExpectedType $actual
+ * @phan-assert ExpectedType $actual
  *
  * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
  *

projects/packages/changelogger/changelog/fix-phan-phpunit-stubs

@@ -0,0 +1,5 @@
+Significance: patch
+Type: fixed
+Comment: Suppress a Phan issue in a test now that Phan infers classes from assertInstanceOf(). No change to functionality.
+
+

projects/packages/changelogger/src/Application.php

@@ -19,7 +19,7 @@
  */
 class Application extends SymfonyApplication {
 
-	const VERSION = '4.2.2';
+	const VERSION = '4.2.3-alpha';
 
 	/**
 	 * Constructor.

projects/packages/changelogger/tests/php/tests/src/ConfigTest.php

@@ -356,6 +356,7 @@ class_alias( DummyPluginImpl::class, \Automattic\Jetpack\Changelogger\Plugins\Fo
 				'filename' => 'dummy.php',
 				'option'   => 'value',
 			),
+			// @phan-suppress-next-line PhanUndeclaredClassProperty -- Same.
 			$ret->c
 		);
 

tools/stubs/munge-phpunit-stubs.php

@@ -18,6 +18,9 @@
 		'@psalm-template'  => '@phan-template',
 		'@psalm-var'       => '@phan-var',
 		'@psalm-immutable' => '@phan-side-effect-free', // https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-immutable vs https://github.com/phan/phan/wiki/Annotating-Your-Source-Code#phan-side-effect-free-on-classes
+
+		// Psalm allows asserting "=Foo" versus "Foo", with the difference being that with "=Foo" does not imply "!Foo" when the call throws. Phan doesn't make that assumption in any case.
+		'@psalm-assert ='  => '@phan-assert ',
 	)
 );