Add ability to dump usages of a package, simplify bin script (#88)

Author: janedbal

README.md

@@ -5,7 +5,7 @@
 - ⚙️ **Configurable:** Fine-grained ignores via PHP config
 - 🕸️ **Lightweight:** No composer dependencies
 - 🍰 **Easy-to-use:** No config needed for first try
-- ✨ **Compatible:** PHP 7.2 - 8.3 
+- ✨ **Compatible:** PHP 7.2 - 8.3
 
 ## Comparison:
 
@@ -48,43 +48,49 @@ Found unused dependencies!
 (scanned 13970 files in 2.297 s)
 ```
 
-You can add `--verbose` to see more example classes & usages.
-
 ## Detected issues:
 This tool reads your `composer.json` and scans all paths listed in `autoload` & `autoload-dev` sections while analysing:
 
 ### Shadowed dependencies
   - 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 packages within your dependencies
-  - Ignorable by `--ignore-shadow-deps` or more granularly by `--config`
 
 ### 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`
-  - Ignorable by `--ignore-unused-deps` or more granularly by `--config`
 
 ### Dev dependencies in production code
   - 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`
-  - Ignorable by `--ignore-dev-in-prod-deps` or more granularly by `--config`
 
 ### Prod dependencies used only in dev paths
   - For libraries, this miscategorization can lead to uselessly required dependencies for your users
   - You should move those from `require` to `require-dev`
-  - Ignorable by `--ignore-prod-only-in-dev-deps` or more granularly by `--config`
 
 ### Unknown classes
   - Any class that cannot be autoloaded gets reported as we cannot say if that one is shadowed or not
-  - Ignorable 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.
+
+## Cli options:
+- `--composer-json path/to/composer.json` for custom path to composer.json
+- `--dump-usages symfony/console` to show usages of certain package(s), `*` placeholder is supported
+- `--config path/to/config.php` for custom path to config file
+- `--help` display usage & cli options
+- `--verbose` to see more example classes & usages
+- `--show-all-usages` to see all usages
+- `--ignore-unknown-classes` to globally ignore unknown classes
+- `--ignore-shadow-deps` to globally ignore shadow dependencies
+- `--ignore-unused-deps` to globally ignore unused dependencies
+- `--ignore-dev-in-prod-deps` to globally ignore dev dependencies in prod code
+- `--ignore-prod-only-in-dev-deps` to globally ignore prod dependencies used only in dev paths
+
 
 ## Configuration:
-You can provide custom path to config file by `--config=path/to/config.php` where the config file is PHP file returning `ShipMonk\ComposerDependencyAnalyser\Config\Configuration` object.
-It gets loaded automatically if it is located in cwd as `composer-dependency-analyser.php`.
+When a file named `composer-dependency-analyser.php` is located in cwd, it gets loaded automatically.
+The file must return `ShipMonk\ComposerDependencyAnalyser\Config\Configuration` object.
+You can use custom path and filename via `--config` cli option.
 Here is example of what you can do:
 
 ```php

bin/composer-dependency-analyser

@@ -1,44 +1,18 @@
 #!/usr/bin/env php
 <?php declare(strict_types=1);
 
-use Composer\Autoload\ClassLoader;
-use ShipMonk\ComposerDependencyAnalyser\Cli;
 use ShipMonk\ComposerDependencyAnalyser\Analyser;
-use ShipMonk\ComposerDependencyAnalyser\ComposerJson;
-use ShipMonk\ComposerDependencyAnalyser\Config\Configuration;
-use ShipMonk\ComposerDependencyAnalyser\Config\ErrorType;
 use ShipMonk\ComposerDependencyAnalyser\Exception\InvalidCliException;
-use ShipMonk\ComposerDependencyAnalyser\Exception\RuntimeException as OurRuntimeException;
+use ShipMonk\ComposerDependencyAnalyser\Exception\InvalidConfigException;
+use ShipMonk\ComposerDependencyAnalyser\Exception\InvalidPathException;
+use ShipMonk\ComposerDependencyAnalyser\Initializer;
 use ShipMonk\ComposerDependencyAnalyser\Printer;
+use ShipMonk\ComposerDependencyAnalyser\Result\ResultFormatter;
 use ShipMonk\ComposerDependencyAnalyser\Stopwatch;
 
 error_reporting(E_ALL);
 ini_set('display_errors', 'stderr');
 
-$usage = <<<EOD
-
-Usage:
-    vendor/bin/composer-analyser
-
-Options:
-    --help                      Print this help text and exit.
-    --verbose                   Print more usage examples
-    --composer-json <path>      Provide custom path to composer.json
-    --config <path>             Provide path to php configuration file
-                                (must return ShipMonk\ComposerDependencyAnalyser\Config\Configuration instance)
-
-Ignore options:
-    (or use --config for better granularity)
-
-    --ignore-unknown-classes            Ignore when class is not found in classmap
-    --ignore-unused-deps                Ignore all unused dependency issues
-    --ignore-shadow-deps                Ignore all shadow dependency issues
-    --ignore-dev-in-prod-deps           Ignore all dev dependency in production code issues
-    --ignore-prod-only-in-dev-deps      Ignore all prod dependency used only in dev paths issues
-
-
-EOD;
-
 $psr4Prefix = 'ShipMonk\\ComposerDependencyAnalyser\\';
 
 // autoloader for own classes (do not rely on presence in composer's autoloader)
@@ -51,141 +25,35 @@ spl_autoload_register(static function (string $class) use ($psr4Prefix): void {
     }
 });
 
