Introduce a @return-type-will-be-added annotation to indicate return type addition in next major; enforce with a PHPStan rule

Needs tests for the rule and some cleanup, but I am opening it for review of the concept.

This shows how adding the @return-type-will-be-added to some methods of ImageInterface, PHPStan identifies that the implementing methods on the concrete Image class need to get the return type.

Reverted changes to code that were meant to showcase the rule. The example pipeline were the PHPStan output is visible is https://git.drupalcode.org/issue/drupal-3486376/-/pipelines/333846

Added PHPUnit tests for the PHPSTan rule.

this makes the bot crash, i don't have 10G or ram on it

Wonder if this counts as an API change?

Or least warrants a CR?

Only moving to NR for the pipeline revert as not sure it's in scope.

If can rebase too since it's kinda older (sorry took so long to look at)

If you are another contributor eager to jump in, please allow the original poster @mondrake at least 48 hours to respond to feedback first, so they have the opportunity to finish what they started!

It certainly needs a CR to explain how to use the annotation, but let's get more reviews and consensus before writing one and letting it go stale because of later changes of direction.

The path addition in CI is needed to get the rule tested (HEAD is currently checking only changes to file in the base path of Drupal's PHPStan-related stuff).

The Symfony classloader proposed changes were closed without commit; this remains the only approach currently workable to address this issue.

BTW I am not even sure this is for core or rather for mglaman/phpstan-drupal.

Probably phpstan-drupal right?