Missing documentation for `Node`

[JakeQZ]

Bug report

I'm trying to write an extension to ignore alwaysTrue in assert()s.

I have

final class IgnoreBooleanAlways implements IgnoreErrorExtension
{
    public function shouldIgnore(Error $error, Node $node, Scope $scope): bool
    {
        $shouldIgnore = false;

        switch ($error->getIdentifier()) {
            case 'function.alreadyNarrowedType':
            case 'instanceof.alwaysTrue':
                $functionName = $scope->getFunctionName();
                error_log(var_export($functionName, true));
                error_log(get_class($node));
                $shouldIgnore = true;
                break;
        }

        return $shouldIgnore;
    }
}

The function name from $scope is the class method name, not the assert() function. So that's no use.

And Node does not seem to be documented properly. The classes logged are PhpParser\Node\Expr\FuncCall and PhpParser\Node\Expr\Instanceof_, neither of which appear in the documentation.

How can I programmatically determine if an alwaysTrue warning arises from within an assert() in order to discard it? Or is that not possible?

Code snippet that reproduces the problem

No response

Expected output

n/a

Did PHPStan help you today? Did it make you happy in any way?

No. The documentation was hard to find, and appears to be missing substantial parts. Better documentation on creating extensions is needed.

[mergeable]

This bug report is missing a link to reproduction at phpstan.org/try.

It will most likely be closed after manual review.

[JakeQZ]

This bug report is missing a link to reproduction at phpstan.org/try.

It will most likely be closed after manual review.

Not possible, since this is about extensions.

[VincentLanglet]

Node is coming from php parser https://github.com/nikic/PHP-Parser/blob/master/lib/PhpParser/Node.php

and you can find FuncCall https://github.com/nikic/PHP-Parser/blob/master/lib/PhpParser/Node/Expr/FuncCall.php

[ondrejmirtes]

Try to inspect https://apiref.phpstan.org/2.2.x/PHPStan.Analyser.Scope.html#_getFunctionCallStack (Scope::getFunctionCallStack()).

[JakeQZ]

Thanks both for your pointers. I had overlooked that PhpParser is a separate package. There is some documentation for it in the PHPStan documentation, but it's incomplete, which led to my confusion. Sorry, I put the wrong link in the OP.

If there's already an open ticket to complete the PhpParser documentation within the PHPStan documentation, then this can be closed.

With your much-appreciated help I have arrived at

use PhpParser\Node;
use PhpParser\Node\Expr\FuncCall;
use PhpParser\Node\Name;
use PHPStan\Analyser\Error;
use PHPStan\Analyser\IgnoreErrorExtension;
use PHPStan\Analyser\Scope;

final class IgnoreBooleanAlways implements IgnoreErrorExtension
{
    public function shouldIgnore(Error $error, Node $node, Scope $scope): bool
    {
        $shouldIgnore = false;

        switch ($error->getIdentifier()) {
            case 'function.alreadyNarrowedType':
                if ($node instanceof FuncCall) {
                    $nameNode = $node->name;
                    if ($nameNode instanceof Name && $nameNode->name === 'assert') {
                        $shouldIgnore = true;
                    }
                }
                break;
            case 'instanceof.alwaysTrue':
                $functionCallStack = $scope->getFunctionCallStack();
                if (isset($functionCallStack[0]) && $functionCallStack[0]->getName() === 'assert') {
                    $shouldIgnore = true;
                }
                break;
        }

        return $shouldIgnore;
    }
}

Now I just need to cater for

if ($impossibleConditionAccordingToDocBlock) {
    throw \Exception();
}

...

[ondrejmirtes]

I feel like this is sufficient documentation https://phpstan.org/developing-extensions/abstract-syntax-tree

[JakeQZ]

Job done, including tests, and in review: MyIntervals/emogrifier#1624

Would welcome any feedback.

And if you would like to use any of this as examples for the documentation, you would be more than welcome (though half of it is lifted from your documentation - I just had to figure out how to implement it, which was not without a challenge ;)).