[Enhancement] Emit an error when phpdoc is impossible

[mr-feek]

https://psalm.dev/r/af5065a4c0

Given that bar has a native return type of string, shouldn't psalm be able to emit an error that the phpdoc is invalid? I'm thinking that phpdoc should only become the source of truth if there are no native typehints or the typehints are castable to each other..

[psalm-github-bot]

I found these snippets:

https://psalm.dev/r/af5065a4c0

<?php

/**
* @method array bar()
*/
interface Foo
{
    public function bar(): string;
}

function test(Foo $foo): string
{
    return $foo->bar();
}

Psalm output (using commit 38d3b15):

ERROR: InvalidReturnStatement - 13:12 - The inferred type 'array<array-key, mixed>' does not match the declared return type 'string' for test

ERROR: InvalidReturnType - 11:26 - The declared return type 'string' for test is incorrect, got 'array<array-key, mixed>'

[weirdan]

I think it should be consistent with @return: https://psalm.dev/r/cba0b4b5a3, i.e. trust the docblock but emit MismatchingDocblock issue

[psalm-github-bot]

I found these snippets:

https://psalm.dev/r/cba0b4b5a3

<?php

/**
* @method array bar()
*/
interface Foo
{
    public function bar(): string;
    
    /** @return array */
    public function baz(): string;
}

function test(Foo $foo): string
{
    if (rand(0, 1)) {
        return $foo->bar();
    } else {
        return $foo->baz();
    }
}

Psalm output (using commit 38d3b15):

ERROR: InvalidReturnStatement - 17:16 - The inferred type 'array<array-key, mixed>' does not match the declared return type 'string' for test

ERROR: InvalidReturnStatement - 19:16 - The inferred type 'array<array-key, mixed>' does not match the declared return type 'string' for test

ERROR: InvalidReturnType - 14:26 - The declared return type 'string' for test is incorrect, got 'array<array-key, mixed>'

ERROR: MismatchingDocblockReturnType - 10:17 - Docblock has incorrect return type 'array<array-key, mixed>', should be 'string'

[orklah]

I think this is a duplicate of #5786

[weirdan]

We don't have any inheritance here, so the only possible developer intent is to clarify native return type. This makes it very clear that contradiction is a different problem to LSP violations that linked ticket discusses.

[orklah]

https://psalm.dev/r/af5065a4c0 emits a MismatchingDocblockReturnType now, so it should be okay now

[psalm-github-bot]

I found these snippets:

https://psalm.dev/r/af5065a4c0

<?php

/**
* @method array bar()
*/
interface Foo
{
    public function bar(): string;
}

function test(Foo $foo): string
{
    return $foo->bar();
}

Psalm output (using commit be92afa):

ERROR: InvalidReturnStatement - 13:12 - The inferred type 'array<array-key, mixed>' does not match the declared return type 'string' for test

ERROR: InvalidReturnType - 11:26 - The declared return type 'string' for test is incorrect, got 'array<array-key, mixed>'

ERROR: MismatchingDocblockReturnType - 4:11 - The inherited return type 'string' for Foo::bar is different to the corresponding @method annotation 'array<array-key, mixed>'