refactor/javascript: Move package manager decisions to one place (#21135)

Future extensions could be exposing the `PackageManager` fields as
configurable overrides in `pants.toml` to attempt easier integration
with future versions of package managers.

Author: tobni

src/python/pants/backend/javascript/install_node_package.py

@@ -18,6 +18,7 @@
     NodePackageVersionField,
     PackageJsonSourceField,
 )
+from pants.backend.javascript.package_manager import PackageManager
 from pants.backend.javascript.subsystems import nodejs
 from pants.backend.javascript.target_types import JSSourceField
 from pants.build_graph.address import Address
@@ -52,6 +53,10 @@ def join_relative_workspace_directory(self, path: str) -> str:
     def target(self) -> Target:
         return self.project_env.ensure_target()
 
+    @property
+    def package_manager(self) -> PackageManager:
+        return self.project_env.project.package_manager
+
 
 @dataclass(frozen=True)
 class InstalledNodePackageWithSource(InstalledNodePackage):

src/python/pants/backend/javascript/nodejs_project.py

@@ -8,15 +8,14 @@
 from pathlib import PurePath
 from typing import Iterable
 
-import nodesemver
-
 from pants.backend.javascript import package_json
 from pants.backend.javascript.package_json import (
     AllPackageJson,
     PackageJson,
     PnpmWorkspaceGlobs,
     PnpmWorkspaces,
 )
+from pants.backend.javascript.package_manager import PackageManager
 from pants.backend.javascript.subsystems import nodejs
 from pants.backend.javascript.subsystems.nodejs import NodeJS, UserChosenNodeJSResolveAliases
 from pants.core.util_rules import stripped_source_files
@@ -56,80 +55,38 @@ class NodeJSProject:
     root_dir: str
     workspaces: FrozenOrderedSet[PackageJson]
     default_resolve_name: str
-    package_manager: str
-    package_manager_version: str | None = None
+    package_manager: PackageManager
     pnpm_workspace: PnpmWorkspaceGlobs | None = None
 
     @property
     def lockfile_name(self) -> str:
-        if self.package_manager == "pnpm":
-            return "pnpm-lock.yaml"
-        elif self.package_manager == "yarn":
-            return "yarn.lock"
-        return "package-lock.json"
+        return self.package_manager.lockfile_name
 
     @property
     def generate_lockfile_args(self) -> tuple[str, ...]:
-        if self.package_manager == "pnpm":
-            return ("install", "--lockfile-only")
-        elif self.package_manager == "yarn":
-            return ("install",)  # yarn does not provide a lockfile only mode.
-        return ("install", "--package-lock-only")
+        return self.package_manager.generate_lockfile_args
 
     @property
     def immutable_install_args(self) -> tuple[str, ...]:
-        if self.package_manager == "npm":
-            return ("clean-install",)
-        if self.package_manager == "pnpm":
-            return ("install", "--frozen-lockfile")
-        if self.package_manager == "yarn":
-            if nodesemver.satisfies(self.package_manager_version, "1.x"):
-                return ("install", "--frozen-lockfile")
-            return ("install", "--immutable")
-        raise ValueError(f"Unsupported package manager: {self.package_manager}")
+        return self.package_manager.immutable_install_args
 
     @property
     def workspace_specifier_arg(self) -> str:
-        if self.package_manager == "pnpm":
-            return "--filter"
-        elif self.package_manager == "yarn":
-            return "workspace"
-        return "--workspace"
+        return self.package_manager.workspace_specifier_arg
 
     @property
     def args_separator(self) -> tuple[str, ...]:
-        # pnpm 7 changed the arguments to the `run` command - all other package managers
-        # accept an args separator --, but pnpm does not in versions 7 and above.
-        # > When using pnpm run <script>, all command line arguments after the script
-        # > name are now passed to the script's argv, even --.
-        if self.package_manager == "pnpm" and (
-            self.package_manager_version is None
-            or nodesemver.satisfies(self.package_manager_version, ">=7")
-        ):
-            return ()
-
-        return ("--",)
+        return self.package_manager.run_arg_separator
 
     def extra_env(self) -> dict[str, str]:
