[dependencies] Add shadow dependency audit option

Author: coisa

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Keep required PHPUnit matrix checks reporting after workflow-managed `.github/wiki` pointer commits by running the pull-request test workflow without top-level path filters and aligning the packaged consumer test wrapper (#230)
+- Ignore intentional Composer Dependency Analyser shadow dependency findings by default while adding `dependencies --show-shadow-dependencies` for audits (#233)
 
 ## [1.21.0] - 2026-04-24
 

docs/commands/dependencies.rst

@@ -55,6 +55,16 @@ Options
    Asks ``composer-dependency-analyser`` to dump usages for the given package
    or wildcard pattern and enables ``--show-all-usages`` automatically.
 
+``--show-shadow-dependencies`` (optional)
+   Reports shadow dependencies instead of applying the Fast Forward default
+   ignore for intentional dependency groups.
+
+   By default, DevTools hides ``SHADOW_DEPENDENCY`` findings because Fast
+   Forward packages may intentionally require ecosystem bundles, meta packages,
+   or convenience packages that install related dependencies for consumers.
+   Use this flag when auditing whether a package has accidental shadow
+   dependencies that should be removed or documented more precisely.
+
 ``--json``
    Emit a structured machine-readable payload instead of the normal terminal
    output.
@@ -95,6 +105,12 @@ Dump all matched usages for one package:
 
    composer dependencies --dump-usage=symfony/console
 
+Audit shadow dependencies:
+
+.. code-block:: bash
+
+   composer dependencies --show-shadow-dependencies
+
 Apply the upgrade workflow and then analyze dependencies:
 
 .. code-block:: bash
@@ -135,6 +151,8 @@ Behavior
     consumer repositories can extend the baseline instead of copying it whole
   - ``--dump-usages <package>`` and ``--show-all-usages`` when ``--dump-usage``
     is passed to the DevTools command
+  - the ``FAST_FORWARD_DEV_TOOLS_SHOW_SHADOW_DEPENDENCIES`` process environment
+    flag, which is enabled when ``--show-shadow-dependencies`` is passed
 - ``jack breakpoint`` maps ``--max-outdated`` to Jack's ``--limit`` option.
 - ``--max-outdated=-1`` keeps ``jack breakpoint`` in the workflow for reporting,
   but its failure is ignored so only missing or unused dependency findings fail

docs/configuration/overriding-defaults.rst

@@ -141,6 +141,13 @@ consumers can extend the default configuration using the
 This approach keeps the Fast Forward baseline while letting consumer
 repositories add project-specific ignores or scan rules.
 
+The baseline ignores ``SHADOW_DEPENDENCY`` findings by default because Fast
+Forward packages may intentionally require dependency groups, ecosystem bundles,
+or meta packages that install related dependencies for consumers. Run
+``composer dependencies --show-shadow-dependencies`` when you want to audit
+those findings and decide whether a package should keep, document, or remove a
+direct dependency.
+
 What Is Not Overwritten Automatically
 --------------------------------------
 

docs/running/specialized-commands.rst

@@ -77,6 +77,7 @@ Analyzes missing, unused, misplaced, and outdated Composer dependencies.
    composer dependencies --max-outdated=-1
    composer dependencies --dev
    composer dependencies --dump-usage=symfony/console
+   composer dependencies --show-shadow-dependencies
    composer dependencies --upgrade --dev
 
 Important details:
@@ -88,6 +89,10 @@ Important details:
   override locally;
 - ``--dump-usage=<package>`` forwards to
   ``composer-dependency-analyser --dump-usages <package> --show-all-usages``;
+- ``--show-shadow-dependencies`` keeps shadow dependency findings visible for
+  audits; without it, DevTools hides intentional Fast Forward dependency-group
+  shadows so CI does not fail on ecosystem or meta packages that deliberately
+  install related dependencies for consumers;
 - it uses ``jack breakpoint --limit=<max-outdated>`` to fail when too many
   outdated dependencies accumulate;
 - ``--max-outdated=-1`` keeps the Jack outdated report in the output but

src/Config/ComposerDependencyAnalyserConfig.php

@@ -41,6 +41,8 @@
  */
 final class ComposerDependencyAnalyserConfig
 {
+    public const string ENV_SHOW_SHADOW_DEPENDENCIES = 'FAST_FORWARD_DEV_TOOLS_SHOW_SHADOW_DEPENDENCIES';
+
     /**
      * Dependencies that are only required by the packaged DevTools distribution itself.
      *
@@ -90,6 +92,10 @@ public static function configure(?callable $customize = null): Configuration
     {
         $configuration = new Configuration();
 
+        if (! self::shouldShowShadowDependencies()) {
+            self::applyIgnoresShadowDependencies($configuration);
+        }
+
         if (DevToolsPathResolver::isRepositoryCheckout()) {
             self::applyPackagedRepositoryIgnores($configuration);
         }
@@ -101,12 +107,39 @@ public static function configure(?callable $customize = null): Configuration
         return $configuration;
     }
 
+    /**
+     * The default configuration ignores shadow dependencies because Fast
+     * Forward packages MAY intentionally require dependency groups. For example,
+     * ecosystem or meta packages can require related PSR or framework packages
+     * so consumers do not need to install every package one by one.
+     *
+     * @param Configuration $configuration the analyser configuration to customize
+     *
+     * @return Configuration the modified configuration with shadow dependencies ignored
+     */
+    public static function applyIgnoresShadowDependencies(Configuration $configuration): Configuration
+    {
+        $configuration->ignoreErrors([ErrorType::SHADOW_DEPENDENCY]);
+
+        return $configuration;
+    }
+
+    /**
+     * Determines whether shadow dependency reports SHOULD remain visible.
+     *
+     * @return bool
+     */
+    public static function shouldShowShadowDependencies(): bool
+    {
+        return '1' === getenv(self::ENV_SHOW_SHADOW_DEPENDENCIES);
+    }
+
     /**
      * Applies the ignores required only by the packaged DevTools repository.
      *
      * @param Configuration $configuration the analyser configuration to customize
      *
-     * @return void
+     * @return Configuration the modified configuration with packaged repository ignores applied
      */
     public static function applyPackagedRepositoryIgnores(Configuration $configuration): Configuration
     {

src/Console/Command/DependenciesCommand.php

@@ -22,6 +22,7 @@
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
 use Composer\Command\BaseCommand;
 use FastForward\DevTools\Console\Input\HasJsonOption;
+use FastForward\DevTools\Config\ComposerDependencyAnalyserConfig;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use InvalidArgumentException;
@@ -101,6 +102,11 @@ protected function configure(): void
                 name: 'dump-usage',
                 mode: InputOption::VALUE_REQUIRED,
                 description: 'Dump usages for the given package pattern and show all matched usages.',
+            )
+            ->addOption(
+                name: 'show-shadow-dependencies',
+                mode: InputOption::VALUE_NONE,
+                description: 'Report shadow dependencies instead of applying Fast Forward intentional-shadow ignores.',
             );
     }
 
@@ -176,7 +182,13 @@ private function getComposerDependencyAnalyserCommand(InputInterface $input): Pr
                 ->withArgument('--show-all-usages');
         }
 
-        return $processBuilder->build('vendor/bin/composer-dependency-analyser');
+        $showShadowDependencies = (bool) $input->getOption('show-shadow-dependencies');
+        $process = $processBuilder->build('vendor/bin/composer-dependency-analyser');
+        $process->setEnv([
+            ComposerDependencyAnalyserConfig::ENV_SHOW_SHADOW_DEPENDENCIES => $showShadowDependencies ? '1' : '0',
+        ]);
+
+        return $process;
     }
 
     /**

tests/Config/ComposerDependencyAnalyserConfigTest.php

@@ -28,6 +28,8 @@
 use ShipMonk\ComposerDependencyAnalyser\Config\Configuration;
 use ShipMonk\ComposerDependencyAnalyser\Config\ErrorType;
 
+use function Safe\putenv;
+
 #[CoversClass(ComposerDependencyAnalyserConfig::class)]
 #[UsesClass(DevToolsPathResolver::class)]
 final class ComposerDependencyAnalyserConfigTest extends TestCase
@@ -43,6 +45,48 @@ public function configureWillReturnConfiguration(): void
         self::assertInstanceOf(Configuration::class, $configuration);
     }
 
+    /**
+     * @return void
+     */
+    #[Test]
+    public function configureWillIgnoreShadowDependenciesByDefault(): void
+    {
+        $originalValue = getenv(ComposerDependencyAnalyserConfig::ENV_SHOW_SHADOW_DEPENDENCIES);
+
+        try {
+            putenv(ComposerDependencyAnalyserConfig::ENV_SHOW_SHADOW_DEPENDENCIES);
+            $configuration = ComposerDependencyAnalyserConfig::configure();
+
+            self::assertTrue(
+                $configuration->getIgnoreList()
+                    ->shouldIgnoreError(ErrorType::SHADOW_DEPENDENCY, null, 'vendor/shadow-package')
+            );
+        } finally {
+            self::restoreShadowDependenciesEnvironment($originalValue);
+        }
+    }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function configureWillKeepShadowDependenciesVisibleWhenRequested(): void
+    {
+        $originalValue = getenv(ComposerDependencyAnalyserConfig::ENV_SHOW_SHADOW_DEPENDENCIES);
+
+        try {
+            putenv(ComposerDependencyAnalyserConfig::ENV_SHOW_SHADOW_DEPENDENCIES . '=1');
+            $configuration = ComposerDependencyAnalyserConfig::configure();
+
+            self::assertFalse(
+                $configuration->getIgnoreList()
+                    ->shouldIgnoreError(ErrorType::SHADOW_DEPENDENCY, null, 'vendor/shadow-package')
+            );
+        } finally {
+            self::restoreShadowDependenciesEnvironment($originalValue);
+        }
+    }
+
     /**
      * @return void
      */
