[PostRector] Skip inline {@see } used use statement on remove unused imports (#8080)

* [PostRector] Skip inline {@see } used use statement on remove unused imports

* [ci-review] Rector Rectify

* add support for uses and used-by

* [ci-review] Rector Rectify

* skip fqcn inline {@see \FQCN}

* alias fix

* final touch: fqcn is not reference to any use statements

* final touch: eof

* final touch: avoid regex lookup when no { char found

---------

Co-authored-by: GitHub Action <actions@github.com>

Author: samsonasik

src/BetterPhpDocParser/PhpDocInfo/PhpDocInfo.php

@@ -4,6 +4,7 @@
 
 namespace Rector\BetterPhpDocParser\PhpDocInfo;
 
+use Nette\Utils\Strings;
 use PHPStan\PhpDocParser\Ast\ConstExpr\ConstFetchNode;
 use PHPStan\PhpDocParser\Ast\Node;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ExtendsTagValueNode;
@@ -34,6 +35,7 @@
 use Rector\BetterPhpDocParser\ValueObject\Type\ShortenedIdentifierTypeNode;
 use Rector\Exception\ShouldNotHappenException;
 use Rector\PhpDocParser\PhpDocParser\PhpDocNodeTraverser;
+use Rector\StaticTypeMapper\Naming\NameScopeFactory;
 use Rector\StaticTypeMapper\StaticTypeMapper;
 use Rector\Validation\RectorAssert;
 use Webmozart\Assert\InvalidArgumentException;
@@ -43,6 +45,11 @@
  */
 final class PhpDocInfo
 {
+    /**
+     * @see https://regex101.com/r/7GCrlj/2
+     */
+    private const string INLINE_GENERIC_USES_CLASS_REFERENCE_REGEX = '#\{@(?:uses|used-by|see)\s+(?<class_name>[^}\s]+)#';
+
     /**
      * @var array<class-string<PhpDocTagValueNode>, string>
      */
@@ -66,7 +73,8 @@ public function __construct(
         private readonly StaticTypeMapper $staticTypeMapper,
         private readonly \PhpParser\Node $node,
         private readonly AnnotationNaming $annotationNaming,
-        private readonly PhpDocNodeByTypeFinder $phpDocNodeByTypeFinder
+        private readonly PhpDocNodeByTypeFinder $phpDocNodeByTypeFinder,
+        private readonly NameScopeFactory $nameScopeFactory
     ) {
         $this->originalPhpDocNode = clone $phpDocNode;
 
@@ -480,6 +488,32 @@ public function getGenericTagClassNames(): array
         return $resolvedClasses;
     }
 
+    /**
+     * @return string[]
+     */
+    public function getInlineGenericUsesTagClassNames(): array
+    {
+        $printedPhpDocNode = (string) $this->phpDocNode;
+        if (! str_contains($printedPhpDocNode, '{')) {
+            return [];
+        }
+
+        $matches = Strings::matchAll($printedPhpDocNode, self::INLINE_GENERIC_USES_CLASS_REFERENCE_REGEX);
+
+        $classNames = [];
+        foreach ($matches as $match) {
+            $reference = $match['class_name'];
+            $resolvedClassNames = $this->resolveInlineGenericUsesReferenceClassNames($reference);
+            if ($resolvedClassNames === []) {
+                continue;
+            }
+
+            $classNames = [...$classNames, ...$resolvedClassNames];
+        }
+
+        return array_unique($classNames);
+    }
+
     /**
      * @return string[]
      */
@@ -556,6 +590,40 @@ private function resolveNameForPhpDocTagValueNode(PhpDocTagValueNode $phpDocTagV
         return null;
     }
 
+    /**
+     * @return string[]
+     */
+    private function resolveInlineGenericUsesReferenceClassNames(string $reference): array
+    {
+        $reference = explode('|', $reference, 2)[0];
+        $reference = explode('::', $reference, 2)[0];
+
+        $referenceToResolve = $reference;
+        $reference = ltrim($reference, '\\');
+
+        try {
+            RectorAssert::className($reference);
+        } catch (InvalidArgumentException) {
+            return [];
+        }
+
+        // fqcn not reference to any use statements
+        if (str_starts_with($referenceToResolve, '\\')) {
+            return [$referenceToResolve];
+        }
+
+        $nameScope = $this->nameScopeFactory->createNameScopeFromNodeWithoutTemplateTypes($this->node);
+        $resolvedClassName = $nameScope->resolveStringName($referenceToResolve);
+
+        if (str_contains($reference, '\\')) {
+            // Keep both forms: resolved class for namespace-aware matching and original class
+            // for alias-partial matching in unused import checks.
+            return array_unique([$resolvedClassName, $reference]);
+        }
+
+        return [$resolvedClassName];
+    }
+
     private function getTypeOrMixed(?PhpDocTagValueNode $phpDocTagValueNode): MixedType | Type
     {
         if (! $phpDocTagValueNode instanceof PhpDocTagValueNode) {

src/BetterPhpDocParser/PhpDocInfo/PhpDocInfoFactory.php

@@ -16,6 +16,7 @@
 use Rector\BetterPhpDocParser\ValueObject\PhpDocAttributeKey;
 use Rector\BetterPhpDocParser\ValueObject\StartAndEnd;
 use Rector\NodeTypeResolver\Node\AttributeKey;
+use Rector\StaticTypeMapper\Naming\NameScopeFactory;
 use Rector\StaticTypeMapper\StaticTypeMapper;
 
 final class PhpDocInfoFactory
@@ -31,7 +32,8 @@ public function __construct(
         private readonly BetterPhpDocParser $betterPhpDocParser,
         private readonly StaticTypeMapper $staticTypeMapper,
         private readonly AnnotationNaming $annotationNaming,
-        private readonly PhpDocNodeByTypeFinder $phpDocNodeByTypeFinder
+        private readonly PhpDocNodeByTypeFinder $phpDocNodeByTypeFinder,
+        private readonly NameScopeFactory $nameScopeFactory
     ) {
     }
 
@@ -127,7 +129,8 @@ private function createFromPhpDocNode(
             $this->staticTypeMapper,
             $node,
             $this->annotationNaming,
-            $this->phpDocNodeByTypeFinder
+            $this->phpDocNodeByTypeFinder,
+            $this->nameScopeFactory
         );
 
         $node->setAttribute(AttributeKey::PHP_DOC_INFO, $phpDocInfo);

src/PostRector/Rector/UnusedImportRemovingPostRector.php

@@ -169,6 +169,9 @@ private function findNamesInDocBlocks(Namespace_|FileNode $rootNode): array
                 $genericTagClassNames = $phpDocInfo->getGenericTagClassNames();
                 $names = [...$names, ...$genericTagClassNames];
 
+                $inlineGenericUsesTagClassNames = $phpDocInfo->getInlineGenericUsesTagClassNames();
+                $names = [...$names, ...$inlineGenericUsesTagClassNames];
+
                 $arrayItemTagClassNames = $phpDocInfo->getArrayItemNodeClassNames();
                 $names = [...$names, ...$arrayItemTagClassNames];
             }

tests/Issues/NamespacedUseAutoImport/Fixture/fqcn_inline_see.php.inc

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\Issues\NamespacedUseAutoImport\Fixture;
+
+use Rector\Tests\Issues\NamespacedUse\Source\SomeClass;
+
+final class FqcnInlineSee
+{
+    /**
+     * See {@see \Rector\Tests\Issues\NamespacedUse\Source\SomeClass::$property} for more information.
+     */
+    public function test(): void {}
+}
+
+?>
+-----
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\Issues\NamespacedUseAutoImport\Fixture;
+
+final class FqcnInlineSee
+{
+    /**
+     * See {@see \Rector\Tests\Issues\NamespacedUse\Source\SomeClass::$property} for more information.
+     */
+    public function test(): void {}
+}
+
+?>

tests/Issues/NamespacedUseAutoImport/Fixture/skip_inline_see.php.inc

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\Issues\NamespacedUseAutoImport\Fixture;
+
+use Rector\Tests\Issues\NamespacedUse\Source\SomeClassFirst;
+use Rector\Tests\Issues\NamespacedUse\Source\SomeClassSecond;
+use Rector\Tests\Issues\NamespacedUse\Source\SomeClassThird;
+
+final class SkipInlineSee
+{
+    /**
+     * See {@uses SomeClassFirst} for more information.
+     * See {@used-by SomeClassSecond::test()} for more information.
+     * See {@see SomeClassThird::$property} for more information.
+     */
+    public function test(): void {}
+}

tests/Issues/NamespacedUseAutoImport/Fixture/skip_inline_see_prefixed_partial_alias.php.inc

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\Issues\NamespacedUseAutoImport\Fixture;
+
+use Rector\Tests\Issues\NamespacedUseAutoImport as Alias;
+
+final class SkipInlineSeePrefixedPartialAlias
+{
+    /**
+     * See {@see Alias\Source\SomeClass} for more information.
+     */
+    public function test(): void {}
+}