+/** @var non-empty-string $cwd */
 $cwd = getcwd();
-$printer = new Printer($cwd === false ? '' : $cwd);
-
-/**
- * @return never
- */
-$exit = static function (string $message) use ($printer): void {
-    $printer->printLine("\n<red>$message</red>" . PHP_EOL);
-    exit(255);
-};
-
-if ($cwd === false) {
-    $exit('Cannot get current working directory');
-}
-if (!isset($argv)) {
-    $exit('No $argv available, possibly disabled register_argc_argv?');
-}
 
-try {
-    $cli = new Cli();
-    $cli->validateArgv($cwd, $argv);
-    $providedOptions = $cli->getProvidedOptions();
-} catch (InvalidCliException $e) {
-    $exit($e->getMessage());
-}
-
-if (isset($providedOptions['help'])) {
-    echo $usage;
-    exit;
-}
-
-$composerJsonPath = isset($providedOptions['composer-json'])
-    ? ($cwd . "/" . $providedOptions['composer-json'])
-    : ($cwd . "/composer.json");
+$printer = new Printer();
+$initializer = new Initializer($cwd, $printer);
+$stopwatch = new Stopwatch();
 
 try {
-    $composerJson = new ComposerJson($composerJsonPath);
-} catch (OurRuntimeException $e) {
-    $exit($e->getMessage());
-}
-
-// load vendor that belongs to given composer.json
-$autoloadFile = $composerJson->composerAutoloadPath;
-if (is_file($autoloadFile)) {
-    require_once $autoloadFile;
-} else {
-    $exit("Cannot find composer's autoload file, expected at '$autoloadFile'");
-}
-
-if (isset($providedOptions['config'])) {
-    $configPath = $cwd . "/" . $providedOptions['config'];
-
-    if (!is_file($configPath)) {
-        $exit("Invalid config path given, {$configPath} is not a file.");
-    }
-} else {
-    $configPath = $cwd . "/composer-dependency-analyser.php";
-}
+    $options = $initializer->initCliOptions($cwd, $argv);
+    $composerJson = $initializer->initComposerJson($cwd, $options);
+    $initializer->initComposerAutoloader($composerJson);
+    $configuration = $initializer->initConfiguration($options, $composerJson);
+    $classLoaders = $initializer->initComposerClassLoaders();
 
