PHPStan Level 8 (#29)

* Refactor rules to improve type handling and documentation

- Updated various rule classes to use IdentifierRuleError for error handling instead of RuleError.
- Enhanced method signatures with type hints for better clarity and type safety.
- Added parameter type annotations in processNode methods for improved documentation.
- Removed unnecessary instance checks for nodes in processNode methods to streamline logic.
- Improved error handling and reporting consistency across rules.

* Add PHPStan and PHPCS workflows to CI configuration

- Introduced new jobs for PHPStan and PHPCS in the CI pipeline to enhance code quality checks.
- Configured both jobs to run on Ubuntu 24.04 with PHP 8.4.
- Added steps for checking out the code, setting up PHP, installing Composer dependencies, and running the respective analysis tools.
- Ensured that the workflows are set up to improve static analysis and coding standards enforcement.

* Remove trailing whitespace in ForbiddenDependenciesRule.php

---------

Co-authored-by: Florian Krämer <f.kraemer@clipmyhorse.tv>

Author: floriankraemer

.github/workflows/ci.yaml

@@ -43,3 +43,45 @@ jobs:
       - name: Code Coverage Report
         if: success() && matrix.php-version == '8.3'
         uses: codecov/codecov-action@v4
+
+  phpstan:
+    name: PHPStan
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: json, fileinfo
+
+      - name: Composer install
+        run: composer install
+
+      - name: Run PHPStan
+        run: bin/phpstan analyse --no-progress
+
+  phpcs:
+    name: PHPCS
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: json, fileinfo
+
+      - name: Composer install
+        run: composer install
+
+      - name: Run PHPCS
+        run: bin/phpcs

src/Architecture/CatchExceptionOfTypeNotAllowedRule.php

@@ -55,12 +55,11 @@ public function getNodeType(): string
         return Catch_::class;
     }
 
