[flutter_plugin_tools] Add --packages, and deprecated --plugins (#4134)

Most of the tool operates on packages in general, and the targetting
done currently by the `--plugins` flag is not actually restricted to
plugins, so this makes the name less confusing.

Part of flutter/flutter#83413

Author: stuartmorgan-g

script/tool/CHANGELOG.md

@@ -7,6 +7,8 @@
   new output format.
 - Fixed some cases where a failure in a command for a single package would
   immediately abort the test.
+- Deprecated `--plugins` in favor of new `--packages`. `--plugins` continues to
+  work for now, but will be removed in the future.
 
 ## 0.3.0
 

script/tool/README.md

@@ -58,31 +58,31 @@ Note that the `plugins` argument, despite the name, applies to any package.
 
 ```sh
 cd <repository root>
-dart run ./script/tool/bin/flutter_plugin_tools.dart format --plugins plugin_name
+dart run ./script/tool/bin/flutter_plugin_tools.dart format --packages plugin_name
 ```
 
 ### Run the Dart Static Analyzer
 
 ```sh
 cd <repository root>
-dart run ./script/tool/bin/flutter_plugin_tools.dart analyze --plugins plugin_name
+dart run ./script/tool/bin/flutter_plugin_tools.dart analyze --packages plugin_name
 ```
 
 ### Run Dart Unit Tests
 
 ```sh
 cd <repository root>
-dart run ./script/tool/bin/flutter_plugin_tools.dart test --plugins plugin_name
+dart run ./script/tool/bin/flutter_plugin_tools.dart test --packages plugin_name
 ```
 
 ### Run XCTests
 
 ```sh
 cd <repository root>
 # For iOS:
-dart run ./script/tool/bin/flutter_plugin_tools.dart xctest --ios --plugins plugin_name
+dart run ./script/tool/bin/flutter_plugin_tools.dart xctest --ios --packages plugin_name
 # For macOS:
-dart run ./script/tool/bin/flutter_plugin_tools.dart xctest --macos --plugins plugin_name
+dart run ./script/tool/bin/flutter_plugin_tools.dart xctest --macos --packages plugin_name
 ```
 
 ### Publish a Release

script/tool/lib/src/common/plugin_command.dart

@@ -24,11 +24,12 @@ abstract class PluginCommand extends Command<void> {
     GitDir? gitDir,
   }) : _gitDir = gitDir {
     argParser.addMultiOption(
-      _pluginsArg,
+      _packagesArg,
       splitCommas: true,
       help:
-          'Specifies which plugins the command should run on (before sharding).',
-      valueHelp: 'plugin1,plugin2,...',
+          'Specifies which packages the command should run on (before sharding).\n',
+      valueHelp: 'package1,package2,...',
+      aliases: <String>[_pluginsArg],
     );
     argParser.addOption(
       _shardIndexArg,
@@ -51,7 +52,7 @@ abstract class PluginCommand extends Command<void> {
     );
     argParser.addFlag(_runOnChangedPackagesArg,
         help: 'Run the command on changed packages/plugins.\n'
-            'If the $_pluginsArg is specified, this flag is ignored.\n'
+            'If the $_packagesArg is specified, this flag is ignored.\n'
             'If no packages have changed, or if there have been changes that may\n'
             'affect all packages, the command runs on all packages.\n'
             'The packages excluded with $_excludeArg is also excluded even if changed.\n'
@@ -63,6 +64,7 @@ abstract class PluginCommand extends Command<void> {
   }
 
   static const String _pluginsArg = 'plugins';
+  static const String _packagesArg = 'packages';
   static const String _shardIndexArg = 'shardIndex';
   static const String _shardCountArg = 'shardCount';
   static const String _excludeArg = 'exclude';
@@ -203,7 +205,7 @@ abstract class PluginCommand extends Command<void> {
   ///    is a sibling of the packages directory. This is used for a small number
   ///    of packages in the flutter/packages repository.
   Stream<Directory> _getAllPlugins() async* {
-    Set<String> plugins = Set<String>.from(getStringListArg(_pluginsArg));
+    Set<String> plugins = Set<String>.from(getStringListArg(_packagesArg));
     final Set<String> excludedPlugins =
         Set<String>.from(getStringListArg(_excludeArg));
     final bool runOnChangedPackages = getBoolArg(_runOnChangedPackagesArg);

script/tool/test/common/plugin_command_test.dart

@@ -69,6 +69,22 @@ void main() {
       expect(plugins, unorderedEquals(<String>[plugin1.path, plugin2.path]));
     });
 
+    test('includes both plugins and packages', () async {
+      final Directory plugin1 = createFakePlugin('plugin1', packagesDir);
+      final Directory plugin2 = createFakePlugin('plugin2', packagesDir);
+      final Directory package3 = createFakePackage('package3', packagesDir);
+      final Directory package4 = createFakePackage('package4', packagesDir);
+      await runCapturingPrint(runner, <String>['sample']);
+      expect(
+          plugins,
+          unorderedEquals(<String>[
+            plugin1.path,
+            plugin2.path,
+            package3.path,
+            package4.path,
+          ]));
+    });
+
     test('all plugins includes third_party/packages', () async {
       final Directory plugin1 = createFakePlugin('plugin1', packagesDir);
       final Directory plugin2 = createFakePlugin('plugin2', packagesDir);
@@ -79,40 +95,73 @@ void main() {
           unorderedEquals(<String>[plugin1.path, plugin2.path, plugin3.path]));
     });
 
-    test('exclude plugins when plugins flag is specified', () async {
+    test('--packages limits packages', () async {
+      final Directory plugin1 = createFakePlugin('plugin1', packagesDir);
+      createFakePlugin('plugin2', packagesDir);
+      createFakePackage('package3', packagesDir);
+      final Directory package4 = createFakePackage('package4', packagesDir);
+      await runCapturingPrint(
+          runner, <String>['sample', '--packages=plugin1,package4']);
+      expect(
+          plugins,
+          unorderedEquals(<String>[
+            plugin1.path,
+            package4.path,
+          ]));
+    });
+
+    test('--plugins acts as an alias to --packages', () async {
+      final Directory plugin1 = createFakePlugin('plugin1', packagesDir);
+      createFakePlugin('plugin2', packagesDir);
+      createFakePackage('package3', packagesDir);
+      final Directory package4 = createFakePackage('package4', packagesDir);
+      await runCapturingPrint(
+          runner, <String>['sample', '--plugins=plugin1,package4']);
+      expect(
+          plugins,
+          unorderedEquals(<String>[
+            plugin1.path,
+            package4.path,
+          ]));
+    });
+
+    test('exclude packages when packages flag is specified', () async {
       createFakePlugin('plugin1', packagesDir);
       final Directory plugin2 = createFakePlugin('plugin2', packagesDir);
-      await runCapturingPrint(runner,
-          <String>['sample', '--plugins=plugin1,plugin2', '--exclude=plugin1']);
+      await runCapturingPrint(runner, <String>[
+        'sample',
+        '--packages=plugin1,plugin2',
+        '--exclude=plugin1'
+      ]);
       expect(plugins, unorderedEquals(<String>[plugin2.path]));
     });
 
-    test('exclude plugins when plugins flag isn\'t specified', () async {
+    test('exclude packages when packages flag isn\'t specified', () async {
       createFakePlugin('plugin1', packagesDir);
       createFakePlugin('plugin2', packagesDir);
       await runCapturingPrint(
           runner, <String>['sample', '--exclude=plugin1,plugin2']);
       expect(plugins, unorderedEquals(<String>[]));
     });
 
-    test('exclude federated plugins when plugins flag is specified', () async {
+    test('exclude federated plugins when packages flag is specified', () async {
       createFakePlugin('plugin1', packagesDir.childDirectory('federated'));
       final Directory plugin2 = createFakePlugin('plugin2', packagesDir);
       await runCapturingPrint(runner, <String>[
         'sample',
-        '--plugins=federated/plugin1,plugin2',
+        '--packages=federated/plugin1,plugin2',
         '--exclude=federated/plugin1'
       ]);
       expect(plugins, unorderedEquals(<String>[plugin2.path]));
     });
 
-    test('exclude entire federated plugins when plugins flag is specified',
+    test('exclude entire federated plugins when packages flag is specified',
         () async {
       createFakePlugin('plugin1', packagesDir.childDirectory('federated'));
       final Directory plugin2 = createFakePlugin('plugin2', packagesDir);
       await runCapturingPrint(runner, <String>[
         'sample',
-        '--plugins=federated/plugin1,plugin2',
+        '--packages=federated/plugin1,plugin2',
         '--exclude=federated'
       ]);
       expect(plugins, unorderedEquals(<String>[plugin2.path]));
@@ -315,7 +364,8 @@ packages/plugin1/plugin1_web/plugin1_web.dart
         expect(plugins, unorderedEquals(<String>[plugin1.path]));
       });
 
-      test('--plugins flag overrides the behavior of --run-on-changed-packages',
+      test(
+          '--packages flag overrides the behavior of --run-on-changed-packages',
           () async {
         gitDiffResponse = '''
 packages/plugin1/plugin1.dart
@@ -328,7 +378,7 @@ packages/plugin3/plugin3.dart
         createFakePlugin('plugin3', packagesDir);
         await runCapturingPrint(runner, <String>[
           'sample',
-          '--plugins=plugin1,plugin2',
+          '--packages=plugin1,plugin2',
           '--base-sha=master',
           '--run-on-changed-packages'
         ]);

script/tool/test/list_command_test.dart

@@ -139,7 +139,7 @@ void main() {
       );
     });
 
-    test('can filter plugins with the --plugins argument', () async {
+    test('can filter plugins with the --packages argument', () async {
       createFakePlugin('plugin1', packagesDir);
 
       // Create a federated plugin by creating a directory under the packages
@@ -157,7 +157,7 @@ void main() {
       createFakePubspec(macLibrary);
 
       List<String> plugins = await runCapturingPrint(
-          runner, <String>['list', '--plugins=plugin1']);
+          runner, <String>['list', '--packages=plugin1']);
       expect(
         plugins,
         unorderedEquals(<String>[
@@ -166,7 +166,7 @@ void main() {
       );
 
       plugins = await runCapturingPrint(
-          runner, <String>['list', '--plugins=my_plugin']);
+          runner, <String>['list', '--packages=my_plugin']);
       expect(
         plugins,
         unorderedEquals(<String>[
@@ -177,7 +177,7 @@ void main() {
       );
 
       plugins = await runCapturingPrint(
-          runner, <String>['list', '--plugins=my_plugin/my_plugin_web']);
+          runner, <String>['list', '--packages=my_plugin/my_plugin_web']);
       expect(
         plugins,
         unorderedEquals(<String>[
@@ -186,7 +186,7 @@ void main() {
       );
 
       plugins = await runCapturingPrint(runner,
-          <String>['list', '--plugins=my_plugin/my_plugin_web,plugin1']);
+          <String>['list', '--packages=my_plugin/my_plugin_web,plugin1']);
       expect(
         plugins,
         unorderedEquals(<String>[