Replace ignore-paths with include/exclude

Author: olvlvl

README.md

@@ -12,7 +12,7 @@ Later, these targets can be retrieved through a convenient interface.
 
 #### Features
 
-- Zero configuration
+- Little configuration
 - No reflection in the generated file
 - No impact on performance
 - No dependency (except Composer of course)
@@ -85,6 +85,28 @@ future.
 want to add it to your `.gitignore` file.
 
 
+#### Sample configuration
+
+The plugin only inspects paths and files specified in the configuration, that's usually your "src"
+directory. Add this section to your `composer.json` file to enable the generation of the attributes
+file on autoload dump.
+
+Check the [Configuration options](#configuration) for more details.
+
+```json
+{
+  "extra": {
+    "composer-attribute-collector": {
+      "include": [
+        "src"
+      ]
+    }
+  }
+}
+```
+
+
+
 
 ## Frequently Asked Questions
 
@@ -122,34 +144,40 @@ You can require the attributes file as shown in the usage example, but it's pref
 
 ## Configuration
 
-### Ignoring paths ([root-only][])
+### Excluding paths or files ([root-only][])
 
-composer-attribute-collector inspects files that participate in the autoload process. This can cause
-issues with files that have side effects. For instance, `symfony/cache` is known to cause issues, so
-we're excluding paths matching `{vendor}/symfony/cache/Traits` from inspection. Additional paths can
-be specified using the `extra` section of `composer.json`. The specified paths are relative to the
-`composer.json` file, and the `{vendor}` placeholder is replaced with the path to the vendor folder.
+Use the `include` property to define the paths or files to inspect for attributes. Without this
+property, the attributes file will be empty.
+
+The specified paths are relative to the `composer.json` file, and the `{vendor}` placeholder is
+replaced with the path to the vendor folder.
 
 ```json
 {
   "extra": {
     "composer-attribute-collector": {
-      "ignore-paths": [
-        "path/to/ignore"
+      "include": [
+        "path-or-file/to/include"
       ]
     }
   }
 }
 ```
 
-For instance, if you are only concerned about the attributes of your own project, you could ignore the vendor directory:
+### Excluding paths or files ([root-only][])
+
+Use the `exclude` property to excluded paths or files from inspection. This is handy when files
+cause issues or have side effects.
+
+The specified paths are relative to the `composer.json` file, and the `{vendor}` placeholder is
+replaced with the path to the vendor folder.
 
 ```json
 {
   "extra": {
     "composer-attribute-collector": {
-      "ignore-paths": [
-        "vendor"
+      "exclude": [
+        "path-or-file/to/ignore"
       ]
     }
   }
@@ -168,6 +196,20 @@ Use the `symfony` command to create a new project. If you don't have it yet, you
 symfony new --webapp my_project
 ```
 
+Add the `composer-attribute-collector` node to `extra` in the `composer.json` file:
+
+```json
+{
+  "extra": {
+    "composer-attribute-collector": {
+      "include": [
+        "src"
+      ]
+    }
+  }
+}
+```
+
 Now get into that project and install the plugin. You'll be asked if you trust the plugin and wish
 to activate it. If you wish to continue, choose `y`.
 

src/Config.php

@@ -7,7 +7,6 @@
 use InvalidArgumentException;
 use RuntimeException;
 
-use function array_merge;
 use function dirname;
 use function is_string;
 use function realpath;
@@ -24,14 +23,8 @@
 final class Config
 {
     public const EXTRA = 'composer-attribute-collector';
-    public const EXTRA_IGNORE_PATHS = 'ignore-paths';
-
-    public const BUILTIN_IGNORE_PATHS = [
-
-        // https://github.com/olvlvl/composer-attribute-collector/issues/4
-        "{vendor}/symfony/cache/Traits"
-
-    ];
+    public const EXTRA_INCLUDE = 'include';
+    public const EXTRA_EXCLUDE = 'exclude';
 
     /**
      * If a path starts with this placeholder, it is replaced with the absolute path to the vendor directory.
@@ -55,30 +48,31 @@ public static function from(PartialComposer $composer): self
 
         $rootDir .= DIRECTORY_SEPARATOR;
 
-        /** @var array{ ignore-paths?: non-empty-string[] } $extra */
+        /** @var array{ include?: non-empty-string[], exclude?: non-empty-string[] } $extra */
         $extra = $composer->getPackage()->getExtra()[self::EXTRA] ?? [];
 
-        $ignorePaths = self::expandPaths(
-            array_merge($extra[self::EXTRA_IGNORE_PATHS] ?? [], self::BUILTIN_IGNORE_PATHS),
-            $vendorDir,
-            $rootDir
-        );
+        $include = self::expandPaths($extra[self::EXTRA_INCLUDE] ?? [], $vendorDir, $rootDir);
+        $exclude = self::expandPaths($extra[self::EXTRA_EXCLUDE] ?? [], $vendorDir, $rootDir);
 
         return new self(
             attributesFile: "$vendorDir/attributes.php",
-            ignorePaths: $ignorePaths,
+            include: $include,
+            exclude: $exclude,
         );
     }
 
     /**
      * @param non-empty-string $attributesFile
      *     Absolute path to the `attributes.php` file.
-     * @param string[] $ignorePaths
-     *     Paths that should be ignored for attributes collection.
+     * @param string[] $include
+     *     Paths that should be included to attributes collection.
+     * @param string[] $exclude
+     *     Paths that should be excluded from attributes collection.
      */
     public function __construct(
         public string $attributesFile,
-        public array $ignorePaths,
+        public array $include,
+        public array $exclude,
     ) {
     }
 

src/Filter/PathFilter.php

@@ -1,12 +1,5 @@
 <?php
 
-/*
- * (c) Olivier Laviale <olivier.laviale@gmail.com>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
 namespace olvlvl\ComposerAttributeCollector\Filter;
 
 use Composer\IO\IOInterface;
@@ -20,23 +13,34 @@
 final class PathFilter implements Filter
 {
     /**
-     * @param string[] $matches
+     * @param string[] $include
+     * @param string[] $exclude
      */
     public function __construct(
-        private array $matches
+        private array $include,
+        private array $exclude,
     ) {
     }
 
     public function filter(string $filepath, string $class, IOInterface $io): bool
     {
-        foreach ($this->matches as $match) {
+        foreach ($this->exclude as $match) {
             if (str_starts_with($filepath, $match)) {
                 $io->debug("Discarding '$class' because its path matches '$match'");
 
                 return false;
             }
         }
 
-        return true;
+        foreach ($this->include as $match) {
+            if (str_starts_with($filepath, $match)) {
+
+                return true;
+            }
+        }
+
+        $io->debug("Discarding '$class' because it does not match any included path");
+
+        return false;
     }
 }

src/Plugin.php

@@ -1,12 +1,5 @@
 <?php
 
-/*
- * (c) Olivier Laviale <olivier.laviale@gmail.com>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
 namespace olvlvl\ComposerAttributeCollector;
 
 use Composer\Composer;
@@ -20,9 +13,7 @@
 use olvlvl\ComposerAttributeCollector\Filter\PathFilter;
 use ReflectionException;
 
-use function array_merge;
 use function file_put_contents;
-use function is_string;
 use function microtime;
 use function spl_autoload_register;
 use function sprintf;
@@ -163,7 +154,10 @@ private static function setupAutoload(array $classMap): void
     private static function buildFileFilter(Config $config): Filter
     {
         return new Filter\Chain([
-            new PathFilter($config->ignorePaths),
+            new PathFilter(
+                include: $config->include,
+                exclude: $config->exclude
+            ),
             new ContentFilter(),
             new InterfaceFilter()
         ]);

tests/ConfigTest.php

@@ -18,10 +18,14 @@ public function testFrom(): void
     {
         $extra = [
             Config::EXTRA => [
-                Config::EXTRA_IGNORE_PATHS => [
+                Config::EXTRA_INCLUDE => [
+                    'tests',
                     '{vendor}/vendor1/package1',
-                    'tests/Acme/PSR4/IncompatibleSignature.php'
-                ]
+                ],
+                Config::EXTRA_EXCLUDE => [
+                    'tests/Acme/PSR4/IncompatibleSignature.php',
+                    '{vendor}/vendor1/package1/file.php',
+                ],
             ]
         ];
 
@@ -44,11 +48,14 @@ public function testFrom(): void
 
         $expected = new Config(
             attributesFile: "$cwd/vendor/attributes.php",
-            ignorePaths: [
+            include: [
+                "$cwd/tests",
                 "$cwd/vendor/vendor1/package1",
+            ],
+            exclude: [
                 "$cwd/tests/Acme/PSR4/IncompatibleSignature.php",
-                "$cwd/vendor/symfony/cache/Traits",
-            ]
+                "$cwd/vendor/vendor1/package1/file.php",
+            ],
         );
 
         $actual = Config::from($composer);

tests/Filter/PathFilterTest.php

@@ -21,9 +21,16 @@ protected function setUp(): void
     {
         parent::setUp();
 
-        $this->filter = new PathFilter([
-            "/absolute/path/to/symfony/cache/Traits"
-        ]);
+        $this->filter = new PathFilter(
+            include: [
+                "/app/src",
+                "/app/vendor",
+            ],
+            exclude: [
+                "/app/src/Excluded.php",
+                "/app/vendor/symfony/cache/Traits",
+            ],
+        );
     }
 
     /**
@@ -43,7 +50,7 @@ public function testFilter(string $filepath, string $class, bool $expected): voi
             $io
                 ->expects($this->once())
                 ->method('debug')
-                ->with($this->stringStartsWith("Discarding '$class' because its path matches"));
+                ->with($this->stringStartsWith("Discarding '$class'"));
         }
 
         $actual = $this->filter->filter($filepath, $class, $io);
@@ -58,10 +65,13 @@ public function provideFilter(): array
     {
         return [
 
-            [ "/absolute/path/to/symfony/cache/Traits/RedisCluster5Proxy.php", "RedisCluster5Proxy", false ],
-            [ "some/prefix/absolute/path/to/symfony/cache/Traits/RedisCluster5Proxy.php", "RedisCluster5Proxy", true ],
-            [ "symfony/cache/Traits/RedisCluster5Proxy.php", "RedisCluster5Proxy", true ],
-            [ "/absolute/path/to/symfony/routing/Route.php", "Route", true ],
+            [ "/app/src/some/file.php", "SampleClass", true ],
+            [ "/app/src/Excluded.php", "SampleClass", false ],
+            [ "/app/vendor/symfony/routing/Route.php", "Route", true ],
+            [ "/app/vendor/symfony/cache/Traits/RedisCluster5Proxy.php", "RedisCluster5Proxy", false ],
+            [ "vendor/symfony/cache/Traits/RedisCluster5Proxy.php", "RedisCluster5Proxy", false ],
+            [ "symfony/cache/Traits/RedisCluster5Proxy.php", "RedisCluster5Proxy", false ],
+            [ "/vendor/symfony/routing/Route.php", "Route", false ],
 
         ];
     }

tests/PluginTest.php

@@ -82,7 +82,10 @@ protected function setUp(): void
 
         $config = new Config(
             $filepath,
-            [
+            include: [
+               "$cwd/tests"
+            ],
+            exclude: [
                 "$cwd/tests/Acme/PSR4/IncompatibleSignature.php"
             ]
         );