Refactors yarn workspaces foreach (#5644)

**What's the problem this PR addresses?**

The command default's behavior was "worktree" (ie to only run on the
current workspace and whatever it listed in its own `workspaces` field),
but it was rarely what users expected (since very few people use nested
workspace setups).

**How did you fix it?**

The main functional change is that one of `--all`, `--worktree`,
`--since`, or `--recursive` is now required. The `--since` flag doesn't
automatically imply `--worktree` anymore.

Using `--all` with one of `--worktree`, `--from`, `--since`, or
`--recursive` doesn't work anymore, since they have incompatible
meanings (it still accept `--include` and `--exclude` to further refine
the list).

**Checklist**
<!--- Don't worry if you miss something, chores are automatically
tested. -->
<!--- This checklist exists to help you remember doing the chores when
you submit a PR. -->
<!--- Put an `x` in all the boxes that apply. -->
- [x] I have read the [Contributing
Guide](https://yarnpkg.com/advanced/contributing).

<!-- See
https://yarnpkg.com/advanced/contributing#preparing-your-pr-to-be-released
for more details. -->
<!-- Check with `yarn version check` and fix with `yarn version check
-i` -->
- [x] I have set the packages that need to be released for my changes to
be effective.

<!-- The "Testing chores" workflow validates that your PR follows our
guidelines. -->
<!-- If it doesn't pass, click on it to see details as to what your PR
might be missing. -->
- [x] I will check that all automated PR checks pass before the PR gets
reviewed.

Author: arcanis

.pnp.cjs

@@ -0,0 +1,23 @@
+releases:
+  "@yarnpkg/cli": major
+  "@yarnpkg/plugin-workspace-tools": major
+
+declined:
+  - "@yarnpkg/plugin-compat"
+  - "@yarnpkg/plugin-constraints"
+  - "@yarnpkg/plugin-dlx"
+  - "@yarnpkg/plugin-essentials"
+  - "@yarnpkg/plugin-init"
+  - "@yarnpkg/plugin-interactive-tools"
+  - "@yarnpkg/plugin-nm"
+  - "@yarnpkg/plugin-npm-cli"
+  - "@yarnpkg/plugin-pack"
+  - "@yarnpkg/plugin-patch"
+  - "@yarnpkg/plugin-pnp"
+  - "@yarnpkg/plugin-pnpm"
+  - "@yarnpkg/plugin-stage"
+  - "@yarnpkg/plugin-typescript"
+  - "@yarnpkg/plugin-version"
+  - "@yarnpkg/builder"
+  - "@yarnpkg/core"
+  - "@yarnpkg/doctor"

.yarn/cache/typanion-npm-3.12.1-788497c54f-abd4cd4d4c.zip

@@ -15,6 +15,7 @@ Features in `master` can be tried out by running `yarn set version from sources`
 - Some important defaults have changed:
   - `yarn set version` will prefer using `packageManager` rather than `yarnPath` when possible.
   - `yarn init` will no longer use zero-install by default. You still can enable it, but it should make it easier to start one-of projects without having to rewrite the configuration afterwards.
+  - `yarn workspaces foreach` now requires one of `--all`, `--recursive`, `--since`, or `--worktree` to be explicitly specified; the previous default was `--worktree`, but it was rarely what users expected.
 
 - All official Yarn plugins are now included by default in the bundle we provide. You no longer need to run `yarn plugin import` for *official* plugins (you still need to do it for third-party plugins, of course).
   - This doesn't change anything to the plugin API we provide, which will keep being maintained.

.yarn/cache/typanion-npm-3.14.0-8af344c436-5e88d9e612.zip

@@ -38,7 +38,7 @@
     "node": ">=18.12.0"
   },
   "dependencies": {
-    "typanion": "^3.12.1",
+    "typanion": "^3.14.0",
     "uuid": "^8.3.2"
   }
 }

.yarn/versions/bae4fa98.yml

@@ -39,10 +39,6 @@ exports[`Commands workspace foreach --since runs on workspaces changed since bra
   "stderr": "",
   "stdout": "Test Workspace B
 Test Workspace C
-Test Workspace D
-Test Workspace E
-Test Workspace F
-Test Workspace G
 Done
 ",
 }
@@ -54,10 +50,6 @@ exports[`Commands workspace foreach --since runs on workspaces changed since com
   "stderr": "",
   "stdout": "Test Workspace B
 Test Workspace C
-Test Workspace D
-Test Workspace E
-Test Workspace F
-Test Workspace G
 Done
 ",
 }