-if (is_file($configPath)) {
-    $printer->printLine('<gray>Using config</gray> ' . $configPath);
-
-    try {
-        $config = require $configPath;
-    } catch (OurRuntimeException $e) {
-        $exit($e->getMessage());
-    } catch (Throwable $e) {
-        $exit(get_class($e) . " in {$e->getFile()}:{$e->getLine()}\n > " . $e->getMessage());
-    }
-
-    if (!$config instanceof Configuration) {
-        $exit("Invalid config file, it must return instance of " . Configuration::class);
-    }
-} else {
-    $config = new Configuration();
-}
-
-$ignoreUnknown = isset($providedOptions['ignore-unknown-classes']);
-$ignoreUnused = isset($providedOptions['ignore-unused-deps']);
-$ignoreShadow = isset($providedOptions['ignore-shadow-deps']);
-$ignoreDevInProd = isset($providedOptions['ignore-dev-in-prod-deps']);
-$ignoreProdOnlyInDev = isset($providedOptions['ignore-prod-only-in-dev-deps']);
-
-if ($ignoreUnknown) {
-    $config->ignoreErrors([ErrorType::UNKNOWN_CLASS]);
-}
-if ($ignoreUnused) {
-    $config->ignoreErrors([ErrorType::UNUSED_DEPENDENCY]);
-}
-if ($ignoreShadow) {
-    $config->ignoreErrors([ErrorType::SHADOW_DEPENDENCY]);
-}
-if ($ignoreDevInProd) {
-    $config->ignoreErrors([ErrorType::DEV_DEPENDENCY_IN_PROD]);
-}
-if ($ignoreProdOnlyInDev) {
-    $config->ignoreErrors([ErrorType::PROD_DEPENDENCY_ONLY_IN_DEV]);
-}
-
-$loaders = ClassLoader::getRegisteredLoaders();
-if (count($loaders) > 1) {
-    $printer->printLine("\nDetected multiple class loaders:");
-    foreach ($loaders as $vendorDir => $_) {
-        $printer->printLine(" • <gray>$vendorDir</gray>");
-    }
-    $printer->printLine('');
-}
-
-if (count($loaders) === 0) {
-    $printer->printLine("\nNo composer class loader detected!\n");
-}
-
-try {
-    if ($config->shouldScanComposerAutoloadPaths()) {
-        foreach ($composerJson->autoloadPaths as $absolutePath => $isDevPath) {
-            $config->addPathToScan($absolutePath, $isDevPath);
-        }
+    $analyser = new Analyser($stopwatch, $classLoaders, $configuration, $composerJson->dependencies);
+    $result = $analyser->run();
 
-        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.');
-        }
-    }
+    $formatter = new ResultFormatter($cwd, $printer);
+    $exitCode = $formatter->format($result, $options, $configuration);
 
-    $stopwatch = new Stopwatch();
-    $analyser = new Analyser($stopwatch, $loaders, $config, $composerJson->dependencies);
-    $result = $analyser->run();
-} catch (OurRuntimeException $e) {
-    $exit($e->getMessage());
+} catch (
+    InvalidPathException |
+    InvalidConfigException |
+    InvalidCliException $e
+) {
+    $printer->printLine("\n<red>{$e->getMessage()}</red>" . PHP_EOL);
+    exit(255);
 }
 
-$exitCode = $printer->printResult($result, isset($providedOptions['verbose']), $config->shouldReportUnmatchedIgnoredErrors());
 exit($exitCode);
 
 

src/Analyser.php

@@ -33,9 +33,7 @@
 use function implode;
 use function in_array;
 use function is_file;
-use function ksort;
 use function preg_split;
-use function sort;
 use function str_replace;
 use function strlen;
 use function strpos;
@@ -124,6 +122,8 @@ public function run(): AnalysisResult
         $usedPackages = [];
         $prodPackagesUsedInProdPath = [];
 
+        $usages = [];
+
         $ignoreList = $this->config->getIgnoreList();
 
         foreach ($this->getUniqueFilePathsToScan() as $filePath => $isDevFilePath) {
@@ -179,6 +179,10 @@ public function run(): AnalysisResult
                 }
 
                 $usedPackages[$packageName] = true;
+
+                foreach ($lineNumbers as $lineNumber) {
+                    $usages[$packageName][$usedSymbol][] = new SymbolUsage($filePath, $lineNumber);
+                }
             }
         }
 
@@ -235,15 +239,10 @@ public function run(): AnalysisResult
             }
         }
 
-        ksort($classmapErrors);
-        ksort($shadowErrors);
-        ksort($devInProdErrors);
-        sort($prodOnlyInDevErrors);
-        sort($unusedErrors);
-
         return new AnalysisResult(
             $scannedFilesCount,
             $this->stopwatch->stop(),
+            $usages,
             $classmapErrors,
             $shadowErrors,
             $devInProdErrors,