Feat Introduces new unless modifier

src/Blueprint.php

@@ -231,9 +231,9 @@ private function getUsagePathAndLines(Layer $layer, string $objectName, string $
 
         $class = PhpCoreExpressions::getClass($target) ?? Name::class;
 
-        $nodes = ServiceContainer::$nodeFinder->findInstanceOf(
+        $nodes = ServiceContainer::$nodeFinder->findInstanceOf( //@phpstan-ignore-line
             $dependOnObject->stmts,
-            $class,
+            $class, //@phpstan-ignore-line
         );
 
         /** @var array<int, Name|Expr> $nodes */

src/Contracts/ArchExpectation.php

@@ -46,4 +46,12 @@ public function mergeExcludeCallbacks(array $callbacks): void;
      * @internal
      */
     public function excludeCallbacks(): array;
+
+    /**
+     * Expectations that the given "targets" or "dependencies" are to ignore.
+     *
+     * @param  array<int, string>|string  $expectations
+     * @return $this
+     */
+    public function unless(array|string $expectations): self;
 }

src/GroupArchExpectation.php

@@ -138,4 +138,16 @@ private function ensureLazyExpectationIsVerified(): void
             $expectation->ensureLazyExpectationIsVerified();
         }
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function unless(mixed $expectations): self
+    {
+        foreach ($this->expectations as $expectation) {
+            $expectation->unless($expectations);
+        }
+
+        return $this;
+    }
 }

src/SingleArchExpectation.php

@@ -170,4 +170,19 @@ public function ensureLazyExpectationIsVerified(): void
             ($this->opposite)(); // @phpstan-ignore-line
         }
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function unless(array|string $expectations): self
+    {
+        $modifier = UnlessModifier::make($this->expectation);
+        $expectations = is_array($expectations) ? $expectations : [$expectations => true];
+
+        $this->ignoring([
+            ...$modifier->targetsToIgnore($expectations, LayerOptions::fromExpectation($this)),
+        ]);
+
+        return $this;
+    }
 }

src/UnlessModifier.php

@@ -0,0 +1,114 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Arch;
+
+use Pest\Arch\Collections\Dependencies;
+use Pest\Arch\Options\LayerOptions;
+use Pest\Arch\ValueObjects\Targets;
+use Pest\Expectation;
+use PHPUnit\Architecture\Elements\ObjectDescription;
+
+/**
+ * @internal
+ *
+ * @mixin Expectation<array|string>
+ */
+final readonly class UnlessModifier
+{
+    public static function make(Expectation $expectation): self
+    {
+        return new self($expectation);
+    }
+
+    public function __construct(protected Expectation $expectation)
+    {
+    }
+
+    /* @phpstan-ignore-next-line */
+    public function targetsToIgnore(array $expectations, LayerOptions $options): array
+    {
+        $ignoreArr = [];
+        $blueprint = Blueprint::make(
+            Targets::fromExpectation($this->expectation),
+            Dependencies::fromExpectationInput([]),
+        );
+
+        $targets = (fn (): array => $this->target->value)->call($blueprint);
+        $layerFactory = (fn (): \Pest\Arch\Factories\LayerFactory => $this->layerFactory)->call($blueprint);
+
+        foreach ($targets as $targetValue) {
+            $targetLayer = $layerFactory->make($options, $targetValue);
+
+            foreach ($targetLayer as $object) {
+                /** @var \Pest\Arch\Objects\ObjectDescription $objectDescription */
+                $objectDescription = $object;
+
+                foreach ($expectations as $expectation => $value) {
+                    if ($ignore = $this->handleExpectation($objectDescription, $expectation, $value)) { // @phpstan-ignore-line
+                        $ignoreArr[] = $ignore;
+                    }
+                }
+            }
+        }
+
+        return $ignoreArr;
+    }
+
+    /**
+     * Handles the expectation.
+     */
+    private function handleExpectation(ObjectDescription $objectDescription, string $expectation, mixed $value): ?string
+    {
+        return match ($expectation) {
+            'abstractParent' => $this->handleAbstractParent($objectDescription, $value),
+            'extends' => $this->handleExtends($objectDescription, $value),
+            default => null,
+        };
+    }
+
+    /**
+     * Handles the "extends" expectation.
+     */
+    private function handleExtends(ObjectDescription $objectDescription, mixed $value): ?string
+    {
+        $reflection = $objectDescription->reflectionClass;
+
+        if ($value === true && $reflection->getParentClass() !== false) {
+            return $reflection->getName();
+        }
+
+        if (! is_string($value)) {
+            return null;
+        }
+
+        if (! $reflection->isSubclassOf($value)) {
+            return null;
+        }
+
+        return $reflection->getName();
+    }
+
+    /**
+     * Handles the "abstractParent" expectation.
+     */
+    private function handleAbstractParent(ObjectDescription $objectDescription, mixed $value): ?string
+    {
+        $reflection = $objectDescription->reflectionClass;
+
+        if ($reflection->getParentClass() === false) {
+            return null;
+        }
+
+        if ($value !== true) {
+            return null;
+        }
+
+        if (! $reflection->getParentClass()->isAbstract()) {
+            return null;
+        }
+
+        return $reflection->getName();
+    }
+}

tests/Arch.php

@@ -77,3 +77,18 @@
     ->expect(Targets::class)
     ->toOnlyUse([Expectation::class])
     ->ignoring('PHPUnit\Framework');
+
+arch('avoid mutation unless extending controller')
+    ->expect('Tests\Fixtures\Controllers\Service')
+    ->toHavePrefix('Service')
+    ->toBeReadonly()
+    ->unless([
+        'extends' => Tests\Fixtures\Controller::class,
+        'abstractParent' => true,
+    ]);
+
+arch('avoid mutation if extends')
+    ->expect('Tests\Fixtures\Controllers\Service')
+    ->toHavePrefix('Service')
+    ->toBeReadonly()
+    ->unless('extends');

tests/Fixtures/Controllers/AbstractServiceController.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures\Controllers;
+
+abstract class AbstractServiceController
+{
+}

tests/Fixtures/Controllers/Service/ServiceControllerA.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures\Controllers\Service;
+
+final readonly class ServiceControllerA
+{
+}

tests/Fixtures/Controllers/Service/ServiceControllerB.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures\Controllers\Service;
+
+final readonly class ServiceControllerB
+{
+}

tests/Fixtures/Controllers/Service/ServiceControllerC.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures\Controllers\Service;
+
+use Tests\Fixtures\Controllers\ServiceControllerBase;
+
+final class ServiceControllerC extends ServiceControllerBase
+{
+}

tests/Fixtures/Controllers/Service/ServiceControllerD.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures\Controllers\Service;
+
+use Tests\Fixtures\Controllers\AbstractServiceController;
+
+final class ServiceControllerD extends AbstractServiceController
+{
+}

tests/Fixtures/Controllers/ServiceControllerBase.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures\Controllers;
+
+use Tests\Fixtures\Controller;
+
+class ServiceControllerBase extends Controller
+{
+}