Preserve special protocols (patch:, portal:, link:) when resolving catalog references

.yarn/versions/33ccb772.yml

@@ -0,0 +1,24 @@
+releases:
+  "@yarnpkg/cli": patch
+  "@yarnpkg/plugin-catalog": patch
+
+declined:
+  - "@yarnpkg/plugin-compat"
+  - "@yarnpkg/plugin-constraints"
+  - "@yarnpkg/plugin-dlx"
+  - "@yarnpkg/plugin-essentials"
+  - "@yarnpkg/plugin-init"
+  - "@yarnpkg/plugin-interactive-tools"
+  - "@yarnpkg/plugin-nm"
+  - "@yarnpkg/plugin-npm-cli"
+  - "@yarnpkg/plugin-pack"
+  - "@yarnpkg/plugin-patch"
+  - "@yarnpkg/plugin-pnp"
+  - "@yarnpkg/plugin-pnpm"
+  - "@yarnpkg/plugin-stage"
+  - "@yarnpkg/plugin-typescript"
+  - "@yarnpkg/plugin-version"
+  - "@yarnpkg/plugin-workspace-tools"
+  - "@yarnpkg/builder"
+  - "@yarnpkg/core"
+  - "@yarnpkg/doctor"

packages/acceptance-tests/pkg-tests-specs/sources/commands/patchCommit.test.ts

@@ -114,7 +114,7 @@ describe(`Commands`, () => {
         });
 
         expect(manifest.resolutions).toEqual({
-        [`no-deps@npm:1.0.0`]: expect.stringMatching(/^patch:no-deps/),
+          [`no-deps@npm:1.0.0`]: expect.stringMatching(/^patch:no-deps/),
         });
       }),
     );

packages/plugin-catalog/sources/index.ts

@@ -1,8 +1,44 @@
-import {type Descriptor, type Locator, type Plugin, type Project, type Resolver, type ResolveOptions, type Workspace, SettingsType, structUtils, Manifest, ThrowReport} from '@yarnpkg/core';
-import {Hooks as CoreHooks}                                                                                                                                             from '@yarnpkg/core';
-import {Hooks as PackHooks}                                                                                                                                             from '@yarnpkg/plugin-pack';
+import {type Descriptor, type Locator, type Plugin, type Project, type Resolver, type ResolveOptions, type Workspace, SettingsType, structUtils, Manifest, ThrowReport, Configuration} from '@yarnpkg/core';
+import {Hooks as CoreHooks}                                                                                                                                                            from '@yarnpkg/core';
+import {Hooks as PackHooks}                                                                                                                                                            from '@yarnpkg/plugin-pack';
 
-import {isCatalogReference, resolveDescriptorFromCatalog}                                                                                                               from './utils';
+import {isCatalogReference, resolveDescriptorFromCatalog}                                                                                                                              from './utils';
+
+const SAFE_PROTOCOLS_TO_ALWAYS_KEEP = new Set<string>([`patch:`, `portal:`, `link:`]);
+
+function tryRoundTripRange(range: string, configuration: Configuration): string {
+  try {
+    const parsed = structUtils.parseRange(range);
+    let {protocol, source, params, selector} = parsed;
+
+    const defaultProtocol = configuration.get(`defaultProtocol`);
+
+    // only drop protocol when it's exactly the default npm protocol and no special semantics needed
+    const canDropProtocol =
+      protocol != null &&
+      protocol === defaultProtocol &&
+      protocol === `npm:` && // be explicit
+      !SAFE_PROTOCOLS_TO_ALWAYS_KEEP.has(protocol);
+
+    if (canDropProtocol)
+      protocol = null;
+
+    // Replace the catalog reference with the resolved range
+    const normalized = structUtils.makeRange({protocol, source, params, selector});
+
+    // idempotency check: if normalization changes meaningfully, keep original
+    const reparsed = structUtils.parseRange(normalized);
+    const sameShape =
+      reparsed.protocol === (canDropProtocol ? null : parsed.protocol) &&
+      reparsed.source === parsed.source &&
+      JSON.stringify(reparsed.params) === JSON.stringify(parsed.params) &&
+      reparsed.selector === parsed.selector;
+
+    return sameShape ? normalized : range;
+  } catch {
+    return range;
+  }
+}
 
 declare module '@yarnpkg/core' {
   interface ConfigurationValueMap {
@@ -85,12 +121,11 @@ const plugin: Plugin<CoreHooks & PackHooks> = {
           // Resolve the catalog reference to get the actual version range
           const resolvedDescriptor = resolveDescriptorFromCatalog(project, descriptor, resolver, resolveOptions);
 
-          let {protocol, source, params, selector} = structUtils.parseRange(structUtils.convertToManifestRange(resolvedDescriptor.range));
-          if (protocol === workspace.project.configuration.get(`defaultProtocol`))
-            protocol = null;
+          // Convert to manifest range to strip internal params
+          const resolvedRange = structUtils.convertToManifestRange(resolvedDescriptor.range);
 
           // Replace the catalog reference with the resolved range
-          dependencies[identStr] = structUtils.makeRange({protocol, source, params, selector});
+          dependencies[identStr] = tryRoundTripRange(resolvedRange, workspace.project.configuration);
         }
       }
     },