@@ -291,7 +283,7 @@ Done
 }
 `;
 
-exports[`Commands workspace foreach should run on current and descendant workspaces by default 1`] = `
+exports[`Commands workspace foreach should run on current and descendant workspaces when --worktree is set 1`] = `
 {
   "code": 0,
   "stderr": "",

CHANGELOG.md

@@ -93,7 +93,7 @@ async function setupWorkspaces(path) {
 describe(`Commands`, () => {
   describe(`workspace foreach`, () => {
     test(
-      `should run on current and descendant workspaces by default`,
+      `should run on current and descendant workspaces when --worktree is set`,
       makeTemporaryEnv(
         {
           private: true,
@@ -103,7 +103,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          await expect(run(`workspaces`, `foreach`, `run`, `print`, {cwd: `${path}/packages/workspace-c`})).resolves.toMatchSnapshot();
+          await expect(run(`workspaces`, `foreach`, `--worktree`, `run`, `print`, {cwd: `${path}/packages/workspace-c`})).resolves.toMatchSnapshot();
         },
       ),
     );
@@ -119,15 +119,15 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          const {code, stdout, stderr} = await run(`workspaces`, `foreach`, `--parallel`, `--topological`, `node`, `-p`, `require("./package.json").name`, {cwd: `${path}/packages/workspace-c`});
+          const {code, stdout, stderr} = await run(`workspaces`, `foreach`, `--worktree`, `--parallel`, `--topological`, `node`, `-p`, `require("./package.json").name ?? "root"`, {cwd: `${path}/packages/workspace-c`});
 
           const orderedStdout = stdout.trim().split(`\n`);
           expect(orderedStdout.pop()).toContain(`Done`);
 
           // The exact order is unstable, so just make sure all the workspaces we expect to be there, are.
           orderedStdout.sort();
 
-          await expect({code, orderedStdout, stderr}).toMatchSnapshot();
+          expect({code, orderedStdout, stderr}).toMatchSnapshot();
         },
       ),
     );
@@ -143,7 +143,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          const {code, stdout, stderr} = await run(`workspaces`, `foreach`, `--parallel`, `--interlaced`, `--jobs`, `2`, `run`, `start`);
+          const {code, stdout, stderr} = await run(`workspaces`, `foreach`, `--all`, `--parallel`, `--interlaced`, `--jobs`, `2`, `run`, `start`);
 
           const lines = stdout.trim().split(`\n`);
           const firstLine = lines[0];
@@ -176,7 +176,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          const {code, stdout, stderr} = await run(`workspaces`, `foreach`, `--parallel`, `--topological`, `--jobs`, `2`, `run`, `print`);
+          const {code, stdout, stderr} = await run(`workspaces`, `foreach`, `--all`, `--parallel`, `--topological`, `--jobs`, `2`, `run`, `print`);
 
           const extractWorkspaces = output => {
             const relevantOutput = output.split(`\n`).filter(output => output.includes(`Test Workspace`));
@@ -206,7 +206,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          await expect(run(`workspaces`, `foreach`, `--verbose`, `run`, `print`)).resolves.toMatchSnapshot();
+          await expect(run(`workspaces`, `foreach`, `--all`, `--verbose`, `run`, `print`)).resolves.toMatchSnapshot();
         },
       ),
     );
@@ -222,7 +222,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          await expect(run(`workspaces`, `foreach`, `--no-verbose`, `run`, `print`)).resolves.toMatchSnapshot();
+          await expect(run(`workspaces`, `foreach`, `--all`, `--no-verbose`, `run`, `print`)).resolves.toMatchSnapshot();
         },
       ),
     );
@@ -238,7 +238,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          await expect(run(`workspaces`, `foreach`, `--verbose`, `--include`, `workspace-a`, `--include`, `packages/workspace-b`, `run`, `print`)).resolves.toMatchSnapshot();
+          await expect(run(`workspaces`, `foreach`, `--all`, `--verbose`, `--include`, `workspace-a`, `--include`, `packages/workspace-b`, `run`, `print`)).resolves.toMatchSnapshot();
         },
       ),
     );
@@ -254,7 +254,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          await expect(run(`workspaces`, `foreach`, `--verbose`, `--include`, `packages/workspace-c/**`, `run`, `print`)).resolves.toMatchSnapshot();
+          await expect(run(`workspaces`, `foreach`, `--all`, `--verbose`, `--include`, `packages/workspace-c/**`, `run`, `print`)).resolves.toMatchSnapshot();
         },
       ),
     );
@@ -270,7 +270,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          await expect(run(`workspaces`, `foreach`, `--verbose`, `--exclude`, `workspace-a`, `--exclude`, `packages/workspace-b`, `run`, `print`)).resolves.toMatchSnapshot();
+          await expect(run(`workspaces`, `foreach`, `--all`, `--verbose`, `--exclude`, `workspace-a`, `--exclude`, `packages/workspace-b`, `run`, `print`)).resolves.toMatchSnapshot();
         },
       ),
     );
@@ -306,7 +306,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          await expect(run(`workspaces`, `foreach`, `--jobs`, `2`, `run`, `print`)).rejects.toThrowError(/parallel must be set/);
+          await expect(run(`workspaces`, `foreach`, `--all`, `--jobs`, `2`, `run`, `print`)).rejects.toThrowError(/parallel must be set/);
         },
       ),
     );
@@ -322,7 +322,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          await expect(run(`workspaces`, `foreach`, `--parallel`, `--jobs`, `0`, `run`, `print`)).rejects.toThrowError(/to be at least 1 \(got 0\)/);
+          await expect(run(`workspaces`, `foreach`, `--all`, `--parallel`, `--jobs`, `0`, `run`, `print`)).rejects.toThrowError(/to be at least 1 \(got 0\)/);
         },
       ),
     );
@@ -338,7 +338,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          const {code, stdout, stderr} = await run(`workspaces`, `foreach`, `--parallel`, `--jobs`, `unlimited`, `--verbose`, `run`, `print`);
+          const {code, stdout, stderr} = await run(`workspaces`, `foreach`, `--all`, `--parallel`, `--jobs`, `unlimited`, `--verbose`, `run`, `print`);
 
           // We don't care what order they start in, just that they all started at the beginning.
           const first7Lines = stdout.split(`\n`).slice(0, 7).sort().join(`\n`);
@@ -382,7 +382,7 @@ describe(`Commands`, () => {
 
         await run(`install`);
 
-        await expect(run(`workspaces`, `foreach`, `--no-private`, `run`, `print`)).resolves.toMatchSnapshot();
+        await expect(run(`workspaces`, `foreach`, `--all`, `--no-private`, `run`, `print`)).resolves.toMatchSnapshot();
       },
     ));
 
@@ -399,7 +399,7 @@ describe(`Commands`, () => {
           let code = 0;
           try {
             await run(`install`);
-            await run(`workspaces`, `foreach`, `run`, `testExit`);
+            await run(`workspaces`, `foreach`, `--all`, `run`, `testExit`);
           } catch (error) {
             ({code} = error);
           }
@@ -423,7 +423,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          await expect(run(`workspaces`, `foreach`, `--topological`, `run`, `test:colon`)).resolves.toMatchSnapshot();
+          await expect(run(`workspaces`, `foreach`, `--all`, `--topological`, `run`, `test:colon`)).resolves.toMatchSnapshot();
         },
       ),
     );
@@ -442,7 +442,7 @@ describe(`Commands`, () => {
           await setupWorkspaces(path);
           await run(`install`);
 
-          await expect(run(`workspaces`, `foreach`, `--topological`, `run`, `g:echo`)).resolves.toMatchSnapshot();
+          await expect(run(`workspaces`, `foreach`, `--all`, `--topological`, `run`, `g:echo`)).resolves.toMatchSnapshot();
         },
       ),
     );
@@ -560,7 +560,7 @@ describe(`Commands`, () => {
         async ({run}) => {
           await run(`install`);
 
-          await expect(run(`workspaces`, `foreach`, `run`, `has-bin-entries`, `binary-executed`)).resolves.toMatchObject({
+          await expect(run(`workspaces`, `foreach`, `--all`, `run`, `has-bin-entries`, `binary-executed`)).resolves.toMatchObject({
             code: 0,
             stdout: expect.stringContaining(`binary-executed`),
           });

packages/acceptance-tests/pkg-tests-core/package.json

@@ -49,7 +49,7 @@ To declare a workspace, all you have to do is add a `workspaces` array to the ro
 
 Constraints are to monorepos what Eslint is to your source code. They let you declare rules that must apply to specific workspaces in your project. For example, you can use constraints to enforce that all dependencies in your project are synchronized, to prevent some dependencies from being used, or to enforce that some fields such as `license` or `engines.node` are properly set everywhere.
 
-For more information and examples about constraints, check the [dedicated article](/).
+For more information and examples about constraints, check the [dedicated article](/features/constraints).
 
 ### Cross-references
 
@@ -99,10 +99,10 @@ Global scripts are characterized by at least one colon (`:`) in the script name.
 Scripts from multiple workspaces can be run in parallel if they share the same name, by using `yarn workspaces foreach`. The following example shows you how to publish all packages in your project in parallel, but respecting topological order (so that a workspace only gets published once all other workspaces it depends on did):
 
 ```
-yarn workspaces foreach -pt npm publish
+yarn workspaces foreach --all -pt npm publish
 ```
 
-By default `yarn workspaces foreach` will run the commands on every workspace in the project, but it can be tweaked. In this example we use the `yarn workspaces foreach ! --since` flag to instead only select workspaces that were modified in the current branch compared to the [main branch](/):
+The `yarn workspaces foreach ! --all` flag will run the provided command on every workspace in the project, but it can be tweaked. In this example we use the `yarn workspaces foreach ! --since` flag to instead only select workspaces that were modified in the current branch compared to the [main branch](/):
 
 ```
 yarn workspaces foreach --since run lint

packages/acceptance-tests/pkg-tests-specs/sources/commands/workspaces/__snapshots__/foreach.test.js.snap

@@ -18,7 +18,7 @@
     "micromatch": "^4.0.2",
     "semver": "^7.1.2",
     "tslib": "^2.4.0",
-    "typanion": "^3.12.1"
+    "typanion": "^3.14.0"
   },
   "peerDependencies": {
     "@yarnpkg/cli": "workspace:^",