feat(yarn): add workspace focus support for Yarn v4

Allow users to specify workspaces in the package input so that only
the dependencies for those workspaces are prefetched via
`yarn workspaces focus`. The output is filtered to reflect only the
packages actually installed for the focused workspaces, including
their transitive workspace dependencies.

`yarn workspaces focus` does not support `--mode skip-build`, and
`enableScripts: false` does not apply to workspace scripts. To
prevent lifecycle scripts from executing during focus, the `scripts`
field is stripped from workspace `package.json` files before running
the command.

Signed-off-by: Jon Koops <jonkoops@gmail.com>

Author: jonkoops

docs/yarn.md

@@ -7,6 +7,7 @@
   - [Dealing with Yarn Zero-Installs](#dealing-with-yarn-zero-installs)
   - [Dealing with plugins](#dealing-with-plugins)
 - [Specifying packages to process](#specifying-packages-to-process)
+  - [Workspace focus](#workspace-focus)
   - [Controlling Yarn's behavior](#controlling-yarns-behavior)
   - [Downloading dependencies](#downloading-dependencies)
   - [Known pitfalls](#known-pitfalls)
@@ -115,6 +116,43 @@ or more simply by just invoking `hermeto fetch-deps yarn`.
 For complete example of how to pre-fetch dependencies, see
 [Example: Pre-fetch dependencies](#pre-fetch-dependencies).
 
+### Workspace focus
+
+For monorepo projects using [Yarn workspaces][], you can instruct Hermeto to
+fetch only the dependencies needed for specific workspaces rather than the
+entire project. This is done by specifying the `workspaces` field in the JSON
+input:
+
+```js
+{
+  "type": "yarn",
+  "path": ".",
+  // Only fetch dependencies for the "my-app" workspace
+  "workspaces": ["my-app"]
+}
+```
+
+Hermeto will fetch only the dependencies needed for the specified workspaces
+and their transitive workspace dependencies. Note that `devDependencies` are
+also included and will appear in the SBOM.
+
+You can specify multiple workspace names:
+
+```shell
+hermeto fetch-deps \
+  --source ./my-monorepo \
+  --output ./hermeto-output \
+  '{"type": "yarn", "workspaces": ["app-frontend", "lib-shared"]}'
+```
+
+> **NOTE**
+>
+> This feature requires **Yarn v4**. The workspace names must match the `name`
+> field in each workspace's `package.json`.
+
+When `workspaces` is not specified, Hermeto fetches dependencies for all
+workspaces.
+
 ### Controlling Yarn's behavior
 
 Hermeto instructs Yarn to download dependencies explicitly declared in
@@ -269,5 +307,6 @@ podman build . \
 [project]: https://github.com/hermetoproject/doc-examples/tree/yarn-basic
 [yarn install]: https://yarnpkg.com/getting-started/usage/#installing-all-the-dependencies
 [Yarn protocols]: https://yarnpkg.com/protocols
+[Yarn workspaces]: https://yarnpkg.com/features/workspaces
 [yarn]: https://yarnpkg.com
 [ZIP archives]: https://yarnpkg.com/features/pnp/#packages-are-stored-inside-zip-archives-how-can-i-access-their-files

hermeto/core/models/input.py

@@ -396,6 +396,14 @@ class YarnPackageInput(_PackageInputBase):
     """Accepted input for a yarn package."""
 
     type: Literal["yarn"]
+    workspaces: list[str] | None = None
+
+    @pydantic.field_validator("workspaces")
+    @classmethod
+    def _workspaces_not_empty(cls, workspaces: list[str] | None) -> list[str] | None:
+        if workspaces is not None and len(workspaces) == 0:
+            raise ValueError("'workspaces' must not be an empty list, omit the field instead")
+        return workspaces
 
 
 PackageInput = Annotated[

hermeto/core/package_managers/yarn/main.py

@@ -9,14 +9,20 @@
 from hermeto.core.models.input import Request
 from hermeto.core.models.output import Component, EnvironmentVariable, RequestOutput
 from hermeto.core.models.sbom import create_backend_annotation
+from hermeto.core.package_managers.yarn.locators import WorkspaceLocator
 from hermeto.core.package_managers.yarn.project import (
+    PackageJson,
     Plugin,
     Project,
     YarnRc,
     get_semver_from_package_manager,
     get_semver_from_yarn_path,
 )
-from hermeto.core.package_managers.yarn.resolver import create_components, resolve_packages
+from hermeto.core.package_managers.yarn.resolver import (
+    Package,
+    create_components,
+    resolve_packages,
+)
 from hermeto.core.package_managers.yarn.utils import (
     VersionsRange,
     extract_yarn_version_from_env,
@@ -35,7 +41,7 @@ def fetch_yarn_source(request: Request) -> RequestOutput:
         path = request.source_dir.join_within_root(package.path)
         project = Project.from_source_dir(path)
 
-        components.extend(_resolve_yarn_project(project, request.output_dir))
+        components.extend(_resolve_yarn_project(project, request.output_dir, package.workspaces))
 
     annotations = []
     if backend_annotation := create_backend_annotation(components, "yarn"):
@@ -101,21 +107,38 @@ def _verify_repository(project: Project) -> None:
     _check_lockfile(project)
 
 
-def _resolve_yarn_project(project: Project, output_dir: RootedPath) -> list[Component]:
+def _resolve_yarn_project(
+    project: Project,
+    output_dir: RootedPath,
+    workspaces: list[str] | None = None,
+) -> list[Component]:
     """Process a request for a single yarn source directory.
 
     :param project: the directory to be processed.
     :param output_dir: the directory where the prefetched dependencies will be placed.
+    :param workspaces: optional list of workspace names to focus on (Yarn v4 only).
     :raises PackageManagerError: if fetching dependencies fails
     """
     log.info(f"Fetching the yarn dependencies at the subpath {project.source_dir}")
 
     version = _configure_yarn_version(project)
+
+    if workspaces and version < semver.Version.parse("4.0.0"):
+        raise PackageRejected(
+            f"Workspace focus requires Yarn v4 or later, but this project uses Yarn {version}",
+            solution="Either upgrade to Yarn v4 or remove the 'workspaces' field from the input.",
+        )
+
     _verify_repository(project)
 
     _set_yarnrc_configuration(project, output_dir, version)
-    packages = resolve_packages(project.source_dir)
-    _fetch_dependencies(project.source_dir)
+
+    packages = resolve_packages(project.source_dir, workspaces)
+
+    if workspaces:
+        _strip_workspace_scripts(project.source_dir, packages)
+
+    _fetch_dependencies(project.source_dir, workspaces)
 
     return create_components(packages, project, output_dir)
 
@@ -241,14 +264,44 @@ def _set_yarnrc_configuration(
     yarn_rc.write()
 
 
-def _fetch_dependencies(source_dir: RootedPath) -> None:
-    """Fetch dependencies using 'yarn install'.
+def _strip_workspace_scripts(source_dir: RootedPath, packages: list[Package]) -> None:
+    """Remove scripts from workspace package.json files.
+
+    yarn workspaces focus does not support --mode skip-build, and enableScripts: false
+    does not apply to workspace scripts (https://github.com/yarnpkg/berry/pull/4781).
+    Stripping the scripts field prevents lifecycle scripts from executing during focus.
+
+    :param source_dir: the project source directory.
+    :param packages: packages returned by ``resolve_packages``, used to find workspace paths.
+    """
+    for pkg in packages:
+        locator = pkg.parsed_locator
+        if not isinstance(locator, WorkspaceLocator):
+            continue
+        pkg_json_path = source_dir.join_within_root(locator.relpath, "package.json")
+        if not pkg_json_path.path.exists():
+            continue
+        pkg_json = PackageJson.from_file(pkg_json_path)
+        if "scripts" in pkg_json:
+            del pkg_json["scripts"]
+            pkg_json.write()
+
+
+def _fetch_dependencies(source_dir: RootedPath, workspaces: list[str] | None = None) -> None:
+    """Fetch dependencies using 'yarn install' or 'yarn workspaces focus'.
+
+    When workspaces are specified, only the dependencies of those workspaces (and their
+    transitive workspace dependencies) are installed via 'yarn workspaces focus'.
 
     :param source_dir: the directory in which the yarn command will be called.
-    :raises PackageManagerError: if the 'yarn install' command fails.
+    :param workspaces: optional list of workspace names to focus on (Yarn v4 only).
+    :raises PackageManagerError: if the yarn command fails.
     """
     try:
-        run_yarn_cmd(["install", "--mode", "skip-build"], source_dir)
+        if workspaces:
+            run_yarn_cmd(["workspaces", "focus", *workspaces], source_dir)
+        else:
+            run_yarn_cmd(["install", "--mode", "skip-build"], source_dir)
     except PackageManagerError as e:
         # TODO: this follows a precedent set in resolver. Either a more robust way for
         # dealing with this must be found or a comment provided that such methods do not exist.

hermeto/core/package_managers/yarn/resolver.py

@@ -141,20 +141,46 @@ class _YarnInfoEntry(pydantic.BaseModel):
     children: _YarnInfoChildren
 
 
-def resolve_packages(source_dir: RootedPath) -> list[Package]:
+def resolve_packages(source_dir: RootedPath, workspaces: list[str] | None = None) -> list[Package]:
     """Fetch and parse package data from the 'yarn info' output.
 
+    When *workspaces* is provided, runs ``yarn workspace $name info`` for each
+    workspace and deduplicates the results. Otherwise, runs ``yarn info --all``
+    to report the full dependency graph.
+
     This function also performs validation to ensure that the current yarn project can be
     processed.
 
+    :param source_dir: the directory containing the yarn project.
+    :param workspaces: optional list of workspace names to scope the query to.
     :raises UnsupportedFeature: if an unsupported locator type is found in 'yarn info' output
     :raises PackageManagerError: if the 'yarn info' command fails.
     """
+    if workspaces:
+        packages = _resolve_workspace_packages(source_dir, workspaces)
+    else:
+        packages = _resolve_all_packages(source_dir)
+
+    n_unsupported = 0
+    for package in packages:
+        try:
+            _ = package.parsed_locator
+        except UnsupportedFeature as e:
+            log.error(e)
+            n_unsupported += 1
+
+    if n_unsupported > 0:
+        raise UnsupportedFeature(
+            f"Found {n_unsupported} unsupported dependencies, more details in the logs."
+        )
+
+    return packages
+
+
+def _get_packages_from_yarn_info(args: list[str], source_dir: RootedPath) -> list[Package]:
+    """Run a ``yarn info`` variant and return the parsed packages."""
     try:
-        # --all: report dependencies of all workspaces, not just the active workspace
-        # --recursive: report transitive dependencies, not just direct ones
-        # --cache: include info about the cache entry for each dependency
-        result = run_yarn_cmd(["info", "--all", "--recursive", "--cache", "--json"], source_dir)
+        result = run_yarn_cmd(args, source_dir)
     except PackageManagerError as e:
         if e.stderr and "isn't supported by any available resolver" in e.stderr:
             raise UnsupportedFeature(
@@ -170,22 +196,33 @@ def resolve_packages(source_dir: RootedPath) -> list[Package]:
         raise
 
     # the result is not a valid json list, but a sequence of json objects separated by line breaks
-    packages = [Package.from_info_string(info) for info in result.splitlines()]
+    return [Package.from_info_string(info) for info in result.splitlines()]
 
-    n_unsupported = 0
-    for package in packages:
-        try:
-            _ = package.parsed_locator
-        except UnsupportedFeature as e:
-            log.error(e)
-            n_unsupported += 1
 
-    if n_unsupported > 0:
-        raise UnsupportedFeature(
-            f"Found {n_unsupported} unsupported dependencies, more details in the logs."
+def _resolve_all_packages(source_dir: RootedPath) -> list[Package]:
+    # --all: report dependencies of all workspaces, not just the active workspace
+    # --recursive: report transitive dependencies, not just direct ones
+    # --cache: include info about the cache entry for each dependency
+    return _get_packages_from_yarn_info(
+        ["info", "--all", "--recursive", "--cache", "--json"], source_dir
+    )
+
+
+def _resolve_workspace_packages(source_dir: RootedPath, workspaces: list[str]) -> list[Package]:
+    seen: dict[str, Package] = {}
+
+    for ws_name in workspaces:
+        # Run info scoped to a single workspace (without --all), so yarn only reports
+        # the transitive dependencies of that workspace rather than the full project.
+        packages = _get_packages_from_yarn_info(
+            ["workspace", ws_name, "info", "--recursive", "--cache", "--json"], source_dir
         )
+        # Deduplicate across workspaces: overlapping deps appear only once
+        for pkg in packages:
+            if pkg.raw_locator not in seen:
+                seen[pkg.raw_locator] = pkg
 
-    return packages
+    return list(seen.values())
 
 
 def create_components(

tests/integration/test_data/yarn_e2e_workspace_focus/.build-config.yaml

@@ -0,0 +1,10 @@
+environment_variables:
+- name: YARN_ENABLE_GLOBAL_CACHE
+  value: 'false'
+- name: YARN_ENABLE_IMMUTABLE_CACHE
+  value: 'false'
+- name: YARN_ENABLE_MIRROR
+  value: 'true'
+- name: YARN_GLOBAL_FOLDER
+  value: ${output_dir}/deps/yarn
+project_files: []