feat: implement reversed-filter-group-priority option

docs/filters.mdx

@@ -5,17 +5,29 @@ description: Learn more about all the package filtering flags in Melos.
 
 # Filtering Packages
 
-Each Melos command can be used alongside the following global filters:
+Each Melos command can be used alongside the following global filters.
 
-## --no-private
+The filters are divided into 2 priority groups. The priority determines the
+order of their application. The grouping has been introduced with backward
+compatibility in mind. It is possible to reverse the order of the priority
+groups to achive different filtering result.
+
+## --reversed-filter-group-priority
+Reverses the priority of filtering groups. Useful for applying diff-based
+filtering first, allowing the filters from the other group to further narrow
+down the packages.
+
+## 1st Priority Group
+
+### --no-private
 
 Exclude private packages (`publish_to: none`). They are included by default.
 
 ```bash
 melos bootstrap --no-private
 ```
 
-## --published
+### --published
 
 Filter packages where the current local package version exists on pub.dev.
 
@@ -26,7 +38,7 @@ melos bootstrap --published
 Use `--no-published` to filter packages that have not had their current version
 published yet.
 
-## --scope
+### --scope
 
 Include only packages with names matching the given glob. This option can be
 repeated.
@@ -36,7 +48,7 @@ repeated.
 melos exec --scope="*example*" -- flutter build ios
 ```
 
-## --ignore
+### --ignore
 
 Exclude packages with names matching the given glob. This option can be
 repeated.
@@ -46,25 +58,7 @@ repeated.
 melos exec --ignore="*internal*" -- flutter build ios
 ```
 
-## --diff
-
-Filter packages based on whether there were changes between a commit and the
-current HEAD or within a range of commits.
-
-A range of commits can be specified using the git short hand syntax
-`<start-commit>..<end-commit>` and `<start-commit>...<end-commit>`.
-
-```bash
-# Run `flutter build ios` on all packages that are different between current
-# branch and the specified commit hash.
-melos exec --diff=<commit hash> -- flutter build ios
-
-# Run `flutter build ios` on all packages that are different between remote
-# `main` branch and HEAD.
-melos exec --diff=origin/main...HEAD -- flutter build ios
-```
-
-## --dir-exists
+### --dir-exists
 
 Include only packages where a specific directory exists inside the package.
 
@@ -73,7 +67,7 @@ Include only packages where a specific directory exists inside the package.
 melos bootstrap --dir-exists="example"
 ```
 
-## --file-exists
+### --file-exists
 
 Include only packages where a specific file exists in the package.
 
@@ -82,7 +76,7 @@ Include only packages where a specific file exists in the package.
 melos bootstrap --file-exists="README.md"
 ```
 
-## --flutter
+### --flutter
 
 Filter packages where the package depends on the Flutter SDK.
 
@@ -92,7 +86,7 @@ melos exec --flutter -- flutter test
 
 Use `--no-flutter` to filter packages that do not depend on the Flutter SDK.
 
-## --depends-on
+### --depends-on
 
 Include only packages that depend on specific dependencies.
 
@@ -103,7 +97,32 @@ melos exec --depends-on="flutter" --depends-on="firebase_core" -- flutter test
 Use `--no-depends-on` to filter packages that do not depend on the given
 dependencies.
 
-## --include-dependencies
+## 2nd Priority Group
+
+### --diff
+
+Filter packages based on whether there were changes between a commit and the
+current HEAD or within a range of commits.
+
+A range of commits can be specified using the git short hand syntax
+`<start-commit>..<end-commit>` and `<start-commit>...<end-commit>`.
+
+```bash
+# Run `flutter build ios` on all packages that are different between current
+# branch and the specified commit hash.
+melos exec --diff=<commit hash> -- flutter build ios
+
+# Run `flutter build ios` on all packages that are different between remote
+# `main` branch and HEAD.
+melos exec --diff=origin/main...HEAD -- flutter build ios
+
+# Find all packages that are different between remote `main` branch and HEAD,
+# add their dependents to the list, filter out packages without `test`
+# directory and run `flutter test` on them.
+melos exec --diff=origin/main...HEAD --include-dependents --reversed-filter-group-priority --dir-exists="test" -- flutter test
+```
+
+### --include-dependencies
 
 Takes the filtered list of packages, and expands them to include those packages'
 transitive dependencies (ignoring filters).
