Add tips to the rules using because()

carlosas · Aug 12, 2023 · e1ce34e · e1ce34e
1 parent 13dc7fb
commit e1ce34e
Show file tree

Hide file tree

Showing 30 changed files with 530 additions and 70 deletions.
diff --git a/README.md b/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');
  }
 }
 ```

diff --git a/src/Rule/Assertion/Declaration/DeclarationAssertion.php b/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;

diff --git a/src/Rule/Assertion/Declaration/ShouldBeAbstract/ShouldBeAbstract.php b/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

diff --git a/src/Rule/Assertion/Declaration/ShouldBeFinal/ShouldBeFinal.php b/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

diff --git a/src/Rule/Assertion/Declaration/ShouldNotBeAbstract/ShouldNotBeAbstract.php b/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

diff --git a/src/Rule/Assertion/Declaration/ShouldNotBeFinal/ShouldNotBeFinal.php b/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

diff --git a/src/Rule/Assertion/Declaration/ValidationTrait.php b/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;

diff --git a/src/Rule/Assertion/Relation/CanOnlyDepend/CanOnlyDepend.php b/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

diff --git a/src/Rule/Assertion/Relation/RelationAssertion.php b/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)
  );
  }
 

diff --git a/src/Rule/Assertion/Relation/ShouldExtend/ShouldExtend.php b/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

diff --git a/src/Rule/Assertion/Relation/ShouldImplement/ShouldImplement.php b/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

diff --git a/src/Rule/Assertion/Relation/ShouldNotConstruct/ShouldNotConstruct.php b/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

diff --git a/src/Rule/Assertion/Relation/ShouldNotDepend/ShouldNotDepend.php b/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

diff --git a/src/Rule/Assertion/Relation/ShouldNotExtend/ShouldNotExtend.php b/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

diff --git a/src/Rule/Assertion/Relation/ShouldNotImplement/ShouldNotImplement.php b/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