[do not merge] Document the upcoming Selector Expressions feature

websites/rushjs.io/docs/pages/advanced/selector_expressions.md

@@ -0,0 +1,170 @@
+---
+title: Selector expressions
+---
+
+## Introduction
+
+A **selector expression** is a way to combine multiple selectors, selector parameters, and set operators to select a specific subset of projects.
+
+For example, you may want to select all projects that _were changed in the current pull request_ and also _tagged in rush.json with the tag "app"_. You can express this as a JSON selector expression:
+
+```json
+{
+  "intersect": ["git:origin/main", "tag:app"]
+}
+```
+
+If you save this expression in a local file, `example.json`, you can select it on the command line:
+
+```bash
+rush build --to json:example.json
+```
+
+## Common examples
+
+### Intersecting selections
+
+A very common reason to use a selector expression is that you need an _intersection_ of different filters. Without an expression, you can only combine multiple selector parameters on the command line, which provides a _union_ of all selections.
+
+The introduction above provides an example:
+
+```json
+{
+  "intersect": ["git:origin/main", "tag:app"]
+}
+```
+
+### Operating on a selection parameter
+
+In addition to operating on a selector, you can _apply_ a selection parameter (like `from` or `to` or `impacted-by`) and then perform set operations on the result. For example, instead of finding changed projects tagged "app", perhaps you need the set of projects that could be _impacted by_ the changed projects, that are tagged "app".
+
+```json
+{
+  "intersect": [{ "impactedBy": "git:origin/main" }, "tag:app"]
+}
+```
+
+Each selection parameter from the command line is available as a JSON property in a JSON selector expression -- just remove the leading dashes and make it lower camelcase. For example, `--to-except` becomes `"toExcept"` in a selector expression.
+
+### Listing projects
+
+A list of named projects is technically a _set union_ of the named projects.
+
+For example, you may have several key projects in the repo, and in a pull request, you need a list of any project that is in the dependency tree for those projects and also impacted by this pull request. That might look like this:
+
+```json
+{
+  "intersect": [
+    {
+      "to": {
+        "union": ["@acme/project1", "@acme/project2", "@acme/project3"]
+      }
+    },
+    {
+      "impactedBy": "git:origin/main"
+    }
+  ]
+}
+```
+
+When you use this selector expression, you probably want _only_ the projects that are the result of this expression; you can obtain this from the command line like this:
+
+```bash
+rush list --only json:example.json
+```
+
+## Expression reference
+
+### Operators
+
+#### Union
+
+```json
+{
+   "union": ["expression1", "expression2", ...]
+}
+```
+
+This operator returns the union of two or more expressions (that is, it returns projects that are in at least one of the passed expressions).
+
+#### Intersect
+
+```json
+{
+   "intersect": ["expression1", "expression2", ...]
+}
+```
+
+This operator returns the intersection of two or more expressions (that is, it returns only projects that are in all of the passed expressions).
+
+#### Subtract
+
+```json
+{
+   "subtract": ["expression1", "expression2", ...]
+}
+```
+
+This operator returns the subtraction of two or more expressions (that is, it returns only projects that are in expression1, but not in any of the remaining expressions).
+
+### Selection parameters
+
+#### to
+
+```json
+{
+  "to": "expression"
+}
+```
+
+Filters the provided expression, using the same rules as `--to`.
+
+#### toExcept
+
+```json
+{
+  "toExcept": "expression"
+}
+```
+
+Filters the provided expression, using the same rules as `--to-except`.
+
+#### from
+
+```json
+{
+  "from": "expression"
+}
+```
+
+Filters the provided expression, using the same rules as `--from`.
+
+#### impactedBy
+
+```json
+{
+  "impactedBy": "expression"
+}
+```
+
+Filters the provided expression, using the same rules as `--impacted-by`.
+
+#### impactedByExcept
+
+```json
+{
+  "impactedByExcept": "expression"
+}
+```
+
+Filters the provided expression, using the same rules as `--impacted-by-except`.
+
+#### only
+
+```json
+{
+  "only": "expression"
+}
+```
+
+This parameter is supported for completeness only, to mimic the parameter `--only`. It serves no practical purpose, and just returns the provided expression without changes.

websites/rushjs.io/docs/pages/developer/selecting_subsets.md

@@ -236,15 +236,34 @@ rush build --to tag:shipping
 rush list --only tag:frontend-team-libs --detailed
 ```
 
+### JSON file: `json:`
+
+This selector allows you to specify the path to a JSON file containing a \*_JSON selector expression_. These expressions allow you to define complex project selections (for example, "all projects changed since this commit that are also tagged with this tag"). These expressions can use all of the selectors and selector parameters from above, and also make use of set operators like union, intersect, and subtract.
+
+To use a selector expression file, you'll create a JSON file containing the expression and then refer to it in a `json:` selector.
+
+Examples:
+
+```bash
+# Select a predefined subset of projects (the path is relative to monorepo root)
+rush build --to json:common/config/updated-web-apps.json
+
+# Use a file relative to the current path
+rush build --to json:./apps.json
+
+# Use a JSON expression piped from stdin
+cat expression.json | rush build --to json:-
+```
+
+For more details on selector expressions, see the advanced guide: [Selector expressions](../advanced/selector_expressions.md).
+
 ## Combining parameters
 
 - You can combine any of the selection parameters on a single command line. The result is always the union of each
   individual selection.
 - The same parameter can be specified multiple times. For example: `rush build --only A --only B --only C`
   will select `A`, `B`, and `C`
-- Note that Rush does not provide any parameter that would reduce the selection. This is an intentional design choice;
-  in [#1241](https://github.com/microsoft/rushstack/issues/1241) we'll implement personal tags for building up more
-  complex selections.)
+- Note that Rush does not provide command-line parameters that would reduce the selection. This is an intentional design choice. If you need more complex selections (for example, intersecting or subtracting different selections), see [Selector expressions](../advanced/selector_expressions.md).
 
 Here's a more complex combined command-line: