Try inline annotations for first()/firstOrFail() on magic finders.

composer.json

@@ -35,6 +35,7 @@
 		"cakephp/bake": "^3.0.4",
 		"cakephp/cakephp": "^5.1.5",
 		"phpstan/phpdoc-parser": "^2.1.0",
+		"nikic/php-parser": "^5.5",
 		"sebastian/diff": "^5.0 || ^6.0 || ^7.0",
 		"squizlabs/php_codesniffer": "^3.11"
 	},
@@ -68,8 +69,7 @@
 	},
 	"config": {
 		"allow-plugins": {
-			"cakephp/plugin-installer": true,
-			"dealerdirect/phpcodesniffer-composer-installer": true
+			"cakephp/plugin-installer": true
 		}
 	},
 	"scripts": {

src/Annotator/ClassAnnotatorTask/TableFindAnnotatorTask.php

@@ -0,0 +1,147 @@
+<?php
+
+namespace IdeHelper\Annotator\ClassAnnotatorTask;
+
+use Cake\Utility\Inflector;
+use IdeHelper\Annotation\AnnotationFactory;
+use IdeHelper\Annotation\UsesAnnotation;
+use PhpParser\Comment\Doc;
+use PhpParser\Node;
+use PhpParser\Node\Expr\Assign;
+use PhpParser\NodeTraverser;
+use PhpParser\NodeVisitorAbstract;
+use PhpParser\ParserFactory;
+use PhpParser\PrettyPrinter\Standard;
+use Throwable;
+
+/**
+ * Usage of find() or findOrFail() should have inline annotations added.
+ */
+class TableFindAnnotatorTask extends AbstractClassAnnotatorTask implements ClassAnnotatorTaskInterface {
+
+	/**
+	 * Deprecated: $content, use $this->content instead.
+	 *
+	 * @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 {
+		$parser = (new ParserFactory())->createForHostVersion();
+		try {
+			$ast = $parser->parse($this->content);
+			$tokens = $parser->getTokens();
+			$originalAst = $ast;
+		} catch (Throwable $e) {
+			trigger_error($e);
+
+			return false;
+		}
+
+		$array = [];
+
+		$traverser = new NodeTraverser();
+		$traverser->addVisitor(new class($array) extends NodeVisitorAbstract {
+			private array $array;
+
+			/**
+			 * @param array $array
+			 */
+			public function __construct(array &$array) {
+				$this->array = &$array;
+			}
+
+			/**
+			 * @param \PhpParser\Node $node
+			 * @return \PhpParser\Node|null
+			 */
+			public function enterNode(Node $node): ?Node {
+				if ($node instanceof Assign && $node->expr instanceof Node\Expr\MethodCall) {
+					$methodCall = $node->expr;
+
+					// Check for ->first() or ->firstOrFail()
+					if (
+						$methodCall->name instanceof Node\Identifier &&
+						in_array($methodCall->name->toString(), ['first', 'firstOrFail'])
+					) {
+						$method = $methodCall->name->toString();
+
+						// Traverse back to $this->TableName->find()
+						$callChain = $methodCall->var;
+						while ($callChain instanceof Node\Expr\MethodCall) {
+							$callChain = $callChain->var;
+						}
+
+						if (
+							$callChain instanceof Node\Expr\PropertyFetch &&
+							$callChain->var instanceof Node\Expr\Variable &&
+							$callChain->var->name === 'this' &&
+							$callChain->name instanceof Node\Identifier
+						) {
+							$tableName = $callChain->name->toString(); // e.g., "Residents"
+							$varName = ($node->var instanceof Node\Expr\Variable && is_string($node->var->name))
+								                ? $node->var->name
+							                : 'unknown';
+
+							$entityName = Inflector::singularize($tableName);
+							$entityClass = '\\App\\Model\\Entity\\' . $entityName;
+							$nullable = $method === 'first' ? '|null' : '';
+							$doc = new Doc("/** @var {$entityClass}{$nullable} \${$varName} */");
+							$node->setDocComment($doc);
+
+							$this->array[] = [
+								'line' => $node->getStartLine(),
+								'content' => $doc->getText(),
+								'varName' => $varName,
+								'tableName' => $tableName,
+								'entityName' => $entityName,
+							];
+						}
+					}
+				}
+
+				return null;
+			}
+		});
+
+		$modifiedAst = $traverser->traverse($ast);
+		$printer = new Standard();
+		$modifiedCode = $printer->printFormatPreserving(
+			$modifiedAst,
+			$originalAst,
+			$tokens,
+		);
+
+		debug($array);
+		dd($modifiedCode);
+
+		//return $this->annotateInlineContent($path, $this->content, $annotations, $rowToAnnotate);
+	}
+
+	/**
+	 * @param array<string> $classes
+	 * @return array<\IdeHelper\Annotation\AbstractAnnotation>
+	 */
+	protected function buildUsesAnnotations(array $classes): array {
+		$annotations = [];
+
+		foreach ($classes as $className) {
+			$annotations[] = AnnotationFactory::createOrFail(UsesAnnotation::TAG, '\\' . $className);
+		}
+
+		return $annotations;
+	}
+
+}

