Reinstate MethodSignatureMustProvideReturnType

It's never emitted, but is there for BC.

config.xsd

@@ -331,6 +331,7 @@
             <xs:element name="LoopInvalidation" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="MethodSignatureMismatch" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="MethodSignatureMustOmitReturnType" type="IssueHandlerType" minOccurs="0" />
+            <xs:element name="MethodSignatureMustProvideReturnType" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="MismatchingDocblockParamType" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="MismatchingDocblockPropertyType" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="MismatchingDocblockReturnType" type="IssueHandlerType" minOccurs="0" />

docs/running_psalm/error_levels.md

@@ -56,6 +56,7 @@ Level 5 and above allows a more non-verifiable code, and higher levels are even
  - [InvalidThrow](issues/InvalidThrow.md)
  - [LoopInvalidation](issues/LoopInvalidation.md)
  - [MethodSignatureMustOmitReturnType](issues/MethodSignatureMustOmitReturnType.md)
+ - [MethodSignatureMustProvideReturnType](issues/MethodSignatureMustProvideReturnType.md)
  - [MissingDependency](issues/MissingDependency.md)
  - [MissingFile](issues/MissingFile.md)
  - [MissingImmutableAnnotation](issues/MissingImmutableAnnotation.md)

docs/running_psalm/issues.md

@@ -99,6 +99,7 @@
  - [LoopInvalidation](issues/LoopInvalidation.md)
  - [MethodSignatureMismatch](issues/MethodSignatureMismatch.md)
  - [MethodSignatureMustOmitReturnType](issues/MethodSignatureMustOmitReturnType.md)
+ - [MethodSignatureMustProvideReturnType](issues/MethodSignatureMustProvideReturnType.md)
  - [MismatchingDocblockParamType](issues/MismatchingDocblockParamType.md)
  - [MismatchingDocblockPropertyType](issues/MismatchingDocblockPropertyType.md)
  - [MismatchingDocblockReturnType](issues/MismatchingDocblockReturnType.md)

docs/running_psalm/issues/MethodSignatureMustProvideReturnType.md

@@ -0,0 +1,16 @@
+# MethodSignatureMustProvideReturnType
+
+In PHP 8.1+, [most non-final internal methods now require overriding methods to declare a compatible return type, otherwise a deprecated notice is emitted during inheritance validation](https://www.php.net/manual/en/migration81.incompatible.php#migration81.incompatible.core.type-compatibility-internal).  
+
+This issue is emitted when a method overriding a native method is defined without a return type.  
+
+**Only if** the return type cannot be declared to keep support for PHP 7, a `#[ReturnTypeWillChange]` attribute can be added to silence the PHP deprecation notice and Psalm issue.  
+
+```php
+<?php
+class A implements JsonSerializable {
+    public function jsonSerialize() {
+        return ['type' => 'A'];
+    }
+}
+```

src/Psalm/Issue/MethodSignatureMustProvideReturnType.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Psalm\Issue;
+
+class MethodSignatureMustProvideReturnType extends CodeIssue
+{
+    public const ERROR_LEVEL = -1;
+    public const SHORTCODE = 282;
+}

tests/DocumentationTest.php

@@ -289,6 +289,10 @@ public function providerInvalidCodeParse(): array
                 case 'TraitMethodSignatureMismatch':
                     continue 2;
 
+                /** @todo reinstate this test when the issue is restored */
+                case 'MethodSignatureMustProvideReturnType':
+                    continue 2;
+
                 case 'InvalidFalsableReturnType':
                     $ignored_issues = ['FalsableReturnStatement'];
                     break;