Support generic trait @use tags in class-level PHPDocs

[misenhower]

Hey there, I'm looking to add this so I can put all my @use statements at the top of the class, rather than on each use statement in the class body. Just a nice visual clean-up.

This supersedes #2638, which targeted the v1.x branch.

There are a few failing tests, but I think they might be preexisting issues.

This was all from claude/codex so let me know if there are any issues!

Notes from Codex below:

---

Closes phpstan/phpstan#7486

Summary

Allow generic trait @use annotations to be placed on the PHPDoc of the class-like using the trait:

/**
 * @use GenericTrait<string>
 */
final class Example
{
    use GenericTrait;
}

Previously, PHPStan only used annotations attached directly to the trait-use statement. Some PHPDoc consumers do not support that placement, making it difficult to share these annotations across tools.

This change:

• Uses class-level @use, @template-use, and @phpstan-use tags for generic trait type resolution.
• Preserves existing statement-level behavior, with a matching statement-level annotation taking precedence.
• Adds a separate rule to validate class-level annotations, as proposed in the issue.
• Includes referenced class-level annotation types in dependency tracking.
• Covers multiple traits, nested traits, invalid and unmatched annotations, template forwarding, enums, prefixed tags, and imported trait aliases.
• Adds type-inference and diagnostic regression tests.

Statement-level annotations remain fully supported:

final class Example
{
    /** @use GenericTrait<string> */
    use GenericTrait;
}

Validation

• vendor/bin/phpunit tests/PHPStan/Rules/Generics/ClassLevelUsedTraitsRuleTest.php tests/PHPStan/Rules/Generics/UsedTraitsRuleTest.php
• vendor/bin/phpunit tests/PHPStan/Analyser/NodeScopeResolverTest.php --filter class-level-use-tag

[phpstan-bot]

This pull request has been marked as ready for review.