fix(builtin): detect yarn 2+ berry and adjust CLI args

Fixes #3071
Fixes #1599

internal/npm_install/npm_install.bzl

@@ -813,25 +813,40 @@ def _yarn_install_impl(repository_ctx):
     is_windows_host = is_windows_os(repository_ctx)
     node = repository_ctx.path(get_node_label(repository_ctx))
     yarn = get_yarn_label(repository_ctx)
+    result = repository_ctx.execute(
+        [repository_ctx.path(yarn), "--version"],
+        timeout = repository_ctx.attr.timeout,
+        quiet = repository_ctx.attr.quiet,
+    )
+    if result.return_code:
+        fail("yarn --version failed: %s (%s)" % (result.stdout, result.stderr))
+    if result.stdout.startswith("1."):
+        yarn_version = "classic"
+    else:
+        yarn_version = "berry"
 
     yarn_args = []
 
     # Set frozen lockfile as default install to install the exact version from the yarn.lock
     # file. To perform an yarn install use the vendord yarn binary with:
     # `bazel run @nodejs//:yarn install` or `bazel run @nodejs//:yarn install -- -D <dep-name>`
-    if repository_ctx.attr.frozen_lockfile:
-        yarn_args.append("--frozen-lockfile")
+    if repository_ctx.attr.frozen_lockfile or repository_ctx.attr.immutable:
+        yarn_args.append("--frozen-lockfile" if yarn_version == "classic" else "--immutable")
 
     if not repository_ctx.attr.use_global_yarn_cache:
         yarn_args.extend(["--cache-folder", str(repository_ctx.path("_yarn_cache"))])
-    else:
+    elif yarn_version == "classic":
         # Multiple yarn rules cannot run simultaneously using a shared cache.
         # See https://github.com/yarnpkg/yarn/issues/683
         # The --mutex option ensures only one yarn runs at a time, see
         # https://yarnpkg.com/en/docs/cli#toc-concurrency-and-mutex
         # The shared cache is not necessarily hermetic, but we need to cache downloaded
         # artifacts somewhere, so we rely on yarn to be correct.
         yarn_args.extend(["--mutex", "network"])
+    else:
+        # Can't tell from documentation if Yarn Berry has any replacement for the --mutex
+        # flag. We'll have to assume it's safe to run concurrently.
+        pass
     yarn_args.extend(repository_ctx.attr.args)
 
     # Run the package manager in the package.json folder
@@ -936,12 +951,15 @@ yarn_install = repository_rule(
         "args": attr.string_list(
             doc = """Arguments passed to yarn install.
 
-See yarn CLI docs https://yarnpkg.com/en/docs/cli/install for complete list of supported arguments.""",
+See yarn CLI docs for complete list of supported arguments.
+Yarn 1: https://yarnpkg.com/en/docs/cli/install
+Yarn 2+: https://yarnpkg.com/cli/install
+""",
             default = [],
         ),
         "frozen_lockfile": attr.bool(
             default = True,
-            doc = """Use the `--frozen-lockfile` flag for yarn.
+            doc = """Use the `--frozen-lockfile` flag for yarn 1, or `--immutable` flag for yarn 2+ (Berry)
 
 Don't generate a `yarn.lock` lockfile and fail if an update is needed.
 
@@ -953,6 +971,10 @@ vendored yarn binary. `bazel run @nodejs//:yarn install`. You can pass the optio
 `bazel run @nodejs//:yarn install -- -D <dep-name>`.
 """,
         ),
+        "immutable": attr.bool(
+            default = True,
+            doc = "Alias for `frozen_lockfile`",
+        ),
         "use_global_yarn_cache": attr.bool(
             default = True,
             doc = """Use the global yarn cache on the system.
@@ -964,7 +986,8 @@ have bugs.
 Disabling this attribute causes every run of yarn to have a unique
 cache_directory.
 
-If True, this rule will pass `--mutex network` to yarn to ensure that
+If True, this rule will pass
+`--mutex network` to yarn 1 or to ensure that
 the global cache can be shared by parallelized yarn_install rules.
 
 If False, this rule will pass `--cache-folder /path/to/external/repository/__yarn_cache`