feat: add replace_package module extension tag (aspect-build#2289)

### Changes are visible to end-users: yes

- Searched for relevant documentation and updated as needed: yes
- Breaking change (forces users to change their own code or config): yes
- Suggested release notes appear below: yes

Add `npm_replace_package(package, replacement)` bzlmod API.

### Test plan

- Updated old test case

---------

Co-authored-by: Simeon Visotskiy <[email protected]>

Author: Mivr

docs/npm_translate_lock.md

@@ -1 +1,3 @@
 node_modules
+utils_module
+lodash_module

e2e/npm_translate_lock_replace_packages/.bazelignore

@@ -15,6 +15,15 @@ js_test(
     entry_point = "main.js",
 )
 
+js_test(
+    name = "utils_test",
+    data = [
+        "@utils_replacement_module//:test_lib",
+    ],
+    entry_point = "@utils_replacement_module//:test.mjs",
+    no_copy_to_bin = ["@utils_replacement_module//:test.mjs"],
+)
+
 npm_package(
     name = "npm-pkg",
     srcs = [

e2e/npm_translate_lock_replace_packages/BUILD.bazel

@@ -14,19 +14,10 @@ local_path_override(
     path = "../..",
 )
 
-npm = use_extension(
-    "@aspect_rules_js//npm:extensions.bzl",
-    "npm",
-    dev_dependency = True,
-)
-npm.npm_translate_lock(
-    name = "npm",
-    npmrc = "//:.npmrc",
-    pnpm_lock = "//:pnpm-lock.yaml",
-    replace_packages = {
-        "[email protected]": "@chalk_501//:pkg",
-    },
-    verify_node_modules_ignored = "//:.bazelignore",
+bazel_dep(name = "lodash_replacement_module", version = "0.0.0")
+local_path_override(
+    module_name = "lodash_replacement_module",
+    path = "lodash_module",
 )
 
 http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
@@ -39,4 +30,29 @@ http_archive(
     url = "https://registry.npmjs.org/chalk/-/chalk-5.0.1.tgz",
 )
 
+bazel_dep(name = "utils_replacement_module", version = "0.0.0")
+local_path_override(
+    module_name = "utils_replacement_module",
+    path = "utils_module",
+)
+
+npm = use_extension(
+    "@aspect_rules_js//npm:extensions.bzl",
+    "npm",
+    dev_dependency = True,
+)
+npm.npm_translate_lock(
+    name = "npm",
+    npmrc = "//:.npmrc",
+    pnpm_lock = "//:pnpm-lock.yaml",
+    verify_node_modules_ignored = "//:.bazelignore",
+)
+npm.npm_replace_package(
+    package = "[email protected]",
+    replacement = "@chalk_501//:pkg",
+)
+npm.npm_replace_package(
+    package = "[email protected]",
+    replacement = "@lodash_replacement_module//:lodash_replacement",
+)
 use_repo(npm, "npm")

e2e/npm_translate_lock_replace_packages/MODULE.bazel

@@ -0,0 +1,11 @@
+load("@aspect_rules_js//npm:defs.bzl", "npm_package")
+
+# This module provides a lodash replacement package
+npm_package(
+    name = "lodash_replacement",
+    srcs = [
+        "lodash.js",
+        "package.json",
+    ],
+    visibility = ["//visibility:public"],
+)

e2e/npm_translate_lock_replace_packages/lodash_module/BUILD.bazel

@@ -0,0 +1,11 @@
+module(
+    name = "lodash_replacement_module",
+    version = "0.0.0",
+    compatibility_level = 1,
+)
+
+bazel_dep(name = "aspect_rules_js", version = "0.0.0")
+local_path_override(
+    module_name = "aspect_rules_js",
+    path = "../../..",
+)

e2e/npm_translate_lock_replace_packages/lodash_module/MODULE.bazel

@@ -0,0 +1,7 @@
+// Simple lodash replacement - version 4.17.20 equivalent
+export default {
+    uniq: function(array) {
+        return [...new Set(array)];
+    },
+    version: "4.17.20"
+};

e2e/npm_translate_lock_replace_packages/lodash_module/lodash.js

@@ -0,0 +1,6 @@
+{
+    "name": "lodash",
+    "version": "4.17.20",
+    "type": "module",
+    "main": "lodash.js"
+}

e2e/npm_translate_lock_replace_packages/lodash_module/package.json

@@ -1,21 +1,47 @@
 import chalk from 'chalk'
+import lodash from 'lodash'
 import { readFileSync } from 'fs'
 
-const packageJsonDep = JSON.parse(readFileSync('./package.json', 'utf-8'))
-    .dependencies['chalk']
-if (packageJsonDep !== '5.3.0') {
+const packageJson = JSON.parse(readFileSync('./package.json', 'utf-8'))
+
+// Test chalk replacement
+const chalkPackageJsonDep = packageJson.dependencies['chalk']
+if (chalkPackageJsonDep !== '5.3.0') {
     throw new Error(
-        `Expected chalk version 5.3.0 declared in package.json, but got ${pkgDep}`
+        `Expected chalk version 5.3.0 declared in package.json, but got ${chalkPackageJsonDep}`
     )
 }
 
-const actualDep = JSON.parse(
+const chalkActualDep = JSON.parse(
     readFileSync('./node_modules/chalk/package.json', 'utf-8')
 ).version
-if (actualDep !== '5.0.1') {
+if (chalkActualDep !== '5.0.1') {
+    throw new Error(
+        `Expected chalk to be replaced with version 5.0.1, but got ${chalkActualDep}`
+    )
+}
+
+// Test lodash replacement
+const lodashPackageJsonDep = packageJson.dependencies['lodash']
+if (lodashPackageJsonDep !== '4.17.21') {
+    throw new Error(
+        `Expected lodash version 4.17.21 declared in package.json, but got ${lodashPackageJsonDep}`
+    )
+}
+
+const lodashActualDep = JSON.parse(
+    readFileSync('./node_modules/lodash/package.json', 'utf-8')
+).version
+if (lodashActualDep !== '4.17.20') {
     throw new Error(
-        `Expected chalk to be replaced with version 5.0.1, but got ${actualDep}`
+        `Expected lodash to be replaced with version 4.17.20, but got ${lodashActualDep}`
     )
 }
 
-console.log(chalk.blue(`Hello world! The meaning of life is... 42`))
+// Test that both packages work functionally
+const testArray = [1, 2, 2, 3, 3, 3]
+const uniqueArray = lodash.uniq(testArray)
+if (uniqueArray.length !== 3) {
+    throw new Error(`Expected lodash.uniq to work, but got array length ${uniqueArray.length}`)
+}
+

e2e/npm_translate_lock_replace_packages/main.js

@@ -2,7 +2,8 @@
     "private": true,
     "type": "module",
     "dependencies": {
-        "chalk": "5.3.0"
+        "chalk": "5.3.0",
+        "lodash": "4.17.21"
     },
     "pnpm": {
         "onlyBuiltDependencies": []