Configuration: allow extra paths, granual ignores etc. (#8)

Author: janedbal

README.md

@@ -36,13 +36,15 @@ Example output:
 Found shadow dependencies!
 (those are used, but not listed as dependency in composer.json)
 
-  • Nette\Utils\Json (nette/utils)
-  • Nette\Utils\JsonException (nette/utils)
-  • Symfony\Contracts\Service\Attribute\Required (symfony/service-contracts)
+  • symfony/service-contracts
+    e.g. Symfony\Contracts\Service\Attribute\Required in app/Controller/ProductController.php:24
 
-```
+Found unused dependencies!
+(those are listed in composer.json, but no usage was found in scanned paths)
+
+  • nette/utils
 
-You can add `--verbose` flag to see first usage (file & line) of each class.
+```
 
 ## Detected issues:
 This tool reads your `composer.json` and scans all paths listed in both `autoload` sections while analysing:
@@ -51,20 +53,76 @@ This tool reads your `composer.json` and scans all paths listed in both `autoloa
   - Those are dependencies of your dependencies, which are not listed in `composer.json`
   - Your code can break when your direct dependency gets updated to newer version which does not require that shadowed dependency anymore
   - You should list all those classes within your dependencies
+
 - **Unused dependencies**
   - Any non-dev dependency is expected to have at least single usage within the scanned paths
+  - To avoid false positives here, you might need to adjust scanned paths or ignore some packages by `--config`
+
 - **Dev dependencies in production code**
-  - Your code can break once you run your application with `composer install --no-dev`
-  - You should move those to `require` from `require-dev`
+  - For libraries, this is risky as your users might not have those installed
+  - For applications, it can break once you run it with `composer install --no-dev`
+  - You should move those from `require-dev` to `require`
+  - If you want to ignore some packages here, use `--config`
+
 - **Unknown classes**
   - Any class missing in composer classmap gets reported as we cannot say if that one is shadowed or not
-  - This might be expected in some cases, so you can disable this behaviour by `--ignore-unknown-classes`
+  - This might be expected in some cases, so you can disable this behaviour by `--ignore-unknown-classes` or more granularly by `--config`
 
 It is expected to run this tool in root of your project, where the `composer.json` is located.
 If you want to run it elsewhere, you can use `--composer-json=path/to/composer.json` option.
 
 Currently, it only supports those autoload sections: `psr-4`, `psr-0`, `files`.
 
+## Configuration:
+You can provide custom path to config file by `--config=path/to/config.php` where the config file is PHP file returning `ShipMonk\Composer\Config\Configuration` object.
+Here is example of what you can do:
+
+```php
+<?php
+
+use ShipMonk\Composer\Config\Configuration;
+use ShipMonk\Composer\Config\ErrorType;
+
+$config = new Configuration();
+
+return $config
+    // disable scanning autoload & autoload-dev paths from composer.json
+    // with such option, you should add custom paths by addPathToScan() or addPathsToScan()
+    ->disableComposerAutoloadPathScan()
+
+    // disable detection of dev dependencies in production code globally
+    ->ignoreErrors([ErrorType::DEV_DEPENDENCY_IN_PROD])
+
+    // overwrite file extensions to scan, defaults to 'php'
+    ->setFileExtensions(['php'])
+
+    // add extra path to scan
+    // for multiple paths at once, use addPathsToScan()
+    ->addPathToScan(__DIR__ . '/build', isDev: false)
+
+    // ignore errors on specific paths
+    // this can be handy when DIC container file was passed as extra path, but you want to ignore shadow dependencies there
+    // for multiple paths at once, use ignoreErrorsOnPaths()
+    ->ignoreErrorsOnPath(__DIR__ . '/cache/DIC.php', [ErrorType::SHADOW_DEPENDENCY])
+
+    // ignore errors on specific packages
+    // you might have various reasons to ignore certain errors
+    // e.g. polyfills are often used in libraries, but those are obviously unused when running with latest PHP
+    // for multiple packages at once, use ignoreErrorsOnPackages()
+    ->ignoreErrorsOnPackage('symfony/polyfill-php73', [ErrorType::UNUSED_DEPENDENCY])
+
+    // allow using classes not present in composer's autoloader
+    // e.g. a library may conditionally support some feature only when Memcached is available
+    ->ignoreUnknownClasses(['Memcached'])
+
+    // allow using classes not present in composer's autoloader by regex
+    // e.g. when you want to ignore whole namespace of classes
+    ->ignoreUnknownClassesRegex('~^PHPStan\\.*?~')
+;
+```
+
+All paths are expected to exist. If you need some glob functionality, you can do it in your config file and pass the expanded list to e.g. `ignoreErrorsOnPaths`.
+
 ## Limitations:
 - Files without namespace has limited support
   - Only classes with use statements and FQNs are detected

bin/composer-dependency-analyser

@@ -4,18 +4,21 @@
 use Composer\Autoload\ClassLoader;
 use ShipMonk\Composer\ComposerDependencyAnalyser;
 use ShipMonk\Composer\ComposerJson;
+use ShipMonk\Composer\Config\Configuration;
+use ShipMonk\Composer\Config\ErrorType;
 use ShipMonk\Composer\Printer;
 
 $usage = <<<EOD
 
 Usage:
-    vendor/bin/composer-analyser dir-to-scan
+    vendor/bin/composer-analyser
 
 Options:
     --help                      Print this help text and exit.
-    --verbose                   Print verbose output
     --ignore-unknown-classes    Ignore when class is not found in classmap
     --composer-json <path>      Provide custom path to composer.json
+    --config <path>             Provide path to php configuration file
+                                (must return ShipMonk\Composer\Config\Configuration instance)
 
 EOD;
 
@@ -41,24 +44,44 @@ $exit = static function (string $message) use ($printer): void {
     exit(255);
 };
 
-/** @var int $restIndex */
-$providedOptions = getopt('', ['help', 'verbose', 'ignore-unknown-classes', 'composer-json:'], $restIndex);
+/** @var string[] $providedOptions */
+$providedOptions = getopt('', ['help', 'ignore-unknown-classes', 'composer-json:', 'config:'], $restIndex);
 
-$cwd = getcwd();
+/** @var int $restIndex */
 $providedPaths = array_slice($argv, $restIndex);
+$cwd = getcwd();
 
 if (isset($providedOptions['help'])) {
     echo $usage;
     exit;
 }
 
-$verbose = isset($providedOptions['verbose']);
+if (isset($providedOptions['config'])) {
+    $printer->printLine('Using config ' . $providedOptions['config'] . PHP_EOL);
+
+    $configPath = $cwd . "/" . $providedOptions['config'];
+    if (!is_file($configPath)) {
+        $exit("Invalid config path given, {$providedOptions['config']} is not a file.");
+    }
+
+    $config = require $configPath;
+
+    if (!$config instanceof Configuration) {
+        $exit("Invalid config file, must return instance of " . Configuration::class);
+    }
+} else {
+    $config = new Configuration();
+}
+
 $ignoreUnknown = isset($providedOptions['ignore-unknown-classes']);
 
+if ($ignoreUnknown) {
+    $config->ignoreErrors([ErrorType::UNKNOWN_CLASS]);
+}
+
 /** @var non-empty-string $cwd */
 $cwd = getcwd();
 
-/** @var string[] $providedOptions */
 $composerJsonPath = isset($providedOptions['composer-json'])
     ? ($cwd . "/" . $providedOptions['composer-json'])
     : ($cwd . "/composer.json");
@@ -97,19 +120,43 @@ if (!$loaders[$vendorDir]->isClassMapAuthoritative()) {
     $exit('Run \'composer dump-autoload --classmap-authoritative\' first');
 }
 
-$absolutePaths = [];
-foreach ($composerJson->autoloadPaths as $relativePath => $isDevPath) {
-    $absolutePath = dirname($composerJsonPath) . '/' . $relativePath;
-    if (!is_dir($absolutePath) && !is_file($absolutePath)) {
-        $exit("Unexpected path detected, $absolutePath is not a file nor directory.");
+if ($config->shouldScanComposerAutoloadPaths()) {
+    foreach ($composerJson->autoloadPaths as $relativePath => $isDevPath) {
+        $absolutePath = dirname($composerJsonPath) . '/' . $relativePath;
+        $config->addPathToScan($absolutePath, $isDevPath);
+    }
+
+    if ($config->getPathsToScan() === []) {
+        $exit('No paths to scan! There is no composer autoload section and no extra path to scan configured.');
+    }
+} else {
+    if ($config->getPathsToScan() === []) {
+        $exit('No paths to scan! Scanning composer\'s \'autoload\' sections is disabled and no extra path to scan was configured.');
+    }
+}
+
+foreach ($config->getPathsToScan() as $pathToScan) {
+    if (!is_dir($pathToScan->getPath()) && !is_file($pathToScan->getPath())) {
+        $exit("Invalid scan path given, {$pathToScan->getPath()} is not a file nor directory.");
+    }
+}
+
+foreach ($config->getPathsToExclude() as $pathToExclude) {
+    if (!is_dir($pathToExclude) && !is_file($pathToExclude)) {
+        $exit("Invalid exclude path given, {$pathToExclude} is not a file nor directory.");
+    }
+}
+
+foreach ($config->getPathsWithIgnore() as $pathWithIgnore) {
+    if (!is_dir($pathWithIgnore) && !is_file($pathWithIgnore)) {
+        $exit("Invalid ignore path given, {$pathWithIgnore} is not a file nor directory.");
     }
-    $absolutePaths[$absolutePath] = $isDevPath;
 }
 
-$detector = new ComposerDependencyAnalyser($vendorDir, $loaders[$vendorDir]->getClassMap(), $composerJson->dependencies, ['php']);
-$errors = $detector->scan($absolutePaths);
+$analyser = new ComposerDependencyAnalyser($config, $vendorDir, $loaders[$vendorDir]->getClassMap(), $composerJson->dependencies);
+$errors = $analyser->run();
 
-$exitCode = $printer->printResult(array_values($errors), $ignoreUnknown, $verbose);
+$exitCode = $printer->printResult($errors);
 exit($exitCode);
 
 

composer.lock

@@ -407,7 +407,6 @@
     <rule ref="SlevomatCodingStandard.ControlStructures.AssignmentInCondition"/>
     <rule ref="SlevomatCodingStandard.ControlStructures.BlockControlStructureSpacing"/>
     <rule ref="SlevomatCodingStandard.ControlStructures.DisallowContinueWithoutIntegerOperandInSwitch"/>
-    <rule ref="SlevomatCodingStandard.ControlStructures.UselessIfConditionWithReturn"/>
     <rule ref="SlevomatCodingStandard.ControlStructures.UselessTernaryOperator"/>
     <rule ref="SlevomatCodingStandard.ControlStructures.EarlyExit">
         <exclude name="SlevomatCodingStandard.ControlStructures.EarlyExit.EarlyExitNotUsed"/> <!-- leads to less readable code in some cases -->