Adding inline annotations

[dereuromark]

Sometimes you need to add those annotations manually:

/** @var \Queue\Model\Table\QueuedJobsTable $queuedJobsTable */
$queuedJobsTable = TableRegistry::getTableLocator()->get('Queue.QueuedJobs');

( in case you cannot or don't want to use ModelAwareTrait and loadModel() call )

And usually also the query results for all():

/** @var \App\Model\Entity\Module[] $modules */
$modules = $query->all()->toArray();

In order for the IDE/PHPStan/Psalm to know the collection item and autocomplete entity properties etc.

As well as first() calls:

/** @var \App\Model\Entity\AttributeValue $attributeValueToMove */
$attributeValueToMove = $this->AttributeValues->find()
            ->where(['attribute_id' => $attribute, 'position' => $oldPos])
            ->firstOrFail();
$attributeValueToMove->position = $newPos;

I am sure there are other use cases for inline annotations that are occurring over and over again.

We should try to find a way to auto fix that for us if we encounter such cases.
Since this is too complex for tokenizing, we will need a AST based tool here that also is able to modify code (similar to rector) etc.

[dereuromark]

This has been partially made possible, but on regex level, not static analyzer level
https://github.com/dereuromark/cakephp-ide-helper/releases/tag/1.17.0

So it only works convention based and with a high level of missing things as well as some false positives.
If someone has time to invest into AST based ideas, that would be awesome

[dereuromark]

#241
was an early experiment

with
#391
I try to include AST via Parser to have more correct findings (no false positives)

[dereuromark]

@rochamarcelo
A mixed approach of using PHPStan to find the places and info, and then using tokenized annotator to add/edit seems to work really fine out of the box:

   |          if ($uuid) {
   | +            /** @var \App\Model\Entity\CustomField $customField */
   |              $customField = $this->CustomFields->getByUuid($uuid);

<?php

namespace App\Annotator\ClassAnnotatorTask;

use Cake\Utility\Inflector;
use IdeHelper\Annotation\AnnotationFactory;
use IdeHelper\Annotation\VariableAnnotation;
use IdeHelper\Annotator\ClassAnnotatorTask\AbstractClassAnnotatorTask;
use IdeHelper\Annotator\ClassAnnotatorTask\ClassAnnotatorTaskInterface;
use PhpParser\Node;
use PhpParser\Node\Expr\Assign;
use PhpParser\Node\Expr\MethodCall;
use PhpParser\Node\Expr\PropertyFetch;
use PhpParser\Node\Expr\Variable;
use PhpParser\Node\Identifier;
use PhpParser\NodeTraverser;
use PhpParser\NodeVisitorAbstract;
use PhpParser\ParserFactory;

/**
 * Usage of getByUuid() should have inline annotations added.
 */
class TableGetAnnotatorTask extends AbstractClassAnnotatorTask implements ClassAnnotatorTaskInterface
{
    /**
     * @param string $path
     * @param string $content
     *
     * @return bool
     */
    public function shouldRun(string $path, string $content): bool
    {
        if (!str_contains($path, DS . 'src' . DS)) {
            return false;
        }

        return true;
    }

    /**
     * @param string $path
     *
     * @return bool
     */
    public function annotate(string $path): bool
    {
        $found = $this->findGetByUuidCalls();

        $result = true;
        foreach ($found as $row) {
            $annotations = [
                AnnotationFactory::createOrFail(
                    VariableAnnotation::TAG,
                    $row['entity'],
                    $row['var'],
                ),
            ];
            $result &= $this->annotateInlineContent($path, $this->content, $annotations, $row['line']);
        }

        return $result;
    }

    protected function findGetByUuidCalls(): array
    {
        $parser = (new ParserFactory())->createForNewestSupportedVersion();
        $ast = $parser->parse($this->content);

        $found = [];

        $traverser = new NodeTraverser();

        $traverser->addVisitor(new class ($found) extends NodeVisitorAbstract {
            protected array $found;

            /**
             * @param array $found
             */
            public function __construct(array &$found)
            {
                $this->found = &$found;
            }

            /**
             * @param \PhpParser\Node $node
             *
             * @return null
             */
            public function enterNode(Node $node): null
            {
                if (
                    $node instanceof Assign &&
                    $node->expr instanceof MethodCall &&
                    $node->expr->name instanceof Identifier &&
                    $node->expr->name->toString() === 'getByUuid'
                ) {
                    $varName = $node->var instanceof Variable ? $node->var->name : null;

                    $caller = $node->expr->var;
                    if (
                        $caller instanceof PropertyFetch &&
                        $caller->var instanceof Variable &&
                        $caller->var->name === 'this' &&
                        $caller->name instanceof Identifier
                    ) {
                        $modelName = $caller->name->toString();
                        //$entityName = Inflector::singularize($modelName);
                        //$entityClass = '\\App\\Model\\Entity\\' . ucfirst($entityName);
                        $entityClass = TableRegistry::getTableLocator()->get($modelName)->getEntityClass();

                        $this->found[] = [
                            'line' => $node->getStartLine(),
                            'var' => '$' . $varName,
                            'entity' => '\\' . $entityClass,
                        ];
                    }
                }

                return null;
            }
        });

        $traverser->traverse($ast);

        return $found;
    }
}