automatic_updates_extensions/tests/src/Functional/UpdateErrorTest.php

@@ -7,7 +7,7 @@ namespace Drupal\Tests\automatic_updates_extensions\Functional;
 use Drupal\automatic_updates_test\EventSubscriber\TestSubscriber1;
 use Drupal\package_manager\Event\StatusCheckEvent;
 use Drupal\package_manager\ValidationResult;
-use Drupal\package_manager_bypass\Committer;
+use Drupal\package_manager_bypass\LoggingCommitter;
 use Drupal\package_manager_test_validation\EventSubscriber\TestSubscriber;
 
 /**
@@ -38,7 +38,7 @@ class UpdateErrorTest extends UpdaterFormTestBase {
     $this->checkForMetaRefresh();
     $this->assertUpdateStagedTimes(1);
     $assert_session->pageTextNotContains('The following dependencies will also be updated:');
-    Committer::setException(new \Exception('failed at committer'));
+    LoggingCommitter::setException(new \Exception('failed at committer'));
     $page->pressButton('Continue');
     $this->checkForMetaRefresh();
     $assert_session->pageTextContainsOnce('An error has occurred.');

package_manager/package_manager.api.php

@@ -50,6 +50,11 @@
  *
  * The stage dispatches the following events during its life cycle:
  *
+ * - \Drupal\package_manager\Event\CollectIgnoredPathsEvent
+ *   Dispatched before the stage directory is created and also before changes in
+ *   the stage directory are copied to the active directory. This event may be
+ *   dispatched multiple times during a stage's life cycle.
+ *
  * - \Drupal\package_manager\Event\PreCreateEvent
  *   Dispatched before the stage directory is created. At this point, the
  *   stage will have recorded which user or session owns it, so another stage
@@ -97,6 +102,17 @@
  *   has released its ownership. This event is dispatched only once during a
  *   stage's life cycle.
  *
+ *  There are some cases where there is no point for an event to trigger further
+ *  event subscribers, in which case the event propagation should be stopped.
+ *  For example, in a situation where Composer or Composer Stager cannot work
+ *  at all, or a security vulnerability is detected, the event propagation must
+ *  be stopped to prevent further event subscribers from breaking. For example,
+ *  Package Manager stops event propagation if:
+ * - The stage directory is a subdirectory of the active directory.
+ * - No composer.json file exists in active directory.
+ * - Package Manager has been deliberately disabled in the current environment.
+ *   See \Drupal\package_manager\Validator\EnvironmentSupportValidator
+ *
  * The public API of any stage consists of the following methods:
  *
  * - \Drupal\package_manager\Stage::create()
@@ -155,9 +171,13 @@
  *   irrelevant to Composer or Package Manager. Examples include settings.php
  *   and related files, public and private files, SQLite databases, and git
  *   repositories. Custom code can use
- *   \Drupal\package_manager\Event\PreCreateEvent::excludePath() to exclude a
- *   specific path from being copied from the active directory into the stage
- *   directory, or \Drupal\package_manager\Event\PreApplyEvent::excludePath() to
- *   exclude a specific path from being copied from the stage directory back
- *   into the active directory.
+ *   \Drupal\package_manager\Stage::getIgnoredPaths() which dispatches the
+ *   CollectIgnoredPathsEvent to collect ignored paths that are excluded from
+ *   being copied from the active directory into the stage directory, and also
+ *   from being copied from the stage directory back into the active directory.
+ *
+ * \Drupal\package_manager\Event\StatusCheckEvent
+ * Dispatched to check the status of the Drupal site and whether Package Manager
+ * can function properly. These checks can be performed anytime, so this event
+ * may be dispatched multiple times.
  */

package_manager/package_manager.module

