feat: add ignorePaths method to exclude specified paths from arch ana…

src/Expectation.php

@@ -434,6 +434,39 @@ public function any(): Any
         return new Any;
     }
 
+    /**
+     * Excludes files whose paths contain any of the given path fragments from arch analysis.
+     *
+     * @param  list<string>  $paths
+     */
+    public function ignorePaths(array $paths): PendingArchExpectation
+    {
+        $normalizedPaths = array_values(array_filter(array_map(
+            static fn (string $path): string => trim(str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $path), DIRECTORY_SEPARATOR),
+            $paths,
+        ), static fn (string $path): bool => $path !== ''));
+
+        return new PendingArchExpectation($this, [
+            static function (ObjectDescription $object) use ($normalizedPaths): bool {
+                if (isset($object->path)) {
+                    $normalizedObjectPath = trim(str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $object->path), DIRECTORY_SEPARATOR);
+                } else {
+                    // Fallback for objects without an initialized path (e.g., vendor objects);
+                    // use the class name as a path approximation.
+                    $normalizedObjectPath = trim(str_replace('\\', DIRECTORY_SEPARATOR, $object->name), DIRECTORY_SEPARATOR);
+                }
+
+                foreach ($normalizedPaths as $path) {
+                    if (str_contains($normalizedObjectPath, $path)) {
+                        return true;
+                    }
+                }
+
+                return false;
+            },
+        ]);
+    }
+
     /**
      * Asserts that the given expectation target use the given dependencies.
      *

tests/Features/Expect/ignorePaths.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+use Pest\Arch\Exceptions\ArchExpectationFailedException;
+
+test('single ignored path', function () {
+    expect('Tests\Fixtures\Arch\IgnorePaths\Single')
+        ->ignorePaths(['database/migrations'])
+        ->toUseStrictTypes();
+});
+
+test('multiple ignored paths', function () {
+    expect('Tests\Fixtures\Arch\IgnorePaths\Multiple')
+        ->ignorePaths(['database/migrations', 'vendor'])
+        ->toUseStrictTypes();
+});
+
+test('nested directory ignored', function () {
+    expect('Tests\Fixtures\Arch\IgnorePaths\Single')
+        ->ignorePaths(['database'])
+        ->toUseStrictTypes();
+});
+
+test('partial path matching', function () {
+    expect('Tests\Fixtures\Arch\IgnorePaths\Single')
+        ->ignorePaths(['migrations'])
+        ->toUseStrictTypes();
+});
+
+test('windows path separators', function () {
+    expect('Tests\Fixtures\Arch\IgnorePaths\Single')
+        ->ignorePaths(['database\\migrations'])
+        ->toUseStrictTypes();
+});
+
+test('non-ignored files still analyzed', function () {
+    expect('Tests\Fixtures\Arch\IgnorePaths\Dirty')
+        ->ignorePaths(['database/migrations'])
+        ->toUseStrictTypes();
+})->throws(ArchExpectationFailedException::class);
+
+test('violations caught in all paths without ignorePaths', function () {
+    expect('Tests\Fixtures\Arch\IgnorePaths\Single')
+        ->toUseStrictTypes();
+})->throws(ArchExpectationFailedException::class);
+
+test('chainable with not', function () {
+    expect('Tests\Fixtures\Arch\IgnorePaths\Single')
+        ->ignorePaths(['database/migrations'])
+        ->not->toBeAbstract();
+});

tests/Fixtures/Arch/IgnorePaths/Dirty/DirtyService.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace Tests\Fixtures\Arch\IgnorePaths\Dirty;
+
+class DirtyService {}

tests/Fixtures/Arch/IgnorePaths/Dirty/database/migrations/CreateUsersTable.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace Tests\Fixtures\Arch\IgnorePaths\Dirty\database\migrations;
+
+class CreateUsersTable {}

tests/Fixtures/Arch/IgnorePaths/Multiple/Service.php

@@ -0,0 +1,7 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures\Arch\IgnorePaths\Multiple;
+
+class Service {}

tests/Fixtures/Arch/IgnorePaths/Multiple/database/migrations/CreateUsersTable.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace Tests\Fixtures\Arch\IgnorePaths\Multiple\database\migrations;
+
+class CreateUsersTable {}

tests/Fixtures/Arch/IgnorePaths/Multiple/vendor/Library.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace Tests\Fixtures\Arch\IgnorePaths\Multiple\vendor;
+
+class Library {}

tests/Fixtures/Arch/IgnorePaths/Single/Service.php

@@ -0,0 +1,7 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures\Arch\IgnorePaths\Single;
+
+class Service {}

tests/Fixtures/Arch/IgnorePaths/Single/database/migrations/AbstractMigration.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace Tests\Fixtures\Arch\IgnorePaths\Single\database\migrations;
+
+abstract class AbstractMigration {}

tests/Fixtures/Arch/IgnorePaths/Single/database/migrations/CreateUsersTable.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace Tests\Fixtures\Arch\IgnorePaths\Single\database\migrations;
+
+class CreateUsersTable {}