packages/plugin-catalog/tests/utils.test.ts

@@ -437,5 +437,75 @@ describe(`utils`, () => {
       expect(result).toBe(modifiedDescriptor);
       expect(result.range).toBe(`npm:^18.0.0-modified`);
     });
+
+    it(`should preserve patch: protocol when resolving catalog reference.`, () => {
+      const catalog = new Map();
+      catalog.set(`typescript`, `patch:typescript@npm%3A^5.9.3#optional!builtin<compat/typescript>`);
+      configuration.values.set(`catalog`, catalog);
+
+      const dependency = structUtils.makeDescriptor(
+        structUtils.makeIdent(null, `typescript`),
+        `catalog:`,
+      );
+
+      // Mock the resolver to return the patch descriptor
+      const patchRange = `patch:typescript@npm%3A^5.9.3#optional!builtin<compat/typescript>`;
+      const patchDescriptor = structUtils.makeDescriptor(
+        structUtils.makeIdent(null, `typescript`),
+        patchRange,
+      );
+      mockResolver.bindDescriptor.mockReturnValue(patchDescriptor);
+
+      const result = resolveDescriptorFromCatalog(project, dependency, mockResolver, resolveOptions);
+
+      expect(result.range).toBe(patchRange);
+      expect(result.range).toMatch(/^patch:/);
+    });
+
+    it(`should preserve portal: protocol when resolving catalog reference`, () => {
+      const catalog = new Map();
+      catalog.set(`my-package`, `portal:../local-package`);
+      configuration.values.set(`catalog`, catalog);
+
+      const dependency = structUtils.makeDescriptor(
+        structUtils.makeIdent(null, `my-package`),
+        `catalog:`,
+      );
+
+      const portalRange = `portal:../local-package`;
+      const portalDescriptor = structUtils.makeDescriptor(
+        structUtils.makeIdent(null, `my-package`),
+        portalRange,
+      );
+      mockResolver.bindDescriptor.mockReturnValue(portalDescriptor);
+
+      const result = resolveDescriptorFromCatalog(project, dependency, mockResolver, resolveOptions);
+
+      expect(result.range).toBe(portalRange);
+      expect(result.range).toMatch(/^portal:/);
+    });
+
+    it(`should preserve link: protocol when resolving catalog reference`, () => {
+      const catalog = new Map();
+      catalog.set(`my-package`, `link:../linked-package`);
+      configuration.values.set(`catalog`, catalog);
+
+      const dependency = structUtils.makeDescriptor(
+        structUtils.makeIdent(null, `my-package`),
+        `catalog:`,
+      );
+
+      const linkRange = `link:../linked-package`;
+      const linkDescriptor = structUtils.makeDescriptor(
+        structUtils.makeIdent(null, `my-package`),
+        linkRange,
+      );
+      mockResolver.bindDescriptor.mockReturnValue(linkDescriptor);
+
+      const result = resolveDescriptorFromCatalog(project, dependency, mockResolver, resolveOptions);
+
+      expect(result.range).toBe(linkRange);
+      expect(result.range).toMatch(/^link:/);
+    });
   });
 });