tests/TestCase/Annotator/ClassAnnotatorTask/TableFindAnnotatorTaskTest.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace IdeHelper\Test\TestCase\Annotator\ClassAnnotatorTask;
+
+use Cake\Console\ConsoleIo;
+use IdeHelper\Annotator\AbstractAnnotator;
+use IdeHelper\Annotator\ClassAnnotatorTask\TableFindAnnotatorTask;
+use IdeHelper\Console\Io;
+use Shim\TestSuite\ConsoleOutput;
+use Shim\TestSuite\TestCase;
+
+class TableFindAnnotatorTaskTest extends TestCase {
+
+	protected ConsoleOutput $out;
+
+	protected ConsoleOutput $err;
+
+	protected ?Io $io = null;
+
+	/**
+	 * @return void
+	 */
+	protected function setUp(): void {
+		parent::setUp();
+
+		$this->out = new ConsoleOutput();
+		$this->err = new ConsoleOutput();
+		$consoleIo = new ConsoleIo($this->out, $this->err);
+		$this->io = new Io($consoleIo);
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testShouldRun() {
+		$task = $this->getTask('');
+
+		$result = $task->shouldRun('/src/Foo.php', '');
+		$this->assertTrue($result);
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testAnnotate() {
+		$content = file_get_contents(TEST_FILES . 'ClassAnnotation/TableFind/before.php');
+		$task = $this->getTask($content);
+		$path = '/src/Controller/TestMeController.php';
+
+		$result = $task->annotate($path);
+		$this->assertTrue($result);
+
+		$content = $task->getContent();
+		dd($content);
+		$this->assertTextContains('/** @var \App\Model\Entity\Resident $resident */', $content);
+
+		$output = $this->out->output();
+		$this->assertTextContains('  -> 1 annotation added.', $output);
+	}
+
+	/**
+	 * @param string $content
+	 * @param array $params
+	 *
+	 * @return \IdeHelper\Annotator\ClassAnnotatorTask\TableFindAnnotatorTask
+	 */
+	protected function getTask(string $content, array $params = []) {
+		$params += [
+			AbstractAnnotator::CONFIG_DRY_RUN => true,
+			AbstractAnnotator::CONFIG_VERBOSE => true,
+		];
+
+		return new TableFindAnnotatorTask($this->io, $params, $content);
+	}
+
+}

tests/test_files/ClassAnnotation/TableFind/before.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Controller;
+
+use Cake\ORM\Locator\LocatorAwareTrait;
+
+/** @property \Cake\ORM\Table $Residents */
+class TestMeController
+{
+	use LocatorAwareTrait;
+
+	public function test(): void {
+		$residentsTable = $this->fetchTable('Residents');
+		$resident = $residentsTable->find(
+			'all',
+			[
+				'contain' => ['Units', 'Rooms'],
+			],
+		)->first();
+
+		$residentOther = $residentsTable->find(
+			'all',
+			[
+				'contain' => ['Units', 'Rooms'],
+			],
+		)->firstOrFail();
+
+		$residentX = $this->Residents->find(
+			'all',
+			[
+				'contain' => ['Units', 'Rooms'],
+			],
+		)->first();
+
+		$residentY = $this->Residents->find(
+			'all',
+			[
+				'contain' => ['Units', 'Rooms'],
+			],
+		)->firstOrFail();
+	}
+
+}