feat: add rule to prevent comments after attributes

Author: calebdw

src/Rules/PhpDoc/NoCommentsAfterAttributesRule.php

@@ -0,0 +1,84 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PhpDoc;
+
+use LogicException;
+use Override;
+use PhpParser\Node;
+use PhpParser\Node\AttributeGroup;
+use PhpParser\Node\Param;
+use PhpParser\Node\Stmt\ClassConst;
+use PhpParser\Node\Stmt\Property;
+use PHPStan\Analyser\Scope;
+use PHPStan\DependencyInjection\RegisteredRule;
+use PHPStan\Node\VirtualNode;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use function array_map;
+use function assert;
+use function max;
+use function min;
+use function property_exists;
+
+/** @implements Rule<Node> */
+#[RegisteredRule(level: 0)]
+final class NoCommentsAfterAttributesRule implements Rule
+{
+
+	#[Override]
+	public function getNodeType(): string
+	{
+		return Node::class;
+	}
+
+	#[Override]
+	public function processNode(Node $node, Scope $scope): array
+	{
+		if ($node instanceof VirtualNode) {
+			return [];
+		}
+
+		if ($node->getDocComment() !== null) {
+			return [];
+		}
+
+		if (! property_exists($node, 'attrGroups')) {
+			return [];
+		}
+
+		$attrGroups = $node->attrGroups;
+
+		if ($attrGroups === []) {
+			return [];
+		}
+
+		$attrGroupEndLine = max(array_map(static fn (AttributeGroup $g) => $g->getEndLine(), $attrGroups));
+
+		if (property_exists($node, 'name')) {
+			$name = $node->name;
+			assert($name instanceof Node);
+			$startLine = $name->getStartLine();
+		} elseif ($node instanceof ClassConst) {
+			$startLine = min(array_map(static fn ($c) => $c->getStartLine(), $node->consts));
+		} elseif ($node instanceof Property) {
+			$startLine = min(array_map(static fn ($c) => $c->getStartLine(), $node->props));
+		} elseif ($node instanceof Param) {
+			$startLine = $node->var->getStartLine();
+		} else {
+			throw new LogicException('Unexpected node type: ' . $node::class);
+		}
+
+		if ($startLine - $attrGroupEndLine <= 1) {
+			return [];
+		}
+
+		return [
+			RuleErrorBuilder::message('No comments after attributes.')
+				->identifier('node.noCommentsAfterAttributes')
+				->line($attrGroupEndLine + 1)
+				->nonIgnorable()
+				->build(),
+		];
+	}
+
+}

tests/PHPStan/Rules/PhpDoc/NoCommentsAfterAttributesRuleTest.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PhpDoc;
+
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+use PHPUnit\Framework\Attributes\CoversNothing;
+
+/** @extends RuleTestCase<NoCommentsAfterAttributesRule> */
+#[CoversNothing]
+class NoCommentsAfterAttributesRuleTest extends RuleTestCase
+{
+
+	protected function getRule(): Rule
+	{
+		return new NoCommentsAfterAttributesRule();
+	}
+
+	public function testRule(): void
+	{
+		$message = 'No comments after attributes.';
+
+		$this->analyse([__DIR__ . '/data/no-comments-after-attributes.php'], [
+			[$message, 37],
+			[$message, 41],
+			[$message, 45],
+			[$message, 50],
+			[$message, 53],
+			[$message, 58],
+			[$message, 62],
+			[$message, 71],
+			[$message, 81],
+		]);
+	}
+
+}

tests/PHPStan/Rules/PhpDoc/data/no-comments-after-attributes.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace NoCommentsAfterAttributes;
+
+/** This is a doc comment. */
+#[Good]
+class Good
+{
+	/** @var array<int, string> */
+	#[Good]
+	public const array FOO = [];
+
+	/** @var array<int, string> */
+	#[Good]
+	private array $foo = [];
+
+	public function __construct(
+		/** @var array<int, string> */
+		#[Good]
+		private array $bar,
+		/** @var array<int, string> */
+		#[Good]
+		array $baz,
+		#[Good] string $qux,
+	) {}
+
+	// This is a comment.
+	#[Good]
+	public function foo(): void {}
+
+	/** This is a doc comment. */
+	#[Good]
+	public function bar(): void {}
+}
+
+#[Bad]
+/** This is a doc comment. */
+class Bad
+{
+	#[Bad]
+	/** @var array<int, string> */
+	public const array BAR = [];
+
+	#[Bad]
+	/** @var array<int, string> */
+	private array $foo = [];
+
+	public function __construct(
+		#[Bad]
+		/** @var array<int, string> */
+		private array $bar,
+		#[Bad]
+		/** @var array<int, string> */
+		array $baz,
+	) {}
+
+	#[Bad]
+	// This is a comment after attributes.
+	public function foo(): void {}
+
+	#[Bad]
+	/** This is a doc comment after attributes. */
+	public function bar(): void {}
+}
+
+/** This is a doc comment. */
+#[Good]
+function foo(): void {}
+
+#[Bad]
+/** This is a doc comment. */
+function bar(): void {}
+
+enum Foo
+{
+	/** This is a doc comment before attributes. */
+	#[Good]
+	case Foo;
+
+	#[Bad]
+	/** This is a doc comment after attributes. */
+	case Baz;
+}