+    /**
+     * @param Catch_ $node
+     */
     public function processNode(Node $node, Scope $scope): array
     {
-        if (!$node instanceof Catch_) {
-            return [];
-        }
-
         $errors = [];
 
         foreach ($node->types as $type) {

src/Architecture/CircularModuleDependencyRule.php

@@ -19,8 +19,8 @@
 use PhpParser\Node;
 use PhpParser\Node\Stmt\Use_;
 use PHPStan\Analyser\Scope;
+use PHPStan\Rules\IdentifierRuleError;
 use PHPStan\Rules\Rule;
-use PHPStan\Rules\RuleError;
 use PHPStan\Rules\RuleErrorBuilder;
 use PHPStan\ShouldNotHappenException;
 
@@ -55,6 +55,7 @@ public function getNodeType(): string
     }
 
     /**
+     * @return list<IdentifierRuleError>
      * @throws ShouldNotHappenException
      */
     public function processNode(Node $node, Scope $scope): array
@@ -153,7 +154,7 @@ private function detectCircularDependency(
         string $sourceModule,
         string $targetModule,
         int $line
-    ): ?RuleError {
+    ): ?IdentifierRuleError {
         // Check if adding this dependency would create a cycle
         // We're adding: sourceModule → targetModule
         // Check if there's already a path: targetModule → ... → sourceModule

src/Architecture/ClassMustBeFinalRule.php

@@ -19,6 +19,7 @@
 use PhpParser\Node;
 use PhpParser\Node\Stmt\Class_;
 use PHPStan\Analyser\Scope;
+use PHPStan\Rules\IdentifierRuleError;
 use PHPStan\Rules\Rule;
 use PHPStan\Rules\RuleErrorBuilder;
 use PHPStan\ShouldNotHappenException;
@@ -53,11 +54,12 @@ public function getNodeType(): string
     }
 
     /**
+     * @param Class_ $node
      * @throws ShouldNotHappenException
      */
     public function processNode(Node $node, Scope $scope): array
     {
-        if (!$node instanceof Class_ || !isset($node->name)) {
+        if (!isset($node->name)) {
             return [];
         }
 
@@ -79,7 +81,7 @@ public function processNode(Node $node, Scope $scope): array
         return [];
     }
 
-    private function buildRuleError(string $fullClassName)
+    private function buildRuleError(string $fullClassName): IdentifierRuleError
     {
         return RuleErrorBuilder::message(sprintf(self::ERROR_MESSAGE, $fullClassName))
             ->identifier(self::IDENTIFIER)

src/Architecture/ClassMustBeReadonlyRule.php

@@ -54,9 +54,12 @@ public function getNodeType(): string
         return Class_::class;
     }
 
+    /**
+     * @param Class_ $node
+     */
     public function processNode(Node $node, Scope $scope): array
     {
-        if (!$node instanceof Class_ || !isset($node->name)) {
+        if (!isset($node->name)) {
             return [];
         }
 

src/Architecture/ClassMustHaveSpecificationDocblockRule.php

@@ -182,7 +182,9 @@ private function extractDocblockLines(string $text): array
         $lines = explode("\n", $cleaned);
 
         // Remove leading * and whitespace from each line
-        $lines = array_map(function (string $line): string {
+        /** @var list<string> $result */
+        $result = [];
+        foreach ($lines as $line) {
             $line = ltrim($line);
             if (strpos($line, '*') === 0) {
                 $line = substr($line, 1);
@@ -191,19 +193,22 @@ private function extractDocblockLines(string $text): array
                     $line = substr($line, 1);
                 }
             }
-            return $line;
-        }, $lines);
+            $result[] = $line;
+        }
 
         // Remove empty first and last lines that might be from the /** */ delimiters
-        if ($lines !== [] && trim($lines[0]) === '') {
-            array_shift($lines);
+        // The list is guaranteed to have at least one element (explode always returns at least one)
+        if (trim($result[0]) === '') {
+            array_shift($result);
         }
-        $lastIndex = count($lines) - 1;
-        if ($lastIndex >= 0 && trim($lines[$lastIndex]) === '') {
-            array_pop($lines);
+
+        // Check last element only if list still has elements after possible removal
+        $resultCount = count($result);
+        if ($resultCount > 0 && trim($result[$resultCount - 1]) === '') {
+            array_pop($result);
         }
 
-        return $lines;
+        return $result;
     }
 
     /**

src/Architecture/ClassnameMustMatchPatternRule.php

@@ -20,6 +20,7 @@
 use PhpParser\Node\Stmt\Class_;
 use PhpParser\Node\Stmt\Namespace_;
 use PHPStan\Analyser\Scope;
+use PHPStan\Rules\IdentifierRuleError;
 use PHPStan\Rules\Rule;
 use PHPStan\Rules\RuleErrorBuilder;
 use PHPStan\ShouldNotHappenException;
@@ -51,13 +52,14 @@ public function getNodeType(): string
         return Namespace_::class;
     }
 
+    /**
+     * @param Namespace_ $node
+     * @return list<IdentifierRuleError>
+     */
     public function processNode(Node $node, Scope $scope): array
     {
-        if (!$node instanceof Namespace_) {
-            return [];
-        }
-
         $namespaceName = $node->name ? $node->name->toString() : '';
+        /** @var list<IdentifierRuleError> $errors */
         $errors = [];
 
         foreach ($this->namespaceClassPatterns as $config) {
@@ -118,16 +120,16 @@ private function buildErrorMessage(string $fqcn, string $namespace, array $patte
     /**
      * @param string $namespaceName
      * @param string $className
-     * @param $classPatterns
+     * @param array<string> $classPatterns
      * @param Class_ $stmt
-     * @param array $errors
-     * @return array
+     * @param list<IdentifierRuleError> $errors
+     * @return list<IdentifierRuleError>
      * @throws ShouldNotHappenException
      */
     public function buildRuleError(
         string $namespaceName,
         string $className,
-        $classPatterns,
+        array $classPatterns,
         Class_ $stmt,
         array $errors
     ): array {

src/Architecture/ForbiddenDependenciesRule.php

@@ -456,4 +456,3 @@ private function validateClassReference(string $className, string $currentNamesp
         return $errors;
     }
 }
-

src/Architecture/ForbiddenNamespacesRule.php

@@ -59,14 +59,11 @@ public function getNodeType(): string
     }
 
     /**
+     * @param Namespace_ $node
      * @throws ShouldNotHappenException
      */
     public function processNode(Node $node, Scope $scope): array
     {
-        if (!$node instanceof Namespace_) {
-            return [];
-        }
-
         $namespaceName = $node->name ? $node->name->toString() : '';
 
         // Empty namespace is allowed (global namespace)