@@ -112,7 +131,7 @@ transitive dependencies (ignoring filters).
 melos list --scope=some_package --include-dependencies
 ```
 
-## --include-dependents
+### --include-dependents
 Takes the filtered list of packages, and expands them to include those packages'
 transitive dependents (ignoring filters).
 

packages/melos/lib/src/command_runner/base.dart

@@ -42,7 +42,8 @@ abstract class MelosCommand extends Command<void> {
     argParser.addFlag(
       filterOptionPrivate,
       help: 'Whether to include or exclude packages with `publish_to: "none"`. '
-          'By default, the filter has no effect.',
+          'By default, the filter has no effect.'
+          ' ${FilterGroup.belongsToFirstPriorityGroupFilterDescription}',
       defaultsTo: null,
     );
 
@@ -51,7 +52,8 @@ abstract class MelosCommand extends Command<void> {
       defaultsTo: null,
       help: 'Filter packages where the current local package version exists on '
           'pub.dev. Or "-no-published" to filter packages that have not had '
-          'their current version published yet.',
+          'their current version published yet.'
+          ' ${FilterGroup.belongsToFirstPriorityGroupFilterDescription}',
     );
 
     argParser.addFlag(
@@ -60,52 +62,48 @@ abstract class MelosCommand extends Command<void> {
       help:
           'Filter packages where the current local version uses a "nullsafety" '
           'prerelease preid. Or "-no-nullsafety" to filter packages where '
-          'their current version does not have a "nullsafety" preid.',
+          'their current version does not have a "nullsafety" preid.'
+          ' ${FilterGroup.belongsToFirstPriorityGroupFilterDescription}',
     );
 
     argParser.addFlag(
       filterOptionFlutter,
       defaultsTo: null,
       help: 'Filter packages where the package depends on the Flutter SDK. Or '
           '"-no-flutter" to filter packages that do not depend on the Flutter '
-          'SDK.',
+          'SDK.'
+          ' ${FilterGroup.belongsToFirstPriorityGroupFilterDescription}',
     );
 
     argParser.addMultiOption(
       filterOptionScope,
       valueHelp: 'glob',
       help: 'Include only packages with names matching the given glob. This '
-          'option can be repeated.',
+          'option can be repeated.'
+          ' ${FilterGroup.belongsToFirstPriorityGroupFilterDescription}',
     );
 
     argParser.addMultiOption(
       filterOptionIgnore,
       valueHelp: 'glob',
       help: 'Exclude packages with names matching the given glob. This option '
-          'can be repeated.',
-    );
-
-    argParser.addOption(
-      filterOptionDiff,
-      valueHelp: 'ref',
-      help: 'Filter packages based on whether there were changes between a '
-          'commit and the current HEAD or within a range of commits. A range '
-          'of commits can be specified using the git short hand syntax '
-          '`<start-commit>..<end-commit>` and `<start-commit>...<end-commit>`',
+          'can be repeated.'
+          ' ${FilterGroup.belongsToFirstPriorityGroupFilterDescription}',
     );
 
     argParser.addMultiOption(
       filterOptionDirExists,
       valueHelp: 'dirRelativeToPackageRoot',
       help: 'Include only packages where a specific directory exists inside '
-          'the package.',
+          'the package.'
+          ' ${FilterGroup.belongsToFirstPriorityGroupFilterDescription}',
     );
 
     argParser.addMultiOption(
       filterOptionFileExists,
       valueHelp: 'fileRelativeToPackageRoot',
-      help:
-          'Include only packages where a specific file exists in the package.',
+      help: 'Include only packages where a specific file exists in the package.'
+          ' ${FilterGroup.belongsToFirstPriorityGroupFilterDescription}',
     );
 
     argParser.addMultiOption(
@@ -122,20 +120,37 @@ abstract class MelosCommand extends Command<void> {
           'This option can be repeated.',
     );
 
+    argParser.addOption(
+      filterOptionDiff,
+      valueHelp: 'ref',
+      help: 'Filter packages based on whether there were changes between a '
+          'commit and the current HEAD or within a range of commits. A range '
+          'of commits can be specified using the git short hand syntax '
+          '`<start-commit>..<end-commit>` and `<start-commit>...<end-commit>`.'
+          ' ${FilterGroup.belongsToSecondPriorityGroupFilterDescription}',
+    );
+
     argParser.addFlag(
       filterOptionIncludeDependents,
       negatable: false,
       help: 'Include all transitive dependents for each package that matches '
-          'the other filters. The included packages skip --ignore and '
-          '--diff checks.',
+          'the other filters.'
+          ' ${FilterGroup.belongsToSecondPriorityGroupFilterDescription}',
     );
 
     argParser.addFlag(
       filterOptionIncludeDependencies,
       negatable: false,
       help: 'Include all transitive dependencies for each package that '
-          'matches the other filters. The included packages skip --ignore '
-          'and --diff checks.',
+          'matches the other filters.'
+          ' ${FilterGroup.belongsToSecondPriorityGroupFilterDescription}',
+    );
+
+    argParser.addFlag(
+      filterOptionReversedFilterGroupPriority,
+      negatable: false,
+      help: 'Filters are divided into several groups based on their priority '
+          'of execution. This flag reverses the priority of these groups.',
     );
   }
 
@@ -172,6 +187,8 @@ abstract class MelosCommand extends Command<void> {
       noDependsOn: argResults![filterOptionNoDependsOn] as List<String>? ?? [],
       includeDependents: argResults![filterOptionIncludeDependents] as bool,
       includeDependencies: argResults![filterOptionIncludeDependencies] as bool,
+      reversedFilterGroupPriority:
+          argResults![filterOptionReversedFilterGroupPriority] as bool,
     );
   }
 }

packages/melos/lib/src/common/utils.dart

@@ -39,6 +39,8 @@ const filterOptionDependsOn = 'depends-on';
 const filterOptionNoDependsOn = 'no-depends-on';
 const filterOptionIncludeDependents = 'include-dependents';
 const filterOptionIncludeDependencies = 'include-dependencies';
+const filterOptionReversedFilterGroupPriority =
+    'reversed-filter-group-priority';
 
 const publishOptionDryRun = 'dry-run';
 const publishOptionNoDryRun = 'no-dry-run';