refactor: implement lazy plugin path resolution

Author: josbeir

src/AttributeRegistry.php

@@ -85,7 +85,13 @@ private static function createFromConfig(): self
         $scannerConfig = (array)($config['scanner'] ?? []);
         $cacheConfig = (array)($config['cache'] ?? []);
 
-        $pathResolver = new PathResolver(implode(PATH_SEPARATOR, self::resolveAllPaths()));
+        // Create PathResolver with lazy plugin path resolution
+        // The callback is only invoked when scanning is needed (cache miss)
+        $pathResolver = new PathResolver(
+            ROOT,
+            fn(): array => (new PluginPathResolver())->getEnabledPluginPaths(),
+        );
+
         $cache = new AttributeCache(
             (string)($cacheConfig['config'] ?? 'default'),
             (bool)($cacheConfig['enabled'] ?? true),
@@ -106,30 +112,6 @@ private static function createFromConfig(): self
         return new self($scanner, $cache);
     }
 
-    /**
-     * Resolve all base paths from app + all enabled plugins.
-     *
-     * Uses PluginPathResolver to get ALL enabled plugins (including CLI-only)
-     * regardless of current request context. This ensures atomic discovery
-     * where the same attributes are discovered in both CLI and web contexts.
-     *
-     * @return array<string> Resolved base paths
-     */
-    private static function resolveAllPaths(): array
-    {
-        $basePaths = [];
-        $basePaths[] = ROOT;
-
-        $pluginPathResolver = new PluginPathResolver();
-        $pluginPaths = $pluginPathResolver->getEnabledPluginPaths();
-
-        foreach ($pluginPaths as $path) {
-            $basePaths[] = $path;
-        }
-
-        return $basePaths;
-    }
-
     /**
      * Discover all attributes from configured paths.
      *

src/Service/PathResolver.php

@@ -3,6 +3,7 @@
 
 namespace AttributeRegistry\Service;
 
+use Closure;
 use Generator;
 use RecursiveDirectoryIterator;
 use RecursiveIteratorIterator;
@@ -14,25 +15,52 @@ class PathResolver
      */
     private array $basePaths;
 
+    private bool $pathsResolved = false;
+
     /**
      * Constructor for PathResolver.
      *
-     * @param string $basePaths Base paths separated by PATH_SEPARATOR
+     * @param string $basePath Primary base path (typically ROOT)
+     * @param \Closure|null $pluginPathsCallback Optional lazy callback returning additional plugin paths
      */
     public function __construct(
-        string $basePaths,
+        string $basePath,
+        private readonly ?Closure $pluginPathsCallback = null,
     ) {
-        $this->basePaths = array_filter(explode(PATH_SEPARATOR, $basePaths));
+        $this->basePaths = array_filter(explode(PATH_SEPARATOR, $basePath));
+    }
+
+    /**
+     * Ensure all paths (including plugin paths) are resolved.
+     * Only resolves once on first call for performance.
+     */
+    private function ensureAllPathsResolved(): void
+    {
+        if ($this->pathsResolved) {
+            return;
+        }
+
+        if ($this->pluginPathsCallback instanceof \Closure) {
+            $pluginPaths = ($this->pluginPathsCallback)();
+            foreach ($pluginPaths as $path) {
+                $this->basePaths[] = $path;
+            }
+        }
+
+        $this->pathsResolved = true;
     }
 
     /**
      * Resolve all paths from glob patterns.
+     * Lazily resolves plugin paths on first invocation.
      *
      * @param array<string> $globPatterns Array of glob patterns
      * @return \Generator<string> Generator yielding file paths
      */
     public function resolveAllPaths(array $globPatterns): Generator
     {
+        $this->ensureAllPathsResolved();
+
         foreach ($this->basePaths as $basePath) {
             foreach ($this->resolvePatternsForPath($basePath, $globPatterns) as $path) {
                 yield $path;

tests/TestCase/Service/PathResolverTest.php

@@ -97,6 +97,95 @@ public function testResolveMultipleBasePaths(): void
         rmdir($pluginPath);
     }
 
+    public function testLazyPluginPathCallbackIsNotInvokedOnConstruction(): void
+    {
+        $callbackInvoked = false;
+        $callback = function () use (&$callbackInvoked): array {
+            $callbackInvoked = true;
+
+            return ['/some/plugin/path'];
+        };
+
+        new PathResolver($this->testAppPath, $callback);
+
+        // Callback should NOT be invoked during construction
+        $this->assertFalse($callbackInvoked, 'Plugin path callback should not be invoked during construction');
+    }
+
+    public function testLazyPluginPathCallbackIsInvokedOnFirstResolve(): void
+    {
+        $callbackInvoked = false;
+        $callback = function () use (&$callbackInvoked): array {
+            $callbackInvoked = true;
+
+            return [];
+        };
+
+        $resolver = new PathResolver($this->testAppPath, $callback);
+
+        // Invoke resolveAllPaths to trigger callback
+        iterator_to_array($resolver->resolveAllPaths(['src/*.php']));
+
+        // Callback should be invoked on first resolve
+        $this->assertTrue($callbackInvoked, 'Plugin path callback should be invoked on first path resolution');
+    }
+
+    public function testLazyPluginPathCallbackIsOnlyInvokedOnce(): void
+    {
+        $callbackInvokeCount = 0;
+        $callback = function () use (&$callbackInvokeCount): array {
+            $callbackInvokeCount++;
+
+            return [];
+        };
+
+        $resolver = new PathResolver($this->testAppPath, $callback);
+
+        // Invoke resolveAllPaths multiple times
+        iterator_to_array($resolver->resolveAllPaths(['src/*.php']));
+        iterator_to_array($resolver->resolveAllPaths(['src/*.php']));
+        iterator_to_array($resolver->resolveAllPaths(['src/*.php']));
+
+        // Callback should only be invoked once
+        $this->assertSame(1, $callbackInvokeCount, 'Plugin path callback should only be invoked once');
+    }
+
+    public function testLazyPluginPathsAreMergedWithBasePath(): void
+    {
+        // Create a plugin path
+        $pluginPath = sys_get_temp_dir() . '/attribute_registry_lazy_plugin_' . uniqid();
+        mkdir($pluginPath . '/src', 0755, true);
+        file_put_contents($pluginPath . '/src/PluginClass.php', "<?php\n// Plugin file");
+
+        $callback = fn(): array => [$pluginPath];
+
+        $resolver = new PathResolver($this->testAppPath, $callback);
+
+        $patterns = ['src/*.php'];
+        $paths = iterator_to_array($resolver->resolveAllPaths($patterns));
+
+        // Should find files from both base path and lazily resolved plugin paths
+        $this->assertContains($this->testAppPath . '/src/TestClass.php', $paths);
+        $this->assertContains($pluginPath . '/src/PluginClass.php', $paths);
+
+        // Cleanup plugin path
+        unlink($pluginPath . '/src/PluginClass.php');
+        rmdir($pluginPath . '/src');
+        rmdir($pluginPath);
+    }
+
+    public function testPathResolverWorksWithoutLazyCallback(): void
+    {
+        // Ensure backward compatibility - can be constructed without callback
+        $resolver = new PathResolver($this->testAppPath);
+
+        $patterns = ['src/*.php'];
+        $paths = iterator_to_array($resolver->resolveAllPaths($patterns));
+
+        $this->assertContains($this->testAppPath . '/src/TestClass.php', $paths);
+        $this->assertNotEmpty($paths);
+    }
+
     private function createTestStructure(): void
     {
         $structure = [