-        if self.package_manager == "pnpm":
-            return {"PNPM_HOME": "{chroot}/._pnpm_home"}
-        elif self.package_manager == "yarn":
-            return {"YARN_CACHE_FOLDER": "{chroot}/._yarn_cache"}
-        return {}
+        return dict(self.package_manager.extra_env)
 
     @property
     def pack_archive_format(self) -> str:
-        if self.package_manager == "yarn":
-            return "{}-v{}.tgz"
-        else:
-            return "{}-{}.tgz"
+        return self.package_manager.pack_archive_format
 
     def extra_caches(self) -> dict[str, str]:
-        if self.package_manager == "pnpm":
-            return {"pnpm_home": "._pnpm_home"}
-        elif self.package_manager == "yarn":
-            return {"yarn_cache": "._yarn_cache"}
-        return {}
+        return dict(self.package_manager.extra_caches)
 
     def get_project_digest(self) -> MergeDigests:
         return MergeDigests(
@@ -182,15 +139,12 @@ def from_tentative(
                             """
                         )
                     )
-        package_manager_command, *maybe_version = package_manager.split("@")
-        package_manager_version = maybe_version[0] if maybe_version else None
 
         return NodeJSProject(
             root_dir=project.root_dir,
             workspaces=project.workspaces,
             default_resolve_name=project.default_resolve_name or "nodejs-default",
-            package_manager=package_manager_command,
-            package_manager_version=package_manager_version,
+            package_manager=PackageManager.from_string(package_manager),
             pnpm_workspace=pnpm_workspaces.for_root(project.root_dir),
         )
 
@@ -239,9 +193,11 @@ async def find_node_js_projects(
     # Note: If pnpm_workspace.yaml is present for an npm-managed project, it will override the package.json["workspaces"] setting, which is not intuitive
     # pnpm_workspace.yaml should only be used for pnpm projects - see https://github.com/pantsbuild/pants/issues/21134
     project_paths = (
-        ProjectPaths(pkg.root_dir, ["", *pkg.workspaces])
-        if pkg not in pnpm_workspaces
-        else ProjectPaths(pkg.root_dir, ["", *pnpm_workspaces[pkg].packages])
+        (
+            ProjectPaths(pkg.root_dir, ["", *pkg.workspaces])
+            if pkg not in pnpm_workspaces
+            else ProjectPaths(pkg.root_dir, ["", *pnpm_workspaces[pkg].packages])
+        )
         for pkg in package_workspaces
     )
 

src/python/pants/backend/javascript/nodejs_project_environment.py

@@ -142,8 +142,8 @@ async def setup_nodejs_project_environment_process(req: NodeJsProjectEnvironment
         Process,
         NodeJSToolProcess,
         NodeJSToolProcess(
-            tool=req.env.project.package_manager,
-            tool_version=req.env.project.package_manager_version,
+            tool=req.env.project.package_manager.name,
+            tool_version=req.env.project.package_manager.version,
             args=args,
             description=req.description,
             level=req.level,

src/python/pants/backend/javascript/nodejs_project_test.py

@@ -110,10 +110,9 @@ def test_immutable_install_args_property_with_unsupported_package_manager(
             "src/js/foo/package.json": given_package("foo", "0.0.1", package_manager="[email protected]"),
         }
     )
-    projects = rule_runner.request(AllNodeJSProjects, [])
     expected_error = "Unsupported package manager: bar"
-    with pytest.raises(ValueError, match=expected_error):
-        {project.immutable_install_args for project in projects}
+    with engine_error(ValueError, contains=expected_error):
+        rule_runner.request(AllNodeJSProjects, [])
 
 
 def test_root_package_json_is_supported(rule_runner: RuleRunner) -> None:
@@ -144,7 +143,7 @@ def test_parses_project_with_workspaces(rule_runner: RuleRunner) -> None:
     [project] = rule_runner.request(AllNodeJSProjects, [])
     assert project.root_dir == "src/js"
     assert {workspace.name for workspace in project.workspaces} == {"egg", "ham", "spam"}
-    assert project.package_manager == "npm"
+    assert project.package_manager.name == "npm"
 
 
 def test_parses_project_with_nested_workspaces(rule_runner: RuleRunner) -> None:

src/python/pants/backend/javascript/package_manager.py

@@ -0,0 +1,99 @@
+# Copyright 2024 Pants project contributors (see CONTRIBUTORS.md).
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import nodesemver
+
+from pants.util.frozendict import FrozenDict
+
+
+@dataclass(frozen=True)
+class PackageManager:
+    name: str
+    version: str | None
+    lockfile_name: str
+    generate_lockfile_args: tuple[str, ...]
+    immutable_install_args: tuple[str, ...]
+    workspace_specifier_arg: str
+    run_arg_separator: tuple[str, ...]
+    download_and_execute_args: tuple[str, ...]
+    execute_args: tuple[str, ...]
+    current_directory_args: tuple[str, ...]
+
+    extra_env: FrozenDict[str, str]
+    pack_archive_format: str
+    extra_caches: FrozenDict[str, str]
+
+    @classmethod
+    def from_string(cls, string: str) -> PackageManager:
+        package_manager_command, *maybe_version = string.split("@")
+        package_manager_version = maybe_version[0] if maybe_version else None
+        if package_manager_command == "npm":
+            return cls.npm(package_manager_version)
+        if package_manager_command == "yarn":
+            return cls.yarn(package_manager_version)
+        if package_manager_command == "pnpm":
+            return cls.pnpm(package_manager_version)
+        raise ValueError(f"Unsupported package manager: {package_manager_command}.")
+
+    @classmethod
+    def pnpm(cls, version: str | None) -> PackageManager:
+        return PackageManager(
+            name="pnpm",
+            version=version,
+            lockfile_name="pnpm-lock.yaml",
+            generate_lockfile_args=("install", "--lockfile-only"),
+            immutable_install_args=("install", "--frozen-lockfile"),
+            workspace_specifier_arg="--filter",
+            run_arg_separator=(
+                () if version is None or nodesemver.satisfies(version, ">=7") else ("--",)
+            ),
+            download_and_execute_args=("dlx",),
+            execute_args=("exec",),
+            current_directory_args=("--prefix",),
+            extra_env=FrozenDict({"PNPM_HOME": "{chroot}/._pnpm_home"}),
+            pack_archive_format="{}-{}.tgz",
+            extra_caches=FrozenDict({"pnpm_home": "._pnpm_home"}),
+        )
+
+    @classmethod
+    def yarn(cls, version: str | None) -> PackageManager:
+        return PackageManager(
+            name="yarn",
+            version=version,
+            lockfile_name="yarn.lock",
+            generate_lockfile_args=("install",),
+            immutable_install_args=(
+                ("install", "--frozen-lockfile")
+                if version is None or nodesemver.satisfies(version, "1.x")
+                else ("install", "--immutable")
+            ),
+            workspace_specifier_arg="workspace",
+            run_arg_separator=("--",),
+            download_and_execute_args=("dlx", "--quiet"),
+            execute_args=("--silent", "exec", "--"),
+            current_directory_args=("--cwd",),
+            extra_env=FrozenDict({"YARN_CACHE_FOLDER": "{chroot}/._yarn_cache"}),
+            pack_archive_format="{}-v{}.tgz",
+            extra_caches=FrozenDict({"yarn_cache": "._yarn_cache"}),
+        )
+
+    @classmethod
+    def npm(cls, version: str | None) -> PackageManager:
+        return PackageManager(
+            name="npm",
+            version=version,
+            lockfile_name="package-lock.json",
+            generate_lockfile_args=("install", "--package-lock-only"),
+            immutable_install_args=("clean-install",),
+            workspace_specifier_arg="--workspace",
+            run_arg_separator=("--",),
+            download_and_execute_args=("exec", "--yes", "--"),
+            execute_args=("exec", "--no", "--"),
+            current_directory_args=("--prefix",),
+            extra_env=FrozenDict(),
+            pack_archive_format="{}-{}.tgz",
+            extra_caches=FrozenDict(),
+        )

src/python/pants/backend/javascript/run/rules.py

@@ -46,15 +46,16 @@ async def run_node_build_script(
         EnvironmentVars, EnvironmentVarsRequest(field_set.extra_env_vars.value or ())
     )
 
-    prefix_arg = "--prefix"
-    if installation.project_env.project.package_manager == "yarn":
-        prefix_arg = "--cwd"
-
     process = await Get(
         Process,
         NodeJsProjectEnvironmentProcess(
             installation.project_env,
-            args=(prefix_arg, "{chroot}", "run", str(field_set.entry_point.value)),
+            args=(
+                *installation.package_manager.current_directory_args,
+                "{chroot}",
+                "run",
+                str(field_set.entry_point.value),
+            ),
             description=f"Running {str(field_set.entry_point.value)}.",
             input_digest=installation.digest,
             extra_env=target_env_vars,

src/python/pants/backend/javascript/subsystems/nodejs_tool.py

@@ -12,6 +12,7 @@
     InstalledNodePackageRequest,
 )
 from pants.backend.javascript.nodejs_project_environment import NodeJsProjectEnvironmentProcess
+from pants.backend.javascript.package_manager import PackageManager
 from pants.backend.javascript.resolve import FirstPartyNodePackageResolves, NodeJSProjectResolves
 from pants.backend.javascript.subsystems.nodejs import NodeJS, NodeJSToolProcess
 from pants.engine.internals.native_engine import Digest, MergeDigests
@@ -97,14 +98,10 @@ class NodeJSToolRequest:
 
 async def _run_tool_without_resolve(request: NodeJSToolRequest) -> Process:
     nodejs = await Get(NodeJS)
-    dl_and_execute_args = {
-        "npm": ("exec", "--yes", "--"),
-        "pnpm": ("dlx",),
-        "yarn": ("dlx", "--quiet"),
-    }
 
     pkg_manager_version = nodejs.package_managers.get(nodejs.package_manager)
-    if pkg_manager_version is None:
+    pkg_manager_and_version = nodejs.default_package_manager
+    if pkg_manager_version is None or pkg_manager_and_version is None:
         # Occurs when a user configures a custom package manager but without a resolve.
         # Corepack requires a package.json to make a decision on a "good known release".
         raise ValueError(
@@ -116,19 +113,21 @@ async def _run_tool_without_resolve(request: NodeJSToolRequest) -> Process:
                 """
             )
         )