@@ -102,4 +146,34 @@ public function applyPackagedRepositoryIgnoresWillReturnTheSameConfigurationInst
             ComposerDependencyAnalyserConfig::applyPackagedRepositoryIgnores($configuration)
         );
     }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function applyIgnoresShadowDependenciesWillReturnTheSameConfigurationInstance(): void
+    {
+        $configuration = new Configuration();
+
+        self::assertSame(
+            $configuration,
+            ComposerDependencyAnalyserConfig::applyIgnoresShadowDependencies($configuration)
+        );
+    }
+
+    /**
+     * @param false|string $value
+     *
+     * @return void
+     */
+    private static function restoreShadowDependenciesEnvironment(false|string $value): void
+    {
+        if (false === $value) {
+            putenv(ComposerDependencyAnalyserConfig::ENV_SHOW_SHADOW_DEPENDENCIES);
+
+            return;
+        }
+
+        putenv(ComposerDependencyAnalyserConfig::ENV_SHOW_SHADOW_DEPENDENCIES . '=' . $value);
+    }
 }

tests/Console/Command/DependenciesCommandTest.php

@@ -21,7 +21,9 @@
 
 use FastForward\DevTools\Console\Command\DependenciesCommand;
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
+use FastForward\DevTools\Config\ComposerDependencyAnalyserConfig;
 use FastForward\DevTools\Process\ProcessBuilder;
