Retain 'contrib' / 'custom' paths for site-wide Drush extensions (#3687)

Author: greg-1-anderson

.gitignore

@@ -11,6 +11,7 @@ api
 .idea/
 # https://github.com/drush-ops/drush/issues/2688
 composer.lock
-/sut/
+sut/*
+!sut/drush
 /sandbox/
 .env

composer.json

@@ -34,7 +34,7 @@
     "ext-dom": "*",
     "chi-teck/drupal-code-generator": "^1.26.1",
     "composer/semver": "^1.4",
-    "consolidation/annotated-command": "^2.8.1",
+    "consolidation/annotated-command": "^2.9.1",
     "consolidation/config": "^1.1.0",
     "consolidation/output-formatters": "^3.1.12",
     "consolidation/robo": "^1.1.5",

docs/commands.md

@@ -47,31 +47,60 @@ Altering Drush Command Info
 
 Drush command info (annotations) can be altered from other modules. This is done by creating and registering 'command info alterers'. Alterers are class services that are able to intercept and manipulate an existing command annotation.
 
-In order to alter an existing command info, follow the next steps:
+In order to alter an existing command info, follow the steps below:
 
 1. In the module that wants to alter a command info, add a service class that implements the `\Consolidation\AnnotatedCommand\CommandInfoAltererInterface`.
 1. In the module `drush.services.yml` declare a service pointing to this class and tag the service with the `drush.command_info_alterer` tag.
-1. In the class implement the alteration logic the `alterCommandInfo()` method.
-1. Along with the alter code, it's strongly recommended to log a debug message explaining what exactly was altered. This would allow the easy debugging. Also it's a good practice to inject the the logger in the class constructor.
+1. In that class, implement the alteration logic in the `alterCommandInfo()` method.
+1. Along with the alter code, it's strongly recommended to log a debug message explaining what exactly was altered. This makes things easier on others who may need to debug the interaction of the alter code with other modules. Also it's a good practice to inject the the logger in the class constructor.
 
 For an example, see the alterer class provided by the testing 'woot' module: `tests/resources/modules/d8/woot/src/WootCommandInfoAlterer.php`.
 
-Global Drush Commands
+Site-Wide Drush Commands
 ==============================
 
-Commandfiles that don't ship inside Drupal modules are called 'global' commandfiles. See the [examples/Commands](https://github.com/drush-ops/drush/tree/master/examples/Commands) folder for examples. In general, it's better to use modules to carry your Drush commands. If you still prefer using a global commandfiles, here are two examples of valid commandfile names and namespaces:
+Commandfiles that are installed in a Drupal site and are not bundled inside a Drupal module are called 'site-wide' commandfiles. Site-wide commands may either be added directly to the Drupal site's repository (e.g. for site-specific policy files), or via `composer require`. See the [examples/Commands](/examples/Commands) folder for examples. In general, it's better to use modules to carry your Drush commands, as module-based commands may [participate in Drupal's dependency injection via the drush.services.yml](#specifying-the-services-file). 
+
+If you still prefer using site-wide commandfiles, here are some examples of valid commandfile names and namespaces:
 
 1. Simple
      - Filename: $PROJECT_ROOT/drush/Commands/ExampleCommands.php
      - Namespace: Drush\Commands
-1. Nested (e.g. Commandfile is part of a Composer package)
-    - Filename: $PROJECT_ROOT/drush/Commands/dev_modules/ExampleCommands.php
+1. Nested in a subdirectory committed to the site's repository
+     - Filename: $PROJECT_ROOT/drush/Commands/example/ExampleCommands.php
+     - Namespace: Drush\Commands\example
+1. Nested in a subdirectory installed via a Composer package
+    - Filename: $PROJECT_ROOT/drush/Commands/contrib/dev_modules/ExampleCommands.php
     - Namespace: Drush\Commands\dev_modules
 
+Installing commands as part of a Composer project requires that the project's type be `drupal-drush`, and that the `installer-paths` in the Drupal site's composer.json file contains `"drush/Commands/contrib/{$name}": ["type:drupal-drush"]`. It is also possible to commit projects with a similar layout using a directory named `custom` in place of `contrib`; if this is done, then the directory `custom` will not be considered to be part of the commandfile's namespace.
+
+If a site-wide commandfile is added via a Composer package, then it may declare any dependencies that it may need in its composer.json file. Site-wide commandfiles that are committed directly to a site's repository only have access to the dependencies already available in the site. Site-wide commandfiles should declare their Drush version compatibility via a `conflict` directive. For example, a Composer-managed site-wide command that works with both Drush 8 and Drush 9 might contain something similar to the following in its composer.json file:
+```
+    "conflict": {
+        "drush/drush": "<8.1 || >=9.0 <9.5 || >=10.0",
+    }
+```
+Using `require` in place of `conflict` is not recommended.
+
+Global Drush Commands
+==============================
+
+Commandfiles that are not part of any Drupal site are called 'global' commandfiles. Global commandfiles are not supported by default; in order to enable them, you must configure your `drush.yml` configuration file to add an `include` search location.
+
+For example:
+
+drush:
+  paths:
+    include:
+      - '${env.home}/.drush/commands'
+      
+With this configuration in place, global commands may be placed as described in the Site-Wide Drush Commands section above. Global commandfiles may not declare any dependencies of their own; they may only use those dependencies already available via the autoloader.
+
 ##### Tips
 1. The filename must be have a name like Commands/ExampleCommands.php
     1. The prefix `Example` can be whatever string you want.
     1. The file must end in `Commands.php`
-1. The directory above Commands must be one of: 
-    1.  A Folder listed in the 'include' option. include may be provided via config or via CLI.
+1. The directory above `Commands` must be one of: 
+    1.  A Folder listed in the 'include' option. Include may be provided via [config](#global-drush-commands) or via CLI.
     1.  ../drush, /drush or /sites/all/drush. These paths are relative to Drupal root.

scenarios/isolation-phpunit4/composer.json

@@ -60,6 +60,7 @@
     "optimize-autoloader": true,
     "preferred-install": "dist",
     "sort-packages": true,
+    "process-timeout": 2400,
     "platform": {
 
     },

scenarios/isolation/composer.json

@@ -60,6 +60,7 @@
     "optimize-autoloader": true,
     "preferred-install": "dist",
     "sort-packages": true,
+    "process-timeout": 2400,
     "platform": {
 
     },

src/Application.php

@@ -316,6 +316,7 @@ public function configureAndRegisterCommands(InputInterface $input, OutputInterf
 
         $discovery = $this->commandDiscovery();
         $commandClasses = $discovery->discover($commandfileSearchpath, '\Drush');
+
         $this->loadCommandClasses($commandClasses);
 
         // Uncomment the lines below to use Console's built in help and list commands.
@@ -350,6 +351,10 @@ protected function commandDiscovery()
         $discovery = new CommandFileDiscovery();
         $discovery
             ->setIncludeFilesAtBase(true)
+            ->setSearchDepth(3)
+            ->ignoreNamespacePart('contrib', 'Commands')
+            ->ignoreNamespacePart('custom', 'Commands')
+            ->ignoreNamespacePart('src')
             ->setSearchLocations(['Commands', 'Hooks', 'Generators'])
             ->setSearchPattern('#.*(Command|Hook|Generator)s?.php$#');
         return $discovery;

src/Config/ConfigLocator.php

@@ -5,7 +5,6 @@
 use Drush\Config\Loader\YamlConfigLoader;
 use Consolidation\Config\Loader\ConfigProcessor;
 use Consolidation\Config\Util\EnvConfig;
-use Symfony\Component\Finder\Finder;
 
 /**
  * Locate Drush configuration files and load them into the configuration
@@ -422,7 +421,7 @@ public function getCommandFilePaths($commandPaths, $root)
     {
         $builtin = $this->getBuiltinCommandFilePaths();
         $included = $this->getIncludedCommandFilePaths($commandPaths);
-        $site = $this->getSiteCommandFilePaths(["$root/drush", dirname($root) . '/drush']);
+        $site = $this->getSiteCommandFilePaths($root);
 
         return array_merge(
             $builtin,
@@ -462,29 +461,11 @@ protected function getIncludedCommandFilePaths($commandPaths)
      * 'dirname($root)/drush' directory that contains a composer.json
      * file or a 'Commands' or 'src/Commands' directory.
      */
-    protected function getSiteCommandFilePaths($directories)
+    protected function getSiteCommandFilePaths($root)
     {
-        $result = [];
-
-        $directories = array_filter($directories, 'is_dir');
-
-        if (empty($directories)) {
-            return $result;
-        }
+        $directories = ["$root/drush", dirname($root) . '/drush', "$root/sites/all/drush"];
 
-        // Find projects
-        $finder = new Finder();
-        $finder->directories()
-            ->ignoreUnreadableDirs()
-            ->path('#^src/Commands$|^Commands$#')
-            ->in($directories)
-            ->depth('<= 3');
-
-        foreach ($finder as $file) {
-            $result[] = dirname($file->getRealPath());
-        }
-
-        return $result;
+        return array_filter($directories, 'is_dir');
     }
 
     /**

sut/drush/Commands/SimpleSutCommands.php

@@ -0,0 +1,32 @@
+<?php
+namespace Drush\Commands;
+
+use Consolidation\AnnotatedCommand\AnnotationData;
+use Consolidation\AnnotatedCommand\CommandData;
+use Consolidation\AnnotatedCommand\Events\CustomEventAwareInterface;
+use Consolidation\AnnotatedCommand\Events\CustomEventAwareTrait;
+use Consolidation\OutputFormatters\StructuredData\RowsOfFields;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Style\SymfonyStyle;
+use Drush\Commands\DrushCommands;
+
+use Drush\Style\DrushStyle;
+use Drush\Utils\StringUtils;
+
+/**
+ * Site-wide commands for the System-Under-Test site
+ */
+
+class SimpleSutCommands extends DrushCommands
+{
+    /**
+     * Show a fabulous picture.
+     *
+     * @command sut:simple
+     */
+    public function example()
+    {
+        $this->logger()->notice(dt("This is an example site-wide command committed to the repository in the SUT inside of the 'drush/Commands' directory."));
+    }
+}

sut/drush/Commands/custom/example-site-wide-command/NestedSutCommands.php

@@ -0,0 +1,32 @@
+<?php
+namespace Drush\Commands\example_site_wide_command;
+
+use Consolidation\AnnotatedCommand\AnnotationData;
+use Consolidation\AnnotatedCommand\CommandData;
+use Consolidation\AnnotatedCommand\Events\CustomEventAwareInterface;
+use Consolidation\AnnotatedCommand\Events\CustomEventAwareTrait;
+use Consolidation\OutputFormatters\StructuredData\RowsOfFields;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Style\SymfonyStyle;
+use Drush\Commands\DrushCommands;
+
+use Drush\Style\DrushStyle;
+use Drush\Utils\StringUtils;
+
+/**
+ * Site-wide commands for the System-Under-Test site
+ */
+
+class NestedSutCommands extends DrushCommands
+{
+    /**
+     * Show a fabulous picture.
+     *
+     * @command sut:nested
+     */
+    public function example()
+    {
+        $this->logger()->notice(dt("This is an example site-wide command committed to the repository in the SUT nested inside a custom/example-site-wide-command directory."));
+    }
+}

sut/drush/Commands/custom/example-site-wide-command/src/NestedSrcSutCommands.php

@@ -0,0 +1,32 @@
+<?php
+namespace Drush\Commands\example_site_wide_command;
+
+use Consolidation\AnnotatedCommand\AnnotationData;
+use Consolidation\AnnotatedCommand\CommandData;
+use Consolidation\AnnotatedCommand\Events\CustomEventAwareInterface;
+use Consolidation\AnnotatedCommand\Events\CustomEventAwareTrait;
+use Consolidation\OutputFormatters\StructuredData\RowsOfFields;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Style\SymfonyStyle;
+use Drush\Commands\DrushCommands;
+
+use Drush\Style\DrushStyle;
+use Drush\Utils\StringUtils;
+
+/**
+ * Site-wide commands for the System-Under-Test site
+ */
+
+class NestedSrcSutCommands extends DrushCommands
+{
+    /**
+     * Show a fabulous picture.
+     *
+     * @command sut:nested-src
+     */
+    public function example()
+    {
+        $this->logger()->notice(dt("This is an example site-wide command committed to the repository in the SUT nested inside a custom/example-site-wide-command/src directory."));
+    }
+}