+    pkg_manager = PackageManager.from_string(pkg_manager_and_version)
+
     return await Get(
         Process,
         NodeJSToolProcess(
-            nodejs.package_manager,
-            pkg_manager_version,
-            args=(*dl_and_execute_args[nodejs.package_manager], request.tool, *request.args),
+            pkg_manager.name,
+            pkg_manager.version,
+            args=(*pkg_manager.download_and_execute_args, request.tool, *request.args),
             description=request.description,
             input_digest=request.input_digest,
             output_files=request.output_files,
             output_directories=request.output_directories,
             append_only_caches=request.append_only_caches,
             timeout_seconds=request.timeout_seconds,
-            extra_env=FrozenDict({"PNPM_HOME": "{chroot}/._pnpm_home", **request.extra_env}),
+            extra_env=FrozenDict({**pkg_manager.extra_env, **request.extra_env}),
         ),
     )
 
@@ -150,18 +149,13 @@ async def _run_tool_with_resolve(request: NodeJSToolRequest, resolve: str) -> Pr
     installed = await Get(
         InstalledNodePackage, InstalledNodePackageRequest(package_for_resolve.address)
     )
-    execute_args = {
-        "npm": ("exec", "--no", "--"),
-        "pnpm": ("exec",),
-        "yarn": ("--silent", "exec", "--"),
-    }
     request_tool_without_version = request.tool.partition("@")[0]
     return await Get(
         Process,
         NodeJsProjectEnvironmentProcess(
             env=installed.project_env,
             args=(
-                *execute_args[project.package_manager],
+                *project.package_manager.execute_args,
                 request_tool_without_version,
                 *request.args,
             ),