@@ -33,7 +33,7 @@ function package_manager_help($route_name, RouteMatchInterface $route_match) {
       $output .= '<ul>';
       $output .= '  <li>' . t('It does not support Drupal multi-site installations.') . '</li>';
       $output .= '  <li>' . t('It does not support symlinks. If you have any, see <a href="#package-manager-faq-composer-not-found">What if it says I have symlinks in my codebase?</a>.') . '</li>';
-      $output .= '  <li>' . t('It only allows supported composer plugins. If you have any, see <a href="#package-manager-faq-unsupported-composer-plugin">What if it says I have unsupported composer plugins in my codebase?</a>.') . '</li>';
+      $output .= '  <li>' . t('It only allows supported Composer plugins. If you have any, see <a href="#package-manager-faq-unsupported-composer-plugin">What if it says I have unsupported Composer plugins in my codebase?</a>.') . '</li>';
       $output .= '  <li>' . t('It does not automatically perform version control operations, e.g., with Git. Site administrators are responsible for committing updates.') . '</li>';
       $output .= '  <li>' . t('It can only maintain one copy of the site at any given time. If a copy of the site already exists, another one cannot be created until the existing copy is destroyed.') . '</li>';
       $output .= '  <li>' . t('It associates the temporary copy of the site with the user or session that originally created it, and only that user or session can make changes to it.') . '</li>';
@@ -81,11 +81,22 @@ function package_manager_help($route_name, RouteMatchInterface $route_match) {
       $output .= '<p>' . t('The new configuration will take effect on the next Composer install or update event. Do this to apply it immediately:') . '</p>';
       $output .= '<pre><code>composer install</code></pre>';
 
-      $output .= '<h4 id="package-manager-faq-unsupported-composer-plugin">' . t('What if it says I have unsupported composer plugins in my codebase?') . '</h4>';
-      $output .= '<p>' . t('A fresh Drupal installation only uses supported composer plugins, but some modules or themes may depend on additional composer plugins. Please <a href=":new-issue">create a new issue</a> when you encounter this.', [
+      $output .= '<h4 id="package-manager-faq-unsupported-composer-plugin">' . t('What if it says I have unsupported Composer plugins in my codebase?') . '</h4>';
+      $output .= '<p>' . t('A fresh Drupal installation only uses supported Composer plugins, but some modules or themes may depend on additional Composer plugins. Please <a href=":new-issue">create a new issue</a> when you encounter this.', [
         ':new-issue' => 'https://www.drupal.org/node/add/project-issue/automatic_updates',
       ]) . '</p>';
-      $output .= '<p>' . t('It is possible to <em>trust</em> additional composer plugins, but this requires significant expertise: understanding the code of that composer plugin, what the effects on the file system are and how it affects the Package Manager module. Some composer plugins could result in a broken site!') . '</p>';
+      $output .= '<p>' . t('It is possible to <em>trust</em> additional Composer plugins, but this requires significant expertise: understanding the code of that Composer plugin, what the effects on the file system are and how it affects the Package Manager module. Some Composer plugins could result in a broken site!') . '</p>';
+
+      $output .= '<h4 id="package-manager-faq-composer-patches-installed-or-removed">' . t('What if it says <code>cweagans/composer-patches</code> cannot be installed/removed?') . '</h4>';
+      $output .= '<p>' . t('Installation or removal of <code>cweagans/composer-patches</code> via Package Manager is not support it. You can install or remove it manually by running Composer commands in your site root.') . '</p>';
+      $output .= '<p>' . t('To install it:') . '</p>';
+      $output .= '<pre><code>composer require cweagans/composer-patches</code></pre>';
+      $output .= '<p>' . t('To remove it:') . '</p>';
+      $output .= '<pre><code>composer remove cweagans/composer-patches</code></pre>';
+
+      $output .= '<h4 id="package-manager-faq-composer-patches-not-a-root-dependency">' . t('What if it says <code>cweagans/composer-patches</code> must be a root dependency?') . '</h4>';
+      $output .= '<p>' . t('If <code>cweagans/composer-patches</code> is installed, it must be defined as a dependency of the main project (i.e., it must be listed in the <code>require</code> or <code>require-dev</code> section of <code>composer.json</code>). You can run the following command in your site root to add it as a dependency of the main project:') . '</p>';
+      $output .= "<pre><code>composer require cweagans/composer-patches</code></pre>";
 
       $output .= '<h5>' . t('Custom code') . '</h5>';
       $output .= '<p>' . t('Symlinks are seldom truly necessary and should be avoided in your own code. No solution currently exists to get around them--they must be removed in order to use Automatic Updates.') . '</p>';

package_manager/package_manager.services.yml

@@ -197,6 +197,12 @@ services:
       - '@file_system'
     tags:
       - { name: event_subscriber }
+  package_manager.unknown_path_excluder:
+    class: Drupal\package_manager\PathExcluder\UnknownPathExcluder
+    arguments:
+      - '@package_manager.path_locator'
+    tags:
+      - { name: event_subscriber }
   package_manager.site_configuration_excluder:
     class: Drupal\package_manager\PathExcluder\SiteConfigurationExcluder
     arguments:
@@ -234,6 +240,8 @@ services:
       - { name: event_subscriber }
   package_manager.validator.patches:
     class: Drupal\package_manager\Validator\ComposerPatchesValidator
+    arguments:
+      - '@module_handler'
     tags:
       - { name: event_subscriber }
   package_manager.validator.supported_releases:

package_manager/src/PathExcluder/UnknownPathExcluder.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager\PathExcluder;
+
+use Drupal\package_manager\Event\CollectIgnoredPathsEvent;
+use Drupal\package_manager\PathLocator;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+/**
+ * Excludes unknown paths from stage operations.
+ *
+ * Any paths in the root directory of the project that are NOT one of the
+ * following are considered unknown paths:
+ * 1. The vendor directory
+ * 2. The webroot
+ * 3. composer.json
+ * 4. composer.lock
+ * 5. Scaffold files as determined by the drupal/core-composer-scaffold plugin
+ * If web root and project root are same then nothing is excluded.
+ *
+ * @internal
+ *   This is an internal part of Package Manager and may be changed or removed
+ *   at any time without warning. External code should not interact with this
+ *   class.
+ */
+final class UnknownPathExcluder implements EventSubscriberInterface {
+
+  use PathExclusionsTrait;
+
+  /**
+   * Constructs a UnknownPathExcluder object.
+   *
+   * @param \Drupal\package_manager\PathLocator $path_locator
+   *   The path locator service.
+   */
+  public function __construct(PathLocator $path_locator) {
+    $this->pathLocator = $path_locator;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function getSubscribedEvents(): array {
+    return [
+      CollectIgnoredPathsEvent::class => 'excludeUnknownPaths',
+    ];
+  }
+
+  /**
+   * Excludes unknown paths from stage operations.
+   *
+   * @param \Drupal\package_manager\Event\CollectIgnoredPathsEvent $event
+   *   The event object.
+   */
+  public function excludeUnknownPaths(CollectIgnoredPathsEvent $event): void {
+    $project_root = $this->pathLocator->getProjectRoot();
+    $web_root = $project_root . DIRECTORY_SEPARATOR . $this->pathLocator->getWebRoot();
+    if (realpath($web_root) === $project_root) {
+      return;
+    }
+    $vendor_dir = $this->pathLocator->getVendorDirectory();
+    // @todo Refactor in https://www.drupal.org/project/automatic_updates/issues/3334994.
+    $core_packages = $event->getStage()->getActiveComposer()->getCorePackages();
+    $scaffold_files_paths = $this->getScaffoldFiles($core_packages);
+    $paths_in_project_root = glob("$project_root/*");
+    $paths = [];
+    $known_paths = array_merge([$vendor_dir, $web_root, "$project_root/composer.json", "$project_root/composer.lock"], $scaffold_files_paths);
+    foreach ($paths_in_project_root as $path_in_project_root) {
+      if (!in_array($path_in_project_root, $known_paths, TRUE)) {
+        $paths[] = $path_in_project_root;
+      }
+    }
+    $this->excludeInProjectRoot($event, $paths);
+  }
+
+  /**
+   * Gets the path of scaffold files, for example 'index.php' and 'robots.txt'.
+   *
+   * @param string[] $core_packages
+   *   The installed core packages.
+   *
+   * @return array
+   *   The array of scaffold file paths.
+   */
+  private function getScaffoldFiles(array $core_packages): array {
+    $scaffold_file_paths = [];
+    /** @var \Composer\Package\PackageInterface $package */
+    foreach ($core_packages as $package) {
+      $core_composer_extra = $package->getExtra();
+      if (array_key_exists('drupal-scaffold', $core_composer_extra)) {
+        $scaffold_file_paths = array_merge($scaffold_file_paths, array_keys($core_composer_extra['drupal-scaffold']['file-mapping']));
+      }
+    }
+    return $scaffold_file_paths;
+  }
+
+}

package_manager/src/Validator/ComposerExecutableValidator.php

@@ -105,7 +105,11 @@ class ComposerExecutableValidator implements EventSubscriberInterface {
       $this->composerIsAvailable->assertIsFulfilled($active_dir, $stage_dir);
     }
     catch (PreconditionException $e) {
-      $event->addError([$e->getMessage()]);
+      if (!$this->moduleHandler->moduleExists('help')) {
+        $event->addErrorFromThrowable($e);
+        return;
+      }
+      $this->setError($e->getMessage(), $event);
       return;
     }
 
@@ -113,6 +117,10 @@ class ComposerExecutableValidator implements EventSubscriberInterface {
       $output = $this->runCommand();
     }
     catch (ExceptionInterface $e) {
+      if (!$this->moduleHandler->moduleExists('help')) {
+        $event->addErrorFromThrowable($e);
+        return;
+      }
       $this->setError($e->getMessage(), $event);
       return;
     }

package_manager/src/Validator/ComposerPatchesValidator.php

@@ -4,7 +4,11 @@ declare(strict_types = 1);
 
 namespace Drupal\package_manager\Validator;
 
+use Drupal\Core\Extension\ModuleHandlerInterface;
 use Drupal\Core\StringTranslation\StringTranslationTrait;
+use Drupal\Core\StringTranslation\TranslatableMarkup;
+use Drupal\Core\Url;
+use Drupal\package_manager\ComposerUtility;
 use Drupal\package_manager\Event\PreApplyEvent;
 use Drupal\package_manager\Event\PreCreateEvent;
 use Drupal\package_manager\Event\PreOperationStageEvent;
@@ -13,30 +17,152 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 /**
  * Validates the configuration of the cweagans/composer-patches plugin.
+ *
+ * To ensure that applied patches remain consistent between the active and
+ * stage directories, the following rules are enforced if the patcher is
+ * installed:
+ * - It must be installed in both places, or in neither of them. It can't, for
+ *   example, be installed in the active directory but not the stage directory
+ *   (or vice-versa).
+ * - It must be one of the project's direct runtime or dev dependencies.
+ * - It cannot be installed or removed by Package Manager. In other words, it
+ *   must be added to the project at the command line by someone technical
+ *   enough to install and configure it properly.
+ *
+ * @internal
+ *   This is an internal part of Package Manager and may be changed or removed
+ *   at any time without warning. External code should not interact with this
+ *   class.
  */
-class ComposerPatchesValidator implements EventSubscriberInterface {
+final class ComposerPatchesValidator implements EventSubscriberInterface {
 
   use StringTranslationTrait;
 
   /**
-   * {@inheritdoc}
+   * The name of the plugin being analyzed.
+   *
+   * @var string
+   */
+  private const PLUGIN_NAME = 'cweagans/composer-patches';
+
+  /**
+   * The module handler service.
+   *
+   * @var \Drupal\Core\Extension\ModuleHandlerInterface
+   */
+  private ModuleHandlerInterface $moduleHandler;
+
+  /**
+   * Constructs a ComposerPatchesValidator object.
+   *
+   * @param \Drupal\Core\Extension\ModuleHandlerInterface $module_handler
+   *   The module handler service.
+   */
+  public function __construct(ModuleHandlerInterface $module_handler) {
+    $this->moduleHandler = $module_handler;
+  }
+
+  /**
+   * Validates the status of the patcher plugin.
+   *
+   * @param \Drupal\package_manager\Event\PreOperationStageEvent $event
+   *   The event object.
    */
-  public function validateStagePreOperation(PreOperationStageEvent $event): void {
+  public function validatePatcher(PreOperationStageEvent $event): void {
+    $messages = [];
+
     $stage = $event->getStage();
-    $composer = $stage->getActiveComposer();
-
-    if (array_key_exists('cweagans/composer-patches', $composer->getInstalledPackages())) {
-      $composer = $composer->getComposer();
-
-      $extra = $composer->getPackage()->getExtra();
-      if (empty($extra['composer-exit-on-patch-failure'])) {
-        $event->addError([
-          $this->t('The <code>cweagans/composer-patches</code> plugin is installed, but the <code>composer-exit-on-patch-failure</code> key is not set to <code>true</code> in the <code>extra</code> section of @file.', [
-            '@file' => $composer->getConfig()->getConfigSource()->getName(),
-          ]),
-        ]);
+    [$plugin_installed_in_active, $is_active_root_requirement, $active_configuration_ok] = $this->computePatcherStatus($stage->getActiveComposer());
+    try {
+      [$plugin_installed_in_stage, $is_stage_root_requirement, $stage_configuration_ok] = $this->computePatcherStatus($stage->getStageComposer());
+      $has_staged_update = TRUE;
+    }
+    catch (\LogicException $e) {
+      // No staged update exists.
+      $has_staged_update = FALSE;
+    }
+
+    // If there's a staged update and the patcher has been installed or removed
+    // in the stage directory, that's a problem.
+    if ($has_staged_update && $plugin_installed_in_active !== $plugin_installed_in_stage) {
+      if ($plugin_installed_in_stage) {
+        $message = $this->t('It cannot be installed by Package Manager.');
+      }
+      else {
+        $message = $this->t('It cannot be removed by Package Manager.');
       }
+      $messages[] = $this->createErrorMessage($message, 'package-manager-faq-composer-patches-installed-or-removed');
+    }
+
+    // If the patcher is not listed in the runtime or dev dependencies, that's
+    // an error as well.
+    if (($plugin_installed_in_active && !$is_active_root_requirement) || ($has_staged_update && $plugin_installed_in_stage && !$is_stage_root_requirement)) {
+      $messages[] = $this->createErrorMessage($this->t('It must be a root dependency.'), 'package-manager-faq-composer-patches-not-a-root-dependency');
     }
+
+    // If the plugin is misconfigured in either the active or stage directories,
+    // flag an error.
+    if (($plugin_installed_in_active && !$active_configuration_ok) || ($has_staged_update && $plugin_installed_in_stage && !$stage_configuration_ok)) {
+      $messages[] = $this->t('The <code>composer-exit-on-patch-failure</code> key is not set to <code>true</code> in the <code>extra</code> section of <code>composer.json</code>.');
+    }
+
+    if ($messages) {
+      $summary = $this->t("Problems detected related to the Composer plugin <code>@plugin</code>.", [
+        '@plugin' => static::PLUGIN_NAME,
+      ]);
+      $event->addError($messages, $summary);
+    }
+  }
+
+  /**
+   * Appends a link to online help to an error message.
+   *
+   * @param \Drupal\Core\StringTranslation\TranslatableMarkup $message
+   *   The error message.
+   * @param string $fragment
+   *   The fragment of the online help to link to.
+   *
+   * @return \Drupal\Core\StringTranslation\TranslatableMarkup
+   *   The final, translated error message.
+   */
+  private function createErrorMessage(TranslatableMarkup $message, string $fragment): TranslatableMarkup {
+    if ($this->moduleHandler->moduleExists('help')) {
+      $url = Url::fromRoute('help.page', ['name' => 'package_manager'])
+        ->setOption('fragment', $fragment)
+        ->toString();
+
+      return $this->t('@message See <a href=":url">the help page</a> for information on how to resolve the problem.', [
+        '@message' => $message,
+        ':url' => $url,
+      ]);
+    }
+    return $message;
+  }
+
+  /**
+   * Computes the status of the patcher plugin in a particular directory.
+   *
+   * @param \Drupal\package_manager\ComposerUtility $composer
+   *   A Composer utility for a specific directory.
+   *
+   * @return bool[]
+   *   An indexed array containing three booleans, in order:
+   *   - Whether the patcher plugin is installed.
+   *   - Whether the patcher plugin is a root requirement in composer.json (in
+   *     either the runtime or dev dependencies).
+   *   - Whether the `composer-exit-on-patch-failure` flag is set in the `extra`
+   *     section of composer.json.
+   */
+  private function computePatcherStatus(ComposerUtility $composer): array {
+    $is_installed = array_key_exists(static::PLUGIN_NAME, $composer->getInstalledPackages());
+
+    $root_package = $composer->getComposer()->getPackage();
+    $is_root_requirement = array_key_exists(static::PLUGIN_NAME, $root_package->getRequires()) || array_key_exists(static::PLUGIN_NAME, $root_package->getDevRequires());
+
+    $extra = $root_package->getExtra();
+    $exit_on_failure = !empty($extra['composer-exit-on-patch-failure']);
+
+    return [$is_installed, $is_root_requirement, $exit_on_failure];
   }
 
   /**
@@ -44,9 +170,9 @@ class ComposerPatchesValidator implements EventSubscriberInterface {
    */
   public static function getSubscribedEvents(): array {
     return [
-      PreCreateEvent::class => 'validateStagePreOperation',
-      PreApplyEvent::class => 'validateStagePreOperation',
-      StatusCheckEvent::class => 'validateStagePreOperation',
+      PreCreateEvent::class => 'validatePatcher',
+      PreApplyEvent::class => 'validatePatcher',
+      StatusCheckEvent::class => 'validatePatcher',
     ];
   }
 

package_manager/tests/fixtures/fake_site/composer.json

@@ -45,6 +45,14 @@
       "options": {
         "symlink": false
       }
+    },
+    "cweagans/composer-patches": {
+      "type": "path",
+      "version": "24.12.1999",
+      "url": "../path_repos/cweagans--composer-patches",
+      "options": {
+        "symlink": false
+      }
     }
   },
   "minimum-stability": "stable",

package_manager/tests/fixtures/path_repos/cweagans--composer-patches/composer.json

+{
+    "name": "cweagans/composer-patches",
+    "type": "composer-plugin",
+    "extra": {
+        "class": "\\cweagans\\Fake\\ComposerPatches"
+    },
+    "require": {
+        "composer-plugin-api": "^1.0 || ^2.0"
+    },
+    "autoload": {
+        "psr-4": {"cweagans\\Fake\\": "src"}
+    }
+}

package_manager/tests/fixtures/path_repos/cweagans--composer-patches/src/ComposerPatches.php

+<?php
+
+namespace cweagans\Fake;
+
+use Composer\Composer;
+use Composer\IO\IOInterface;
+use Composer\Plugin\PluginInterface;
+
+/**
+ * Dummy composer plugin implementation.
+ */
+class ComposerPatches implements PluginInterface {
+
+  /**
+   * {@inheritdoc}
+   */
+  public function activate(Composer $composer, IOInterface $io) {}
+
+  /**
+   * {@inheritdoc}
+   */
+  public function deactivate(Composer $composer, IOInterface $io) {}
+
+  /**
+   * {@inheritdoc}
+   */
+  public function uninstall(Composer $composer, IOInterface $io) {}
+
+}

package_manager/tests/modules/package_manager_bypass/package_manager_bypass.info.yml

 name: 'Package Manager Bypass'
-description: 'Mocks Package Manager services for functional testing.'
+description: 'Mocks PathLocator service, decorates Beginner & Committer services (adds logging) and by default bypasses the Stager service (to minimize I/O during tests).'
 type: module
 package: Testing
 dependencies:

package_manager/tests/modules/package_manager_bypass/package_manager_bypass.services.yml

 services:
   package_manager_bypass.beginner:
-    class: Drupal\package_manager_bypass\Beginner
+    class: Drupal\package_manager_bypass\LoggingBeginner
     arguments: ['@state', '@package_manager_bypass.beginner.inner' ]
     decorates: 'package_manager.beginner'
   package_manager_bypass.committer:
-    class: Drupal\package_manager_bypass\Committer
+    class: Drupal\package_manager_bypass\LoggingCommitter
     arguments: [ '@state', '@package_manager_bypass.committer.inner' ]
     decorates: 'package_manager.committer'

package_manager/tests/modules/package_manager_bypass/src/Beginner.php → package_manager/tests/modules/package_manager_bypass/src/LoggingBeginner.php

@@ -12,9 +12,13 @@ use PhpTuf\ComposerStager\Domain\Value\Path\PathInterface;
 use PhpTuf\ComposerStager\Domain\Value\PathList\PathListInterface;
 
 /**
- * Defines a service that decorates the Composer Stager beginner service.
+ * A composer-stager Beginner decorator that adds logging.
+ *
+ * @internal
  */
-class Beginner extends BypassedStagerServiceBase implements BeginnerInterface {
+final class LoggingBeginner implements BeginnerInterface {
+
+  use LoggingDecoratorTrait;
 
   /**
    * The decorated service.

package_manager/tests/modules/package_manager_bypass/src/Committer.php → package_manager/tests/modules/package_manager_bypass/src/LoggingCommitter.php

@@ -12,9 +12,13 @@ use PhpTuf\ComposerStager\Domain\Value\Path\PathInterface;
 use PhpTuf\ComposerStager\Domain\Value\PathList\PathListInterface;
 
 /**
- * Defines a service that decorates the Composer Stager committer service.
+ * A composer-stager Committer decorator that adds logging.
+ *
+ * @internal
  */
-class Committer extends BypassedStagerServiceBase implements CommitterInterface {
+final class LoggingCommitter implements CommitterInterface {
+
+  use LoggingDecoratorTrait;
 
   /**
    * The decorated service.

package_manager/tests/modules/package_manager_bypass/src/BypassedStagerServiceBase.php → package_manager/tests/modules/package_manager_bypass/src/LoggingDecoratorTrait.php

@@ -10,8 +10,10 @@ namespace Drupal\package_manager_bypass;
  * This can be used by functional tests to ensure that the bypassed Composer
  * Stager services were called as expected. Kernel and unit tests should use
  * regular mocks instead.
+ *
+ * @internal
  */
-abstract class BypassedStagerServiceBase {
+trait LoggingDecoratorTrait {
 
   /**
    * The state service.

package_manager/tests/modules/package_manager_bypass/src/PathLocator.php → package_manager/tests/modules/package_manager_bypass/src/MockPathLocator.php

@@ -9,9 +9,11 @@ use Drupal\package_manager\PathLocator as BasePathLocator;
 use Drupal\package_manager\Path;
 
 /**
- * Overrides the path locator to return pre-set values for testing purposes.
+ * Mock path locator: allows specifying paths instead of discovering paths.
+ *
+ * @internal
  */
-class PathLocator extends BasePathLocator {
+final class MockPathLocator extends BasePathLocator {
 
   /**
    * The state service.

package_manager/tests/modules/package_manager_bypass/src/Stager.php → package_manager/tests/modules/package_manager_bypass/src/NoOpStager.php

@@ -12,9 +12,22 @@ use PhpTuf\ComposerStager\Domain\Service\ProcessRunner\ProcessRunnerInterface;
 use PhpTuf\ComposerStager\Domain\Value\Path\PathInterface;
 
 /**
- * Defines an update stager which doesn't actually do anything.
+ * A composer-stager Stager implementation that does nothing, except logging.
+ *
+ * By default, it will modify composer.lock in the stage directory, to fool the
+ * \Drupal\package_manager\Validator\LockFileValidator into thinking that there
+ * are pending composer operations.
+ *
+ * Opt out of this by calling @code setLockFileShouldChange(FALSE) @endcode.
+ *
+ * @see ::setLockFileShouldChange()
+ * @see \Drupal\package_manager\Validator\LockFileValidator
+ *
+ * @internal
  */
-class Stager extends BypassedStagerServiceBase implements StagerInterface {
+final class NoOpStager implements StagerInterface {
+
+  use LoggingDecoratorTrait;
 
   /**
    * Constructs a Stager object.

package_manager/tests/modules/package_manager_bypass/src/PackageManagerBypassServiceProvider.php

@@ -11,8 +11,10 @@ use Symfony\Component\DependencyInjection\Reference;
 
 /**
  * Defines services to bypass Package Manager's core functionality.
+ *
+ * @internal
  */
-class PackageManagerBypassServiceProvider extends ServiceProviderBase {
+final class PackageManagerBypassServiceProvider extends ServiceProviderBase {
 
   /**
    * {@inheritdoc}
@@ -21,12 +23,15 @@ class PackageManagerBypassServiceProvider extends ServiceProviderBase {
     parent::alter($container);
 
     $state = new Reference('state');
+    // By default, \Drupal\package_manager_bypass\NoOpStager is applied, except
+    // when a test opts out by setting this setting to FALSE.
+    // @see \Drupal\package_manager_bypass\NoOpStager::setLockFileShouldChange()
     if (Settings::get('package_manager_bypass_composer_stager', TRUE)) {
-      $container->getDefinition('package_manager.stager')->setClass(Stager::class)->setArguments([$state]);
+      $container->getDefinition('package_manager.stager')->setClass(NoOpStager::class)->setArguments([$state]);
     }
 
     $definition = $container->getDefinition('package_manager.path_locator')
-      ->setClass(PathLocator::class);
+      ->setClass(MockPathLocator::class);
     $arguments = $definition->getArguments();
     array_unshift($arguments, $state);
     $definition->setArguments($arguments);

package_manager/tests/src/Kernel/ComposerPatchesValidatorTest.php

@@ -4,10 +4,12 @@ declare(strict_types = 1);
 
 namespace Drupal\Tests\package_manager\Kernel;
 
+use Drupal\Core\Url;
 use Drupal\fixture_manipulator\ActiveFixtureManipulator;
-use Drupal\package_manager\Event\PreApplyEvent;
 use Drupal\package_manager\Event\PreCreateEvent;
+use Drupal\package_manager\Event\StatusCheckEvent;
 use Drupal\package_manager\ValidationResult;
+use Symfony\Component\Process\Process;
 
 /**
  * @covers \Drupal\package_manager\Validator\ComposerPatchesValidator
@@ -16,63 +18,227 @@ use Drupal\package_manager\ValidationResult;
  */
 class ComposerPatchesValidatorTest extends PackageManagerKernelTestBase {
 
+  /**
+   * Data provider for testErrorDuringPreCreate().
+   *
+   * @return mixed[][]
+   *   The test cases.
+   */
+  public function providerPatcherConfiguration(): array {
+    return [
+      'exit-on-patch-failure missing' => [
+        FALSE,
+        [
+          ValidationResult::createError([
+            t('The <code>composer-exit-on-patch-failure</code> key is not set to <code>true</code> in the <code>extra</code> section of <code>composer.json</code>.'),
+          ], t('Problems detected related to the Composer plugin <code>cweagans/composer-patches</code>.')),
+        ],
+      ],
+      'exit-on-patch-failure set' => [
+        TRUE,
+        [],
+      ],
+    ];
+  }
+
   /**
    * Tests that the patcher configuration is validated during pre-create.
+   *
+   * @param bool $extra_key_set
+   *   Whether to set key in extra part of root package.
+   * @param \Drupal\package_manager\ValidationResult[] $expected_results
+   *   The expected validation results.
+   *
+   *  @dataProvider providerPatcherConfiguration()
    */
-  public function testError(): void {
-    // Simulate an active directory where the patcher is installed, but there's
-    // no composer-exit-on-patch-failure flag.
-    $dir = $this->container->get('package_manager.path_locator')
-      ->getProjectRoot();
-
-    $this->installPatcherInActive($dir);
-
-    // Because ComposerUtility reads composer.json and passes it to the Composer
-    // factory as an array, Composer will assume that the configuration is
-    // coming from a config.json file, even if one doesn't exist.
-    $error = ValidationResult::createError([
-      t('The <code>cweagans/composer-patches</code> plugin is installed, but the <code>composer-exit-on-patch-failure</code> key is not set to <code>true</code> in the <code>extra</code> section of @dir/composer.json.', [
-        '@dir' => realpath($dir),
-      ]),
-    ]);
-    $this->assertStatusCheckResults([$error]);
-    $this->assertResults([$error], PreCreateEvent::class);
+  public function testPatcherConfiguration(bool $extra_key_set, array $expected_results): void {
+    $this->addPatcherToAllowedPlugins();
+    $this->setRootRequires();
+    if ($extra_key_set) {
+      $this->setRootExtra();
+    }
+    $this->assertStatusCheckResults($expected_results);
+    $this->assertResults($expected_results, PreCreateEvent::class);
   }
 
   /**
-   * Tests that the patcher configuration is validated during pre-apply.
+   * Data provider for testErrorDuringPreApply() and testHelpLink().
+   *
+   * @return mixed[][]
+   *   The test cases.
    */
-  public function testErrorDuringPreApply(): void {
-    // Simulate an active directory where the patcher is installed, but there's
-    // no composer-exit-on-patch-failure flag.
-    $dir = $this->container->get('package_manager.path_locator')
-      ->getProjectRoot();
-
-    $this->addEventTestListener(function () use ($dir): void {
-      $this->installPatcherInActive($dir);
-    });
-    // Because ComposerUtility reads composer.json and passes it to the Composer
-    // factory as an array, Composer will assume that the configuration is
-    // coming from a config.json file, even if one doesn't exist.
-    $error = ValidationResult::createError([
-      "The <code>cweagans/composer-patches</code> plugin is installed, but the <code>composer-exit-on-patch-failure</code> key is not set to <code>true</code> in the <code>extra</code> section of $dir/composer.json.",
-    ]);
-    $this->assertResults([$error], PreApplyEvent::class);
+  public function providerErrorDuringPreApply(): array {
+    $summary = t('Problems detected related to the Composer plugin <code>cweagans/composer-patches</code>.');
+
+    return [
+      'composer-patches present in stage, but not present in active' => [
+        FALSE,
+        TRUE,
+        [
+          ValidationResult::createError([
+            t('It cannot be installed by Package Manager.'),
+            t('It must be a root dependency.'),
+            t('The <code>composer-exit-on-patch-failure</code> key is not set to <code>true</code> in the <code>extra</code> section of <code>composer.json</code>.'),
+          ], $summary),
+        ],
+        [
+          'package-manager-faq-composer-patches-installed-or-removed',
+          'package-manager-faq-composer-patches-not-a-root-dependency',
+          NULL,
+        ],
+      ],
+      'composer-patches removed in stage, but present in active' => [
+        TRUE,
+        FALSE,
+        [
+          ValidationResult::createError([
+            t('It cannot be removed by Package Manager.'),
+          ], $summary),
+        ],
+        [
+          'package-manager-faq-composer-patches-installed-or-removed',
+        ],
+      ],
+      'composer-patches present in stage and active' => [
+        TRUE,
+        TRUE,
+        [],
+        [],
+      ],
+      'composer-patches not present in stage and active' => [
+        FALSE,
+        FALSE,
+        [],
+        [],
+      ],
+    ];
   }
 
   /**
-   * Simulates that the patcher is installed in the active directory.
+   * Tests the patcher's presence and configuration are validated on pre-apply.
    *
-   * @param string $dir
-   *   The active directory.
+   * @param bool $in_active
+   *   Whether patcher is installed in active.
+   * @param bool $in_stage
+   *   Whether patcher is installed in stage.
+   * @param \Drupal\package_manager\ValidationResult[] $expected_results
+   *   The expected validation results.
+   *
+   * @dataProvider providerErrorDuringPreApply
    */
-  private function installPatcherInActive(string $dir): void {
+  public function testErrorDuringPreApply(bool $in_active, bool $in_stage, array $expected_results): void {
+    if ($in_active) {
+      // Add patcher as a root dependency and set
+      // `composer-exit-on-patch-failure` to true.
+      $this->addPatcherToAllowedPlugins();
+      $this->setRootRequires();
+      $this->setRootExtra();
+    }
+    if ($in_stage && !$in_active) {
+      // Simulate a stage directory where the patcher is installed.
+      $this->getStageFixtureManipulator()
+        ->addPackage([
+          'name' => 'cweagans/composer-patches',
+          'version' => '24.12.1999',
+          'type' => 'composer-plugin',
+        ]);
+    }
+
+    if (!$in_stage && $in_active) {
+      $this->getStageFixtureManipulator()
+        ->removePackage('cweagans/composer-patches');
+    }
+
+    $stage = $this->createStage();
+    $stage->create();
+    $stage_dir = $stage->getStageDirectory();
+    $stage->require(['drupal/core:9.8.1']);
+    $event = new StatusCheckEvent($stage, []);
+    $this->container->get('event_dispatcher')->dispatch($event);
+    $this->assertValidationResultsEqual($expected_results, $event->getResults(), NULL, $stage_dir);
+
+    try {
+      $stage->apply();
+      // If we didn't get an exception, ensure we didn't expect any errors
+      $this->assertSame([], $expected_results);
+    }
+    catch (TestStageValidationException $e) {
+      $this->assertNotEmpty($expected_results);
+      $this->assertValidationResultsEqual($expected_results, $e->getResults(), NULL, $stage_dir);
+    }
+  }
+
+  /**
+   * Tests that validation errors can carry links to help.
+   *
+   * @param bool $in_active
+   *   Whether patcher is installed in active.
+   * @param bool $in_stage
+   *   Whether patcher is installed in stage.
+   * @param \Drupal\package_manager\ValidationResult[] $expected_results
+   *   The expected validation results.
+   * @param string[] $help_page_sections
+   *   An associative array of fragments (anchors) in the online help. The keys
+   *   should be the numeric indices of the validation result messages which
+   *   should link to those fragments.
+   *
+   * @dataProvider providerErrorDuringPreApply
+   */
+  public function testErrorDuringPreApplyWithHelp(bool $in_active, bool $in_stage, array $expected_results, array $help_page_sections): void {
+    $this->enableModules(['help']);
+
+    foreach ($expected_results as $result_index => $result) {
+      $messages = $result->getMessages();
+
+      foreach ($messages as $message_index => $message) {
+        if ($help_page_sections[$message_index]) {
+          // Get the link to the online documentation for the error message.
+          $url = Url::fromRoute('help.page', ['name' => 'package_manager'])
+            ->setOption('fragment', $help_page_sections[$message_index])
+            ->toString();
+          // Reformat the provided results so that they all have the link to the
+          // online documentation appended to them.
+          $messages[$message_index] = $message . ' See <a href="' . $url . '">the help page</a> for information on how to resolve the problem.';
+        }
+      }
+      $expected_results[$result_index] = ValidationResult::createError($messages, $result->getSummary());
+    }
+    $this->testErrorDuringPreApply($in_active, $in_stage, $expected_results);
+  }
+
+  /**
+   * Add the installed patcher to allowed plugins.
+   */
+  private function addPatcherToAllowedPlugins(): void {
     (new ActiveFixtureManipulator())
-      ->addPackage([
-        'name' => 'cweagans/composer-patches',
-        'version' => '1.0.0',
-        'type' => 'composer-plugin',
-      ])->commitChanges();
+      ->addConfig([
+        'allow-plugins' => [
+          'cweagans/composer-patches' => TRUE,
+        ],
+      ])
+      ->commitChanges();
+  }
+
+  /**
+   * Sets the cweagans/composer-patches as required package for root package.
+   */
+  private function setRootRequires(): void {
+    $process = new Process(
+      ['composer', 'require', "cweagans/composer-patches:@dev"],
+      $this->container->get('package_manager.path_locator')->getProjectRoot()
+    );
+    $process->mustRun();
+  }
+
+  /**
+   * Sets the composer-exit-on-patch-failure key in extra part of root package.
+   */
+  private function setRootExtra(): void {
+    $process = new Process(
+      ['composer', 'config', 'extra.composer-exit-on-patch-failure', 'true'],
+      $this->container->get('package_manager.path_locator')->getProjectRoot()
+    );
+    $process->mustRun();
   }
 
 }

package_manager/tests/src/Kernel/LockFileValidatorTest.php

@@ -9,7 +9,7 @@ use Drupal\package_manager\Event\PreCreateEvent;
 use Drupal\package_manager\Event\PreRequireEvent;
 use Drupal\package_manager\Validator\LockFileValidator;
 use Drupal\package_manager\ValidationResult;
-use Drupal\package_manager_bypass\Stager;
+use Drupal\package_manager_bypass\NoOpStager;
 
 /**
  * @coversDefaultClass \Drupal\package_manager\Validator\LockFileValidator
@@ -137,7 +137,7 @@ class LockFileValidatorTest extends PackageManagerKernelTestBase {
    */
   public function testApplyWithNoChange(): void {
     // Leave the staged lock file alone.
-    Stager::setLockFileShouldChange(FALSE);
+    NoOpStager::setLockFileShouldChange(FALSE);
 
     $result = ValidationResult::createError([
       t('There are no pending Composer operations.'),