Add Method addTips() to Rule to

README.md

@@ -121,7 +121,8 @@ class MyFirstTest
                 Selector::namespace('App\Infrastructure'),
                 Selector::classname(SuperForbiddenClass::class),
                 Selector::classname('/^SomeVendor\\\.*\\\ForbiddenSubfolder\\\.*/', true)
-            );
+            )
+            ->because('this will break our architecture, implement it another way! see /docs/howto.md');
     }
 }
 ```

src/Rule/Assertion/Declaration/DeclarationAssertion.php

@@ -18,7 +18,7 @@
 
 abstract class DeclarationAssertion implements Assertion
 {
-    /** @var array<array{string, SelectorInterface, array<SelectorInterface>, array<SelectorInterface>, array<SelectorInterface>}> */
+    /** @var array<array{string, SelectorInterface, array<SelectorInterface>, string[]}> */
     protected array $statements;
     protected Configuration $configuration;
     protected ReflectionProvider $reflectionProvider;
@@ -70,9 +70,10 @@ abstract protected function meetsDeclaration(Node $node, Scope $scope): bool;
     abstract protected function getMessage(string $ruleName, string $subject): string;
 
     /**
+     * @param string[] $tips
      * @return array<RuleError>
      */
-    abstract protected function applyValidation(string $ruleName, ClassReflection $subject, bool $meetsDeclaration): array;
+    abstract protected function applyValidation(string $ruleName, ClassReflection $subject, bool $meetsDeclaration, array $tips): array;
 
     protected function ruleApplies(Scope $scope): bool
     {
@@ -95,7 +96,7 @@ protected function validateGetErrors(Scope $scope, bool $meetsDeclaration): arra
             throw new ShouldNotHappenException();
         }
 
-        foreach ($this->statements as [$ruleName, $selector, $subjectExcludes]) {
+        foreach ($this->statements as [$ruleName, $selector, $subjectExcludes, $tips]) {
             if ($subject->isBuiltin() || !$selector->matches($subject)) {
                 continue;
             }
@@ -105,7 +106,7 @@ protected function validateGetErrors(Scope $scope, bool $meetsDeclaration): arra
                 }
             }
 
-            array_push($errors, ...$this->applyValidation($ruleName, $subject, $meetsDeclaration));
+            array_push($errors, ...$this->applyValidation($ruleName, $subject, $meetsDeclaration, $tips));
         }
 
         return $errors;

src/Rule/Assertion/Declaration/ShouldBeAbstract/ShouldBeAbstract.php

@@ -31,9 +31,9 @@ public function __construct(
         );
     }
 
-    protected function applyValidation(string $ruleName, ClassReflection $subject, bool $meetsDeclaration): array
+    protected function applyValidation(string $ruleName, ClassReflection $subject, bool $meetsDeclaration, array $tips): array
     {
-        return $this->applyShould($ruleName, $subject, $meetsDeclaration);
+        return $this->applyShould($ruleName, $subject, $meetsDeclaration, $tips);
     }
 
     protected function getMessage(string $ruleName, string $subject): string

src/Rule/Assertion/Declaration/ShouldBeFinal/ShouldBeFinal.php

@@ -10,6 +10,7 @@
 use PHPat\Statement\Builder\StatementBuilderFactory;
 use PHPStan\Reflection\ClassReflection;
 use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Rules\RuleError;
 use PHPStan\Type\FileTypeMapper;
 
 abstract class ShouldBeFinal extends DeclarationAssertion
@@ -31,9 +32,16 @@ public function __construct(
         );
     }
 
-    protected function applyValidation(string $ruleName, ClassReflection $subject, bool $meetsDeclaration): array
+    /**
+     * @param string $ruleName
+     * @param ClassReflection $subject
+     * @param bool $meetsDeclaration
+     * @param string[] $tips
+     * @return array<RuleError>
+     */
+    protected function applyValidation(string $ruleName, ClassReflection $subject, bool $meetsDeclaration, array $tips): array
     {
-        return $this->applyShould($ruleName, $subject, $meetsDeclaration);
+        return $this->applyShould($ruleName, $subject, $meetsDeclaration, $tips);
     }
 
     protected function getMessage(string $ruleName, string $subject): string

src/Rule/Assertion/Declaration/ShouldNotBeAbstract/ShouldNotBeAbstract.php

@@ -31,9 +31,9 @@ public function __construct(
         );
     }
 
-    protected function applyValidation(string $ruleName, ClassReflection $subject, bool $meetsDeclaration): array
+    protected function applyValidation(string $ruleName, ClassReflection $subject, bool $meetsDeclaration, array $tips): array
     {
-        return $this->applyShouldNot($ruleName, $subject, $meetsDeclaration);
+        return $this->applyShouldNot($ruleName, $subject, $meetsDeclaration, $tips);
     }
 
     protected function getMessage(string $ruleName, string $subject): string

src/Rule/Assertion/Declaration/ShouldNotBeFinal/ShouldNotBeFinal.php

@@ -31,9 +31,9 @@ public function __construct(
         );
     }
 
-    protected function applyValidation(string $ruleName, ClassReflection $subject, bool $meetsDeclaration): array
+    protected function applyValidation(string $ruleName, ClassReflection $subject, bool $meetsDeclaration, array $tips): array
     {
-        return $this->applyShouldNot($ruleName, $subject, $meetsDeclaration);
+        return $this->applyShouldNot($ruleName, $subject, $meetsDeclaration, $tips);
     }
 
     protected function getMessage(string $ruleName, string $subject): string

src/Rule/Assertion/Declaration/ValidationTrait.php

@@ -13,34 +13,46 @@
 trait ValidationTrait
 {
     /**
+     * @param string[] $tips
      * @throws ShouldNotHappenException
      * @return array<RuleError>
      */
-    protected function applyShould(string $ruleName, ClassReflection $subject, bool $meetsDeclaration): array
+    protected function applyShould(string $ruleName, ClassReflection $subject, bool $meetsDeclaration, array $tips): array
     {
         $errors = [];
 
         if (!$meetsDeclaration) {
-            $errors[] = RuleErrorBuilder::message(
+            $ruleError = RuleErrorBuilder::message(
                 $this->getMessage($ruleName, $subject->getName())
-            )->build();
+            );
+
+            foreach($tips as $tip) {
+                $ruleError->addTip($tip);
+            }
+            $errors[] = $ruleError->build();
         }
 
         return $errors;
     }
 
     /**
+     * @param string[] $tips
      * @throws ShouldNotHappenException
      * @return array<RuleError>
      */
-    protected function applyShouldNot(string $ruleName, ClassReflection $subject, bool $meetsDeclaration): array
+    protected function applyShouldNot(string $ruleName, ClassReflection $subject, bool $meetsDeclaration, array $tips): array
     {
         $errors = [];
 
         if ($meetsDeclaration) {
-            $errors[] = RuleErrorBuilder::message(
+            $ruleError = RuleErrorBuilder::message(
                 $this->getMessage($ruleName, $subject->getName())
-            )->build();
+            );
+
+            foreach($tips as $tip) {
+                $ruleError->addTip($tip);
+            }
+            $errors[] = $ruleError->build();
         }
 
         return $errors;

src/Rule/Assertion/Relation/CanOnlyDepend/CanOnlyDepend.php

@@ -31,9 +31,15 @@ public function __construct(
         );
     }
 
-    protected function applyValidation(string $ruleName, ClassReflection $subject, array $targets, array $targetExcludes, array $nodes): array
-    {
-        return $this->applyCanOnly($ruleName, $subject, $targets, $targetExcludes, $nodes);
+    protected function applyValidation(
+        string $ruleName,
+        ClassReflection $subject,
+        array $targets,
+        array $targetExcludes,
+        array $nodes,
+        array $tips
+    ): array {
+        return $this->applyCanOnly($ruleName, $subject, $targets, $targetExcludes, $nodes, $tips);
     }
 
     protected function getMessage(string $ruleName, string $subject, string $target): string

src/Rule/Assertion/Relation/RelationAssertion.php

@@ -19,7 +19,7 @@
 
 abstract class RelationAssertion implements Assertion
 {
-    /** @var array<array{string, SelectorInterface, array<SelectorInterface>, array<SelectorInterface>, array<SelectorInterface>}> */
+    /** @var array<array{string, SelectorInterface, array<SelectorInterface>, array<SelectorInterface>, array<SelectorInterface>, array<string>}> */
     protected array $statements;
     protected Configuration $configuration;
     protected ReflectionProvider $reflectionProvider;
@@ -74,14 +74,22 @@ abstract protected function extractNodeClassNames(Node $node, Scope $scope): arr
     abstract protected function getMessage(string $ruleName, string $subject, string $target): string;
 
     /**
-     * @param string                 $ruleName
+     * @param string                   $ruleName
      * @param ClassReflection          $subject
      * @param array<SelectorInterface> $targets
      * @param array<SelectorInterface> $targetExcludes
      * @param array<class-string>      $nodes
+     * @param array<string>            $tips
      * @return array<RuleError>
      */
-    abstract protected function applyValidation(string $ruleName, ClassReflection $subject, array $targets, array $targetExcludes, array $nodes): array;
+    abstract protected function applyValidation(
+        string $ruleName,
+        ClassReflection $subject,
+        array $targets,
+        array $targetExcludes,
+        array $nodes,
+        array $tips
+    ): array;
 
     /**
      * @param array<class-string> $nodes
@@ -119,7 +127,7 @@ protected function validateGetErrors(Scope $scope, array $nodes): array
             throw new ShouldNotHappenException();
         }
 
-        foreach ($this->statements as [$ruleName, $selector, $subjectExcludes, $targets, $targetExcludes]) {
+        foreach ($this->statements as [$ruleName, $selector, $subjectExcludes, $targets, $targetExcludes, $tips]) {
             if ($subject->isBuiltin() || !$selector->matches($subject)) {
                 continue;
             }
@@ -135,7 +143,7 @@ protected function validateGetErrors(Scope $scope, array $nodes): array
 
             array_push(
                 $errors,
-                ...$this->applyValidation($ruleName, $subject, $targets, $targetExcludes, $nodes)
+                ...$this->applyValidation($ruleName, $subject, $targets, $targetExcludes, $nodes, $tips)
             );
         }
 

src/Rule/Assertion/Relation/ShouldExtend/ShouldExtend.php

@@ -31,9 +31,15 @@ public function __construct(
         );
     }
 
-    protected function applyValidation(string $ruleName, ClassReflection $subject, array $targets, array $targetExcludes, array $nodes): array
-    {
-        return $this->applyShould($ruleName, $subject, $targets, $targetExcludes, $nodes);
+    protected function applyValidation(
+        string $ruleName,
+        ClassReflection $subject,
+        array $targets,
+        array $targetExcludes,
+        array $nodes,
+        array $tips
+    ): array {
+        return $this->applyShould($ruleName, $subject, $targets, $targetExcludes, $nodes, $tips);
     }
 
     protected function getMessage(string $ruleName, string $subject, string $target): string

src/Rule/Assertion/Relation/ShouldImplement/ShouldImplement.php

@@ -31,9 +31,15 @@ public function __construct(
         );
     }
 
-    protected function applyValidation(string $ruleName, ClassReflection $subject, array $targets, array $targetExcludes, array $nodes): array
-    {
-        return $this->applyShould($ruleName, $subject, $targets, $targetExcludes, $nodes);
+    protected function applyValidation(
+        string $ruleName,
+        ClassReflection $subject,
+        array $targets,
+        array $targetExcludes,
+        array $nodes,
+        array $tips
+    ): array {
+        return $this->applyShould($ruleName, $subject, $targets, $targetExcludes, $nodes, $tips);
     }
 
     protected function getMessage(string $ruleName, string $subject, string $target): string

src/Rule/Assertion/Relation/ShouldNotConstruct/ShouldNotConstruct.php

@@ -31,9 +31,15 @@ public function __construct(
         );
     }
 
-    protected function applyValidation(string $ruleName, ClassReflection $subject, array $targets, array $targetExcludes, array $nodes): array
-    {
-        return $this->applyShouldNot($ruleName, $subject, $targets, $targetExcludes, $nodes);
+    protected function applyValidation(
+        string $ruleName,
+        ClassReflection $subject,
+        array $targets,
+        array $targetExcludes,
+        array $nodes,
+        array $tips
+    ): array {
+        return $this->applyShouldNot($ruleName, $subject, $targets, $targetExcludes, $nodes, $tips);
     }
 
     protected function getMessage(string $ruleName, string $subject, string $target): string

src/Rule/Assertion/Relation/ShouldNotDepend/ShouldNotDepend.php

@@ -31,9 +31,15 @@ public function __construct(
         );
     }
 
-    protected function applyValidation(string $ruleName, ClassReflection $subject, array $targets, array $targetExcludes, array $nodes): array
-    {
-        return $this->applyShouldNot($ruleName, $subject, $targets, $targetExcludes, $nodes);
+    protected function applyValidation(
+        string $ruleName,
+        ClassReflection $subject,
+        array $targets,
+        array $targetExcludes,
+        array $nodes,
+        array $tips
+    ): array {
+        return $this->applyShouldNot($ruleName, $subject, $targets, $targetExcludes, $nodes, $tips);
     }
 
     protected function getMessage(string $ruleName, string $subject, string $target): string

src/Rule/Assertion/Relation/ShouldNotExtend/ShouldNotExtend.php

@@ -31,9 +31,15 @@ public function __construct(
         );
     }
 
-    protected function applyValidation(string $ruleName, ClassReflection $subject, array $targets, array $targetExcludes, array $nodes): array
-    {
-        return $this->applyShouldNot($ruleName, $subject, $targets, $targetExcludes, $nodes);
+    protected function applyValidation(
+        string $ruleName,
+        ClassReflection $subject,
+        array $targets,
+        array $targetExcludes,
+        array $nodes,
+        array $tips
+    ): array {
+        return $this->applyShouldNot($ruleName, $subject, $targets, $targetExcludes, $nodes, $tips);
     }
 
     protected function getMessage(string $ruleName, string $subject, string $target): string

src/Rule/Assertion/Relation/ShouldNotImplement/ShouldNotImplement.php

@@ -31,9 +31,15 @@ public function __construct(
         );
     }
 
-    protected function applyValidation(string $ruleName, ClassReflection $subject, array $targets, array $targetExcludes, array $nodes): array
-    {
-        return $this->applyShouldNot($ruleName, $subject, $targets, $targetExcludes, $nodes);
+    protected function applyValidation(
+        string $ruleName,
+        ClassReflection $subject,
+        array $targets,
+        array $targetExcludes,
+        array $nodes,
+        array $tips
+    ): array {
+        return $this->applyShouldNot($ruleName, $subject, $targets, $targetExcludes, $nodes, $tips);
     }
 
     protected function getMessage(string $ruleName, string $subject, string $target): string