Add allowedDependencies feature to override forbidden dependencies (#27)

- Introduced new classes `AllowedOverride` and `StillForbidden` to demonstrate the functionality of overriding forbidden dependencies with a whitelist.
- Updated `ForbiddenDependenciesRule` to include an `allowedDependencies` parameter, allowing specific dependencies to bypass the forbidden rules.
- Enhanced documentation for the `Dependency-Constraints-Rule` to explain the new `allowedDependencies` feature.
- Added tests to validate the behavior of allowed dependencies and ensure that forbidden dependencies still trigger errors when not in the allowed list.

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

Author: floriankraemer

data/ForbiddenDependenciesAllowed/AllowedOverride.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Capability\Billing\Domain;
+
+// These are forbidden by the "forbid everything" pattern but allowed by the whitelist
+use App\Shared\ValueObject\Money;
+use App\Capability\UserManagement\UserManagementFacade;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Test class that uses dependencies which are forbidden but overridden by allowedDependencies.
+ * None of these should trigger errors because they match the allowed patterns.
+ */
+class AllowedOverride
+{
+    private Money $amount;
+
+    private LoggerInterface $logger;
+
+    public function __construct(Money $amount, LoggerInterface $logger)
+    {
+        $this->amount = $amount;
+        $this->logger = $logger;
+    }
+
+    public function getFacade(): UserManagementFacade
+    {
+        return new \App\Capability\UserManagement\UserManagementFacade();
+    }
+
+    public function logSomething(): void
+    {
+        $this->logger->info('test');
+    }
+}

data/ForbiddenDependenciesAllowed/StillForbidden.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Capability\Billing\Domain;
+
+// These are forbidden and NOT in the allowed list - should trigger errors
+use Doctrine\ORM\EntityManager;
+use Symfony\Component\HttpFoundation\Request;
+
+/**
+ * Test class that uses dependencies which are forbidden and NOT overridden.
+ * These should trigger errors.
+ */
+class StillForbidden
+{
+    private EntityManager $entityManager;
+
+    public function __construct(EntityManager $entityManager)
+    {
+        $this->entityManager = $entityManager;
+    }
+
+    public function handleRequest(Request $request): void
+    {
+        // Using forbidden dependency
+    }
+
+    public function createEntityManager(): EntityManager
+    {
+        return new \Doctrine\ORM\EntityManager();
+    }
+}

docs/rules/Dependency-Constraints-Rule.md

@@ -82,6 +82,7 @@ In the example below nothing from `App\Domain` can depend on anything from `App\
 - `forbiddenDependencies`: Array where keys are namespace patterns that should not depend on the namespace patterns in their value arrays.
 - `checkFqcn` (optional, default: `false`): Enable checking of fully qualified class names in addition to use statements.
 - `fqcnReferenceTypes` (optional, default: all types): Array of reference types to check when `checkFqcn` is enabled.
+- `allowedDependencies` (optional, default: `[]`): Whitelist that overrides forbidden dependencies. If a dependency matches both a forbidden pattern and an allowed pattern, it will be allowed.
 
 ## FQCN Reference Types
 
@@ -147,6 +148,51 @@ If you only want to check specific reference types (e.g., to improve performance
             - phpstan.rules.rule
 ```
 
+### Whitelist with allowedDependencies
+
+The `allowedDependencies` parameter lets you create a "forbid everything except X" pattern without complex regex. Dependencies matching both forbidden and allowed patterns will be allowed.
+
+This example forbids all third-party/namespaced dependencies in the domain layer, except for `App\Shared`, `App\Capability`, and `Psr\*`:
+
+```neon
+    -
+        class: Phauthentic\PHPStanRules\Architecture\ForbiddenDependenciesRule
+        arguments:
+            forbiddenDependencies: [
+                '/^App\\Capability\\.*\\Domain$/': [
+                    '/.*\\\\.*/'  # Match anything with a backslash (namespaced)
+                ]
+            ]
+            checkFqcn: true
+            allowedDependencies: [
+                '/^App\\Capability\\.*\\Domain$/': [
+                    '/^App\\Shared\\/',
+                    '/^App\\Capability\\/',
+                    '/^Psr\\/'
+                ]
+            ]
+        tags:
+            - phpstan.rules.rule
+```
+
+This will:
+
+- **Allow**: `App\Shared\ValueObject\Money`, `App\Capability\Billing\Invoice`, `Psr\Log\LoggerInterface`
+- **Forbid**: `Doctrine\ORM\EntityManager`, `Symfony\Component\HttpFoundation\Request`
+
+Note: Root namespace classes (like `DateTime`, `Exception`) are not matched by the `/.*\\\\.*/'` pattern since they don't contain a backslash, so they are implicitly allowed.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A[Check Dependency] --> B{Matches forbidden pattern?}
+    B -->|No| C[Allow]
+    B -->|Yes| D{Matches allowed pattern?}
+    D -->|Yes| E[Allow - Override]
+    D -->|No| F[Report Error]
+```
+
 ## Backward Compatibility
 
-By default, `checkFqcn` is `false`, so existing configurations will continue to work exactly as before, checking only `use` statements. The new FQCN checking feature must be explicitly enabled.
+By default, `checkFqcn` is `false` and `allowedDependencies` is empty, so existing configurations will continue to work exactly as before, checking only `use` statements. The new FQCN checking and allowedDependencies features must be explicitly enabled.

src/Architecture/ForbiddenDependenciesRule.php

@@ -66,19 +66,29 @@ class ForbiddenDependenciesRule implements Rule
      */
     private array $fqcnReferenceTypes;
 
+    /**
+     * @var array<string, array<string>>
+     * An array where the key is a regex for the source namespace and the value is
+     * an array of regexes for allowed dependency namespaces that override forbidden ones.
+     */
+    private array $allowedDependencies;
+
     /**
      * @param array<string, array<string>> $forbiddenDependencies
      * @param bool $checkFqcn Enable checking of fully qualified class names (default: false for backward compatibility)
      * @param array<string> $fqcnReferenceTypes Which reference types to check when checkFqcn is enabled (default: all)
+     * @param array<string, array<string>> $allowedDependencies Whitelist that overrides forbidden dependencies
      */
     public function __construct(
         array $forbiddenDependencies,
         bool $checkFqcn = false,
-        array $fqcnReferenceTypes = self::ALL_REFERENCE_TYPES
+        array $fqcnReferenceTypes = self::ALL_REFERENCE_TYPES,
+        array $allowedDependencies = []
     ) {
         $this->forbiddenDependencies = $forbiddenDependencies;
         $this->checkFqcn = $checkFqcn;
         $this->fqcnReferenceTypes = $fqcnReferenceTypes;
+        $this->allowedDependencies = $allowedDependencies;
     }
 
     public function getNodeType(): string
@@ -131,7 +141,7 @@ public function validateUseStatements(Use_ $node, array $disallowedDependencyPat
         foreach ($node->uses as $use) {
             $usedClassName = $use->name->toString();
             foreach ($disallowedDependencyPatterns as $disallowedPattern) {
-                if (preg_match($disallowedPattern, $usedClassName)) {
+                if (preg_match($disallowedPattern, $usedClassName) && !$this->isAllowed($usedClassName, $currentNamespace)) {
                     $errors[] = RuleErrorBuilder::message(sprintf(
                         static::ERROR_MESSAGE,
                         $currentNamespace,
@@ -147,6 +157,30 @@ public function validateUseStatements(Use_ $node, array $disallowedDependencyPat
         return $errors;
     }
 
+    /**
+     * Check if a class name is in the allowed list for the current namespace
+     *
+     * @param string $className
+     * @param string $currentNamespace
+     * @return bool
+     */
+    private function isAllowed(string $className, string $currentNamespace): bool
+    {
+        foreach ($this->allowedDependencies as $sourcePattern => $allowedPatterns) {
+            if (!preg_match($sourcePattern, $currentNamespace)) {
+                continue;
+            }
+
+            foreach ($allowedPatterns as $allowedPattern) {
+                if (preg_match($allowedPattern, $className)) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
     /**
      * Process FQCN references in various node types
      *
@@ -406,7 +440,7 @@ private function validateClassReference(string $className, string $currentNamesp
             }
 
             foreach ($disallowedDependencyPatterns as $disallowedPattern) {
-                if (preg_match($disallowedPattern, $className)) {
+                if (preg_match($disallowedPattern, $className) && !$this->isAllowed($className, $currentNamespace)) {
                     $errors[] = RuleErrorBuilder::message(sprintf(
                         static::ERROR_MESSAGE,
                         $currentNamespace,

tests/TestCases/Architecture/ForbiddenDependenciesAllowedTest.php

@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phauthentic\PHPStanRules\Tests\TestCases\Architecture;
+
+use Phauthentic\PHPStanRules\Architecture\ForbiddenDependenciesRule;
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+
+/**
+ * Test allowedDependencies feature that overrides forbidden dependencies
+ *
+ * @extends RuleTestCase<ForbiddenDependenciesRule>
+ */
+class ForbiddenDependenciesAllowedTest extends RuleTestCase
+{
+    protected function getRule(): Rule
+    {
+        return new ForbiddenDependenciesRule(
+            // Forbid everything (any namespaced class)
+            [
+                '/^App\\\\Capability\\\\.*\\\\Domain$/' => [
+                    '/.*\\\\.*/'  // Match anything with a backslash (namespaced)
+                ]
+            ],
+            true, // Enable FQCN checking
+            [     // All reference types (default)
+                'new',
+                'param',
+                'return',
+                'property',
+                'static_call',
+                'static_property',
+                'class_const',
+                'instanceof',
+                'catch',
+                'extends',
+                'implements',
+            ],
+            // Allow specific namespaces as override
+            [
+                '/^App\\\\Capability\\\\.*\\\\Domain$/' => [
+                    '/^App\\\\Shared\\\\/',
+                    '/^App\\\\Capability\\\\/',
+                    '/^Psr\\\\/'
+                ]
+            ]
+        );
+    }
+
+    /**
+     * Test that allowed dependencies do not trigger errors
+     */
+    public function testAllowedDependenciesOverrideForbidden(): void
+    {
+        // Should have no errors - all dependencies match allowed patterns
+        $this->analyse([__DIR__ . '/../../../data/ForbiddenDependenciesAllowed/AllowedOverride.php'], []);
+    }
+
+    /**
+     * Test that forbidden dependencies not in allowed list still trigger errors
+     */
+    public function testForbiddenDependenciesStillReportErrors(): void
+    {
+        $this->analyse([__DIR__ . '/../../../data/ForbiddenDependenciesAllowed/StillForbidden.php'], [
+            [
+                'Forbidden dependency: A class in namespace `App\Capability\Billing\Domain` is not allowed to depend on `Doctrine\ORM\EntityManager`.',
+                8,
+            ],
+            [
+                'Forbidden dependency: A class in namespace `App\Capability\Billing\Domain` is not allowed to depend on `Symfony\Component\HttpFoundation\Request`.',
+                9,
+            ],
+            [
+                'Forbidden dependency: A class in namespace `App\Capability\Billing\Domain` is not allowed to depend on `Doctrine\ORM\EntityManager`.',
+                17,
+            ],
+            [
+                'Forbidden dependency: A class in namespace `App\Capability\Billing\Domain` is not allowed to depend on `Doctrine\ORM\EntityManager`.',
+                19,
+            ],
+            [
+                'Forbidden dependency: A class in namespace `App\Capability\Billing\Domain` is not allowed to depend on `Symfony\Component\HttpFoundation\Request`.',
+                24,
+            ],
+            [
+                'Forbidden dependency: A class in namespace `App\Capability\Billing\Domain` is not allowed to depend on `Doctrine\ORM\EntityManager`.',
+                29,
+            ],
+            [
+                'Forbidden dependency: A class in namespace `App\Capability\Billing\Domain` is not allowed to depend on `Doctrine\ORM\EntityManager`.',
+                31,
+            ],
+        ]);
+    }
+}