+use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Test;
@@ -79,6 +81,8 @@ protected function setUp(): void
             ->willReturn(false);
         $this->input->getOption('dump-usage')
             ->willReturn(null);
+        $this->input->getOption('show-shadow-dependencies')
+            ->willReturn(false);
         $this->input->getOption('json')
             ->willReturn(false);
         $this->input->getOption('pretty-json')
@@ -167,6 +171,30 @@ public function executeWillIgnoreJackFailuresWhenMaxOutdatedIsDisabled(): void
         self::assertSame(DependenciesCommand::SUCCESS, $this->executeCommand());
     }
 
+    /**
+     * @return void
+     */
+    #[Test]
+    public function composerDependencyAnalyserProcessWillHideShadowDependenciesByDefault(): void
+    {
+        $this->input->getOption('show-shadow-dependencies')
+            ->willReturn(false);
+
+        $this->assertComposerDependencyAnalyserEnvironment('0');
+    }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function composerDependencyAnalyserProcessCanReportShadowDependencies(): void
+    {
+        $this->input->getOption('show-shadow-dependencies')
+            ->willReturn(true);
+
+        $this->assertComposerDependencyAnalyserEnvironment('1');
+    }
+
     /**
      * @return int
      */
@@ -175,4 +203,36 @@ private function executeCommand(): int
         return (new ReflectionMethod($this->command, 'execute'))
             ->invoke($this->command, $this->input->reveal(), $this->output->reveal());
     }
+
+    /**
+     * @param string $expectedValue
+     *
+     * @return void
+     */
+    private function assertComposerDependencyAnalyserEnvironment(string $expectedValue): void
+    {
+        $processBuilder = $this->prophesize(ProcessBuilderInterface::class);
+        $configuredProcessBuilder = $this->prophesize(ProcessBuilderInterface::class);
+        $process = $this->prophesize(Process::class);
+        $command = new DependenciesCommand(
+            $processBuilder->reveal(),
+            $this->processQueue->reveal(),
+            $this->fileLocator->reveal(),
+            $this->logger->reveal(),
+        );
+
+        $processBuilder->withArgument('--config', '/app/composer-dependency-analyser.php')
+            ->willReturn($configuredProcessBuilder->reveal())
+            ->shouldBeCalledOnce();
+        $configuredProcessBuilder->build('vendor/bin/composer-dependency-analyser')
+            ->willReturn($process->reveal())
+            ->shouldBeCalledOnce();
+        $process->setEnv([
+            ComposerDependencyAnalyserConfig::ENV_SHOW_SHADOW_DEPENDENCIES => $expectedValue,
+        ])->willReturn($process->reveal())
+            ->shouldBeCalledOnce();
+
+        (new ReflectionMethod($command, 'getComposerDependencyAnalyserCommand'))
+            ->invoke($command, $this->input->reveal());
+    }
 }