feat: add replace_packages to npm_translate_lock

MODULE.bazel

@@ -189,6 +189,9 @@ npm.npm_translate_lock(
         # other direct dependencies in the `examples/npm_deps/package.json`.
         "ms@2.1.3": ["examples/npm_deps"],
     },
+    replace_packages = {
+        "chalk@5.0.1": "@chalk_501//:pkg",
+    },
     update_pnpm_lock = True,
     verify_node_modules_ignored = "//:.bazelignore",
     verify_patches = "//examples/npm_deps/patches:patches",

WORKSPACE

@@ -160,6 +160,9 @@ npm_translate_lock(
         # other direct dependencies in the `examples/npm_deps/package.json`.
         "ms@2.1.3": ["examples/npm_deps"],
     },
+    replace_packages = {
+        "chalk@5.0.1": "@chalk_501//:pkg",
+    },
     update_pnpm_lock = True,
     verify_node_modules_ignored = "//:.bazelignore",
     verify_patches = "//examples/npm_deps/patches:patches",

WORKSPACE.bzlmod

@@ -8,3 +8,13 @@ load(
 fetch_shfmt()
 
 fetch_terraform()
+
+# dev dependency
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "chalk_501",
+    build_file = "//npm/private/test:vendored/chalk-5.0.1.BUILD",
+    integrity = "sha256-/nD5GSp77HDNFDwIL68S5PbS+8gefWkube2iIr80/x4=",
+    url = "https://registry.npmjs.org/chalk/-/chalk-5.0.1.tgz",
+)

js/dev_repositories.bzl

@@ -52,3 +52,10 @@ def rules_js_dev_dependencies():
         strip_prefix = "rules_lint-0.7.0",
         url = "https://github.com/aspect-build/rules_lint/releases/download/v0.7.0/rules_lint-v0.7.0.tar.gz",
     )
+
+    http_archive(
+        name = "chalk_501",
+        integrity = "sha256-/nD5GSp77HDNFDwIL68S5PbS+8gefWkube2iIr80/x4=",
+        url = "https://registry.npmjs.org/chalk/-/chalk-5.0.1.tgz",
+        build_file = "//npm/private/test:vendored/chalk-5.0.1.BUILD",
+    )

npm/extensions.bzl

@@ -47,6 +47,7 @@ def _extension_impl(module_ctx):
                 register_copy_directory_toolchains = False,  # this registration is handled elsewhere with bzlmod
                 register_copy_to_directory_toolchains = False,  # this registration is handled elsewhere with bzlmod
                 register_yq_toolchains = False,  # this registration is handled elsewhere with bzlmod
+                replace_packages = attr.replace_packages,
                 root_package = attr.root_package,
                 run_lifecycle_hooks = attr.run_lifecycle_hooks,
                 update_pnpm_lock = attr.update_pnpm_lock,
@@ -160,6 +161,7 @@ WARNING: Cannot determine home directory in order to load home `.npmrc` file in
                     package = i.package,
                     patch_args = i.patch_args,
                     patches = i.patches,
+                    replace_package = i.replace_package,
                     root_package = i.root_package,
                     transitive_closure = i.transitive_closure,
                     url = i.url,
@@ -191,6 +193,7 @@ WARNING: Cannot determine home directory in order to load home `.npmrc` file in
                 package = i.package,
                 patch_args = i.patch_args,
                 patches = i.patches,
+                replace_package = i.replace_package,
                 root_package = i.root_package,
                 run_lifecycle_hooks = i.run_lifecycle_hooks,
                 transitive_closure = i.transitive_closure,

npm/private/npm_import.bzl

@@ -718,7 +718,9 @@ def _impl_links(rctx):
     if npm_import_sources_repo_name.startswith("aspect_rules_js.npm."):
         npm_import_sources_repo_name = npm_import_sources_repo_name[len("aspect_rules_js.npm."):]
 
-    if rctx.attr.npm_translate_lock_repo:
+    if rctx.attr.replace_package:
+        npm_package_target = rctx.attr.replace_package
+    elif rctx.attr.npm_translate_lock_repo:
         npm_package_target = "@{}//:{}_source_directory".format(
             rctx.attr.npm_translate_lock_repo,
             npm_import_sources_repo_name,
@@ -828,6 +830,7 @@ _ATTRS_LINKS = dicts.add(_COMMON_ATTRS, {
     "npm_translate_lock_repo": attr.string(),
     "transitive_closure": attr.string_list_dict(),
     "package_visibility": attr.string_list(),
+    "replace_package": attr.string(),
 })
 
 _ATTRS = dicts.add(_COMMON_ATTRS, {
@@ -899,6 +902,7 @@ def npm_import(
         integrity = "",
         url = "",
         commit = "",
+        replace_package = None,
         package_visibility = ["//visibility:public"],
         patch_args = ["-p0"],
         patches = [],
@@ -1090,6 +1094,19 @@ def npm_import(
 
         commit: Specific commit to be checked out if url is a git repository.
 
+        replace_package: Use the specified npm_package target when linking instead of the fetched sources for this npm package.
+
+            The injected npm_package target may optionally contribute transitive npm package dependencies on top
+            of the transitive dependencies specified in the pnpm lock file for the same package, however, these
+            transitive dependencies must not collide with pnpm lock specified transitive dependencies.
+
+            Any patches specified for this package will be not applied to the injected npm_package target. They
+            will be applied, however, to the fetches sources so they can still be useful for patching the fetched
+            `package.json` file, which is used to determine the generated bin entries for the package.
+
+            NB: lifecycle hooks and custom_postinstall scripts, if implicitly or explicitly enabled, will be run on
+            the injected npm_package. These may be disabled explicitly using the `lifecycle_hooks` attribute.
+
         package_visibility: Visibility of generated node_module link targets.
 
         patch_args: Arguments to pass to the patch tool.
@@ -1218,4 +1235,5 @@ def npm_import(
         bins = bins,
         npm_translate_lock_repo = npm_translate_lock_repo,
         package_visibility = package_visibility,
+        replace_package = replace_package,
     )