Mark throwable methods as pure (#3171)

* Write stub as valid PHP

This works probably because it is not parsed by PHP but by something
more tolerant, but let's make it more valid (the final access type in
the signature is not valid) PHP anyway, that will raise fewer eyebrows.

* Document actual return type

See ca006e54e3/Zend/zend_exceptions.stub.php (L8)

* Mark all methods from Throwable as mutation free

Exception is the only possible class implementation of Throwable, and
all of its methods except __toString() are final.
See ca006e54e3/Zend/zend_exceptions.stub.php (L3-L25)

Closes #3170

src/Psalm/Internal/Stubs/CoreImmutableClasses.phpstub

@@ -21,7 +21,37 @@ interface Throwable
     /**
      * @psalm-mutation-free
      */
-    public final function getMessage() : string {}
+    public final function getMessage() : string;
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getCode() : int;
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getFile() : string;
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getLine() : int;
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getTrace() : array;
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getPrevious() : ?Throwable;
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getTraceAsString() : string;
 }
 
 class Exception implements Throwable
@@ -61,21 +91,33 @@ class Exception implements Throwable
 
     /**
      * @psalm-mutation-free
-     * @return int|string
      */
-    public final function getCode(){}
+    public final function getCode(): int {}
 
     /**
      * @psalm-mutation-free
-     * @return string
      */
-    public final function getFile(){}
+    public final function getFile(): string {}
 
     /**
      * @psalm-mutation-free
-     * @return int
      */
-    public final function getLine(){}
+    public final function getLine(): int {}
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getTrace() : array {}
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getPrevious() : ?Throwable {}
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getTraceAsString() : string {}
 }
 
 class Error implements Throwable
@@ -115,19 +157,31 @@ class Error implements Throwable
 
     /**
      * @psalm-mutation-free
-     * @return int|string
      */
-    public final function getCode(){}
+    public final function getCode(): int {}
 
     /**
      * @psalm-mutation-free
-     * @return string
      */
-    public final function getFile(){}
+    public final function getFile(): string {}
 
     /**
      * @psalm-mutation-free
-     * @return int
      */
-    public final function getLine(){}
+    public final function getLine(): int{}
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getTrace() : array {}
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getPrevious() : ?Throwable {}
+
+    /**
+     * @psalm-mutation-free
+     */
+    public final function getTraceAsString() : string {}
 }

tests/PureAnnotationTest.php

@@ -210,6 +210,72 @@ class PureAnnotationTest extends TestCase
 
                     echo getMessage(new Exception("test"));'
             ],
+            'exceptionGetCode' => [
+                '<?php
+                    /**
+                     * @psalm-pure
+                     */
+                    function getCode(Throwable $e): int {
+                        return $e->getCode();
+                    }
+
+                    echo getCode(new Exception("test"));'
+            ],
+            'exceptionGetFile' => [
+                '<?php
+                    /**
+                     * @psalm-pure
+                     */
+                    function getFile(Throwable $e): string {
+                        return $e->getFile();
+                    }
+
+                    echo getFile(new Exception("test"));'
+            ],
+            'exceptionGetLine' => [
+                '<?php
+                    /**
+                     * @psalm-pure
+                     */
+                    function getLine(Throwable $e): int {
+                        return $e->getLine();
+                    }
+
+                    echo getLine(new Exception("test"));'
+            ],
+            'exceptionGetTrace' => [
+                '<?php
+                    /**
+                     * @psalm-pure
+                     */
+                    function getTrace(Throwable $e): array {
+                        return $e->getTrace();
+                    }
+
+                    echo count(getTrace(new Exception("test")));'
+            ],
+            'exceptionGetPrevious' => [
+                '<?php
+                    /**
+                     * @psalm-pure
+                     */
+                    function getPrevious(Throwable $e): ?Throwable {
+                        return $e->getPrevious();
+                    }
+
+                    echo gettype(getPrevious(new Exception("test")));'
+            ],
+            'exceptionGetTraceAsString' => [
+                '<?php
+                    /**
+                     * @psalm-pure
+                     */
+                    function getTraceAsString(Throwable $e): string {
+                        return $e->getTraceAsString();
+                    }
+
+                    echo getTraceAsString(new Exception("test"));'
+            ],
         ];
     }