feat(npm): Support for new option replacementApproach (#34018)

Co-authored-by: Rhys Arkins <[email protected]>

Author: zharinov

docs/usage/configuration-options.md

@@ -3849,6 +3849,16 @@ The field supports multiple URLs but it is datasource-dependent on whether only
 
 Add to this object if you wish to define rules that apply only to PRs that replace dependencies.
 
+## replacementApproach
+
+For `npm` manager when `replacementApproach=alias` then instead of replacing `"foo": "1.2.3"` with `"@my/foo": "1.2.4"` we would instead replace it with `"foo": "npm:@my/[email protected]"`.
+
+```json
+{
+  "replacementApproach": "alias"
+}
+```
+
 ## respectLatest
 
 Similar to `ignoreUnstable`, this option controls whether to update to versions that are greater than the version tagged as `latest` in the repository.

lib/config/options/index.ts

@@ -1465,6 +1465,16 @@ const options: RenovateOptions[] = [
     cli: false,
     env: false,
   },
+  {
+    name: 'replacementApproach',
+    description:
+      'Select whether to perform a direct replacement or alias replacement.',
+    type: 'string',
+    stage: 'branch',
+    allowedValues: ['replace', 'alias'],
+    supportedManagers: ['npm'],
+    default: 'replace',
+  },
   {
     name: 'matchConfidence',
     description:

lib/modules/manager/npm/update/dependency/index.spec.ts

@@ -1,5 +1,6 @@
 import * as npmUpdater from '../..';
 import { Fixtures } from '../../../../../../test/fixtures';
+import { type Upgrade } from '../../../types';
 
 const readFixture = (x: string): string => Fixtures.get(x, '../..');
 
@@ -254,6 +255,23 @@ describe('modules/manager/npm/update/dependency/index', () => {
       expect(JSON.parse(testContent!).dependencies.abc).toBe('2.0.0');
     });
 
+    it('supports alias-based replacement', () => {
+      const upgrade: Upgrade = {
+        depType: 'dependencies',
+        depName: 'config',
+        newName: 'abc',
+        replacementApproach: 'alias',
+        newValue: '2.0.0',
+      };
+      const testContent = npmUpdater.updateDependency({
+        fileContent: input01Content,
+        upgrade,
+      });
+      expect(JSON.parse(testContent!).dependencies.config).toBe(
+        'npm:[email protected]',
+      );
+    });
+
     it('replaces glob package resolutions', () => {
       const upgrade = {
         depType: 'dependencies',

lib/modules/manager/npm/update/dependency/index.ts

@@ -161,25 +161,38 @@ export function updateDependency({
     }
 
     // TODO #22198
-    let newFileContent = replaceAsString(
-      parsedContents,
-      fileContent,
-      depType as NpmDepType,
-      depName,
-      oldVersion!,
-      newValue!,
-      overrideDepParents,
-    );
-    if (upgrade.newName) {
+    let newFileContent: string;
+    if (upgrade.newName && upgrade.replacementApproach === 'alias') {
       newFileContent = replaceAsString(
         parsedContents,
-        newFileContent,
+        fileContent,
         depType as NpmDepType,
         depName,
+        oldVersion!,
+        `npm:${upgrade.newName}@${newValue}`,
+        overrideDepParents,
+      );
+    } else {
+      newFileContent = replaceAsString(
+        parsedContents,
+        fileContent,
+        depType as NpmDepType,
         depName,
-        upgrade.newName,
+        oldVersion!,
+        newValue!,
         overrideDepParents,
       );
+      if (upgrade.newName) {
+        newFileContent = replaceAsString(
+          parsedContents,
+          newFileContent,
+          depType as NpmDepType,
+          depName,
+          depName,
+          upgrade.newName,
+          overrideDepParents,
+        );
+      }
     }
     // istanbul ignore if
     if (!newFileContent) {

lib/modules/manager/types.ts

@@ -192,6 +192,7 @@ export interface Upgrade<T = Record<string, any>> extends PackageDependency<T> {
   registryUrls?: string[] | null;
   currentVersion?: string;
   replaceString?: string;
+  replacementApproach?: 'replace' | 'alias';
 }
 
 export interface ArtifactNotice {